@vocalstack/js-sdk 2.0.0-alpha.1 → 2.0.0-alpha.3

package/README.md

@@ -31,8 +31,8 @@ npm install @vocalstack/js-sdk
 
 - [Quickstart](https://github.com/vocalstack/js-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
-- [Transcribe a batch of files](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-batch.md): Send many files or links as one batch, start it once, and read every transcript when it is done. Cheaper than one transcription per file.
+- [Transcribe a link](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Search your transcriptions](https://github.com/vocalstack/js-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/js-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
@@ -52,7 +52,6 @@ npm install @vocalstack/js-sdk
 | transcription | a file, link, microphone or stream, transcribed and stored (`live: true` for a microphone or stream) | `vs.transcriptions` |
 | recording | one take inside a broadcast or a transcription | `vs.recordings` |
 | job | a file or link recording's transcription work | `vs.jobs` |
-| batch | many files transcribed together, for less than one transcription each | `vs.batches` |
 
 The other groups: `vs.corrections`, `vs.shareLinks`, `vs.voices`,
 `vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.

package/SKILL.md

@@ -19,9 +19,6 @@ one group per resource: `vs.transcriptions`, `vs.jobs`, `vs.recordings`,
 - A **job** is a file or link recording's transcription work:
   `vs.jobs.wait(recordingId)` polls it until it is `done` or `failed`
   (`{ onProgress: (job) => … }` sees each read: `job.state`, `job.progress.pct`).
-- A **batch** is many files transcribed together for less than one
-  transcription each: `vs.batches.create()`, `addFile`/`addUrl` per file,
-  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -179,26 +176,14 @@ for (const h of hits) {
 }
 ```
 
-## 6. A batch of files
-
-Many files at once cost less as a batch: one create, one minimum charge for
-the whole batch. Its files get transcripts, exports and speaker labels (when
-`settings.speakerLabels` asks), never a summary, title, share link or voices.
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
 
 ```js
-import { VocalStack } from '@vocalstack/js-sdk';
-const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
-
-const batch = await vs.batches.create({ name: 'Interviews', settings: { spokenLanguage: 'en' } });
-for (const path of process.argv.slice(2)) await vs.batches.addFile(batch.id, { file: path }); // or addUrl(batch.id, url)
-await vs.batches.start(batch.id);
-const done = await vs.batches.wait(batch.id); // done (or stopped); check done.counts.failed
-for (const tx of done.files ?? []) {
-  if (tx.job?.state !== 'done') continue;
-  const { sentences } = await vs.recordings.transcript(tx.job.recordingId);
-  console.log(tx.name, sentences.map((s) => s.text).join(' '));
-}
-// vs.batches.export(batch.id, 'srt') is every finished transcript in one zip.
+const { hits: found } = await vs.search.vector('how much does housing cost');
+for (const h of found) console.log(h.similarity.toFixed(2), h.passage.mediaStart, h.passage.text);
 ```
 
 ## Errors
@@ -238,8 +223,7 @@ try {
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `listShareLinks`, `createShareLink`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audioUrl`, `subscribe` for a
-  live transcript feed), `vs.batches` (`create`, `addFile`, `addUrl`, `start`,
-  `wait`, `get`, `list`, `export`, `stop`, `delete`), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+  live transcript feed), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
   `vs.broadcasts`, `vs.me` (`get`, `usage`), `vs.languages`,
   `vs.rtmp`, `vs.events`, `vs.meta`. Each method is named after its operation
   in the OpenAPI document (`transcriptions.create` is `POST /v1/transcriptions`).

package/dist/index.d.ts

@@ -1,21 +1,21 @@
 import { type ClientOptions } from './http.js';
 import { Realtime } from './realtime.js';
-import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices } from './resources.js';
+import { Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices } from './resources.js';
 export type { ClientOptions, CallOptions, ReadAs, Query } from './http.js';
 export { DEFAULT_BASE_URL } from './http.js';
 export { VocalStackError } from './errors.js';
 export type { ConnectTokenErrorCode, VocalStackErrorOptions } from './errors.js';
 export { RealtimeSession } from './realtime.js';
-export type { ConnectParams, SessionEvent } from './realtime.js';
+export type { ConnectParams, QueuedInfo, SessionEvent } from './realtime.js';
 export type { FileInput } from './file.js';
 export { Realtime, applySentence } from './realtime.js';
 export type { ConnectOptions, TranscribeOptions, RealtimeTranscript } from './realtime.js';
 export { Subscription } from './subscription.js';
 export type { SubscribeOptions, SubscriptionEvent } from './subscription.js';
 export type { WsLike } from './ws.js';
-export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
-export type { AudioKind, MediaAuth, MediaFormat, RenderVoice } from './resources.js';
-export type { AddBatchFileInput, ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
+export { Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export type { AudioKind, MediaAuth, MediaFormat, RenderVoice, VoicesChoice } from './resources.js';
+export type { ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, TranscriptionFilters, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
 export type * from '@vocalstack/contract';
 export type VocalStackOptions = ClientOptions;
 export declare class VocalStack {
@@ -23,7 +23,6 @@ export declare class VocalStack {
     readonly realtime: Realtime;
     readonly broadcasts: Broadcasts;
     readonly transcriptions: Transcriptions;
-    readonly batches: Batches;
     readonly recordings: Recordings;
     readonly jobs: Jobs;
     readonly corrections: Corrections;

package/dist/index.js

@@ -1,18 +1,17 @@
 import { Transport } from './http.js';
 import { Realtime } from './realtime.js';
-import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, } from './resources.js';
+import { Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, } from './resources.js';
 export { DEFAULT_BASE_URL } from './http.js';
 export { VocalStackError } from './errors.js';
 export { RealtimeSession } from './realtime.js';
 export { Realtime, applySentence } from './realtime.js';
 export { Subscription } from './subscription.js';
-export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export { Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
 export class VocalStack {
     baseUrl;
     realtime;
     broadcasts;
     transcriptions;
-    batches;
     recordings;
     jobs;
     corrections;
@@ -33,7 +32,6 @@ export class VocalStack {
         this.realtime = new Realtime(t);
         this.broadcasts = new Broadcasts(t);
         this.transcriptions = new Transcriptions(t);
-        this.batches = new Batches(t);
         this.recordings = new Recordings(t);
         this.jobs = new Jobs(t);
         this.corrections = new Corrections(t);

package/dist/realtime.d.ts

@@ -11,8 +11,12 @@ export interface ConnectParams {
     options?: SessionOptions;
     readyDeadlineMs?: number;
     onLoading?(stage: 'download' | 'model'): void;
+    onQueued?(queued: QueuedInfo): void;
     onFrame?(frame: ServerFrame): void;
 }
+export type QueuedInfo = Omit<Extract<ServerFrame, {
+    type: 'session.queued';
+}>, 'type'>;
 export declare function engineLost(closeCode?: number): VocalStackError;
 export declare function upgradeRefused(status: number | undefined, body: string): VocalStackError;
 export declare const RESTART_CLOSE = 1012;
@@ -41,6 +45,7 @@ export declare class RealtimeSession implements AsyncIterable<SessionEvent> {
 }
 export interface ConnectOptions {
     onLoading?(stage: 'download' | 'model'): void;
+    onQueued?(queued: QueuedInfo): void;
     onFrame?(frame: ServerFrame): void;
     readyDeadlineMs?: number;
 }

package/dist/realtime.js

@@ -29,7 +29,7 @@ export function upgradeRefused(status, body) {
 export const RESTART_CLOSE = 1012;
 const RESTART_TRIES = 3;
 const MAX_PENDING_BYTES = 4 * 1024 * 1024;
-async function openReady(url, deadlineMs, onLoading, onFrame, attach) {
+async function openReady(url, deadlineMs, onLoading, onQueued, onFrame, attach) {
     const ws = await openWebSocket(url);
     ws.binaryType = 'arraybuffer';
     await new Promise((resolve, reject) => {
@@ -77,6 +77,10 @@ async function openReady(url, deadlineMs, onLoading, onFrame, attach) {
             if (frame.type === 'session.loading') {
                 onLoading?.(frame.stage);
             }
+            else if (frame.type === 'session.queued') {
+                const { type: _type, ...queued } = frame;
+                onQueued?.(queued);
+            }
             else if (frame.type === 'session.ready') {
                 if (!settled) {
                     settled = true;
@@ -142,7 +146,7 @@ export class RealtimeSession {
         const deadlineMs = params.readyDeadlineMs ?? DEFAULT_READY_DEADLINE_MS;
         const early = [];
         let session;
-        await openReady(params.streamUrl, deadlineMs, params.onLoading, (f) => early.push(f), (ws) => {
+        await openReady(params.streamUrl, deadlineMs, params.onLoading, params.onQueued, (f) => early.push(f), (ws) => {
             const s = new RealtimeSession(params.sessionId, ws, params);
             for (const f of early)
                 s.#frame(f);
@@ -160,7 +164,7 @@ export class RealtimeSession {
             if (this.#closedByUs)
                 break;
             try {
-                await openReady(this.#params.streamUrl, deadlineMs, this.#params.onLoading, (f) => this.#frame(f), (ws) => {
+                await openReady(this.#params.streamUrl, deadlineMs, this.#params.onLoading, this.#params.onQueued, (f) => this.#frame(f), (ws) => {
                     this.#ws = ws;
                     this.#reconnecting = false;
                     this.#listen();
@@ -389,6 +393,7 @@ export class Realtime {
             options,
             readyDeadlineMs: connect.readyDeadlineMs ?? this.#t.opts.readyDeadlineMs,
             onLoading: connect.onLoading,
+            onQueued: connect.onQueued,
             onFrame: connect.onFrame,
         });
     }

package/dist/resources.d.ts

@@ -1,10 +1,23 @@
-import type { AppStreamKey, AudioSourceCheck, Batch, BatchPage, AutoTopUpSettings, AutoTopUpView, BillingDetails, BillingView, CheckPromoCode, CheckoutView, CreateCheckout, LowBalanceAlertSettings, LowBalanceAlertView, PaymentDocument, PaymentMethodList, PaymentPage, PortalLink, PromoCodeView, SetInterval, SubscriptionView, YearlyOptIn, UsageChargePage, UsageReport, Broadcast, Correction, CorrectionBatch, CorrectionPage, CreateAppStreamKey, CreateAudioSource, CreateBatch, CreateLiveTranscription, CreateBroadcast, CreateShareLink, CreateTag, CreateTranscription, CreateVoiceFromSpeaker, CreatedAppStreamKey, ChargePage, ExportFormat, ClientApp, ClientPolicy, Health, LanguageLists, LedgerPage, LinkProbe, PatchVoice, PlanList, PublishGrant, Recording, RecordingEvent, RecordingEvents, RecordingPage, RetranscribeLine, RtmpStatus, SearchResults, SettingsPatch, ShareLink, SharedTranscript, StartRecording, StartJob, SummaryStatus, Tag, TagTranscriptions, Transcription, TranscriptionJob, TranscriptionPage, TranscriptSnapshot, UpdateBroadcast, UpdateTag, UpdateTranscription, UpdateShareLink, UploadRecording, Voice, VoiceCatalogue, VoiceTrack, ManyResult } from '@vocalstack/contract';
+import type { AppStreamKey, AudioSourceCheck, AutoTopUpSettings, AutoTopUpView, BillingDetails, BillingView, CheckPromoCode, CheckoutView, CreateCheckout, LowBalanceAlertSettings, LowBalanceAlertView, PaymentDocument, PaymentMethodList, PaymentPage, PortalLink, PromoCodeView, SetInterval, SubscriptionView, YearlyOptIn, UsageChargePage, UsageReport, Broadcast, Correction, CorrectionBatch, CorrectionPage, CreateAppStreamKey, CreateAudioSource, CreateLiveTranscription, CreateBroadcast, CreateShareLink, CreateTag, CreateTranscription, CreateVoiceFromSpeaker, CreatedAppStreamKey, ChargePage, ExportFormat, ClientApp, ClientPolicy, Health, LanguageLists, LedgerPage, LinkProbe, PatchVoice, PlanList, PublishGrant, Recording, RecordingEvent, RecordingEvents, RecordingPage, RetranscribeLine, RtmpStatus, SearchResults, VectorResults, SettingsPatch, ShareLink, SharedTranscript, StartRecording, StartJob, SummaryStatus, Tag, TagTranscriptions, Transcription, TranscriptionJob, TranscriptionPage, TranscriptSnapshot, UpdateBroadcast, UpdateTag, UpdateTranscription, UpdateShareLink, UploadRecording, Voice, VoiceCatalogue, VoiceTrack, ManyResult } from '@vocalstack/contract';
 import { Transport, type CallOptions, type ReadAs } from './http.js';
 import { RealtimeSession, type ConnectOptions } from './realtime.js';
 import { Subscription, type SubscribeOptions } from './subscription.js';
 import { type WsLike } from './ws.js';
 export type Upload = Blob | Uint8Array | ArrayBuffer | string;
 export type LifecycleFilter = 'active' | 'archived' | 'all';
+export interface TranscriptionFilters {
+    lifecycle?: LifecycleFilter;
+    q?: string;
+    site?: string;
+    language?: string;
+    kind?: 'file' | 'link' | 'live';
+    origin?: Transcription['origin'];
+    tag?: string;
+    broadcast?: string;
+    createdAfter?: string | Date;
+    createdBefore?: string | Date;
+    shared?: boolean;
+}
 export interface RecordingPageOptions extends PageOptions {
     lifecycle?: 'active' | 'archived';
 }
@@ -49,41 +62,17 @@ export type CreateTranscriptionInput = CreateTranscription & {
 export declare class Transcriptions extends ParentResource<Transcription, UpdateTranscription> {
     protected readonly base: "/v1/transcriptions";
     protected readonly key: "transcriptions";
-    listPage(opts?: PageOptions & {
-        lifecycle?: LifecycleFilter;
-    }): Promise<TranscriptionPage>;
+    list(opts?: LifecycleFilter | TranscriptionFilters): Promise<Transcription[]>;
+    listPage(opts?: PageOptions & TranscriptionFilters): Promise<TranscriptionPage>;
     uploadRecording(id: string, req?: UploadRecording, call?: CallOptions): Promise<PublishGrant>;
     create(req: CreateTranscriptionInput, call?: CallOptions): Promise<Transcription>;
     createFromUrl(url: string, opts?: Omit<CreateTranscription, 'url'>, call?: CallOptions): Promise<Transcription>;
     createLive(req: CreateLiveTranscription, call?: CallOptions): Promise<Transcription>;
+    lookup(url: string): Promise<Transcription | null>;
     probe(url: string): Promise<LinkProbe>;
     attachBroadcast(id: string, broadcastId: string): Promise<Transcription>;
     detachBroadcast(id: string, broadcastId: string): Promise<Transcription>;
 }
-export type AddBatchFileInput = Pick<CreateTranscription, 'url' | 'name' | 'startS' | 'endS' | 'durationS'> & {
-    file?: Upload;
-    fileName?: string;
-};
-export declare class Batches {
-    #private;
-    constructor(t: Transport);
-    create(req?: CreateBatch, call?: CallOptions): Promise<Batch>;
-    list(): Promise<Batch[]>;
-    listPage(opts?: PageOptions): Promise<BatchPage>;
-    get(id: string): Promise<Batch>;
-    delete(id: string): Promise<void>;
-    addFile(id: string, req: AddBatchFileInput, call?: CallOptions): Promise<Transcription>;
-    addUrl(id: string, url: string, opts?: Omit<AddBatchFileInput, 'url' | 'file' | 'fileName'>, call?: CallOptions): Promise<Transcription>;
-    start(id: string, call?: CallOptions): Promise<Batch>;
-    export(id: string, format: ExportFormat): Promise<Response>;
-    stop(id: string): Promise<Batch>;
-    wait(id: string, opts?: {
-        intervalMs?: number;
-        timeoutMs?: number;
-        signal?: AbortSignal;
-        onProgress?(batch: Batch): void;
-    }): Promise<Batch>;
-}
 export declare class Recordings {
     #private;
     constructor(t: Transport);
@@ -131,6 +120,7 @@ export declare class Recordings {
     audioSrc(id: string, opts?: {
         kind?: AudioKind;
         lang?: string;
+        voices?: VoicesChoice;
         voice?: string;
         format?: MediaFormat;
     } & MediaAuth): string;
@@ -138,6 +128,7 @@ export declare class Recordings {
         clean?: boolean;
     } & MediaAuth): string;
     voiceClipSrc(id: string, sentence: number, lang: string, opts?: {
+        voices?: VoicesChoice;
         voice?: string;
         format?: 'ogg' | 'caf';
         part?: number;
@@ -149,6 +140,7 @@ export declare class Recordings {
     renderVoice(id: string, req: RenderVoice & ReadAs, call?: CallOptions): Promise<VoiceTrack[]>;
     voiceClip(id: string, sentence: number, lang: string, opts?: {
         format?: 'ogg' | 'caf';
+        voices?: VoicesChoice;
     } & ReadAs): Promise<Response>;
     mediaToken(id: string): Promise<{
         token: string;
@@ -168,11 +160,14 @@ export declare class Recordings {
 }
 export type AudioKind = 'delivery' | 'voice' | 'background' | 'speech' | 'master' | 'source' | 'video';
 export type MediaFormat = 'ogg' | 'caf' | 'mp3';
+export type VoicesChoice = 'cloned' | 'synthetic';
 export interface RenderVoice {
     langs: string[];
+    voices?: VoicesChoice;
     voice?: string;
     voiceBySpeaker?: Record<string, string>;
     near?: number;
+    consent?: boolean;
 }
 export interface MediaAuth extends ReadAs {
     token?: string;
@@ -260,10 +255,11 @@ export declare class Voices {
     } & ReadAs): Promise<Response>;
     sample(id: string): Promise<Response>;
 }
-export interface SearchOptions {
+export interface SearchOptions extends Omit<TranscriptionFilters, 'lifecycle' | 'q' | 'broadcast'> {
     broadcasts?: string[];
     listenerTokens?: string[];
     recording?: string;
+    transcription?: string;
     lang?: string;
     limit?: number;
 }
@@ -271,7 +267,9 @@ export declare class Search {
     #private;
     constructor(t: Transport);
     query(q: string, opts?: SearchOptions): Promise<SearchResults>;
+    vector(q: string, opts?: VectorSearchOptions): Promise<VectorResults>;
 }
+export type VectorSearchOptions = Omit<SearchOptions, 'broadcasts' | 'listenerTokens' | 'lang' | 'limit'>;
 export interface Me {
     userId?: string | null;
     apiKeyId?: string | null;

package/dist/resources.js

@@ -3,6 +3,10 @@ import { listenerQuery, seg } from './http.js';
 import { RealtimeSession } from './realtime.js';
 import { Subscription } from './subscription.js';
 import { openWebSocket } from './ws.js';
+function filterQuery(f) {
+    const at = (d) => (d instanceof Date ? d.toISOString() : d);
+    return { lifecycle: f.lifecycle, q: f.q, site: f.site, language: f.language, kind: f.kind, origin: f.origin, tag: f.tag, broadcast: f.broadcast, createdAfter: at(f.createdAfter), createdBefore: at(f.createdBefore), shared: f.shared };
+}
 async function toBlob(file) {
     if (typeof file === 'string') {
         const fsSpecifier = 'node:' + 'fs';
@@ -106,8 +110,15 @@ export class Broadcasts extends ParentResource {
 export class Transcriptions extends ParentResource {
     base = '/v1/transcriptions';
     key = 'transcriptions';
+    list(opts = 'active') {
+        const f = typeof opts === 'string' ? { lifecycle: opts } : opts;
+        return allPages(async (cursor) => {
+            const r = await this.listPage({ ...f, cursor });
+            return { items: r.transcriptions, nextCursor: r.nextCursor };
+        });
+    }
     listPage(opts = {}) {
-        return this.t.json('GET', this.base, { query: { lifecycle: opts.lifecycle, cursor: opts.cursor, limit: opts.limit } });
+        return this.t.json('GET', this.base, { query: { ...filterQuery(opts), cursor: opts.cursor, limit: opts.limit } });
     }
     uploadRecording(id, req = {}, call = {}) {
         return this.t.json('POST', this.p(id, '/recordings/upload'), { body: req, ...call });
@@ -128,6 +139,10 @@ export class Transcriptions extends ParentResource {
     createLive(req, call = {}) {
         return this.t.json('POST', `${this.base}/live`, { body: req, ...call });
     }
+    async lookup(url) {
+        const r = await this.t.json('GET', `${this.base}/lookup`, { query: { url } });
+        return r.transcription ?? null;
+    }
     probe(url) {
         return this.t.json('GET', `${this.base}/probe`, { query: { url } });
     }
@@ -138,72 +153,6 @@ export class Transcriptions extends ParentResource {
         return this.t.json('DELETE', this.p(id, `/broadcasts/${seg(broadcastId)}`));
     }
 }
-export class Batches {
-    #t;
-    constructor(t) {
-        this.#t = t;
-    }
-    #p(id, rest = '') {
-        return `/v1/batches/${seg(id)}${rest}`;
-    }
-    create(req = {}, call = {}) {
-        return this.#t.json('POST', '/v1/batches', { body: req, ...call });
-    }
-    list() {
-        return allPages(async (cursor) => {
-            const r = await this.listPage({ cursor });
-            return { items: r.batches, nextCursor: r.nextCursor };
-        });
-    }
-    listPage(opts = {}) {
-        return this.#t.json('GET', '/v1/batches', { query: { cursor: opts.cursor, limit: opts.limit } });
-    }
-    get(id) {
-        return this.#t.json('GET', this.#p(id));
-    }
-    async delete(id) {
-        await this.#t.json('DELETE', this.#p(id));
-    }
-    async addFile(id, req, call = {}) {
-        const { file, fileName, ...options } = req;
-        if (file === undefined)
-            return this.#t.json('POST', this.#p(id, '/files'), { body: options, ...call });
-        const { blob, name } = await toBlob(file);
-        const fd = new FormData();
-        fd.append('options', JSON.stringify(options));
-        fd.append('file', blob, fileName ?? name ?? 'upload');
-        return this.#t.json('POST', this.#p(id, '/files'), { body: fd, ...call });
-    }
-    addUrl(id, url, opts = {}, call = {}) {
-        return this.addFile(id, { ...opts, url }, call);
-    }
-    start(id, call = {}) {
-        return this.#t.json('POST', this.#p(id, '/start'), call);
-    }
-    export(id, format) {
-        return this.#t.raw('GET', this.#p(id, '/export'), { headers: { accept: '*/*' }, query: { format } });
-    }
-    stop(id) {
-        return this.#t.json('POST', this.#p(id, '/stop'));
-    }
-    async wait(id, opts = {}) {
-        const interval = opts.intervalMs ?? 5000;
-        const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : Infinity;
-        for (;;) {
-            const batch = await this.get(id);
-            opts.onProgress?.(batch);
-            if ((batch.state === 'done' || batch.state === 'stopped') && batch.finishedAt)
-                return batch;
-            if (batch.state === 'open')
-                throw new VocalStackError('invalid_state', 'the batch is open: start it before waiting for it');
-            if (Date.now() + interval > deadline)
-                throw new VocalStackError('timeout', `batch still ${batch.state} after ${opts.timeoutMs} ms`, { retryable: true });
-            if (opts.signal?.aborted)
-                throw opts.signal.reason ?? new Error('aborted');
-            await new Promise((r) => setTimeout(r, interval));
-        }
-    }
-}
 export class Recordings {
     #t;
     constructor(t) {
@@ -238,6 +187,7 @@ export class Recordings {
             streamUrl: grant.streamUrl,
             readyDeadlineMs: opts.readyDeadlineMs ?? this.#t.opts.readyDeadlineMs,
             onLoading: opts.onLoading,
+            onQueued: opts.onQueued,
             onFrame: opts.onFrame,
         });
     }
@@ -292,7 +242,7 @@ export class Recordings {
         return location;
     }
     audioSrc(id, opts = {}) {
-        return this.#t.url(this.#p(id, '/audio'), { kind: opts.kind ?? 'delivery', lang: opts.lang, format: opts.format, voice: opts.voice, ...mediaQuery(opts) });
+        return this.#t.url(this.#p(id, '/audio'), { kind: opts.kind ?? 'delivery', lang: opts.lang, format: opts.format, voices: opts.voices, voice: opts.voice, ...mediaQuery(opts) });
     }
     clipSrc(id, startS, endS, opts = {}) {
         return this.#t.url(this.#p(id, '/audio/clip'), { startS: startS.toFixed(2), endS: endS.toFixed(2), clean: opts.clean ? 'true' : undefined, ...mediaQuery(opts) });
@@ -300,6 +250,7 @@ export class Recordings {
     voiceClipSrc(id, sentence, lang, opts = {}) {
         return this.#t.url(this.#p(id, `/voice/${seg(sentence)}`), {
             lang,
+            voices: opts.voices,
             voice: opts.voice,
             format: opts.format,
             part: opts.part ? opts.part : undefined,
@@ -317,12 +268,12 @@ export class Recordings {
         const r = Array.isArray(req) ? { langs: req } : req;
         return this.#t.json('POST', this.#p(id, '/voice'), {
             query: listenerQuery(r),
-            body: { langs: r.langs, voice: r.voice, voiceBySpeaker: r.voiceBySpeaker, near: r.near },
+            body: { langs: r.langs, voices: r.voices, voice: r.voice, voiceBySpeaker: r.voiceBySpeaker, near: r.near, consent: r.consent },
             ...call,
         });
     }
     voiceClip(id, sentence, lang, opts = {}) {
-        return this.#t.raw('GET', this.#p(id, `/voice/${seg(sentence)}`), { headers: { accept: '*/*' }, query: { ...listenerQuery(opts), lang, format: opts.format } });
+        return this.#t.raw('GET', this.#p(id, `/voice/${seg(sentence)}`), { headers: { accept: '*/*' }, query: { ...listenerQuery(opts), lang, format: opts.format, voices: opts.voices } });
     }
     mediaToken(id) {
         return this.#t.json('GET', this.#p(id, '/media-token'));
@@ -542,15 +493,26 @@ export class Search {
     }
     query(q, opts = {}) {
         const query = {
+            ...filterQuery({ site: opts.site, language: opts.language, kind: opts.kind, origin: opts.origin, tag: opts.tag, createdAfter: opts.createdAfter, createdBefore: opts.createdBefore, shared: opts.shared }),
             q,
             broadcasts: opts.broadcasts?.join(','),
             listenerTokens: opts.listenerTokens?.join(','),
             recording: opts.recording,
+            transcription: opts.transcription,
             lang: opts.lang,
             limit: opts.limit,
         };
         return this.#t.json('GET', '/v1/search', { query });
     }
+    vector(q, opts = {}) {
+        const query = {
+            ...filterQuery({ site: opts.site, language: opts.language, kind: opts.kind, origin: opts.origin, tag: opts.tag, createdAfter: opts.createdAfter, createdBefore: opts.createdBefore, shared: opts.shared }),
+            q,
+            recording: opts.recording,
+            transcription: opts.transcription,
+        };
+        return this.#t.json('GET', '/v1/search/vector', { query });
+    }
 }
 export class MeApi {
     #t;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocalstack/js-sdk",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.3",
   "description": "VocalStack speech API SDK for Node and browsers: one client (VocalStack) grouped by resource, typed from the generated contract, with realtime WebSocket streaming.",
   "license": "MIT",
   "type": "module",
@@ -25,20 +25,16 @@
     "skills"
   ],
   "scripts": {
-    "build": "npm run build --prefix contract && tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@vocalstack/contract": "1.0.0-alpha.1",
+    "@vocalstack/contract": "1.0.0-alpha.3",
     "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
     "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vocalstack/js-sdk.git"
   }
 }

package/skills/vocalstack/SKILL.md

@@ -19,9 +19,6 @@ one group per resource: `vs.transcriptions`, `vs.jobs`, `vs.recordings`,
 - A **job** is a file or link recording's transcription work:
   `vs.jobs.wait(recordingId)` polls it until it is `done` or `failed`
   (`{ onProgress: (job) => … }` sees each read: `job.state`, `job.progress.pct`).
-- A **batch** is many files transcribed together for less than one
-  transcription each: `vs.batches.create()`, `addFile`/`addUrl` per file,
-  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -179,26 +176,14 @@ for (const h of hits) {
 }
 ```
 
-## 6. A batch of files
-
-Many files at once cost less as a batch: one create, one minimum charge for
-the whole batch. Its files get transcripts, exports and speaker labels (when
-`settings.speakerLabels` asks), never a summary, title, share link or voices.
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
 
 ```js
-import { VocalStack } from '@vocalstack/js-sdk';
-const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
-
-const batch = await vs.batches.create({ name: 'Interviews', settings: { spokenLanguage: 'en' } });
-for (const path of process.argv.slice(2)) await vs.batches.addFile(batch.id, { file: path }); // or addUrl(batch.id, url)
-await vs.batches.start(batch.id);
-const done = await vs.batches.wait(batch.id); // done (or stopped); check done.counts.failed
-for (const tx of done.files ?? []) {
-  if (tx.job?.state !== 'done') continue;
-  const { sentences } = await vs.recordings.transcript(tx.job.recordingId);
-  console.log(tx.name, sentences.map((s) => s.text).join(' '));
-}
-// vs.batches.export(batch.id, 'srt') is every finished transcript in one zip.
+const { hits: found } = await vs.search.vector('how much does housing cost');
+for (const h of found) console.log(h.similarity.toFixed(2), h.passage.mediaStart, h.passage.text);
 ```
 
 ## Errors
@@ -238,8 +223,7 @@ try {
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `listShareLinks`, `createShareLink`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audioUrl`, `subscribe` for a
-  live transcript feed), `vs.batches` (`create`, `addFile`, `addUrl`, `start`,
-  `wait`, `get`, `list`, `export`, `stop`, `delete`), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+  live transcript feed), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
   `vs.broadcasts`, `vs.me` (`get`, `usage`), `vs.languages`,
   `vs.rtmp`, `vs.events`, `vs.meta`. Each method is named after its operation
   in the OpenAPI document (`transcriptions.create` is `POST /v1/transcriptions`).