@withpica/mcp-sdk 3.11.0 → 3.13.0

package/dist/index.js

@@ -721,6 +721,46 @@ class BookingsResource extends BaseResource {
         return this.request("PATCH", `/admin/bookings/${encodeURIComponent(id)}`, data);
     }
 }
+/**
+ * Live shows and tour credits (ADR-313). Wraps `/admin/shows` and
+ * `/admin/setlist-items/[id]`.
+ */
+class ShowsResource extends BaseResource {
+    /** POST /admin/shows — log a dated show, or a tour credit. */
+    async log(payload) {
+        return this.request("POST", "/admin/shows", payload);
+    }
+    /**
+     * GET /admin/shows — list shows for the org (newest first), or the single
+     * show + its folded-in setlist when `id` is given.
+     */
+    async query(params) {
+        const qp = new URLSearchParams();
+        if (params?.id)
+            qp.set("id", params.id);
+        if (params?.from)
+            qp.set("from", params.from);
+        if (params?.to)
+            qp.set("to", params.to);
+        if (params?.venue)
+            qp.set("venue", params.venue);
+        if (params?.city)
+            qp.set("city", params.city);
+        if (params?.country)
+            qp.set("country", params.country);
+        if (params?.unfiled_only !== undefined)
+            qp.set("unfiled_only", String(params.unfiled_only));
+        const qs = qp.toString();
+        return this.request("GET", `/admin/shows${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * PATCH /admin/setlist-items/[id] — confirm a setlist match, a cover, a
+     * performer, or (with `venue_id` + `show_id`) a venue candidate.
+     */
+    async matchItem(id, payload) {
+        return this.request("PATCH", `/admin/setlist-items/${encodeURIComponent(id)}`, payload);
+    }
+}
 class CreditsResource extends BaseResource {
     async listForWork(workId) {
         return this.request("GET", `/admin/works/${workId}/credits`);
@@ -735,9 +775,14 @@ class CreditsResource extends BaseResource {
         return this.request("POST", `/admin/works/${workId}/collaborators`, { collaborators: collaborators.credits });
     }
     /**
-     * ADR-232 atomic add — INSERT a single work credit. Race-safe under
-     * concurrent writes (replace_work_credits is read-modify-write and
-     * therefore not atomic for this verb). Returns the new credit_id.
+     * ADR-232 atomic add — INSERT a single work credit. NOT replace
+     * semantics: the work-level POST /credits is an additive upsert that
+     * re-reads and re-writes the whole set, so it is not atomic for this
+     * verb. createWorkCredit routes the row to its canonical home —
+     * publishing roles to work_collaborators, master attribution to
+     * recording_credits, owner to recording_splits (ADR-252 WS-A; the
+     * legacy work_credits table was dropped at DB-M3). Returns the new
+     * credit_id.
      */
     async atomicAdd(workId, input) {
         return this.request("POST", `/admin/works/${workId}/credits/atomic-add`, input);
@@ -1473,6 +1518,14 @@ class EnrichmentResource extends BaseResource {
      * `pending` rows are visible — applied/rejected/expired are hidden
      * regardless of filter. See ADR-163 for the design.
      *
+     * ⚠️ `pending` is not the same as "still worth asking". A finding the
+     * catalogue has since ANSWERED by another route keeps that status — nothing
+     * re-asks the question after mint time — and applying it refuses. Those are
+     * excluded, matching what `/inspect/found` shows, and
+     * `data.excluded_stale` ({count, reasons}) reports the drop so a short page
+     * is distinguishable from a filtered one. Applied after pagination, so a
+     * page may return fewer rows than `limit`.
+     *
      * ADR-264 C1: supports min_confidence, max_confidence, created_after
      * for filtering by confidence band and recency.
      */
@@ -1497,6 +1550,8 @@ class EnrichmentResource extends BaseResource {
             query.max_confidence = String(params.max_confidence);
         if (params?.created_after)
             query.created_after = params.created_after;
+        if (params?.review_shape)
+            query.review_shape = "true";
         const qs = new URLSearchParams(query).toString();
         const path = qs
             ? `/admin/enrichment-proposals?${qs}`
@@ -1537,6 +1592,28 @@ class EnrichmentResource extends BaseResource {
     async bulkRejectProposals(input) {
         return this.request("POST", "/admin/enrichment-proposals/bulk-reject", input);
     }
+    /**
+     * Apply many pending proposals in one call — the accept side of the
+     * /inspect/found queue.
+     *
+     * Takes ids only; unlike `bulkRejectProposals` there is deliberately no
+     * `filter` form, because a filter that bulk-ACCEPTS is a different kind of
+     * thing from one that bulk-dismisses: rejecting a mis-filtered set costs a
+     * re-proposal, accepting one writes to the catalogue.
+     *
+     * Caps at 100 per call. ⚠️ **Partial success is normal** — apply branches
+     * into four different update/create paths and each id is applied
+     * independently, so `failed` being non-empty alongside a non-zero `applied`
+     * is the expected shape, not an error. Never report a partial as a success.
+     *
+     * Returns `{ applied, failed: [{ id, error }], skipped }`. `skipped` is
+     * always empty here (a non-pending id arrives as a `failed` entry carrying
+     * its own message); the key exists so one client shape reads apply, reject
+     * and undo alike.
+     */
+    async bulkApplyProposals(input) {
+        return this.request("POST", "/admin/enrichment-proposals/bulk-apply", input);
+    }
     /**
      * ADR-178: File a proposal sourced from open-web agent research.
      *
@@ -1804,10 +1881,12 @@ class GdprResource extends BaseResource {
 }
 class DiscoveriesResource extends BaseResource {
     /**
-     * Drain a pending discovered_credits row into a work_credits row in
-     * the caller's org. Check-and-set on status — returns
-     * DISCOVERY_ALREADY_RESOLVED (409) if another session won the race.
-     * is_first_claim=true triggers the checkout pill on the agent surface.
+     * Claim a pending discovered_credits row in the caller's org. ADR-252
+     * WS-A: this is a STATUS TRANSITION on discovered_credits — no credit
+     * row is written anywhere by this call. Check-and-set on status —
+     * returns DISCOVERY_ALREADY_RESOLVED (409) if another session won the
+     * race. is_first_claim=true triggers the checkout pill on the agent
+     * surface.
      */
     async claimCredit(id) {
         return this.request("POST", `/admin/discoveries/${encodeURIComponent(id)}/claim-credit`, {});
@@ -1825,10 +1904,13 @@ class DiscoveriesResource extends BaseResource {
         return this.request("POST", `/admin/discoveries/${encodeURIComponent(id)}/claim-custody`, {});
     }
     /**
-     * INSTANT path — drain a pending discovered_artists row into the
-     * work_claims + work_credits tables via
-     * artistClaimingService.processClaimDecision. No +72h window; identity
-     * evidence was validated at discovery time.
+     * INSTANT path — drain a pending discovered_artists row via
+     * artistClaimingService.processClaimDecision: CAS-updates work_claims
+     * and inserts the claimed performer credit. ADR-252 WS-A: a performer
+     * credit is a MASTER credit, so it lands in recording_credits (role
+     * 'Performer') on the work's sole recording — NOT the dropped
+     * work_credits table. No +72h window; identity evidence was validated
+     * at discovery time.
      *
      * Refuses with 409 ADMIN_REVIEW_IN_PROGRESS when an open artist_claims
      * row exists for the same (work, person) — see response body
@@ -1941,6 +2023,28 @@ class FeedbackResource extends BaseResource {
         return this.request("POST", "/feedback", params);
     }
 }
+class BillingResource extends BaseResource {
+    /**
+     * Mint a pay link for one offer. Minting is not charging: the link is a
+     * capability an agent POSTs with a Machine Payments credential, or a person
+     * opens in a browser and pays by card.
+     *
+     * Refusals arrive as `ApiError` carrying the route's status with its JSON
+     * body embedded in the message (the shape `duplicates.ts` and
+     * `integrity.ts` already parse): 403 `billing not enabled`; 400
+     * `nothing_held_for_entity` / `entity_id is required to unlock`; 409
+     * `offer_no_longer_applies`, whose body lists the offers that DO apply.
+     * A 403 can ALSO come from the auth wrapper in front of the route rather
+     * than the route itself (`{ error: { code: "INSUFFICIENT_SCOPE", … } }`),
+     * so status alone never identifies which refusal this is — read the body.
+     * They are deliberately not caught here — the MCP tool turns each into a
+     * structured refusal, and a resource that swallowed them would leave every
+     * other caller unable to tell a refusal from an outage.
+     */
+    async mintPayLink(params) {
+        return this.request("POST", "/admin/billing/pay-link", params);
+    }
+}
 class SubscriptionResource extends BaseResource {
     /**
      * Read the org's billing posture. Wraps the same
@@ -2282,6 +2386,49 @@ class ExportResource extends BaseResource {
         const csv = await this.requestText("GET", path);
         return { format: params.format, csv };
     }
+    /**
+     * The three diligence documents that had no agent path at all until
+     * 2026-07-30 (ADR-303). Each has had a working route and a fully-styled PDF
+     * for months, reachable only by typing the URL, because the buttons that
+     * opened them lived in the `/admin` page tree ADR-251 retired.
+     *
+     * `delivery=url` is the default here for the same reason PR 3 moved the other
+     * exports onto it: `request()` calls `response.json()`, so an inline binary ZIP
+     * cannot cross this transport. `inline` swaps to `format=json` for a sandboxed
+     * agent that cannot fetch a signed S3 URL.
+     */
+    /**
+     * The ADR-100 catalogue snapshot: score, financials, ownership coverage, gaps
+     * with a suggested action for each, physical and production assets, and a
+     * "what to do next" list.
+     *
+     * It had no agent path and no UI control — its buttons lived on the
+     * `/admin/catalog` pages ADR-251 retired, which is why an 80%-implemented
+     * "replace the nine fragments with one document" decision quietly stopped
+     * being reachable at all. Restored 2026-07-30 rather than deleted: the
+     * roadmap and the production-asset provenance exist nowhere else.
+     */
+    async picaSnapshot(params) {
+        return this.request("POST", "/admin/exports/pica", {
+            scope: params?.scope ?? "everything",
+            ...(params?.work_ids?.length ? { workIds: params.work_ids } : {}),
+        });
+    }
+    async ownershipRecord(params) {
+        return this.request("GET", `/admin/exports/ownership-record?${params?.inline ? "format=json" : "delivery=url"}`);
+    }
+    async rightsProof(params) {
+        return this.request("GET", `/admin/exports/rights-proof?${params?.inline ? "format=json" : "delivery=url"}`);
+    }
+    /**
+     * The diligence PACK (the ZIP with its PDF). Distinct from
+     * `analytics.catalogDiligence()`, which reads the same data as JSON and stays
+     * the right tool for "am I ready to register?" — a question that wants an
+     * answer, not a document.
+     */
+    async diligencePack(params) {
+        return this.request("GET", `/admin/exports/catalog-diligence?${params?.inline ? "format=json" : "delivery=url"}`);
+    }
     async songRegistration(params) {
         // Returns a signed-URL JSON envelope:
         // { success, data: { download_url, expires_at, file_size_bytes, s3_key, ... } }
@@ -2598,7 +2745,11 @@ class CollaboratorsResource extends BaseResource {
     }
     /**
      * ADR-157 warm path — accept an invite addressed to the authenticated
-     * user. Writes a real work_credits row and flips status to confirmed.
+     * user, and flip its status to confirmed. The credit write is
+     * grain-routed (ADR-265): a composition-grain invite writes
+     * work_collaborators, a master/owner-grain invite attests the person's
+     * pending recording_credits. ADR-252 WS-A dropped work_credits at
+     * DB-M3, so no row is written there.
      */
     async accept(inviteId) {
         return this.request("POST", `/admin/collaborators/invites/${inviteId}/accept`);
@@ -2954,9 +3105,14 @@ class RecordingCreditsResource extends BaseResource {
         };
     }
     /**
-     * ADR-232 atomic remove — DELETE with `?atomic=1` so the route returns 403
-     * INSUFFICIENT_SCOPE on 0-row instead of the legacy lenient silent
-     * success. AC-2 strict semantics for pica_credit_remove.
+     * ADR-232 atomic remove — the route returns 403 INSUFFICIENT_SCOPE on a
+     * 0-row delete. AC-2 strict semantics for pica_credit_remove.
+     *
+     * As of 2026-08-24 that is the route's behaviour for every caller, flagged
+     * or not; `?atomic=1` is kept only so an older published server keeps
+     * working, and is accepted-and-ignored server-side. **Remove when
+     * `@withpica/mcp-server` 2.96.0 ships (the alias-removal release)**, together
+     * with the route's param handling — the two must go in the same release.
      */
     async atomicRemove(recordingId, creditId) {
         return this.request("DELETE", `/admin/recordings/${recordingId}/credits/${creditId}?atomic=1`);
@@ -3485,7 +3641,9 @@ class ShareLinksResource extends BaseResource {
  */
 class ConsentResource extends BaseResource {
     async readiness(params) {
-        const qs = params?.limit ? `?limit=${encodeURIComponent(String(params.limit))}` : "";
+        const qs = params?.limit
+            ? `?limit=${encodeURIComponent(String(params.limit))}`
+            : "";
         return this.request("GET", `/admin/consent/readiness${qs}`);
     }
 }
@@ -3712,6 +3870,8 @@ export class PicaClient {
     licensing;
     // ADR-289 Wave C1 — internal-team booking enquiries.
     bookings;
+    // ADR-313 — live shows and tour credits.
+    shows;
     credits;
     creditsBalance;
     picaScore;
@@ -3784,6 +3944,8 @@ export class PicaClient {
     workflowOutcomes;
     feedback;
     subscription;
+    /** MPP pay rail (WS-B) — mints pay links; never charges. */
+    billing;
     opsIssues;
     discoveries;
     agentIdentity;
@@ -3826,6 +3988,7 @@ export class PicaClient {
         this.recordings = new RecordingsResource(baseUrl, config.apiKey, debug);
         this.licensing = new LicensingResource(baseUrl, config.apiKey, debug);
         this.bookings = new BookingsResource(baseUrl, config.apiKey, debug);
+        this.shows = new ShowsResource(baseUrl, config.apiKey, debug);
         this.credits = new CreditsResource(baseUrl, config.apiKey, debug);
         this.creditsBalance = new CreditsBalanceResource(baseUrl, config.apiKey, debug);
         this.picaScore = new PicaScoreResource(baseUrl, config.apiKey, debug);
@@ -3895,6 +4058,7 @@ export class PicaClient {
         this.workflowOutcomes = new WorkflowOutcomesResource(baseUrl, config.apiKey, debug);
         this.feedback = new FeedbackResource(baseUrl, config.apiKey, debug);
         this.subscription = new SubscriptionResource(baseUrl, config.apiKey, debug);
+        this.billing = new BillingResource(baseUrl, config.apiKey, debug);
         this.opsIssues = new OpsIssuesResource(baseUrl, config.apiKey, debug);
         this.discoveries = new DiscoveriesResource(baseUrl, config.apiKey, debug);
         this.agentIdentity = new AgentIdentityResource(baseUrl, config.apiKey, debug);