@withpica/mcp-sdk 3.24.0 → 3.25.0

package/dist/index.js

@@ -1,5 +1,10 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Lightweight PICA SDK client for MCP server
+ * Uses the PICA API directly without external dependencies
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
 // --- Request infrastructure ---
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LONG_TIMEOUT_MS = 120_000;
@@ -32,6 +37,98 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
+/**
+ * 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 const CATALOGUE_HEADER = "x-pica-catalogue";
+export const CATALOGUE_RESOLVED_HEADER = "x-pica-catalogue-resolved";
+const catalogueContext = new AsyncLocalStorage();
+/** Run `fn` with every SDK request in it acting for `catalogueId`. */
+export function withCatalogue(catalogueId, fn) {
+    return catalogueId
+        ? runInCatalogue(catalogueId, fn).then((r) => r.value)
+        : fn();
+}
+/**
+ * `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 async function runInCatalogue(catalogueId, fn) {
+    const report = {
+        catalogueId,
+        answered: 0,
+        refused: [],
+    };
+    const value = await catalogueContext.run(report, fn);
+    return { value, report };
+}
+/** The catalogue the current call acts for, if any. */
+export function currentCatalogue() {
+    return catalogueContext.getStore()?.catalogueId;
+}
+/**
+ * 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 function asideFromReport(fn) {
+    const current = catalogueContext.getStore();
+    if (!current)
+        return fn();
+    return catalogueContext.run({ catalogueId: current.catalogueId, answered: 0, refused: [] }, fn);
+}
+/**
+ * Record a relationship refusal on the current call's report (no-op outside
+ * one). Every client-catalogue refusal, from the proxy or a route, answers
+ * `{ success: false, error: { code, message, details: { reason_code } } }`
+ * (catalogueRefusalBody, lib/auth/relationship-refused-error.ts; pinned by
+ * lib/auth/__tests__/catalogue-refusal-shape.test.ts).
+ */
+function recordCatalogueRefusal(url, body) {
+    const report = catalogueContext.getStore();
+    if (!report)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return;
+    }
+    if (parsed?.error?.code !== "RELATIONSHIP_REFUSED")
+        return;
+    const reason = parsed.error.details?.reason_code;
+    report.refused.push({
+        path: new URL(url).pathname,
+        reason: typeof reason === "string" ? reason : null,
+    });
+}
+export class CatalogueNotHonouredError extends ApiError {
+    catalogueId;
+    constructor(catalogueId, path) {
+        super(`This action can't be done for a client's catalogue yet, so nothing was done for catalogue ${catalogueId} (${path}).`, 0, false);
+        this.catalogueId = catalogueId;
+        this.name = "CatalogueNotHonouredError";
+    }
+}
 /**
  * Thrown when the API responds 404 — the entity at the given id either
  * doesn't exist or doesn't belong to the caller's org. Distinguished from
@@ -106,9 +203,30 @@ class BaseResource {
         const timingOn = typeof process !== "undefined" && process.env?.PICA_SDK_TIMING === "1";
         const t0 = timingOn ? Date.now() : 0;
         let statusForTiming = 0;
+        const catalogueId = currentCatalogue();
+        const headers = catalogueId
+            ? {
+                ...init.headers,
+                [CATALOGUE_HEADER]: catalogueId,
+            }
+            : init.headers;
         try {
-            const res = await fetch(url, { ...init, signal: controller.signal });
+            const res = await fetch(url, {
+                ...init,
+                headers,
+                signal: controller.signal,
+            });
             statusForTiming = res.status;
+            if (catalogueId &&
+                res.ok &&
+                res.headers.get(CATALOGUE_RESOLVED_HEADER) !== catalogueId) {
+                throw new CatalogueNotHonouredError(catalogueId, new URL(url).pathname);
+            }
+            if (catalogueId && res.ok) {
+                const report = catalogueContext.getStore();
+                if (report)
+                    report.answered += 1;
+            }
             return res;
         }
         catch (err) {
@@ -142,6 +260,7 @@ class BaseResource {
                 if (response.ok)
                     return response;
                 const errorText = await response.text();
+                recordCatalogueRefusal(url, errorText);
                 // Auth errors — fail fast, never retry
                 if (response.status === 401 || response.status === 403) {
                     throw new ApiError(`Authentication failed: ${response.status} ${errorText}`, response.status, false);
@@ -2775,6 +2894,24 @@ class DuplicatesResource extends BaseResource {
             loser_ids: loserIds,
         });
     }
+    /**
+     * "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}.
+     */
+    async markDifferent(entityType, ids) {
+        return this.request("POST", "/admin/catalog/duplicates/exclusions", {
+            entity_type: entityType,
+            ids,
+        });
+    }
+    /** Take back markDifferent for every pair among `ids`. */
+    async unmarkDifferent(entityType, ids) {
+        return this.request("DELETE", "/admin/catalog/duplicates/exclusions", {
+            entity_type: entityType,
+            ids,
+        });
+    }
 }
 // --- Entity Context Resource (ADR-116 Phase 3) ---
 class EntityContextResource extends BaseResource {
@@ -4040,6 +4177,113 @@ class RightsResource extends BaseResource {
         return this.request("GET", "/admin/rights-statements/measures");
     }
 }
+function pageQuery(params) {
+    const qp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            value.forEach((v) => qp.append(key, v));
+        else
+            qp.set(key, String(value));
+    }
+    const qs = qp.toString();
+    return qs ? `?${qs}` : "";
+}
+/**
+ * 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.
+ */
+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.
+     */
+    async create(body) {
+        return this.request("POST", "/admin/handovers", body);
+    }
+    /** POST /admin/handovers/{id}/send { expected_version? } — email the client. */
+    async send(id, body) {
+        return this.request("POST", `/admin/handovers/${encodeURIComponent(id)}/send`, body);
+    }
+}
+/**
+ * /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`.
+ */
+class RelationshipsResource extends BaseResource {
+    /** GET /admin/relationships?side=owner|organisation&status=&cursor=&limit= */
+    async list(params) {
+        return this.request("GET", `/admin/relationships${pageQuery({
+            side: params.side,
+            status: params.statuses,
+            cursor: params.cursor,
+            limit: params.limit,
+        })}`);
+    }
+    /** GET /admin/relationships/{id} */
+    async get(id) {
+        return this.request("GET", `/admin/relationships/${encodeURIComponent(id)}`);
+    }
+    /**
+     * 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.
+     */
+    async invite(body) {
+        return this.request("POST", "/admin/relationships", body);
+    }
+    /** PATCH /admin/relationships/{id} { action: accept | decline | edit, expected_version, … } */
+    async answer(id, body) {
+        return this.request("PATCH", `/admin/relationships/${encodeURIComponent(id)}`, body);
+    }
+    /** DELETE /admin/relationships/{id} { expected_version, reason? } — the owner ends it. */
+    async revoke(id, body) {
+        return this.request("DELETE", `/admin/relationships/${encodeURIComponent(id)}`, body);
+    }
+    /** POST /admin/relationships/{id}/step-down { expected_version, reason? } — the organisation ends its side. */
+    async stepDown(id, body) {
+        return this.request("POST", `/admin/relationships/${encodeURIComponent(id)}/step-down`, body);
+    }
+    /** GET /admin/relationships/{id}/activity — one relationship's history, either party. */
+    async events(id, params = {}) {
+        return this.request("GET", `/admin/relationships/${encodeURIComponent(id)}/activity${pageQuery(params)}`);
+    }
+    /**
+     * 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).
+     */
+    async activity(params) {
+        return this.request("GET", `/admin/relationships/activity${pageQuery(params)}`);
+    }
+    /**
+     * PATCH /admin/relationships/invites/{id} { action: "accept", organisation_id, type?, scope? }
+     * — answer yes to an invitation for one of the person's organisations.
+     */
+    async acceptInvite(inviteId, body) {
+        return this.request("PATCH", `/admin/relationships/invites/${encodeURIComponent(inviteId)}`, { action: "accept", ...body });
+    }
+}
+/**
+ * /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.
+ */
+class PortfolioResource extends BaseResource {
+    /** GET /admin/portfolio?cursor=&limit= (limit ≤ 25) */
+    async list(params = {}) {
+        return this.request("GET", `/admin/portfolio${pageQuery(params)}`);
+    }
+    /** GET /admin/portfolio/briefing?cursor=&limit= — the list plus what needs attention. */
+    async briefing(params = {}) {
+        return this.request("GET", `/admin/portfolio/briefing${pageQuery(params)}`);
+    }
+}
 class RoyaltiesResource extends BaseResource {
     async payments(params) {
         const qp = new URLSearchParams();
@@ -4542,6 +4786,11 @@ export class PicaClient {
     producerAgreements;
     workForHire;
     royalties;
+    /** ADR-333 — who looks after whose catalogue, from either side. */
+    relationships;
+    handovers;
+    /** ADR-333 — the client catalogues an organisation looks after. */
+    portfolio;
     /** ADR-321 Phase 2 — programmable rights (propose / status / inspect). */
     rights;
     statements;
@@ -4653,6 +4902,9 @@ export class PicaClient {
         this.producerAgreements = new ProducerAgreementsResource(baseUrl, config.apiKey, debug);
         this.workForHire = new WorkForHireResource(baseUrl, config.apiKey, debug);
         this.royalties = new RoyaltiesResource(baseUrl, config.apiKey, debug);
+        this.relationships = new RelationshipsResource(baseUrl, config.apiKey, debug);
+        this.handovers = new HandoversResource(baseUrl, config.apiKey, debug);
+        this.portfolio = new PortfolioResource(baseUrl, config.apiKey, debug);
         this.rights = new RightsResource(baseUrl, config.apiKey, debug);
         this.statements = new StatementsResource(baseUrl, config.apiKey, debug);
         this.selections = new SelectionsResource(baseUrl, config.apiKey, debug);