@withpica/mcp-sdk 3.5.0 → 3.7.0

package/dist/index.js

@@ -203,6 +203,37 @@ class BaseResource {
         }
         return (data.data || data);
     }
+    /**
+     * Like `request`, but returns the FULL parsed envelope instead of
+     * narrowing to `.data`. Needed by the two spreadsheet-moment auto-twin
+     * routes (`POST /admin/works`, `POST /admin/recordings`), whose response
+     * carries `twin`/`twin_error` as siblings of `data` — `request()`'s
+     * `return data.data || data` would otherwise silently drop them before
+     * the MCP tool ever sees a twin was created.
+     */
+    async requestWithEnvelope(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const timeoutMs = getTimeoutForPath(path);
+        if (this.debug) {
+            console.error(`[PICA SDK] ${method} ${url} (timeout: ${timeoutMs}ms)`);
+        }
+        const response = await this.fetchWithRetry(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                ...this.getBypassHeaders(),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        }, timeoutMs);
+        const json = await response.json();
+        // Same success:false guard as `request()` — see its comment above.
+        if (json && typeof json === "object" && json.success === false) {
+            const msg = typeof json.error === "string" ? json.error : "unspecified error";
+            throw new ApiError(`API returned success:false: ${msg}`, response.status, false);
+        }
+        return json;
+    }
     /**
      * Make a request whose SUCCESS body is raw text, not a JSON envelope —
      * for routes that stream a generated file (e.g. `text/csv`) rather than
@@ -353,7 +384,19 @@ class WorksResource extends BaseResource {
         return this.request("GET", `/admin/works/${id}`);
     }
     async create(data) {
-        return this.request("POST", "/admin/works", data);
+        // Spreadsheet-moment auto-twin — the route response carries `twin` /
+        // `twin_error` as siblings of `data`, which the plain `request()`
+        // helper would drop (it narrows to `.data`). Fetch the full envelope
+        // and merge the twin fields onto the returned Work so callers (and the
+        // MCP tool executor) can see them.
+        const envelope = await this.requestWithEnvelope("POST", "/admin/works", data);
+        return {
+            ...envelope.data,
+            twin: envelope.twin ?? null,
+            ...(envelope.twin_error !== undefined && {
+                twin_error: envelope.twin_error,
+            }),
+        };
     }
     async update(id, updates) {
         return this.request("PATCH", `/admin/works/${id}`, updates);
@@ -392,6 +435,18 @@ class WorksResource extends BaseResource {
         const result = await this.request("GET", `/admin/works/${workId}/releases`);
         return result?.data || [];
     }
+    /**
+     * Assemble the full song dossier for one work — everything PICA holds about
+     * a song in one call (work, recordings, releases, composition credits,
+     * people, provenance, AI disclosure, consent). Backs the `dossier` section
+     * of pica_works_inspect. JSON format only here; the PDF export lives on the
+     * web UI (`GET /admin/works/[id]/dossier?format=pdf`).
+     *
+     * `request()` unwraps the `{ success, data }` envelope to the dossier itself.
+     */
+    async dossier(workId) {
+        return this.request("GET", `/admin/works/${workId}/dossier?format=json`);
+    }
     /**
      * Stamp a human-creation provenance attestation. Complement to the
      * AI-disclosure side — captures who signed, when, the attestation
@@ -704,6 +759,37 @@ class PicaScoreResource extends BaseResource {
         return this.request("GET", "/admin/pica-score");
     }
 }
+class IntegrityResource extends BaseResource {
+    /**
+     * GET /admin/integrity/assess?entity_type=&entity_id= -> single-entity assessment.
+     * NOTE: for entity_type "release" this is a documented v1 no-op — no
+     * release-grain gap code exists yet, so `gaps` is always empty by design
+     * (see assessEntity's release branch in lib/services/integrity-floor.ts).
+     */
+    async assessEntity(entityType, entityId) {
+        const qp = new URLSearchParams({
+            entity_type: entityType,
+            entity_id: entityId,
+        });
+        return this.request("GET", `/admin/integrity/assess?${qp.toString()}`);
+    }
+    /** GET /admin/integrity/assess (no params) -> org-grain summary. */
+    async assessOrg() {
+        return this.request("GET", "/admin/integrity/assess");
+    }
+    /**
+     * POST /admin/integrity/waivers. Duplicate-active-waiver is a 409
+     * (`ConflictError` on the app side) — surfaces here as a non-retryable
+     * `ApiError` with `status === 409` (see `BaseResource.request`).
+     */
+    async waive(input) {
+        return this.request("POST", "/admin/integrity/waivers", input);
+    }
+    /** PATCH /admin/integrity/waivers { waiver_id, revoke: true }. No un-revoke path. */
+    async revokeWaiver(waiverId) {
+        await this.request("PATCH", "/admin/integrity/waivers", { waiver_id: waiverId, revoke: true });
+    }
+}
 class AudioFilesResource extends BaseResource {
     async list(params) {
         const queryParams = new URLSearchParams();
@@ -1119,7 +1205,18 @@ class RecordingsResource extends BaseResource {
         return this.request("GET", `/admin/recordings/${id}`);
     }
     async create(data) {
-        return this.request("POST", "/admin/recordings", data);
+        // Spreadsheet-moment auto-twin — mirrors WorksResource.create above:
+        // fetch the full envelope so `twin`/`twin_error` survive onto the
+        // returned Recording instead of being dropped by `request()`'s
+        // `.data`-only narrowing.
+        const envelope = await this.requestWithEnvelope("POST", "/admin/recordings", data);
+        return {
+            ...envelope.data,
+            twin: envelope.twin ?? null,
+            ...(envelope.twin_error !== undefined && {
+                twin_error: envelope.twin_error,
+            }),
+        };
     }
     async update(id, updates) {
         return this.request("PATCH", `/admin/recordings/${id}`, updates);
@@ -3623,6 +3720,8 @@ export class PicaClient {
     shareSend;
     accessSimulate;
     approvals;
+    // Registration Integrity Floor (spec 2026-07-09, Task 8).
+    integrity;
     async catalogStats(params) {
         const baseUrl = this.works["baseUrl"];
         const apiKey = this.works["apiKey"];
@@ -3731,6 +3830,7 @@ export class PicaClient {
         this.shareSend = new ShareSendResource(baseUrl, config.apiKey, debug);
         this.accessSimulate = new AccessSimulateResource(baseUrl, config.apiKey, debug);
         this.approvals = new ApprovalsResource(baseUrl, config.apiKey, debug);
+        this.integrity = new IntegrityResource(baseUrl, config.apiKey, debug);
     }
 }
 //# sourceMappingURL=index.js.map