@withpica/mcp-sdk 3.23.1 → 3.25.0

package/dist/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * Lightweight PICA SDK client for MCP server
- * Uses the PICA API directly without external dependencies
- */
 /**
  * ADR-179 resolver result shape. Mirrors the server-side
  * `ResolveWorkResult` in `lib/services/enrichment-cascade/resolver.ts`.
@@ -264,7 +260,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
@@ -865,6 +866,68 @@ export declare class ApiError extends Error {
     retryAfterMs?: number | undefined;
     constructor(message: string, status: number, retryable: boolean, retryAfterMs?: number | undefined);
 }
+/**
+ * ADR-333 D7 — acting for a client catalogue, one call at a time.
+ *
+ * An organisation's assistant names the client catalogue on each tool call
+ * (the optional `catalogue` argument). The MCP server runs that call inside
+ * `withCatalogue(id, …)`, and every request the call makes carries
+ * `x-pica-catalogue: <id>`. The app resolves it through the relationship on
+ * every request (PR 1.3) and answers with `x-pica-catalogue-resolved: <id>`.
+ *
+ * A per-call context, not a field on the client: the stdio server shares one
+ * client across concurrent tool calls, so a field would leak one call's
+ * catalogue into another's requests.
+ *
+ * Fails closed: a 2xx answer without a matching echo means the route did not
+ * act for that catalogue (it may have used the caller's own), so the call
+ * throws `CatalogueNotHonouredError` instead of reporting success. This is the
+ * client's check only; stopping such a route from writing at all is the app's
+ * job (PR 1.3 refuses a catalogue header it did not resolve).
+ */
+export declare const CATALOGUE_HEADER = "x-pica-catalogue";
+export declare const CATALOGUE_RESOLVED_HEADER = "x-pica-catalogue-resolved";
+/**
+ * What the app did with one call's requests in a client catalogue: how many it
+ * answered for that catalogue, and which it refused because the route does
+ * not open through a relationship, or because the relationship does not
+ * allow it (code RELATIONSHIP_REFUSED: proxy.ts, the request-context
+ * builders, requireCatalogueContext).
+ * The MCP server reads it after the tool returns: a tool that fails its parts
+ * soft would otherwise answer "success" with every part refused.
+ */
+export interface CatalogueCallReport {
+    catalogueId: string;
+    answered: number;
+    refused: Array<{
+        path: string;
+        reason: string | null;
+    }>;
+}
+/** Run `fn` with every SDK request in it acting for `catalogueId`. */
+export declare function withCatalogue<T>(catalogueId: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * `withCatalogue`, also returning the call's report. The report is the one
+ * the call's requests wrote to; it is complete once `fn` settles.
+ */
+export declare function runInCatalogue<T>(catalogueId: string, fn: () => Promise<T>): Promise<{
+    value: T;
+    report: CatalogueCallReport;
+}>;
+/** The catalogue the current call acts for, if any. */
+export declare function currentCatalogue(): string | undefined;
+/**
+ * Run `fn` in the current client catalogue (its requests still name it), but
+ * leave its requests off the current call's report: for a check PICA makes
+ * for itself (the billing gate reading the client's plan), which must not
+ * read as the tool's own work having been answered (the MCP server judges a
+ * call "every part refused" by that report).
+ */
+export declare function asideFromReport<T>(fn: () => Promise<T>): Promise<T>;
+export declare class CatalogueNotHonouredError extends ApiError {
+    catalogueId: string;
+    constructor(catalogueId: string, path: string);
+}
 /**
  * Uniform delete outcome (mirrors the server's deletion contract). `deleted` =
  * gone; `archived` = hidden but kept (registry data / dependents preserved);
@@ -1032,6 +1095,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;
@@ -1177,6 +1246,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?: {
@@ -1256,6 +1368,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
@@ -1266,16 +1386,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
      */
@@ -1297,20 +1417,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
@@ -1827,36 +1954,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;
@@ -1921,6 +2056,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>;
@@ -2339,6 +2527,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.
@@ -3504,6 +3712,14 @@ declare class DuplicatesResource extends BaseResource {
      */
     findDuplicates(entityType: "works" | "people" | "releases" | "recordings" | "audio_files"): Promise<any>;
     merge(entityType: "work" | "person" | "recording" | "release", winnerId: string, loserIds: string[]): Promise<any>;
+    /**
+     * "They're different": mark every pair among `ids` (2–25 recordings or
+     * releases of this catalogue) as not duplicates, so findDuplicates stops
+     * offering them. Idempotent. Resolves {entity_type, ids, pairs, changed}.
+     */
+    markDifferent(entityType: "recordings" | "releases", ids: string[]): Promise<any>;
+    /** Take back markDifferent for every pair among `ids`. */
+    unmarkDifferent(entityType: "recordings" | "releases", ids: string[]): Promise<any>;
 }
 declare class EntityContextResource extends BaseResource {
     getWorkFull(workId: string): Promise<Record<string, unknown>>;
@@ -4031,6 +4247,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
@@ -4046,6 +4278,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
@@ -4279,6 +4525,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?: {
@@ -4601,6 +4856,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;
@@ -4629,6 +4893,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;
@@ -4684,6 +4960,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;
@@ -4691,11 +4973,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 {
@@ -4754,16 +5038,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
@@ -4897,10 +5190,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>;
@@ -4970,6 +5273,318 @@ declare class RightsResource extends BaseResource {
     /** GET /admin/rights-statements/measures — the four measures (ADR-321 §7a). */
     measures(): Promise<any>;
 }
+/** A relationship's scope, as the routes return it (camelCase). */
+export interface RelationshipScopeRecord {
+    half: "both" | "composition" | "master";
+    territories: string[];
+    termStartsOn: string | null;
+    termEndsOn: string | null;
+    money: boolean;
+    directory: boolean;
+    catalogue: "whole" | "chosen";
+    workIds: string[];
+    recordingIds: string[];
+}
+/**
+ * One relationship (`org_grants` row) as GET /admin/relationships returns it.
+ * `version` is passed back as `expected_version` on every step, so a step
+ * never lands on terms that changed since they were read.
+ */
+export interface RelationshipRecord {
+    id: string;
+    grantorOrgId: string;
+    grantorOrgName: string;
+    granteeOrgId: string;
+    granteeOrgName: string;
+    type: "co_owner" | "administrator" | "representative" | "viewer";
+    status: "proposed" | "active" | "declined" | "revoked" | "stepped_down" | "expired" | "suspended";
+    proposedBySide: "grantor" | "grantee";
+    scope: RelationshipScopeRecord;
+    proposedAt: string;
+    respondedAt: string | null;
+    endedAt: string | null;
+    endReason: string | null;
+    proposalExpiresAt: string | null;
+    suspendedAt: string | null;
+    version: number;
+    [key: string]: unknown;
+}
+/** An invitation waiting for the person (no address in it). */
+export interface ClaimableInviteRecord {
+    invite_id: string;
+    direction: "grantee_invites_owner" | "owner_invites_grantee";
+    inviting_org_id: string;
+    inviting_org_name: string;
+    type: RelationshipRecord["type"];
+    scope: RelationshipScopeRecord;
+    expires_at: string;
+    eligible_organisations: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface RelationshipListPage {
+    rows: RelationshipRecord[];
+    nextCursor: string | null;
+    waiting_for_you: ClaimableInviteRecord[];
+    /** Set when the waiting invitations could not be read: never "none waiting". */
+    waiting_for_you_unavailable?: "email_not_verified" | "check_failed";
+}
+/** One audit row (`org_grant_events`). */
+export interface RelationshipEventRecord {
+    id: string;
+    relationshipId: string;
+    kind: string;
+    at: string;
+    actorSide: "grantor" | "grantee" | "system" | "platform";
+    actorDisplayName: string | null;
+    grantorOrgId: string;
+    grantorOrgName: string;
+    granteeOrgId: string;
+    granteeOrgName: string;
+    type: RelationshipRecord["type"];
+    typeBefore: RelationshipRecord["type"] | null;
+    statusBefore: RelationshipRecord["status"] | null;
+    statusAfter: RelationshipRecord["status"];
+    version: number;
+    /** The scope before this event (null for `proposed`). */
+    scopeBefore: RelationshipScopeRecord | null;
+    /** The scope after this event (for an ending: the scope that ended). */
+    scope: RelationshipScopeRecord;
+    reason: string | null;
+    action: string | null;
+    entityType: string | null;
+    entityId: string | null;
+    detail: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface RelationshipPageOf<T> {
+    rows: T[];
+    nextCursor: string | null;
+}
+/** The result of accepting, declining, editing, revoking or stepping down. */
+export interface RelationshipStepRecord {
+    relationship: RelationshipRecord;
+    event: RelationshipEventRecord | null;
+}
+/** The result of accepting an invitation: the claim and the accept, both recorded. */
+export interface RelationshipInviteAcceptRecord {
+    relationship: RelationshipRecord;
+    events: RelationshipEventRecord[];
+}
+/** A hand-over just created (ADR-333 D5): nothing is sent yet. */
+export interface HandoverCreatedRecord {
+    handover_id: string;
+    catalogue_org_id: string;
+}
+/** A hand-over as its builder sees it (POST /admin/handovers/{id}/send). */
+export interface HandoverRecord {
+    handover_id: string;
+    catalogue_org_id: string;
+    catalogue_name: string | null;
+    builder_org_id: string;
+    builder_name: string | null;
+    client_name: string;
+    client_email?: string;
+    status: string;
+    relationship_type: string;
+    sent_at: string | null;
+    expires_at: string | null;
+    version: number;
+}
+/**
+ * Catalogues an organisation builds for a client, who accepts to own them
+ * (ADR-333 D5). Builder side only: the client answers on screen, signed in.
+ */
+declare class HandoversResource extends BaseResource {
+    /**
+     * POST /admin/handovers — create a catalogue for a client
+     * (catalogue_name), or a new hand-over on one this organisation built whose
+     * last one closed (catalogue_org_id). Nothing is sent.
+     */
+    create(body: {
+        catalogue_name?: string;
+        catalogue_org_id?: string;
+        client_name: string;
+        client_email: string;
+        relationship_type: string;
+    }): Promise<HandoverCreatedRecord>;
+    /** POST /admin/handovers/{id}/send { expected_version? } — email the client. */
+    send(id: string, body: {
+        expected_version?: number;
+    }): Promise<HandoverRecord>;
+}
+/**
+ * /admin/relationships/** — both sides of a relationship. Refusals arrive as
+ * `{ success: false, error: { code, message, details? } }` (read them with
+ * the MCP package's parseApiErrorBody); a step whose terms changed since they
+ * were read is a 409 `status_changed` carrying `details.relationship`.
+ */
+declare class RelationshipsResource extends BaseResource {
+    /** GET /admin/relationships?side=owner|organisation&status=&cursor=&limit= */
+    list(params: {
+        side: "owner" | "organisation";
+        statuses?: string[];
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipListPage>;
+    /** GET /admin/relationships/{id} */
+    get(id: string): Promise<RelationshipRecord>;
+    /**
+     * POST /admin/relationships { as, email, type, scope? } — invite someone by
+     * email. as="owner" asks someone at an organisation to look after this
+     * catalogue; as="organisation" asks a client to let this organisation look
+     * after theirs. The reply is the same whether or not the address is on PICA.
+     */
+    invite(body: {
+        as: "owner" | "organisation";
+        email: string;
+        type: string;
+        scope?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** PATCH /admin/relationships/{id} { action: accept | decline | edit, expected_version, … } */
+    answer(id: string, body: {
+        action: "accept" | "decline" | "edit";
+        expected_version: number;
+        type?: string;
+        scope?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** DELETE /admin/relationships/{id} { expected_version, reason? } — the owner ends it. */
+    revoke(id: string, body: {
+        expected_version: number;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** POST /admin/relationships/{id}/step-down { expected_version, reason? } — the organisation ends its side. */
+    stepDown(id: string, body: {
+        expected_version: number;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** GET /admin/relationships/{id}/activity — one relationship's history, either party. */
+    events(id: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipPageOf<RelationshipEventRecord>>;
+    /**
+     * GET /admin/relationships/activity?side=&org= — side=owner: what
+     * organisations did in this catalogue (org = one organisation);
+     * side=organisation: this organisation's own actions (org = one catalogue).
+     */
+    activity(params: {
+        side: "owner" | "organisation";
+        org?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipPageOf<RelationshipEventRecord>>;
+    /**
+     * PATCH /admin/relationships/invites/{id} { action: "accept", organisation_id, type?, scope? }
+     * — answer yes to an invitation for one of the person's organisations.
+     */
+    acceptInvite(inviteId: string, body: {
+        organisation_id: string;
+        type?: string;
+        scope?: Record<string, unknown>;
+    }): Promise<RelationshipInviteAcceptRecord>;
+}
+/** A portfolio section: checked, out of scope, unavailable, or failed (never 0). */
+export type PortfolioSection<T> = {
+    state: "ok";
+    data: T;
+} | {
+    state: "not_in_scope" | "unavailable" | "failed";
+    reason: string;
+};
+/** One client catalogue an organisation looks after (portfolio PR 1.4). */
+export interface PortfolioClientRecord {
+    relationshipId: string;
+    catalogue: {
+        orgId: string;
+        name: string;
+    };
+    relationship: {
+        type: RelationshipRecord["type"];
+        typeLabel: string;
+        status: "active" | "suspended";
+        access: "open" | "paused" | "not_started";
+        acceptedAt: string | null;
+        termEndsOn: string | null;
+        endingSoon: boolean;
+        version: number;
+        /** What a change by this caller does in that catalogue. */
+        changes: "direct" | "proposal" | "none";
+        scope: {
+            half: RelationshipScopeRecord["half"];
+            territories: string[];
+            termStartsOn: string | null;
+            termEndsOn: string | null;
+            money: boolean;
+            directory: boolean;
+            catalogue: "whole" | "chosen";
+            songsChosen: number;
+            recordingsChosen: number;
+        };
+    };
+    /** null = the scope doesn't cover that half ("not covered", never 0). */
+    missing: PortfolioSection<{
+        songs: number | null;
+        songsWithGaps: number | null;
+        recordings: number | null;
+        recordingsWithGaps: number | null;
+    }>;
+    moneyBlockers: PortfolioSection<{
+        songs: number;
+        blocked: number;
+        clear: number;
+        unknown: number;
+        byCode: Array<{
+            code: string;
+            label: string;
+            songs: number;
+        }>;
+    }>;
+    enquiries: PortfolioSection<{
+        waiting: number;
+        oldestAt: string | null;
+    }>;
+    deadlines: PortfolioSection<{
+        total: number;
+        items: Array<{
+            kind: string;
+            on: string;
+            label: string;
+        }>;
+    }>;
+    /** Briefing only: at most five, in scope only. */
+    highlights?: Array<{
+        kind: string;
+        label: string;
+        workId?: string;
+        recordingId?: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface PortfolioPage {
+    rows: PortfolioClientRecord[];
+    nextCursor: string | null;
+    asOf: string;
+}
+/**
+ * /admin/portfolio — the client catalogues an organisation looks after. A
+ * page may hold fewer rows than `limit` and still not be the last: follow
+ * `nextCursor` until it is null.
+ */
+declare class PortfolioResource extends BaseResource {
+    /** GET /admin/portfolio?cursor=&limit= (limit ≤ 25) */
+    list(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PortfolioPage>;
+    /** GET /admin/portfolio/briefing?cursor=&limit= — the list plus what needs attention. */
+    briefing(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PortfolioPage>;
+}
 declare class RoyaltiesResource extends BaseResource {
     payments(params?: {
         source?: string;
@@ -5209,10 +5824,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;
@@ -5459,6 +6080,7 @@ export declare class PicaClient {
     multimedia: MultimediaResource;
     agreements: AgreementsResource;
     syncPlacements: SyncPlacementsResource;
+    syncFit: SyncFitResource;
     workspace: WorkspaceResource;
     memory: MemoryResource;
     audit: AuditResource;
@@ -5504,6 +6126,11 @@ export declare class PicaClient {
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;
     royalties: RoyaltiesResource;
+    /** ADR-333 — who looks after whose catalogue, from either side. */
+    relationships: RelationshipsResource;
+    handovers: HandoversResource;
+    /** ADR-333 — the client catalogues an organisation looks after. */
+    portfolio: PortfolioResource;
     /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
     rights: RightsResource;
     statements: StatementsResource;