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

package/dist/subscription.d.ts

@@ -1,19 +1,10 @@
 import type { ServerFrame, SubscriberFrame, TranscriptSnapshot } from '@vocalstack/contract';
 export interface SubscribeOptions {
-    /** Read (and hear) the recording in this language. */
     lang?: string;
-    /** Which voice speaks `lang` for this listener: a voice id from
-     * `vs.voices.available(lang)`.  Omitted means the recording's
-     * `settings.voiceByLang` pin, then the engine's pick. */
     voice?: string;
-    /** A private broadcast's listener token (the one VocalStack's listener page holds). */
     listenerToken?: string;
-    /** Read a transcription through its share link. */
     shareCode?: string;
-    /** With a token the socket is an owner subscriber (full frames, audience
-     * counts); `false` listens as a plain listener. */
     asOwner?: boolean;
-    /** Live original audio (binary Opus frames) from the start. */
     audio?: boolean;
 }
 export type SubscriptionEvent = {
@@ -32,22 +23,14 @@ export type SubscriptionEvent = {
     reason?: string;
 };
 type Snapshotter = (after: number | undefined) => Promise<TranscriptSnapshot>;
-/** A recording's live fan-out (`vs.recordings.subscribe`).  It resolves
- * once the backfill snapshot is in place; live frames follow through the
- * async iterator, with gaps detected on the cursor and healed by
- * re-snapshotting. */
 export declare class Subscription implements AsyncIterable<SubscriptionEvent> {
     #private;
     readonly recordingId: string;
-    /** Highest durable cursor applied (snapshot or frame). */
     cursor: number;
     snapshot: TranscriptSnapshot | null;
     private constructor();
-    /** @internal */
     static open(recordingId: string, url: string, bearer: string | undefined, opts: SubscribeOptions, snap: Snapshotter): Promise<Subscription>;
-    /** Switch the target language (`null` = as spoken). */
     setLanguage(lang: string | null): void;
-    /** Opt in or out of live original audio. */
     setAudio(enabled: boolean): void;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<SubscriptionEvent>;

package/dist/subscription.js

@@ -1,12 +1,7 @@
 import { VocalStackError } from './errors.js';
 import { openWebSocket, WS_OPEN } from './ws.js';
-/** A recording's live fan-out (`vs.recordings.subscribe`).  It resolves
- * once the backfill snapshot is in place; live frames follow through the
- * async iterator, with gaps detected on the cursor and healed by
- * re-snapshotting. */
 export class Subscription {
     recordingId;
-    /** Highest durable cursor applied (snapshot or frame). */
     cursor = -1;
     snapshot = null;
     #snap;
@@ -23,7 +18,6 @@ export class Subscription {
         this.#opts = opts;
         this.#snap = snap;
     }
-    /** @internal */
     static async open(recordingId, url, bearer, opts, snap) {
         const ws = await openWebSocket(url, bearer);
         ws.binaryType = 'arraybuffer';
@@ -77,7 +71,6 @@ export class Subscription {
             this.#onFrame(b.frame);
     }
     #onFrame(frame) {
-        // The relay cursor is `cursor`; segment-scoped frames use `seq` for the segment.
         const seq = typeof frame.cursor === 'number' ? frame.cursor : typeof frame.seq === 'number' ? frame.seq : undefined;
         if (this.#buffering) {
             this.#buffering.push({ seq, frame });
@@ -85,7 +78,7 @@ export class Subscription {
         }
         if (seq !== undefined) {
             if (seq <= this.cursor)
-                return; // already in the snapshot
+                return;
             if (seq > this.cursor + 1 && !this.#healing) {
                 this.#healing = true;
                 this.#buffering = [{ seq, frame }];
@@ -106,13 +99,10 @@ export class Subscription {
         this.#queue.push(ev);
         this.#wake?.();
     }
-    /** Switch the target language (`null` = as spoken). */
     setLanguage(lang) {
-        // A gap heal re-reads the snapshot in the language being read now.
         this.#opts.lang = lang ?? undefined;
         this.#send({ type: 'subscribe.update', lang: lang ?? 'none' });
     }
-    /** Opt in or out of live original audio. */
     setAudio(enabled) {
         this.#send({ type: 'subscribe.update', audio: enabled });
     }
@@ -128,7 +118,6 @@ export class Subscription {
             this.#ws.close();
         }
         catch {
-            // already closed
         }
         this.#wake?.();
     }

package/dist/ws.d.ts

@@ -6,7 +6,4 @@ export interface WsLike {
     addEventListener(type: string, listener: (ev: any) => void): void;
 }
 export declare const WS_OPEN = 1;
-/** Open a socket.  `bearer` is the caller's credential: Node sends it as
- * an `Authorization` header (an API key is refused in a URL); a browser
- * cannot set socket headers, so it rides in `access_token` instead. */
 export declare function openWebSocket(url: string, bearer?: string): Promise<WsLike>;

package/dist/ws.js

@@ -2,9 +2,6 @@ export const WS_OPEN = 1;
 const isNode = () => typeof globalThis.process?.versions?.node === 'string' &&
     !globalThis.Deno &&
     !globalThis.Bun;
-/** Open a socket.  `bearer` is the caller's credential: Node sends it as
- * an `Authorization` header (an API key is refused in a URL); a browser
- * cannot set socket headers, so it rides in `access_token` instead. */
 export async function openWebSocket(url, bearer) {
     if (!isNode() && typeof globalThis.WebSocket === 'function') {
         const u = bearer ? `${url}${url.includes('?') ? '&' : '?'}access_token=${encodeURIComponent(bearer)}` : url;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocalstack/js-sdk",
-  "version": "2.0.0-alpha.0",
+  "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.0",
+    "@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

@@ -33,11 +33,8 @@ npm init -y && npm pkg set type=module   # in a new folder: the programs below a
 npm i @vocalstack/js-sdk                    # Node 20 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a clone of https://github.com/vocalstack/js-sdk. Build it
+To run code newer than the npm release, install it from a clone of
+https://github.com/vocalstack/js-sdk. Build it
 first (`npm run build` also builds the bundled `contract/` package):
 
 ```sh
@@ -105,7 +102,7 @@ const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: pr
 
 const tx = await vs.transcriptions.create({
   file: process.argv[2], // a path (mp3, wav, flac, ogg, m4a, mp4 ...), a Blob or bytes
-  settings: { spokenLanguage: 'en', speakerLabels: 'on' }, // both optional; speakerLabels: 'off' (default) | 'auto' | 'on'
+  settings: { spokenLanguage: 'en', speakerLabels: 'on' }, // both optional; speakerLabels: 'auto' (default) | 'on' | 'off'
   // Off unless asked for: settings.summary, settings.title, settings.summaryTranslations,
   // settings.voice (spoken translations), and shareLink: true (a public share link).
 });
@@ -182,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