@withpica/mcp-sdk 3.4.0 → 3.6.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
@@ -312,6 +343,40 @@ class WorksResource extends BaseResource {
             qp.set("sort", params.sort);
         if (params.society_code)
             qp.set("society_code", params.society_code);
+        if (params.work_type)
+            qp.set("work_type", params.work_type);
+        if (params.work_status)
+            qp.set("work_status", params.work_status);
+        if (params.genre)
+            qp.set("genre", params.genre);
+        if (params.mood)
+            qp.set("mood", params.mood);
+        if (params.tempo_min !== undefined)
+            qp.set("tempo_min", String(params.tempo_min));
+        if (params.tempo_max !== undefined)
+            qp.set("tempo_max", String(params.tempo_max));
+        if (params.primary_artist)
+            qp.set("primary_artist", params.primary_artist);
+        if (params.artist)
+            qp.set("artist", params.artist);
+        if (params.label)
+            qp.set("label", params.label);
+        if (params.available_for_licensing !== undefined)
+            qp.set("available_for_licensing", String(params.available_for_licensing));
+        if (params.release_format)
+            qp.set("release_format", params.release_format);
+        if (params.is_featured !== undefined)
+            qp.set("is_featured", String(params.is_featured));
+        if (params.published !== undefined)
+            qp.set("published", String(params.published));
+        if (params.created_from)
+            qp.set("created_from", params.created_from);
+        if (params.created_to)
+            qp.set("created_to", params.created_to);
+        if (params.has_iswc !== undefined)
+            qp.set("has_iswc", String(params.has_iswc));
+        if (params.has_publisher !== undefined)
+            qp.set("has_publisher", String(params.has_publisher));
         const qs = qp.toString();
         return this.requestPaginated("GET", `/admin/works${qs ? `?${qs}` : ""}`);
     }
@@ -319,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);
@@ -409,6 +486,14 @@ class PeopleResource extends BaseResource {
             qp.set("record_kind", params.record_kind);
         if (params.outreach_state)
             qp.set("outreach_state", params.outreach_state);
+        if (params.has_email !== undefined)
+            qp.set("has_email", String(params.has_email));
+        if (params.has_phone !== undefined)
+            qp.set("has_phone", String(params.has_phone));
+        if (params.roles && params.roles.length > 0)
+            qp.set("roles", params.roles.join(","));
+        if (params.tags && params.tags.length > 0)
+            qp.set("tags", params.tags.join(","));
         const qs = qp.toString();
         return this.requestPaginated("GET", `/admin/people${qs ? `?${qs}` : ""}`);
     }
@@ -662,6 +747,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();
@@ -771,6 +887,18 @@ class AgreementsResource extends BaseResource {
             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)
@@ -1046,6 +1174,18 @@ class RecordingsResource extends BaseResource {
             qp.set("missing_field_count_gt", String(params.missing_field_count_gt));
         if (params.missing_field_count_lt !== undefined)
             qp.set("missing_field_count_lt", String(params.missing_field_count_lt));
+        if (params.has_isrc !== undefined)
+            qp.set("has_isrc", String(params.has_isrc));
+        if (params.version_type)
+            qp.set("version_type", params.version_type);
+        if (params.recorded_from)
+            qp.set("recorded_from", params.recorded_from);
+        if (params.recorded_to)
+            qp.set("recorded_to", params.recorded_to);
+        if (params.created_from)
+            qp.set("created_from", params.created_from);
+        if (params.created_to)
+            qp.set("created_to", params.created_to);
         const qs = qp.toString();
         return this.requestPaginated("GET", `/admin/recordings?${qs}`);
     }
@@ -1053,7 +1193,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);
@@ -2914,6 +3065,10 @@ class ReleasesResource extends BaseResource {
             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}`);
     }
@@ -3553,13 +3708,18 @@ export class PicaClient {
     shareSend;
     accessSimulate;
     approvals;
-    /**
-     * Get accurate catalog stats via SQL counts (no pagination limits)
-     */
-    async catalogStats() {
+    // Registration Integrity Floor (spec 2026-07-09, Task 8).
+    integrity;
+    async catalogStats(params) {
         const baseUrl = this.works["baseUrl"];
         const apiKey = this.works["apiKey"];
-        const res = await fetch(`${baseUrl}/admin/catalog/stats`, {
+        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",
@@ -3658,6 +3818,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