assemblyai 4.34.5 → 4.35.0

package/dist/node.cjs

@@ -35,7 +35,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.34.5" },
+    sdk: { name: "JavaScript", version: "4.35.0" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -980,6 +980,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`).
@@ -1188,12 +1206,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());
             }
@@ -1210,6 +1297,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.
@@ -1220,25 +1316,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;
                     }
@@ -1285,6 +1393,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
@@ -1558,6 +1680,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/dist/node.mjs

@@ -33,7 +33,7 @@ if (typeof navigator !== "undefined" && navigator.userAgent) {
     defaultUserAgentString += navigator.userAgent;
 }
 const defaultUserAgent = {
-    sdk: { name: "JavaScript", version: "4.34.5" },
+    sdk: { name: "JavaScript", version: "4.35.0" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -978,6 +978,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`).
@@ -1186,12 +1204,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());
             }
@@ -1208,6 +1295,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.
@@ -1218,25 +1314,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;
                     }
@@ -1283,6 +1391,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
@@ -1556,6 +1678,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/dist/services/streaming/service.d.ts

@@ -39,7 +39,24 @@ export declare class StreamingTranscriber {
     on(event: "vad", listener: (event: VadFrame) => void): void;
     on(event: "error", listener: (error: Error) => void): void;
     on(event: "close", listener: (code: number, reason: string) => void): void;
+    /**
+     * 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.
+     */
     connect(): Promise<BeginEvent>;
+    private connectOnce;
+    /** Tear down a half-open socket from a failed connection attempt. */
+    private discardPendingSocket;
     /**
      * Returns a WritableStream that pumps PCM chunks into `sendAudio`. Single-channel
      * only — in dual-channel mode use `sendAudio(pcm, { channel })` directly, since
@@ -95,6 +112,11 @@ export declare class StreamingTranscriber {
      * Force the current turn to end immediately.
      */
     forceEndpoint(): void;
+    /**
+     * Reset the server's inactivity timer. Only needed when the session was
+     * created with `inactivityTimeout` and no audio is being sent.
+     */
+    keepAlive(): void;
     private send;
     close(waitForSessionTermination?: boolean): Promise<void>;
 }