@withpica/mcp-sdk 3.7.2 → 3.10.0

package/CHANGELOG.md

@@ -9,6 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > matching entry here in the same commit. See the project's "npm publish
 > discipline" memory entry for the enforcement rationale.
 
+## [Unreleased]
+
+## [3.10.0] - 2026-07-27
+
+### Added
+
+- `DocumentsResource.read()` accepts `row_offset` / `row_limit` — parsed
+  spreadsheet rows now page independently of content chars (ops 41ff656c:
+  `parsed_data.rows` previously rode whole on every page, so an xlsx read
+  could never complete under the 100KB MCP response cap).
+
+## [3.9.0] - 2026-07-24
+
+### Added
+
+- **`AudioFilesResource.bulkAssignSuggested()`** — one-call attach of ALL
+  orphan audio whose suggested match is ISRC-high and non-ambiguous
+  (`POST /admin/audio-files/bulk-assign-suggested`; pairings recomputed
+  server-side, `possible` never bulk-attached). Returns the
+  `BulkAssignSuggestedResult` counts + `attached_ids`. Backs the new
+  `pica_audio_bulk_assign_suggested` MCP tool (agent feedback 20f592ff —
+  an agent hand-looped `pica_audio_assign` over a 74-file queue).
+- **`AudioFilesResource.dismissMatch(id, recordingId)`** — reject a
+  suggested audio→recording pairing so it never resurfaces (repeat
+  dismissals are server-side no-op successes). Backs the new
+  `pica_audio_dismiss_match` MCP tool.
+
+## [3.8.0] - 2026-07-24
+
+### Added
+
+- **`PaginatedResult.recovery_hint`** — `requestPaginated` now carries the
+  server's zero-result guidance through instead of silently dropping it.
+  `GET /admin/recordings/search` has emitted a `recovery_hint` on empty
+  result sets since the unified-catalog-search work (e.g. "N recordings
+  have a null primary artist — try ISRC or title"), but the SDK envelope
+  unwrap discarded it, so agents saw a bare empty list and read it as "no
+  recordings exist" (ops_issue 689a8e9a — an agent nearly created duplicate
+  recordings). Optional field; only present when the server sent one.
+
 ## [3.7.2] - 2026-07-16
 
 ### Fixed

package/dist/index.d.ts

@@ -259,6 +259,15 @@ interface PaginatedResult<T> {
     data: T[];
     total: number;
     hasMore: boolean;
+    /**
+     * Server-provided next-step guidance when a search legitimately returns
+     * zero rows (e.g. GET /admin/recordings/search explains that N recordings
+     * have no primary artist and suggests ISRC/title search). Optional — only
+     * routes that build one emit it, and only on empty result sets. Dropping
+     * this on the wire was ops_issue 689a8e9a: an agent read a silent empty as
+     * "no recordings exist" and nearly created duplicates.
+     */
+    recovery_hint?: string;
 }
 /**
  * Society registration record returned on work and recording read results
@@ -402,6 +411,23 @@ interface PicaScore {
     topActions: string[];
     calculatedAt: string;
 }
+/**
+ * Outcome of a server-recomputed bulk attach of high-confidence orphan-audio
+ * matches (POST /admin/audio-files/bulk-assign-suggested). Mirrors
+ * `BulkAssignResult` in the app's audio-match service; `attached_ids` always
+ * has exactly `attached` entries (shape-locked by the api-audio-bulk-assign
+ * holdout).
+ */
+export interface BulkAssignSuggestedResult {
+    attached: number;
+    skipped_ambiguous: number;
+    skipped_possible: number;
+    failed: number;
+    attached_ids: string[];
+    /** Present and true when the run was a dry-run preview (nothing persisted;
+     *  `attached`/`attached_ids` mean WOULD-attach). */
+    dry_run?: boolean;
+}
 interface AudioFile {
     id: string;
     work_id: string | null;
@@ -1366,6 +1392,32 @@ declare class AudioFilesResource extends BaseResource {
         limit?: number;
     }): Promise<AudioFile[]>;
     get(id: string): Promise<AudioFile>;
+    /**
+     * Attach ALL orphan audio files whose suggested match is ISRC-high and
+     * non-ambiguous, in one call. Pairings are recomputed server-side at
+     * execution time — nothing is sent, so stale suggestions can't be applied
+     * and dismissed pairs stay excluded; `possible` (title-tier) matches are
+     * never bulk-attached. Wraps POST /admin/audio-files/bulk-assign-suggested
+     * (the route behind the /inspect "attach all high" strip; agent feedback
+     * 20f592ff asked for the same action tool-side).
+     *
+     * NB the route responds `{ success, result }` with no `data` key, so
+     * `request()`'s `.data || whole` unwrap yields the full envelope — read
+     * `.result` here rather than typing against a payload that isn't there
+     * (the ADR-265 double-unwrap lesson).
+     */
+    bulkAssignSuggested(params?: {
+        /** Preview: same server-side classification, nothing persisted;
+         *  `attached`/`attached_ids` mean WOULD-attach. */
+        dry_run?: boolean;
+    }): Promise<BulkAssignSuggestedResult>;
+    /**
+     * Reject a suggested (audio_file → recording) match so the pair never
+     * resurfaces in suggestions or bulk attach. The file stays an orphan —
+     * only THIS pairing is suppressed. Repeat dismissals are no-op successes
+     * server-side. Wraps POST /admin/audio-files/{id}/dismiss-match.
+     */
+    dismissMatch(id: string, recordingId: string): Promise<void>;
     update(id: string, body: {
         work_id?: string | null;
         recording_id?: string | null;
@@ -3162,6 +3214,8 @@ declare class DocumentsResource extends BaseResource {
     read(id: string, params?: {
         offset?: number;
         max_chars?: number;
+        row_offset?: number;
+        row_limit?: number;
     }): Promise<Record<string, unknown>>;
     link(id: string, entity_type: string, entity_id: string): Promise<unknown>;
     /**