@withpica/mcp-sdk 1.4.0 → 1.8.0

package/dist/index.js

@@ -10,6 +10,7 @@ const LONG_TIMEOUT_PATTERNS = [
     "/exports/",
     "/enrichment/",
     "/enrich",
+    "/resolve", // ADR-179 resolver fan-out (up to 5 sources per call)
     "/industry-ready",
     "/catalog-asset-report",
     "/analyze",
@@ -51,6 +52,26 @@ class BaseResource {
         this.apiKey = apiKey;
         this.debug = debug;
     }
+    /**
+     * 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.
+     */
+    getBypassHeaders() {
+        if (typeof process !== "undefined" &&
+            process.env?.VERCEL_AUTOMATION_BYPASS_SECRET) {
+            return {
+                "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET,
+            };
+        }
+        return {};
+    }
     async fetchWithTimeout(url, init, timeoutMs) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -122,6 +143,7 @@ class BaseResource {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`,
                 "Content-Type": "application/json",
+                ...this.getBypassHeaders(),
             },
             body: body ? JSON.stringify(body) : undefined,
         }, timeoutMs);
@@ -142,6 +164,7 @@ class BaseResource {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`,
                 "Content-Type": "application/json",
+                ...this.getBypassHeaders(),
             },
             body: body ? JSON.stringify(body) : undefined,
         }, timeoutMs);
@@ -202,6 +225,15 @@ class WorksResource extends BaseResource {
         const result = await this.request("GET", `/admin/works/${workId}/production-assets`);
         return result?.assets || [];
     }
+    /**
+     * 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.
+     */
+    async listReleases(workId) {
+        const result = await this.request("GET", `/admin/works/${workId}/releases`);
+        return result?.data || [];
+    }
 }
 class PeopleResource extends BaseResource {
     async list(params) {
@@ -615,6 +647,15 @@ class RecordingsResource extends BaseResource {
         const result = await this.request("GET", `/admin/recordings/${recordingId}/production-assets`);
         return result?.assets || [];
     }
+    /**
+     * ADR-173 Decision 2: list every release this recording appears on,
+     * with its track position. Backs the `releases` section on
+     * pica_recordings_inspect.
+     */
+    async listReleases(recordingId) {
+        const result = await this.request("GET", `/admin/recordings/${recordingId}/releases`);
+        return result?.data || [];
+    }
 }
 // --- Enrichment Resource ---
 class EnrichmentResource extends BaseResource {
@@ -645,6 +686,78 @@ class EnrichmentResource extends BaseResource {
     async enrichWorkYouTube(workId) {
         return this.request("POST", `/admin/youtube/enrich/${workId}`);
     }
+    /**
+     * 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.
+     */
+    async resolveWork(workId, options) {
+        const body = {};
+        if (options?.sources)
+            body.sources = options.sources;
+        if (options?.includeFuzzy !== undefined) {
+            body.include_fuzzy = options.includeFuzzy;
+        }
+        return this.request("POST", `/admin/works/${workId}/resolve`, body);
+    }
+    /**
+     * 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.
+     */
+    async resolvePerson(personId, options) {
+        const body = {};
+        if (options?.sources)
+            body.sources = options.sources;
+        if (options?.includeFuzzy !== undefined) {
+            body.include_fuzzy = options.includeFuzzy;
+        }
+        return this.request("POST", `/admin/people/${personId}/resolve`, body);
+    }
+    /**
+     * 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.
+     */
+    async resolveRecording(recordingId, options) {
+        const body = {};
+        if (options?.sources)
+            body.sources = options.sources;
+        if (options?.includeFuzzy !== undefined) {
+            body.include_fuzzy = options.includeFuzzy;
+        }
+        return this.request("POST", `/admin/recordings/${recordingId}/resolve`, body);
+    }
     /**
      * ADR-164: manually re-evaluate a work against every cascade rule.
      * Idempotent — rules whose preconditions are already satisfied skip.
@@ -717,6 +830,27 @@ class EnrichmentResource extends BaseResource {
     async rejectEnrichmentProposal(proposalId, options) {
         return this.request("POST", `/admin/enrichment-proposals/${proposalId}/reject`, options ?? {});
     }
+    /**
+     * 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
+     */
+    async proposeAgentResearch(input) {
+        return this.request("POST", "/admin/enrichment-proposals", input);
+    }
     /** Preview what a Spotify URL would do — delegates to streaming-link */
     async spotifyUrlPreview(url) {
         return this.request("POST", "/admin/import/streaming-link", { url });
@@ -830,6 +964,132 @@ class SettingsResource extends BaseResource {
     async userProfile() {
         return this.request("GET", "/admin/settings/user-profile");
     }
+    /**
+     * 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.
+     */
+    async updatePrivacySettings(params) {
+        return this.request("PATCH", "/admin/settings/user-profile", params);
+    }
+    /**
+     * 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.
+     */
+    async getPrivacySettings() {
+        return this.request("GET", "/admin/settings/user-profile");
+    }
+    /**
+     * 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.
+     */
+    async updateMyIdentity(params) {
+        return this.request("POST", "/admin/my-identity", params);
+    }
+    /**
+     * 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.
+     */
+    async updateOrganisationProfile(params) {
+        return this.request("POST", "/admin/organisation-profile", params);
+    }
+}
+// --- GDPR Resource (user self-service delete + export) ---
+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.
+     */
+    async deleteMyAccount(params) {
+        return this.request("POST", "/admin/gdpr/delete-my-account", params ?? {});
+    }
+    /**
+     * 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).
+     */
+    async exportMyData() {
+        return this.request("POST", "/admin/gdpr/export-my-data", {});
+    }
+}
+// --- Feedback Resource (user feedback submissions) ---
+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.
+     */
+    async submit(params) {
+        return this.request("POST", "/feedback", params);
+    }
+}
+// --- Agent Identity Resource (ADR-185 Part 1) ---
+/**
+ * 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.
+ */
+class AgentIdentityResource extends BaseResource {
+    async createIdentity(params) {
+        return this.request("POST", "/admin/agent-identities", {
+            display_name: params.displayName,
+            client_fingerprint: params.clientFingerprint ?? null,
+        });
+    }
+    async listIdentities() {
+        return this.request("GET", "/admin/agent-identities");
+    }
+    async issueGrant(params) {
+        return this.request("POST", `/admin/agent-identities/${params.agentIdentityId}/grants`, {
+            scopes: params.scopes,
+            expires_at: params.expiresAt ?? null,
+        });
+    }
+    async listMyGrants() {
+        return this.request("GET", "/admin/agent-grants");
+    }
+    async revokeGrant(params) {
+        return this.request("DELETE", `/admin/agent-grants/${params.grantId}`);
+    }
+    async getActivity(params) {
+        const query = new URLSearchParams();
+        if (params.agentIdentityId)
+            query.set("agent_identity_id", params.agentIdentityId);
+        if (params.agentGrantId)
+            query.set("agent_grant_id", params.agentGrantId);
+        if (typeof params.limit === "number")
+            query.set("limit", String(params.limit));
+        if (typeof params.offset === "number")
+            query.set("offset", String(params.offset));
+        const qs = query.toString();
+        return this.request("GET", qs ? `/admin/agent-activity?${qs}` : "/admin/agent-activity");
+    }
 }
 // --- Calendar Resource ---
 class CalendarResource extends BaseResource {
@@ -1220,6 +1480,9 @@ class ProjectsResource extends BaseResource {
     async delete(id) {
         return this.request("DELETE", `/admin/projects/${id}`);
     }
+    async attachWork(projectId, data) {
+        return this.request("POST", `/admin/projects/${projectId}/works`, data);
+    }
 }
 class SplitSheetsResource extends BaseResource {
     async listForWork(workId) {
@@ -1263,6 +1526,18 @@ class PublishersResource extends BaseResource {
         return this.request("POST", "/admin/publishers", data);
     }
 }
+class LabelsResource extends BaseResource {
+    async list(params) {
+        const queryParams = new URLSearchParams();
+        if (params?.query)
+            queryParams.set("query", params.query);
+        if (params?.limit)
+            queryParams.set("limit", String(params.limit));
+        const qs = queryParams.toString();
+        const res = await this.request("GET", `/admin/labels${qs ? `?${qs}` : ""}`);
+        return (res?.data ?? []);
+    }
+}
 class ReleasesResource extends BaseResource {
     async list(params) {
         const qs = params?.limit ? `?limit=${params.limit}` : "";
@@ -1280,6 +1555,88 @@ class ReleasesResource extends BaseResource {
     async delete(id) {
         return this.request("DELETE", `/admin/releases/${id}`);
     }
+    /**
+     * ADR-173: attach a recording and/or work to a release at a
+     * specific (disc, track) position. Idempotent on position.
+     */
+    async attachTrack(releaseId, data) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks`, data);
+    }
+    /**
+     * ADR-173: list tracks on a release in (disc, track) order with
+     * inlined work + recording summary fields.
+     */
+    async listTracks(releaseId) {
+        return this.request("GET", `/admin/releases/${releaseId}/tracks`);
+    }
+    /**
+     * ADR-173: soft-confirmation detach by position. Call without
+     * confirm:true to get a preview; call with confirm:true to execute.
+     */
+    async detachTrack(releaseId, data) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/detach`, data);
+    }
+    /**
+     * ADR-173: transactional positional reorder. Input is the full
+     * new order as [{ track_id, track_number, disc_number }].
+     */
+    async reorderTracks(releaseId, newOrder) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/reorder`, {
+            new_order: newOrder,
+        });
+    }
+    /**
+     * ADR-173 Decision 4: compound attach that resolves the
+     * recording's work_id server-side before creating the track row.
+     */
+    async attachRecordingWithWork(releaseId, data) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/attach-recording-with-work`, data);
+    }
+    /**
+     * 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.
+     */
+    async bulkAttachTracks(releaseId, tracks) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/bulk-attach`, { tracks });
+    }
+    /**
+     * ADR-175 Decision 3: swap two track positions on a release.
+     */
+    async moveTrack(releaseId, from, to) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/move`, {
+            from,
+            to,
+        });
+    }
+    /**
+     * 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.
+     */
+    async attachTrackByIdentifier(releaseId, data) {
+        return this.request("POST", `/admin/releases/${releaseId}/tracks/attach-by-identifier`, data);
+    }
+    /**
+     * 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.
+     */
+    async completenessCheck(params) {
+        const qs = params?.release_id
+            ? `?release_id=${encodeURIComponent(params.release_id)}`
+            : "";
+        return this.request("GET", `/admin/releases/completeness-check${qs}`);
+    }
+    /**
+     * 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.
+     */
+    async createWithTracks(data) {
+        return this.request("POST", "/admin/releases/create-with-tracks", data);
+    }
 }
 class SessionsResource extends BaseResource {
     async list(params) {
@@ -1594,6 +1951,7 @@ export class PicaClient {
     splitSheets;
     recordingSplits;
     publishers;
+    labels;
     agreementTemplates;
     producerAgreements;
     workForHire;
@@ -1604,6 +1962,9 @@ export class PicaClient {
     disputes;
     chain;
     telegram;
+    gdpr;
+    feedback;
+    agentIdentity;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */
@@ -1670,6 +2031,7 @@ export class PicaClient {
         this.splitSheets = new SplitSheetsResource(baseUrl, config.apiKey, debug);
         this.recordingSplits = new RecordingSplitsResource(baseUrl, config.apiKey, debug);
         this.publishers = new PublishersResource(baseUrl, config.apiKey, debug);
+        this.labels = new LabelsResource(baseUrl, config.apiKey, debug);
         this.agreementTemplates = new AgreementTemplatesResource(baseUrl, config.apiKey, debug);
         this.producerAgreements = new ProducerAgreementsResource(baseUrl, config.apiKey, debug);
         this.workForHire = new WorkForHireResource(baseUrl, config.apiKey, debug);
@@ -1680,6 +2042,9 @@ export class PicaClient {
         this.disputes = new DisputesResource(baseUrl, config.apiKey, debug);
         this.chain = new ChainResource(baseUrl, config.apiKey, debug);
         this.telegram = new TelegramResource(baseUrl, config.apiKey, debug);
+        this.gdpr = new GdprResource(baseUrl, config.apiKey, debug);
+        this.feedback = new FeedbackResource(baseUrl, config.apiKey, debug);
+        this.agentIdentity = new AgentIdentityResource(baseUrl, config.apiKey, debug);
     }
 }
 //# sourceMappingURL=index.js.map