@withpica/mcp-sdk 3.13.0 → 3.15.0

package/dist/index.js

@@ -210,6 +210,12 @@ class BaseResource {
      * 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.
+     *
+     * `TRest` types any FURTHER siblings a specific route puts next to
+     * `data` (e.g. `POST /admin/multimedia/import-from-url` returns `via`,
+     * `source_url`, `profile_image`, `work_link`). It defaults to `unknown`,
+     * which is the identity for intersection, so the existing
+     * `requestWithEnvelope<Work>` call sites keep exactly the type they had.
      */
     async requestWithEnvelope(method, path, body) {
         const url = `${this.baseUrl}${path}`;
@@ -862,6 +868,8 @@ class AudioFilesResource extends BaseResource {
             queryParams.set("query", params.query);
         if (params?.limit !== undefined)
             queryParams.set("limit", String(params.limit));
+        if (params?.offset)
+            queryParams.set("offset", String(params.offset));
         const query = queryParams.toString();
         return this.request("GET", `/admin/audio-files${query ? `?${query}` : ""}`);
     }
@@ -955,7 +963,25 @@ class MultimediaResource extends BaseResource {
         return this.request("POST", "/admin/multimedia", data);
     }
     async importFromUrl(params) {
-        return this.request("POST", "/admin/multimedia/import-from-url", params);
+        // `request()` returns `data.data || data`, so it hands back ONLY the
+        // created row and drops every sibling field the route puts next to
+        // `data` — `via`, `source_url`, `profile_image`, `work_link`. Those
+        // are the receipts: without them pica_multimedia_import_url could say
+        // "imported" but never whether the person's profile image was set, or
+        // whether the URL was followed through an og:image. Read the envelope.
+        const envelope = await this.requestWithEnvelope("POST", "/admin/multimedia/import-from-url", params);
+        return {
+            item: envelope.data,
+            multimedia_id: envelope.multimedia_id,
+            s3_url: envelope.s3_url,
+            via: envelope.via,
+            source_url: envelope.source_url,
+            message: envelope.message,
+            ...(envelope.profile_image
+                ? { profile_image: envelope.profile_image }
+                : {}),
+            ...(envelope.work_link ? { work_link: envelope.work_link } : {}),
+        };
     }
     async linkYoutube(params) {
         return this.request("POST", "/admin/multimedia/link-youtube", params);
@@ -1208,6 +1234,8 @@ class NotesResource extends BaseResource {
             query.set("person", params.person);
         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/notes${qs ? `?${qs}` : ""}`);
     }
@@ -1719,6 +1747,8 @@ class HealthResource extends BaseResource {
     /**
      * ADR-273 — apply accepted fix actions from a prior plan. Requires planToken
      * from catalogHealthPlan; accept is a list of actionIds (or "all_safe_auto").
+     * `selections` carries the human choice a resolve_person action needs
+     * ({ actionId, chosenPersonId }); a selection also accepts its action.
      * Returns honest per-action met/unmet plus a fresh verdict.
      */
     async catalogHealthFix(body) {
@@ -3419,8 +3449,13 @@ class ReleasesResource extends BaseResource {
 }
 class SessionsResource extends BaseResource {
     async list(params) {
-        const qs = params?.limit ? `?limit=${params.limit}` : "";
-        return this.request("GET", `/admin/sessions${qs}`);
+        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}` : ""}`);
     }
     async get(id) {
         return this.request("GET", `/admin/sessions/${id}`);
@@ -3597,6 +3632,46 @@ class StatementsResource extends BaseResource {
         return this.request("POST", "/admin/statements/ingest-agent", payload);
     }
 }
+class SelectionsResource extends BaseResource {
+    async list(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));
+        const qs = qp.toString();
+        const result = await this.request("GET", `/admin/selections${qs ? `?${qs}` : ""}`);
+        return result.selections;
+    }
+    async create(data) {
+        const result = await this.request("POST", "/admin/selections", data);
+        return result.selection;
+    }
+    /**
+     * Per-id read. `resolve: true` also resolves the predicate — the route
+     * returns `{ selection, resolution }` instead of `{ selection }`, and
+     * `resolution` is omitted below when the caller didn't ask for it.
+     */
+    async inspect(id, opts) {
+        const qp = new URLSearchParams();
+        if (opts?.resolve)
+            qp.set("resolve", "true");
+        if (opts?.limit !== undefined)
+            qp.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            qp.set("offset", String(opts.offset));
+        const qs = qp.toString();
+        const result = await this.request("GET", `/admin/selections/${id}${qs ? `?${qs}` : ""}`);
+        return { selection: result.selection, resolution: result.resolution };
+    }
+    async update(id, data) {
+        const result = await this.request("PATCH", `/admin/selections/${id}`, data);
+        return result.selection;
+    }
+    async delete(id) {
+        await this.request("DELETE", `/admin/selections/${id}`);
+    }
+}
 class ShareLinksResource extends BaseResource {
     async list(params) {
         const qp = new URLSearchParams();
@@ -3929,6 +4004,8 @@ export class PicaClient {
     workForHire;
     royalties;
     statements;
+    /** ADR-319 — saved catalog selections. */
+    selections;
     shareLinks;
     consent;
     custody;
@@ -4043,6 +4120,7 @@ export class PicaClient {
         this.workForHire = new WorkForHireResource(baseUrl, config.apiKey, debug);
         this.royalties = new RoyaltiesResource(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);
         this.consent = new ConsentResource(baseUrl, config.apiKey, debug);
         this.custody = new CustodyResource(baseUrl, config.apiKey, debug);