speechrevolutions 0.2.0

package/dist/cjs/client.js

@@ -0,0 +1,786 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpeechRevolutionsClient = exports.SpeechRevolutions = exports.STTClient = void 0;
+const exceptions_js_1 = require("./exceptions.js");
+const progress_js_1 = require("./progress.js");
+const sse_js_1 = require("./sse.js");
+const transcript_js_1 = require("./transcript.js");
+const upload_js_1 = require("./upload.js");
+const types_js_1 = require("./types.js");
+/**
+ * Identifies the SDK to the platform, which makes a client-side problem findable
+ * in our edge logs without the caller reproducing it. It is also insurance: the
+ * edge answers a request with NO User-Agent with a bare 403, which is how the C#
+ * client turned out to be unable to reach production at all while passing every
+ * test that pointed at a local mock.
+ */
+const USER_AGENT = "speechrevolutions-node/0.2.0";
+const DEFAULT_BASE_URL = "https://api.speechrevolutions.com";
+const UPLOAD_PROGRESS_INTERVAL_MS = 10_000;
+const UPLOAD_MAX_ATTEMPTS = 4;
+const UPLOAD_BASE_DELAY_MS = 1_000;
+const SSE_MAX_RECONNECTS = 10;
+const SSE_RECONNECT_DELAY_MS = 3_000;
+const POLL_INTERVAL_MS = 5_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BACKOFF_MS = 500;
+const RETRY_BACKOFF_MAX_MS = 30_000;
+const RETRY_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+const REQUEST_ID_HEADERS = ["x-request-id", "x-amzn-requestid", "cf-ray"];
+/**
+ * Endpoints that CREATE a job, and so are not safe to blindly retry.
+ *
+ * A job is created the moment the server handles one of these; the response
+ * carrying the job_id back is what can be lost. Retrying after the request may
+ * have arrived creates a SECOND job for the same audio — two transcripts, two
+ * charges — and the caller never learns about the orphan. The API has no
+ * idempotency key, so the only safe rule is to retry these solely when the
+ * request provably never reached the server.
+ *
+ * Every other endpoint either reads, or acts on a jobId the caller already
+ * holds, and stays fully retryable.
+ */
+const JOB_CREATING_PATHS = new Set([
+    "/api/v1/upload",
+    "/api/v1/upload/multipart/create",
+]);
+function createsJob(path) {
+    const clean = path.split("?")[0].replace(/\/+$/, "");
+    return JOB_CREATING_PATHS.has(clean);
+}
+/**
+ * Network error codes that mean no connection was ever established, so the
+ * request cannot have been processed. Anything else (a reset mid-flight, a
+ * headers timeout) is ambiguous and must not be retried for a create.
+ */
+const NEVER_SENT_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+function neverReachedServer(err) {
+    const code = err?.cause?.code
+        ?? err?.code;
+    return typeof code === "string" && NEVER_SENT_CODES.has(code);
+}
+function extractRequestId(headers) {
+    for (const name of REQUEST_ID_HEADERS) {
+        const value = headers.get(name);
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** Parse a Retry-After header (delta-seconds form) into milliseconds. */
+function parseRetryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const secs = Number(value);
+    return Number.isFinite(secs) ? Math.max(0, secs) * 1000 : undefined;
+}
+function resolveApiKey(apiKey) {
+    if (apiKey)
+        return apiKey;
+    const env = (typeof process !== "undefined" &&
+        (process.env.SPEECHREVOLUTIONS_API_KEY || process.env.STT_API_KEY)) ||
+        undefined;
+    if (env)
+        return env;
+    throw new exceptions_js_1.AuthenticationError("apiKey is required (pass apiKey or set SPEECHREVOLUTIONS_API_KEY / STT_API_KEY)");
+}
+/**
+ * Resolves the API host: an explicit option, then the environment, then
+ * production.
+ *
+ * Symmetric with the API key — if a caller can supply a key from the
+ * environment, they can point it at an environment too. Needed for staging, for
+ * an egress proxy or gateway, and for running any published example against
+ * something that is not production.
+ */
+function resolveBaseUrl(baseUrl) {
+    const env = (typeof process !== "undefined" &&
+        (process.env.SPEECHREVOLUTIONS_BASE_URL || process.env.STT_BASE_URL)) ||
+        undefined;
+    return (baseUrl ?? env ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+/** Internal signal that a multipart upload should fall back to single-shot. */
+class MultipartUnavailable extends Error {
+}
+class STTClient {
+    apiKey;
+    baseUrl;
+    timeout;
+    fetchFn;
+    maxRetries;
+    retryBackoffMs;
+    requestInit;
+    multipart;
+    constructor(opts = {}) {
+        const options = typeof opts === "string" ? { apiKey: opts } : opts ?? {};
+        this.apiKey = resolveApiKey(options.apiKey);
+        this.baseUrl = resolveBaseUrl(options.baseUrl);
+        this.timeout = options.timeout ?? 600;
+        this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryBackoffMs = options.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+        this.requestInit = options.requestInit ?? {};
+        // Prefer multipart; falls back to a single presigned PUT if the server has
+        // multipart disabled (404) or a multipart upload fails mid-flight.
+        this.multipart = options.multipart ?? true;
+    }
+    retryDelayMs(attempt, retryAfterMs) {
+        if (retryAfterMs !== undefined)
+            return Math.min(retryAfterMs, RETRY_BACKOFF_MAX_MS);
+        return Math.min(this.retryBackoffMs * 2 ** (attempt - 1), RETRY_BACKOFF_MAX_MS);
+    }
+    // high-level
+    /**
+     * Transcribe a local file path, remote URL, bytes, or Blob. A URL is handed
+     * to the platform to fetch, so nothing is uploaded from here.
+     */
+    async transcribe(audio, options = {}, onProgress) {
+        const opts = (0, types_js_1.resolveOptions)(options);
+        const onTranscribeProgress = onProgress ?? options.onProgress;
+        const show = options.progress ?? false;
+        if (typeof audio === "string" && isUrl(audio)) {
+            const { jobId, downloadUrl } = await this.submitUrl(audio, opts);
+            return this.awaitTranscript(jobId, downloadUrl, opts, onTranscribeProgress, show);
+        }
+        const { data, fileSize } = await readAudio(audio);
+        // Upload phase: byte-level "Uploading" bar, then a "Transcribing" bar.
+        const upload = (0, progress_js_1.resolveProgress)(options.onUploadProgress, show, {
+            label: "Uploading",
+            bytesMode: true,
+        });
+        let jobId;
+        let jobDownloadUrl;
+        try {
+            ({ jobId, downloadUrl: jobDownloadUrl } = await this.ingestUpload(data, fileSize, opts, upload.callback));
+        }
+        finally {
+            upload.printer?.close();
+        }
+        return this.awaitTranscript(jobId, jobDownloadUrl, opts, onTranscribeProgress, show);
+    }
+    /** Waits out the transcription phase and parses the result. */
+    async awaitTranscript(jobId, jobDownloadUrl, opts, onProgress, show) {
+        const transcribeProgress = (0, progress_js_1.resolveProgress)(onProgress, show, { label: "Transcribing" });
+        let content;
+        let downloadUrl;
+        try {
+            ({ content, downloadUrl } = await this.waitForResult(jobId, jobDownloadUrl, transcribeProgress.callback));
+        }
+        finally {
+            transcribeProgress.printer?.close();
+        }
+        return (0, transcript_js_1.parseTranscript)({
+            jobId,
+            content,
+            outputType: opts.outputType,
+            downloadUrl,
+        });
+    }
+    /** Registers a job the platform fetches itself. No bytes leave this process. */
+    async submitUrl(audioUrl, opts) {
+        const data = await this.apiRequest("POST", "/api/v1/upload", { ...this.uploadBody(undefined, opts), audio_url: audioUrl });
+        return { jobId: String(data.job_id), downloadUrl: String(data.download_url) };
+    }
+    async transcribeUrl(url, options = {}, onProgress) {
+        return this.transcribe(url, options, onProgress);
+    }
+    async transcribeFile(path, options = {}, onProgress) {
+        return this.transcribe(path, options, onProgress);
+    }
+    /**
+     * Upload and enqueue a job, returning its `jobId` WITHOUT waiting for the
+     * result. Collect it later via a webhook (`callbackUrl`) or by polling
+     * `getJobStatus` / `getTranscript`. Ideal for batch workloads — submit many,
+     * then gather — since it holds no long-lived connection per job.
+     */
+    async submit(audio, options = {}) {
+        const opts = (0, types_js_1.resolveOptions)(options);
+        if (typeof audio === "string" && isUrl(audio)) {
+            const { jobId } = await this.submitUrl(audio, opts);
+            return jobId;
+        }
+        const { data, fileSize } = await readAudio(audio);
+        const upload = (0, progress_js_1.resolveProgress)(options.onUploadProgress, options.progress ?? false, {
+            label: "Uploading",
+            bytesMode: true,
+        });
+        let jobId;
+        try {
+            ({ jobId } = await this.ingestUpload(data, fileSize, opts, upload.callback));
+        }
+        finally {
+            upload.printer?.close();
+        }
+        return jobId;
+    }
+    // upload flow
+    /** JSON body shared by the single-shot and multipart create endpoints. */
+    uploadBody(fileSize, opts) {
+        return {
+            ...(fileSize === undefined ? {} : { file_size: fileSize }),
+            output_type: opts.outputType,
+            word_timestamps: opts.wordTimestamps,
+            speaker_labels: opts.speakerLabels,
+            nltk: opts.nltk,
+            tier: opts.tier,
+            ...(opts.customVocabulary ? { custom_vocabulary: opts.customVocabulary } : {}),
+            ...(opts.callbackUrl ? { callback_url: opts.callbackUrl } : {}),
+        };
+    }
+    /**
+     * Get audio into the platform and return `{ jobId, downloadUrl }`. Prefers a
+     * multipart upload (when enabled) and falls back to a single presigned PUT if
+     * the server has multipart disabled or a multipart upload fails mid-flight.
+     */
+    async ingestUpload(data, fileSize, opts, onProgress) {
+        if (this.multipart) {
+            try {
+                return await this.uploadMultipart(data, fileSize, opts, onProgress);
+            }
+            catch (err) {
+                if (!(err instanceof MultipartUnavailable))
+                    throw err;
+                // multipart unavailable — fall through to the single-shot path
+            }
+        }
+        const job = await this.createUploadJob(fileSize, opts);
+        await this.uploadAudio(job.uploadUrl, data, { jobId: job.jobId, onProgress });
+        await this.completeUpload(job.jobId);
+        return { jobId: job.jobId, downloadUrl: job.downloadUrl };
+    }
+    /**
+     * S3 multipart flow: create -> PUT each part -> complete. Throws
+     * {@link MultipartUnavailable} if the server has multipart disabled (404) or a
+     * mid-flight failure means we should retry via the single-shot path.
+     */
+    async uploadMultipart(data, fileSize, opts, onProgress) {
+        let created;
+        try {
+            created = await this.apiRequest("POST", "/api/v1/upload/multipart/create", this.uploadBody(fileSize, opts));
+        }
+        catch (err) {
+            // The route returns 404 when multipart is disabled.
+            if (err instanceof exceptions_js_1.JobNotFoundError)
+                throw new MultipartUnavailable();
+            throw err;
+        }
+        const jobId = String(created.job_id);
+        const partSize = Number(created.part_size);
+        const byteCb = (0, upload_js_1.byteProgressAdapter)(onProgress);
+        const completedParts = [];
+        let uploaded = 0;
+        try {
+            for (const part of created.parts) {
+                const number = Number(part.part_number);
+                const start = (number - 1) * partSize;
+                const chunk = data.subarray(start, start + partSize);
+                const etag = await this.putPart(part.url, chunk);
+                completedParts.push({ part_number: number, etag });
+                uploaded += chunk.length;
+                byteCb?.(uploaded, fileSize);
+            }
+            await this.apiRequest("POST", "/api/v1/upload/multipart/complete", {
+                job_id: jobId,
+                parts: completedParts,
+            });
+        }
+        catch (err) {
+            // Roll back the partial upload, then fall back to a single-shot PUT.
+            try {
+                await this.apiRequest("POST", "/api/v1/upload/multipart/abort", { job_id: jobId });
+            }
+            catch {
+                /* best effort */
+            }
+            throw new MultipartUnavailable(String(err));
+        }
+        return { jobId, downloadUrl: String(created.download_url) };
+    }
+    /** PUT one part to its presigned URL and return the S3 ETag. */
+    async putPart(url, chunk) {
+        const resp = await this.fetchFn(url, { method: "PUT", body: toArrayBuffer(chunk) });
+        if (resp.status !== 200 && resp.status !== 204) {
+            throw new exceptions_js_1.UploadError(`part upload failed (HTTP ${resp.status})`);
+        }
+        const etag = resp.headers.get("ETag") ?? resp.headers.get("etag");
+        if (!etag)
+            throw new exceptions_js_1.UploadError("part upload response missing ETag header");
+        return etag;
+    }
+    async createUploadJob(fileSize, options = {}) {
+        const opts = (0, types_js_1.resolveOptions)(options);
+        const body = this.uploadBody(fileSize, opts);
+        const data = await this.apiRequest("POST", "/api/v1/upload", body);
+        return {
+            jobId: String(data.job_id),
+            uploadUrl: data.upload_url,
+            downloadUrl: data.download_url,
+            contentType: data.content_type ?? "application/octet-stream",
+            expiresIn: data.expires_in ?? 0,
+        };
+    }
+    async touchUploadProgress(jobId) {
+        await this.apiRequest("POST", "/api/v1/upload/progress", { job_id: jobId });
+    }
+    async uploadAudio(uploadUrl, data, opts = {}) {
+        const contentType = opts.contentType ?? "application/octet-stream";
+        const byteCb = (0, upload_js_1.byteProgressAdapter)(opts.onProgress);
+        const stop = { stopped: false };
+        let heartbeat;
+        if (opts.jobId) {
+            heartbeat = setInterval(() => {
+                if (stop.stopped)
+                    return;
+                void this.touchUploadProgress(opts.jobId).catch(() => undefined);
+            }, UPLOAD_PROGRESS_INTERVAL_MS);
+        }
+        let lastError;
+        try {
+            for (let attempt = 1; attempt <= UPLOAD_MAX_ATTEMPTS; attempt++) {
+                try {
+                    // A fresh streamed body per attempt so retries restart progress from 0.
+                    await this.putUpload(uploadUrl, data, contentType, byteCb);
+                    return;
+                }
+                catch (err) {
+                    lastError = err;
+                    if (attempt < UPLOAD_MAX_ATTEMPTS) {
+                        await sleep(UPLOAD_BASE_DELAY_MS * 2 ** (attempt - 1));
+                    }
+                }
+            }
+        }
+        finally {
+            stop.stopped = true;
+            if (heartbeat)
+                clearInterval(heartbeat);
+        }
+        throw new exceptions_js_1.UploadError(`Upload failed after ${UPLOAD_MAX_ATTEMPTS} attempts: ${String(lastError)}`);
+    }
+    async completeUpload(jobId) {
+        await this.apiRequest("POST", "/api/v1/upload/complete", { job_id: jobId });
+    }
+    // progress / result
+    async waitForResult(jobId, downloadUrl, onProgress, timeout = this.timeout) {
+        const sseUrl = await this.waitSSE(jobId, downloadUrl, onProgress, timeout);
+        if (sseUrl === null) {
+            const content = await this.waitPoll(jobId, downloadUrl, timeout);
+            return { content, downloadUrl };
+        }
+        const content = await this.downloadResult(sseUrl);
+        return { content, downloadUrl: sseUrl };
+    }
+    async downloadResult(downloadUrl) {
+        const resp = await this.fetchFn(downloadUrl);
+        if (!resp.ok) {
+            throw new exceptions_js_1.APIError(`Download failed (HTTP ${resp.status})`, {
+                statusCode: resp.status,
+                body: await resp.text().then((t) => t.slice(0, 300)),
+            });
+        }
+        return new Uint8Array(await resp.arrayBuffer());
+    }
+    // job management
+    async cancelJob(jobId) {
+        await this.apiRequest("POST", "/api/v1/jobs/cancel", { job_id: jobId });
+    }
+    async checkFailed(jobIds) {
+        const data = await this.apiRequest("POST", "/api/v1/jobs/check-failed", { job_ids: jobIds.map(String) });
+        return data.failed_jobs ?? [];
+    }
+    // retrieval (get by id / list)
+    /** Fetch a job's current status (and a fresh download URL once complete). */
+    async getJobStatus(jobId) {
+        const data = await this.apiRequest("GET", `/api/v1/jobs/${encodeURIComponent(jobId)}`);
+        return {
+            jobId: String(data.job_id ?? jobId),
+            status: String(data.status ?? ""),
+            downloadUrl: data.download_url,
+            failedStage: data.failed_stage,
+            reason: data.reason,
+        };
+    }
+    /**
+     * Fetch and parse a completed job's transcript by id. Throws
+     * {@link JobFailedError} if it failed, or {@link APIError} if still processing.
+     */
+    async getTranscript(jobId, opts = {}) {
+        const status = await this.getJobStatus(jobId);
+        if (status.status === "failed") {
+            throw new exceptions_js_1.JobFailedError(`Job ${jobId} failed`, {
+                step: status.failedStage,
+                reason: status.reason,
+            });
+        }
+        if (status.status !== "completed" || !status.downloadUrl) {
+            throw new exceptions_js_1.APIError(`Job ${jobId} is not complete (status=${status.status})`);
+        }
+        const content = await this.downloadResult(status.downloadUrl);
+        return (0, transcript_js_1.parseTranscript)({
+            jobId,
+            content,
+            outputType: opts.outputType ?? "json",
+            downloadUrl: status.downloadUrl,
+        });
+    }
+    /** List the caller's most-recent jobs (newest first), cursor-paginated. */
+    async listJobs(opts = {}) {
+        const params = new URLSearchParams();
+        params.set("limit", String(opts.limit ?? 50));
+        if (opts.before)
+            params.set("before", opts.before);
+        const data = await this.apiRequest("GET", `/api/v1/jobs?${params.toString()}`);
+        return {
+            jobs: (data.jobs ?? []).map((j) => ({ jobId: j.job_id, createdAt: j.created_at })),
+            nextBefore: data.next_before ?? null,
+        };
+    }
+    // internals
+    headers(extra) {
+        return {
+            "X-API-Key": this.apiKey,
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            ...extra,
+        };
+    }
+    async apiRequest(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        // Job-creating calls retry only when the request provably never landed;
+        // anything else would risk a duplicate job and a duplicate charge.
+        const creating = createsJob(path);
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            let resp;
+            try {
+                resp = await this.fetchFn(url, {
+                    ...this.requestInit,
+                    method,
+                    headers: this.headers(),
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (err) {
+                if (isAbort(err))
+                    throw err;
+                // Retry transient network failures with exponential backoff.
+                const safe = !creating || neverReachedServer(err);
+                if (safe && attempt <= this.maxRetries) {
+                    await sleep(this.retryDelayMs(attempt));
+                    continue;
+                }
+                throw new exceptions_js_1.APIError(`Cannot connect to ${this.baseUrl}: ${String(err)}`);
+            }
+            // Retry throttling / transient server errors, honoring Retry-After.
+            // For a create, only 429 is safe: the server refused it outright, so no
+            // job exists. A 5xx may well have created one before failing.
+            if (RETRY_STATUS_CODES.has(resp.status) &&
+                attempt <= this.maxRetries &&
+                (!creating || resp.status === 429)) {
+                const retryAfterMs = parseRetryAfterMs(resp.headers.get("Retry-After"));
+                await sleep(this.retryDelayMs(attempt, retryAfterMs));
+                continue;
+            }
+            await this.raiseForStatus(resp);
+            if (!resp.body || resp.status === 204)
+                return {};
+            const text = await resp.text();
+            if (!text)
+                return {};
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return { raw: text };
+            }
+        }
+    }
+    async raiseForStatus(resp) {
+        if (resp.status === 200 || resp.status === 204)
+            return;
+        const body = await resp.text().then((t) => t.slice(0, 300)).catch(() => undefined);
+        const requestId = extractRequestId(resp.headers);
+        if (resp.status === 401)
+            throw new exceptions_js_1.AuthenticationError(undefined, { statusCode: 401, requestId, body });
+        if (resp.status === 404)
+            throw new exceptions_js_1.JobNotFoundError(undefined, { statusCode: 404, requestId, body });
+        if (resp.status === 429) {
+            throw new exceptions_js_1.RateLimitError(undefined, {
+                statusCode: 429,
+                requestId,
+                body,
+                retryAfter: (parseRetryAfterMs(resp.headers.get("Retry-After")) ?? 0) / 1000 || undefined,
+            });
+        }
+        throw new exceptions_js_1.APIError(`Unexpected response (HTTP ${resp.status})`, {
+            statusCode: resp.status,
+            requestId,
+            body,
+        });
+    }
+    async putUpload(uploadUrl, data, contentType, byteCb) {
+        let resp;
+        if (byteCb) {
+            // Presigned PUT with progress: stream the body in chunks and report after
+            // each. An explicit Content-Length keeps undici from switching to
+            // Transfer-Encoding: chunked (which S3 rejects); `duplex: "half"` is
+            // required by Node when the body is a stream / async iterable.
+            const init = {
+                method: "PUT",
+                headers: {
+                    "Content-Type": contentType,
+                    "Content-Length": String(data.byteLength),
+                },
+                body: (0, upload_js_1.iterWithProgress)(data, byteCb),
+                duplex: "half",
+            };
+            resp = await this.fetchFn(uploadUrl, init);
+        }
+        else {
+            resp = await this.fetchFn(uploadUrl, {
+                method: "PUT",
+                headers: { "Content-Type": contentType },
+                body: toArrayBuffer(data),
+            });
+        }
+        if (resp.status !== 200 && resp.status !== 204) {
+            const text = await resp.text().then((t) => t.slice(0, 200));
+            throw new exceptions_js_1.UploadError(`HTTP ${resp.status}: ${text}`);
+        }
+    }
+    async waitSSE(jobId, fallbackDownloadUrl, onProgress, timeout) {
+        const start = Date.now();
+        let lastEventId;
+        let reconnects = 0;
+        while (true) {
+            const elapsed = (Date.now() - start) / 1000;
+            if (elapsed >= timeout) {
+                throw new exceptions_js_1.TimeoutError(`Timed out after ${timeout}s waiting for job ${jobId}`);
+            }
+            if (reconnects > SSE_MAX_RECONNECTS)
+                return null;
+            if (reconnects > 0)
+                await sleep(SSE_RECONNECT_DELAY_MS);
+            const result = await this.sseAttempt(jobId, start, timeout, lastEventId, fallbackDownloadUrl, onProgress);
+            lastEventId = result.lastEventId;
+            if (result.outcome === "done")
+                return result.downloadUrl ?? fallbackDownloadUrl;
+            if (result.outcome === "failed")
+                throw new exceptions_js_1.JobFailedError("Job failed");
+            if (result.outcome === "timeout") {
+                throw new exceptions_js_1.TimeoutError(`Timed out after ${timeout}s waiting for job ${jobId}`);
+            }
+            reconnects += 1;
+        }
+    }
+    async sseAttempt(jobId, start, timeout, lastEventId, fallbackDownloadUrl, onProgress) {
+        const elapsed = (Date.now() - start) / 1000;
+        if (elapsed >= timeout)
+            return { outcome: "timeout", lastEventId };
+        const headers = {
+            "X-API-Key": this.apiKey,
+            "User-Agent": USER_AGENT,
+            Accept: "text/event-stream",
+        };
+        if (lastEventId !== undefined)
+            headers["Last-Event-ID"] = lastEventId;
+        let resp;
+        try {
+            const controller = new AbortController();
+            const remainingMs = Math.max(1000, (timeout - elapsed) * 1000);
+            const timer = setTimeout(() => controller.abort(), remainingMs);
+            try {
+                resp = await this.fetchFn(`${this.baseUrl}/api/v1/jobs/${jobId}/stream`, {
+                    method: "GET",
+                    headers,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            return { outcome: "reconnect", lastEventId };
+        }
+        if (resp.status === 401)
+            throw new exceptions_js_1.AuthenticationError();
+        if (resp.status === 429)
+            throw new exceptions_js_1.RateLimitError();
+        if (resp.status !== 200)
+            return { outcome: "reconnect", lastEventId };
+        if (!resp.body)
+            return { outcome: "reconnect", lastEventId };
+        const reader = resp.body.getReader();
+        try {
+            for await (const sse of (0, sse_js_1.parseSSEStream)(reader)) {
+                if (sse.id)
+                    lastEventId = sse.id;
+                const nowElapsed = (Date.now() - start) / 1000;
+                if (nowElapsed >= timeout)
+                    return { outcome: "timeout", lastEventId };
+                const eventType = sse.event ?? "message";
+                let data = {};
+                try {
+                    data = JSON.parse(sse.data ?? "{}");
+                }
+                catch {
+                    data = { raw: sse.data };
+                }
+                if (eventType === "progress") {
+                    // Fire the callback inline so progress is live, not replayed in a
+                    // burst after the stream closes.
+                    onProgress?.((0, types_js_1.makeProgressEvent)({
+                        completed: asInt(data.completed),
+                        total: asInt(data.total),
+                        step: typeof data.step === "string" ? data.step : undefined,
+                        elapsedSeconds: nowElapsed,
+                        raw: data,
+                    }));
+                }
+                else if (eventType === "completed") {
+                    const dl = typeof data.download_url === "string"
+                        ? data.download_url
+                        : fallbackDownloadUrl;
+                    return { outcome: "done", downloadUrl: dl, lastEventId };
+                }
+                else if (eventType === "failed") {
+                    const step = String(data.step ?? "unknown");
+                    const reason = String(data.reason ?? "unknown");
+                    throw new exceptions_js_1.JobFailedError(`Job failed at step=${step}: ${reason}`, {
+                        step,
+                        reason,
+                    });
+                }
+            }
+            return { outcome: "reconnect", lastEventId };
+        }
+        catch (err) {
+            if (err instanceof exceptions_js_1.JobFailedError || err instanceof exceptions_js_1.AuthenticationError)
+                throw err;
+            return { outcome: "reconnect", lastEventId };
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async waitPoll(jobId, downloadUrl, timeout) {
+        const start = Date.now();
+        const maxAttempts = Math.max(1, Math.floor(timeout / (POLL_INTERVAL_MS / 1000)));
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            if ((Date.now() - start) / 1000 >= timeout)
+                break;
+            try {
+                const failed = await this.checkFailed([jobId]);
+                if (failed[0])
+                    throw new exceptions_js_1.JobFailedError(`Job ${jobId} has failed`);
+            }
+            catch (err) {
+                if (err instanceof exceptions_js_1.AuthenticationError || err instanceof exceptions_js_1.JobFailedError)
+                    throw err;
+            }
+            try {
+                const resp = await this.fetchFn(downloadUrl);
+                if (resp.ok)
+                    return new Uint8Array(await resp.arrayBuffer());
+            }
+            catch {
+                // ignore probe errors
+            }
+            if (attempt < maxAttempts)
+                await sleep(POLL_INTERVAL_MS);
+        }
+        throw new exceptions_js_1.TimeoutError(`Job ${jobId} did not complete within ${timeout}s`);
+    }
+}
+exports.STTClient = STTClient;
+// helpers
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** True for an aborted request, which must propagate rather than be retried. */
+function isAbort(err) {
+    return (err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError"));
+}
+function toArrayBuffer(data) {
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    return copy.buffer;
+}
+function asInt(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function isUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+async function readAudio(audio) {
+    let data;
+    if (typeof audio === "string") {
+        const { readFile } = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+        data = new Uint8Array(await readFile(audio));
+    }
+    else if (audio instanceof ArrayBuffer) {
+        data = new Uint8Array(audio);
+    }
+    else if (audio instanceof Uint8Array) {
+        data = audio;
+    }
+    else if (typeof Blob !== "undefined" && audio instanceof Blob) {
+        data = new Uint8Array(await audio.arrayBuffer());
+    }
+    else {
+        throw new TypeError(`Unsupported audio type: ${typeof audio}`);
+    }
+    if (data.byteLength === 0)
+        throw new Error("Audio is empty");
+    return { data, fileSize: data.byteLength };
+}
+/** @deprecated Use STTClient — alias for Deepgram / ElevenLabs naming. */
+class SpeechRevolutions extends STTClient {
+}
+exports.SpeechRevolutions = SpeechRevolutions;
+exports.SpeechRevolutionsClient = SpeechRevolutions;