@withpica/mcp-sdk 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -11,6 +11,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-10-31
+
+### Added
+
+- `statements.removeImport(importBatchId)`: removes an imported statement — its royalty lines and
+  payment total go in one transaction; an uploaded statement document it came from stays. Returns
+  `{ paymentsDeleted, royaltyPaymentsDeleted }`. Refused (409 `IMPORT_RUNNING`) while the statement
+  is still importing. Backs `pica_statement_import_remove` in `@withpica/mcp-server` 2.113.0.
+
+## [4.1.0] - 2026-10-29
+
+### Changed
+
+- **A write that may have run is never sent twice** (#3391). A POST or PATCH is resent only on 429
+  or 503, refusals before the route runs. A timeout, a dropped connection, a 502 or a 504 now throws
+  `WriteOutcomeUnknownError` (`code: "WRITE_OUTCOME_UNKNOWN"`) instead of resending: a 94 s works
+  create on prod was resent at the 30 s timeout and answered `WORK_ALREADY_EXISTS` naming the song
+  its first attempt had made. GET, PUT and DELETE keep every retry.
+
+- `credits.listCollaborators(workId)`: `verified` and `split_status` are each collaborator's own
+  confirmation (`split_status` is `attested`, `pending`, `disputed` or `declined`; `verified` is
+  true only when every one of their credits on the work is attested). Both used to say "verified"
+  for everyone.
+
+### Deprecated
+
+- `is_owner` on `credits.listCollaborators(workId)` entries. The server no longer sends it, so a
+  reader gets `undefined`. It was `true` for every entry and did not reflect the credit (the same
+  field `pica_credits_list` dropped in mcp-server 2.107.0). The type keeps it optional, so 4.x code
+  that reads it still compiles; it is removed in the next major.
+
+- `isrc_source` on `recordings.create` / `recordings.update` (and works writes): ignored by the
+  server, which records where an ISRC came from; the response's `warnings` says so.
+
+### Added
+
+- `shareSend.send` takes `share_link_id` (email an existing link).
+- `recordingCredits.bulkUpdate`: each credit takes `instrument`, applied on every target recording.
+- `audioFiles.list({ cursor })` (#3392): start after a previous page's `pagination.next_cursor`
+  instead of at `offset`; a file uploaded during the walk no longer shifts the pages.
+
+### One bio per person
+
+- `users.getMyProfile()` adds `bio_short`, `bio_confirmed`, `bio_choice: MyProfileBioChoice | null` and `set_aside_bios: MyProfileSetAsideBio[]`. `bio` is now the biography on the caller's own person record.
+- `users.setBio()` returns `{ bio, person_id }`. New `users.chooseBio("current" | "earlier")`.
+- `users.importBioFromPerson()` is **deprecated**. The server answers 410 RETIRED, and the method will be removed in the next major.
+
 ## [4.0.0] - 2026-10-23
 
 > **Major** for one breaking change, below. Publish this first, then `@withpica/mcp-utils` 2.0.1,

package/dist/index.d.ts

@@ -398,8 +398,15 @@ interface WorkCredit {
     splits: number;
     person_name?: string;
     ipi?: string;
+    /** True only when every one of the person's credits on the work is attested. */
     verified?: boolean;
+    /** attested | pending | disputed | declined (work_collaborators.attestation_status). */
     split_status?: string;
+    /**
+     * @deprecated No longer sent: it was `true` for every entry and did not
+     * reflect the credit. Kept optional so 4.x readers still compile; removed in
+     * the next major.
+     */
     is_owner?: boolean;
 }
 /** One credit row on a work, from GET /admin/works/:id/credits?view=rows. */
@@ -987,6 +994,15 @@ export interface DeletionResult {
 export declare class EntityNotFoundError extends ApiError {
     constructor(message: string);
 }
+/**
+ * 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 declare class WriteOutcomeUnknownError extends ApiError {
+    readonly code = "WRITE_OUTCOME_UNKNOWN";
+    constructor(method: string, path: string, cause: string, status?: number);
+}
 declare class BaseResource {
     protected baseUrl: string;
     protected apiKey: string;
@@ -1880,6 +1896,8 @@ declare class AudioFilesResource extends BaseResource {
         query?: string;
         limit?: number;
         offset?: number;
+        /** Start after a previous page's `pagination.next_cursor`, instead of at offset. */
+        cursor?: string;
     }): Promise<AudioFile[]>;
     get(id: string): Promise<AudioFile>;
     /**
@@ -2050,6 +2068,14 @@ declare class AgreementsResource extends BaseResource {
         agreement: Agreement;
         signatureStatus: unknown;
         linkedWorks: unknown[];
+        /** Documents linked to the agreement; null when the server could not read them. */
+        linkedDocuments?: Array<{
+            id: string;
+            title: string | null;
+            filename: string | null;
+            category: string | null;
+            created_at: string | null;
+        }> | null;
     }>;
     create(data: Partial<Agreement>): Promise<Agreement>;
     /**
@@ -2270,8 +2296,12 @@ declare class ShareSendResource extends BaseResource {
         scope?: "view" | "view+download";
         confirm_first_external_send?: boolean;
         included_file_ids?: string[];
+        /** email this existing share link instead of making one (its settings stand) */
+        share_link_id?: string;
     }): Promise<{
         send_id: string;
+        /** "failed" means Postmark took no email (the share_sends row says why) */
+        delivery: "sent" | "failed";
         share_link_id: string;
         share_url: string;
         work_ids: string[];
@@ -4640,20 +4670,38 @@ declare class UsersResource extends BaseResource {
         handle_accepts_invites: boolean;
         avatar_url: string | null;
         bio: string | null;
+        bio_short: string | null;
+        bio_confirmed: boolean;
+        bio_choice: MyProfileBioChoice | null;
+        set_aside_bios: MyProfileSetAsideBio[];
         linked_person_id: string | null;
     }>;
+    /**
+     * 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.
+     */
     setBio(bio: string | null): Promise<{
         bio: string | null;
+        person_id: string;
+    }>;
+    /**
+     * 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.
+     */
+    chooseBio(keep: "current" | "earlier"): Promise<{
+        bio: string | null;
+        person_id: string;
     }>;
     setAvatarUrl(avatarUrl: string | null): Promise<{
         avatar_url: string | null;
     }>;
     /**
-     * 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.
      */
     importBioFromPerson(params?: {
         overwrite?: boolean;
@@ -4662,6 +4710,17 @@ declare class UsersResource extends BaseResource {
         bio?: string;
     }>;
 }
+/** An earlier bio waiting for you to choose (see `UsersResource.chooseBio`). */
+export interface MyProfileBioChoice {
+    id: string;
+    earlier_bio: string;
+}
+/** An earlier bio kept after a choice. */
+export interface MyProfileSetAsideBio {
+    id: string;
+    bio: string;
+    created_at: string;
+}
 interface DirectorySettings {
     organisation_id: string;
     opted_in: boolean;
@@ -4788,6 +4847,8 @@ export interface RecordingCreditsBulkCreditInput {
     split_type?: string | null;
     display_order?: number;
     notes?: string | null;
+    /** Instrument(s) for this credit, applied on every target recording. */
+    instrument?: string | null;
 }
 export interface RecordingCreditsBulkUpdateInput {
     /** Target every recording on this release. Exactly one of release_id / recording_ids. */
@@ -4990,6 +5051,40 @@ declare class ShareTraceResource extends BaseResource {
      */
     trace(query: ShareTraceQuery): Promise<ShareTraceResult>;
 }
+/** One line of "who has access" to a song (ADR-346 part 5b). */
+export interface SongAccessLine {
+    /** Opaque; pass back to remove. */
+    key: string;
+    granteeOrgName: string | null;
+    /** The address a share waits on, when nobody has accepted yet. */
+    pendingEmail: string | null;
+    /** "both" is a legacy share written with no side. */
+    side: "composition" | "master" | "both";
+    /** For a master line: the one recording it covers. */
+    recordingTitle: string | null;
+    status: "active" | "pending";
+    /** "look_after_master": they can also edit this master (2b-1). */
+    canDo: "view" | "look_after_master";
+    /** Part of a wider arrangement: change it from people & access, not here. */
+    widerArrangement: boolean;
+}
+export interface SongAccessRemoval {
+    removed: number;
+    failed: number;
+    /** True when they can still see the song: say so and offer a retry. */
+    still_shared: boolean;
+    /** Set when a wider arrangement was kept, so they can still edit. */
+    kept_reason: string | null;
+}
+declare class SongAccessResource extends BaseResource {
+    /** GET /admin/works/{id}/access — who can see one of your songs. */
+    list(workId: string): Promise<SongAccessLine[]>;
+    /**
+     * POST /admin/works/{id}/access — end one line. A removal that took
+     * nothing off throws (500 ACCESS_NOT_REMOVED).
+     */
+    remove(workId: string, key: string): Promise<SongAccessRemoval>;
+}
 /** Siblings of `data` on the recording split edit / end responses. */
 export interface RecordingSplitEditEnvelope {
     previous?: Record<string, any>;
@@ -5828,6 +5923,15 @@ declare class StatementsResource extends BaseResource {
         document_id?: string;
     }): Promise<Record<string, unknown>>;
     getImport(id: string): Promise<Record<string, unknown>>;
+    /**
+     * Remove an imported statement: its royalty lines and payment total go
+     * (one transaction); an uploaded statement document it came from stays.
+     * Refused (409 IMPORT_RUNNING) while it is still importing.
+     */
+    removeImport(importBatchId: string): Promise<{
+        paymentsDeleted: number;
+        royaltyPaymentsDeleted: number;
+    }>;
 }
 /**
  * ADR-319 — saved catalog selections. `mcp-sdk` is a standalone published
@@ -6298,6 +6402,7 @@ export declare class PicaClient {
     recordingSplits: RecordingSplitsResource;
     recordingCredits: RecordingCreditsResource;
     shareTrace: ShareTraceResource;
+    songAccess: SongAccessResource;
     countExplain: CountExplainResource;
     audioPipelineStatus: AudioPipelineStatusResource;
     publishers: PublishersResource;