assemblyai 4.34.6 → 4.35.0

package/dist/workerd.mjs

@@ -28,7 +28,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.34.6" },
+    sdk: { name: "JavaScript", version: "4.35.0" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -983,6 +983,24 @@ function toInt16View(audio) {
 }
 const defaultStreamingUrl$1 = "wss://streaming.assemblyai.com/v3/ws";
 const terminateSessionMessage = `{"type":"Terminate"}`;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1000;
+const DEFAULT_MAX_CONNECTION_RETRIES = 2;
+const DEFAULT_CONNECTION_RETRY_DELAY_MS = 500;
+/**
+ * Close/error codes that signal a permanent client-side problem (auth,
+ * billing, malformed config). A retry would hit the same failure, so the
+ * connection is never retried on these.
+ */
+const NON_RETRYABLE_CLOSE_CODES = new Set([
+    StreamingErrorType.BadSampleRate,
+    StreamingErrorType.AuthFailed,
+    StreamingErrorType.InsufficientFunds,
+    StreamingErrorType.FreeTierUser,
+    StreamingErrorType.BadSchema,
+]);
+function isRetryableCloseCode(code) {
+    return code !== 1000 && !NON_RETRYABLE_CLOSE_CODES.has(code);
+}
 /**
  * Per-send chunk cap in milliseconds for the dual-channel mixer. The streaming
  * server rejects audio messages longer than 1000 ms (`Input Duration Error`).
@@ -1191,12 +1209,81 @@ class StreamingTranscriber {
     on(event, listener) {
         this.listeners[event] = listener;
     }
-    connect() {
-        return new Promise((resolve) => {
-            if (this.socket) {
-                throw new Error("Already connected");
+    /**
+     * Open the streaming session.
+     *
+     * Resolves with the server's `Begin` event once the handshake completes. A
+     * single attempt is bounded by `connectTimeout` (default 1000ms); transient
+     * failures (timeout, network drop, unexpected close) are retried up to
+     * `maxConnectionRetries` times (default 2), waiting `connectionRetryDelay`
+     * (default 500ms) between attempts. Permanent failures (auth, insufficient
+     * funds, malformed config) are not retried.
+     *
+     * Unlike previously, a failed connection now rejects this promise rather
+     * than only invoking the `error` listener — necessary for the caller (and
+     * the retry loop) to observe the failure.
+     */
+    async connect() {
+        if (this.socket) {
+            throw new Error("Already connected");
+        }
+        const maxRetries = this.params.maxConnectionRetries ?? DEFAULT_MAX_CONNECTION_RETRIES;
+        const retryDelay = this.params.connectionRetryDelay ?? DEFAULT_CONNECTION_RETRY_DELAY_MS;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.connectOnce();
+            }
+            catch (err) {
+                lastError = err;
+                const retryable = err.retryable === true;
+                if (!retryable || attempt === maxRetries) {
+                    throw err;
+                }
+                console.warn(`Streaming connect attempt ${attempt + 1}/${maxRetries + 1} failed (${err.message}); retrying`);
+                if (retryDelay > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                }
             }
+        }
+        // The loop above always returns or throws; this only satisfies the type
+        // checker that a value is produced on every path.
+        throw lastError ?? new Error("Failed to connect to streaming server");
+    }
+    connectOnce() {
+        return new Promise((resolve, reject) => {
             const url = this.connectionUrl();
+            const timeoutMs = this.params.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT_MS;
+            // `settled` flips once this attempt has resolved (`Begin`) or rejected
+            // (timeout / pre-`Begin` close / error). Before it flips the socket
+            // handlers drive this promise; after it flips they revert to normal
+            // runtime dispatch (close / error / message listeners).
+            let settled = false;
+            let timer;
+            const failAttempt = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                this.discardPendingSocket();
+                reject(error);
+            };
+            const succeed = (begin) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                resolve(begin);
+            };
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    const err = new StreamingError(`Streaming connection timed out after ${timeoutMs}ms`);
+                    err.retryable = true;
+                    failAttempt(err);
+                }, timeoutMs);
+            }
             if (this.token) {
                 this.socket = factory(url.toString());
             }
@@ -1213,6 +1300,15 @@ class StreamingTranscriber {
                         reason = StreamingErrorMessages[code];
                     }
                 }
+                // A close before `Begin` is a failed connection attempt — reject so
+                // connect() can retry (or surface a permanent failure).
+                if (!settled) {
+                    const err = new StreamingError(reason || `Streaming connection closed (code=${code})`);
+                    err.code = code;
+                    err.retryable = isRetryableCloseCode(code);
+                    failAttempt(err);
+                    return;
+                }
                 // Stop the flush timer when the socket is gone (server-initiated close,
                 // network drop, etc.) — otherwise subsequent ticks call send() on a
                 // closed socket and spam the error listener.
@@ -1223,25 +1319,37 @@ class StreamingTranscriber {
                 this.listeners.close?.(code, reason);
             };
             this.socket.onerror = (event) => {
-                if (event.error)
-                    this.listeners.error?.(event.error);
-                else
-                    this.listeners.error?.(new Error(event.message));
+                const error = event.error ?? new Error(event.message);
+                // A socket error before `Begin` is a failed attempt → reject/retry.
+                if (!settled) {
+                    error.retryable = true;
+                    failAttempt(error);
+                    return;
+                }
+                this.listeners.error?.(error);
             };
             this.socket.onmessage = ({ data }) => {
                 const message = JSON.parse(data.toString());
                 if ("error" in message) {
                     const err = new StreamingError(message.error);
                     if ("error_code" in message) {
-                        err.code =
-                            message.error_code;
+                        err.code = message.error_code;
+                    }
+                    // A server error frame before `Begin` fails the attempt; the code
+                    // decides whether a retry is worthwhile.
+                    if (!settled) {
+                        const attemptErr = err;
+                        attemptErr.retryable =
+                            err.code === undefined ? true : isRetryableCloseCode(err.code);
+                        failAttempt(attemptErr);
+                        return;
                     }
                     this.listeners.error?.(err);
                     return;
                 }
                 switch (message.type) {
                     case "Begin": {
-                        resolve(message);
+                        succeed(message);
                         this.listeners.open?.(message);
                         break;
                     }
@@ -1288,6 +1396,20 @@ class StreamingTranscriber {
             };
         });
     }
+    /** Tear down a half-open socket from a failed connection attempt. */
+    discardPendingSocket() {
+        if (!this.socket)
+            return;
+        try {
+            if (this.socket.removeAllListeners)
+                this.socket.removeAllListeners();
+            this.socket.close();
+        }
+        catch {
+            // Best-effort cleanup; a half-open socket may throw on close.
+        }
+        this.socket = undefined;
+    }
     /**
      * Returns a WritableStream that pumps PCM chunks into `sendAudio`. Single-channel
      * only — in dual-channel mode use `sendAudio(pcm, { channel })` directly, since
@@ -1561,6 +1683,16 @@ class StreamingTranscriber {
         };
         this.send(JSON.stringify(message));
     }
+    /**
+     * Reset the server's inactivity timer. Only needed when the session was
+     * created with `inactivityTimeout` and no audio is being sent.
+     */
+    keepAlive() {
+        const message = {
+            type: "KeepAlive",
+        };
+        this.send(JSON.stringify(message));
+    }
     send(data) {
         if (!this.socket || this.socket.readyState !== this.socket.OPEN) {
             throw new Error("Socket is not open for communication");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assemblyai",
-  "version": "4.34.6",
+  "version": "4.35.0",
   "description": "The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription, as well as the latest LeMUR models.",
   "engines": {
     "node": ">=18"

package/src/services/streaming/service.ts

@@ -18,12 +18,17 @@ import {
   SpeakerRevisionEvent,
   StreamingUpdateConfiguration,
   StreamingForceEndpoint,
+  StreamingKeepAlive,
   WarningEvent,
 } from "../..";
 import type { VadDetector, VadFrame } from "../../types/streaming/dual-channel";
 import { EnergyVad } from "./energy-vad";
 import { attributeTurn, rollUpTurnChannel, VadTimeline } from "./label-mapper";
-import { StreamingError, StreamingErrorMessages } from "../../utils/errors";
+import {
+  StreamingError,
+  StreamingErrorMessages,
+  StreamingErrorType,
+} from "../../utils/errors";
 import { StreamingErrorTypeCodes } from "../../utils/errors/streaming";
 
 /**
@@ -58,6 +63,30 @@ function toInt16View(audio: AudioData): Int16Array {
 const defaultStreamingUrl = "wss://streaming.assemblyai.com/v3/ws";
 const terminateSessionMessage = `{"type":"Terminate"}`;
 
+const DEFAULT_CONNECT_TIMEOUT_MS = 1000;
+const DEFAULT_MAX_CONNECTION_RETRIES = 2;
+const DEFAULT_CONNECTION_RETRY_DELAY_MS = 500;
+
+/**
+ * Close/error codes that signal a permanent client-side problem (auth,
+ * billing, malformed config). A retry would hit the same failure, so the
+ * connection is never retried on these.
+ */
+const NON_RETRYABLE_CLOSE_CODES = new Set<number>([
+  StreamingErrorType.BadSampleRate,
+  StreamingErrorType.AuthFailed,
+  StreamingErrorType.InsufficientFunds,
+  StreamingErrorType.FreeTierUser,
+  StreamingErrorType.BadSchema,
+]);
+
+/** Error from a single connection attempt, tagged for retry handling. */
+type ConnectionAttemptError = Error & { code?: number; retryable: boolean };
+
+function isRetryableCloseCode(code: number): boolean {
+  return code !== 1000 && !NON_RETRYABLE_CLOSE_CODES.has(code);
+}
+
 /**
  * Per-send chunk cap in milliseconds for the dual-channel mixer. The streaming
  * server rejects audio messages longer than 1000 ms (`Input Duration Error`).
@@ -432,13 +461,90 @@ export class StreamingTranscriber {
     this.listeners[event] = listener;
   }
 
-  connect() {
-    return new Promise<BeginEvent>((resolve) => {
-      if (this.socket) {
-        throw new Error("Already connected");
+  /**
+   * Open the streaming session.
+   *
+   * Resolves with the server's `Begin` event once the handshake completes. A
+   * single attempt is bounded by `connectTimeout` (default 1000ms); transient
+   * failures (timeout, network drop, unexpected close) are retried up to
+   * `maxConnectionRetries` times (default 2), waiting `connectionRetryDelay`
+   * (default 500ms) between attempts. Permanent failures (auth, insufficient
+   * funds, malformed config) are not retried.
+   *
+   * Unlike previously, a failed connection now rejects this promise rather
+   * than only invoking the `error` listener — necessary for the caller (and
+   * the retry loop) to observe the failure.
+   */
+  async connect(): Promise<BeginEvent> {
+    if (this.socket) {
+      throw new Error("Already connected");
+    }
+
+    const maxRetries =
+      this.params.maxConnectionRetries ?? DEFAULT_MAX_CONNECTION_RETRIES;
+    const retryDelay =
+      this.params.connectionRetryDelay ?? DEFAULT_CONNECTION_RETRY_DELAY_MS;
+
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.connectOnce();
+      } catch (err) {
+        lastError = err as Error;
+        const retryable = (err as ConnectionAttemptError).retryable === true;
+        if (!retryable || attempt === maxRetries) {
+          throw err;
+        }
+        console.warn(
+          `Streaming connect attempt ${attempt + 1}/${maxRetries + 1} failed (${(err as Error).message}); retrying`,
+        );
+        if (retryDelay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
       }
+    }
+    // The loop above always returns or throws; this only satisfies the type
+    // checker that a value is produced on every path.
+    throw lastError ?? new Error("Failed to connect to streaming server");
+  }
 
+  private connectOnce(): Promise<BeginEvent> {
+    return new Promise<BeginEvent>((resolve, reject) => {
       const url = this.connectionUrl();
+      const timeoutMs =
+        this.params.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT_MS;
+
+      // `settled` flips once this attempt has resolved (`Begin`) or rejected
+      // (timeout / pre-`Begin` close / error). Before it flips the socket
+      // handlers drive this promise; after it flips they revert to normal
+      // runtime dispatch (close / error / message listeners).
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+
+      const failAttempt = (error: ConnectionAttemptError) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.discardPendingSocket();
+        reject(error);
+      };
+
+      const succeed = (begin: BeginEvent) => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        resolve(begin);
+      };
+
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const err = new StreamingError(
+            `Streaming connection timed out after ${timeoutMs}ms`,
+          ) as ConnectionAttemptError;
+          err.retryable = true;
+          failAttempt(err);
+        }, timeoutMs);
+      }
 
       if (this.token) {
         this.socket = polyfillWebSocketFactory(url.toString());
@@ -465,6 +571,17 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
             reason = StreamingErrorMessages[code as StreamingErrorTypeCodes];
           }
         }
+        // A close before `Begin` is a failed connection attempt — reject so
+        // connect() can retry (or surface a permanent failure).
+        if (!settled) {
+          const err = new StreamingError(
+            reason || `Streaming connection closed (code=${code})`,
+          ) as ConnectionAttemptError;
+          err.code = code;
+          err.retryable = isRetryableCloseCode(code);
+          failAttempt(err);
+          return;
+        }
         // Stop the flush timer when the socket is gone (server-initiated close,
         // network drop, etc.) — otherwise subsequent ticks call send() on a
         // closed socket and spam the error listener.
@@ -476,18 +593,34 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
       };
 
       this.socket.onerror = (event: ErrorEvent) => {
-        if (event.error) this.listeners.error?.(event.error as Error);
-        else this.listeners.error?.(new Error(event.message));
+        const error = (event.error as Error) ?? new Error(event.message);
+        // A socket error before `Begin` is a failed attempt → reject/retry.
+        if (!settled) {
+          (error as ConnectionAttemptError).retryable = true;
+          failAttempt(error as ConnectionAttemptError);
+          return;
+        }
+        this.listeners.error?.(error);
       };
 
       this.socket.onmessage = ({ data }: MessageEvent) => {
         const message = JSON.parse(data.toString()) as StreamingEventMessage;
 
         if ("error" in message) {
-          const err = new StreamingError(message.error);
+          const err = new StreamingError(message.error) as StreamingError & {
+            code?: number;
+          };
           if ("error_code" in message) {
-            (err as StreamingError & { code?: number }).code =
-              message.error_code;
+            err.code = message.error_code;
+          }
+          // A server error frame before `Begin` fails the attempt; the code
+          // decides whether a retry is worthwhile.
+          if (!settled) {
+            const attemptErr = err as ConnectionAttemptError;
+            attemptErr.retryable =
+              err.code === undefined ? true : isRetryableCloseCode(err.code);
+            failAttempt(attemptErr);
+            return;
           }
           this.listeners.error?.(err);
           return;
@@ -495,7 +628,7 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
 
         switch (message.type) {
           case "Begin": {
-            resolve(message);
+            succeed(message);
             this.listeners.open?.(message);
             break;
           }
@@ -548,6 +681,18 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
     });
   }
 
+  /** Tear down a half-open socket from a failed connection attempt. */
+  private discardPendingSocket(): void {
+    if (!this.socket) return;
+    try {
+      if (this.socket.removeAllListeners) this.socket.removeAllListeners();
+      this.socket.close();
+    } catch {
+      // Best-effort cleanup; a half-open socket may throw on close.
+    }
+    this.socket = undefined;
+  }
+
   /**
    * Returns a WritableStream that pumps PCM chunks into `sendAudio`. Single-channel
    * only — in dual-channel mode use `sendAudio(pcm, { channel })` directly, since
@@ -829,6 +974,17 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c
     this.send(JSON.stringify(message));
   }
 
+  /**
+   * Reset the server's inactivity timer. Only needed when the session was
+   * created with `inactivityTimeout` and no audio is being sent.
+   */
+  keepAlive() {
+    const message: StreamingKeepAlive = {
+      type: "KeepAlive",
+    };
+    this.send(JSON.stringify(message));
+  }
+
   private send(data: BufferLike) {
     if (!this.socket || this.socket.readyState !== this.socket.OPEN) {
       throw new Error("Socket is not open for communication");

package/src/types/streaming/index.ts

@@ -76,6 +76,22 @@ export type StreamingTranscriberParams = {
   websocketBaseUrl?: string;
   apiKey?: string;
   token?: string;
+  /**
+   * Milliseconds to wait for the streaming handshake (socket open + server
+   * `Begin`) before treating the attempt as failed. Defaults to 1000.
+   */
+  connectTimeout?: number;
+  /**
+   * Number of additional connection attempts after the first one fails on a
+   * transient error (timeout, network drop, unexpected close). 0 disables
+   * retries. Permanent failures (auth, insufficient funds, malformed config)
+   * are never retried. Defaults to 2.
+   */
+  maxConnectionRetries?: number;
+  /**
+   * Milliseconds to wait between connection attempts. Defaults to 500.
+   */
+  connectionRetryDelay?: number;
   sampleRate: number;
   encoding?: AudioEncoding;
   endOfTurnConfidenceThreshold?: number;
@@ -349,6 +365,10 @@ export type StreamingForceEndpoint = {
   type: "ForceEndpoint";
 };
 
+export type StreamingKeepAlive = {
+  type: "KeepAlive";
+};
+
 export type ErrorEvent = {
   type: "Error";
   error_code?: number;
@@ -405,4 +425,5 @@ export type StreamingEventMessage =
 export type StreamingOperationMessage =
   | StreamingUpdateConfiguration
   | StreamingForceEndpoint
+  | StreamingKeepAlive
   | StreamingTerminateSession;