@deepgram/sdk 5.0.0 → 5.2.0

package/dist/esm/core/url/QueryStringBuilder.mjs

@@ -0,0 +1,80 @@
+import { toQueryString } from "./qs.mjs";
+/**
+ * Creates a fluent builder for constructing URL query strings.
+ *
+ * Each `.add()` call serializes its value immediately (like C#'s builder),
+ * so no format tracking is needed — the style is applied at add-time.
+ *
+ * Usage (generated code):
+ *
+ *     const qs = core.url.queryBuilder()
+ *         .add("limit", limit)
+ *         .add("tags", tags, { style: "comma" })   // explode: false
+ *         .mergeAdditional(requestOptions?.queryParams)
+ *         .build();
+ */
+export function queryBuilder() {
+    return new QueryStringBuilder();
+}
+class QueryStringBuilder {
+    constructor() {
+        this.parts = new Map();
+    }
+    /**
+     * Adds a query parameter, serializing it immediately.
+     *
+     * By default arrays use "repeat" format (`key=a&key=b`).
+     * Pass `{ style: "comma" }` for OpenAPI `explode: false` parameters
+     * to get comma-separated values (`key=a,b,c`).
+     *
+     * Null / undefined values are silently skipped.
+     */
+    add(key, value, options) {
+        if (value === undefined || value === null) {
+            return this;
+        }
+        const serialized = toQueryString({ [key]: value }, { arrayFormat: (options === null || options === void 0 ? void 0 : options.style) === "comma" ? "comma" : "repeat" });
+        if (serialized.length > 0) {
+            this.parts.set(key, serialized);
+        }
+        return this;
+    }
+    /**
+     * Adds multiple query parameters at once from a record.
+     * All parameters use the default "repeat" array format.
+     * Null / undefined values are silently skipped.
+     */
+    addMany(params) {
+        if (params != null) {
+            for (const [key, value] of Object.entries(params)) {
+                this.add(key, value);
+            }
+        }
+        return this;
+    }
+    /**
+     * Merges additional query parameters supplied at call-time via
+     * `requestOptions.queryParams`. Overrides existing keys (last-write-wins).
+     */
+    mergeAdditional(additionalParams) {
+        if (additionalParams != null) {
+            for (const [key, value] of Object.entries(additionalParams)) {
+                if (value === undefined || value === null) {
+                    continue;
+                }
+                const serialized = toQueryString({ [key]: value }, { arrayFormat: "repeat" });
+                if (serialized.length > 0) {
+                    this.parts.set(key, serialized);
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * Returns the assembled query string (without the leading `?`).
+     * Returns an empty string when no parameters were added.
+     */
+    build() {
+        return [...this.parts.values()].join("&");
+    }
+}

package/dist/esm/core/url/index.d.mts

@@ -1,3 +1,4 @@
 export { encodePathParam } from "./encodePathParam.mjs";
 export { join } from "./join.mjs";
+export { queryBuilder } from "./QueryStringBuilder.mjs";
 export { toQueryString } from "./qs.mjs";

package/dist/esm/core/url/index.mjs

@@ -1,3 +1,4 @@
 export { encodePathParam } from "./encodePathParam.mjs";
 export { join } from "./join.mjs";
+export { queryBuilder } from "./QueryStringBuilder.mjs";
 export { toQueryString } from "./qs.mjs";

package/dist/esm/core/url/qs.d.mts

@@ -1,5 +1,6 @@
+type ArrayFormat = "indices" | "repeat" | "comma";
 interface QueryStringOptions {
-    arrayFormat?: "indices" | "repeat";
+    arrayFormat?: ArrayFormat;
     encode?: boolean;
 }
 export declare function toQueryString(obj: unknown, options?: QueryStringOptions): string;

package/dist/esm/core/url/qs.mjs

@@ -23,19 +23,31 @@ function stringifyObject(obj, prefix = "", options) {
             if (value.length === 0) {
                 continue;
             }
-            for (let i = 0; i < value.length; i++) {
-                const item = value[i];
-                if (item === undefined) {
-                    continue;
+            const effectiveFormat = options.arrayFormat;
+            if (effectiveFormat === "comma") {
+                const encodedKey = options.encode ? encodeURIComponent(fullKey) : fullKey;
+                const encodedValues = value
+                    .filter((item) => item !== undefined && item !== null)
+                    .map((item) => encodeValue(item, options.encode));
+                if (encodedValues.length > 0) {
+                    parts.push(`${encodedKey}=${encodedValues.join(",")}`);
                 }
-                if (typeof item === "object" && !Array.isArray(item) && item !== null) {
-                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
-                    parts.push(...stringifyObject(item, arrayKey, options));
-                }
-                else {
-                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
-                    const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
-                    parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+            }
+            else {
+                for (let i = 0; i < value.length; i++) {
+                    const item = value[i];
+                    if (item === undefined) {
+                        continue;
+                    }
+                    if (typeof item === "object" && !Array.isArray(item) && item !== null) {
+                        const arrayKey = effectiveFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                        parts.push(...stringifyObject(item, arrayKey, options));
+                    }
+                    else {
+                        const arrayKey = effectiveFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                        const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
+                        parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+                    }
                 }
             }
         }

package/dist/esm/core/websocket/ws.d.mts

@@ -85,7 +85,7 @@ export declare class ReconnectingWebSocket {
     /**
      * The current state of the connection; this is one of the Ready state constants
      */
-    get readyState(): number;
+    get readyState(): ReconnectingWebSocket.ReadyState;
     /**
      * The URL as resolved by the constructor
      */
@@ -148,3 +148,12 @@ export declare class ReconnectingWebSocket {
     private _addListeners;
     private _clearTimeouts;
 }
+export declare namespace ReconnectingWebSocket {
+    const ReadyState: {
+        readonly CONNECTING: 0;
+        readonly OPEN: 1;
+        readonly CLOSING: 2;
+        readonly CLOSED: 3;
+    };
+    type ReadyState = (typeof ReadyState)[keyof typeof ReadyState];
+}

package/dist/esm/core/websocket/ws.mjs

@@ -3,13 +3,13 @@ import { RUNTIME } from "../runtime/index.mjs";
 import { toQueryString } from "../url/qs.mjs";
 import * as Events from "./events.mjs";
 const getGlobalWebSocket = () => {
-    if (typeof WebSocket !== "undefined") {
+    if (RUNTIME.type === "node" || RUNTIME.type === "bun" || RUNTIME.type === "deno") {
+        return NodeWebSocket;
+    }
+    else if (typeof WebSocket !== "undefined") {
         // @ts-ignore
         return WebSocket;
     }
-    else if (RUNTIME.type === "node") {
-        return NodeWebSocket;
-    }
     return undefined;
 };
 /**
@@ -72,6 +72,8 @@ export class ReconnectingWebSocket {
             this._clearTimeouts();
             if (this._ws) {
                 this._removeListeners();
+                // Absorb async errors emitted by ws when closing during CONNECTING state
+                this._ws.addEventListener("error", () => { });
                 try {
                     this._ws.close(1000, "aborted");
                     this._handleClose(new Events.CloseEvent(1000, "aborted", this));
@@ -198,7 +200,9 @@ export class ReconnectingWebSocket {
         if (this._ws) {
             return this._ws.readyState;
         }
-        return this._options.startClosed ? ReconnectingWebSocket.CLOSED : ReconnectingWebSocket.CONNECTING;
+        return this._options.startClosed
+            ? ReconnectingWebSocket.ReadyState.CLOSED
+            : ReconnectingWebSocket.ReadyState.CONNECTING;
     }
     /**
      * The URL as resolved by the constructor
@@ -382,6 +386,8 @@ export class ReconnectingWebSocket {
             return;
         }
         this._removeListeners();
+        // Absorb async errors emitted by ws when closing during CONNECTING state
+        this._ws.addEventListener("error", () => { });
         try {
             this._ws.close(code, reason);
             this._handleClose(new Events.CloseEvent(code, reason, this));
@@ -435,3 +441,11 @@ ReconnectingWebSocket.CONNECTING = 0;
 ReconnectingWebSocket.OPEN = 1;
 ReconnectingWebSocket.CLOSING = 2;
 ReconnectingWebSocket.CLOSED = 3;
+(function (ReconnectingWebSocket) {
+    ReconnectingWebSocket.ReadyState = {
+        CONNECTING: 0,
+        OPEN: 1,
+        CLOSING: 2,
+        CLOSED: 3,
+    };
+})(ReconnectingWebSocket || (ReconnectingWebSocket = {}));

package/dist/esm/errors/DeepgramError.d.mts

@@ -3,10 +3,12 @@ export declare class DeepgramError extends Error {
     readonly statusCode?: number;
     readonly body?: unknown;
     readonly rawResponse?: core.RawResponse;
-    constructor({ message, statusCode, body, rawResponse, }: {
+    readonly cause?: unknown;
+    constructor({ message, statusCode, body, rawResponse, cause, }: {
         message?: string;
         statusCode?: number;
         body?: unknown;
         rawResponse?: core.RawResponse;
+        cause?: unknown;
     });
 }

package/dist/esm/errors/DeepgramError.mjs

@@ -1,7 +1,7 @@
 // This file was auto-generated by Fern from our API Definition.
 import { toJson } from "../core/json.mjs";
 export class DeepgramError extends Error {
-    constructor({ message, statusCode, body, rawResponse, }) {
+    constructor({ message, statusCode, body, rawResponse, cause, }) {
         super(buildMessage({ message, statusCode, body }));
         Object.setPrototypeOf(this, new.target.prototype);
         if (Error.captureStackTrace) {
@@ -11,6 +11,9 @@ export class DeepgramError extends Error {
         this.statusCode = statusCode;
         this.body = body;
         this.rawResponse = rawResponse;
+        if (cause != null) {
+            this.cause = cause;
+        }
     }
 }
 function buildMessage({ message, statusCode, body, }) {

package/dist/esm/errors/DeepgramTimeoutError.d.mts

@@ -1,3 +1,6 @@
 export declare class DeepgramTimeoutError extends Error {
-    constructor(message: string);
+    readonly cause?: unknown;
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
 }

package/dist/esm/errors/DeepgramTimeoutError.mjs

@@ -1,11 +1,14 @@
 // This file was auto-generated by Fern from our API Definition.
 export class DeepgramTimeoutError extends Error {
-    constructor(message) {
+    constructor(message, opts) {
         super(message);
         Object.setPrototypeOf(this, new.target.prototype);
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, this.constructor);
         }
         this.name = this.constructor.name;
+        if ((opts === null || opts === void 0 ? void 0 : opts.cause) != null) {
+            this.cause = opts.cause;
+        }
     }
 }

package/dist/esm/errors/handleNonStatusCodeError.mjs

@@ -14,11 +14,14 @@ export function handleNonStatusCodeError(error, rawResponse, method, path) {
                 rawResponse: rawResponse,
             });
         case "timeout":
-            throw new errors.DeepgramTimeoutError(`Timeout exceeded when calling ${method} ${path}.`);
+            throw new errors.DeepgramTimeoutError(`Timeout exceeded when calling ${method} ${path}.`, {
+                cause: error.cause,
+            });
         case "unknown":
             throw new errors.DeepgramError({
                 message: error.errorMessage,
                 rawResponse: rawResponse,
+                cause: error.cause,
             });
         default:
             throw new errors.DeepgramError({

package/dist/esm/transport.d.mts

@@ -0,0 +1,73 @@
+/**
+ * Message payloads exchanged over Deepgram streaming transports.
+ *
+ * A transport can carry JSON control messages as strings and audio or synthesized
+ * audio as binary payloads.
+ */
+export type DeepgramTransportMessage = string | ArrayBuffer | Blob | ArrayBufferView;
+/** Close metadata reported by a custom transport. */
+export interface DeepgramTransportCloseEvent {
+    code?: number;
+    reason?: string;
+}
+/**
+ * Metadata passed to a transport factory when a streaming connection is created.
+ *
+ * The first two factory arguments intentionally match the Python and Java SDKs:
+ * `factory(url, headers)`. JavaScript also passes this third metadata object so
+ * custom transports can inspect the target streaming API and connection settings.
+ */
+export interface DeepgramTransportRequest {
+    /** Full Deepgram websocket URL including query parameters. */
+    url: string;
+    /** Resolved request headers including auth and session headers. */
+    headers: Record<string, string>;
+    /** Requested websocket subprotocols, if any. */
+    protocols: string[];
+    /** Deepgram websocket path (for example `/v1/listen`). */
+    path: string;
+    /** Streaming API being targeted. */
+    service: "agent.v1" | "listen.v1" | "listen.v2" | "speak.v1";
+    /** Query parameters before they are encoded into the URL. */
+    queryParams: Record<string, unknown>;
+    /** Whether debug logging was requested for the connection. */
+    debug: boolean;
+    /** Requested reconnect attempts for this connection. */
+    reconnectAttempts: number;
+    /** Optional connection timeout in seconds. */
+    connectionTimeoutInSeconds?: number;
+    /** Optional abort signal for the connection attempt. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Transport interface for replacing the SDK's default websocket transport.
+ *
+ * This is the seam used by SageMaker support and other non-websocket streaming
+ * implementations. The SDK adapts this transport to its existing socket APIs, so
+ * callers still use `client.listen.v1.createConnection()` and related methods.
+ */
+export interface DeepgramTransport {
+    /** Send either a JSON string or binary payload to the transport. */
+    send(data: DeepgramTransportMessage): void | Promise<void>;
+    /** Register a listener fired once the transport is ready to exchange messages. */
+    onOpen(listener: () => void): void;
+    /** Register a listener for inbound text or binary messages. */
+    onMessage(listener: (message: DeepgramTransportMessage) => void): void;
+    /** Register a listener for transport-level errors. */
+    onError(listener: (error: Error) => void): void;
+    /** Register a listener for transport close events. */
+    onClose(listener: (event: DeepgramTransportCloseEvent) => void): void;
+    /** Returns true while the transport is open and able to send data. */
+    isOpen(): boolean;
+    /** Close the transport gracefully. */
+    close(code?: number, reason?: string): void | Promise<void>;
+    /** Optional ping hook for transports that expose an explicit keepalive primitive. */
+    ping?(data?: string | ArrayBuffer | Blob | ArrayBufferView): void | Promise<void>;
+}
+/**
+ * Factory for creating custom streaming transports.
+ *
+ * The first two arguments mirror the Python and Java SDKs. JavaScript also passes
+ * a third metadata argument for transports that need more connection context.
+ */
+export type DeepgramTransportFactory = (url: string, headers: Record<string, string>, request: DeepgramTransportRequest) => DeepgramTransport | Promise<DeepgramTransport>;

package/dist/esm/transport.mjs

@@ -0,0 +1 @@
+export {};

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "4.11.4";
+export declare const SDK_VERSION = "5.1.1";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "4.11.4";
+export const SDK_VERSION = "5.1.1";