@withpica/mcp-sdk 3.12.0 → 3.14.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}` : ""}`);
     }
@@ -2023,6 +2051,28 @@ class FeedbackResource extends BaseResource {
         return this.request("POST", "/feedback", params);
     }
 }
+class BillingResource extends BaseResource {
+    /**
+     * Mint a pay link for one offer. Minting is not charging: the link is a
+     * capability an agent POSTs with a Machine Payments credential, or a person
+     * opens in a browser and pays by card.
+     *
+     * Refusals arrive as `ApiError` carrying the route's status with its JSON
+     * body embedded in the message (the shape `duplicates.ts` and
+     * `integrity.ts` already parse): 403 `billing not enabled`; 400
+     * `nothing_held_for_entity` / `entity_id is required to unlock`; 409
+     * `offer_no_longer_applies`, whose body lists the offers that DO apply.
+     * A 403 can ALSO come from the auth wrapper in front of the route rather
+     * than the route itself (`{ error: { code: "INSUFFICIENT_SCOPE", … } }`),
+     * so status alone never identifies which refusal this is — read the body.
+     * They are deliberately not caught here — the MCP tool turns each into a
+     * structured refusal, and a resource that swallowed them would leave every
+     * other caller unable to tell a refusal from an outage.
+     */
+    async mintPayLink(params) {
+        return this.request("POST", "/admin/billing/pay-link", params);
+    }
+}
 class SubscriptionResource extends BaseResource {
     /**
      * Read the org's billing posture. Wraps the same
@@ -3397,8 +3447,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}`);
@@ -3922,6 +3977,8 @@ export class PicaClient {
     workflowOutcomes;
     feedback;
     subscription;
+    /** MPP pay rail (WS-B) — mints pay links; never charges. */
+    billing;
     opsIssues;
     discoveries;
     agentIdentity;
@@ -4034,6 +4091,7 @@ export class PicaClient {
         this.workflowOutcomes = new WorkflowOutcomesResource(baseUrl, config.apiKey, debug);
         this.feedback = new FeedbackResource(baseUrl, config.apiKey, debug);
         this.subscription = new SubscriptionResource(baseUrl, config.apiKey, debug);
+        this.billing = new BillingResource(baseUrl, config.apiKey, debug);
         this.opsIssues = new OpsIssuesResource(baseUrl, config.apiKey, debug);
         this.discoveries = new DiscoveriesResource(baseUrl, config.apiKey, debug);
         this.agentIdentity = new AgentIdentityResource(baseUrl, config.apiKey, debug);