@withpica/mcp-sdk 3.28.0 → 4.1.0

package/CHANGELOG.md

@@ -11,6 +11,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,
+> then `@withpica/mcp-server` 2.110.0 (which calls `people.restore` and `removed.list`, so it needs
+> this version), then `@withpica/mcp-server-directory` 1.9.0.
+
+### Changed
+
+- **Breaking:** `AccessSimulateShareLinkConfig.access_type` is now
+  `"anyone" | "specific_people" | "collaborators_only"`, the share_links words,
+  instead of `"private" | "limited" | "public"`. Until this release the server
+  accepted the old words (`pica_access_simulate` listed them); it now refuses
+  them as an input error, so a caller still sending them must switch.
+
+### Added
+
+- `CatalogHealthVerdict.recordings`: each kind of recording present (`CatalogHealthRecordingKind`:
+  `released_master`, `unreleased_master`, `demo`, `alternate`, `video`) with `label`, `total` and
+  `missingFields`, or `null` when the check could not run. `CatalogHealthItem.recordingKind` on
+  `missing_recording_fields` items (one item per kind). Type only: `health.catalogHealth()`
+  already returns what the server sends.
+- `ShareTraceReason.audience` may be `"song_collaborators"` (a
+  collaborators-only link: a signed-in account credited on the song).
+- `ShareTraceReason.audience` may be `"named_recipients"` (a specific-people
+  link), with `recipients: [{ recipient_id, email, person_id, view_count,
+last_viewed_at }]`.
+- `ShareTraceReason` share-link fields: `audience: "anyone_with_the_link"`,
+  `view_count`, `max_views`, `password_protected`. Every live link to a song is
+  now reported for any viewer.
+- `works.restore(id)` and `people.restore(id)`: bring back a removed song or person
+  (`POST /admin/works/{id}/restore`, `/admin/people/{id}/restore`). Removing a song or a person
+  never deletes it. 409 when a live song now holds its title and artist or tunecode, or when the
+  record was merged into another.
+- `removed.list({ kind?, limit?, offset? })` → `RemovedList` (`kind`, `total`, `totals`,
+  `items: RemovedItem[]`, `next_offset`): one page of the songs (default) or people removed from
+  the catalogue, with when, by whom and why (`GET /admin/removed`).
+- `RemovedItem.holds`: for a removed person, the song credits, song artist credits, recording
+  credits, recording splits in force, agreement parties and main-artist songs/recordings that
+  still sit with them; `null` for a song.
+
 ## [3.28.0] - 2026-10-19
 
 > **Publish order:** this package first, then `@withpica/mcp-server` 2.109.0, which calls

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;
@@ -1132,6 +1148,14 @@ declare class WorksResource extends BaseResource {
     }): Promise<Work>;
     update(id: string, updates: Partial<Work>): Promise<Work>;
     delete(id: string): Promise<DeletionResult>;
+    /**
+     * 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.
+     */
+    restore(id: string): Promise<{
+        success: boolean;
+    }>;
     /**
      * @deprecated `works` has no `is_verified` column, so PATCH /admin/works/[id]
      * refuses this body (VALIDATION_ERROR "unknown field 'is_verified'") on every
@@ -1339,7 +1363,23 @@ declare class PeopleResource extends BaseResource {
     get(id: string): Promise<Person>;
     create(data: Partial<Person>): Promise<Person>;
     update(id: string, updates: Partial<Person>): Promise<Person>;
-    delete(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    delete(id: string, opts?: {
+        moveTo?: string;
+    }): Promise<{
+        moved_to?: {
+            id: string;
+            name: string;
+        };
+    }>;
+    /** Bring back a removed person. 409 when they were merged into another. */
+    restore(id: string): Promise<{
+        success: boolean;
+    }>;
     enrichFromISNI(id: string, isni: string): Promise<Person>;
     enrichFromMusicBrainz(id: string, musicbrainz_id: string): Promise<Person>;
     bulkDelete(ids: string[]): Promise<unknown>;
@@ -1856,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>;
     /**
@@ -2026,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>;
     /**
@@ -2176,6 +2226,58 @@ declare class WorkspaceResource extends BaseResource {
         }>;
     }>;
 }
+/** One removed song or person, as GET /admin/removed answers. */
+export interface RemovedItem {
+    kind: "song" | "person";
+    id: string;
+    name: string;
+    removed_at: string | null;
+    /** "you" is never said here: a person's or agent's name, or null. */
+    removed_by: string | null;
+    /** Set when a song was moved to performances or linked to a shared song. */
+    why: {
+        kind: "moved_to_performance" | "linked_to_shared";
+        title: string;
+    } | null;
+    /**
+     * For a person: what they still hold in the live catalogue, which stays
+     * with them while removed. Null for a song.
+     */
+    holds: {
+        song_credits: number;
+        song_artist_credits: number;
+        recording_credits: number;
+        /** Recording splits of every type still in force. */
+        recording_splits: number;
+        /** Agreements they are a party to. */
+        agreements: number;
+        main_artist_songs: number;
+        main_artist_recordings: number;
+        total: number;
+    } | null;
+}
+export interface RemovedList {
+    kind: "song" | "person";
+    /** How many of this kind are removed. */
+    total: number;
+    /** How many of each kind are removed. */
+    totals: {
+        songs: number;
+        people: number;
+    };
+    items: RemovedItem[];
+    /** The offset of the next page, or null on the last. */
+    next_offset: number | null;
+}
+/** What has been removed from the catalogue and can be brought back. */
+declare class RemovedResource extends BaseResource {
+    /** One page of removed songs (the default) or people, newest changed first. */
+    list(params?: {
+        kind?: "song" | "person";
+        limit?: number;
+        offset?: number;
+    }): Promise<RemovedList>;
+}
 declare class ShareSendResource extends BaseResource {
     send(args: {
         entity_type: "recording" | "work" | "audio_file" | "document";
@@ -2194,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[];
@@ -2696,6 +2802,17 @@ export interface CatalogHealthItem {
     truncated: boolean;
     needsScope: string | null;
     actionableByCaller: boolean;
+    /** On missing_recording_fields: which kind of recording the item counts (one item per kind). */
+    recordingKind?: CatalogHealthRecordingKind;
+}
+/** Mirrors lib/services/recording-kind.ts — a master is "released" only when it is on a release. */
+export type CatalogHealthRecordingKind = "released_master" | "unreleased_master" | "demo" | "alternate" | "video";
+export interface CatalogHealthRecordingKindLine {
+    kind: CatalogHealthRecordingKind;
+    /** Say this: "demos", "released masters". */
+    label: string;
+    total: number;
+    missingFields: number;
 }
 export interface CatalogHealthVerdict {
     score: number | null;
@@ -2711,6 +2828,8 @@ export interface CatalogHealthVerdict {
     assessed: string[];
     notAssessed: string[];
     items: CatalogHealthItem[];
+    /** Recordings by kind (only kinds present); null when the check could not run. */
+    recordings: CatalogHealthRecordingKindLine[] | null;
     generatedAt: string;
 }
 export interface CatalogHealthPlanAction {
@@ -4551,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;
@@ -4573,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;
@@ -4699,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. */
@@ -4774,7 +4924,21 @@ export interface ShareTraceReason {
         territory: string;
     }>;
     share_link_id?: string;
+    /** 'anyone' links open for anyone with the URL; specific-people links
+     *  only through their named recipients' own URLs; collaborators-only
+     *  links only for a signed-in account credited on the song */
+    audience?: "anyone_with_the_link" | "named_recipients" | "song_collaborators";
+    recipients?: Array<{
+        recipient_id: string;
+        email: string | null;
+        person_id: string | null;
+        view_count: number;
+        last_viewed_at: string | null;
+    }>;
     expires_at?: string | null;
+    view_count?: number;
+    max_views?: number | null;
+    password_protected?: boolean;
     grant_id?: string;
     scope?: string[];
     granted_at?: string | null;
@@ -4887,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>;
@@ -5865,7 +6063,8 @@ declare class ShareLinksResource extends BaseResource {
     get(id: string): Promise<any>;
     /**
      * 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.
      */
@@ -6058,7 +6257,11 @@ export type AccessSimulateEntityType = "work" | "recording" | "person" | "releas
 export type AccessSimulateAction = "view" | "share_link_preview" | "claim" | "grant";
 export type AccessSimulateRecipientType = "user" | "anonymous" | "share_link";
 export interface AccessSimulateShareLinkConfig {
-    access_type: "private" | "limited" | "public";
+    /** The share_links vocabulary. 'anyone': anyone with its URL.
+     *  'specific_people': only the recipients in the two lists below, each
+     *  through their own URL. 'collaborators_only': a signed-in account
+     *  credited on the link's one song. */
+    access_type: "anyone" | "specific_people" | "collaborators_only";
     allow_download?: boolean;
     allow_streaming?: boolean;
     allow_comments?: boolean;
@@ -6190,6 +6393,7 @@ export declare class PicaClient {
     recordingSplits: RecordingSplitsResource;
     recordingCredits: RecordingCreditsResource;
     shareTrace: ShareTraceResource;
+    songAccess: SongAccessResource;
     countExplain: CountExplainResource;
     audioPipelineStatus: AudioPipelineStatusResource;
     publishers: PublishersResource;
@@ -6234,6 +6438,7 @@ export declare class PicaClient {
     groups: GroupsResource;
     assistantInteractions: AssistantInteractionsResource;
     shareSend: ShareSendResource;
+    removed: RemovedResource;
     accessSimulate: AccessSimulateResource;
     approvals: ApprovalsResource;
     integrity: IntegrityResource;