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

package/dist/file.js

@@ -0,0 +1,38 @@
+export async function* fileChunks(input) {
+    if (typeof input === 'string') {
+        const fsSpecifier = 'node:' + 'fs';
+        const { createReadStream } = (await import(/* @vite-ignore */ fsSpecifier));
+        for await (const chunk of createReadStream(input)) {
+            yield chunk;
+        }
+        return;
+    }
+    if (input instanceof Uint8Array) {
+        yield input;
+        return;
+    }
+    if (input instanceof ArrayBuffer) {
+        yield new Uint8Array(input);
+        return;
+    }
+    if (typeof Blob !== 'undefined' && input instanceof Blob) {
+        const reader = input.stream().getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                if (value)
+                    yield value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    if (input && typeof input === 'object' && Symbol.asyncIterator in input) {
+        yield* input;
+        return;
+    }
+    throw new TypeError('transcribeFile: expected a path, Blob, byte array, or async iterable');
+}

package/dist/http.d.ts

@@ -0,0 +1,75 @@
+export type Query = Record<string, string | number | boolean | undefined | null>;
+export interface ClientOptions {
+    /** API origin; `https://api.vocalstack.com` when absent. */
+    baseUrl?: string;
+    /** An API key (`vs_key_…`), on a server: keys are refused from web
+     * pages.  Absent (and no `token`) = anonymous (a listener). */
+    apiKey?: string;
+    /** In a browser instead: a signed-in person's access token or a
+     * short-lived browser token (`vs_bt_…`), or a getter so a refreshed one
+     * is picked up per request.  Not with `apiKey`. */
+    token?: string | (() => string | undefined | null | Promise<string | undefined | null>);
+    /** Act for an organization the user belongs to (`X-Acting-Principal`). */
+    actingPrincipal?: string;
+    /** A stable per-device id (correlation only, `X-Device-Id`). */
+    deviceId?: string;
+    fetch?: typeof fetch;
+    /** How often a `429 rate_limited`, or a `503 unavailable` on a call that
+     * is safe to repeat (GET, HEAD, DELETE, or one with an `Idempotency-Key`),
+     * is retried after its `Retry-After` (at most 60 s each).  Default 2; 0
+     * turns it off. */
+    maxRetries?: number;
+    /** Default deadline for a realtime socket to report ready, in ms. */
+    readyDeadlineMs?: number;
+}
+/** Per-call options every method takes last. */
+export interface CallOptions {
+    /** Sent as `Idempotency-Key` on the creates that honour it. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/** How a listener reads something that is not theirs: a private
+ * broadcast's listener token, or a share link's code. */
+export interface ReadAs {
+    listenerToken?: string;
+    shareCode?: string;
+}
+/** A listener-side read's query: the wire spells both as the options do
+ * (`?listenerToken=`, `?shareCode=`), so this only picks them out. */
+export declare function listenerQuery(as: ReadAs | undefined): Query;
+export interface RequestInit2 extends CallOptions {
+    query?: Query;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Send no credential even when the client has one. */
+    anonymous?: boolean;
+    /** Never retry, whatever the answer (a single-use code). */
+    noRetry?: boolean;
+    /** Read a 400 as OAuth's `{ error, error_description }`. */
+    oauthErrors?: boolean;
+}
+export declare const DEFAULT_BASE_URL = "https://api.vocalstack.com";
+export declare function qs(q: Query | undefined): string;
+export declare const seg: (s: string | number) => string;
+/** Whether a failed call is retried after its `Retry-After` (up to
+ * `maxRetries` times): `429 rate_limited` always (nothing ran), and
+ * `503 unavailable` (the database is waking) only when repeating the call
+ * cannot do the work twice: GET, HEAD and DELETE, or a call carrying an
+ * `Idempotency-Key`. */
+export declare function retries(status: number, code: string, method: string, idempotencyKey?: string): boolean;
+/** The one HTTP path every resource method goes through. */
+export declare class Transport {
+    #private;
+    readonly baseUrl: string;
+    readonly opts: ClientOptions;
+    constructor(opts: ClientOptions);
+    /** What goes in `Authorization: Bearer`: the API key, else the token. */
+    bearer(): Promise<string | undefined>;
+    url(path: string, query?: Query): string;
+    wsUrl(path: string, query?: Query): string;
+    /** The raw response, after error mapping.  Redirects are not followed
+     * (`redirect: 'manual'`), so a 302 comes back as itself. */
+    raw(method: string, path: string, init?: RequestInit2): Promise<Response>;
+    /** A JSON call; an empty body resolves to `undefined`. */
+    json<T>(method: string, path: string, init?: RequestInit2): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,122 @@
+import { fromEnvelope, fromOAuth } from './errors.js';
+/** A listener-side read's query: the wire spells both as the options do
+ * (`?listenerToken=`, `?shareCode=`), so this only picks them out. */
+export function listenerQuery(as) {
+    return { listenerToken: as?.listenerToken, shareCode: as?.shareCode };
+}
+export const DEFAULT_BASE_URL = 'https://api.vocalstack.com';
+export function qs(q) {
+    if (!q)
+        return '';
+    const parts = [];
+    for (const [k, v] of Object.entries(q)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    return parts.length ? `?${parts.join('&')}` : '';
+}
+export const seg = (s) => encodeURIComponent(String(s));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The wait before retrying `503 unavailable` when it names none. */
+const UNAVAILABLE_WAIT_S = 2;
+/** Whether a failed call is retried after its `Retry-After` (up to
+ * `maxRetries` times): `429 rate_limited` always (nothing ran), and
+ * `503 unavailable` (the database is waking) only when repeating the call
+ * cannot do the work twice: GET, HEAD and DELETE, or a call carrying an
+ * `Idempotency-Key`. */
+export function retries(status, code, method, idempotencyKey) {
+    if (status === 429)
+        return true;
+    if (status !== 503 || code !== 'unavailable')
+        return false;
+    const m = method.toUpperCase();
+    return m === 'GET' || m === 'HEAD' || m === 'DELETE' || !!idempotencyKey;
+}
+/** The one HTTP path every resource method goes through. */
+export class Transport {
+    baseUrl;
+    opts;
+    #fetch;
+    constructor(opts) {
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+        if (opts.apiKey && opts.token)
+            throw new TypeError('VocalStack: pass apiKey (a server) or token (a browser), not both');
+        this.opts = opts;
+        this.#fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** What goes in `Authorization: Bearer`: the API key, else the token. */
+    async bearer() {
+        if (this.opts.apiKey)
+            return this.opts.apiKey;
+        const t = this.opts.token;
+        const v = typeof t === 'function' ? await t() : t;
+        return v ?? undefined;
+    }
+    url(path, query) {
+        return `${this.baseUrl}${path}${qs(query)}`;
+    }
+    wsUrl(path, query) {
+        return `${this.baseUrl.replace(/^http/, 'ws')}${path}${qs(query)}`;
+    }
+    /** The raw response, after error mapping.  Redirects are not followed
+     * (`redirect: 'manual'`), so a 302 comes back as itself. */
+    async raw(method, path, init = {}) {
+        const headers = { accept: 'application/json', ...init.headers };
+        const form = typeof FormData !== 'undefined' && init.body instanceof FormData;
+        const urlencoded = init.body instanceof URLSearchParams;
+        if (urlencoded)
+            headers['content-type'] = 'application/x-www-form-urlencoded';
+        else if (init.body !== undefined && !form)
+            headers['content-type'] = 'application/json';
+        const token = init.anonymous ? undefined : await this.bearer();
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        if (this.opts.actingPrincipal)
+            headers['x-acting-principal'] = this.opts.actingPrincipal;
+        if (this.opts.deviceId)
+            headers['x-device-id'] = this.opts.deviceId;
+        if (init.idempotencyKey)
+            headers['idempotency-key'] = init.idempotencyKey;
+        const body = init.body === undefined ? undefined : form ? init.body : urlencoded ? String(init.body) : JSON.stringify(init.body);
+        const maxRetries = init.noRetry ? 0 : (this.opts.maxRetries ?? 2);
+        for (let attempt = 0;; attempt++) {
+            const res = await this.#fetch(this.url(path, init.query), {
+                method,
+                headers,
+                body,
+                redirect: 'manual',
+                signal: init.signal,
+            });
+            if (res.ok || (res.status >= 300 && res.status < 400))
+                return res;
+            const text = await res.text().catch(() => '');
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                json = null;
+            }
+            const err = (init.oauthErrors ? fromOAuth : fromEnvelope)(json, res.status, res.headers);
+            if (retries(res.status, err.code, method, init.idempotencyKey) && attempt < maxRetries) {
+                // `unavailable` (a waking database) asks for Retry-After: 2; a
+                // missing header means the same.
+                const wait = err.retryAfter ?? (err.code === 'unavailable' ? UNAVAILABLE_WAIT_S : undefined);
+                if (wait !== undefined && wait <= 60) {
+                    await sleep(wait * 1000);
+                    continue;
+                }
+            }
+            throw err;
+        }
+    }
+    /** A JSON call; an empty body resolves to `undefined`. */
+    async json(method, path, init = {}) {
+        const res = await this.raw(method, path, init);
+        if (res.status >= 300 && res.status < 400)
+            return { location: res.headers.get('location') };
+        const text = await res.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,56 @@
-export * from './apis/index';
-export * from './generics.zod';
+/**
+ * The VocalStack SDK: one client, `VocalStack`, grouped by resource.
+ *
+ *   import { VocalStack } from '@vocalstack/js-sdk';
+ *   const vs = new VocalStack({ apiKey: process.env.VOCALSTACK_API_KEY });
+ *
+ *   const tx = await vs.transcriptions.createFromUrl('https://example.com/talk.mp3');
+ *   const job = await vs.jobs.wait(tx.job!.recordingId);
+ *   const { sentences } = await vs.recordings.transcript(job.recordingId);
+ *
+ * What is what (the API's glossary): a realtime session is a signed token
+ * plus one socket, nothing stored (`vs.realtime`); a broadcast is the link
+ * listeners open; a transcription is a file, link, microphone or stream
+ * transcribed and stored; a recording is one take inside either; a job is
+ * a file or link recording's transcription work.
+ */
+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, 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 { 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, Transcriptions, Voices, } from './resources.js';
+export type { AddBatchFileInput, ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
+export type * from '@vocalstack/contract';
+export type VocalStackOptions = ClientOptions;
+export declare class VocalStack {
+    readonly baseUrl: string;
+    readonly realtime: Realtime;
+    readonly broadcasts: Broadcasts;
+    readonly transcriptions: Transcriptions;
+    readonly batches: Batches;
+    readonly recordings: Recordings;
+    readonly jobs: Jobs;
+    readonly corrections: Corrections;
+    readonly shareLinks: ShareLinks;
+    readonly voices: Voices;
+    readonly search: Search;
+    readonly me: MeApi;
+    readonly connect: Connect;
+    readonly billing: Billing;
+    readonly languages: Languages;
+    readonly rtmp: Rtmp;
+    readonly events: Events;
+    readonly meta: Meta;
+    constructor(opts?: ClientOptions);
+}

package/dist/index.js

@@ -1,18 +1,66 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
+/**
+ * The VocalStack SDK: one client, `VocalStack`, grouped by resource.
+ *
+ *   import { VocalStack } from '@vocalstack/js-sdk';
+ *   const vs = new VocalStack({ apiKey: process.env.VOCALSTACK_API_KEY });
+ *
+ *   const tx = await vs.transcriptions.createFromUrl('https://example.com/talk.mp3');
+ *   const job = await vs.jobs.wait(tx.job!.recordingId);
+ *   const { sentences } = await vs.recordings.transcript(job.recordingId);
+ *
+ * What is what (the API's glossary): a realtime session is a signed token
+ * plus one socket, nothing stored (`vs.realtime`); a broadcast is the link
+ * listeners open; a transcription is a file, link, microphone or stream
+ * transcribed and stored; a recording is one take inside either; a job is
+ * a file or link recording's transcription work.
+ */
+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, 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, Transcriptions, Voices, } from './resources.js';
+export class VocalStack {
+    baseUrl;
+    realtime;
+    broadcasts;
+    transcriptions;
+    batches;
+    recordings;
+    jobs;
+    corrections;
+    shareLinks;
+    voices;
+    search;
+    me;
+    connect;
+    billing;
+    languages;
+    rtmp;
+    events;
+    meta;
+    constructor(opts = {}) {
+        const t = new Transport(opts);
+        this.baseUrl = t.baseUrl;
+        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);
+        this.shareLinks = new ShareLinks(t);
+        this.voices = new Voices(t);
+        this.search = new Search(t);
+        this.me = new MeApi(t);
+        this.connect = new Connect(t);
+        this.billing = new Billing(t);
+        this.languages = new Languages(t);
+        this.rtmp = new Rtmp(t);
+        this.events = new Events(t);
+        this.meta = new Meta(t);
     }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./apis/index"), exports);
-__exportStar(require("./generics.zod"), exports);
+}

package/dist/mic.d.ts

@@ -0,0 +1,75 @@
+import type { RealtimeSession } from './realtime.js';
+/** Why capture stopped producing audio (see `MicCaptureOptions.onStall`). */
+export type MicStallReason = 
+/** The input track ended: device unplugged, headset switched, permission revoked. */
+'track_ended'
+/** The track is muted by the OS/hardware (no samples until it unmutes). */
+ | 'track_muted'
+/** The AudioContext was suspended (phone call, screen lock, route change). */
+ | 'context_suspended'
+/** The AudioContext was closed underneath us. */
+ | 'context_closed'
+/** Seconds of exact-zero samples: a silently denied or hardware-muted mic. */
+ | 'silent';
+export interface MicCaptureOptions {
+    chunkSeconds?: number;
+    sampleRate?: number;
+    audio?: MediaTrackConstraints;
+    /**
+     * Called every ~0.5s with (pcm, wall): cumulative output samples
+     * produced and seconds since capture start.  Wire it to
+     * `session.sendClock` so the server can detect capture loss (a
+     * suspended context or dead track produces no samples while wall
+     * time advances) and mark the transcript with honest gaps.  Driven
+     * by a timer, not by sample arrival, so it keeps reporting while
+     * capture is stalled — that is the case it exists for.
+     */
+    onClock?: (pcm: number, wall: number) => void;
+    /**
+     * Capture stopped producing audio.  Recovery is attempted
+     * automatically (context resume, track re-acquire); `onRecover`
+     * fires when samples flow again.  Use it to show a "microphone
+     * lost" state instead of "Listening".
+     */
+    onStall?: (reason: MicStallReason) => void;
+    /** Audio is flowing again after a stall. */
+    onRecover?: () => void;
+    /**
+     * Exact-zero run length (seconds) that flags a silently denied or
+     * hardware-muted mic (real mics always carry a noise floor).  Default
+     * 3; 0 disables.
+     */
+    silentSeconds?: number;
+}
+/** The input device the capture is reading, as the browser reports it. */
+export interface MicDevice {
+    /** The device's name, e.g. "MacBook Pro Microphone" ("" before permission is granted). */
+    label: string;
+    /** Its native rate (the capture resamples to `sampleRate`). */
+    sampleRate?: number;
+    channelCount?: number;
+    noiseSuppression?: boolean;
+    echoCancellation?: boolean;
+}
+export interface MicCapture {
+    stop(): Promise<void>;
+    readonly sampleRate: number;
+    /** The microphone being read now (a re-acquired track may be another one). */
+    readonly device: MicDevice;
+    /** Hold the capture open but stop sending what the microphone hears.
+     *
+     *  A side conversation should not have to end the session, and pausing
+     *  is not the same thing: pausing closes the stream and the listeners
+     *  lose it. Muting keeps every listener connected and the recording
+     *  running, and simply says nothing.
+     *
+     *  Muted chunks are emitted as SILENCE rather than dropped. The server
+     *  measures media time by the audio it receives, so dropping would
+     *  compress the timeline and every later timestamp would be wrong;
+     *  silence keeps the clock honest and transcribes to nothing, which is
+     *  exactly what happened. */
+    setMuted(muted: boolean): void;
+    readonly muted: boolean;
+}
+export declare function captureMicrophone(onChunk: (pcm: Float32Array) => void, opts?: MicCaptureOptions): Promise<MicCapture>;
+export declare function streamMicrophone(session: RealtimeSession, opts?: MicCaptureOptions): Promise<MicCapture>;