@withpica/mcp-sdk 3.23.0 → 3.24.0

package/CHANGELOG.md

@@ -11,6 +11,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.24.0] - 2026-10-09
+
+### Added
+
+- `works.getThemes`, `works.setThemes`, `works.proposeThemes`, `works.reviewThemes` and
+  `directory.untaggedThemes` for a song's directory topics.
+
+### Changed — needs a MINOR bump at release
+
+- ⚠️ **`PaginatedResult.total` is now `number | null`** (type change). An
+  explicit `pagination.total: null` from the server means "unknown" — a
+  platform-wide registry the route will not count, or a filter applied
+  after the read — and is passed through as `null` instead of being turned
+  into the page length. Code that does arithmetic on `total` must handle
+  `null`.
+- `requestPaginated`'s fallback `has_more` (when the server sends none) is
+  now `offset + page < total`; it ignored the offset, so every last page of
+  a multi-page result reported more (row-cap T3).
+
+### Added
+
+- **`syncFit` resource**: `query({ work_id?, screen_project_id?,
+song_facts?, limit?, offset? })` (GET `/admin/sync-fit`), with the
+  `SyncFitPage`, `SyncFitRow`, `SyncFitProduction`, `SyncFitSongFacts` and
+  `SyncFitMeasured` types.
+- `works.getThemes`, `works.setThemes`, `works.proposeThemes`, `works.reviewThemes` and
+  `directory.untaggedThemes` for a song's directory topics.
+- Page methods that return `{ data, total, hasMore }` — the real total —
+  alongside the existing `list()` calls, whose return types are unchanged:
+  `agreements.listPage`, `bookings.listPage`, `licensing.listEnquiriesPage`,
+  `partyClaims.listPage`, `releases.listPage`, `sessions.listPage`,
+  `collaborators.listInvitesPage` / `listIncomingPage`,
+  `publishers.listPage` and `labels.listPage` (total `null`: platform-wide
+  rows are not counted; `labels.listPage` also takes `ids` for a lookup by
+  id). `custody.list` takes `offset`.
+- `works.getAgreements(workId)` — the agreements linked to one work.
+- `enrichment.previewBulkRejectProposals(input)` — what a bulk reject
+  would reject, resolved by the same server-side resolver, writing nothing.
+
+## [3.23.1] - 2026-10-07
+
+### Fixed
+
+- `imports.getTemplate()` and `catalogStats()` go through the shared request
+  path. Both were bare `fetch()` calls without the
+  `x-vercel-protection-bypass` header, so on a protected Vercel preview they
+  never reached PICA: `getTemplate` returned Vercel's login page as the CSV
+  (or failed when that hop answered 500). They also skipped the timeout,
+  retry and typed errors.
+- `requestText()` refuses a `text/html` body instead of returning it as the
+  file.
+
 ## [3.23.0] - 2026-10-04
 
 ### Added

package/dist/index.d.ts

@@ -264,7 +264,12 @@ interface PicaClientConfig {
 }
 interface PaginatedResult<T> {
     data: T[];
-    total: number;
+    /**
+     * The real total, or null when the server says it is unknown (a
+     * platform-wide registry it will not count, or a filter applied after
+     * the read). Never the page length dressed up as a total (row-cap T3).
+     */
+    total: number | null;
     hasMore: boolean;
     /**
      * Server-provided next-step guidance when a search legitimately returns
@@ -943,13 +948,20 @@ declare class BaseResource {
      * for routes that stream a generated file (e.g. `text/csv`) rather than
      * `{success, data}`. `request()` unconditionally calls `response.json()`,
      * which throws a SyntaxError parsing CSV text; every such route needs this
-     * method instead (see `ImportResource.getTemplate()` for the prior
-     * precedent this generalises).
+     * method instead (`ImportResource.getTemplate()`, `ExportResource.catalogCsv()`).
      *
      * `fetchWithRetry` already throws `ApiError` for non-2xx responses (reading
      * the body as text), so reaching here means `response.ok`. Still guard
      * against a 2xx JSON error envelope (`{success:false}`) via content-type,
      * since a route can commit to status 200 before a later validation step.
+     *
+     * An HTML page is refused. Neither route that uses this
+     * (`/admin/import/template`, `/admin/works/export` CSV formats) answers
+     * `text/html`, so one means something in front of PICA answered (on a
+     * protected Vercel preview, a missing bypass header ends on Vercel's
+     * login page with status 200). Returning that page as the file read as a
+     * success (2026-10-06, pica_import_template). Locked by
+     * `mcp-server/src/__tests__/sdk-request-text-and-bare-fetch.test.ts`.
      */
     protected requestText(method: string, path: string): Promise<string>;
     /**
@@ -1025,6 +1037,12 @@ declare class WorksResource extends BaseResource {
          */
         has_lyrics?: boolean;
     }): Promise<PaginatedResult<Work>>;
+    /**
+     * The agreements linked to ONE work (GET /admin/works/:id/agreements).
+     * Inspect used `agreements.list()`, which returned the org's first page of
+     * agreements under a work's heading (row-cap T3).
+     */
+    getAgreements(workId: string): Promise<any[]>;
     get(id: string): Promise<Work>;
     create(data: Partial<Work> & {
         create_twin?: boolean;
@@ -1170,6 +1188,49 @@ declare class WorksResource extends BaseResource {
             person_id?: string;
         }>;
     }>;
+    /** A song's directory topics: approved, proposed, moods awaiting review, settings. */
+    getThemes(workId: string): Promise<WorkThemeState>;
+    /** Set the song's approved topics directly, and/or its switch and lyric visibility. */
+    setThemes(workId: string, body: {
+        themes?: string[];
+        themes_enabled?: boolean;
+        lyrics_visibility?: "themes" | "snippet" | "full";
+    }): Promise<WorkThemeState>;
+    /** Propose topics (and recording moods) for the owner to review. Nothing goes public. */
+    proposeThemes(workId: string, body: {
+        themes?: string[];
+        moods?: Array<{
+            recording_id: string;
+            moods: string[];
+        }>;
+    }): Promise<WorkThemeState>;
+    /** The owner's review of proposed topics and moods. */
+    reviewThemes(workId: string, body: {
+        approve?: string[] | "all";
+        reject?: string[];
+        approve_moods_for?: string[] | "all";
+        reject_moods_for?: string[] | "all";
+    }): Promise<WorkThemeState>;
+}
+/** GET /api/admin/works/[id]/themes (lib/services/directory/themes.ts ThemeState). */
+export interface WorkThemeState {
+    work_id: string;
+    title: string;
+    has_lyrics: boolean;
+    themes_enabled: boolean;
+    lyrics_visibility: "themes" | "snippet" | "full";
+    approved: Array<{
+        theme: string;
+        source: "owner" | "assistant";
+    }>;
+    proposed: Array<{
+        theme: string;
+        source: "owner" | "assistant";
+    }>;
+    proposed_moods: Array<{
+        recording_id: string;
+        moods: string[];
+    }>;
 }
 declare class PeopleResource extends BaseResource {
     list(params?: {
@@ -1249,6 +1310,14 @@ declare class PeopleResource extends BaseResource {
         musicbrainz_id?: string;
     }): Promise<Record<string, unknown>>;
 }
+export interface LicenseEnquiryListParams {
+    work_id?: string;
+    status?: string;
+    project_type?: string;
+    territory?: string;
+    limit?: number;
+    offset?: number;
+}
 declare class LicensingResource extends BaseResource {
     /**
      * Search for sync-licensable tracks by audio characteristics
@@ -1259,16 +1328,16 @@ declare class LicensingResource extends BaseResource {
      */
     submitEnquiry(enquiry: LicenseEnquiryInput): Promise<LicenseEnquiry>;
     /**
-     * List license enquiries with optional filters
+     * List license enquiries with optional filters (one page, the bare array;
+     * see listEnquiriesPage for the real total).
      */
-    listEnquiries(params?: {
-        work_id?: string;
-        status?: string;
-        project_type?: string;
-        territory?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<LicenseEnquiry[]>;
+    listEnquiries(params?: LicenseEnquiryListParams): Promise<LicenseEnquiry[]>;
+    /**
+     * One page of license enquiries WITH the real total and has_more
+     * (row-cap T3): `listEnquiries()` returns the bare array, so callers
+     * reported the page length as the total.
+     */
+    listEnquiriesPage(params?: LicenseEnquiryListParams): Promise<PaginatedResult<LicenseEnquiry>>;
     /**
      * Get a specific license enquiry by ID
      */
@@ -1290,20 +1359,27 @@ declare class LicensingResource extends BaseResource {
  * bookings, distinct from `LicensingResource`'s sync-license enquiries).
  * Wraps `/admin/bookings` + `/admin/bookings/[id]`.
  */
+export interface BookingListParams {
+    status?: string;
+    priority?: string;
+    query?: string;
+    enquiry_type?: string;
+    follow_up_required?: boolean;
+    limit?: number;
+    offset?: number;
+}
 declare class BookingsResource extends BaseResource {
     /**
-     * List/search booking enquiries. `GET /admin/bookings` returns the raw
-     * array (not `{data, count}`) — `request()` unwraps to that array.
+     * One page of booking enquiries (the bare array; see listPage for the real
+     * total). `request()` unwraps the route's `{ data, count }` envelope.
      */
-    list(params?: {
-        status?: string;
-        priority?: string;
-        query?: string;
-        enquiry_type?: string;
-        follow_up_required?: boolean;
-        limit?: number;
-        offset?: number;
-    }): Promise<BookingEnquiry[]>;
+    list(params?: BookingListParams): Promise<BookingEnquiry[]>;
+    /**
+     * One page of booking enquiries WITH the real total and has_more
+     * (row-cap T3): `list()` returns the bare array, so callers reported the
+     * page length as the total.
+     */
+    listPage(params?: BookingListParams): Promise<PaginatedResult<BookingEnquiry>>;
     get(id: string): Promise<BookingEnquiry>;
     /**
      * `PATCH /admin/bookings/[id]` only processes ONE update mode per call
@@ -1820,36 +1896,44 @@ declare class MultimediaResource extends BaseResource {
     }): Promise<MultimediaItem>;
     linkWork(id: string, workId: string, relationshipType: string, notes?: string): Promise<Record<string, unknown>>;
 }
+export interface AgreementListParams {
+    query?: string;
+    agreement_type?: string;
+    status?: string;
+    party_name?: string;
+    includeWorkCounts?: boolean;
+    /**
+     * ADR-289 Wave B1 item 4 — filter to agreements in `pending_signature`
+     * or `partially_signed` (ports the bespoke assistant's
+     * `list_pending_signatures`). Maps to `?awaiting_signature=true` on the
+     * route, which already had multi-status filtering (`statuses[]`) under
+     * the hood.
+     */
+    awaiting_signature?: boolean;
+    /** Agreements with start_date on/after this ISO date (YYYY-MM-DD). */
+    start_date_from?: string;
+    /** Agreements with start_date on/before this ISO date. */
+    start_date_to?: string;
+    /** Agreements with end_date on/after this ISO date. */
+    end_date_from?: string;
+    /** Agreements with end_date on/before this ISO date. */
+    end_date_to?: string;
+    /** Active agreements whose end_date falls within N days from today. */
+    expiring_within_days?: number;
+    /** true → only agreements that have an end_date; false → only open-ended. */
+    has_end_date?: boolean;
+    limit?: number;
+    offset?: number;
+}
 declare class AgreementsResource extends BaseResource {
-    list(params?: {
-        query?: string;
-        agreement_type?: string;
-        status?: string;
-        party_name?: string;
-        includeWorkCounts?: boolean;
-        /**
-         * ADR-289 Wave B1 item 4 — filter to agreements in `pending_signature`
-         * or `partially_signed` (ports the bespoke assistant's
-         * `list_pending_signatures`). Maps to `?awaiting_signature=true` on the
-         * route, which already had multi-status filtering (`statuses[]`) under
-         * the hood.
-         */
-        awaiting_signature?: boolean;
-        /** Agreements with start_date on/after this ISO date (YYYY-MM-DD). */
-        start_date_from?: string;
-        /** Agreements with start_date on/before this ISO date. */
-        start_date_to?: string;
-        /** Agreements with end_date on/after this ISO date. */
-        end_date_from?: string;
-        /** Agreements with end_date on/before this ISO date. */
-        end_date_to?: string;
-        /** Active agreements whose end_date falls within N days from today. */
-        expiring_within_days?: number;
-        /** true → only agreements that have an end_date; false → only open-ended. */
-        has_end_date?: boolean;
-        limit?: number;
-        offset?: number;
-    }): Promise<Agreement[]>;
+    /** One page of agreements (the bare array; see listPage for the real total). */
+    list(params?: AgreementListParams): Promise<Agreement[]>;
+    /**
+     * One page of agreements WITH the real total and has_more (row-cap T3):
+     * `list()` returns the bare array, so callers reported the page length
+     * as the total.
+     */
+    listPage(params?: AgreementListParams): Promise<PaginatedResult<Agreement>>;
     get(id: string): Promise<{
         agreement: Agreement;
         signatureStatus: unknown;
@@ -1914,6 +1998,59 @@ declare class AgreementsResource extends BaseResource {
         expires_in_days?: number;
     }): Promise<AgreementSendForSignatureResult>;
 }
+/** One production behind a sync-fit match (TMDB and Wikidata facts). */
+export interface SyncFitProduction {
+    tmdb_id: number | null;
+    release_date: string | null;
+    genres: string[];
+    themes: string[];
+    countries: string[];
+    language: string | null;
+    companies: string[];
+    networks: string[];
+}
+/** One analysed master's measured facts (the MCPs' shared `measured` names). */
+export interface SyncFitMeasured {
+    audio_file_id: string;
+    tempo_bpm: number | null;
+    key: string | null;
+    mode: "major" | "minor" | null;
+    duration_seconds: number | null;
+}
+export interface SyncFitSongFacts {
+    genres: string[];
+    language: string | null;
+    measured: SyncFitMeasured[];
+}
+export interface SyncFitRow {
+    work_id: string;
+    screen_project_id: string;
+    work_title: string | null;
+    production_title: string | null;
+    production_type: string | null;
+    production_status: string | null;
+    band: "strong" | "possible";
+    reasons: string[];
+    production: SyncFitProduction;
+    song?: SyncFitSongFacts;
+}
+export interface SyncFitPage {
+    rows: SyncFitRow[];
+    total: number;
+    songs: number;
+    offset: number;
+    limit: number;
+}
+/** Sync fit: GET /admin/sync-fit, the same read as /inspect/sync. */
+declare class SyncFitResource extends BaseResource {
+    query(params?: {
+        work_id?: string;
+        screen_project_id?: string;
+        song_facts?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<SyncFitPage>;
+}
 declare class SyncPlacementsResource extends BaseResource {
     list(params?: SyncPlacementQueryParams): Promise<PaginatedResult<SyncPlacement>>;
     get(id: string): Promise<SyncPlacementWithRelations>;
@@ -2332,6 +2469,26 @@ declare class EnrichmentResource extends BaseResource {
         rejected: number;
         skipped: string[];
     }>;
+    /**
+     * What bulkRejectProposals would reject, without rejecting: the route
+     * resolves the same pending set the real call would (row-cap T3).
+     */
+    previewBulkRejectProposals(input: {
+        proposal_ids?: string[];
+        filter?: {
+            rule_id?: string;
+            source?: string;
+            max_confidence?: number;
+        };
+    }): Promise<{
+        dry_run: true;
+        would_affect: string[];
+        /** null when exceeds_cap: the count past the cap is not read. */
+        count: number | null;
+        skipped: string[];
+        exceeds_cap: boolean;
+        cap: number;
+    }>;
     /**
      * Apply many pending proposals in one call — the accept side of the
      * /inspect/found queue.
@@ -4024,6 +4181,22 @@ declare class CollaboratorsResource extends BaseResource {
         workId?: string;
         limit?: number;
     }): Promise<CollaboratorInvite[]>;
+    /**
+     * One page of the invites this org sent WITH the real total and has_more
+     * (row-cap T3). `listInvites()` is typed as an array but the route nests
+     * its rows as `data: { data, count }`, so it never carried a usable total.
+     */
+    listInvitesPage(params?: {
+        status?: "pending" | "verified" | "confirmed" | "expired" | "cancelled" | "disputed";
+        workId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<CollaboratorInvite>>;
+    /**
+     * Reads a collaborator list route, whose rows sit at `data.data` (kept
+     * for published SDKs) with the total in the top-level `pagination`.
+     */
+    private requestNestedPage;
     resendInvite(inviteId: string): Promise<Record<string, unknown>>;
     /**
      * ADR-157 warm path — list invites addressed to the authenticated
@@ -4039,6 +4212,20 @@ declare class CollaboratorsResource extends BaseResource {
         credit_type: string;
         percentage_split: number | null;
     }>>;
+    /**
+     * One page of the invites addressed to the caller WITH the real total and
+     * has_more (row-cap T3: `listIncoming()` returns only the rows).
+     */
+    listIncomingPage(params?: {
+        status?: "pending" | "verified" | "confirmed" | "expired" | "cancelled" | "disputed";
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<CollaboratorInvite & {
+        work_title: string | null;
+        inviter_org_name: string | null;
+        credit_type: string;
+        percentage_split: number | null;
+    }>>;
     /**
      * ADR-157 warm path — accept an invite addressed to the authenticated
      * user, and flip its status to confirmed. The credit write is
@@ -4272,6 +4459,15 @@ declare class DirectoryResource extends BaseResource {
         eligible_work_count: number;
     }>;
     updateSettings(updates: Partial<DirectorySettings>): Promise<DirectorySettings>;
+    /** Listed songs with lyrics and topics on, but no approved topic yet. */
+    untaggedThemes(): Promise<{
+        count: number;
+        songs: Array<{
+            work_id: string;
+            title: string;
+            pending_proposals: number;
+        }>;
+    }>;
 }
 declare class ProjectsResource extends BaseResource {
     list(params?: {
@@ -4594,6 +4790,15 @@ declare class RecordingSplitsResource extends BaseResource {
     verify(recordingId: string, splitId: string): Promise<any>;
 }
 declare class PublishersResource extends BaseResource {
+    /**
+     * One page of the publisher registry with an honest has_more. The total
+     * is null: the route does not count the platform-wide registry.
+     */
+    listPage(params?: {
+        query?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<any>>;
     list(params?: {
         query?: string;
         limit?: number;
@@ -4622,6 +4827,18 @@ export interface LabelIdentifiers {
     deezer_label_id?: string;
 }
 declare class LabelsResource extends BaseResource {
+    /**
+     * One page of label/distributor organisations with an honest has_more.
+     * The total is null: the route does not count platform-wide rows.
+     */
+    listPage(params?: {
+        query?: string;
+        limit?: number;
+        offset?: number;
+        org_type?: "label" | "distributor";
+        /** Only these organisation ids — a lookup by id. */
+        ids?: string[];
+    }): Promise<PaginatedResult<LabelOrganisation>>;
     list(params?: {
         query?: string;
         limit?: number;
@@ -4677,6 +4894,12 @@ export interface PartyClaimInviteResult {
  * Typed against the UNWRAPPED reality (ADR-265 lesson): BaseResource.request
  * auto-unwraps the `{success,data}` envelope, so methods see `data` itself.
  */
+export interface PartyClaimListParams {
+    target_organisation_id?: string;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
 declare class PartyClaimsResource extends BaseResource {
     invite(params: {
         target_organisation_id: string;
@@ -4684,11 +4907,13 @@ declare class PartyClaimsResource extends BaseResource {
         release_id?: string;
         recording_id?: string;
     }): Promise<PartyClaimInviteResult | null>;
-    list(params?: {
-        target_organisation_id?: string;
-        status?: string;
-        limit?: number;
-    }): Promise<PartyClaimInviteSummary[]>;
+    list(params?: PartyClaimListParams): Promise<PartyClaimInviteSummary[]>;
+    /**
+     * One page of sent claim invites WITH the real total and has_more
+     * (row-cap T3): `list()` returns the bare array, so callers reported the
+     * page length as the total.
+     */
+    listPage(params?: PartyClaimListParams): Promise<PaginatedResult<PartyClaimInviteSummary>>;
 }
 /** One person's outcome from POST /admin/people/claim-invites. */
 export interface ProfileClaimInviteOutcome {
@@ -4747,16 +4972,25 @@ declare class ProfileClaimsResource extends BaseResource {
         limit?: number;
     }): Promise<ProfileClaimStatusResult>;
 }
+export interface ReleaseListParams {
+    limit?: number;
+    offset?: number;
+    query?: string;
+    upc?: string;
+    spotify_album_id?: string;
+    release_date_from?: string;
+    release_date_to?: string;
+}
 declare class ReleasesResource extends BaseResource {
-    list(params?: {
-        limit?: number;
-        offset?: number;
-        query?: string;
-        upc?: string;
-        spotify_album_id?: string;
-        release_date_from?: string;
-        release_date_to?: string;
-    }): Promise<any>;
+    /** One page of releases (the bare array; see listPage for the real total). */
+    list(params?: ReleaseListParams): Promise<any>;
+    /**
+     * One page of releases WITH the real total and has_more (row-cap T3):
+     * `list()` returns the bare array, so callers guessed has_more from "the
+     * page came back full". `total` is null when the server cannot count (a
+     * title search past its match cap); has_more is the server's own answer.
+     */
+    listPage(params?: ReleaseListParams): Promise<PaginatedResult<any>>;
     get(id: string): Promise<any>;
     /**
      * ADR-208 Phase 3 Primitive D — fetch a server-resized ≤512px JPEG
@@ -4890,10 +5124,20 @@ declare class ReleasesResource extends BaseResource {
     }): Promise<any>;
 }
 declare class SessionsResource extends BaseResource {
+    /** One page of upcoming sessions (see listPage for the real total). */
     list(params?: {
         limit?: number;
         offset?: number;
     }): Promise<any>;
+    /**
+     * One page of the next 7 days' sessions WITH the real total and has_more
+     * (row-cap T3): `list()` returns the bare array, so callers could only
+     * guess has_more from "the page came back full".
+     */
+    listPage(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<any>>;
     get(id: string): Promise<any>;
     create(data: Record<string, any>): Promise<any>;
     update(id: string, data: Record<string, any>): Promise<any>;
@@ -5202,10 +5446,16 @@ declare class CustodyResource extends BaseResource {
         action: "accept" | "decline" | "dispute";
         reason?: string;
     }): Promise<any>;
+    /**
+     * Custody claims, one page per direction. Since row-cap T3 the result also
+     * carries `totals: { incoming, outgoing }` (null for a direction not asked
+     * for), `has_more: { incoming, outgoing }`, `limit` and `offset`.
+     */
     list(params?: {
         direction?: "incoming" | "outgoing" | "both";
         status?: string;
         limit?: number;
+        offset?: number;
     }): Promise<any>;
     history(params: {
         work_id: string;
@@ -5452,6 +5702,7 @@ export declare class PicaClient {
     multimedia: MultimediaResource;
     agreements: AgreementsResource;
     syncPlacements: SyncPlacementsResource;
+    syncFit: SyncFitResource;
     workspace: WorkspaceResource;
     memory: MemoryResource;
     audit: AuditResource;