@withpica/mcp-sdk 3.19.0 → 3.21.0

package/CHANGELOG.md

@@ -11,6 +11,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.21.0] - 2026-09-29
+
+### Added
+
+- `rights.propose(workId, body)`, `rights.status(ruleId)` and
+  `rights.inspect(workId)` — ADR-321 Phase 2, over
+  `POST /admin/works/{id}/rights/propose`, `GET /admin/rights/rules/{id}` and
+  `GET /admin/works/{id}/rights`.
+
+## [3.20.0] - 2026-09-26
+
+### Changed
+
+- Licensing enquiry `proposed_budget_amount` / `proposed_budget_currency` are
+  optional on input and nullable on the returned enquiry (no budget given).
+- `IdentifyResult` carries the flat ACRCloud identification the route actually
+  returns (`acrId`, `confidence`, `title`, `artist`, …); `match` is deprecated.
+- `listEnrichmentProposals` accepts `entity_type: "audio_file"`.
+
+### Added
+
+- `royalties.blockers(workId)` and `royalties.blockersCatalogue({ code, limit,
+offset })` — ADR-321 Phase 0, over `GET /admin/works/{id}/money-blockers` and
+  `GET /admin/money-blockers`.
+- **`health.getLowScoreWorksPage({ limit, offset, threshold })`** and
+  **`health.getWorksHealthPage({ limit, offset, unreconciledOnly })`** — the
+  paged health reads with the routes' `meta` (true `total` / scan progress).
+  The argument-less `getLowScoreWorks()` / `getWorksHealth()` are unchanged.
+- **`audioFiles.bulkUpdate(items, { dry_run })`** —
+  `POST /admin/audio-files/bulk-update`, lean per-item results.
+- **`audioFiles.list({ work_ids })`** — several works in one read.
+
 ## [3.19.0] - 2026-09-18
 
 ### Added

package/dist/index.d.ts

@@ -418,6 +418,32 @@ interface PicaScore {
     topActions: string[];
     calculatedAt: string;
 }
+/** One item of `audioFiles.bulkUpdate` — the fields pica_audio_update sets. */
+export interface AudioBulkUpdateItem {
+    id: string;
+    file_type?: "master" | "instrumental" | "stem" | "demo" | "version";
+    stem_label?: string | null;
+    version_label?: string | null;
+    title?: string;
+}
+export type AudioBulkUpdateItemResult = {
+    id: string;
+    status: "updated" | "would_update";
+    changed: Array<"file_type" | "stem_label" | "version_label" | "title">;
+} | {
+    id: string;
+    status: "failed";
+    reason: string;
+};
+/** Response of POST /admin/audio-files/bulk-update. */
+export interface AudioBulkUpdateResult {
+    dry_run: boolean;
+    requested: number;
+    /** Updated — or, on a dry run, would be updated. */
+    updated: number;
+    failed: number;
+    results: AudioBulkUpdateItemResult[];
+}
 /**
  * Outcome of a server-recomputed bulk attach of high-confidence orphan-audio
  * matches (POST /admin/audio-files/bulk-assign-suggested). Mirrors
@@ -762,8 +788,9 @@ interface LicenseEnquiryInput {
     territory: string;
     duration: string;
     distribution?: string[];
-    proposed_budget_amount: number;
-    proposed_budget_currency: string;
+    /** Optional since 2026-09-25; omit or null for no budget given. */
+    proposed_budget_amount?: number | null;
+    proposed_budget_currency?: string;
     budget_notes?: string;
 }
 interface LicenseEnquiry {
@@ -779,7 +806,8 @@ interface LicenseEnquiry {
     territory: string;
     duration: string;
     distribution: string[] | null;
-    proposed_budget_amount: number;
+    /** NULL = no budget given. */
+    proposed_budget_amount: number | null;
     proposed_budget_currency: string;
     budget_notes: string | null;
     status: string;
@@ -997,6 +1025,13 @@ declare class WorksResource extends BaseResource {
     }): Promise<Work>;
     update(id: string, updates: Partial<Work>): Promise<Work>;
     delete(id: string): Promise<DeletionResult>;
+    /**
+     * @deprecated `works` has no `is_verified` column, so PATCH /admin/works/[id]
+     * refuses this body (VALIDATION_ERROR "unknown field 'is_verified'") on every
+     * call. PICA keeps no work-level verified flag; the MCP tool
+     * `pica_works_verify` no longer calls this. Kept only so the published SDK's
+     * surface does not break; remove at the next major.
+     */
     verify(id: string): Promise<Work>;
     bulkDelete(ids: string[]): Promise<void>;
     bulkMoveToPerformances(ids: string[]): Promise<unknown>;
@@ -1533,6 +1568,22 @@ interface IdentifyResult {
     alreadyIdentified?: boolean;
     audioFileId?: string;
     message?: string;
+    acrId?: string | null;
+    confidence?: number | null;
+    title?: string | null;
+    artist?: string | null;
+    album?: string | null;
+    label?: string | null;
+    releaseDate?: string | null;
+    externalIds?: {
+        isrc?: string[];
+        upc?: string[];
+        iswc?: string[];
+    } | null;
+    /**
+     * @deprecated Never sent by the route — kept only so existing consumers
+     * still compile. Read the flat fields above.
+     */
     match?: {
         title?: string;
         artist?: string;
@@ -1571,6 +1622,8 @@ export interface AudioFileTranscript {
 declare class AudioFilesResource extends BaseResource {
     list(params?: {
         work_id?: string;
+        /** Several works at once, sent comma-separated (route caps the count). */
+        work_ids?: string[];
         file_type?: string;
         unprocessed?: boolean;
         unassigned?: boolean;
@@ -1623,6 +1676,15 @@ declare class AudioFilesResource extends BaseResource {
         version_label?: string | null;
         title?: string;
     }): Promise<AudioFile>;
+    /**
+     * Per-file metadata patches for up to 200 files in one request (ops issue
+     * 5c53049a). Returns one lean result per item — `updated`, `would_update`
+     * (dry run) or `failed` with a reason — never the rows. Wraps
+     * POST /admin/audio-files/bulk-update.
+     */
+    bulkUpdate(items: AudioBulkUpdateItem[], params?: {
+        dry_run?: boolean;
+    }): Promise<AudioBulkUpdateResult>;
     analyze(id: string, options?: {
         forceReAnalyze?: boolean;
         enableAudio?: boolean;
@@ -1825,7 +1887,12 @@ declare class WorkspaceResource extends BaseResource {
 declare class ShareSendResource extends BaseResource {
     send(args: {
         entity_type: "recording" | "work" | "audio_file" | "document";
-        entity_id: string;
+        /** one work. Give this OR entity_ids. */
+        entity_id?: string;
+        /** several works → one link, one email, in this order. */
+        entity_ids?: string[];
+        /** show split percentages to the recipient (default false). */
+        include_splits?: boolean;
         recipient: {
             kind: "user_id" | "collaborator_id" | "email";
             value: string;
@@ -1839,6 +1906,7 @@ declare class ShareSendResource extends BaseResource {
         send_id: string;
         share_link_id: string;
         share_url: string;
+        work_ids: string[];
         recipient_resolution: {
             classification: "internal_user" | "internal_contact" | "external";
             display_name: string | null;
@@ -2113,7 +2181,7 @@ declare class EnrichmentResource extends BaseResource {
      * for filtering by confidence band and recency.
      */
     listEnrichmentProposals(params?: {
-        entity_type?: "work" | "person" | "recording";
+        entity_type?: "work" | "person" | "recording" | "audio_file";
         entity_id?: string;
         rule_id?: string;
         source?: string;
@@ -2145,10 +2213,17 @@ declare class EnrichmentResource extends BaseResource {
      * `artist_title_to_youtube` recording-create), a uniqueness check
      * runs instead; conflicts return `{ status: 'create_conflict' }` and
      * cannot be forced.
+     *
+     * File-type questions (`entity_type: 'audio_file'`) take the owner's own
+     * answer: `file_type` (master / version / instrumental / demo / stem) and,
+     * for a stem, an optional `stem_label`. A refused answer is a 400 with
+     * `code: 'INVALID_FILE_TYPE_ANSWER'`.
      */
     applyEnrichmentProposal(proposalId: string, options?: {
         force?: boolean;
         resolution_note?: string;
+        file_type?: "master" | "version" | "instrumental" | "demo" | "stem";
+        stem_label?: string;
     }): Promise<any>;
     /**
      * Reject a pending proposal. Content-hash suppression (ADR-163)
@@ -2364,9 +2439,61 @@ export interface CatalogHealthFixResult {
     verdict: unknown;
     outcomesRecorded: number;
 }
+/** `meta` of GET /admin/quality/completeness/low-score. */
+export interface LowScoreWorksPageMeta {
+    threshold: number;
+    limit: number;
+    offset: number;
+    count: number;
+    /** Works below the threshold by the cached score; null when unknown. */
+    total: number | null;
+    has_more: boolean | null;
+}
+/** `meta` of GET /admin/quality/works-health. */
+export interface WorksHealthPageMeta {
+    limit: number;
+    offset: number;
+    unreconciled_only: boolean;
+    count: number;
+    /** Candidate works assembled by this call. */
+    scanned: number;
+    /** Live works with a canonical node; null when unknown. */
+    candidates_total: number | null;
+    has_more: boolean;
+    next_offset: number | null;
+}
 declare class HealthResource extends BaseResource {
     getWorksHealth(): Promise<any>;
     getLowScoreWorks(): Promise<any>;
+    /**
+     * One page of works below a completeness threshold, with the route's
+     * `meta` (true `total` below the threshold, `has_more`). Backs
+     * `pica_works_query {health_filter: "low_completeness"}` — the bare
+     * `getLowScoreWorks()` above sends no limit/offset, so the tool used to
+     * ignore both (ops issue 314325eb).
+     */
+    getLowScoreWorksPage(params: {
+        limit?: number;
+        offset?: number;
+        threshold?: number;
+    }): Promise<{
+        data: any[];
+        meta?: LowScoreWorksPageMeta;
+    }>;
+    /**
+     * One page of the cross-org reconciliation scan, with the route's `meta`
+     * (`scanned`, `candidates_total`, `next_offset`). `offset`/`limit` page the
+     * candidate works, not the returned rows — see the route. Backs
+     * `pica_works_query {health_filter: "needs_attention"}`.
+     */
+    getWorksHealthPage(params: {
+        limit?: number;
+        offset?: number;
+        unreconciledOnly?: boolean;
+    }): Promise<{
+        data: any[];
+        meta?: WorksHealthPageMeta;
+    }>;
     getWorkCompleteness(workId: string): Promise<any>;
     /**
      * ADR-277 WS2 — opt-in per-field provenance for a work: one entry per
@@ -3568,6 +3695,20 @@ declare class ImportResource extends BaseResource {
             existingTitle: string;
             matchType: string;
         }>;
+        /**
+         * Same title as a work under a different (or no recorded) artist. These
+         * tracks stay in `newTracks`; optional because an older server omits it.
+         */
+        possibleMatches?: Array<{
+            track: {
+                title: string;
+                externalId: string;
+            };
+            existingWorkId: string;
+            existingTitle: string;
+            existingArtist: string | null;
+            reason: string;
+        }>;
         newTracks: Array<{
             title: string;
             artists: Array<{
@@ -4570,6 +4711,24 @@ declare class WorkForHireResource extends BaseResource {
     update(id: string, data: Record<string, any>): Promise<any>;
     delete(id: string): Promise<void>;
 }
+/**
+ * ADR-321 Phase 2 — programmable rights. `propose` only proposes: the route
+ * never activates a rule on an API key, and each party confirms by email.
+ */
+declare class RightsResource extends BaseResource {
+    /**
+     * POST /admin/works/{id}/rights/propose. Body is one of
+     * `{ rule: "song" }`, `{ rule: "master", recording_id }` or
+     * `{ rule: "share", side?, recording_id?, subject_person_id, kind,
+     * parties: [{ person_id, share_bp }], effective_from, effective_to? }`.
+     * A refusal is a 422 carrying `details.reasons`.
+     */
+    propose(workId: string, body: Record<string, unknown>): Promise<any>;
+    /** GET /admin/rights/rules/{id} — one rule's status and confirmations. */
+    status(ruleId: string): Promise<any>;
+    /** GET /admin/works/{id}/rights — every rule on a song, history, holds. */
+    inspect(workId: string): Promise<any>;
+}
 declare class RoyaltiesResource extends BaseResource {
     payments(params?: {
         source?: string;
@@ -4592,6 +4751,18 @@ declare class RoyaltiesResource extends BaseResource {
         workId?: string;
         limit?: number;
     }): Promise<any[]>;
+    /**
+     * ADR-321 Phase 0 — what in one song's record is likely holding up its
+     * society income. `state` is "clear" only when every area was checked;
+     * `unchecked` lists areas that could not be.
+     */
+    blockers(workId: string): Promise<any>;
+    /** ADR-321 Phase 0 — the catalogue roll-up: summary + songs not clear, paged. */
+    blockersCatalogue(params?: {
+        code?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
     stats(): Promise<any>;
     unmatched(opts?: {
         importBatchId?: string;
@@ -4636,7 +4807,7 @@ declare class StatementsResource extends BaseResource {
  * with `substrate_rows === 0` on a clause means "PICA does not know", not
  * "there are none" — the never-invent rule applied to a selection.
  */
-export type SubstrateUnit = "works" | "credit_rows" | "audio_analysis_rows";
+export type SubstrateUnit = "works" | "credit_rows" | "audio_analysis_rows" | "audio_files";
 export interface CoverageEntry {
     clause: string;
     /**
@@ -4650,21 +4821,49 @@ export interface CoverageEntry {
     substrate_rows: number;
     /**
      * What `substrate_rows` counted. NOT the same unit as `org_rows`, which is
-     * always works: a role clause counts credits and a trait clause counts
-     * audio analyses, so the two numbers are not two halves of one fraction.
+     * always works: a role clause counts credits, a trait clause counts audio
+     * analyses and a has_audio clause counts attached audio files, so the two
+     * numbers are not two halves of one fraction.
      */
     substrate_unit: SubstrateUnit;
     org_rows: number;
 }
+/**
+ * @deprecated Never populated — `SelectionMember.playable` was always null
+ * while it carried this type. It is now {@link MemberPlayable}.
+ */
 export interface PlayableRef {
     source: "spotify" | "youtube" | "apple" | "audio_file";
     ref: string;
 }
+/** One of a work's audio files other than its primary, in lean form. */
+export interface AudioVersionRef {
+    audio_file_id: string;
+    /** master / version / demo / instrumental / stem */
+    file_type: string;
+    /** stem label, else version label, else filename */
+    label: string;
+}
+/**
+ * What a selection member plays: its primary audio file (the master when it
+ * has one — `is_master` false means a fallback pick) plus every other audio
+ * file on the work, so a renderer can offer master, PA and stems as one
+ * bundle. Null exactly when the work has no audio file. Owned audio only —
+ * streaming pointers are not resolved into a member yet.
+ */
+export interface MemberPlayable {
+    audio_file_id: string;
+    file_type: string;
+    duration_seconds: number | null;
+    label: string;
+    is_master: boolean;
+    versions: AudioVersionRef[];
+}
 export interface SelectionMember {
     work_id: string;
     title: string;
     primary_artist: string | null;
-    playable: PlayableRef | null;
+    playable: MemberPlayable | null;
     has_lyrics: boolean;
 }
 export interface ResolveResult {
@@ -5045,6 +5244,8 @@ export declare class PicaClient {
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;
     royalties: RoyaltiesResource;
+    /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
+    rights: RightsResource;
     statements: StatementsResource;
     /** ADR-319 — saved catalog selections. */
     selections: SelectionsResource;