@withpica/mcp-sdk 3.28.0 → 4.0.0

package/CHANGELOG.md

@@ -11,6 +11,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -1132,6 +1132,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 +1347,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>;
@@ -2176,6 +2200,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";
@@ -2696,6 +2772,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 +2798,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 {
@@ -4774,7 +4863,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;
@@ -5865,7 +5968,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 +6162,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;
@@ -6234,6 +6342,7 @@ export declare class PicaClient {
     groups: GroupsResource;
     assistantInteractions: AssistantInteractionsResource;
     shareSend: ShareSendResource;
+    removed: RemovedResource;
     accessSimulate: AccessSimulateResource;
     approvals: ApprovalsResource;
     integrity: IntegrityResource;