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

package/README.md

@@ -31,8 +31,9 @@ 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 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.
 - [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.
+- [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.

package/SKILL.md

@@ -179,6 +179,16 @@ for (const h of hits) {
 }
 ```
 
+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
+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);
+```
+
 ## 6. A batch of files
 
 Many files at once cost less as a batch: one create, one minimum charge for

package/dist/index.d.ts

@@ -14,8 +14,8 @@ 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 type { AudioKind, MediaAuth, MediaFormat, RenderVoice, VoicesChoice } from './resources.js';
+export type { AddBatchFileInput, 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 {

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, 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, 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,13 +62,13 @@ 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>;
@@ -131,6 +144,7 @@ export declare class Recordings {
     audioSrc(id: string, opts?: {
         kind?: AudioKind;
         lang?: string;
+        voices?: VoicesChoice;
         voice?: string;
         format?: MediaFormat;
     } & MediaAuth): string;
@@ -138,6 +152,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 +164,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 +184,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 +279,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 +291,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 } });
     }
@@ -292,7 +307,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 +315,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 +333,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 +558,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.2",
   "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.2",
     "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

@@ -179,6 +179,16 @@ for (const h of hits) {
 }
 ```
 
+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
+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);
+```
+
 ## 6. A batch of files
 
 Many files at once cost less as a batch: one create, one minimum charge for