@withpica/mcp-sdk 3.23.1 → 3.25.0

package/dist/index.js

@@ -1,5 +1,10 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Lightweight PICA SDK client for MCP server
+ * Uses the PICA API directly without external dependencies
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
 // --- Request infrastructure ---
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LONG_TIMEOUT_MS = 120_000;
@@ -32,6 +37,98 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
+/**
+ * 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 const CATALOGUE_HEADER = "x-pica-catalogue";
+export const CATALOGUE_RESOLVED_HEADER = "x-pica-catalogue-resolved";
+const catalogueContext = new AsyncLocalStorage();
+/** Run `fn` with every SDK request in it acting for `catalogueId`. */
+export function withCatalogue(catalogueId, fn) {
+    return catalogueId
+        ? runInCatalogue(catalogueId, fn).then((r) => r.value)
+        : fn();
+}
+/**
+ * `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 async function runInCatalogue(catalogueId, fn) {
+    const report = {
+        catalogueId,
+        answered: 0,
+        refused: [],
+    };
+    const value = await catalogueContext.run(report, fn);
+    return { value, report };
+}
+/** The catalogue the current call acts for, if any. */
+export function currentCatalogue() {
+    return catalogueContext.getStore()?.catalogueId;
+}
+/**
+ * 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 function asideFromReport(fn) {
+    const current = catalogueContext.getStore();
+    if (!current)
+        return fn();
+    return catalogueContext.run({ catalogueId: current.catalogueId, answered: 0, refused: [] }, fn);
+}
+/**
+ * Record a relationship refusal on the current call's report (no-op outside
+ * one). Every client-catalogue refusal, from the proxy or a route, answers
+ * `{ success: false, error: { code, message, details: { reason_code } } }`
+ * (catalogueRefusalBody, lib/auth/relationship-refused-error.ts; pinned by
+ * lib/auth/__tests__/catalogue-refusal-shape.test.ts).
+ */
+function recordCatalogueRefusal(url, body) {
+    const report = catalogueContext.getStore();
+    if (!report)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return;
+    }
+    if (parsed?.error?.code !== "RELATIONSHIP_REFUSED")
+        return;
+    const reason = parsed.error.details?.reason_code;
+    report.refused.push({
+        path: new URL(url).pathname,
+        reason: typeof reason === "string" ? reason : null,
+    });
+}
+export class CatalogueNotHonouredError extends ApiError {
+    catalogueId;
+    constructor(catalogueId, path) {
+        super(`This action can't be done for a client's catalogue yet, so nothing was done for catalogue ${catalogueId} (${path}).`, 0, false);
+        this.catalogueId = catalogueId;
+        this.name = "CatalogueNotHonouredError";
+    }
+}
 /**
  * Thrown when the API responds 404 — the entity at the given id either
  * doesn't exist or doesn't belong to the caller's org. Distinguished from
@@ -54,6 +151,14 @@ function getTimeoutForPath(path) {
         ? LONG_TIMEOUT_MS
         : DEFAULT_TIMEOUT_MS;
 }
+/** The `offset` query parameter of a request path (0 when absent). */
+function offsetOf(path) {
+    const q = path.indexOf("?");
+    if (q === -1)
+        return 0;
+    const n = Number(new URLSearchParams(path.slice(q + 1)).get("offset"));
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -98,9 +203,30 @@ class BaseResource {
         const timingOn = typeof process !== "undefined" && process.env?.PICA_SDK_TIMING === "1";
         const t0 = timingOn ? Date.now() : 0;
         let statusForTiming = 0;
+        const catalogueId = currentCatalogue();
+        const headers = catalogueId
+            ? {
+                ...init.headers,
+                [CATALOGUE_HEADER]: catalogueId,
+            }
+            : init.headers;
         try {
-            const res = await fetch(url, { ...init, signal: controller.signal });
+            const res = await fetch(url, {
+                ...init,
+                headers,
+                signal: controller.signal,
+            });
             statusForTiming = res.status;
+            if (catalogueId &&
+                res.ok &&
+                res.headers.get(CATALOGUE_RESOLVED_HEADER) !== catalogueId) {
+                throw new CatalogueNotHonouredError(catalogueId, new URL(url).pathname);
+            }
+            if (catalogueId && res.ok) {
+                const report = catalogueContext.getStore();
+                if (report)
+                    report.answered += 1;
+            }
             return res;
         }
         catch (err) {
@@ -134,6 +260,7 @@ class BaseResource {
                 if (response.ok)
                     return response;
                 const errorText = await response.text();
+                recordCatalogueRefusal(url, errorText);
                 // Auth errors — fail fast, never retry
                 if (response.status === 401 || response.status === 403) {
                     throw new ApiError(`Authentication failed: ${response.status} ${errorText}`, response.status, false);
@@ -312,8 +439,18 @@ class BaseResource {
         // `total`/`hasMore` (e.g. GET /admin/recordings/search, ADR unified
         // catalog search). Check nested first, then flat, then fall back to
         // `count` / items.length so untouched callers keep their prior behaviour.
-        const total = json.pagination?.total ?? json.total ?? json.count ?? items.length;
-        const hasMore = json.pagination?.hasMore ?? json.hasMore ?? total > items.length;
+        // An explicit `pagination.total: null` means the server does not know
+        // the total — keep it null rather than falling through to the page
+        // length, which would read as "that's all of them".
+        const total = json.pagination && json.pagination.total === null
+            ? null
+            : (json.pagination?.total ?? json.total ?? json.count ?? items.length);
+        // With no server-side hasMore, the answer is offset + this page < total.
+        // `total > items.length` alone ignored the offset, so every LAST page of
+        // a multi-page result said "more" (row-cap T3).
+        const hasMore = json.pagination?.hasMore ??
+            json.hasMore ??
+            (total !== null && offsetOf(path) + items.length < total);
         // Carry the server's zero-result guidance through — silently dropping it
         // here left agents staring at a bare empty list (ops_issue 689a8e9a).
         const recovery_hint = typeof json.recovery_hint === "string" ? json.recovery_hint : undefined;
@@ -406,6 +543,15 @@ class WorksResource extends BaseResource {
         const qs = qp.toString();
         return this.requestPaginated("GET", `/admin/works${qs ? `?${qs}` : ""}`);
     }
+    /**
+     * 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).
+     */
+    async getAgreements(workId) {
+        const res = await this.request("GET", `/admin/works/${workId}/agreements`);
+        return Array.isArray(res) ? res : [];
+    }
     async get(id) {
         return this.request("GET", `/admin/works/${id}`);
     }
@@ -517,6 +663,22 @@ class WorksResource extends BaseResource {
     async addWriters(workId, names) {
         return this.request("POST", `/admin/works/${workId}/writers`, { names });
     }
+    /** A song's directory topics: approved, proposed, moods awaiting review, settings. */
+    async getThemes(workId) {
+        return this.request("GET", `/admin/works/${encodeURIComponent(workId)}/themes`);
+    }
+    /** Set the song's approved topics directly, and/or its switch and lyric visibility. */
+    async setThemes(workId, body) {
+        return this.request("PUT", `/admin/works/${encodeURIComponent(workId)}/themes`, body);
+    }
+    /** Propose topics (and recording moods) for the owner to review. Nothing goes public. */
+    async proposeThemes(workId, body) {
+        return this.request("POST", `/admin/works/${encodeURIComponent(workId)}/themes/proposals`, body);
+    }
+    /** The owner's review of proposed topics and moods. */
+    async reviewThemes(workId, body) {
+        return this.request("PATCH", `/admin/works/${encodeURIComponent(workId)}/themes/proposals`, body);
+    }
 }
 class PeopleResource extends BaseResource {
     async list(params) {
@@ -628,6 +790,23 @@ class PeopleResource extends BaseResource {
         return this.request("GET", `/admin/people/triangulate?${qp.toString()}`);
     }
 }
+function licenseEnquiryListPath(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.work_id)
+        queryParams.set("work_id", params.work_id);
+    if (params?.status)
+        queryParams.set("status", params.status);
+    if (params?.project_type)
+        queryParams.set("project_type", params.project_type);
+    if (params?.territory)
+        queryParams.set("territory", params.territory);
+    if (params?.limit !== undefined)
+        queryParams.set("limit", String(params.limit));
+    if (params?.offset !== undefined)
+        queryParams.set("offset", String(params.offset));
+    const query = queryParams.toString();
+    return `/admin/license-enquiries${query ? `?${query}` : ""}`;
+}
 class LicensingResource extends BaseResource {
     /**
      * Search for sync-licensable tracks by audio characteristics
@@ -673,33 +852,26 @@ class LicensingResource extends BaseResource {
         return this.request("POST", "/admin/license-enquiries", enquiry);
     }
     /**
-     * List license enquiries with optional filters
+     * List license enquiries with optional filters (one page, the bare array;
+     * see listEnquiriesPage for the real total).
      */
     async listEnquiries(params) {
-        const queryParams = new URLSearchParams();
-        if (params?.work_id)
-            queryParams.set("work_id", params.work_id);
-        if (params?.status)
-            queryParams.set("status", params.status);
-        if (params?.project_type)
-            queryParams.set("project_type", params.project_type);
-        if (params?.territory)
-            queryParams.set("territory", params.territory);
-        if (params?.limit !== undefined)
-            queryParams.set("limit", String(params.limit));
-        if (params?.offset !== undefined)
-            queryParams.set("offset", String(params.offset));
-        const query = queryParams.toString();
-        const path = `/admin/license-enquiries${query ? `?${query}` : ""}`;
-        // The admin route returns successResponse({ data: [...], count }); after
-        // request() unwraps the outer { success, data } envelope the payload is the
-        // { data, count } object, not the array. Tolerate both shapes (mirrors
-        // listDiscoveriesRecent + the other list resources) so the caller never
-        // calls `.map` on a non-array — the "t.map is not a function" crash that
-        // made pica_list_license_enquiries fail on every call shape.
-        const res = (await this.request("GET", path));
+        // Older servers nested the list as `{ data: { data: [...], count } }`, so
+        // after request() unwraps the outer envelope the payload was an object,
+        // not the array. Tolerate both shapes so the caller never calls `.map` on
+        // a non-array — the "t.map is not a function" crash that made
+        // pica_list_license_enquiries fail on every call shape.
+        const res = (await this.request("GET", licenseEnquiryListPath(params)));
         return Array.isArray(res) ? res : (res?.data ?? []);
     }
+    /**
+     * 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.
+     */
+    async listEnquiriesPage(params) {
+        return this.requestPaginated("GET", licenseEnquiryListPath(params));
+    }
     /**
      * Get a specific license enquiry by ID
      */
@@ -722,34 +894,40 @@ class LicensingResource extends BaseResource {
         return this.request("PATCH", `/admin/license-enquiries/${id}`, { counterOffer, notes });
     }
 }
-/**
- * ADR-289 Wave C1 — booking enquiries (internal-team session/production
- * bookings, distinct from `LicensingResource`'s sync-license enquiries).
- * Wraps `/admin/bookings` + `/admin/bookings/[id]`.
- */
+function bookingListPath(params) {
+    const qp = new URLSearchParams();
+    if (params?.status)
+        qp.set("status", params.status);
+    if (params?.priority)
+        qp.set("priority", params.priority);
+    if (params?.query)
+        qp.set("query", params.query);
+    if (params?.enquiry_type)
+        qp.set("enquiry_type", params.enquiry_type);
+    if (params?.follow_up_required !== undefined)
+        qp.set("follow_up_required", String(params.follow_up_required));
+    if (params?.limit !== undefined)
+        qp.set("limit", String(params.limit));
+    if (params?.offset !== undefined)
+        qp.set("offset", String(params.offset));
+    const qs = qp.toString();
+    return `/admin/bookings${qs ? `?${qs}` : ""}`;
+}
 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.
      */
     async list(params) {
-        const qp = new URLSearchParams();
-        if (params?.status)
-            qp.set("status", params.status);
-        if (params?.priority)
-            qp.set("priority", params.priority);
-        if (params?.query)
-            qp.set("query", params.query);
-        if (params?.enquiry_type)
-            qp.set("enquiry_type", params.enquiry_type);
-        if (params?.follow_up_required !== undefined)
-            qp.set("follow_up_required", String(params.follow_up_required));
-        if (params?.limit !== undefined)
-            qp.set("limit", String(params.limit));
-        if (params?.offset !== undefined)
-            qp.set("offset", String(params.offset));
-        const qs = qp.toString();
-        return this.request("GET", `/admin/bookings${qs ? `?${qs}` : ""}`);
+        return this.request("GET", bookingListPath(params));
+    }
+    /**
+     * 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.
+     */
+    async listPage(params) {
+        return this.requestPaginated("GET", bookingListPath(params));
     }
     async get(id) {
         return this.request("GET", `/admin/bookings/${encodeURIComponent(id)}`);
@@ -1084,39 +1262,51 @@ class MultimediaResource extends BaseResource {
         });
     }
 }
+function agreementListPath(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.query)
+        queryParams.set("query", params.query);
+    if (params?.agreement_type)
+        queryParams.set("agreement_type", params.agreement_type);
+    if (params?.status)
+        queryParams.set("status", params.status);
+    if (params?.party_name)
+        queryParams.set("party_name", params.party_name);
+    if (params?.includeWorkCounts)
+        queryParams.set("includeWorkCounts", "true");
+    if (params?.awaiting_signature)
+        queryParams.set("awaiting_signature", "true");
+    if (params?.start_date_from)
+        queryParams.set("start_date_from", params.start_date_from);
+    if (params?.start_date_to)
+        queryParams.set("start_date_to", params.start_date_to);
+    if (params?.end_date_from)
+        queryParams.set("end_date_from", params.end_date_from);
+    if (params?.end_date_to)
+        queryParams.set("end_date_to", params.end_date_to);
+    if (params?.expiring_within_days !== undefined)
+        queryParams.set("expiring_within_days", String(params.expiring_within_days));
+    if (params?.has_end_date !== undefined)
+        queryParams.set("has_end_date", String(params.has_end_date));
+    if (params?.limit !== undefined)
+        queryParams.set("limit", String(params.limit));
+    if (params?.offset !== undefined)
+        queryParams.set("offset", String(params.offset));
+    const query = queryParams.toString();
+    return `/admin/agreements${query ? `?${query}` : ""}`;
+}
 class AgreementsResource extends BaseResource {
+    /** One page of agreements (the bare array; see listPage for the real total). */
     async list(params) {
-        const queryParams = new URLSearchParams();
-        if (params?.query)
-            queryParams.set("query", params.query);
-        if (params?.agreement_type)
-            queryParams.set("agreement_type", params.agreement_type);
-        if (params?.status)
-            queryParams.set("status", params.status);
-        if (params?.party_name)
-            queryParams.set("party_name", params.party_name);
-        if (params?.includeWorkCounts)
-            queryParams.set("includeWorkCounts", "true");
-        if (params?.awaiting_signature)
-            queryParams.set("awaiting_signature", "true");
-        if (params?.start_date_from)
-            queryParams.set("start_date_from", params.start_date_from);
-        if (params?.start_date_to)
-            queryParams.set("start_date_to", params.start_date_to);
-        if (params?.end_date_from)
-            queryParams.set("end_date_from", params.end_date_from);
-        if (params?.end_date_to)
-            queryParams.set("end_date_to", params.end_date_to);
-        if (params?.expiring_within_days !== undefined)
-            queryParams.set("expiring_within_days", String(params.expiring_within_days));
-        if (params?.has_end_date !== undefined)
-            queryParams.set("has_end_date", String(params.has_end_date));
-        if (params?.limit !== undefined)
-            queryParams.set("limit", String(params.limit));
-        if (params?.offset !== undefined)
-            queryParams.set("offset", String(params.offset));
-        const query = queryParams.toString();
-        return this.request("GET", `/admin/agreements${query ? `?${query}` : ""}`);
+        return this.request("GET", agreementListPath(params));
+    }
+    /**
+     * 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.
+     */
+    async listPage(params) {
+        return this.requestPaginated("GET", agreementListPath(params));
     }
     async get(id) {
         return this.request("GET", `/admin/agreements/${id}`);
@@ -1189,10 +1379,28 @@ class AgreementsResource extends BaseResource {
         return this.request("POST", `/admin/agreements/${id}/send-for-signature`, { expiresInDays: params?.expires_in_days });
     }
 }
-// ADR-222 — sync placements as a first-class domain. REST routes implemented
-// by W4 at /api/admin/sync-placements (paired PR on the same parent feature
-// branch). All methods scope to the caller's organisation server-side via
-// requireOrganisationContext — no orgId param needed on the SDK surface.
+/** Sync fit: GET /admin/sync-fit, the same read as /inspect/sync. */
+class SyncFitResource extends BaseResource {
+    async query(params) {
+        const q = new URLSearchParams();
+        if (params?.work_id)
+            q.set("work_id", params.work_id);
+        if (params?.screen_project_id)
+            q.set("screen_project_id", params.screen_project_id);
+        if (params?.song_facts)
+            q.set("song_facts", "true");
+        if (params?.limit)
+            q.set("limit", String(params.limit));
+        if (params?.offset)
+            q.set("offset", String(params.offset));
+        const qs = q.toString();
+        const res = await this.request("GET", `/admin/sync-fit${qs ? `?${qs}` : ""}`);
+        if (res && typeof res === "object" && "data" in res && res.data) {
+            return res.data;
+        }
+        return res;
+    }
+}
 class SyncPlacementsResource extends BaseResource {
     async list(params) {
         const queryParams = new URLSearchParams();
@@ -1735,6 +1943,16 @@ class EnrichmentResource extends BaseResource {
     async bulkRejectProposals(input) {
         return this.request("POST", "/admin/enrichment-proposals/bulk-reject", input);
     }
+    /**
+     * What bulkRejectProposals would reject, without rejecting: the route
+     * resolves the same pending set the real call would (row-cap T3).
+     */
+    async previewBulkRejectProposals(input) {
+        return this.request("POST", "/admin/enrichment-proposals/bulk-reject", {
+            ...input,
+            dry_run: true,
+        });
+    }
     /**
      * Apply many pending proposals in one call — the accept side of the
      * /inspect/found queue.
@@ -2676,6 +2894,24 @@ class DuplicatesResource extends BaseResource {
             loser_ids: loserIds,
         });
     }
+    /**
+     * "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}.
+     */
+    async markDifferent(entityType, ids) {
+        return this.request("POST", "/admin/catalog/duplicates/exclusions", {
+            entity_type: entityType,
+            ids,
+        });
+    }
+    /** Take back markDifferent for every pair among `ids`. */
+    async unmarkDifferent(entityType, ids) {
+        return this.request("DELETE", "/admin/catalog/duplicates/exclusions", {
+            entity_type: entityType,
+            ids,
+        });
+    }
 }
 // --- Entity Context Resource (ADR-116 Phase 3) ---
 class EntityContextResource extends BaseResource {
@@ -2943,6 +3179,40 @@ class CollaboratorsResource extends BaseResource {
         const qs = qp.toString();
         return this.request("GET", `/admin/collaborators/invites${qs ? `?${qs}` : ""}`);
     }
+    /**
+     * 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.
+     */
+    async listInvitesPage(params) {
+        const qp = new URLSearchParams();
+        if (params?.status)
+            qp.set("status", params.status);
+        if (params?.workId)
+            qp.set("workId", params.workId);
+        if (params?.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params?.offset)
+            qp.set("offset", String(params.offset));
+        const qs = qp.toString();
+        return this.requestNestedPage(`/admin/collaborators/invites${qs ? `?${qs}` : ""}`, params?.offset ?? 0);
+    }
+    /**
+     * Reads a collaborator list route, whose rows sit at `data.data` (kept
+     * for published SDKs) with the total in the top-level `pagination`.
+     */
+    async requestNestedPage(path, offset) {
+        const json = await this.requestWithEnvelope("GET", path);
+        const inner = json.data;
+        const rows = Array.isArray(inner) ? inner : (inner?.data ?? []);
+        const pagination = json.pagination;
+        const total = pagination?.total ?? rows.length;
+        return {
+            data: rows,
+            total,
+            hasMore: pagination?.hasMore ?? offset + rows.length < total,
+        };
+    }
     async resendInvite(inviteId) {
         return this.request("POST", `/admin/collaborators/invites/${inviteId}/resend`);
     }
@@ -2961,6 +3231,21 @@ class CollaboratorsResource extends BaseResource {
         const res = await this.request("GET", `/admin/collaborators/incoming${qs ? `?${qs}` : ""}`);
         return res.data;
     }
+    /**
+     * One page of the invites addressed to the caller WITH the real total and
+     * has_more (row-cap T3: `listIncoming()` returns only the rows).
+     */
+    async listIncomingPage(params) {
+        const qp = new URLSearchParams();
+        if (params?.status)
+            qp.set("status", params.status);
+        if (params?.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params?.offset)
+            qp.set("offset", String(params.offset));
+        const qs = qp.toString();
+        return this.requestNestedPage(`/admin/collaborators/incoming${qs ? `?${qs}` : ""}`, params?.offset ?? 0);
+    }
     /**
      * ADR-157 warm path — accept an invite addressed to the authenticated
      * user, and flip its status to confirmed. The credit write is
@@ -3192,6 +3477,10 @@ class DirectoryResource extends BaseResource {
     async updateSettings(updates) {
         return this.request("PATCH", "/admin/directory/settings", updates);
     }
+    /** Listed songs with lyrics and topics on, but no approved topic yet. */
+    async untaggedThemes() {
+        return this.request("GET", "/admin/directory/themes/untagged");
+    }
 }
 class ProjectsResource extends BaseResource {
     async list(params) {
@@ -3438,6 +3727,21 @@ class RecordingSplitsResource extends BaseResource {
     }
 }
 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.
+     */
+    async listPage(params) {
+        const queryParams = new URLSearchParams();
+        if (params?.query)
+            queryParams.set("query", params.query);
+        if (params?.limit)
+            queryParams.set("limit", String(params.limit));
+        if (params?.offset)
+            queryParams.set("offset", String(params.offset));
+        const qs = queryParams.toString();
+        return this.requestPaginated("GET", `/admin/publishers${qs ? `?${qs}` : ""}`);
+    }
     async list(params) {
         const queryParams = new URLSearchParams();
         if (params?.query)
@@ -3452,6 +3756,25 @@ class PublishersResource extends BaseResource {
     }
 }
 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.
+     */
+    async listPage(params) {
+        const queryParams = new URLSearchParams();
+        if (params?.query)
+            queryParams.set("query", params.query);
+        if (params?.limit)
+            queryParams.set("limit", String(params.limit));
+        if (params?.offset)
+            queryParams.set("offset", String(params.offset));
+        if (params?.org_type)
+            queryParams.set("org_type", params.org_type);
+        if (params?.ids?.length)
+            queryParams.set("ids", params.ids.join(","));
+        const qs = queryParams.toString();
+        return this.requestPaginated("GET", `/admin/labels${qs ? `?${qs}` : ""}`);
+    }
     async list(params) {
         const queryParams = new URLSearchParams();
         if (params?.query)
@@ -3480,14 +3803,20 @@ class LabelsResource extends BaseResource {
         return (res ?? null);
     }
 }
-/**
- * ADR-268 WS1 — party org claim flow. `invite()` sends an artist-anchored
- * claim invite for an unclaimed label/distributor/publisher org;
- * `list()` reads the claims the calling org has sent.
- *
- * Typed against the UNWRAPPED reality (ADR-265 lesson): BaseResource.request
- * auto-unwraps the `{success,data}` envelope, so methods see `data` itself.
- */
+function partyClaimListPath(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.target_organisation_id) {
+        queryParams.set("target_organisation_id", params.target_organisation_id);
+    }
+    if (params?.status)
+        queryParams.set("status", params.status);
+    if (params?.limit)
+        queryParams.set("limit", String(params.limit));
+    if (params?.offset)
+        queryParams.set("offset", String(params.offset));
+    const qs = queryParams.toString();
+    return `/admin/party-claims${qs ? `?${qs}` : ""}`;
+}
 class PartyClaimsResource extends BaseResource {
     async invite(params) {
         const res = await this.request("POST", "/admin/party-claims", params);
@@ -3499,20 +3828,19 @@ class PartyClaimsResource extends BaseResource {
         return (res ?? null);
     }
     async list(params) {
-        const queryParams = new URLSearchParams();
-        if (params?.target_organisation_id) {
-            queryParams.set("target_organisation_id", params.target_organisation_id);
-        }
-        if (params?.status)
-            queryParams.set("status", params.status);
-        if (params?.limit)
-            queryParams.set("limit", String(params.limit));
-        const qs = queryParams.toString();
-        const res = await this.request("GET", `/admin/party-claims${qs ? `?${qs}` : ""}`);
+        const res = await this.request("GET", partyClaimListPath(params));
         if (Array.isArray(res))
             return res;
         return (res?.data ?? []);
     }
+    /**
+     * 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.
+     */
+    async listPage(params) {
+        return this.requestPaginated("GET", partyClaimListPath(params));
+    }
 }
 /**
  * Claim your profile: invite people to claim their profile (a preview
@@ -3544,25 +3872,38 @@ class ProfileClaimsResource extends BaseResource {
         };
     }
 }
+function releaseListPath(params) {
+    const parts = [];
+    if (params?.limit != null)
+        parts.push(`limit=${params.limit}`);
+    if (params?.offset != null)
+        parts.push(`offset=${params.offset}`);
+    if (params?.query)
+        parts.push(`query=${encodeURIComponent(params.query)}`);
+    if (params?.upc)
+        parts.push(`upc=${encodeURIComponent(params.upc)}`);
+    if (params?.spotify_album_id)
+        parts.push(`spotify_album_id=${encodeURIComponent(params.spotify_album_id)}`);
+    if (params?.release_date_from)
+        parts.push(`release_date_from=${encodeURIComponent(params.release_date_from)}`);
+    if (params?.release_date_to)
+        parts.push(`release_date_to=${encodeURIComponent(params.release_date_to)}`);
+    const qs = parts.length > 0 ? `?${parts.join("&")}` : "";
+    return `/admin/releases${qs}`;
+}
 class ReleasesResource extends BaseResource {
+    /** One page of releases (the bare array; see listPage for the real total). */
     async list(params) {
-        const parts = [];
-        if (params?.limit != null)
-            parts.push(`limit=${params.limit}`);
-        if (params?.offset != null)
-            parts.push(`offset=${params.offset}`);
-        if (params?.query)
-            parts.push(`query=${encodeURIComponent(params.query)}`);
-        if (params?.upc)
-            parts.push(`upc=${encodeURIComponent(params.upc)}`);
-        if (params?.spotify_album_id)
-            parts.push(`spotify_album_id=${encodeURIComponent(params.spotify_album_id)}`);
-        if (params?.release_date_from)
-            parts.push(`release_date_from=${encodeURIComponent(params.release_date_from)}`);
-        if (params?.release_date_to)
-            parts.push(`release_date_to=${encodeURIComponent(params.release_date_to)}`);
-        const qs = parts.length > 0 ? `?${parts.join("&")}` : "";
-        return this.request("GET", `/admin/releases${qs}`);
+        return this.request("GET", releaseListPath(params));
+    }
+    /**
+     * 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.
+     */
+    async listPage(params) {
+        return this.requestPaginated("GET", releaseListPath(params));
     }
     async get(id) {
         return this.request("GET", `/admin/releases/${id}`);
@@ -3681,15 +4022,27 @@ class ReleasesResource extends BaseResource {
         return this.request("POST", "/admin/releases/create-with-tracks", data);
     }
 }
+function sessionListPath(params) {
+    const query = new URLSearchParams();
+    if (params?.limit)
+        query.set("limit", String(params.limit));
+    if (params?.offset)
+        query.set("offset", String(params.offset));
+    const qs = query.toString();
+    return `/admin/sessions${qs ? `?${qs}` : ""}`;
+}
 class SessionsResource extends BaseResource {
+    /** One page of upcoming sessions (see listPage for the real total). */
     async list(params) {
-        const query = new URLSearchParams();
-        if (params?.limit)
-            query.set("limit", String(params.limit));
-        if (params?.offset)
-            query.set("offset", String(params.offset));
-        const qs = query.toString();
-        return this.request("GET", `/admin/sessions${qs ? `?${qs}` : ""}`);
+        return this.request("GET", sessionListPath(params));
+    }
+    /**
+     * 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".
+     */
+    async listPage(params) {
+        return this.requestPaginated("GET", sessionListPath(params));
     }
     async get(id) {
         return this.request("GET", `/admin/sessions/${id}`);
@@ -3824,6 +4177,113 @@ class RightsResource extends BaseResource {
         return this.request("GET", "/admin/rights-statements/measures");
     }
 }
+function pageQuery(params) {
+    const qp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            value.forEach((v) => qp.append(key, v));
+        else
+            qp.set(key, String(value));
+    }
+    const qs = qp.toString();
+    return qs ? `?${qs}` : "";
+}
+/**
+ * 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.
+ */
+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.
+     */
+    async create(body) {
+        return this.request("POST", "/admin/handovers", body);
+    }
+    /** POST /admin/handovers/{id}/send { expected_version? } — email the client. */
+    async send(id, body) {
+        return this.request("POST", `/admin/handovers/${encodeURIComponent(id)}/send`, body);
+    }
+}
+/**
+ * /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`.
+ */
+class RelationshipsResource extends BaseResource {
+    /** GET /admin/relationships?side=owner|organisation&status=&cursor=&limit= */
+    async list(params) {
+        return this.request("GET", `/admin/relationships${pageQuery({
+            side: params.side,
+            status: params.statuses,
+            cursor: params.cursor,
+            limit: params.limit,
+        })}`);
+    }
+    /** GET /admin/relationships/{id} */
+    async get(id) {
+        return this.request("GET", `/admin/relationships/${encodeURIComponent(id)}`);
+    }
+    /**
+     * 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.
+     */
+    async invite(body) {
+        return this.request("POST", "/admin/relationships", body);
+    }
+    /** PATCH /admin/relationships/{id} { action: accept | decline | edit, expected_version, … } */
+    async answer(id, body) {
+        return this.request("PATCH", `/admin/relationships/${encodeURIComponent(id)}`, body);
+    }
+    /** DELETE /admin/relationships/{id} { expected_version, reason? } — the owner ends it. */
+    async revoke(id, body) {
+        return this.request("DELETE", `/admin/relationships/${encodeURIComponent(id)}`, body);
+    }
+    /** POST /admin/relationships/{id}/step-down { expected_version, reason? } — the organisation ends its side. */
+    async stepDown(id, body) {
+        return this.request("POST", `/admin/relationships/${encodeURIComponent(id)}/step-down`, body);
+    }
+    /** GET /admin/relationships/{id}/activity — one relationship's history, either party. */
+    async events(id, params = {}) {
+        return this.request("GET", `/admin/relationships/${encodeURIComponent(id)}/activity${pageQuery(params)}`);
+    }
+    /**
+     * 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).
+     */
+    async activity(params) {
+        return this.request("GET", `/admin/relationships/activity${pageQuery(params)}`);
+    }
+    /**
+     * PATCH /admin/relationships/invites/{id} { action: "accept", organisation_id, type?, scope? }
+     * — answer yes to an invitation for one of the person's organisations.
+     */
+    async acceptInvite(inviteId, body) {
+        return this.request("PATCH", `/admin/relationships/invites/${encodeURIComponent(inviteId)}`, { action: "accept", ...body });
+    }
+}
+/**
+ * /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.
+ */
+class PortfolioResource extends BaseResource {
+    /** GET /admin/portfolio?cursor=&limit= (limit ≤ 25) */
+    async list(params = {}) {
+        return this.request("GET", `/admin/portfolio${pageQuery(params)}`);
+    }
+    /** GET /admin/portfolio/briefing?cursor=&limit= — the list plus what needs attention. */
+    async briefing(params = {}) {
+        return this.request("GET", `/admin/portfolio/briefing${pageQuery(params)}`);
+    }
+}
 class RoyaltiesResource extends BaseResource {
     async payments(params) {
         const qp = new URLSearchParams();
@@ -4044,6 +4504,11 @@ class CustodyResource extends BaseResource {
     async respond(body) {
         return this.request("POST", "/admin/custody/respond", body);
     }
+    /**
+     * 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`.
+     */
     async list(params) {
         const qp = new URLSearchParams();
         if (params?.direction)
@@ -4052,6 +4517,8 @@ class CustodyResource extends BaseResource {
             qp.set("status", params.status);
         if (params?.limit !== undefined)
             qp.set("limit", String(params.limit));
+        if (params?.offset)
+            qp.set("offset", String(params.offset));
         const qs = qp.toString();
         return this.request("GET", `/admin/custody/list${qs ? `?${qs}` : ""}`);
     }
@@ -4270,6 +4737,7 @@ export class PicaClient {
     agreements;
     // ADR-222 — sync placements (W3, paired with W4 REST routes).
     syncPlacements;
+    syncFit;
     workspace;
     memory;
     audit;
@@ -4318,6 +4786,11 @@ export class PicaClient {
     producerAgreements;
     workForHire;
     royalties;
+    /** ADR-333 — who looks after whose catalogue, from either side. */
+    relationships;
+    handovers;
+    /** ADR-333 — the client catalogues an organisation looks after. */
+    portfolio;
     /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
     rights;
     statements;
@@ -4382,6 +4855,7 @@ export class PicaClient {
         this.multimedia = new MultimediaResource(baseUrl, config.apiKey, debug);
         this.agreements = new AgreementsResource(baseUrl, config.apiKey, debug);
         this.syncPlacements = new SyncPlacementsResource(baseUrl, config.apiKey, debug);
+        this.syncFit = new SyncFitResource(baseUrl, config.apiKey, debug);
         this.workspace = new WorkspaceResource(baseUrl, config.apiKey, debug);
         this.memory = new MemoryResource(baseUrl, config.apiKey, debug);
         this.audit = new AuditResource(baseUrl, config.apiKey, debug);
@@ -4428,6 +4902,9 @@ export class PicaClient {
         this.producerAgreements = new ProducerAgreementsResource(baseUrl, config.apiKey, debug);
         this.workForHire = new WorkForHireResource(baseUrl, config.apiKey, debug);
         this.royalties = new RoyaltiesResource(baseUrl, config.apiKey, debug);
+        this.relationships = new RelationshipsResource(baseUrl, config.apiKey, debug);
+        this.handovers = new HandoversResource(baseUrl, config.apiKey, debug);
+        this.portfolio = new PortfolioResource(baseUrl, config.apiKey, debug);
         this.rights = new RightsResource(baseUrl, config.apiKey, debug);
         this.statements = new StatementsResource(baseUrl, config.apiKey, debug);
         this.selections = new SelectionsResource(baseUrl, config.apiKey, debug);