@withpica/mcp-sdk 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -11,6 +11,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`ConsentResource` (ADR-300)** — `pica.consent.readiness({ limit? })` → `GET /admin/consent/readiness`. Returns the org-scoped consent readiness verdict: per-level cleared / partial / blocked / unset asset counts, plus named blockers ranked refusals-first then by catalogue reach. Backs the `pica_consent_readiness` tool in `@withpica/mcp-server` 2.95.2.
+- Read-only by design: there is deliberately no consent **write** method. The per-subject consent routes refuse Bearer callers (ADR-292), because a consent decision has to be made by the person whose rights it binds rather than by an agent acting for them. Do not add one without revisiting that ADR.
+
 ## [3.10.0] - 2026-07-27
 
 ### 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;
@@ -2305,10 +2465,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 +2484,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
@@ -2826,6 +2991,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 +3219,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 +3300,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 +3540,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 +3910,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>;
     /**
@@ -4173,6 +4418,17 @@ declare class ShareLinksResource extends BaseResource {
      */
     delete(id: string): Promise<any>;
 }
+/**
+ * ADR-300 — the read side of the ADR-292 consent ledger. Read-only by
+ * design: consent WRITES stay human-session only (the per-subject consent
+ * routes refuse Bearer callers), so there is deliberately no write method
+ * on this resource.
+ */
+declare class ConsentResource extends BaseResource {
+    readiness(params?: {
+        limit?: number;
+    }): Promise<any>;
+}
 declare class CustodyResource extends BaseResource {
     claim(body: {
         work_id: string;
@@ -4407,6 +4663,7 @@ export declare class PicaClient {
     recordings: RecordingsResource;
     licensing: LicensingResource;
     bookings: BookingsResource;
+    shows: ShowsResource;
     credits: CreditsResource;
     creditsBalance: CreditsBalanceResource;
     picaScore: PicaScoreResource;
@@ -4461,6 +4718,7 @@ export declare class PicaClient {
     royalties: RoyaltiesResource;
     statements: StatementsResource;
     shareLinks: ShareLinksResource;
+    consent: ConsentResource;
     custody: CustodyResource;
     recordingCustody: RecordingCustodyResource;
     recordingSamples: RecordingSamplesResource;