@withpica/mcp-sdk 3.15.0 → 3.16.0

package/CHANGELOG.md

@@ -11,6 +11,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.16.0] - 2026-09-09
+
+### Added
+
+- `works.search()` accepts `has_lyrics` (boolean) and writes it to the query
+  string. Without it a caller could not count works holding a lyric sheet
+  without paging the whole catalogue, which is how a connector session came to
+  inspect one work, see `lyrics: null`, and report that lyrics were not being
+  stored for an org holding 178 of them (PICA FIX_LOG 2026-09-09).
+
+⚠️ **`@withpica/mcp-server` must not be published against 3.15.0 once its
+`pica_works_query` declares `has_lyrics`.** `URLSearchParams` drops unknown
+keys silently, so an older SDK would send no filter, the route would return the
+unfiltered catalogue, and the tool description tells the agent to read `total`
+as the answer — it would report every work as having lyrics. Publish this
+package first.
+
 ## [3.15.0] - 2026-09-08
 
 ### Added

package/dist/index.d.ts

@@ -985,6 +985,11 @@ declare class WorksResource extends BaseResource {
         has_iswc?: boolean;
         /** Filter to works that have (true) or lack (false) a publisher_name. */
         has_publisher?: boolean;
+        /**
+         * Filter to works that have (true) or lack (false) a stored lyric sheet
+         * (works.lyrics; blank counts as lacking).
+         */
+        has_lyrics?: boolean;
     }): Promise<PaginatedResult<Work>>;
     get(id: string): Promise<Work>;
     create(data: Partial<Work> & {
@@ -1508,6 +1513,31 @@ interface IdentifyResult {
         confidence: number;
     };
 }
+export interface AudioFileTranscriptSegment {
+    start: number;
+    end: number;
+    text: string;
+    confidence?: number;
+}
+export interface AudioFileTranscript {
+    audio_file_id: string;
+    has_transcript: boolean;
+    /** absent when has_transcript is false */
+    work_id?: string | null;
+    recording_id?: string | null;
+    /** false when the transcript reaches no work — nothing else can show it */
+    reaches_work?: boolean;
+    transcript: {
+        full_text: string;
+        language: string | null;
+        confidence: number | null;
+        segment_count: number;
+        segments: AudioFileTranscriptSegment[];
+        processor: string | null;
+        model_version: string | null;
+        created_at: string | null;
+    } | null;
+}
 declare class AudioFilesResource extends BaseResource {
     list(params?: {
         work_id?: string;
@@ -1519,6 +1549,16 @@ declare class AudioFilesResource extends BaseResource {
         offset?: number;
     }): Promise<AudioFile[]>;
     get(id: string): Promise<AudioFile>;
+    /**
+     * The stored Whisper transcript for one audio file, linked to a work or not.
+     *
+     * Until 2026-09-07 a transcript was readable only as `works.lyrics` after
+     * propagation, so a transcript on an unlinked file had no reader at all —
+     * 218 of 558 on prod. `has_transcript: false` is a normal answer, not an
+     * error, and `reaches_work` says whether this transcript can be seen
+     * anywhere else.
+     */
+    getTranscript(id: string): Promise<AudioFileTranscript>;
     /**
      * Attach ALL orphan audio files whose suggested match is ISRC-high and
      * non-ambiguous, in one call. Pairings are recomputed server-side at