@withpica/mcp-sdk 3.19.0 → 3.21.0

package/dist/index.js

@@ -420,6 +420,13 @@ class WorksResource extends BaseResource {
     async delete(id) {
         return this.request("DELETE", `/admin/works/${id}`);
     }
+    /**
+     * @deprecated `works` has no `is_verified` column, so PATCH /admin/works/[id]
+     * refuses this body (VALIDATION_ERROR "unknown field 'is_verified'") on every
+     * call. PICA keeps no work-level verified flag; the MCP tool
+     * `pica_works_verify` no longer calls this. Kept only so the published SDK's
+     * surface does not break; remove at the next major.
+     */
     async verify(id) {
         return this.request("PATCH", `/admin/works/${id}`, {
             is_verified: true,
@@ -882,6 +889,8 @@ class AudioFilesResource extends BaseResource {
         const queryParams = new URLSearchParams();
         if (params?.work_id)
             queryParams.set("work_id", params.work_id);
+        if (params?.work_ids && params.work_ids.length > 0)
+            queryParams.set("work_ids", params.work_ids.join(","));
         if (params?.file_type)
             queryParams.set("file_type", params.file_type);
         if (params?.unprocessed)
@@ -942,6 +951,15 @@ class AudioFilesResource extends BaseResource {
     async update(id, body) {
         return this.request("PATCH", `/admin/audio-files/${id}`, body);
     }
+    /**
+     * Per-file metadata patches for up to 200 files in one request (ops issue
+     * 5c53049a). Returns one lean result per item — `updated`, `would_update`
+     * (dry run) or `failed` with a reason — never the rows. Wraps
+     * POST /admin/audio-files/bulk-update.
+     */
+    async bulkUpdate(items, params) {
+        return this.request("POST", "/admin/audio-files/bulk-update", { items, ...(params?.dry_run ? { dry_run: true } : {}) });
+    }
     async analyze(id, options) {
         return this.request("POST", `/admin/audio-files/${id}/analyze`, options);
     }
@@ -1631,6 +1649,11 @@ class EnrichmentResource extends BaseResource {
      * `artist_title_to_youtube` recording-create), a uniqueness check
      * runs instead; conflicts return `{ status: 'create_conflict' }` and
      * cannot be forced.
+     *
+     * File-type questions (`entity_type: 'audio_file'`) take the owner's own
+     * answer: `file_type` (master / version / instrumental / demo / stem) and,
+     * for a stem, an optional `stem_label`. A refused answer is a 400 with
+     * `code: 'INVALID_FILE_TYPE_ANSWER'`.
      */
     async applyEnrichmentProposal(proposalId, options) {
         return this.request("POST", `/admin/enrichment-proposals/${proposalId}/apply`, options ?? {});
@@ -1743,6 +1766,43 @@ class HealthResource extends BaseResource {
     async getLowScoreWorks() {
         return this.request("GET", "/admin/quality/completeness/low-score");
     }
+    /**
+     * One page of works below a completeness threshold, with the route's
+     * `meta` (true `total` below the threshold, `has_more`). Backs
+     * `pica_works_query {health_filter: "low_completeness"}` — the bare
+     * `getLowScoreWorks()` above sends no limit/offset, so the tool used to
+     * ignore both (ops issue 314325eb).
+     */
+    async getLowScoreWorksPage(params) {
+        const qp = new URLSearchParams();
+        if (params.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params.offset !== undefined)
+            qp.set("offset", String(params.offset));
+        if (params.threshold !== undefined)
+            qp.set("threshold", String(params.threshold));
+        const qs = qp.toString();
+        const env = await this.requestWithEnvelope("GET", `/admin/quality/completeness/low-score${qs ? `?${qs}` : ""}`);
+        return { data: Array.isArray(env.data) ? env.data : [], meta: env.meta };
+    }
+    /**
+     * One page of the cross-org reconciliation scan, with the route's `meta`
+     * (`scanned`, `candidates_total`, `next_offset`). `offset`/`limit` page the
+     * candidate works, not the returned rows — see the route. Backs
+     * `pica_works_query {health_filter: "needs_attention"}`.
+     */
+    async getWorksHealthPage(params) {
+        const qp = new URLSearchParams();
+        if (params.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params.offset !== undefined)
+            qp.set("offset", String(params.offset));
+        if (params.unreconciledOnly)
+            qp.set("unreconciledOnly", "true");
+        const qs = qp.toString();
+        const env = await this.requestWithEnvelope("GET", `/admin/quality/works-health${qs ? `?${qs}` : ""}`);
+        return { data: Array.isArray(env.data) ? env.data : [], meta: env.meta };
+    }
     async getWorkCompleteness(workId) {
         return this.request("GET", `/admin/quality/completeness/${workId}`);
     }
@@ -3584,6 +3644,30 @@ class WorkForHireResource extends BaseResource {
         await this.request("DELETE", `/admin/work-for-hire/${id}`);
     }
 }
+/**
+ * ADR-321 Phase 2 — programmable rights. `propose` only proposes: the route
+ * never activates a rule on an API key, and each party confirms by email.
+ */
+class RightsResource extends BaseResource {
+    /**
+     * POST /admin/works/{id}/rights/propose. Body is one of
+     * `{ rule: "song" }`, `{ rule: "master", recording_id }` or
+     * `{ rule: "share", side?, recording_id?, subject_person_id, kind,
+     * parties: [{ person_id, share_bp }], effective_from, effective_to? }`.
+     * A refusal is a 422 carrying `details.reasons`.
+     */
+    async propose(workId, body) {
+        return this.request("POST", `/admin/works/${encodeURIComponent(workId)}/rights/propose`, body);
+    }
+    /** GET /admin/rights/rules/{id} — one rule's status and confirmations. */
+    async status(ruleId) {
+        return this.request("GET", `/admin/rights/rules/${encodeURIComponent(ruleId)}`);
+    }
+    /** GET /admin/works/{id}/rights — every rule on a song, history, holds. */
+    async inspect(workId) {
+        return this.request("GET", `/admin/works/${encodeURIComponent(workId)}/rights`);
+    }
+}
 class RoyaltiesResource extends BaseResource {
     async payments(params) {
         const qp = new URLSearchParams();
@@ -3630,6 +3714,26 @@ class RoyaltiesResource extends BaseResource {
         const qs = qp.toString();
         return this.request("GET", `/admin/royalties/gaps${qs ? `?${qs}` : ""}`);
     }
+    /**
+     * ADR-321 Phase 0 — what in one song's record is likely holding up its
+     * society income. `state` is "clear" only when every area was checked;
+     * `unchecked` lists areas that could not be.
+     */
+    async blockers(workId) {
+        return this.request("GET", `/admin/works/${encodeURIComponent(workId)}/money-blockers`);
+    }
+    /** ADR-321 Phase 0 — the catalogue roll-up: summary + songs not clear, paged. */
+    async blockersCatalogue(params) {
+        const qp = new URLSearchParams();
+        if (params?.code)
+            qp.set("code", params.code);
+        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/money-blockers${qs ? `?${qs}` : ""}`);
+    }
     async stats() {
         return this.request("GET", "/admin/royalties/stats");
     }
@@ -4057,6 +4161,8 @@ export class PicaClient {
     producerAgreements;
     workForHire;
     royalties;
+    /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
+    rights;
     statements;
     /** ADR-319 — saved catalog selections. */
     selections;
@@ -4173,6 +4279,7 @@ 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.rights = new RightsResource(baseUrl, config.apiKey, debug);
         this.statements = new StatementsResource(baseUrl, config.apiKey, debug);
         this.selections = new SelectionsResource(baseUrl, config.apiKey, debug);
         this.shareLinks = new ShareLinksResource(baseUrl, config.apiKey, debug);