feat: respect per-user library and label restrictions when reporting availability (Plex, Jellyfin, Emby)

server/api/externalapi.ts

@@ -101,6 +101,31 @@ class ExternalAPI {
     return response.data;
   }
 
+  protected async put<T>(
+    endpoint: string,
+    data?: Record<string, unknown>,
+    config?: AxiosRequestConfig,
+    ttl?: number
+  ): Promise<T> {
+    const cacheKey = this.serializeCacheKey(endpoint, {
+      config: config?.params,
+      ...(data ? { data } : {}),
+    });
+
+    const cachedItem = this.cache?.get<T>(cacheKey);
+    if (cachedItem) {
+      return cachedItem;
+    }
+
+    const response = await this.axios.put<T>(endpoint, data, config);
+
+    if (this.cache && ttl !== 0) {
+      this.cache.set(cacheKey, response.data, ttl ?? DEFAULT_TTL);
+    }
+
+    return response.data;
+  }
+
   protected async getRolling<T>(
     endpoint: string,
     config?: AxiosRequestConfig,

server/api/jellyfin.ts

@@ -18,6 +18,30 @@ export interface JellyfinUserResponse {
   };
   Policy: {
     IsAdministrator: boolean;
+    /**
+     * Library access, as configured per user under Access. When
+     * `EnableAllFolders` is set the user reaches every library and
+     * `EnabledFolders` is empty; otherwise it lists the library item ids the
+     * user is allowed to browse.
+     */
+    EnableAllFolders?: boolean;
+    EnabledFolders?: string[];
+    /** Legacy Emby counterpart of `EnabledFolders`. */
+    BlockedMediaFolders?: string[];
+    /**
+     * Tag based restrictions, the counterpart of Plex labels. The two servers
+     * disagree on how they are expressed, which was established against real
+     * servers rather than taken from the documentation:
+     *
+     * - Jellyfin uses two independent lists, `AllowedTags` and `BlockedTags`,
+     *   and applies both, a denied tag winning over an allowed one.
+     * - Emby keeps a single list in `BlockedTags` whose polarity is flipped by
+     *   `IsTagBlockingModeInclusive`: false denies those tags, true allows only
+     *   those tags. Its `IncludeTags` field has no effect.
+     */
+    AllowedTags?: string[];
+    BlockedTags?: string[];
+    IsTagBlockingModeInclusive?: boolean;
   };
   PrimaryImageTag?: string;
 }
@@ -70,13 +94,21 @@ interface JellyfinMediaFolder {
   Id: string;
   Type: string;
   CollectionType: string;
+  /**
+   * Emby only. Its user policy references libraries by this value while `Id`
+   * stays numeric, so both have to be kept to match a policy entry. Jellyfin
+   * does not return it, its `Id` already being the guid.
+   */
+  Guid?: string;
 }
 
 export interface JellyfinLibrary {
   type: 'show' | 'movie';
   key: string;
   title: string;
   agent: string;
+  /** Emby's alternative identifier for the same library, see `JellyfinMediaFolder`. */
+  guid?: string;
 }
 
 export interface JellyfinLibraryItem {
@@ -93,6 +125,10 @@ export interface JellyfinLibraryItem {
   IndexNumberEnd?: number;
   ParentIndexNumber?: number;
   MediaType: string;
+  /** Only populated when requested through `fields`. Jellyfin answers with
+   * `Tags`, Emby with `TagItems`, so callers have to read both. */
+  Tags?: string[];
+  TagItems?: { Name: string }[];
 }
 
 export interface JellyfinMediaStream {
@@ -442,14 +478,20 @@ class JellyfinAPI extends ExternalAPI {
           title: Item.Name,
           type: Item.CollectionType === 'movies' ? 'movie' : 'show',
           agent: 'jellyfin',
+          guid: Item.Guid,
         };
       });
   }
 
-  public async getLibraryContents(id: string): Promise<JellyfinLibraryItem[]> {
+  public async getLibraryContents(
+    id: string,
+    { fields }: { fields?: string } = {}
+  ): Promise<JellyfinLibraryItem[]> {
     try {
       const libraryItemsResponse = await this.get<any>(
-        `/Items?SortBy=SortName&SortOrder=Ascending&IncludeItemTypes=Series,Movie,Others&Recursive=true&StartIndex=0&ParentId=${id}&collapseBoxSetItems=false`
+        `/Items?SortBy=SortName&SortOrder=Ascending&IncludeItemTypes=Series,Movie,Others&Recursive=true&StartIndex=0&ParentId=${id}&collapseBoxSetItems=false${
+          fields ? `&Fields=${fields}` : ''
+        }`
       );
 
       return libraryItemsResponse.Items.filter(

server/api/plexapi.ts

@@ -93,6 +93,17 @@ interface PlexMetadataResponse {
   };
 }
 
+interface PlexLabelResponse {
+  MediaContainer: {
+    Metadata?: {
+      librarySectionID?: number | string;
+      Label?: {
+        tag: string;
+      }[];
+    }[];
+  };
+}
+
 class PlexAPI extends ExternalAPI {
   constructor({
     plexToken,
@@ -199,6 +210,101 @@ class PlexAPI extends ExternalAPI {
     };
   }
 
+  /**
+   * Returns the rating keys of every item in a library section carrying the
+   * given label.
+   *
+   * Plex never returns labels in bulk library listings, whatever the requested
+   * fields, but it does support filtering by label. Resolving one request per
+   * label is therefore far cheaper than fetching metadata item by item.
+   */
+  public async getRatingKeysByLabel(
+    sectionId: string,
+    label: string
+  ): Promise<string[]> {
+    const ratingKeys: string[] = [];
+    const size = 500;
+    let offset = 0;
+    let totalSize = 0;
+
+    do {
+      const response = await this.get<PlexLibraryResponse>(
+        `/library/sections/${sectionId}/all?label=${encodeURIComponent(label)}`,
+        {
+          headers: {
+            'X-Plex-Container-Start': `${offset}`,
+            'X-Plex-Container-Size': `${size}`,
+          },
+        }
+      );
+
+      totalSize = response.MediaContainer.totalSize ?? 0;
+      ratingKeys.push(
+        ...(response.MediaContainer.Metadata ?? []).map(
+          (item) => item.ratingKey
+        )
+      );
+      offset += size;
+    } while (offset < totalSize);
+
+    return ratingKeys;
+  }
+
+  /**
+   * Adds a label to a library item.
+   *
+   * Plex merges the labels sent with the ones already set, so the existing set
+   * is never read back and replayed: two concurrent grants on the same item
+   * cannot drop each other's label.
+   */
+  public async addLabel(
+    ratingKey: string,
+    type: 'movie' | 'show',
+    label: string
+  ): Promise<void> {
+    const { sectionId, labels: existing } = await this.getItemLabels(ratingKey);
+
+    if (!sectionId) {
+      throw new Error(
+        `Unable to resolve the library section of Plex item ${ratingKey}`
+      );
+    }
+
+    if (existing.some((l) => l.toLowerCase() === label.toLowerCase())) {
+      return;
+    }
+
+    const params = new URLSearchParams({
+      type: type === 'show' ? '2' : '1',
+      id: ratingKey,
+      'label[0].tag.tag': label,
+      'label.locked': '1',
+    });
+
+    await this.put(`/library/sections/${sectionId}/all?${params.toString()}`);
+  }
+
+  /**
+   * Returns the labels currently set on a library item, along with the section
+   * it belongs to, which is required to write labels back.
+   */
+  public async getItemLabels(
+    ratingKey: string
+  ): Promise<{ sectionId?: string; labels: string[] }> {
+    const response = await this.get<PlexLabelResponse>(
+      `/library/metadata/${ratingKey}`
+    );
+
+    const metadata = response.MediaContainer.Metadata?.[0];
+
+    return {
+      sectionId: metadata?.librarySectionID
+        ? `${metadata.librarySectionID}`
+        : undefined,
+      labels: (metadata?.Label ?? []).map((label) => label.tag),
+    };
+  }
+
   public async getMetadata(
     key: string,
     options: { includeChildren?: boolean } = {}

server/api/plextv.test.ts

@@ -0,0 +1,133 @@
+import {
+  isAllowedByLabelFilter,
+  parsePlexLabelFilter,
+} from '@server/api/plextv';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+describe('parsePlexLabelFilter', () => {
+  it('returns empty lists when no restriction is set', () => {
+    for (const value of [undefined, null, '']) {
+      assert.deepEqual(parsePlexLabelFilter(value), { allow: [], deny: [] });
+    }
+  });
+
+  it('parses a single allowed label', () => {
+    assert.deepEqual(parsePlexLabelFilter('label=Family'), {
+      allow: ['Family'],
+      deny: [],
+    });
+  });
+
+  it('parses several comma separated labels', () => {
+    assert.deepEqual(parsePlexLabelFilter('label=Family,Kids'), {
+      allow: ['Family', 'Kids'],
+      deny: [],
+    });
+  });
+
+  it('decodes url encoded values, as returned by plex.tv', () => {
+    assert.deepEqual(parsePlexLabelFilter('label=Family%2CKids'), {
+      allow: ['Family', 'Kids'],
+      deny: [],
+    });
+  });
+
+  it('parses negated restrictions into the deny list', () => {
+    assert.deepEqual(parsePlexLabelFilter('label!=Private'), {
+      allow: [],
+      deny: ['Private'],
+    });
+  });
+
+  it('handles allow and deny clauses in the same filter', () => {
+    assert.deepEqual(parsePlexLabelFilter('label=Family&label!=Private'), {
+      allow: ['Family'],
+      deny: ['Private'],
+    });
+  });
+
+  it('ignores clauses that are not label based', () => {
+    assert.deepEqual(parsePlexLabelFilter('contentRating=PG&label=Family'), {
+      allow: ['Family'],
+      deny: [],
+    });
+  });
+
+  it('keeps encoded separators inside a label value', () => {
+    // %26 is `&`, which must not be mistaken for a clause separator.
+    assert.deepEqual(parsePlexLabelFilter('label=Tom%20%26%20Jerry'), {
+      allow: ['Tom & Jerry'],
+      deny: [],
+    });
+  });
+
+  it('does not throw on a malformed encoding', () => {
+    assert.deepEqual(parsePlexLabelFilter('label=100%'), {
+      allow: ['100%'],
+      deny: [],
+    });
+  });
+
+  it('drops empty values and surrounding whitespace', () => {
+    assert.deepEqual(parsePlexLabelFilter('label= Family , ,Kids '), {
+      allow: ['Family', 'Kids'],
+      deny: [],
+    });
+  });
+});
+
+describe('isAllowedByLabelFilter', () => {
+  it('hides everything when the restrictions cannot be satisfied', () => {
+    assert.equal(
+      isAllowedByLabelFilter({ allow: [], deny: [], allowNothing: true }, [
+        'Family',
+      ]),
+      false
+    );
+  });
+
+  it('allows anything when no restriction applies', () => {
+    assert.equal(isAllowedByLabelFilter({ allow: [], deny: [] }, []), true);
+    assert.equal(
+      isAllowedByLabelFilter({ allow: [], deny: [] }, ['Family']),
+      true
+    );
+  });
+
+  it('requires one of the allowed labels', () => {
+    const filter = { allow: ['Family', 'Kids'], deny: [] };
+
+    assert.equal(isAllowedByLabelFilter(filter, ['Family']), true);
+    assert.equal(isAllowedByLabelFilter(filter, ['Other', 'Kids']), true);
+    assert.equal(isAllowedByLabelFilter(filter, ['Other']), false);
+  });
+
+  it('hides unlabelled media when an allow list is set', () => {
+    assert.equal(
+      isAllowedByLabelFilter({ allow: ['Family'], deny: [] }, []),
+      false
+    );
+  });
+
+  it('denies media carrying a denied label, even when also allowed', () => {
+    assert.equal(
+      isAllowedByLabelFilter({ allow: ['Family'], deny: ['Private'] }, [
+        'Family',
+        'Private',
+      ]),
+      false
+    );
+  });
+
+  it('compares labels case insensitively', () => {
+    assert.equal(
+      isAllowedByLabelFilter({ allow: ['family'], deny: [] }, ['Family']),
+      true
+    );
+    assert.equal(
+      isAllowedByLabelFilter({ allow: [], deny: ['private'] }, ['PRIVATE']),
+      false
+    );
+  });
+});