@withpica/mcp-sdk 3.7.1 → 3.9.0

package/CHANGELOG.md

@@ -9,7 +9,60 @@ 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.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
+
+- **`UsersResource` — all six methods resolved `undefined` on the live wire**
+  (`findByHandle`, `setHandle`, `getMyProfile`, `setBio`, `setAvatarUrl`,
+  `importBioFromPerson`). Each declared its response type as the
+  `{ data: X }` envelope and returned `res.data`, but `BaseResource.request()`
+  already unwraps the envelope — the double-unwrap made every method resolve
+  `undefined`, so `pica_users_get_my_profile` (and siblings) crashed with
+  `Cannot read properties of undefined (reading 'public_handle')` for every
+  caller. Methods are now typed against the unwrapped reality (ADR-265
+  lesson). Regression locked by `sdk-users-resource.test.ts` in mcp-server.
+- **`RecordingsResource.prefixLookup` always returned `null`** — same
+  double-unwrap class, different idiom (`result.data ?? null`). A registry
+  hit unwraps to the row (so `.data` was undefined); a miss returns
+  `data: null`, which `request()`'s `data.data || data` falls through to the
+  full envelope on — fixed with the envelope-discriminating guard
+  (AccessSimulate precedent). `prefix_intel` on works/recordings inspect
+  works again.
+- **`WorksResource.listReleases` always returned `[]`** when the work was
+  actually on releases (`result?.data || []` after the auto-unwrap) —
+  blanking the `releases` section of `pica_works_inspect`. Now mirrors the
+  recordings-side `Array.isArray` guard (cea22b5e). Both locked by
+  `sdk-double-unwrap-sweep.test.ts` in mcp-server.
 
 ## [3.7.1] - 2026-07-14
 

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;
@@ -3400,6 +3452,12 @@ declare class CollaborationsResource extends BaseResource {
  * Cross-org discovery surface that lets the sender's agent invite a
  * collaborator by `@handle` without ever learning the recipient's
  * email (resolution happens server-side).
+ *
+ * Typed against the UNWRAPPED reality (ADR-265 lesson): BaseResource.request
+ * auto-unwraps the `{success,data}` envelope, so methods see `data` itself.
+ * Declaring `T = { data: X }` and returning `res.data` double-unwraps and
+ * resolves `undefined` on the live wire (FIX_LOG 2026-07-16 — the
+ * get_my_profile "reading 'public_handle'" crash).
  */
 declare class UsersResource extends BaseResource {
     /**