@withpica/mcp-sdk 1.4.0 → 1.8.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.
@@ -675,6 +865,51 @@ declare class EnrichmentResource extends BaseResource {
     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" | "agreement";
+        /** Required for update proposals; omit for ADR-193 create proposals. */
+        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";
+        /**
+         * ADR-193 Surface 4 — parent entity for create proposals.
+         * Recording creates require parent_entity_type='work' +
+         * parent_entity_id. Agreements + people may cite an optional
+         * parent; if absent, the child is created standalone.
+         */
+        parent_entity_type?: "work" | "recording" | "agreement" | "person";
+        parent_entity_id?: string;
+    }): 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 */
@@ -717,6 +952,125 @@ 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>;
+    /**
+     * Read the authenticated user's privacy / marketing-preference flags.
+     * Pulls from the same user-profile row the settings UI reads (ADR-184 slice
+     * 5 read-side sibling). Reuses the existing GET endpoint — no dedicated
+     * route needed; the MCP tool picks only the two privacy flags from the
+     * response so unrelated profile fields are not surfaced through this tool.
+     */
+    getPrivacySettings(): Promise<any>;
+    /**
+     * Capture or update the authenticated user's own identifiers
+     * (stage_name, IPI, ISNI, IPN, PRO). Subject is always derived from
+     * 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.
+     * ADR-189 Phase 3.
+     */
+    updateMyIdentity(params: {
+        stage_name?: string | null;
+        cae_ipi_number?: string | null;
+        isni?: string | null;
+        ipn?: string | null;
+        pro_name?: string | null;
+        pro_member_number?: string | null;
+    }): Promise<any>;
+    /**
+     * Update the authenticated caller's organisation profile
+     * (org_type, display_name, tagline, ipi_number). Scope bounded by
+     * auth context — the org id is derived server-side, never accepted
+     * as a parameter. Distinct from the settings-UI PUT at
+     * `/admin/settings/organisation-profile`: this path validates
+     * org_type against the CHECK enum, rate-limits, and stamps via
+     * withAgentActionStamp for grant-auth callers (ADR-185 Part 3).
+     * ADR-189 Phase 3.
+     */
+    updateOrganisationProfile(params: {
+        org_type?: string | null;
+        display_name?: string | null;
+        tagline?: string | null;
+        ipi_number?: string | null;
+    }): Promise<any>;
+}
+declare class GdprResource extends BaseResource {
+    /**
+     * Create a soft-delete request for the authenticated user's account.
+     * Never accepts a user_id — the subject is derived from the bearer token
+     * (ADR-184 rule 2). Returns the deletion_request_id immediately; actual
+     * erasure runs async through the gdpr-deletion processing path. Matches
+     * the web UI's 30-day reversal window.
+     */
+    deleteMyAccount(params?: {
+        reason?: string;
+    }): Promise<any>;
+    /**
+     * Queue a GDPR Article 15 / 20 data export for the authenticated user.
+     * Returns a job_id immediately; the signed download link is emailed when
+     * the job completes. Format defaults to JSON (ADR-184 defers format
+     * negotiation to a future parameter).
+     */
+    exportMyData(): Promise<any>;
+}
+declare class FeedbackResource extends BaseResource {
+    /**
+     * Submit user feedback through the existing /api/feedback pipeline.
+     * ADR-184 slice 8 — actionType is always of form `general_<category>`
+     * so downstream teamTasksService.createFromGeneralFeedback routes
+     * it to the correct team role.
+     */
+    submit(params: {
+        actionType: string;
+        sentiment: "positive" | "negative";
+        comment?: string;
+        portal?: string;
+        pagePath?: string;
+        actionContext?: Record<string, unknown>;
+    }): Promise<any>;
+}
+/**
+ * Session-auth-only surface: the three HTTP routes backing these
+ * methods refuse `pica_grant_` callers with 403 `session_auth_required`
+ * regardless of scope. When invoked via the stdio MCP server the caller
+ * is an API key owned by the user, which passes; when invoked via HTTP
+ * MCP behind a grant token the API rejects before any DB work.
+ */
+declare class AgentIdentityResource extends BaseResource {
+    createIdentity(params: {
+        displayName: string;
+        clientFingerprint?: string | null;
+    }): Promise<any>;
+    listIdentities(): Promise<any>;
+    issueGrant(params: {
+        agentIdentityId: string;
+        scopes: string[];
+        expiresAt?: string | null;
+    }): Promise<any>;
+    listMyGrants(): Promise<any>;
+    revokeGrant(params: {
+        grantId: string;
+    }): Promise<any>;
+    getActivity(params: {
+        agentIdentityId?: string | null;
+        agentGrantId?: string | null;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
 }
 declare class CalendarResource extends BaseResource {
     getEvents(params: {
@@ -1206,6 +1560,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>;
@@ -1224,10 +1583,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?: {
@@ -1237,6 +1607,107 @@ 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>;
+    /**
+     * ADR-175 Decision 2: attach many tracks to a release atomically.
+     * Duplicate (disc_number, track_number) pairs in the payload cause
+     * the call to fail atomically — no rows are inserted.
+     */
+    bulkAttachTracks(releaseId: string, tracks: Array<{
+        recording_id?: string | null;
+        work_id?: string | null;
+        track_number: number;
+        disc_number?: number;
+    }>): Promise<any>;
+    /**
+     * ADR-175 Decision 3: swap two track positions on a release.
+     */
+    moveTrack(releaseId: string, from: {
+        track_number: number;
+        disc_number?: number;
+    }, to: {
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
+    /**
+     * ADR-175 Decision 4: attach a track by external identifier. The SDK
+     * resolves to an internal recording id server-side; on miss or
+     * collision the route returns a 400 with a recovery hint and no row
+     * is created.
+     */
+    attachTrackByIdentifier(releaseId: string, data: {
+        identifier_type: "isrc" | "spotify_url" | "spotify_track_uri" | "youtube_video_id" | "musicbrainz_recording_id" | "mlc_recording_id";
+        value: string;
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
+    /**
+     * ADR-175 Decision 5: release-scoped completeness report. Pass a
+     * release_id for a single-release report, or omit for a scan of every
+     * release in the caller's organisation.
+     */
+    completenessCheck(params?: {
+        release_id?: string;
+    }): Promise<any>;
+    /**
+     * ADR-175 Decision 1: create a release and its tracks in a single
+     * atomic transaction. Track entries accept recording_id, work_id,
+     * or identifier_lookup — whichever shape the agent has.
+     */
+    createWithTracks(data: {
+        release: Record<string, any>;
+        tracks: Array<{
+            recording_id?: string | null;
+            work_id?: string | null;
+            identifier_lookup?: {
+                identifier_type: "isrc" | "spotify_url" | "spotify_track_uri" | "youtube_video_id" | "musicbrainz_recording_id" | "mlc_recording_id";
+                value: string;
+            };
+            track_number: number;
+            disc_number?: number;
+        }>;
+    }): Promise<any>;
 }
 declare class SessionsResource extends BaseResource {
     list(params?: {
@@ -1416,6 +1887,7 @@ export declare class PicaClient {
     splitSheets: SplitSheetsResource;
     recordingSplits: RecordingSplitsResource;
     publishers: PublishersResource;
+    labels: LabelsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;
@@ -1426,6 +1898,9 @@ export declare class PicaClient {
     disputes: DisputesResource;
     chain: ChainResource;
     telegram: TelegramResource;
+    gdpr: GdprResource;
+    feedback: FeedbackResource;
+    agentIdentity: AgentIdentityResource;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */