assemblyai 4.35.4 → 4.36.4

package/dist/node.cjs

@@ -1,9 +1,14 @@
 'use strict';
 
-var web = require('stream/web');
-var ws = require('ws');
 var fs = require('fs');
 var stream = require('stream');
+var web = require('stream/web');
+var ws = require('ws');
+
+/**
+ * The default speech model for synchronous transcription.
+ */
+const defaultSyncSpeechModel = "universal-3-5-pro";
 
 /**
  * Thrown when `DualChannelCapture` is constructed in a non-browser environment
@@ -18,6 +23,8 @@ class BrowserOnlyError extends Error {
     }
 }
 
+const readFile = async (path) => stream.Readable.toWeb(fs.createReadStream(path));
+
 const DEFAULT_FETCH_INIT = {
     cache: "no-store",
 };
@@ -35,7 +42,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.35.4" },
+    sdk: { name: "JavaScript", version: "4.36.4" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -74,12 +81,15 @@ class BaseService {
             this.userAgent = buildUserAgent(params.userAgent || {});
         }
     }
-    async fetch(input, init) {
+    async fetchResponse(input, init) {
         init = { ...DEFAULT_FETCH_INIT, ...init };
         let headers = {
             Authorization: this.params.apiKey,
-            "Content-Type": "application/json",
         };
+        // FormData bodies must let fetch set the multipart boundary itself.
+        if (!(init.body instanceof FormData)) {
+            headers["Content-Type"] = "application/json";
+        }
         if (DEFAULT_FETCH_INIT?.headers)
             headers = { ...headers, ...DEFAULT_FETCH_INIT.headers };
         if (init?.headers)
@@ -90,7 +100,10 @@ class BaseService {
         init.headers = headers;
         if (!input.startsWith("http"))
             input = this.params.baseUrl + input;
-        const response = await fetch(input, init);
+        return await fetch(input, init);
+    }
+    async fetch(input, init) {
+        const response = await this.fetchResponse(input, init);
         if (response.status >= 400) {
             let json;
             const text = await response.text();
@@ -115,52 +128,342 @@ class BaseService {
     }
 }
 
-class LemurService extends BaseService {
-    summary(params, signal) {
-        return this.fetchJson("/lemur/v3/generate/summary", {
-            method: "POST",
-            body: JSON.stringify(params),
-            signal,
-        });
-    }
-    questionAnswer(params, signal) {
-        return this.fetchJson("/lemur/v3/generate/question-answer", {
-            method: "POST",
-            body: JSON.stringify(params),
-            signal,
-        });
+/**
+ * Error thrown when a synchronous transcription request fails.
+ */
+class SyncTranscriptError extends Error {
+    /**
+     * Create a new SyncTranscriptError.
+     * @param message - The human-readable error message.
+     * @param status - The HTTP status code of the failed request.
+     * @param errorCode - Machine-readable code — the snake_cased
+     * problem-details `title` from the server (e.g. `bad_audio`,
+     * `audio_too_large`, `capacity_exceeded`, `inference_timeout`).
+     * @param retryAfter - Seconds to wait before retrying, from the
+     * `Retry-After` header on 429/503 responses.
+     */
+    constructor(message, status, errorCode, retryAfter) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.retryAfter = retryAfter;
+        this.name = "SyncTranscriptError";
     }
-    actionItems(params, signal) {
-        return this.fetchJson("/lemur/v3/generate/action-items", {
-            method: "POST",
-            body: JSON.stringify(params),
-            signal,
-        });
+}
+
+function getPath(path) {
+    if (path.startsWith("http"))
+        return null;
+    if (path.startsWith("https"))
+        return null;
+    if (path.startsWith("data:"))
+        return null;
+    if (path.startsWith("file://"))
+        return path.substring(7);
+    if (path.startsWith("file:"))
+        return path.substring(5);
+    return path;
+}
+
+// Canonical paths since the sync API gained a /v1 prefix (#18103); the
+// unprefixed routes remain served for SDK versions that predate it.
+const transcribeEndpoint = "/v1/transcribe";
+const warmEndpoint = "/v1/warm";
+const modelHeader = "X-AAI-Model";
+// Kept above the server's 30 s deadline so the client doesn't race it.
+const defaultTimeoutMs = 60_000;
+const warmTimeoutMs = 10_000;
+const maxPromptLength = 4096;
+const maxKeytermsPromptLength = 2048;
+const maxContextTurns = 100;
+const maxContextLength = 4096;
+// Extensions that signal raw S16LE PCM rather than a WAV container.
+const pcmSuffixes = [".pcm", ".raw"];
+/**
+ * The synchronous transcription service: audio in, transcript out,
+ * one request.
+ *
+ * Unlike `client.transcripts` (which submits a job to the async API and
+ * polls for completion), `SyncTranscriber` posts the audio to the sync
+ * API and returns the finished transcript in the HTTP response. There is no
+ * job id or status to poll. Accepts a local file path, raw audio bytes, a
+ * Blob, or a readable stream — but not a URL.
+ */
+class SyncTranscriber extends BaseService {
+    /**
+     * Create a new synchronous transcription service.
+     * @param params - The parameters to use for the service.
+     */
+    constructor(params) {
+        super(params);
     }
-    task(params, signal) {
-        return this.fetchJson("/lemur/v3/generate/task", {
+    /**
+     * Transcribe audio and return the finished transcript in one request.
+     * @param audio - A local file path, raw audio bytes, a Blob, or a readable
+     * stream. Raw PCM also requires `sample_rate` and `channels` on the config.
+     * @param config - Options for this transcription request.
+     * @param options - Client-side options, such as the request timeout.
+     * @returns A promise that resolves to the finished transcript.
+     * @throws SyncTranscriptError when the request fails.
+     */
+    async transcribe(audio, config = {}, options = {}) {
+        const { bytes, filename, contentType } = await resolveAudio(audio, config);
+        const body = new FormData();
+        body.append("audio", new Blob([bytes], { type: contentType }), filename);
+        const configJson = buildConfigJson(config);
+        if (configJson) {
+            body.append("config", new Blob([JSON.stringify(configJson)], { type: "application/json" }));
+        }
+        const response = await this.fetchResponse(transcribeEndpoint, {
             method: "POST",
-            body: JSON.stringify(params),
-            signal,
+            body,
+            headers: { [modelHeader]: config.model ?? defaultSyncSpeechModel },
+            signal: AbortSignal.timeout(options.timeout ?? defaultTimeoutMs),
         });
-    }
-    getResponse(id, signal) {
-        return this.fetchJson(`/lemur/v3/${id}`, { signal });
+        if (response.status !== 200)
+            throw await errorFromResponse(response);
+        return (await response.json());
     }
     /**
-     * Delete the data for a previously submitted LeMUR request.
-     * @param id - ID of the LeMUR request
-     * @param signal - Optional AbortSignal to cancel the request
+     * Open the connection to the sync API ahead of time.
+     *
+     * The sync API is a single request/response, so a `transcribe()` that
+     * opens its connection on demand pays the full DNS + TCP + TLS handshake
+     * on the critical path. Call `warm()` as soon as you know audio is coming —
+     * typically while the clip is still being recorded — so the next
+     * `transcribe()` reuses the already-open connection. `warm()` is idempotent
+     * and cheap; call it shortly before `transcribe()` so the pooled connection
+     * hasn't idled out.
+     * @param params - Optionally the model to route the probe to, so the warmed
+     * connection lands on the same backend as the eventual transcription.
+     * @returns A promise that resolves to `true` once the connection is open
+     * (any HTTP response — even a non-200 — means the socket is
+     * established), or `false` if the connection could not be opened.
      */
-    purgeRequestData(id, signal) {
-        return this.fetchJson(`/lemur/v3/${id}`, {
-            method: "DELETE",
-            signal,
-        });
+    async warm(params) {
+        try {
+            await this.fetchResponse(warmEndpoint, {
+                method: "GET",
+                headers: { [modelHeader]: params?.model ?? defaultSyncSpeechModel },
+                signal: AbortSignal.timeout(warmTimeoutMs),
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
 }
-
-const factory = (url, params) => new ws(url, params);
+/**
+ * Read the audio input into bytes and decide its multipart content type.
+ *
+ * PCM is selected when the source has a `.pcm`/`.raw` extension or when
+ * `sample_rate`/`channels` are set on the config (the fields the sync API
+ * requires only for raw PCM) — and both must then be present. Everything
+ * else is treated as a WAV container. URLs are rejected — the sync API has
+ * no URL ingestion.
+ */
+async function resolveAudio(input, config) {
+    let bytes;
+    let filename;
+    let suffix = "";
+    if (typeof input === "string") {
+        if (/^https?:\/\//i.test(input)) {
+            throw new Error("SyncTranscriber does not accept URLs. Pass a local file path or " +
+                "audio bytes, or use client.transcripts for URL/async transcription.");
+        }
+        if (input.startsWith("data:")) {
+            bytes = dataUrlToBytes(input);
+        }
+        else {
+            const path = getPath(input) ?? input;
+            bytes = await readStream(await readFile(path));
+            filename = basename(path);
+            suffix = extname(filename);
+        }
+    }
+    else if (input instanceof Uint8Array) {
+        bytes = input;
+    }
+    else if (input instanceof ArrayBuffer) {
+        bytes = new Uint8Array(input);
+    }
+    else if (input instanceof Blob) {
+        bytes = new Uint8Array(await input.arrayBuffer());
+        // File instances carry a name; the File global itself needs Node >= 20.
+        const name = input.name;
+        if (name) {
+            filename = basename(name);
+            suffix = extname(filename);
+        }
+    }
+    else if (isWebReadableStream(input)) {
+        bytes = await readStream(input);
+    }
+    else if (isAsyncIterable(input)) {
+        bytes = await readAsyncIterable(input);
+        // fs.ReadStream carries the path it was opened from.
+        const path = input.path;
+        if (typeof path === "string") {
+            filename = basename(path);
+            suffix = extname(filename);
+        }
+    }
+    else {
+        throw new TypeError("unsupported audio input type");
+    }
+    const wantsPcm = config.sample_rate !== undefined || config.channels !== undefined;
+    const isPcm = pcmSuffixes.includes(suffix) || wantsPcm;
+    if (isPcm &&
+        (config.sample_rate === undefined || config.channels === undefined)) {
+        throw new Error("raw PCM audio requires both sample_rate and channels in the config");
+    }
+    const contentType = isPcm ? "audio/pcm" : "audio/wav";
+    if (!filename)
+        filename = isPcm ? "audio.pcm" : "audio.wav";
+    return { bytes, filename, contentType };
+}
+/**
+ * Serialize the config to the JSON `config` part, validating and normalizing
+ * field values to match the server's caps. The routing `model` is never
+ * included — it travels in the `X-AAI-Model` header. Returns `undefined`
+ * when there is nothing to send, so the part can be omitted entirely.
+ */
+function buildConfigJson(config) {
+    if (config.prompt !== undefined && config.prompt.length > maxPromptLength) {
+        throw new Error(`prompt exceeds ${maxPromptLength} characters (got ${config.prompt.length})`);
+    }
+    const json = {};
+    if (config.prompt !== undefined)
+        json["prompt"] = config.prompt;
+    const keytermsPrompt = normalizeKeytermsPrompt(config.keyterms_prompt);
+    if (keytermsPrompt)
+        json["keyterms_prompt"] = keytermsPrompt;
+    const context = normalizeConversationContext(config.conversation_context);
+    if (context)
+        json["conversation_context"] = context;
+    if (config.language_codes !== undefined)
+        json["language_codes"] = config.language_codes;
+    if (config.sample_rate !== undefined)
+        json["sample_rate"] = config.sample_rate;
+    if (config.channels !== undefined)
+        json["channels"] = config.channels;
+    if (config.timestamps !== undefined)
+        json["timestamps"] = config.timestamps;
+    return Object.keys(json).length > 0 ? json : undefined;
+}
+function normalizeKeytermsPrompt(keytermsPrompt) {
+    if (!keytermsPrompt)
+        return undefined;
+    const terms = keytermsPrompt
+        .map((term) => term.trim())
+        .filter((term) => term.length > 0);
+    const total = terms.reduce((sum, term) => sum + term.length, 0);
+    if (total > maxKeytermsPromptLength) {
+        throw new Error(`keyterms_prompt exceeds ${maxKeytermsPromptLength} characters (got ${total})`);
+    }
+    return terms.length > 0 ? terms : undefined;
+}
+function normalizeConversationContext(context) {
+    if (context === undefined)
+        return undefined;
+    let turns = (typeof context === "string" ? [context] : context)
+        .map((turn) => turn.trim())
+        .filter((turn) => turn.length > 0);
+    let total = turns.reduce((sum, turn) => sum + turn.length, 0);
+    // Over-cap context is trimmed oldest-first, never rejected.
+    while (turns.length > 0 &&
+        (turns.length > maxContextTurns || total > maxContextLength)) {
+        total -= turns[0].length;
+        turns = turns.slice(1);
+    }
+    return turns.length > 0 ? turns : undefined;
+}
+/**
+ * Build a SyncTranscriptError from a non-200 response. The primary format
+ * is an RFC 9457 problem-details body (`status`/`title`/`detail`); legacy
+ * `{error_code, message}` and `{detail}`-only bodies are also accepted.
+ */
+async function errorFromResponse(response) {
+    let errorCode;
+    let message;
+    const text = await response.text();
+    try {
+        const body = JSON.parse(text);
+        if (body && typeof body === "object" && !Array.isArray(body)) {
+            if (typeof body.error_code === "string")
+                errorCode = body.error_code;
+            if (errorCode === undefined && typeof body.title === "string") {
+                errorCode = body.title.toLowerCase().replace(/ /g, "_");
+            }
+            if (typeof body.detail === "string")
+                message = body.detail;
+            else if (typeof body.message === "string")
+                message = body.message;
+        }
+    }
+    catch {
+        if (text)
+            message = text;
+    }
+    if (!message) {
+        message = `sync transcription failed with status ${response.status}`;
+    }
+    const retryHeader = response.headers.get("retry-after");
+    const retryAfter = retryHeader && /^\d+$/.test(retryHeader)
+        ? parseInt(retryHeader, 10)
+        : undefined;
+    return new SyncTranscriptError(message, response.status, errorCode, retryAfter);
+}
+function basename(path) {
+    return path.split(/[\\/]/).pop() ?? path;
+}
+function extname(filename) {
+    const dotIndex = filename.lastIndexOf(".");
+    return dotIndex > 0 ? filename.slice(dotIndex).toLowerCase() : "";
+}
+function dataUrlToBytes(dataUrl) {
+    const base64 = dataUrl.split(",")[1];
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function isWebReadableStream(input) {
+    return typeof input?.getReader === "function";
+}
+function isAsyncIterable(input) {
+    return (typeof input?.[Symbol.asyncIterator] ===
+        "function");
+}
+async function readStream(stream) {
+    const chunks = [];
+    const reader = stream.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return concatChunks(chunks);
+}
+async function readAsyncIterable(iterable) {
+    const chunks = [];
+    for await (const chunk of iterable)
+        chunks.push(chunk);
+    return concatChunks(chunks);
+}
+function concatChunks(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return bytes;
+}
 
 const RealtimeErrorType = {
     BadSampleRate: 4000,
@@ -266,6 +569,53 @@ const StreamingErrorMessages = {
 class StreamingError extends Error {
 }
 
+class LemurService extends BaseService {
+    summary(params, signal) {
+        return this.fetchJson("/lemur/v3/generate/summary", {
+            method: "POST",
+            body: JSON.stringify(params),
+            signal,
+        });
+    }
+    questionAnswer(params, signal) {
+        return this.fetchJson("/lemur/v3/generate/question-answer", {
+            method: "POST",
+            body: JSON.stringify(params),
+            signal,
+        });
+    }
+    actionItems(params, signal) {
+        return this.fetchJson("/lemur/v3/generate/action-items", {
+            method: "POST",
+            body: JSON.stringify(params),
+            signal,
+        });
+    }
+    task(params, signal) {
+        return this.fetchJson("/lemur/v3/generate/task", {
+            method: "POST",
+            body: JSON.stringify(params),
+            signal,
+        });
+    }
+    getResponse(id, signal) {
+        return this.fetchJson(`/lemur/v3/${id}`, { signal });
+    }
+    /**
+     * Delete the data for a previously submitted LeMUR request.
+     * @param id - ID of the LeMUR request
+     * @param signal - Optional AbortSignal to cancel the request
+     */
+    purgeRequestData(id, signal) {
+        return this.fetchJson(`/lemur/v3/${id}`, {
+            method: "DELETE",
+            signal,
+        });
+    }
+}
+
+const factory = (url, params) => new ws(url, params);
+
 const defaultRealtimeUrl = "wss://api.assemblyai.com/v2/realtime/ws";
 const forceEndOfUtteranceMessage = `{"force_end_utterance":true}`;
 const terminateSessionMessage$1 = `{"terminate_session":true}`;
@@ -510,20 +860,6 @@ class RealtimeTranscriberFactory extends BaseService {
 class RealtimeServiceFactory extends RealtimeTranscriberFactory {
 }
 
-function getPath(path) {
-    if (path.startsWith("http"))
-        return null;
-    if (path.startsWith("https"))
-        return null;
-    if (path.startsWith("data:"))
-        return null;
-    if (path.startsWith("file://"))
-        return path.substring(7);
-    if (path.startsWith("file:"))
-        return path.substring(5);
-    return path;
-}
-
 class TranscriptService extends BaseService {
     constructor(params, files) {
         super(params);
@@ -751,8 +1087,6 @@ class TranscriptService extends BaseService {
     }
 }
 
-const readFile = async (path) => stream.Readable.toWeb(fs.createReadStream(path));
-
 class FileService extends BaseService {
     /**
      * Upload a local file to AssemblyAI.
@@ -1033,9 +1367,12 @@ class StreamingTranscriber {
         if (!(this.token || this.apiKey)) {
             throw new Error("API key or temporary token is required.");
         }
-        const isOpus = params.encoding === "opus" || params.encoding === "ogg_opus";
-        if (params.sampleRate === undefined && (!isOpus || params.channels)) {
-            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus" or "ogg_opus" (the Opus stream is self-describing) and dual-channel mode is not used.');
+        const isSelfDescribing = params.encoding === "opus" ||
+            params.encoding === "ogg_opus" ||
+            params.encoding === "aac";
+        if (params.sampleRate === undefined &&
+            (!isSelfDescribing || params.channels)) {
+            throw new Error('`sampleRate` is required; it may only be omitted when `encoding` is "opus", "ogg_opus", or "aac" (these streams are self-describing) and dual-channel mode is not used.');
         }
         if (params.channels) {
             if (params.channels.length !== 2) {
@@ -1113,6 +1450,9 @@ class StreamingTranscriber {
         if (this.params.formatTurns) {
             searchParams.set("format_turns", this.params.formatTurns.toString());
         }
+        if (this.params.sessionHeartbeat !== undefined) {
+            searchParams.set("session_heartbeat", this.params.sessionHeartbeat.toString());
+        }
         if (this.params.encoding) {
             searchParams.set("encoding", this.params.encoding.toString());
         }
@@ -1397,6 +1737,10 @@ class StreamingTranscriber {
                         this.listeners.warning?.(warning);
                         break;
                     }
+                    case "Heartbeat": {
+                        this.listeners.heartbeat?.(message);
+                        break;
+                    }
                     case "Termination": {
                         this.sessionTerminatedResolve?.();
                         break;
@@ -2014,6 +2358,7 @@ function float32ToPcm16(input) {
 
 const defaultBaseUrl = "https://api.assemblyai.com";
 const defaultStreamingUrl = "https://streaming.assemblyai.com";
+const defaultSyncUrl = "https://sync.assemblyai.com";
 class AssemblyAI {
     /**
      * Create a new AssemblyAI client.
@@ -2032,6 +2377,14 @@ class AssemblyAI {
             ...params,
             baseUrl: params.streamingBaseUrl || defaultStreamingUrl,
         });
+        let syncBaseUrl = params.syncBaseUrl || defaultSyncUrl;
+        if (syncBaseUrl.endsWith("/")) {
+            syncBaseUrl = syncBaseUrl.slice(0, -1);
+        }
+        this.sync = new SyncTranscriber({
+            ...params,
+            baseUrl: syncBaseUrl,
+        });
     }
 }
 
@@ -2047,9 +2400,12 @@ exports.RealtimeServiceFactory = RealtimeServiceFactory;
 exports.RealtimeTranscriber = RealtimeTranscriber;
 exports.RealtimeTranscriberFactory = RealtimeTranscriberFactory;
 exports.StreamingTranscriber = StreamingTranscriber;
+exports.SyncTranscriber = SyncTranscriber;
+exports.SyncTranscriptError = SyncTranscriptError;
 exports.TranscriptService = TranscriptService;
 exports.VadTimeline = VadTimeline;
 exports.attributeTurn = attributeTurn;
 exports.attributeWord = attributeWord;
+exports.defaultSyncSpeechModel = defaultSyncSpeechModel;
 exports.float32ToPcm16 = float32ToPcm16;
 exports.rollUpTurnChannel = rollUpTurnChannel;