@withpica/mcp-sdk 3.23.0 → 3.24.0

package/dist/index.js

@@ -54,6 +54,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));
 }
@@ -245,13 +253,20 @@ 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`.
      */
     async requestText(method, path) {
         const url = `${this.baseUrl}${path}`;
@@ -275,6 +290,9 @@ class BaseResource {
             }
             return typeof data === "string" ? data : JSON.stringify(data);
         }
+        if (contentType.includes("text/html")) {
+            throw new ApiError(`Expected a file from ${path} but got an HTML page; the request did not reach PICA`, response.status, false);
+        }
         return response.text();
     }
     /**
@@ -302,8 +320,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;
@@ -396,6 +424,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}`);
     }
@@ -507,6 +544,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) {
@@ -618,6 +671,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
@@ -663,33 +733,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
      */
@@ -712,34 +775,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)}`);
@@ -1074,39 +1143,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}`);
@@ -1179,10 +1260,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();
@@ -1725,6 +1824,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.
@@ -2548,7 +2657,7 @@ class ExportResource extends BaseResource {
         // request() unconditionally calls response.json(), which throws parsing
         // a CSV body — every pro/distributor/nro call 500'd with INTERNAL_ERROR
         // (pica_export_catalog_csv: 5/5 prod errors, ops audit 2026-07-04).
-        // requestText() mirrors the ImportResource.getTemplate() precedent for
+        // requestText() serves ImportResource.getTemplate() too, for
         // the same response shape.
         if (params.format === "sync-pdf") {
             return this.request("GET", path);
@@ -2847,14 +2956,10 @@ class ImportResource extends BaseResource {
         });
     }
     async getTemplate(domain) {
-        // Template route returns CSV as text/csv — use raw fetch
-        const url = `${this.baseUrl}/admin/import/template?domain=${domain}`;
-        const response = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-        });
-        if (!response.ok)
-            throw new Error(`Template fetch failed: ${response.status}`);
-        return response.text();
+        // The route answers text/csv, so requestText(), not request(). It was a
+        // bare fetch() with no preview-protection bypass header, so on a Vercel
+        // preview it never reached the route (2026-10-06).
+        return this.requestText("GET", `/admin/import/template?domain=${encodeURIComponent(domain)}`);
     }
     /**
      * Emails that reached the organisation's forwarding address, newest first,
@@ -2937,6 +3042,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`);
     }
@@ -2955,6 +3094,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
@@ -3186,6 +3340,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) {
@@ -3432,6 +3590,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)
@@ -3446,6 +3619,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)
@@ -3474,14 +3666,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);
@@ -3493,20 +3691,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
@@ -3538,25 +3735,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}`);
@@ -3675,15 +3885,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}`);
@@ -4038,6 +4260,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)
@@ -4046,6 +4273,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}` : ""}`);
     }
@@ -4264,6 +4493,7 @@ export class PicaClient {
     agreements;
     // ADR-222 — sync placements (W3, paired with W4 REST routes).
     syncPlacements;
+    syncFit;
     workspace;
     memory;
     audit;
@@ -4346,24 +4576,15 @@ export class PicaClient {
     // Registration Integrity Floor (spec 2026-07-09, Task 8).
     integrity;
     async catalogStats(params) {
-        const baseUrl = this.works["baseUrl"];
-        const apiKey = this.works["apiKey"];
         const qp = new URLSearchParams();
         if (params?.entity)
             qp.set("entity", params.entity);
         if (params?.group_by)
             qp.set("group_by", params.group_by);
         const suffix = qp.toString() ? `?${qp.toString()}` : "";
-        const res = await fetch(`${baseUrl}/admin/catalog/stats${suffix}`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!res.ok)
-            throw new Error(`Catalog stats failed: ${res.status}`);
-        const json = (await res.json());
-        return (json.data || json);
+        // Through the shared request path (bypass header, timeout, retry, typed
+        // errors) rather than a bare fetch() that skipped all four (2026-10-06).
+        return this.works["request"]("GET", `/admin/catalog/stats${suffix}`);
     }
     constructor(config) {
         if (!config.apiKey) {
@@ -4385,6 +4606,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);