@withpica/mcp-sdk 3.12.0 → 3.14.0

package/CHANGELOG.md

@@ -11,6 +11,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+PR #2118 (`fix/avatar-import-path-2026-09-03`) is merged into the release branch, so its changes ship in the version below; publish in the order mcp-utils → mcp-sdk → mcp-server.
+
+## [3.14.0] - 2026-09-04
+
+### Added
+
+- `MultimediaResource.importFromUrl` returns `MultimediaImportResult` (item + `via`, `source_url`, `profile_image`, `work_link` receipts) via `requestWithEnvelope` and accepts `person_id` (PR #2118, merged into this release).
+- `requestWithEnvelope<T, TRest>` keeps top-level envelope fields (PR #2118).
+
+- **`offset` on `AudioFilesResource.list()`, `NotesResource.list()`,
+  `SessionsResource.list()`** — companions to the mcp-server `offset`
+  additions on `pica_audio_query`/`pica_notes_query`/`pica_sessions_query`
+  (Task 10, 2026-09-03). Each forwards `offset` as a query-string param
+  exactly like the existing `limit`, omitted when not passed.
+
+## [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.

package/dist/index.d.ts

@@ -493,6 +493,37 @@ interface MultimediaItem {
     created_at: string;
     updated_at: string;
 }
+/**
+ * The full response of `POST /admin/multimedia/import-from-url`.
+ *
+ * The route returns the created row in `data` and its receipts as SIBLINGS
+ * of `data`: `via` (was the given URL a direct image, or a page whose
+ * declared og:image was followed?), the `source_url` actually downloaded,
+ * and the outcome of the two optional follow-on writes — `profile_image`
+ * (the person's avatar) and `work_link`. Those receipts are the only way a
+ * caller learns whether the artist photo was really set, so
+ * `MultimediaResource.importFromUrl` reads the whole envelope rather than
+ * `request()`'s `.data`. `item` is the created row (`data` on the wire).
+ */
+interface MultimediaImportResult {
+    item: MultimediaItem;
+    multimedia_id: string;
+    s3_url: string;
+    via: "direct" | "og:image";
+    source_url: string;
+    message: string;
+    profile_image?: {
+        person_id: string;
+        set: boolean;
+        code?: string;
+        reason?: string;
+    };
+    work_link?: {
+        work_id: string;
+        linked: boolean;
+        reason?: string;
+    };
+}
 interface Agreement {
     id: string;
     organisation_id: string;
@@ -861,12 +892,18 @@ declare class BaseResource {
      * carries `twin`/`twin_error` as siblings of `data` — `request()`'s
      * `return data.data || data` would otherwise silently drop them before
      * the MCP tool ever sees a twin was created.
+     *
+     * `TRest` types any FURTHER siblings a specific route puts next to
+     * `data` (e.g. `POST /admin/multimedia/import-from-url` returns `via`,
+     * `source_url`, `profile_image`, `work_link`). It defaults to `unknown`,
+     * which is the identity for intersection, so the existing
+     * `requestWithEnvelope<Work>` call sites keep exactly the type they had.
      */
-    protected requestWithEnvelope<T>(method: string, path: string, body?: any): Promise<{
+    protected requestWithEnvelope<T, TRest = unknown>(method: string, path: string, body?: any): Promise<{
         data: T;
         twin?: unknown;
         twin_error?: string;
-    }>;
+    } & TRest>;
     /**
      * Make a request whose SUCCESS body is raw text, not a JSON envelope —
      * for routes that stream a generated file (e.g. `text/csv`) rather than
@@ -1479,6 +1516,7 @@ declare class AudioFilesResource extends BaseResource {
         unassigned?: boolean;
         query?: string;
         limit?: number;
+        offset?: number;
     }): Promise<AudioFile[]>;
     get(id: string): Promise<AudioFile>;
     /**
@@ -1577,7 +1615,8 @@ declare class MultimediaResource extends BaseResource {
         title?: string;
         source?: string;
         work_id?: string;
-    }): Promise<MultimediaItem>;
+        person_id?: string;
+    }): Promise<MultimediaImportResult>;
     linkYoutube(params: {
         youtube_video_id: string;
         title: string;
@@ -1795,6 +1834,7 @@ declare class NotesResource extends BaseResource {
         work?: string;
         person?: string;
         limit?: number;
+        offset?: number;
     }): Promise<any[]>;
     get(id: string): Promise<any>;
     create(content: string, metadata?: {
@@ -2196,6 +2236,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[];
@@ -2672,6 +2717,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
@@ -3196,11 +3332,16 @@ interface ImportAnalysis {
     };
 }
 interface ImportValidation {
+    /** True when no row carries a severity "error" entry — warnings do not
+     *  invalidate a row, so `valid` can be true with `errors` non-empty. */
     valid: boolean;
     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;
         severity: "error" | "warning";
     }>;
     validRowCount: number;
@@ -4309,6 +4450,7 @@ declare class ReleasesResource extends BaseResource {
 declare class SessionsResource extends BaseResource {
     list(params?: {
         limit?: number;
+        offset?: number;
     }): Promise<any>;
     get(id: string): Promise<any>;
     create(data: Record<string, any>): Promise<any>;
@@ -4732,6 +4874,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;
@@ -4752,5 +4896,5 @@ export declare class PicaClient {
     }): Promise<CatalogStats | Record<string, unknown>>;
     constructor(config: PicaClientConfig);
 }
-export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, BookingEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, Agreement, AgreementWorkLink, CreateAgreementFromTemplateParams, AgreementSendForSignatureResult, AgreementSendForSignatureSentEntry, AgreementSendForSignatureSkippedEntry, AgreementSendForSignatureSkipReason, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };
+export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, BookingEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, MultimediaImportResult, Agreement, AgreementWorkLink, CreateAgreementFromTemplateParams, AgreementSendForSignatureResult, AgreementSendForSignatureSentEntry, AgreementSendForSignatureSkippedEntry, AgreementSendForSignatureSkipReason, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };
 //# sourceMappingURL=index.d.ts.map