@withpica/mcp-sdk 3.28.0 → 4.1.0

package/dist/index.js

@@ -147,6 +147,35 @@ export class EntityNotFoundError extends ApiError {
 function isRetryableStatus(status) {
     return status === 429 || status === 502 || status === 503 || status === 504;
 }
+/**
+ * A write (POST, PATCH) is resent only when the server said it did nothing:
+ * 429 and 503 are refusals before the route runs. A timeout, a dropped
+ * connection, a 502 or a 504 can each follow a write that DID happen, and
+ * resending it repeats the write. On prod 2026-10-29 a 94 s works create
+ * timed out at 30 s; the resend found the song the first attempt had just
+ * made and answered WORK_ALREADY_EXISTS naming it, and the agent then made by
+ * hand the recording the first attempt was still about to make (ops 198deea1).
+ * GET, PUT and DELETE are idempotent and keep every retry.
+ */
+function isWriteMethod(method) {
+    const m = (method ?? "GET").toUpperCase();
+    return m === "POST" || m === "PATCH";
+}
+function isRefusedBeforeRunning(status) {
+    return status === 429 || status === 503;
+}
+/**
+ * A write whose outcome is unknown: it timed out, lost its connection, or got
+ * a 502/504, and was not resent because it may have been applied. Look before
+ * trying again.
+ */
+export class WriteOutcomeUnknownError extends ApiError {
+    code = "WRITE_OUTCOME_UNKNOWN";
+    constructor(method, path, cause, status = 0) {
+        super(`${method} ${path} did not answer (${cause}). It may still have been applied, so it was not sent again: check whether it took effect (for example, query for what it creates) before retrying.`, status, false);
+        this.name = "WriteOutcomeUnknownError";
+    }
+}
 function getTimeoutForPath(path) {
     return LONG_TIMEOUT_PATTERNS.some((p) => path.includes(p))
         ? LONG_TIMEOUT_MS
@@ -255,6 +284,15 @@ class BaseResource {
     }
     async fetchWithRetry(url, init, timeoutMs) {
         let lastError;
+        const write = isWriteMethod(init.method);
+        const pathOf = () => {
+            try {
+                return new URL(url).pathname;
+            }
+            catch {
+                return url;
+            }
+        };
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
                 const response = await this.fetchWithTimeout(url, init, timeoutMs);
@@ -266,6 +304,12 @@ class BaseResource {
                 if (response.status === 401 || response.status === 403) {
                     throw new ApiError(`Authentication failed: ${response.status} ${errorText}`, response.status, false);
                 }
+                // A write that may have run is never resent (isWriteMethod).
+                if (write &&
+                    isRetryableStatus(response.status) &&
+                    !isRefusedBeforeRunning(response.status)) {
+                    throw new WriteOutcomeUnknownError(init.method ?? "POST", pathOf(), `${response.status} ${errorText.slice(0, 120)}`, response.status);
+                }
                 // Retryable errors — retry with backoff
                 if (isRetryableStatus(response.status) && attempt < MAX_RETRIES) {
                     const retryAfter = response.headers.get("retry-after");
@@ -291,6 +335,10 @@ class BaseResource {
             catch (err) {
                 if (err instanceof ApiError && !err.retryable)
                     throw err;
+                // Timed out or lost the connection: a write may have run.
+                if (write && !(err instanceof CatalogueNotHonouredError)) {
+                    throw new WriteOutcomeUnknownError(init.method ?? "POST", pathOf(), err.message);
+                }
                 lastError = err;
                 if (attempt < MAX_RETRIES) {
                     const delayMs = RETRY_BASE_MS * Math.pow(2, attempt);
@@ -577,6 +625,14 @@ class WorksResource extends BaseResource {
     async delete(id) {
         return this.request("DELETE", `/admin/works/${id}`);
     }
+    /**
+     * Bring back a removed song (removing never deletes one). 409 when a live
+     * song now holds its title and artist or its tunecode, or when it was
+     * merged into another song.
+     */
+    async restore(id) {
+        return this.request("POST", `/admin/works/${id}/restore`);
+    }
     /**
      * @deprecated `works` has no `is_verified` column, so PATCH /admin/works/[id]
      * refuses this body (VALIDATION_ERROR "unknown field 'is_verified'") on every
@@ -718,8 +774,18 @@ class PeopleResource extends BaseResource {
     async update(id, updates) {
         return this.request("PATCH", `/admin/people/${id}`, updates);
     }
-    async delete(id) {
-        await this.request("DELETE", `/admin/people/${id}`);
+    /**
+     * Remove a person. Someone who still has credits is refused (409
+     * PERSON_HOLDS_CREDITS, with what they hold) unless `moveTo` names the live
+     * person their credits move to; the removal is then a person merge.
+     */
+    async delete(id, opts = {}) {
+        const qs = opts.moveTo ? `?move_to=${encodeURIComponent(opts.moveTo)}` : "";
+        return this.request("DELETE", `/admin/people/${id}${qs}`);
+    }
+    /** Bring back a removed person. 409 when they were merged into another. */
+    async restore(id) {
+        return this.request("POST", `/admin/people/${id}/restore`);
     }
     async enrichFromISNI(id, isni) {
         return this.request("POST", `/admin/people/${id}/enrich/isni`, {
@@ -1125,6 +1191,8 @@ class AudioFilesResource extends BaseResource {
             queryParams.set("limit", String(params.limit));
         if (params?.offset)
             queryParams.set("offset", String(params.offset));
+        if (params?.cursor)
+            queryParams.set("cursor", params.cursor);
         const query = queryParams.toString();
         return this.request("GET", `/admin/audio-files${query ? `?${query}` : ""}`);
     }
@@ -1471,9 +1539,21 @@ class WorkspaceResource extends BaseResource {
         return this.request("GET", `/admin/events?limit=${limit || 20}`);
     }
 }
-// ---------------------------------------------------------------------------
-// ADR-231 — User-initiated asset sharing (creator MCP)
-// ---------------------------------------------------------------------------
+/** What has been removed from the catalogue and can be brought back. */
+class RemovedResource extends BaseResource {
+    /** One page of removed songs (the default) or people, newest changed first. */
+    async list(params = {}) {
+        const qp = new URLSearchParams();
+        if (params.kind)
+            qp.set("kind", params.kind);
+        if (params.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params.offset !== undefined)
+            qp.set("offset", String(params.offset));
+        const q = qp.toString();
+        return this.request("GET", `/admin/removed${q ? `?${q}` : ""}`);
+    }
+}
 class ShareSendResource extends BaseResource {
     async send(args) {
         return this.request("POST", "/mcp/share-send", args);
@@ -3474,20 +3554,30 @@ class UsersResource extends BaseResource {
     async getMyProfile() {
         return this.request("GET", "/admin/users/profile");
     }
+    /**
+     * Write your bio: the biography on your own person record (one bio per
+     * person). Refused 409 NO_LINKED_PERSON when your account has no person.
+     */
     async setBio(bio) {
-        return this.request("POST", "/admin/users/bio", {
-            bio,
-        });
+        return this.request("POST", "/admin/users/bio", { bio });
+    }
+    /**
+     * Settle a waiting `bio_choice`: "current" keeps your bio, "earlier" uses
+     * the earlier one. The text not kept goes to `set_aside_bios`, never
+     * deleted. Refused 409 NO_CHOICE_WAITING when nothing is waiting.
+     */
+    async chooseBio(keep) {
+        return this.request("POST", "/admin/users/bio", { choose: keep });
     }
     async setAvatarUrl(avatarUrl) {
         return this.request("POST", "/admin/users/avatar", { avatar_url: avatarUrl });
     }
     /**
-     * Copy `people.biography` into `user_profiles.bio`. Returns the new
-     * bio on success. On `would_overwrite` (existing bio + overwrite
-     * false), surfaces both the existing and proposed bios so the agent
-     * can present a yes/no to the user before re-calling with
-     * `overwrite: true`.
+     * @deprecated Retired: there is one bio now. Your profile bio IS the
+     * biography on your own person record, so there is nothing to import, and
+     * the server answers 410 RETIRED. Read the bio with `getMyProfile` and
+     * change it with `setBio`. Kept so an existing caller gets that message
+     * rather than a missing method; removed in the next major.
      */
     async importBioFromPerson(params) {
         return this.request("POST", "/admin/users/import-bio-from-person", params ?? {});
@@ -3716,6 +3806,19 @@ class ShareTraceResource extends BaseResource {
         return this.request("GET", `/admin/share-trace?${params.toString()}`);
     }
 }
+class SongAccessResource extends BaseResource {
+    /** GET /admin/works/{id}/access — who can see one of your songs. */
+    async list(workId) {
+        return this.request("GET", `/admin/works/${encodeURIComponent(workId)}/access`);
+    }
+    /**
+     * POST /admin/works/{id}/access — end one line. A removal that took
+     * nothing off throws (500 ACCESS_NOT_REMOVED).
+     */
+    async remove(workId, key) {
+        return this.request("POST", `/admin/works/${encodeURIComponent(workId)}/access`, { key });
+    }
+}
 class RecordingSplitsResource extends BaseResource {
     async list(recordingId) {
         return this.request("GET", `/admin/recordings/${recordingId}/splits`);
@@ -4508,7 +4611,8 @@ class ShareLinksResource extends BaseResource {
     }
     /**
      * Update a narrow subset of share-link fields (name, description,
-     * personal_message, expires_at, max_views, is_active, password).
+     * personal_message, expires_at, max_views, is_active, password,
+     * revoke_recipient_ids).
      * Permission-bearing fields are not updatable post-create — revoke
      * and recreate to change permissions.
      */
@@ -4817,6 +4921,7 @@ export class PicaClient {
     // ADR-232 — share trace aggregator + count explain registry +
     // audio pipeline status read.
     shareTrace;
+    songAccess;
     countExplain;
     audioPipelineStatus;
     publishers;
@@ -4861,6 +4966,7 @@ export class PicaClient {
     groups;
     assistantInteractions;
     shareSend;
+    removed;
     accessSimulate;
     approvals;
     // Registration Integrity Floor (spec 2026-07-09, Task 8).
@@ -4933,6 +5039,7 @@ export class PicaClient {
         this.recordingSplits = new RecordingSplitsResource(baseUrl, config.apiKey, debug);
         this.recordingCredits = new RecordingCreditsResource(baseUrl, config.apiKey, debug);
         this.shareTrace = new ShareTraceResource(baseUrl, config.apiKey, debug);
+        this.songAccess = new SongAccessResource(baseUrl, config.apiKey, debug);
         this.countExplain = new CountExplainResource(baseUrl, config.apiKey, debug);
         this.audioPipelineStatus = new AudioPipelineStatusResource(baseUrl, config.apiKey, debug);
         this.publishers = new PublishersResource(baseUrl, config.apiKey, debug);
@@ -4972,6 +5079,7 @@ export class PicaClient {
         this.groups = new GroupsResource(baseUrl, config.apiKey, debug);
         this.assistantInteractions = new AssistantInteractionsResource(baseUrl, config.apiKey, debug);
         this.shareSend = new ShareSendResource(baseUrl, config.apiKey, debug);
+        this.removed = new RemovedResource(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);