@withpica/mcp-sdk 3.13.0 → 3.15.0

package/CHANGELOG.md

@@ -11,6 +11,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.15.0] - 2026-09-08
+
+### Added
+
+- `selections` resource (ADR-319 saved catalog selections) — `list`,
+  `create`, `inspect` (id + optional `resolve`/`limit`/`offset`), `update`,
+  `delete` over `/admin/selections`. Backs the new `pica_selections_*` MCP
+  tools (Task 8).
+- `health.catalogHealthFix` accepts an optional `selections` array
+  (`{ actionId, chosenPersonId }`) — the human choice a `resolve_person`
+  action needs. Type-only on this side (the body is forwarded as-is); the
+  route validates it.
+
+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,

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?: {
@@ -2290,11 +2330,17 @@ declare class HealthResource extends BaseResource {
     /**
      * ADR-273 — apply accepted fix actions from a prior plan. Requires planToken
      * from catalogHealthPlan; accept is a list of actionIds (or "all_safe_auto").
+     * `selections` carries the human choice a resolve_person action needs
+     * ({ actionId, chosenPersonId }); a selection also accepts its action.
      * Returns honest per-action met/unmet plus a fresh verdict.
      */
     catalogHealthFix(body: {
         planToken: string;
         accept: string[];
+        selections?: Array<{
+            actionId: string;
+            chosenPersonId: string;
+        }>;
     }): Promise<CatalogHealthFixResult>;
 }
 declare class DashboardResource extends BaseResource {
@@ -3292,11 +3338,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;
@@ -4405,6 +4456,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>;
@@ -4490,6 +4542,104 @@ declare class StatementsResource extends BaseResource {
         rows: unknown[];
     }): Promise<Record<string, unknown>>;
 }
+/**
+ * ADR-319 — saved catalog selections. `mcp-sdk` is a standalone published
+ * package with no access to the app's path aliases, so this is a hand-kept
+ * mirror of `lib/services/catalog-selection/types.ts` rather than an
+ * import. Keep the two in sync by hand when the shape changes.
+ *
+ * `evaluable`/`substrate_rows`/`org_rows` on {@link CoverageEntry} are the
+ * whole point of the feature (ADR-319 Decision 3): a zero-member resolution
+ * with `substrate_rows === 0` on a clause means "PICA does not know", not
+ * "there are none" — the never-invent rule applied to a selection.
+ */
+export type SubstrateUnit = "works" | "credit_rows" | "audio_analysis_rows";
+export interface CoverageEntry {
+    clause: string;
+    /**
+     * False when the resolver had nothing to run the clause against — today,
+     * a role class the vocabulary no longer carries, which a stored predicate
+     * can still name. The clause is narrowed to nothing rather than dropped,
+     * and this flag is what says the empty answer is PICA's ignorance rather
+     * than the catalogue's.
+     */
+    evaluable: boolean;
+    substrate_rows: number;
+    /**
+     * What `substrate_rows` counted. NOT the same unit as `org_rows`, which is
+     * always works: a role clause counts credits and a trait clause counts
+     * audio analyses, so the two numbers are not two halves of one fraction.
+     */
+    substrate_unit: SubstrateUnit;
+    org_rows: number;
+}
+export interface PlayableRef {
+    source: "spotify" | "youtube" | "apple" | "audio_file";
+    ref: string;
+}
+export interface SelectionMember {
+    work_id: string;
+    title: string;
+    primary_artist: string | null;
+    playable: PlayableRef | null;
+    has_lyrics: boolean;
+}
+export interface ResolveResult {
+    members: SelectionMember[];
+    total: number;
+    coverage: CoverageEntry[];
+    /** True when `total` exceeded the page size and members is a first page. */
+    truncated: boolean;
+}
+export interface CatalogSelection {
+    id: string;
+    organisation_id: string;
+    name: string;
+    description: string | null;
+    predicate: Record<string, unknown>;
+    renderer: "listen" | "worklist";
+    visibility: "private" | "shared" | "public";
+    created_by: string | null;
+    created_at: string;
+    updated_at: string;
+    last_resolved_at: string | null;
+    last_resolved_count: number | null;
+    is_deleted: boolean;
+}
+export interface CreateSelectionInput {
+    name: string;
+    description?: string;
+    /** `{ version: 1, all: [...clauses] }` — validated server-side. */
+    predicate: Record<string, unknown>;
+    renderer?: "listen" | "worklist";
+}
+export interface UpdateSelectionInput {
+    name?: string;
+    description?: string;
+    predicate?: Record<string, unknown>;
+}
+declare class SelectionsResource extends BaseResource {
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<CatalogSelection[]>;
+    create(data: CreateSelectionInput): Promise<CatalogSelection>;
+    /**
+     * Per-id read. `resolve: true` also resolves the predicate — the route
+     * returns `{ selection, resolution }` instead of `{ selection }`, and
+     * `resolution` is omitted below when the caller didn't ask for it.
+     */
+    inspect(id: string, opts?: {
+        resolve?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        selection: CatalogSelection;
+        resolution?: ResolveResult;
+    }>;
+    update(id: string, data: UpdateSelectionInput): Promise<CatalogSelection>;
+    delete(id: string): Promise<void>;
+}
 declare class ShareLinksResource extends BaseResource {
     list(params?: {
         work_id?: string;
@@ -4813,6 +4963,8 @@ export declare class PicaClient {
     workForHire: WorkForHireResource;
     royalties: RoyaltiesResource;
     statements: StatementsResource;
+    /** ADR-319 — saved catalog selections. */
+    selections: SelectionsResource;
     shareLinks: ShareLinksResource;
     consent: ConsentResource;
     custody: CustodyResource;
@@ -4850,5 +5002,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