@withpica/mcp-sdk 3.11.0 → 3.13.0

package/CHANGELOG.md

@@ -11,6 +11,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.13.0] - 2026-08-26
+
+The MPP pay rail (spec 2026-08-24 WS-B): a new resource to mint a pay link,
+and two optional fields on the existing subscription-status response so a
+client can say what pica costs and what it is holding.
+
+### Added
+
+- **`BillingResource.mintPayLink()` on `PicaClient.billing`.** Wraps
+  `POST /admin/billing/pay-link`. Takes `{ offer: PayOffer; entity_id?: string }`
+  and returns a `PayLinkResponse` (`pay_url`, `expires_at`, `offer`, `offers`,
+  `held`, `how`) — the route's own envelope, since this route has no
+  `{success, data}` wrapper. 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` (403 billing not
+  enabled; 400 `nothing_held_for_entity` / entity_id required; 409
+  `offer_no_longer_applies` with the offers that do apply) and are
+  deliberately not caught inside the resource — callers decide what each
+  refusal means.
+- **New exported types**: `PayOffer` (`"resident_month" | "unlock" | "settle"`),
+  `PayLinkOffer` (`{ offer, amount_minor, currency, label }`), `PayLinkResponse`,
+  `HeldSummary` (`{ count, entities }`), `PricingSummary` (`currency`,
+  `freeRunwayDeepProcesses`, `residentFeeMinorUnits`,
+  `residentIncludedDeepProcesses`, `overagePerSongMinorUnits`,
+  `overageCurrency`, `unlockMinorUnits`).
+- **`SubscriptionStatusResponse` gains optional `pricing?: PricingSummary | null`
+  and `held?: HeldSummary | null`.** Both are `null` when billing enforcement
+  is off on the deployment, and absent entirely against a deployment whose
+  route predates the fields — consumers must read "no pricing" as "do not
+  state a price," never as "free."
+
+## [3.12.0] - 2026-08-25
+
+Adds the ADR-314 import continuation surface (below); everything else is documentation — no other method signature, request path or response shape changes.
+
+### Added
+
+- `ImportResult.rowRange` and `imports.execute()` options `rowOffset` / `rowLimit` — the ADR-314 continuation cursor: the server imports one slice per call (default 2,000 rows) and returns `nextOffset` until the file is done.
+- `ImportResult.partial` — set by `POST /admin/import/execute` when a live run wrote rows and some rows failed (a batch import is not transactional; the written rows are committed). `imports.execute()` options gain `conflictStrategy?: "skip" | "error"` (server default now `"skip"`). Error entries are typed with the server's real `error` field alongside `message`, and `severity`.
+
+### Fixed
+
+- **Five docstrings described a table that was dropped 2026-05-29.** ADR-252 WS-A DB-M3 dropped both the `work_credits` view and the `work_credits_legacy` table, but these docstrings still told the reader a row lands there. Each now names the canonical home the code actually writes to:
+  - `CreditsResource.atomicAdd` cited `replace_work_credits` — a retired RPC — as the non-atomic alternative. It now names the live comparison (the work-level `POST /credits` additive upsert) and says where the row lands: publishing roles to `work_collaborators`, master attribution to `recording_credits`, owner to `recording_splits`.
+  - `DiscoveriesResource.claimCredit` said it drains a `discovered_credits` row **into a `work_credits` row**. It does not write a credit row anywhere — the claim is a status transition on `discovered_credits`, which is what the backing route's own provenance stamp records.
+  - `DiscoveriesResource.claimArtist` said `work_claims` + `work_credits`. `work_claims` is right; the claimed performer credit is a MASTER credit and lands in `recording_credits` with role `Performer` on the work's sole recording.
+  - `CollaboratorsResource.accept` said it "writes a real `work_credits` row". 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`.
+  - The `RecordingCredit` orientation comment distinguished this resource from "CreditsResource (`work_credits` / `work_collaborators`)" — now `work_collaborators` / `recording_splits`.
+
+> Verified by sweep, not by eye: every snake_case identifier in a comment in `src/index.ts` was cross-checked against the 398 tables and views in the generated database types. `work_credits` was the **only** name with no schema entry, at exactly these sites. Every other table named in a docstring exists, and each write claim was re-read against the route it calls.
+
 ## [3.11.0] - 2026-07-28
 
 ### Added

package/dist/index.d.ts

@@ -175,7 +175,14 @@ export interface ResolvePersonResult {
 export type BillingTier = "solo" | "indie" | "pro" | "established" | "enterprise";
 export interface BillingSlice {
     billing_state: "trial" | "active" | "hibernated";
-    trial_days_remaining: number | null;
+    /**
+     * free_runway (walked in, never charged, no clock) | resident (paying one
+     * flat fee per 30-day cycle) | paused (a cycle lapsed, deep-processing off).
+     *
+     * ⚠️ Replaced `trial_days_remaining` on 2026-08-21 — pica has no trial, and
+     * that field reported null for every organisation while implying one existed.
+     */
+    plan: "free_runway" | "resident" | "paused";
     current_tier: BillingTier | null;
     capacity_pct: number;
 }
@@ -1215,6 +1222,83 @@ declare class BookingsResource extends BaseResource {
         followUpDate?: string;
     }): Promise<BookingEnquiry>;
 }
+/**
+ * Payload accepted by `POST /admin/shows` — a dated show (venue + date +
+ * setlist) OR a tour credit (act + year + role); the route picks which by
+ * which fields are present. Mirrors `ShowPayload` in
+ * app/api/admin/shows/route.ts (not imported — this package is standalone).
+ */
+interface ShowLogPayload {
+    venue?: string;
+    city?: string;
+    country?: string;
+    date?: string;
+    act?: string;
+    performed_by_person_id?: string;
+    slot?: string;
+    setlist?: string[];
+    set_number?: number;
+    attendance?: number;
+    logged_as?: "act" | "contributor";
+    year?: number;
+    role?: string;
+    tour_name?: string;
+    person_id?: string;
+    email?: string;
+    contributors?: Array<{
+        name?: string;
+        email?: string;
+        person_id?: string;
+        role: string;
+        is_crew?: boolean;
+    }>;
+}
+/**
+ * `GET /admin/shows` query params — list the org's shows (newest first,
+ * optionally filtered), or fetch one show plus its folded-in setlist when
+ * `id` is given. Mirrors the route's `queryShows` filter set.
+ */
+interface ShowQueryParams {
+    id?: string;
+    from?: string;
+    to?: string;
+    venue?: string;
+    city?: string;
+    country?: string;
+    unfiled_only?: boolean;
+}
+/**
+ * `PATCH /admin/setlist-items/[id]` payload — confirms what a setlist line
+ * actually was (work match, cover flag, performer) and, when `venue_id` +
+ * `show_id` are both present, the show's venue candidate. Both are applied
+ * when both are supplied; the response carries `venue` and `item`, either of
+ * which may be null.
+ */
+interface SetlistItemConfirmPayload {
+    work_id?: string;
+    is_cover?: boolean;
+    performed_by?: string;
+    venue_id?: string;
+    show_id?: string;
+}
+/**
+ * Live shows and tour credits (ADR-313). Wraps `/admin/shows` and
+ * `/admin/setlist-items/[id]`.
+ */
+declare class ShowsResource extends BaseResource {
+    /** POST /admin/shows — log a dated show, or a tour credit. */
+    log(payload: ShowLogPayload): Promise<unknown>;
+    /**
+     * GET /admin/shows — list shows for the org (newest first), or the single
+     * show + its folded-in setlist when `id` is given.
+     */
+    query(params?: ShowQueryParams): Promise<unknown>;
+    /**
+     * PATCH /admin/setlist-items/[id] — confirm a setlist match, a cover, a
+     * performer, or (with `venue_id` + `show_id`) a venue candidate.
+     */
+    matchItem(id: string, payload: SetlistItemConfirmPayload): Promise<unknown>;
+}
 export interface WorkCreditAtomicAddInput {
     person_id: string;
     credit_type?: "writer" | "composer" | "arranger" | "lyricist" | "producer" | "performer" | "engineer" | "mixer" | "mastering" | "owner" | "vocalist" | "instrumentalist" | "conductor" | "programmer" | "remixer";
@@ -1233,9 +1317,14 @@ declare class CreditsResource extends BaseResource {
     listCollaborators(workId: string): Promise<WorkCredit[]>;
     updateCollaborators(workId: string, collaborators: WorkCreditsInput): Promise<WorkCredit[]>;
     /**
-     * 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.
      */
     atomicAdd(workId: string, input: WorkCreditAtomicAddInput): Promise<AtomicCreditResult>;
     /**
@@ -1902,6 +1991,14 @@ declare 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.
      */
@@ -1918,6 +2015,16 @@ declare class EnrichmentResource extends BaseResource {
         max_confidence?: number;
         /** ADR-264 C1: only return proposals created at or after this ISO timestamp */
         created_after?: string;
+        /**
+         * Additionally return `groups` — the interpreted review shape the
+         * /inspect/found page renders (grouped, confidence-banded, before/after
+         * field changes, evidence lines, external refs, per-item actionable /
+         * bulkEligible), read through the FOUND_SOURCES registry.
+         *
+         * ⚠️ `groups` is the WHOLE reviewable queue and is NOT narrowed by the
+         * filters above, which only apply to `proposals`.
+         */
+        review_shape?: boolean;
     }): Promise<any>;
     /**
      * Apply a pending proposal. For update proposals, drift detection
@@ -1963,6 +2070,48 @@ declare class EnrichmentResource extends BaseResource {
         rejected: number;
         skipped: string[];
     }>;
+    /**
+     * 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.
+     */
+    bulkApplyProposals(input: {
+        proposal_ids: string[];
+        /**
+         * ADR-180 Rule 12 preview. When true the server writes NOTHING and answers
+         * `{ dry_run: true, would_affect, not_pending }` instead of the apply
+         * shape — so callers must branch on `dry_run` rather than reading
+         * `applied`, which is absent from a preview.
+         */
+        dry_run?: boolean;
+    }): Promise<{
+        applied?: number;
+        failed?: Array<{
+            id: string;
+            error: string;
+        }>;
+        skipped?: string[];
+        dry_run?: boolean;
+        would_affect?: number;
+        not_pending?: Array<{
+            id: string;
+            error: string;
+        }>;
+    }>;
     /**
      * ADR-178: File a proposal sourced from open-web agent research.
      *
@@ -2022,6 +2171,17 @@ declare class RegistrationResource extends BaseResource {
 export interface CatalogHealthItem {
     grain: "work" | "recording" | "release" | "person";
     issue: string;
+    /**
+     * A sentence a person would recognise ("recordings sharing an ISRC with
+     * another recording"), or null when the issue has no wording yet.
+     *
+     * ⚠️ SAY THIS, NOT `issue`. A bare key relayed to a user reads as
+     * "junk_person" — the failure recorded in `.claude/rules/canonical-model.md`,
+     * where an agent said "WORK_NO_WRITER" out loud because a narrowing adapter
+     * dropped the only human-readable field. `issue` stays for arguments
+     * (`catalogHealthPlan({only: [...]})` selects on it); label is for prose.
+     */
+    label: string | null;
     dimension: "completeness" | "cleanliness";
     severity: "high" | "medium" | "low";
     count: number;
@@ -2036,6 +2196,11 @@ export interface CatalogHealthVerdict {
         completeness: number | null;
         cleanliness: number | null;
     };
+    /** entities considered per dimension — what each dimension score is a share of; null iff that score is null (2026-08-26) */
+    dimensionConsidered: {
+        completeness: number | null;
+        cleanliness: number | null;
+    };
     assessed: string[];
     notAssessed: string[];
     items: CatalogHealthItem[];
@@ -2305,10 +2470,12 @@ export interface AcknowledgeNotificationsResponse {
 }
 declare 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.
      */
     claimCredit(id: string): Promise<ClaimCreditResponse>;
     /**
@@ -2322,10 +2489,13 @@ declare class DiscoveriesResource extends BaseResource {
      */
     claimCustody(id: string): Promise<ClaimCustodyResponse>;
     /**
-     * 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
@@ -2507,6 +2677,97 @@ export interface SubscriptionStatusResponse {
         recommendedTier: BillingTier;
     } | null;
     organisationId: string;
+    /**
+     * The org's price card, in its own billing currency. `null` when billing
+     * enforcement is off on this deployment, and ABSENT against a deployment
+     * whose route predates the field — hence both `?` and `| null`. Consumers
+     * must read "no pricing" as "do not state a price", never as "free".
+     */
+    pricing?: PricingSummary | null;
+    /**
+     * How much enrichment is being withheld pending payment. Same two-shaped
+     * absence as `pricing` above.
+     */
+    held?: HeldSummary | null;
+}
+/**
+ * The three things a caller can be asked to pay for. Mirrors `PayOffer` in
+ * `lib/services/billing-engine/pay-link.ts`; the route 400s on anything else,
+ * so this union is the wire contract rather than a convenience.
+ */
+export type PayOffer = "resident_month" | "unlock" | "settle";
+/**
+ * One priced offer as the routes publish it. The server composes `label`,
+ * which already carries the formatted money — a client that re-words the
+ * amount out of `amount_minor` becomes a second home for the price, which is
+ * what `publicOffer` exists to prevent on the server side.
+ */
+export interface PayLinkOffer {
+    offer: PayOffer;
+    amount_minor: number;
+    currency: string;
+    label: string;
+}
+/** Findings pica is holding: `count` proposals across `entities` works. */
+export interface HeldSummary {
+    count: number;
+    entities: number;
+}
+/**
+ * Every figure a reader of "what does pica cost" needs, derived server-side
+ * from the constants that are actually charged (`pricingSummary()`).
+ *
+ * `overagePerSongMinorUnits` is denominated in `overageCurrency`, NOT
+ * `currency` — the overage is charged in the canonical currency until
+ * per-currency event pricing lands. The two fields are separate for that
+ * reason; collapsing them would misprice every non-GBP org.
+ */
+export interface PricingSummary {
+    currency: string;
+    freeRunwayDeepProcesses: number;
+    residentFeeMinorUnits: number;
+    residentIncludedDeepProcesses: number;
+    overagePerSongMinorUnits: number;
+    overageCurrency: string;
+    unlockMinorUnits: number;
+}
+/**
+ * `POST /admin/billing/pay-link`. There is no `{success, data}` envelope on
+ * this route — the body IS the response, so `BaseResource.request`'s
+ * `data.data || data` returns it whole.
+ */
+export interface PayLinkResponse {
+    pay_url: string;
+    expires_at: string;
+    offer: PayOffer;
+    /** Every offer that currently applies, including the one minted. */
+    offers: PayLinkOffer[];
+    held: HeldSummary;
+    /** One sentence naming both ways the link can be paid. */
+    how: string;
+}
+declare 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.
+     */
+    mintPayLink(params: {
+        offer: PayOffer;
+        entity_id?: string;
+    }): Promise<PayLinkResponse>;
 }
 /**
  * ADR-210 Phase 2 — Stripe Checkout session output for
@@ -2826,6 +3087,47 @@ declare class ExportResource extends BaseResource {
         work_id?: string;
         work_ids?: string[];
     }): Promise<any>;
+    /**
+     * 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.
+     */
+    picaSnapshot(params?: {
+        scope?: "everything" | "selected" | "work";
+        work_ids?: string[];
+    }): Promise<any>;
+    ownershipRecord(params?: {
+        inline?: boolean;
+    }): Promise<any>;
+    rightsProof(params?: {
+        inline?: boolean;
+    }): Promise<any>;
+    /**
+     * 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.
+     */
+    diligencePack(params?: {
+        inline?: boolean;
+    }): Promise<any>;
     songRegistration(params?: {
         iswc_status?: "missing" | "present" | "all";
         work_ids?: string[];
@@ -3013,11 +3315,33 @@ interface ImportResult {
     errors: Array<{
         row: number;
         field: string;
-        message: string;
+        /** The server's ValidationError carries the text in `error`; `message`
+         *  is kept for callers that normalised it. Read `error ?? message`. */
+        error?: string;
+        message?: string;
+        /** "error" = the row did not land; "warning" = skipped duplicate etc. */
         severity: string;
     }>;
     summary: string;
     dryRun: boolean;
+    /**
+     * True when a LIVE run wrote rows AND some rows failed with severity
+     * "error" (a batch import is not transactional — the written rows are
+     * committed). Set by POST /admin/import/execute; false for a clean run,
+     * a dry run, or a run whose only "errors" are warnings.
+     */
+    partial?: boolean;
+    /**
+     * Which slice of the file this call imported (ADR-314). `nextOffset` is
+     * the `rowOffset` to pass next, or null when the file is done.
+     */
+    rowRange?: {
+        offset: number;
+        limit: number;
+        count: number;
+        totalRowsInFile: number;
+        nextOffset: number | null;
+    };
 }
 /**
  * Source of CSV content — exactly one must be provided:
@@ -3072,6 +3396,14 @@ declare class ImportResource extends BaseResource {
             dryRun?: boolean;
             skipInvalidRows?: boolean;
             batchSize?: number;
+            /** "skip" (server default): a row that trips a unique constraint
+             *  becomes a warning, the rest of its batch still lands.
+             *  "error": one collision fails the whole batch. */
+            conflictStrategy?: "skip" | "error";
+            /** First data row to import, 0-based (default 0). ADR-314 cursor. */
+            rowOffset?: number;
+            /** Rows to import in this call (server default 2,000, max 10,000). */
+            rowLimit?: number;
         };
     }): Promise<ImportResult>;
     getFields(domain: ImportDomain): Promise<Array<{
@@ -3304,7 +3636,11 @@ declare 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.
      */
     accept(inviteId: string): Promise<Record<string, unknown>>;
     /**
@@ -3670,9 +4006,14 @@ declare class RecordingCreditsResource extends BaseResource {
      */
     atomicAdd(recordingId: string, input: RecordingCreditCreateInput): Promise<AtomicCreditResult>;
     /**
-     * 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.
      */
     atomicRemove(recordingId: string, creditId: string): Promise<AtomicCreditResult>;
     /**
@@ -4418,6 +4759,7 @@ export declare class PicaClient {
     recordings: RecordingsResource;
     licensing: LicensingResource;
     bookings: BookingsResource;
+    shows: ShowsResource;
     credits: CreditsResource;
     creditsBalance: CreditsBalanceResource;
     picaScore: PicaScoreResource;
@@ -4486,6 +4828,8 @@ export declare class PicaClient {
     workflowOutcomes: WorkflowOutcomesResource;
     feedback: FeedbackResource;
     subscription: SubscriptionResource;
+    /** MPP pay rail (WS-B) — mints pay links; never charges. */
+    billing: BillingResource;
     opsIssues: OpsIssuesResource;
     discoveries: DiscoveriesResource;
     agentIdentity: AgentIdentityResource;