@withpica/mcp-sdk 3.18.0 → 3.20.0

package/CHANGELOG.md

@@ -11,6 +11,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`exports.songDossiers({ work_ids })`** — `POST /admin/exports/song-dossiers`.
+  One ZIP of the song dossier (PDF + JSON) for each work named, returned as the
+  signed-URL JSON envelope plus a per-work `works[]` account. 1 to 60 ids; a
+  malformed id or a longer list is a 400.
+
 ## [3.18.0] - 2026-09-17
 
 ### Removed

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;
@@ -1533,6 +1561,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 +1615,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 +1669,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 +1880,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 +1899,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 +2174,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;
@@ -2364,9 +2425,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
@@ -2476,11 +2589,11 @@ declare class SettingsResource extends BaseResource {
      * the auth context — `user_id` is never accepted (ADR-184 rule 2).
      *
      * The route lazy-creates the backing `people` row if the user's
-     * `user_profiles.person_id` is null, then fires
-     * `crossLinkOnIdentifierUpdate` so newly-visible cross-org credits
-     * appear on the next `pica_discoveries_query`. Response includes the
-     * count of new discoveries in each of the 3 typed tables so the
-     * agent can surface "found N more…" in the same conversation.
+     * `user_profiles.person_id` is null. Identifiers are saved on that record
+     * only; this call triggers no cross-org linking (a typed IPI is not
+     * evidence).
+     * Response includes the count of discoveries written in each of the 3
+     * typed tables in the last 10 seconds.
      * ADR-189 Phase 3.
      */
     updateMyIdentity(params: {
@@ -3271,6 +3384,16 @@ declare class ExportResource extends BaseResource {
         };
         work_ids?: string[];
     }): Promise<any>;
+    /**
+     * One ZIP holding the song dossier (PDF + JSON) of each work named — the
+     * work, its recordings, the releases they appear on, people, provenance and
+     * consent — plus a manifest and README. Returns a signed-URL JSON envelope
+     * with a per-work `works[]` account of what was included. 1–60 work ids;
+     * a malformed id or a longer list is refused with a 400.
+     */
+    songDossiers(params: {
+        work_ids: string[];
+    }): Promise<any>;
     aiConsent(params?: {
         work_ids?: string[];
     }): Promise<any>;
@@ -3558,6 +3681,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<{
@@ -4582,6 +4719,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;
@@ -4626,7 +4775,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;
     /**
@@ -4640,21 +4789,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 {