@withpica/mcp-sdk 1.3.0 → 1.7.0

package/dist/index.d.ts

@@ -2,6 +2,107 @@
  * Lightweight PICA SDK client for MCP server
  * Uses the PICA API directly without external dependencies
  */
+/**
+ * ADR-179 resolver result shape. Mirrors the server-side
+ * `ResolveWorkResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ * Duplicated here because this package has no type-sharing mechanism
+ * with the PICA monorepo; drift is caught by the holdout suite.
+ */
+export interface ResolveWorkResult {
+    entity_type: "work";
+    entity_id: string;
+    sources_run: Array<"mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs">;
+    applied: Array<{
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "work";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
+/**
+ * ADR-179 Phase 3 recording resolver result. Mirrors the server-side
+ * `ResolveRecordingResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ */
+export interface ResolveRecordingResult {
+    entity_type: "recording";
+    entity_id: string;
+    sources_run: Array<"spotify" | "youtube" | "musicbrainz" | "discogs">;
+    applied: Array<{
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "recording";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
+/**
+ * ADR-179 Phase 2 person resolver result. Mirrors the server-side
+ * `ResolvePersonResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ * Duplicated here for the same reason as `ResolveWorkResult` — this
+ * package has no type-sharing mechanism with the PICA monorepo; drift
+ * is caught by the holdout suite.
+ */
+export interface ResolvePersonResult {
+    entity_type: "person";
+    entity_id: string;
+    sources_run: Array<"isni" | "musicbrainz">;
+    applied: Array<{
+        source: "isni" | "musicbrainz";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "person";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "isni" | "musicbrainz";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "isni" | "musicbrainz";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
 interface CatalogStats {
     works: {
         total: number;
@@ -298,6 +399,18 @@ declare class BaseResource {
     protected apiKey: string;
     protected debug: boolean;
     constructor(baseUrl: string, apiKey: string, debug: boolean);
+    /**
+     * Vercel Deployment Protection bypass header for preview self-fetches.
+     *
+     * When the SDK is used server-side on a Vercel preview (e.g. the MCP
+     * HTTP route calling back into its own admin resolve routes),
+     * Vercel's edge wraps the internal call in deployment protection and
+     * 401s before the request reaches the route handler. "Protection
+     * Bypass for Automation" auto-injects VERCEL_AUTOMATION_BYPASS_SECRET
+     * at runtime; forward it as the documented header so self-fetches
+     * reach the actual route. Empty outside Vercel — safe no-op.
+     */
+    private getBypassHeaders;
     private fetchWithTimeout;
     private fetchWithRetry;
     protected request<T>(method: string, path: string, body?: any): Promise<T>;
@@ -330,6 +443,16 @@ declare class WorksResource extends BaseResource {
      * from the work side. Withdrawn links are filtered server-side.
      */
     listProductionAssets(workId: string): Promise<ProductionAssetLink[]>;
+    /**
+     * ADR-173 Decision 2: list every release this work appears on, with
+     * its track position. Distinct from listProductionAssets — this is
+     * release-context, not physical-asset provenance.
+     */
+    listReleases(workId: string): Promise<Array<{
+        release: Record<string, any>;
+        track_number: number;
+        disc_number: number | null;
+    }>>;
 }
 declare class PeopleResource extends BaseResource {
     list(params?: {
@@ -612,6 +735,16 @@ declare class RecordingsResource extends BaseResource {
      * from the recording side. Withdrawn links are filtered server-side.
      */
     listProductionAssets(recordingId: string): Promise<ProductionAssetLink[]>;
+    /**
+     * ADR-173 Decision 2: list every release this recording appears on,
+     * with its track position. Backs the `releases` section on
+     * pica_recordings_inspect.
+     */
+    listReleases(recordingId: string): Promise<Array<{
+        release: Record<string, any>;
+        track_number: number;
+        disc_number: number | null;
+    }>>;
 }
 declare class EnrichmentResource extends BaseResource {
     enrichWork(workId: string): Promise<any>;
@@ -623,6 +756,63 @@ declare class EnrichmentResource extends BaseResource {
     enrichWorkDiscogs(workId: string): Promise<any>;
     enrichWorkSpotify(workId: string): Promise<any>;
     enrichWorkYouTube(workId: string): Promise<any>;
+    /**
+     * ADR-179 outcome resolver — fan a work out across every eligible
+     * enrichment source and return a structured receipt.
+     *
+     * The orchestration lives server-side (see
+     * `lib/services/enrichment-cascade/resolver.ts`); this SDK method is
+     * the thin wrapper the MCP tool layer calls. Future Tasks-primitive
+     * conversion (ADR-171) will turn the request into a Task so agents
+     * receive per-source status events as each provider resolves. Today
+     * the shape is the final receipt only — callers treat the object
+     * returned here as that single terminal event.
+     *
+     *   sources:       optional whitelist. Omit to fan out to every
+     *                  eligible source (mlc, spotify, youtube,
+     *                  musicbrainz, discogs).
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolveWork(workId: string, options?: {
+        sources?: Array<"mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolveWorkResult>;
+    /**
+     * ADR-179 Phase 2 — person resolver. Fans a person across the two
+     * eligible identity-graph sources (ISNI + MusicBrainz) and returns
+     * a structured receipt in the same shape as `resolveWork`. Replaces
+     * the legacy `PeopleResource.enrichFromISNI` / `enrichFromMusicBrainz`
+     * calls at the MCP tool layer — those SDK methods stay available this
+     * release but are deprecated via `pica_people_enrich_*` returning
+     * `TOOL_DEPRECATED`.
+     *
+     *   sources:       optional whitelist. Omit to run both sources.
+     *                  Allowed: `isni` | `musicbrainz`.
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolvePerson(personId: string, options?: {
+        sources?: Array<"isni" | "musicbrainz">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolvePersonResult>;
+    /**
+     * ADR-179 Phase 3 — recording resolver. Fans a recording across eligible
+     * master-side sources (Spotify, YouTube, MusicBrainz, Discogs) and returns
+     * a structured receipt in the same shape as `resolveWork` / `resolvePerson`.
+     *
+     *   sources:       optional whitelist. Omit to run every eligible source.
+     *                  Allowed: `spotify` | `youtube` | `musicbrainz` | `discogs`.
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolveRecording(recordingId: string, options?: {
+        sources?: Array<"spotify" | "youtube" | "musicbrainz" | "discogs">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolveRecordingResult>;
     /**
      * ADR-164: manually re-evaluate a work against every cascade rule.
      * Idempotent — rules whose preconditions are already satisfied skip.
@@ -639,6 +829,78 @@ declare class EnrichmentResource extends BaseResource {
      * Not per-org, not persistent across cold starts — a spot-check only.
      */
     getCascadeHealth(): Promise<any>;
+    /**
+     * List pending enrichment proposals for the authenticated org. Only
+     * `pending` rows are visible — applied/rejected/expired are hidden
+     * regardless of filter. See ADR-163 for the design.
+     */
+    listEnrichmentProposals(params?: {
+        entity_type?: "work" | "person" | "recording";
+        entity_id?: string;
+        rule_id?: string;
+        source?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+    /**
+     * Apply a pending proposal. For update proposals, drift detection
+     * runs first — if the entity has changed since the proposal was
+     * created, the response is `{ status: 'drift_detected', conflicts }`
+     * and nothing is written. Pass `force: true` to bypass drift after
+     * explicit user confirmation. For create proposals (e.g. the
+     * `artist_title_to_youtube` recording-create), a uniqueness check
+     * runs instead; conflicts return `{ status: 'create_conflict' }` and
+     * cannot be forced.
+     */
+    applyEnrichmentProposal(proposalId: string, options?: {
+        force?: boolean;
+        resolution_note?: string;
+    }): Promise<any>;
+    /**
+     * Reject a pending proposal. Content-hash suppression (ADR-163)
+     * permanently blocks re-proposal of the same content — no timer,
+     * no cooldown. The cascade re-proposes only when the source data
+     * changes and produces a different hash.
+     */
+    rejectEnrichmentProposal(proposalId: string, options?: {
+        resolution_note?: string;
+    }): Promise<any>;
+    /**
+     * ADR-178: File a proposal sourced from open-web agent research.
+     *
+     * Distinct from cascade-sourced proposals. Every `proposed_fields`
+     * key must appear in at least one `sources[].fields` array —
+     * unsourced claims return a 400 with `code: "MISSING_SOURCE"` and
+     * the proposal is not persisted. The server hard-codes
+     * `source = 'agent_research'` and `rule_id = 'agent_research'`;
+     * callers omit both.
+     *
+     * Response codes carried through to the caller:
+     *   - 201: `{ proposal_id, source, rule_id, status }` (pending)
+     *   - 409 `DUPLICATE_SUPPRESSED`: identical content already filed
+     *   - 400 `MISSING_SOURCE`: uncited proposed field or empty sources
+     *   - 400 `MISSING_FIELDS`: proposed_fields was empty
+     *   - 400 `INVALID_SOURCE_SHAPE`: a source entry lacked url/fields/accessed_at
+     *   - 404 `ENTITY_NOT_FOUND`: entity_id not in caller's org
+     */
+    proposeAgentResearch(input: {
+        entity_type: "work" | "person" | "recording";
+        entity_id: string;
+        proposed_fields: Record<string, unknown>;
+        sources: Array<{
+            url: string;
+            fields: string[];
+            accessed_at: string;
+        }>;
+        confidence_score?: number | null;
+        rationale?: string;
+        proposal_action?: "update" | "create";
+    }): Promise<{
+        proposal_id: string;
+        source: "agent_research";
+        rule_id: "agent_research";
+        status: "pending";
+    }>;
     /** Preview what a Spotify URL would do — delegates to streaming-link */
     spotifyUrlPreview(url: string): Promise<any>;
     /** Execute import/enrich from a Spotify URL — delegates to streaming-link */
@@ -681,6 +943,16 @@ declare class SettingsResource extends BaseResource {
     storageConfig(): Promise<any>;
     orgProfile(): Promise<any>;
     userProfile(): Promise<any>;
+    /**
+     * Update the authenticated user's privacy / marketing-preference flags.
+     * Parity with ADR-183's settings-tab toggles — exposes the same fields
+     * the web UI writes, so an agent can unsubscribe on the user's behalf
+     * without leaving the conversation. ADR-184 slice 5.
+     */
+    updatePrivacySettings(params: {
+        receive_news_announcements?: boolean;
+        receive_monthly_digest?: boolean;
+    }): Promise<any>;
 }
 declare class CalendarResource extends BaseResource {
     getEvents(params: {
@@ -994,6 +1266,71 @@ declare class ImportResource extends BaseResource {
         duplicatesSkipped: number;
         workIds: string[];
     }>;
+    /**
+     * ADR-166 — Preview a YouTube video import. Returns the classified
+     * version type and best work match, without writing.
+     */
+    youtubeLinkPreview(url: string): Promise<{
+        items: Array<{
+            track: {
+                videoId: string;
+                title: string;
+                channel: string;
+                channelTitle: string;
+                youtubeUrl: string;
+                thumbnailUrl: string | null;
+                publishedAt: string | null;
+                durationMs: number | null;
+                viewCount: number | null;
+                likeCount: number | null;
+                commentCount: number | null;
+                licensedContent: boolean;
+                durationIso: string | null;
+            };
+            classification: {
+                versionType: string;
+                reason: string;
+                confidence: number;
+            };
+            match: {
+                workId: string;
+                confidence: number;
+                reason: string;
+            } | null;
+        }>;
+        source: {
+            type: "video" | "playlist" | "channel";
+            id: string;
+            url: string;
+            name: string;
+        };
+        capReached: boolean;
+    }>;
+    /**
+     * ADR-166 — Execute a YouTube video import. Creates a recording with
+     * the classified (or overridden) version type, linked to the matched
+     * or newly-created work. Fires the post-import cascade.
+     */
+    youtubeLinkImport(url: string, options?: {
+        selectedVideoIds?: string[];
+        targetWorkId?: string;
+        overrideVersionType?: string;
+    }): Promise<{
+        recordingsCreated: number;
+        worksCreated: number;
+        worksMatched: number;
+        multimediaLinked: number;
+        workIds: string[];
+        items: Array<{
+            videoId: string;
+            workId: string | null;
+            recordingId: string | null;
+            versionType: string;
+            matched: boolean;
+            status: "created" | "skipped" | "error";
+            error?: string;
+        }>;
+    }>;
     getTemplate(domain: ImportDomain): Promise<string>;
 }
 declare class DocumentsResource extends BaseResource {
@@ -1105,6 +1442,11 @@ declare class ProjectsResource extends BaseResource {
     create(data: Record<string, any>): Promise<any>;
     update(id: string, data: Record<string, any>): Promise<any>;
     delete(id: string): Promise<any>;
+    attachWork(projectId: string, data: {
+        work_id: string;
+        project_day?: number | null;
+        notes?: string | null;
+    }): Promise<any>;
 }
 declare class SplitSheetsResource extends BaseResource {
     listForWork(workId: string): Promise<any>;
@@ -1123,10 +1465,21 @@ declare class PublishersResource extends BaseResource {
         query?: string;
         limit?: number;
     }): Promise<any>;
-    create(data: {
-        name: string;
-        ipi?: string;
-    }): Promise<any>;
+    create(data: Record<string, unknown>): Promise<any>;
+}
+export interface LabelOrganisation {
+    id: string;
+    name: string;
+    display_name: string | null;
+    country: string | null;
+    website: string | null;
+    verification_status: string | null;
+}
+declare class LabelsResource extends BaseResource {
+    list(params?: {
+        query?: string;
+        limit?: number;
+    }): Promise<LabelOrganisation[]>;
 }
 declare class ReleasesResource extends BaseResource {
     list(params?: {
@@ -1136,6 +1489,48 @@ declare class ReleasesResource extends BaseResource {
     create(data: Record<string, any>): Promise<any>;
     update(id: string, data: Record<string, any>): Promise<any>;
     delete(id: string): Promise<any>;
+    /**
+     * ADR-173: attach a recording and/or work to a release at a
+     * specific (disc, track) position. Idempotent on position.
+     */
+    attachTrack(releaseId: string, data: {
+        recording_id?: string | null;
+        work_id?: string | null;
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
+    /**
+     * ADR-173: list tracks on a release in (disc, track) order with
+     * inlined work + recording summary fields.
+     */
+    listTracks(releaseId: string): Promise<any>;
+    /**
+     * ADR-173: soft-confirmation detach by position. Call without
+     * confirm:true to get a preview; call with confirm:true to execute.
+     */
+    detachTrack(releaseId: string, data: {
+        track_number: number;
+        disc_number?: number;
+        confirm?: boolean;
+    }): Promise<any>;
+    /**
+     * ADR-173: transactional positional reorder. Input is the full
+     * new order as [{ track_id, track_number, disc_number }].
+     */
+    reorderTracks(releaseId: string, newOrder: Array<{
+        track_id: string;
+        track_number: number;
+        disc_number?: number;
+    }>): Promise<any>;
+    /**
+     * ADR-173 Decision 4: compound attach that resolves the
+     * recording's work_id server-side before creating the track row.
+     */
+    attachRecordingWithWork(releaseId: string, data: {
+        recording_id: string;
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
 }
 declare class SessionsResource extends BaseResource {
     list(params?: {
@@ -1315,6 +1710,7 @@ export declare class PicaClient {
     splitSheets: SplitSheetsResource;
     recordingSplits: RecordingSplitsResource;
     publishers: PublishersResource;
+    labels: LabelsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;