@withpica/mcp-sdk 3.24.0 → 3.25.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.25.0] - 2026-10-14
+
+> **Publish order:** `asideFromReport` is imported as a value by
+> `@withpica/mcp-utils`'s billing gate. Publish this package (3.25.0) BEFORE
+> the mcp-utils release that uses it, and raise mcp-utils' range to `^3.25.0`
+> in that release; an mcp-utils on an older SDK fails at load.
+
+### Added
+
+- `asideFromReport(fn)`: run requests that still name the current client
+  catalogue, but leave them off the call's report (a check PICA makes for
+  itself, such as the billing gate reading whether the catalogue is paid for).
+- `pica.handovers`: `create` and `send` for catalogues an organisation prepares for a client
+  (`POST /admin/handovers`, `POST /admin/handovers/{id}/send`), with `HandoverCreatedRecord` and
+  `HandoverRecord`.
+- `runInCatalogue(id, fn)` → `{ value, report }` and `CatalogueCallReport` (ADR-333 D7): what the app
+  did with one call's requests in a client catalogue — how many it answered for that catalogue, and
+  each request it refused with `RELATIONSHIP_REFUSED` (path and `reason_code`, from the one
+  refusal shape: `error.code`, `error.details.reason_code`). The MCP server uses it so a tool that fails its parts soft
+  cannot answer "success" with every part refused. `withCatalogue` is unchanged for callers.
+- `withCatalogue(id, fn)`, `currentCatalogue()`, `CATALOGUE_HEADER`, `CATALOGUE_RESOLVED_HEADER` and
+  `CatalogueNotHonouredError` (ADR-333 D7). Every request made inside `withCatalogue` sends
+  `x-pica-catalogue: <id>`. A successful answer without a matching `x-pica-catalogue-resolved`
+  echo throws `CatalogueNotHonouredError` instead of reporting success, so a route that ignores
+  the header can never pass for having acted for the client. The catalogue is held per call
+  (AsyncLocalStorage), so concurrent calls on one shared client never mix catalogues.
+- `relationships` (ADR-333): `list`, `get`, `invite`, `answer`, `revoke`, `stepDown`, `events`,
+  `activity` and `acceptInvite` over `/admin/relationships/**`, with typed records
+  (`RelationshipRecord`, `RelationshipListPage`, `RelationshipEventRecord`,
+  `RelationshipStepRecord`, `ClaimableInviteRecord`). Every step sends `expected_version`.
+- `portfolio` (ADR-333): `list` and `briefing` over `/admin/portfolio`, with
+  `PortfolioClientRecord` and `PortfolioSection` (a section is checked, out of scope, unavailable
+  or failed, never a bare 0).
+- `duplicates.markDifferent(entityType, ids)` and `duplicates.unmarkDifferent(entityType, ids)`
+  for recordings and releases (`POST` / `DELETE /admin/catalog/duplicates/exclusions`).
+
 ## [3.24.0] - 2026-10-09
 
 ### Added

package/dist/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * 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`.
@@ -870,6 +866,68 @@ export declare class ApiError extends Error {
     retryAfterMs?: number | undefined;
     constructor(message: string, status: number, retryable: boolean, retryAfterMs?: number | undefined);
 }
+/**
+ * ADR-333 D7 — acting for a client catalogue, one call at a time.
+ *
+ * An organisation's assistant names the client catalogue on each tool call
+ * (the optional `catalogue` argument). The MCP server runs that call inside
+ * `withCatalogue(id, …)`, and every request the call makes carries
+ * `x-pica-catalogue: <id>`. The app resolves it through the relationship on
+ * every request (PR 1.3) and answers with `x-pica-catalogue-resolved: <id>`.
+ *
+ * A per-call context, not a field on the client: the stdio server shares one
+ * client across concurrent tool calls, so a field would leak one call's
+ * catalogue into another's requests.
+ *
+ * Fails closed: a 2xx answer without a matching echo means the route did not
+ * act for that catalogue (it may have used the caller's own), so the call
+ * throws `CatalogueNotHonouredError` instead of reporting success. This is the
+ * client's check only; stopping such a route from writing at all is the app's
+ * job (PR 1.3 refuses a catalogue header it did not resolve).
+ */
+export declare const CATALOGUE_HEADER = "x-pica-catalogue";
+export declare const CATALOGUE_RESOLVED_HEADER = "x-pica-catalogue-resolved";
+/**
+ * What the app did with one call's requests in a client catalogue: how many it
+ * answered for that catalogue, and which it refused because the route does
+ * not open through a relationship, or because the relationship does not
+ * allow it (code RELATIONSHIP_REFUSED: proxy.ts, the request-context
+ * builders, requireCatalogueContext).
+ * The MCP server reads it after the tool returns: a tool that fails its parts
+ * soft would otherwise answer "success" with every part refused.
+ */
+export interface CatalogueCallReport {
+    catalogueId: string;
+    answered: number;
+    refused: Array<{
+        path: string;
+        reason: string | null;
+    }>;
+}
+/** Run `fn` with every SDK request in it acting for `catalogueId`. */
+export declare function withCatalogue<T>(catalogueId: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * `withCatalogue`, also returning the call's report. The report is the one
+ * the call's requests wrote to; it is complete once `fn` settles.
+ */
+export declare function runInCatalogue<T>(catalogueId: string, fn: () => Promise<T>): Promise<{
+    value: T;
+    report: CatalogueCallReport;
+}>;
+/** The catalogue the current call acts for, if any. */
+export declare function currentCatalogue(): string | undefined;
+/**
+ * Run `fn` in the current client catalogue (its requests still name it), but
+ * leave its requests off the current call's report: for a check PICA makes
+ * for itself (the billing gate reading the client's plan), which must not
+ * read as the tool's own work having been answered (the MCP server judges a
+ * call "every part refused" by that report).
+ */
+export declare function asideFromReport<T>(fn: () => Promise<T>): Promise<T>;
+export declare class CatalogueNotHonouredError extends ApiError {
+    catalogueId: string;
+    constructor(catalogueId: string, path: string);
+}
 /**
  * Uniform delete outcome (mirrors the server's deletion contract). `deleted` =
  * gone; `archived` = hidden but kept (registry data / dependents preserved);
@@ -3654,6 +3712,14 @@ declare class DuplicatesResource extends BaseResource {
      */
     findDuplicates(entityType: "works" | "people" | "releases" | "recordings" | "audio_files"): Promise<any>;
     merge(entityType: "work" | "person" | "recording" | "release", winnerId: string, loserIds: string[]): Promise<any>;
+    /**
+     * "They're different": mark every pair among `ids` (2–25 recordings or
+     * releases of this catalogue) as not duplicates, so findDuplicates stops
+     * offering them. Idempotent. Resolves {entity_type, ids, pairs, changed}.
+     */
+    markDifferent(entityType: "recordings" | "releases", ids: string[]): Promise<any>;
+    /** Take back markDifferent for every pair among `ids`. */
+    unmarkDifferent(entityType: "recordings" | "releases", ids: string[]): Promise<any>;
 }
 declare class EntityContextResource extends BaseResource {
     getWorkFull(workId: string): Promise<Record<string, unknown>>;
@@ -5207,6 +5273,318 @@ declare class RightsResource extends BaseResource {
     /** GET /admin/rights-statements/measures — the four measures (ADR-321 §7a). */
     measures(): Promise<any>;
 }
+/** A relationship's scope, as the routes return it (camelCase). */
+export interface RelationshipScopeRecord {
+    half: "both" | "composition" | "master";
+    territories: string[];
+    termStartsOn: string | null;
+    termEndsOn: string | null;
+    money: boolean;
+    directory: boolean;
+    catalogue: "whole" | "chosen";
+    workIds: string[];
+    recordingIds: string[];
+}
+/**
+ * One relationship (`org_grants` row) as GET /admin/relationships returns it.
+ * `version` is passed back as `expected_version` on every step, so a step
+ * never lands on terms that changed since they were read.
+ */
+export interface RelationshipRecord {
+    id: string;
+    grantorOrgId: string;
+    grantorOrgName: string;
+    granteeOrgId: string;
+    granteeOrgName: string;
+    type: "co_owner" | "administrator" | "representative" | "viewer";
+    status: "proposed" | "active" | "declined" | "revoked" | "stepped_down" | "expired" | "suspended";
+    proposedBySide: "grantor" | "grantee";
+    scope: RelationshipScopeRecord;
+    proposedAt: string;
+    respondedAt: string | null;
+    endedAt: string | null;
+    endReason: string | null;
+    proposalExpiresAt: string | null;
+    suspendedAt: string | null;
+    version: number;
+    [key: string]: unknown;
+}
+/** An invitation waiting for the person (no address in it). */
+export interface ClaimableInviteRecord {
+    invite_id: string;
+    direction: "grantee_invites_owner" | "owner_invites_grantee";
+    inviting_org_id: string;
+    inviting_org_name: string;
+    type: RelationshipRecord["type"];
+    scope: RelationshipScopeRecord;
+    expires_at: string;
+    eligible_organisations: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface RelationshipListPage {
+    rows: RelationshipRecord[];
+    nextCursor: string | null;
+    waiting_for_you: ClaimableInviteRecord[];
+    /** Set when the waiting invitations could not be read: never "none waiting". */
+    waiting_for_you_unavailable?: "email_not_verified" | "check_failed";
+}
+/** One audit row (`org_grant_events`). */
+export interface RelationshipEventRecord {
+    id: string;
+    relationshipId: string;
+    kind: string;
+    at: string;
+    actorSide: "grantor" | "grantee" | "system" | "platform";
+    actorDisplayName: string | null;
+    grantorOrgId: string;
+    grantorOrgName: string;
+    granteeOrgId: string;
+    granteeOrgName: string;
+    type: RelationshipRecord["type"];
+    typeBefore: RelationshipRecord["type"] | null;
+    statusBefore: RelationshipRecord["status"] | null;
+    statusAfter: RelationshipRecord["status"];
+    version: number;
+    /** The scope before this event (null for `proposed`). */
+    scopeBefore: RelationshipScopeRecord | null;
+    /** The scope after this event (for an ending: the scope that ended). */
+    scope: RelationshipScopeRecord;
+    reason: string | null;
+    action: string | null;
+    entityType: string | null;
+    entityId: string | null;
+    detail: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface RelationshipPageOf<T> {
+    rows: T[];
+    nextCursor: string | null;
+}
+/** The result of accepting, declining, editing, revoking or stepping down. */
+export interface RelationshipStepRecord {
+    relationship: RelationshipRecord;
+    event: RelationshipEventRecord | null;
+}
+/** The result of accepting an invitation: the claim and the accept, both recorded. */
+export interface RelationshipInviteAcceptRecord {
+    relationship: RelationshipRecord;
+    events: RelationshipEventRecord[];
+}
+/** A hand-over just created (ADR-333 D5): nothing is sent yet. */
+export interface HandoverCreatedRecord {
+    handover_id: string;
+    catalogue_org_id: string;
+}
+/** A hand-over as its builder sees it (POST /admin/handovers/{id}/send). */
+export interface HandoverRecord {
+    handover_id: string;
+    catalogue_org_id: string;
+    catalogue_name: string | null;
+    builder_org_id: string;
+    builder_name: string | null;
+    client_name: string;
+    client_email?: string;
+    status: string;
+    relationship_type: string;
+    sent_at: string | null;
+    expires_at: string | null;
+    version: number;
+}
+/**
+ * Catalogues an organisation builds for a client, who accepts to own them
+ * (ADR-333 D5). Builder side only: the client answers on screen, signed in.
+ */
+declare class HandoversResource extends BaseResource {
+    /**
+     * POST /admin/handovers — create a catalogue for a client
+     * (catalogue_name), or a new hand-over on one this organisation built whose
+     * last one closed (catalogue_org_id). Nothing is sent.
+     */
+    create(body: {
+        catalogue_name?: string;
+        catalogue_org_id?: string;
+        client_name: string;
+        client_email: string;
+        relationship_type: string;
+    }): Promise<HandoverCreatedRecord>;
+    /** POST /admin/handovers/{id}/send { expected_version? } — email the client. */
+    send(id: string, body: {
+        expected_version?: number;
+    }): Promise<HandoverRecord>;
+}
+/**
+ * /admin/relationships/** — both sides of a relationship. Refusals arrive as
+ * `{ success: false, error: { code, message, details? } }` (read them with
+ * the MCP package's parseApiErrorBody); a step whose terms changed since they
+ * were read is a 409 `status_changed` carrying `details.relationship`.
+ */
+declare class RelationshipsResource extends BaseResource {
+    /** GET /admin/relationships?side=owner|organisation&status=&cursor=&limit= */
+    list(params: {
+        side: "owner" | "organisation";
+        statuses?: string[];
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipListPage>;
+    /** GET /admin/relationships/{id} */
+    get(id: string): Promise<RelationshipRecord>;
+    /**
+     * POST /admin/relationships { as, email, type, scope? } — invite someone by
+     * email. as="owner" asks someone at an organisation to look after this
+     * catalogue; as="organisation" asks a client to let this organisation look
+     * after theirs. The reply is the same whether or not the address is on PICA.
+     */
+    invite(body: {
+        as: "owner" | "organisation";
+        email: string;
+        type: string;
+        scope?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** PATCH /admin/relationships/{id} { action: accept | decline | edit, expected_version, … } */
+    answer(id: string, body: {
+        action: "accept" | "decline" | "edit";
+        expected_version: number;
+        type?: string;
+        scope?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** DELETE /admin/relationships/{id} { expected_version, reason? } — the owner ends it. */
+    revoke(id: string, body: {
+        expected_version: number;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** POST /admin/relationships/{id}/step-down { expected_version, reason? } — the organisation ends its side. */
+    stepDown(id: string, body: {
+        expected_version: number;
+        reason?: string;
+    }): Promise<RelationshipStepRecord>;
+    /** GET /admin/relationships/{id}/activity — one relationship's history, either party. */
+    events(id: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipPageOf<RelationshipEventRecord>>;
+    /**
+     * GET /admin/relationships/activity?side=&org= — side=owner: what
+     * organisations did in this catalogue (org = one organisation);
+     * side=organisation: this organisation's own actions (org = one catalogue).
+     */
+    activity(params: {
+        side: "owner" | "organisation";
+        org?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<RelationshipPageOf<RelationshipEventRecord>>;
+    /**
+     * PATCH /admin/relationships/invites/{id} { action: "accept", organisation_id, type?, scope? }
+     * — answer yes to an invitation for one of the person's organisations.
+     */
+    acceptInvite(inviteId: string, body: {
+        organisation_id: string;
+        type?: string;
+        scope?: Record<string, unknown>;
+    }): Promise<RelationshipInviteAcceptRecord>;
+}
+/** A portfolio section: checked, out of scope, unavailable, or failed (never 0). */
+export type PortfolioSection<T> = {
+    state: "ok";
+    data: T;
+} | {
+    state: "not_in_scope" | "unavailable" | "failed";
+    reason: string;
+};
+/** One client catalogue an organisation looks after (portfolio PR 1.4). */
+export interface PortfolioClientRecord {
+    relationshipId: string;
+    catalogue: {
+        orgId: string;
+        name: string;
+    };
+    relationship: {
+        type: RelationshipRecord["type"];
+        typeLabel: string;
+        status: "active" | "suspended";
+        access: "open" | "paused" | "not_started";
+        acceptedAt: string | null;
+        termEndsOn: string | null;
+        endingSoon: boolean;
+        version: number;
+        /** What a change by this caller does in that catalogue. */
+        changes: "direct" | "proposal" | "none";
+        scope: {
+            half: RelationshipScopeRecord["half"];
+            territories: string[];
+            termStartsOn: string | null;
+            termEndsOn: string | null;
+            money: boolean;
+            directory: boolean;
+            catalogue: "whole" | "chosen";
+            songsChosen: number;
+            recordingsChosen: number;
+        };
+    };
+    /** null = the scope doesn't cover that half ("not covered", never 0). */
+    missing: PortfolioSection<{
+        songs: number | null;
+        songsWithGaps: number | null;
+        recordings: number | null;
+        recordingsWithGaps: number | null;
+    }>;
+    moneyBlockers: PortfolioSection<{
+        songs: number;
+        blocked: number;
+        clear: number;
+        unknown: number;
+        byCode: Array<{
+            code: string;
+            label: string;
+            songs: number;
+        }>;
+    }>;
+    enquiries: PortfolioSection<{
+        waiting: number;
+        oldestAt: string | null;
+    }>;
+    deadlines: PortfolioSection<{
+        total: number;
+        items: Array<{
+            kind: string;
+            on: string;
+            label: string;
+        }>;
+    }>;
+    /** Briefing only: at most five, in scope only. */
+    highlights?: Array<{
+        kind: string;
+        label: string;
+        workId?: string;
+        recordingId?: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface PortfolioPage {
+    rows: PortfolioClientRecord[];
+    nextCursor: string | null;
+    asOf: string;
+}
+/**
+ * /admin/portfolio — the client catalogues an organisation looks after. A
+ * page may hold fewer rows than `limit` and still not be the last: follow
+ * `nextCursor` until it is null.
+ */
+declare class PortfolioResource extends BaseResource {
+    /** GET /admin/portfolio?cursor=&limit= (limit ≤ 25) */
+    list(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PortfolioPage>;
+    /** GET /admin/portfolio/briefing?cursor=&limit= — the list plus what needs attention. */
+    briefing(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PortfolioPage>;
+}
 declare class RoyaltiesResource extends BaseResource {
     payments(params?: {
         source?: string;
@@ -5748,6 +6126,11 @@ export declare class PicaClient {
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;
     royalties: RoyaltiesResource;
+    /** ADR-333 — who looks after whose catalogue, from either side. */
+    relationships: RelationshipsResource;
+    handovers: HandoversResource;
+    /** ADR-333 — the client catalogues an organisation looks after. */
+    portfolio: PortfolioResource;
     /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
     rights: RightsResource;
     statements: StatementsResource;