assemblyai 4.34.6 → 4.35.3

package/dist/index.cjs

@@ -76,7 +76,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.3" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -1077,6 +1077,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`).
@@ -1208,8 +1226,12 @@ class StreamingTranscriber {
             searchParams.set("speech_model", this.params.speechModel.toString());
         }
         if (this.params.languageCode !== undefined) {
+            console.warn("[Deprecation Warning] `languageCode` is deprecated and will be removed in a future release. Please use `languageCodes` instead.");
             searchParams.set("language_code", this.params.languageCode);
         }
+        if (this.params.languageCodes !== undefined) {
+            searchParams.set("language_codes", JSON.stringify(this.params.languageCodes));
+        }
         if (this.params.languageDetection !== undefined) {
             searchParams.set("language_detection", this.params.languageDetection.toString());
         }
@@ -1283,12 +1305,85 @@ class StreamingTranscriber {
     on(event, listener) {
         this.listeners[event] = listener;
     }
+    /**
+     * 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() {
-        return new Promise((resolve) => {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             if (this.socket) {
                 throw new Error("Already connected");
             }
+            const maxRetries = (_a = this.params.maxConnectionRetries) !== null && _a !== void 0 ? _a : DEFAULT_MAX_CONNECTION_RETRIES;
+            const retryDelay = (_b = this.params.connectionRetryDelay) !== null && _b !== void 0 ? _b : DEFAULT_CONNECTION_RETRY_DELAY_MS;
+            let lastError;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    return yield 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) {
+                        yield 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 !== null && lastError !== void 0 ? lastError : new Error("Failed to connect to streaming server");
+        });
+    }
+    connectOnce() {
+        return new Promise((resolve, reject) => {
+            var _a;
             const url = this.connectionUrl();
+            const timeoutMs = (_a = this.params.connectTimeout) !== null && _a !== void 0 ? _a : 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());
             }
@@ -1306,6 +1401,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.
@@ -1316,11 +1420,15 @@ class StreamingTranscriber {
                 (_b = (_a = this.listeners).close) === null || _b === void 0 ? void 0 : _b.call(_a, code, reason);
             };
             this.socket.onerror = (event) => {
-                var _a, _b, _c, _d;
-                if (event.error)
-                    (_b = (_a = this.listeners).error) === null || _b === void 0 ? void 0 : _b.call(_a, event.error);
-                else
-                    (_d = (_c = this.listeners).error) === null || _d === void 0 ? void 0 : _d.call(_c, new Error(event.message));
+                var _a, _b, _c;
+                const error = (_a = event.error) !== null && _a !== void 0 ? _a : new Error(event.message);
+                // A socket error before `Begin` is a failed attempt → reject/retry.
+                if (!settled) {
+                    error.retryable = true;
+                    failAttempt(error);
+                    return;
+                }
+                (_c = (_b = this.listeners).error) === null || _c === void 0 ? void 0 : _c.call(_b, error);
             };
             this.socket.onmessage = ({ data }) => {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
@@ -1328,15 +1436,23 @@ class StreamingTranscriber {
                 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;
                     }
                     (_b = (_a = this.listeners).error) === null || _b === void 0 ? void 0 : _b.call(_a, err);
                     return;
                 }
                 switch (message.type) {
                     case "Begin": {
-                        resolve(message);
+                        succeed(message);
                         (_d = (_c = this.listeners).open) === null || _d === void 0 ? void 0 : _d.call(_c, message);
                         break;
                     }
@@ -1383,6 +1499,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 (_a) {
+            // 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
@@ -1656,6 +1786,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/index.mjs

@@ -74,7 +74,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.3" },
 };
 if (typeof process !== "undefined") {
     if (process.versions.node && defaultUserAgentString.indexOf("Node") === -1) {
@@ -1075,6 +1075,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`).
@@ -1206,8 +1224,12 @@ class StreamingTranscriber {
             searchParams.set("speech_model", this.params.speechModel.toString());
         }
         if (this.params.languageCode !== undefined) {
+            console.warn("[Deprecation Warning] `languageCode` is deprecated and will be removed in a future release. Please use `languageCodes` instead.");
             searchParams.set("language_code", this.params.languageCode);
         }
+        if (this.params.languageCodes !== undefined) {
+            searchParams.set("language_codes", JSON.stringify(this.params.languageCodes));
+        }
         if (this.params.languageDetection !== undefined) {
             searchParams.set("language_detection", this.params.languageDetection.toString());
         }
@@ -1281,12 +1303,85 @@ class StreamingTranscriber {
     on(event, listener) {
         this.listeners[event] = listener;
     }
+    /**
+     * 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() {
-        return new Promise((resolve) => {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             if (this.socket) {
                 throw new Error("Already connected");
             }
+            const maxRetries = (_a = this.params.maxConnectionRetries) !== null && _a !== void 0 ? _a : DEFAULT_MAX_CONNECTION_RETRIES;
+            const retryDelay = (_b = this.params.connectionRetryDelay) !== null && _b !== void 0 ? _b : DEFAULT_CONNECTION_RETRY_DELAY_MS;
+            let lastError;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    return yield 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) {
+                        yield 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 !== null && lastError !== void 0 ? lastError : new Error("Failed to connect to streaming server");
+        });
+    }
+    connectOnce() {
+        return new Promise((resolve, reject) => {
+            var _a;
             const url = this.connectionUrl();
+            const timeoutMs = (_a = this.params.connectTimeout) !== null && _a !== void 0 ? _a : 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());
             }
@@ -1304,6 +1399,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.
@@ -1314,11 +1418,15 @@ class StreamingTranscriber {
                 (_b = (_a = this.listeners).close) === null || _b === void 0 ? void 0 : _b.call(_a, code, reason);
             };
             this.socket.onerror = (event) => {
-                var _a, _b, _c, _d;
-                if (event.error)
-                    (_b = (_a = this.listeners).error) === null || _b === void 0 ? void 0 : _b.call(_a, event.error);
-                else
-                    (_d = (_c = this.listeners).error) === null || _d === void 0 ? void 0 : _d.call(_c, new Error(event.message));
+                var _a, _b, _c;
+                const error = (_a = event.error) !== null && _a !== void 0 ? _a : new Error(event.message);
+                // A socket error before `Begin` is a failed attempt → reject/retry.
+                if (!settled) {
+                    error.retryable = true;
+                    failAttempt(error);
+                    return;
+                }
+                (_c = (_b = this.listeners).error) === null || _c === void 0 ? void 0 : _c.call(_b, error);
             };
             this.socket.onmessage = ({ data }) => {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
@@ -1326,15 +1434,23 @@ class StreamingTranscriber {
                 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;
                     }
                     (_b = (_a = this.listeners).error) === null || _b === void 0 ? void 0 : _b.call(_a, err);
                     return;
                 }
                 switch (message.type) {
                     case "Begin": {
-                        resolve(message);
+                        succeed(message);
                         (_d = (_c = this.listeners).open) === null || _d === void 0 ? void 0 : _d.call(_c, message);
                         break;
                     }
@@ -1381,6 +1497,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 (_a) {
+            // 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
@@ -1654,6 +1784,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");