CustomClient.ts

import { DeepgramClient } from "./Client.js";
import { ReconnectingWebSocket } from "./core/websocket/ws.js";
import type { AgentClient } from "./api/resources/agent/client/Client.js";
import type { ListenClient } from "./api/resources/listen/client/Client.js";
import type { SpeakClient } from "./api/resources/speak/client/Client.js";
import { AgentClient as AgentClientImpl } from "./api/resources/agent/client/Client.js";
import { ListenClient as ListenClientImpl } from "./api/resources/listen/client/Client.js";
import { SpeakClient as SpeakClientImpl } from "./api/resources/speak/client/Client.js";
import { V1Client as AgentV1Client } from "./api/resources/agent/resources/v1/client/Client.js";
import { V1Client as ListenV1Client } from "./api/resources/listen/resources/v1/client/Client.js";
import { V2Client as ListenV2Client } from "./api/resources/listen/resources/v2/client/Client.js";
import { V1Client as SpeakV1Client } from "./api/resources/speak/resources/v1/client/Client.js";
import { V1Socket as AgentV1Socket } from "./api/resources/agent/resources/v1/client/Socket.js";
import { V1Socket as ListenV1Socket } from "./api/resources/listen/resources/v1/client/Socket.js";
import { V2Socket as ListenV2Socket } from "./api/resources/listen/resources/v2/client/Socket.js";
import { V1Socket as SpeakV1Socket } from "./api/resources/speak/resources/v1/client/Socket.js";
import { mergeHeaders } from "./core/headers.js";
import { fromJson } from "./core/json.js";
import { BadRequestError } from "./api/errors/index.js";
import * as core from "./core/index.js";
import * as websocketEvents from "./core/websocket/events.js";
import * as environments from "./environments.js";
import { RUNTIME } from "./core/runtime/index.js";
import type {
    DeepgramTransport,
    DeepgramTransportFactory,
    DeepgramTransportMessage,
    DeepgramTransportRequest,
} from "./transport.js";

// Default WebSocket connection timeout in milliseconds
const DEFAULT_CONNECTION_TIMEOUT_MS = 10000;

// Keys present in every ConnectArgs interface that control the WebSocket connection itself.
// Every other key in ConnectArgs is treated as an API query parameter.
const WEBSOCKET_OPTION_KEYS = new Set([
    "Authorization",
    "headers",
    "protocols",
    "debug",
    "reconnectAttempts",
    "connectionTimeoutInSeconds",
    "abortSignal",
    "queryParams",
]);

// ws for Node.js - loaded lazily to support CJS, ESM, and browser builds.
// A static import of "module" (for createRequire) would break the browser bundle,
// so we detect the environment at runtime and use an opaque dynamic import in ESM
// Node so bundlers cannot statically analyse and reject it.
let NodeWebSocket: any;
let _wsInitialized = false;

async function loadNodeWebSocket(): Promise<void> {
    if (_wsInitialized) return;
    _wsInitialized = true;
    try {
        if (typeof require !== "undefined") {
            // CJS: require is injected as a module-scoped binding
            // eslint-disable-next-line @typescript-eslint/no-require-imports
            let ws = require("ws");
            NodeWebSocket = ws.WebSocket || ws.default || ws;
        } else if (typeof process !== "undefined" && process.versions?.node) {
            // ESM Node: require is not defined. Wrap import() in new Function so
            // bundlers (esbuild, webpack) cannot statically resolve or reject "ws".
            // eslint-disable-next-line no-new-func
            const dynamicImport = new Function("specifier", "return import(specifier)");
            const ws = await dynamicImport("ws");
            NodeWebSocket = ws.WebSocket || ws.default || ws;
        }
        // Browser: process.versions?.node is undefined → NodeWebSocket stays undefined
    } catch {
        // ws not available or failed to load
        NodeWebSocket = undefined;
    }
}

// Helper function to generate UUID that works in both Node.js and browser
function generateUUID(): string {
    // Try global crypto.randomUUID first (works in both Node.js 14.18+ and modern browsers)
    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
        return crypto.randomUUID();
    }
    
    // Fallback for Node.js: use the crypto module
    if (RUNTIME.type === "node") {
        try {
            // eslint-disable-next-line @typescript-eslint/no-require-imports
            const nodeCrypto = require("crypto");
            return nodeCrypto.randomUUID();
        } catch {
            // Fallback if crypto module is not available
        }
    }
    
    // Final fallback: manual UUID generation (RFC4122 version 4)
    // This should work everywhere but is less secure than crypto.randomUUID()
    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
        const r = (Math.random() * 16) | 0;
        const v = c === "x" ? r : (r & 0x3) | 0x8;
        return v.toString(16);
    });
}

/**
 * Wrapper auth provider that adds "Token " prefix to API keys.
 * The auto-generated HeaderAuthProvider doesn't add the prefix, so we wrap it here.
 */
class ApiKeyAuthProviderWrapper implements core.AuthProvider {
    private readonly originalProvider: core.AuthProvider;

    constructor(originalProvider: core.AuthProvider) {
        this.originalProvider = originalProvider;
    }

    public async getAuthRequest(arg?: { endpointMetadata?: core.EndpointMetadata }): Promise<core.AuthRequest> {
        const authRequest = await this.originalProvider.getAuthRequest(arg);
        const authHeader = authRequest.headers?.Authorization || authRequest.headers?.authorization;
        
        // If the header doesn't already have a scheme prefix, add "Token " prefix for API keys
        if (authHeader && typeof authHeader === "string") {
            // Only add prefix if it doesn't already have Bearer or Token prefix
            if (!authHeader.startsWith("Bearer ") && !authHeader.startsWith("Token ") && !authHeader.startsWith("token ")) {
                return {
                    headers: {
                        ...authRequest.headers,
                        Authorization: `Token ${authHeader}`,
                    },
                };
            }
        }
        
        return authRequest;
    }
}

/**
 * Wrapper auth provider that checks for accessToken first (Bearer scheme)
 * before falling back to the original auth provider (Token scheme for API keys).
 */
class AccessTokenAuthProviderWrapper implements core.AuthProvider {
    private readonly originalProvider: core.AuthProvider;
    private readonly accessToken?: core.Supplier<string | undefined>;

    constructor(originalProvider: core.AuthProvider, accessToken?: core.Supplier<string | undefined>) {
        this.originalProvider = originalProvider;
        this.accessToken = accessToken;
    }

    public async getAuthRequest(arg?: { endpointMetadata?: core.EndpointMetadata }): Promise<core.AuthRequest> {
        // Check for access token first (highest priority)
        // Access tokens use Bearer scheme, API keys use Token scheme
        const accessToken = (await core.Supplier.get(this.accessToken)) ?? process.env?.DEEPGRAM_ACCESS_TOKEN;
        if (accessToken != null) {
            return {
                headers: { Authorization: `Bearer ${accessToken}` },
            };
        }

        // Fall back to original provider (which handles API keys)
        return this.originalProvider.getAuthRequest(arg);
    }
}

export type AgentV1ConnectionArgs = Omit<AgentV1Client.ConnectArgs, "Authorization"> & { Authorization?: string };
export type ListenV1ConnectionArgs = Omit<ListenV1Client.ConnectArgs, "Authorization"> & { Authorization?: string };
export type ListenV2ConnectionArgs = Omit<ListenV2Client.ConnectArgs, "Authorization" | "keyterm"> & {
    Authorization?: string;
    keyterm?: string | string[];
};
export type SpeakV1ConnectionArgs = Omit<SpeakV1Client.ConnectArgs, "Authorization"> & { Authorization?: string };

export interface AgentV1ClientWithWebSocket extends AgentV1Client {
    connect(args?: AgentV1ConnectionArgs): Promise<AgentV1Socket>;
    createConnection(args?: AgentV1ConnectionArgs): Promise<AgentV1Socket>;
}

export interface ListenV1ClientWithWebSocket extends ListenV1Client {
    connect(args: ListenV1ConnectionArgs): Promise<ListenV1Socket>;
    createConnection(args: ListenV1ConnectionArgs): Promise<ListenV1Socket>;
}

export interface ListenV2ClientWithWebSocket extends ListenV2Client {
    connect(args: ListenV2ConnectionArgs): Promise<ListenV2Socket>;
    createConnection(args: ListenV2ConnectionArgs): Promise<ListenV2Socket>;
}

export interface SpeakV1ClientWithWebSocket extends SpeakV1Client {
    connect(args: SpeakV1ConnectionArgs): Promise<SpeakV1Socket>;
    createConnection(args: SpeakV1ConnectionArgs): Promise<SpeakV1Socket>;
}

export interface AgentClientWithWebSockets extends AgentClient {
    readonly v1: AgentV1ClientWithWebSocket;
}

export interface ListenClientWithWebSockets extends ListenClient {
    readonly v1: ListenV1ClientWithWebSocket;
    readonly v2: ListenV2ClientWithWebSocket;
}

export interface SpeakClientWithWebSockets extends SpeakClient {
    readonly v1: SpeakV1ClientWithWebSocket;
}

/**
 * Custom wrapper around DeepgramClient that ensures the custom websocket implementation
 * from ws.ts is always used, even if the auto-generated code changes.
 */
export interface CustomDeepgramClientOptions extends DeepgramClient.Options {
    accessToken?: core.Supplier<string | undefined>;
    transportFactory?: DeepgramTransportFactory;
    /**
     * Whether the SDK should retry streaming connections at the wrapper level
     * after a transport failure. Defaults to `true` for native websocket
     * connections. When a `transportFactory` is provided, this is auto-set to
     * `false` because custom transports own their own retry/reconnect lifecycle
     * — wrapping a self-retrying transport in another retry layer creates
     * double-retry storms under burst load. Pass `reconnect: true` together
     * with `transportFactory` to opt back into wrapper-level retries.
     */
    reconnect?: boolean;
}

export class CustomDeepgramClient extends DeepgramClient {
    private _customAgent: AgentClientWithWebSockets | undefined;
    private _customListen: ListenClientWithWebSockets | undefined;
    private _customSpeak: SpeakClientWithWebSockets | undefined;
    private readonly _sessionId: string;
    private readonly _reconnect: boolean;

    constructor(options: CustomDeepgramClientOptions = {}) {
        // Generate a UUID for the session ID
        const sessionId = generateUUID();

        // Add the session ID to headers so it's included in all REST requests
        // Auto-disable wrapper-level reconnect when a custom transportFactory
        // is in use: those transports own their retry lifecycle, and stacking
        // a second retry layer on top causes storm-on-storm under burst load.
        // Callers can still opt back in by explicitly passing reconnect: true.
        const reconnect = options.reconnect ?? (options.transportFactory == null);
        const optionsWithSessionId: CustomDeepgramClientOptions = {
            ...options,
            reconnect,
            headers: {
                ...options.headers,
                "x-deepgram-session-id": sessionId,
            },
        };

        super(optionsWithSessionId);
        this._sessionId = sessionId;
        this._reconnect = reconnect;

        // Always wrap the auth provider to add "Token " prefix to API keys
        // The auto-generated HeaderAuthProvider doesn't add the prefix
        (this._options as any).authProvider = new ApiKeyAuthProviderWrapper(this._options.authProvider);

        // Wrap again to handle accessToken if provided
        // This ensures accessToken takes priority over apiKey/env var
        if (options.accessToken != null) {
            (this._options as any).authProvider = new AccessTokenAuthProviderWrapper(
                this._options.authProvider,
                options.accessToken
            );
        }
    }

    /**
     * Get the session ID that was generated for this client instance.
     */
    public get sessionId(): string {
        return this._sessionId;
    }

    /**
     * Whether the SDK will retry streaming connections at the wrapper level
     * after a transport-side failure. Returns `false` when a `transportFactory`
     * was supplied without an explicit `reconnect: true` override, signalling
     * that the custom transport is expected to manage its own reconnect
     * lifecycle.
     */
    public get reconnect(): boolean {
        return this._reconnect;
    }

    /**
     * Override the agent getter to return a wrapped client that ensures
     * the custom websocket implementation is used.
     */
    public get agent(): AgentClientWithWebSockets {
        if (!this._customAgent) {
            // Create a wrapper that ensures custom websocket is used
            this._customAgent = new WrappedAgentClient(this._options);
        }
        return this._customAgent;
    }

    /**
     * Override the listen getter to return a wrapped client that ensures
     * the custom websocket implementation is used.
     */
    public get listen(): ListenClientWithWebSockets {
        if (!this._customListen) {
            // Create a wrapper that ensures custom websocket is used
            this._customListen = new WrappedListenClient(this._options);
        }
        return this._customListen;
    }

    /**
     * Override the speak getter to return a wrapped client that ensures
     * the custom websocket implementation is used.
     */
    public get speak(): SpeakClientWithWebSockets {
        if (!this._customSpeak) {
            // Create a wrapper that ensures custom websocket is used
            this._customSpeak = new WrappedSpeakClient(this._options);
        }
        return this._customSpeak;
    }
}

/**
 * Wrapper for AgentClient that ensures custom websocket implementation is used.
 *
 * This wrapper exists to guarantee that our custom WebSocket implementation
 * (from ws.ts) continues to be used even after the SDK code is auto-generated
 * by Fern. Without this wrapper, Fern regeneration could overwrite the client
 * with a different WebSocket implementation.
 */
class WrappedAgentClient extends AgentClientImpl {
    public get v1() {
        return new WrappedAgentV1Client(this._options);
    }
}

/**
 * Wrapper for ListenClient that ensures custom websocket implementation is used.
 *
 * This wrapper exists to guarantee that our custom WebSocket implementation
 * (from ws.ts) continues to be used even after the SDK code is auto-generated
 * by Fern. Without this wrapper, Fern regeneration could overwrite the client
 * with a different WebSocket implementation.
 */
class WrappedListenClient extends ListenClientImpl {
    public get v1() {
        return new WrappedListenV1Client(this._options);
    }

    public get v2() {
        return new WrappedListenV2Client(this._options);
    }
}

/**
 * Wrapper for SpeakClient that ensures custom websocket implementation is used.
 *
 * This wrapper exists to guarantee that our custom WebSocket implementation
 * (from ws.ts) continues to be used even after the SDK code is auto-generated
 * by Fern. Without this wrapper, Fern regeneration could overwrite the client
 * with a different WebSocket implementation.
 */
class WrappedSpeakClient extends SpeakClientImpl {
    public get v1() {
        return new WrappedSpeakV1Client(this._options);
    }
}

/**
 * Helper function to resolve Suppliers in headers to their actual values.
 */
async function resolveHeaders(headers: Record<string, unknown>): Promise<Record<string, unknown>> {
    const resolved: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(headers)) {
        if (value == null) {
            continue;
        }
        // Resolve Supplier if it's a Supplier, otherwise use the value directly
        const resolvedValue = await core.Supplier.get(value as any);
        if (resolvedValue != null) {
            resolved[key] = resolvedValue;
        }
    }
    return resolved;
}

/**
 * Builds API query parameters from a ConnectArgs object, excluding all WebSocket
 * infrastructure keys. This means any new typed parameter added to ConnectArgs by
 * the generator is automatically included without needing manual updates here.
 * An explicit `queryParams` override is merged in last.
 */
function buildQueryParams(args: Record<string, unknown>): Record<string, unknown> {
    const result: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(args)) {
        if (!WEBSOCKET_OPTION_KEYS.has(key) && value != null) {
            result[key] = value;
        }
    }
    if (args.queryParams != null && typeof args.queryParams === "object") {
        Object.assign(result, args.queryParams);
    }
    return result;
}

/**
 * Nova-3 dropped the legacy `keywords` parameter in favor of `keyterm`, and the API rejects the
 * combination with a 400. REST surfaces that error, but the streaming endpoint just closes the
 * socket cleanly (code 1000, no reason, no error event) — so it fails silently and the socket
 * never opens. Detecting the combination up front lets the client throw the same error REST
 * already does, in both Node and the browser.
 *
 * Exported for unit testing; not part of the public API.
 */
export function isUnsupportedNova3Keywords(model: unknown, keywords: unknown): boolean {
    if (typeof model !== "string" || !model.startsWith("nova-3")) {
        return false;
    }
    if (keywords == null) {
        return false;
    }
    if (typeof keywords === "string" && keywords.length === 0) {
        return false;
    }
    if (Array.isArray(keywords) && keywords.length === 0) {
        return false;
    }
    return true;
}

function normalizeProtocols(protocols?: string | string[]): string[] {
    if (protocols == null) {
        return [];
    }

    return Array.isArray(protocols) ? protocols : [protocols];
}

function stringifyHeaders(headers: Record<string, unknown>): Record<string, string> {
    const result: Record<string, string> = {};

    for (const [key, value] of Object.entries(headers)) {
        result[key] = String(value);
    }

    return result;
}

function buildWebSocketUrl(url: string, queryParams: Record<string, unknown>): string {
    const queryString = core.url.toQueryString(queryParams, { arrayFormat: "repeat" });
    return queryString ? `${url}?${queryString}` : url;
}

function getTransportFactory(options: DeepgramClient.Options): DeepgramTransportFactory | undefined {
    return (options as CustomDeepgramClientOptions).transportFactory;
}

function getReconnect(options: DeepgramClient.Options): boolean {
    return (options as CustomDeepgramClientOptions).reconnect !== false;
}

class TransportWebSocketAdapter {
    private _listeners: ReconnectingWebSocket.ListenersMap = {
        error: [],
        message: [],
        open: [],
        close: [],
    };
    private _retryCount = -1;
    private _shouldReconnect = true;
    private _connectLock = false;
    private _binaryType: BinaryType = "blob";
    private _closeCalled = false;
    private _messageQueue: DeepgramTransportMessage[] = [];
    private _connectTimeout: ReturnType<typeof setTimeout> | undefined;
    private _transport: DeepgramTransport | undefined;
    private _readyState: ReconnectingWebSocket.ReadyState;
    private _ws:
        | {
              OPEN: typeof ReconnectingWebSocket.OPEN;
              readyState: ReconnectingWebSocket.ReadyState;
              ping?: (data?: string | ArrayBuffer | Blob | ArrayBufferView) => void;
          }
        | undefined;

    private readonly _factory: DeepgramTransportFactory;
    private readonly _request: DeepgramTransportRequest;
    // Whether the wrapper should retry after a transport-side failure. False
    // signals that the underlying transport owns reconnect — the wrapper
    // attempts the connect once and surfaces any error without re-attempting.
    private readonly _reconnect: boolean;

    constructor(args: {
        factory: DeepgramTransportFactory;
        request: DeepgramTransportRequest;
        startClosed?: boolean;
        reconnect?: boolean;
    }) {
        this._factory = args.factory;
        this._request = args.request;
        this._reconnect = args.reconnect !== false;
        this._readyState = args.startClosed ? ReconnectingWebSocket.ReadyState.CLOSED : ReconnectingWebSocket.ReadyState.CONNECTING;

        if (this._request.abortSignal) {
            this._request.abortSignal.addEventListener("abort", this._handleAbort, { once: true });
        }

        if (!args.startClosed) {
            void this._connect();
        }
    }

    public static readonly CONNECTING = ReconnectingWebSocket.CONNECTING;
    public static readonly OPEN = ReconnectingWebSocket.OPEN;
    public static readonly CLOSING = ReconnectingWebSocket.CLOSING;
    public static readonly CLOSED = ReconnectingWebSocket.CLOSED;

    public readonly CONNECTING: typeof ReconnectingWebSocket.CONNECTING = ReconnectingWebSocket.CONNECTING;
    public readonly OPEN: typeof ReconnectingWebSocket.OPEN = ReconnectingWebSocket.OPEN;
    public readonly CLOSING: typeof ReconnectingWebSocket.CLOSING = ReconnectingWebSocket.CLOSING;
    public readonly CLOSED: typeof ReconnectingWebSocket.CLOSED = ReconnectingWebSocket.CLOSED;

    public onclose: ((event: websocketEvents.CloseEvent) => void) | null = null;
    public onerror: ((event: websocketEvents.ErrorEvent) => void) | null = null;
    public onmessage: ((event: MessageEvent) => void) | null = null;
    public onopen: ((event: websocketEvents.Event) => void) | null = null;

    get binaryType(): BinaryType {
        return this._binaryType;
    }

    set binaryType(value: BinaryType) {
        this._binaryType = value;
    }

    get retryCount(): number {
        return Math.max(this._retryCount, 0);
    }

    get bufferedAmount(): number {
        return this._messageQueue.reduce((acc, message) => {
            if (typeof message === "string") {
                return acc + message.length;
            }
            if (message instanceof Blob) {
                return acc + message.size;
            }
            return acc + message.byteLength;
        }, 0);
    }

    get extensions(): string {
        return "";
    }

    get protocol(): string {
        return this._request.protocols[0] ?? "";
    }

    get readyState(): ReconnectingWebSocket.ReadyState {
        return this._readyState;
    }

    get url(): string {
        return this._request.url;
    }

    public close(code = 1000, reason?: string): void {
        this._closeCalled = true;
        this._shouldReconnect = false;
        this._clearConnectTimeout();
        this._readyState = ReconnectingWebSocket.ReadyState.CLOSING;

        const transport = this._transport;
        this._transport = undefined;
        this._setTransportHandle(undefined);

        if (!transport) {
            this._readyState = ReconnectingWebSocket.ReadyState.CLOSED;
            return;
        }

        void transport.close(code, reason);
        this._readyState = ReconnectingWebSocket.ReadyState.CLOSED;
    }

    public reconnect(code?: number, reason?: string): void {
        this._shouldReconnect = true;
        this._closeCalled = false;
        this._retryCount = -1;
        this._readyState = ReconnectingWebSocket.ReadyState.CONNECTING;

        const transport = this._transport;
        this._transport = undefined;
        this._setTransportHandle(undefined);

        if (transport) {
            void transport.close(code, reason);
        }

        void this._connect();
    }

    public send(data: DeepgramTransportMessage): void {
        if (this._transport?.isOpen()) {
            void this._transport.send(data);
            return;
        }

        this._messageQueue.push(data);
    }

    public addEventListener<T extends keyof websocketEvents.WebSocketEventListenerMap>(
        type: T,
        listener: websocketEvents.WebSocketEventListenerMap[T],
    ): void {
        if (this._listeners[type]) {
            (this._listeners[type] as Array<websocketEvents.WebSocketEventListenerMap[T]>).push(listener);
        }
    }

    public dispatchEvent(event: websocketEvents.Event): boolean {
        const listeners = this._listeners[event.type as keyof websocketEvents.WebSocketEventListenerMap];

        if (listeners) {
            for (const listener of listeners) {
                this._callEventListener(event as never, listener as never);
            }
        }

        return true;
    }

    public removeEventListener<T extends keyof websocketEvents.WebSocketEventListenerMap>(
        type: T,
        listener: websocketEvents.WebSocketEventListenerMap[T],
    ): void {
        if (this._listeners[type]) {
            this._listeners[type] = this._listeners[type].filter((registered) => registered !== listener) as never;
        }
    }

    private _debug(...args: unknown[]): void {
        if (this._request.debug) {
            // biome-ignore lint/suspicious/noConsole: transport debug logging mirrors websocket debug logging
            console.log.apply(console, ["DG-TRANSPORT>", ...args]);
        }
    }

    private _handleAbort = () => {
        if (this._closeCalled) {
            return;
        }

        this._debug("abort signal fired");
        this._closeCalled = true;
        this._shouldReconnect = false;
        this._clearConnectTimeout();

        const transport = this._transport;
        this._transport = undefined;
        this._setTransportHandle(undefined);

        if (transport) {
            void transport.close(1000, "aborted");
        }

        this._readyState = ReconnectingWebSocket.ReadyState.CLOSED;
        this._emitClose(1000, "aborted");
    };

    private async _connect(): Promise<void> {
        if (this._connectLock || !this._shouldReconnect || this._request.abortSignal?.aborted) {
            return;
        }

        // When wrapper-level reconnect is disabled, allow only the initial
        // attempt (_retryCount starts at -1 and increments to 0 on first
        // _connect). Any subsequent re-entry from _handleError must short out
        // so the transport's own retry logic is the single source of truth.
        if (!this._reconnect && this._retryCount >= 0) {
            this._debug("reconnect disabled, skipping retry");
            return;
        }

        if (this._retryCount >= this._request.reconnectAttempts) {
            this._debug("max retries reached", this._retryCount, ">=", this._request.reconnectAttempts);
            return;
        }

        this._connectLock = true;
        this._retryCount++;
        this._readyState = ReconnectingWebSocket.ReadyState.CONNECTING;
        this._clearConnectTimeout();

        try {
            const transport = await this._factory(this._request.url, this._request.headers, this._request);

            if (this._closeCalled || this._request.abortSignal?.aborted) {
                this._connectLock = false;
                await transport.close(1000, "aborted");
                return;
            }

            this._transport = transport;
            this._setTransportHandle(transport);
            this._bindTransport(transport);
            this._armConnectTimeout();
            this._connectLock = false;

            if (transport.isOpen()) {
                this._handleOpen(transport);
            }
        } catch (error) {
            this._connectLock = false;
            this._handleError(error instanceof Error ? error : new Error(String(error)));
        }
    }

    private _bindTransport(transport: DeepgramTransport): void {
        transport.onOpen(() => {
            if (this._transport !== transport) {
                return;
            }

            this._handleOpen(transport);
        });

        transport.onMessage((message) => {
            if (this._transport !== transport) {
                return;
            }

            this._handleMessage(message);
        });

        transport.onError((error) => {
            if (this._transport !== transport) {
                return;
            }

            this._handleError(error);
        });

        transport.onClose((event) => {
            if (this._transport !== transport) {
                return;
            }

            this._handleClose(event.code ?? 1000, event.reason ?? "");
        });
    }

    private _armConnectTimeout(): void {
        const timeoutMs =
            this._request.connectionTimeoutInSeconds != null
                ? this._request.connectionTimeoutInSeconds * 1000
                : DEFAULT_CONNECTION_TIMEOUT_MS;

        this._connectTimeout = setTimeout(() => {
            this._handleError(new Error("TIMEOUT"));
        }, timeoutMs);
    }

    private _clearConnectTimeout(): void {
        if (this._connectTimeout != null) {
            clearTimeout(this._connectTimeout);
            this._connectTimeout = undefined;
        }
    }

    private _handleOpen(transport: DeepgramTransport): void {
        if (this._transport !== transport || this._readyState === ReconnectingWebSocket.ReadyState.OPEN) {
            return;
        }

        this._debug("open event");
        this._clearConnectTimeout();
        this._readyState = ReconnectingWebSocket.ReadyState.OPEN;

        const queued = [...this._messageQueue];
        this._messageQueue = [];
        for (const message of queued) {
            void transport.send(message);
        }

        const event = new websocketEvents.Event("open", this);
        if (this.onopen) {
            this.onopen(event);
        }
        this._listeners.open.forEach((listener) => this._callEventListener(event, listener));
    }

    private _handleMessage(message: DeepgramTransportMessage): void {
        const event = { type: "message", data: message, target: this } as unknown as MessageEvent;

        if (this.onmessage) {
            this.onmessage(event);
        }
        this._listeners.message.forEach((listener) => this._callEventListener(event, listener));
    }

    private _handleError(error: Error): void {
        this._debug("error event", error.message);
        this._clearConnectTimeout();
        this._readyState = ReconnectingWebSocket.ReadyState.CLOSED;

        const event = new websocketEvents.ErrorEvent(error, this);
        if (this.onerror) {
            this.onerror(event);
        }
        this._listeners.error.forEach((listener) => this._callEventListener(event, listener));

        const transport = this._transport;
        this._transport = undefined;
        this._setTransportHandle(undefined);

        if (transport) {
            void transport.close(1011, error.message);
        }

        if (this._shouldReconnect && !this._closeCalled) {
            void this._connect();
        }
    }

    private _handleClose(code: number, reason: string): void {
        this._debug("close event", code, reason);
        this._clearConnectTimeout();
        this._transport = undefined;
        this._readyState = ReconnectingWebSocket.ReadyState.CLOSED;
        this._setTransportHandle(undefined);

        if (code === 1000) {
            this._shouldReconnect = false;
        }

        this._emitClose(code, reason);

        if (this._shouldReconnect && !this._closeCalled) {
            void this._connect();
        }
    }

    private _emitClose(code: number, reason: string): void {
        const event = new websocketEvents.CloseEvent(code, reason, this);

        if (this.onclose) {
            this.onclose(event);
        }
        this._listeners.close.forEach((listener) => this._callEventListener(event, listener));
    }

    private _setTransportHandle(transport: DeepgramTransport | undefined): void {
        if (!transport) {
            this._ws = undefined;
            return;
        }

        this._ws = {
            OPEN: this.OPEN,
            get readyState() {
                return transport.isOpen()
                    ? ReconnectingWebSocket.ReadyState.OPEN
                    : ReconnectingWebSocket.ReadyState.CLOSED;
            },
            ping: transport.ping
                ? (data?: string | ArrayBuffer | Blob | ArrayBufferView) => {
                      void transport.ping?.(data);
                  }
                : undefined,
        };
    }

    private _callEventListener<T extends keyof websocketEvents.WebSocketEventListenerMap>(
        event: websocketEvents.WebSocketEventMap[T],
        listener: websocketEvents.WebSocketEventListenerMap[T],
    ): void {
        if (typeof listener === "object" && listener && "handleEvent" in listener) {
            (listener as { handleEvent: (event: websocketEvents.WebSocketEventMap[T]) => void }).handleEvent(event);
        } else {
            (listener as (event: websocketEvents.WebSocketEventMap[T]) => void)(event);
        }
    }
}

/**
 * Helper function to get WebSocket class and handle headers/protocols based on runtime.
 * In Node.js, use the 'ws' library which supports headers.
 * In browser, use Sec-WebSocket-Protocol for authentication since headers aren't supported.
 */
function getWebSocketOptions(headers: Record<string, unknown>, requestedProtocols: string[]): { 
    WebSocket?: any; 
    headers?: Record<string, unknown>; 
    protocols?: string[];
} {
    const options: { WebSocket?: any; headers?: Record<string, unknown>; protocols?: string[] } = {};
    
    // Check if we're in a browser environment (browser or web-worker)
    const isBrowser = RUNTIME.type === "browser" || RUNTIME.type === "web-worker";
    
    // Extract session ID header
    const sessionIdHeader = headers["x-deepgram-session-id"] || headers["X-Deepgram-Session-Id"];
    
    // In Node.js, ensure we use the 'ws' library which supports headers
    if (RUNTIME.type === "node" && NodeWebSocket) {
        options.WebSocket = NodeWebSocket;
        options.headers = headers;
        if (requestedProtocols.length > 0) {
            options.protocols = requestedProtocols;
        }
    } else if (isBrowser) {
        // In browser, native WebSocket doesn't support custom headers
        // Extract Authorization header and use Sec-WebSocket-Protocol instead
        const authHeader = headers.Authorization || headers.authorization;
        const browserHeaders: Record<string, unknown> = { ...headers };
        
        // Remove Authorization and session ID from headers since they won't work in browser
        delete browserHeaders.Authorization;
        delete browserHeaders.authorization;
        delete browserHeaders["x-deepgram-session-id"];
        delete browserHeaders["X-Deepgram-Session-Id"];
        
        options.headers = browserHeaders;
        
        // Build protocols array for browser WebSocket
        const protocols = [...requestedProtocols];
        
        // If we have an Authorization header, extract the token and format as protocols
        // Deepgram expects:
        // - For API keys: Sec-WebSocket-Protocol: token,API_KEY_GOES_HERE
        // - For Bearer tokens: Sec-WebSocket-Protocol: bearer,TOKEN_GOES_HERE
        // The comma separates multiple protocols, so we pass them as an array
        if (authHeader && typeof authHeader === "string") {
            if (authHeader.startsWith("Token ")) {
                // API key: "Token API_KEY" -> ["token", "API_KEY"]
                const apiKey = authHeader.substring(6); // Remove "Token " prefix
                protocols.push("token", apiKey);
            } else if (authHeader.startsWith("Bearer ")) {
                // Access token: "Bearer TOKEN" -> ["bearer", "TOKEN"]
                const token = authHeader.substring(7); // Remove "Bearer " prefix
                protocols.push("bearer", token);
            } else {
                // Fallback: use the entire header value if it doesn't match expected format
                protocols.push(authHeader);
            }
        }
        
        // Add session ID as a protocol for browser WebSocket
        if (sessionIdHeader && typeof sessionIdHeader === "string") {
            protocols.push("x-deepgram-session-id", sessionIdHeader);
        }
        
        if (protocols.length > 0) {
            options.protocols = protocols;
        }
    } else {
        // Fallback for other environments
        options.headers = headers;
        if (requestedProtocols.length > 0) {
            options.protocols = requestedProtocols;
        }
    }
    
    return options;
}

/**
 * Helper function to setup binary-aware message handling for WebSocket sockets.
 * Handles both text (JSON) and binary messages correctly.
 */
function setupBinaryHandling(socket: ReconnectingWebSocket, eventHandlers: { message?: (data: any) => void }): (event: MessageEvent) => void {
    const binaryAwareHandler = (event: MessageEvent) => {
        // Handle both text (JSON) and binary messages
        if (typeof event.data === "string") {
            try {
                const data = fromJson(event.data);
                eventHandlers.message?.(data);
            } catch (error) {
                // If JSON parsing fails, pass the raw string
                eventHandlers.message?.(event.data);
            }
        } else {
            // Binary data - pass through as-is
            eventHandlers.message?.(event.data);
        }
    };

    // Remove the original handler and add our binary-aware one
    const socketAny = socket as any;
    if (socketAny._listeners?.message) {
        // Remove all message listeners
        socketAny._listeners.message.forEach((listener: any) => {
            socket.removeEventListener("message", listener);
        });
    }
    
    // Add our binary-aware handler
    socket.addEventListener("message", binaryAwareHandler);
    
    return binaryAwareHandler;
}

/**
 * Helper to prevent duplicate event listeners on WebSocket connections.
 * This removes all event listeners that were registered by the auto-generated
 * Socket class constructor, preventing duplicate event firing when connect() is called.
 */
function preventDuplicateEventListeners(socket: ReconnectingWebSocket, handlers: {
    handleOpen?: () => void;
    handleMessage?: (event: any) => void;
    handleClose?: (event: any) => void;
    handleError?: (event: any) => void;
}) {
    // Remove the handlers that were added by the auto-generated constructor
    if (handlers.handleOpen) {
        socket.removeEventListener("open", handlers.handleOpen);
    }
    if (handlers.handleMessage) {
        socket.removeEventListener("message", handlers.handleMessage);
    }
    if (handlers.handleClose) {
        socket.removeEventListener("close", handlers.handleClose);
    }
    if (handlers.handleError) {
        socket.removeEventListener("error", handlers.handleError);
    }
}

/**
 * Helper function to reset socket connection state before connecting.
 * Ensures _connectLock is reset if the socket is in CLOSED state.
 */
function resetSocketConnectionState(socket: ReconnectingWebSocket): void {
    if (socket.readyState === socket.CLOSED) {
        // Force a fresh reconnect to ensure _connectLock is reset
        (socket as any)._connectLock = false;
        (socket as any)._shouldReconnect = true;
    }
}

/**
 * Helper function to create a WebSocket connection with common setup logic.
 * Handles authentication, header merging, and WebSocket configuration.
 * This reduces duplication across all Wrapped*Client classes.
 */
async function createWebSocketConnection({
    options,
    urlPath,
    environmentKey,
    queryParams,
    protocols,
    service,
    headers,
    debug,
    reconnectAttempts,
    connectionTimeoutInSeconds,
    abortSignal,
}: {
    options: DeepgramClient.Options;
    urlPath: string;
    environmentKey: "agent" | "production";
    queryParams: Record<string, unknown>;
    protocols?: string | string[];
    service: DeepgramTransportRequest["service"];
    headers?: Record<string, unknown>;
    debug?: boolean;
    reconnectAttempts?: number;
    connectionTimeoutInSeconds?: number;
    abortSignal?: AbortSignal;
}): Promise<ReconnectingWebSocket> {
    // Ensure ws is loaded for Node.js environments (no-op after first call)
    await loadNodeWebSocket();

    // Get Authorization from authProvider (cast to any to access internal property)
    const authRequest = await (options as any).authProvider?.getAuthRequest();

    // Merge headers from options (which includes session ID), auth headers, and request headers
    const mergedHeaders = mergeHeaders(
        options.headers ?? {},
        authRequest?.headers ?? {},
        headers,
    );

    // Resolve any Suppliers in headers to actual values
    const _headers = await resolveHeaders(mergedHeaders);
    const normalizedProtocols = normalizeProtocols(protocols);

    // Get the appropriate base URL for the environment
    const baseUrl = (await core.Supplier.get(options.baseUrl)) ??
        (
            (await core.Supplier.get(options.environment)) ??
            environments.DeepgramEnvironment.Production
        )[environmentKey];

    const url = core.url.join(baseUrl, urlPath);
    const fullUrl = buildWebSocketUrl(url, queryParams);
    const transportFactory = getTransportFactory(options);
    const reconnect = getReconnect(options);

    if (transportFactory) {
        const request: DeepgramTransportRequest = {
            url: fullUrl,
            headers: stringifyHeaders(_headers),
            protocols: normalizedProtocols,
            path: urlPath,
            service,
            queryParams,
            debug: debug ?? false,
            reconnectAttempts: reconnectAttempts ?? 30,
            connectionTimeoutInSeconds,
            abortSignal,
        };

        return new TransportWebSocketAdapter({
            factory: transportFactory,
            request,
            startClosed: true,
            reconnect,
        }) as unknown as ReconnectingWebSocket;
    }

    // Get WebSocket options with proper header handling
    const wsOptions = getWebSocketOptions(_headers, normalizedProtocols);

    // Create and return the ReconnectingWebSocket
    return new ReconnectingWebSocket({
        url,
        protocols: wsOptions.protocols ?? [],
        queryParameters: queryParams,
        headers: wsOptions.headers,
        options: {
            WebSocket: wsOptions.WebSocket,
            debug: debug ?? false,
            maxRetries: reconnectAttempts ?? 30,
            startClosed: true,
            connectionTimeout: connectionTimeoutInSeconds != null ? connectionTimeoutInSeconds * 1000 : DEFAULT_CONNECTION_TIMEOUT_MS,
        },
        abortSignal,
    });
}

/**
 * Wrapper for Agent V1Client that overrides connect to use custom websocket.
 *
 * This wrapper ensures that the connect() method uses our custom ReconnectingWebSocket
 * implementation instead of any auto-generated WebSocket handling. This guarantees
 * consistent behavior across Fern regenerations and allows us to customize
 * connection setup, authentication, and header handling.
 */
class WrappedAgentV1Client extends AgentV1Client {
    public async connect(args: Omit<AgentV1Client.ConnectArgs, "Authorization"> & { Authorization?: string } = {}): Promise<AgentV1Socket> {
        const { headers, protocols, debug, reconnectAttempts, connectionTimeoutInSeconds, abortSignal } = args;

        const socket = await createWebSocketConnection({
            options: this._options,
            urlPath: "/v1/agent/converse",
            environmentKey: 'agent',
            queryParams: buildQueryParams(args as Record<string, unknown>),
            protocols,
            service: "agent.v1",
            headers,
            debug,
            reconnectAttempts,
            connectionTimeoutInSeconds,
            abortSignal,
        });

        return new WrappedAgentV1Socket({ socket });
    }

    /**
     * Creates a WebSocket connection object without actually connecting.
     * This is an alias for connect() with clearer naming - the returned socket
     * is not connected until you call socket.connect().
     *
     * Usage:
     * ```typescript
     * const socket = await client.agent.v1.createConnection();
     * socket.on('open', () => console.log('Connected!'));
     * socket.on('message', (msg) => console.log('Message:', msg));
     * socket.connect(); // Actually initiates the connection
     * ```
     */
    public async createConnection(args: Omit<AgentV1Client.ConnectArgs, "Authorization"> & { Authorization?: string } = {}): Promise<AgentV1Socket> {
        return this.connect(args);
    }
}

/**
 * Wrapper for Agent V1Socket that handles binary messages correctly.
 *
 * This wrapper ensures that both text (JSON) and binary WebSocket messages are
 * handled properly. The auto-generated socket class may not handle binary data
 * correctly, so we override the message handling to support both formats.
 * This is critical for audio and other binary data streaming.
 */
class WrappedAgentV1Socket extends AgentV1Socket {
    private binaryAwareHandler?: (event: MessageEvent) => void;

    constructor(args: AgentV1Socket.Args) {
        super(args);
        this.setupBinaryHandling();
    }

    private setupBinaryHandling() {
        this.binaryAwareHandler = setupBinaryHandling(this.socket, (this as any).eventHandlers);
    }

    public connect(): WrappedAgentV1Socket {
        // Remove duplicate listeners before calling super.connect()
        const socketAny = this as any;
        preventDuplicateEventListeners(this.socket, {
            handleOpen: socketAny.handleOpen,
            handleMessage: socketAny.handleMessage,
            handleClose: socketAny.handleClose,
            handleError: socketAny.handleError
        });

        resetSocketConnectionState(this.socket);
        super.connect();
        // Re-setup binary handling in case connect() re-registered handlers
        this.setupBinaryHandling();
        return this;
    }
}

/**
 * Wrapper for Listen V1Client that overrides connect to use custom websocket.
 *
 * This wrapper ensures that the connect() method uses our custom ReconnectingWebSocket
 * implementation instead of any auto-generated WebSocket handling. This guarantees
 * consistent behavior across Fern regenerations and allows us to customize
 * connection setup, authentication, and header handling.
 */
class WrappedListenV1Client extends ListenV1Client {
    public async connect(args: Omit<ListenV1Client.ConnectArgs, "Authorization"> & { Authorization?: string }): Promise<ListenV1Socket> {
        // Surface the same 400 the REST path throws for nova-3 + keywords, instead of letting the
        // streaming handshake fail silently with a socket that never opens.
        if (isUnsupportedNova3Keywords(args.model, args.keywords)) {
            throw new BadRequestError({
                err_code: "INVALID_QUERY_PARAMETER",
                err_msg: "Keywords are not supported for Nova-3. Please use `keyterm` instead.",
            });
        }

        const { headers, protocols, debug, reconnectAttempts, connectionTimeoutInSeconds, abortSignal } = args;

        const socket = await createWebSocketConnection({
            options: this._options,
            urlPath: "/v1/listen",
            environmentKey: 'production',
            queryParams: buildQueryParams(args as Record<string, unknown>),
            protocols,
            service: "listen.v1",
            headers,
            debug,
            reconnectAttempts,
            connectionTimeoutInSeconds,
            abortSignal,
        });

        return new WrappedListenV1Socket({ socket });
    }

    /**
     * Creates a WebSocket connection object without actually connecting.
     * This is an alias for connect() with clearer naming - the returned socket
     * is not connected until you call socket.connect().
     *
     * Usage:
     * ```typescript
     * const socket = await client.listen.v1.createConnection({ model: 'nova-3' });
     * socket.on('open', () => console.log('Connected!'));
     * socket.on('message', (msg) => console.log('Transcript:', msg));
     * socket.connect(); // Actually initiates the connection
     * ```
     */
    public async createConnection(args: Omit<ListenV1Client.ConnectArgs, "Authorization"> & { Authorization?: string }): Promise<ListenV1Socket> {
        return this.connect(args);
    }
}

/**
 * Wrapper for Listen V1Socket that handles binary messages correctly.
 *
 * This wrapper ensures that both text (JSON) and binary WebSocket messages are
 * handled properly. The auto-generated socket class may not handle binary data
 * correctly, so we override the message handling to support both formats.
 * This is critical for audio and other binary data streaming.
 */
class WrappedListenV1Socket extends ListenV1Socket {
    private binaryAwareHandler?: (event: MessageEvent) => void;

    constructor(args: ListenV1Socket.Args) {
        super(args);
        this.setupBinaryHandling();
    }

    private setupBinaryHandling() {
        this.binaryAwareHandler = setupBinaryHandling(this.socket, (this as any).eventHandlers);
    }

    public connect(): WrappedListenV1Socket {
        // Remove duplicate listeners before calling super.connect()
        const socketAny = this as any;
        preventDuplicateEventListeners(this.socket, {
            handleOpen: socketAny.handleOpen,
            handleMessage: socketAny.handleMessage,
            handleClose: socketAny.handleClose,
            handleError: socketAny.handleError
        });

        resetSocketConnectionState(this.socket);
        super.connect();
        this.setupBinaryHandling();
        return this;
    }
}

/**
 * Wrapper for Listen V2Client that overrides connect to use custom websocket.
 *
 * This wrapper ensures that the connect() method uses our custom ReconnectingWebSocket
 * implementation instead of any auto-generated WebSocket handling. This guarantees
 * consistent behavior across Fern regenerations and allows us to customize
 * connection setup, authentication, and header handling.
 */
class WrappedListenV2Client extends ListenV2Client {
    public async connect(
        args: Omit<ListenV2Client.ConnectArgs, "Authorization" | "keyterm"> & {
            Authorization?: string;
            keyterm?: string | string[];
        }
    ): Promise<ListenV2Socket> {
        const { headers, protocols, debug, reconnectAttempts, connectionTimeoutInSeconds, abortSignal } = args;

        const socket = await createWebSocketConnection({
            options: this._options,
            urlPath: "/v2/listen",
            environmentKey: 'production',
            queryParams: buildQueryParams(args as Record<string, unknown>),
            protocols,
            service: "listen.v2",
            headers,
            debug,
            reconnectAttempts,
            connectionTimeoutInSeconds,
            abortSignal,
        });

        return new WrappedListenV2Socket({ socket });
    }

    /**
     * Creates a WebSocket connection object without actually connecting.
     * This is an alias for connect() with clearer naming - the returned socket
     * is not connected until you call socket.connect().
     *
     * Usage:
     * ```typescript
     * const socket = await client.listen.v2.createConnection({ model: 'flux-general-en' });
     * socket.on('open', () => console.log('Connected!'));
     * socket.on('message', (msg) => console.log('Transcript:', msg));
     * socket.connect(); // Actually initiates the connection
     * ```
     */
    public async createConnection(args: Omit<ListenV2Client.ConnectArgs, "Authorization" | "keyterm"> & { Authorization?: string; keyterm?: string | string[] }): Promise<ListenV2Socket> {
        return this.connect(args);
    }
}

/**
 * Wrapper for Listen V2Socket that handles binary messages correctly and adds ping support.
 *
 * This wrapper ensures that both text (JSON) and binary WebSocket messages are
 * handled properly. The auto-generated socket class may not handle binary data
 * correctly, so we override the message handling to support both formats.
 * Additionally, this wrapper adds a ping() method for sending WebSocket ping
 * frames to keep connections alive (Node.js only).
 */
class WrappedListenV2Socket extends ListenV2Socket {
    private binaryAwareHandler?: (event: MessageEvent) => void;

    constructor(args: ListenV2Socket.Args) {
        super(args);
        this.setupBinaryHandling();
    }

    private setupBinaryHandling() {
        this.binaryAwareHandler = setupBinaryHandling(this.socket, (this as any).eventHandlers);
    }

    public connect(): WrappedListenV2Socket {
        // Remove duplicate listeners before calling super.connect()
        const socketAny = this as any;
        preventDuplicateEventListeners(this.socket, {
            handleOpen: socketAny.handleOpen,
            handleMessage: socketAny.handleMessage,
            handleClose: socketAny.handleClose,
            handleError: socketAny.handleError
        });

        resetSocketConnectionState(this.socket);
        super.connect();
        this.setupBinaryHandling();
        return this;
    }

    /**
     * Send a WebSocket ping frame to keep the connection alive.
     *
     * In Node.js, this uses the native WebSocket ping() method from the 'ws' library.
     * In browsers, WebSocket ping/pong is handled automatically by the browser and
     * cannot be manually triggered, so this method will throw an error.
     *
     * @param data Optional data to send with the ping (Node.js only)
     * @throws Error if not in Node.js environment or WebSocket is not connected
     */
    public ping(data?: string | Buffer): void {
        const ws = (this.socket as any)._ws;

        if (!ws) {
            throw new Error("WebSocket is not connected. Call connect() and waitForOpen() first.");
        }

        if (ws.readyState !== ws.OPEN) {
            throw new Error("WebSocket is not in OPEN state.");
        }

        // Check if we're in Node.js and the WebSocket has a ping method (from 'ws' library)
        if (RUNTIME.type === "node" && typeof ws.ping === "function") {
            // Call the native ping method from the 'ws' library
            ws.ping(data);
        } else {
            // In browsers, WebSocket ping/pong is automatic and not exposed to JavaScript
            throw new Error(
                "WebSocket ping is not supported in browser environments. " +
                "Browser WebSocket connections handle ping/pong automatically. " +
                "If you need keepalive in the browser, consider sending periodic audio data or using a timer."
            );
        }
    }
}

/**
 * Wrapper for Speak V1Client that overrides connect to use custom websocket.
 *
 * This wrapper ensures that the connect() method uses our custom ReconnectingWebSocket
 * implementation instead of any auto-generated WebSocket handling. This guarantees
 * consistent behavior across Fern regenerations and allows us to customize
 * connection setup, authentication, and header handling.
 */
class WrappedSpeakV1Client extends SpeakV1Client {
    public async connect(args: Omit<SpeakV1Client.ConnectArgs, "Authorization"> & { Authorization?: string }): Promise<SpeakV1Socket> {
        const { headers, protocols, debug, reconnectAttempts, connectionTimeoutInSeconds, abortSignal } = args;

        const socket = await createWebSocketConnection({
            options: this._options,
            urlPath: "/v1/speak",
            environmentKey: 'production',
            queryParams: buildQueryParams(args as Record<string, unknown>),
            protocols,
            service: "speak.v1",
            headers,
            debug,
            reconnectAttempts,
            connectionTimeoutInSeconds,
            abortSignal,
        });

        return new WrappedSpeakV1Socket({ socket });
    }

    /**
     * Creates a WebSocket connection object without actually connecting.
     * This is an alias for connect() with clearer naming - the returned socket
     * is not connected until you call socket.connect().
     *
     * Usage:
     * ```typescript
     * const socket = await client.speak.v1.createConnection({ model: 'aura-asteria-en' });
     * socket.on('open', () => console.log('Connected!'));
     * socket.on('message', (audioData) => console.log('Audio received'));
     * socket.connect(); // Actually initiates the connection
     * ```
     */
    public async createConnection(args: Omit<SpeakV1Client.ConnectArgs, "Authorization"> & { Authorization?: string }): Promise<SpeakV1Socket> {
        return this.connect(args);
    }
}

/**
 * Wrapper for Speak V1Socket that handles binary messages correctly.
 *
 * This wrapper ensures that both text (JSON) and binary WebSocket messages are
 * handled properly. The auto-generated socket class may not handle binary data
 * correctly, so we override the message handling to support both formats.
 * This is critical for audio and other binary data streaming.
 */
class WrappedSpeakV1Socket extends SpeakV1Socket {
    private binaryAwareHandler?: (event: MessageEvent) => void;

    constructor(args: SpeakV1Socket.Args) {
        super(args);
        // CRITICAL: Remove the autogenerated handleMessage that tries to parse EVERYTHING as JSON!
        // The autogenerated Socket class assumes all messages are text/JSON, but TTS sends binary audio.
        // We must remove that broken handler immediately after the parent constructor runs.
        const socketAny = this as any;
        if (socketAny.handleMessage) {
            this.socket.removeEventListener("message", socketAny.handleMessage);
        }
        this.setupBinaryHandling();
    }

    private setupBinaryHandling() {
        this.binaryAwareHandler = setupBinaryHandling(this.socket, (this as any).eventHandlers);
    }

    public connect(): WrappedSpeakV1Socket {
        // Remove duplicate listeners before calling super.connect()
        const socketAny = this as any;
        preventDuplicateEventListeners(this.socket, {
            handleOpen: socketAny.handleOpen,
            handleMessage: socketAny.handleMessage,
            handleClose: socketAny.handleClose,
            handleError: socketAny.handleError
        });

        resetSocketConnectionState(this.socket);
        super.connect();
        this.setupBinaryHandling();
        return this;
    }
}