@withpica/mcp-sdk 4.0.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);
@@ -1143,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}` : ""}`);
     }
@@ -3504,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 ?? {});
@@ -3746,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`);
@@ -4848,6 +4921,7 @@ export class PicaClient {
     // ADR-232 — share trace aggregator + count explain registry +
     // audio pipeline status read.
     shareTrace;
+    songAccess;
     countExplain;
     audioPipelineStatus;
     publishers;
@@ -4965,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);