@ohm_studio/sdk-core 0.6.0 → 0.8.0

package/dist/client.js

@@ -1,9 +1,48 @@
-import { OHMAbortError, OHMAuthError, OHMConfigError, OHMError, OHMRateLimitError, OHMServerError, OHMValidationError, } from "./errors";
+import { OHMAbortError, OHMAuthError, OHMConfigError, OHMError, OHMNetworkError, OHMNotFoundError, OHMQuotaExceededError, OHMRateLimitError, OHMServerError, OHMTimeoutError, OHMValidationError, } from "./errors";
 import { backoffMs, isRetriableStatus } from "./retry";
 import { mockResponseFor } from "./mock";
 const DEFAULT_BASE_URL = "https://api.ohm.doctor";
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_RETRIES = 2;
+/**
+ * Best-effort `User-Agent` for Node. Browsers + RN reject custom UA
+ * via fetch (forbidden header), so we only set it on Node-flavoured
+ * runtimes. Empty string disables the header entirely.
+ */
+function buildUserAgent(sdkVersion) {
+    // @ts-ignore — runtime probe
+    const proc = typeof process !== "undefined" ? process : undefined;
+    if (proc?.versions?.node && !proc.versions.bun) {
+        return `ohm-sdk/${sdkVersion} (node/${proc.versions.node}; ${proc.platform} ${proc.arch})`;
+    }
+    return "";
+}
+/** Generate a UUID v4. Uses native crypto.randomUUID() when available. */
+function uuidv4() {
+    // Node 16+, modern browsers, RN 0.71+ all ship crypto.randomUUID.
+    const g = globalThis;
+    if (g.crypto?.randomUUID)
+        return g.crypto.randomUUID();
+    // Fallback for very old hosts — Math.random is acceptable for an
+    // idempotency key (server only uses it as a dedupe token, not a secret).
+    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);
+    });
+}
+/** Safe-fire a hook; swallow exceptions so user bugs don't break requests. */
+function safeHook(fn, arg) {
+    if (!fn)
+        return;
+    try {
+        fn(arg);
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("[ohm-sdk] hook threw — swallowing:", err);
+    }
+}
 /**
  * Platform-agnostic core client. Subclasses (sdk-js, sdk-react-native)
  * supply the platform-specific multipart/audio adapter via the `attachAudio`
@@ -14,11 +53,19 @@ export class OHMCoreClient {
     apiKey;
     jwt;
     timeoutMs;
+    totalTimeoutMs;
     maxRetries;
     fetchImpl;
     onUsage;
+    hooks;
+    disableAutoIdempotency;
+    userAgent;
     _mock;
     _mockResponses;
+    /** Cached options for `withOverrides`. */
+    _opts;
+    /** SDK version stamped on `X-OHM-Client` + `User-Agent`. */
+    static SDK_VERSION = "0.8.0";
     constructor(init) {
         // Accept either a bare `ohms_live_…` string (`new OHM("…")`) or the
         // full options object. Most customers want the one-liner.
@@ -30,16 +77,71 @@ export class OHMCoreClient {
                 message: "OHM client requires an apiKey. Pass it as `new OHM('ohms_live_…')` or `new OHM({ apiKey: '…' })`.",
             });
         }
+        this._opts = opts;
         this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.apiKey = opts.apiKey;
         this.jwt = opts.jwt;
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.totalTimeoutMs = opts.totalTimeoutMs;
         this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
         this.onUsage = opts.onUsage;
+        this.hooks = opts.hooks;
+        this.disableAutoIdempotency = !!opts.disableAutoIdempotency;
+        this.userAgent = buildUserAgent(OHMCoreClient.SDK_VERSION);
         this._mock = !!opts.mock;
         this._mockResponses = opts.mockResponses;
     }
+    /**
+     * Returns the SDK version string. Useful when forwarding the SDK
+     * version to your own telemetry pipeline.
+     */
+    static getVersion() {
+        return OHMCoreClient.SDK_VERSION;
+    }
+    /**
+     * Returns a new client with overridden options for one call. The
+     * underlying auth + base URL are inherited; you typically only
+     * override `timeoutMs` / `maxRetries` / `totalTimeoutMs` for a
+     * single known-slow call.
+     *
+     * @example
+     *   const slow = ohm.withOverrides({ timeoutMs: 5 * 60_000 });
+     *   await slow.audio.extract({ apiSlug, file: bigAudio });
+     */
+    withOverrides(overrides) {
+        // Build a new instance of the same subclass with merged options.
+        // Cast through `unknown` keeps the static type but uses the
+        // runtime constructor (sdk-js / sdk-rn / etc).
+        const Ctor = this.constructor;
+        return new Ctor({ ...this._opts, ...overrides });
+    }
+    /**
+     * Establish a TCP/TLS connection to the API ahead of the first real
+     * call. Drops cold-start latency from ~500 ms to ~150 ms on real-world
+     * mobile networks. Safe to call multiple times; no-op in mock mode.
+     *
+     *   const ohm = new OHM({ apiKey });
+     *   void ohm.warmUp();      // fire-and-forget at app boot
+     *   // ...
+     *   await ohm.extract({ ... });   // already-warm connection
+     */
+    async warmUp() {
+        if (this._mock)
+            return;
+        try {
+            await this.fetchImpl(`${this.baseUrl}/api/health`, {
+                method: "GET",
+                // Short, non-retried, abort-able. We don't care about the
+                // response body — only that the TLS handshake completes.
+                signal: AbortSignal.timeout(5_000),
+            });
+        }
+        catch {
+            // Warm-up is best-effort. If the network is offline the real
+            // call will surface its own OHMNetworkError.
+        }
+    }
     /**
      * Audio surface — speech-to-text and audio-to-structured-JSON.
      * Subclasses fill in the platform-specific multipart adapter (browser
@@ -125,7 +227,7 @@ export class OHMCoreClient {
          * step finishes. Backend uses Server-Sent Events.
          *
          * @example
-         *   const stream = ohm.audio.extract.stream({ apiSlug, file });
+         *   const stream = ohm.audio.extractStream({ apiSlug, file });
          *   for await (const chunk of stream) {
          *     if (chunk.type === "transcript") setT(chunk.transcript);
          *     if (chunk.type === "data") setData(chunk.data);
@@ -270,9 +372,14 @@ export class OHMCoreClient {
              * CANCELLED — caller checks status). Never returns mid-state.
              */
             poll: async (jobId, options = {}) => {
-                const intervalMs = options.intervalMs ?? 2000;
+                const initialIntervalMs = options.intervalMs ?? 2000;
+                const maxIntervalMs = options.maxIntervalMs ?? 30_000;
                 const maxWaitMs = options.maxWaitMs ?? 15 * 60_000;
                 const start = Date.now();
+                // Exponential backoff capped at maxIntervalMs — protects the
+                // worker from a chatty client when a job stays PROCESSING for
+                // 10+ minutes. Grows 1.5× per poll: 2 → 3 → 4.5 → ... → 30.
+                let interval = initialIntervalMs;
                 // eslint-disable-next-line no-constant-condition
                 while (true) {
                     if (options.signal?.aborted)
@@ -292,7 +399,8 @@ export class OHMCoreClient {
                             status: 0,
                         });
                     }
-                    await new Promise((r) => setTimeout(r, intervalMs));
+                    await new Promise((r) => setTimeout(r, interval));
+                    interval = Math.min(maxIntervalMs, Math.round(interval * 1.5));
                 }
             },
         },
@@ -353,6 +461,67 @@ export class OHMCoreClient {
             idempotencyKey: input.idempotencyKey,
         });
     }
+    /**
+     * Bulk-extract a batch of text inputs concurrently. Partial failures
+     * do NOT fail the batch — each input gets a discriminated-union
+     * result (`{ ok: true, data }` or `{ ok: false, error, input }`).
+     *
+     * Use when replaying historical transcripts, batch-tagging lab
+     * reports, or anywhere "10 000 of these need to extract this week".
+     *
+     * Default concurrency is 4 — enough to amortise network round-trips
+     * without blowing the per-key rate limit. Pass a higher cap when you
+     * know your key's quota is generous.
+     *
+     * @example
+     *   const results = await ohm.extractBulk(transcripts.map(t => ({
+     *     apiSlug: "opd-clinic",
+     *     text: t,
+     *   })), {
+     *     concurrency: 8,
+     *     onProgress: (done, total) => console.log(`${done}/${total}`),
+     *   });
+     *   const errored = results.filter(r => !r.ok);
+     */
+    async extractBulk(inputs, options = {}) {
+        const concurrency = Math.max(1, options.concurrency ?? 4);
+        const results = new Array(inputs.length);
+        let cursor = 0;
+        let done = 0;
+        const total = inputs.length;
+        const signal = options.signal;
+        const worker = async () => {
+            while (cursor < total) {
+                if (signal?.aborted) {
+                    throw new OHMAbortError();
+                }
+                const idx = cursor++;
+                const input = inputs[idx];
+                try {
+                    const data = await this.extract({ ...input, signal });
+                    results[idx] = { ok: true, data };
+                }
+                catch (err) {
+                    results[idx] = {
+                        ok: false,
+                        error: err instanceof Error ? err : new Error(String(err)),
+                        input,
+                    };
+                }
+                finally {
+                    done++;
+                    try {
+                        options.onProgress?.(done, total);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, total) }, () => worker()));
+        return results;
+    }
     /**
      * One-line convenience: pass a transcript, get back the data field.
      * Equivalent to `(await ohm.extract({ apiSlug, text })).data` — the most
@@ -519,7 +688,7 @@ export class OHMCoreClient {
         return this.requestRaw(method, path, init, options);
     }
     /**
-     * Default SSE-based streaming for audio.extract.stream. Subclasses
+     * Default SSE-based streaming for audio.extractStream. Subclasses
      * override `runMultipart` to construct the FormData body for their
      * platform; this method reuses that body and parses an SSE event stream
      * off the response.
@@ -537,7 +706,7 @@ export class OHMCoreClient {
             headers.Authorization = `Bearer ${this.apiKey}`;
         else if (this.jwt)
             headers.Authorization = `Bearer ${this.jwt}`;
-        headers["X-OHM-Client"] = "@ohm_studio/sdk-core@0.6.0";
+        headers["X-OHM-Client"] = "@ohm_studio/sdk-core@0.7.0";
         if (opts.idempotencyKey) {
             headers["Idempotency-Key"] = opts.idempotencyKey;
         }
@@ -614,6 +783,11 @@ export class OHMCoreClient {
         });
     }
     async requestRaw(method, path, init, options) {
+        // ── Resolve per-call overrides (or fall back to client defaults).
+        const perAttemptTimeout = options?.timeoutMs ?? this.timeoutMs;
+        const maxRetries = options?.maxRetries ?? this.maxRetries;
+        const totalDeadline = options?.totalTimeoutMs ?? this.totalTimeoutMs;
+        const deadlineAt = totalDeadline != null ? Date.now() + totalDeadline : undefined;
         const url = `${this.baseUrl}${path}`;
         const headers = new Headers(init.headers || {});
         if (this.apiKey)
@@ -621,13 +795,45 @@ export class OHMCoreClient {
         else if (this.jwt)
             headers.set("Authorization", `Bearer ${this.jwt}`);
         if (!headers.has("X-OHM-Client")) {
-            headers.set("X-OHM-Client", "@ohm_studio/sdk-core@0.6.0");
+            headers.set("X-OHM-Client", `@ohm_studio/sdk-core@${OHMCoreClient.SDK_VERSION}`);
+        }
+        // User-Agent — Node only. Browsers + RN reject custom UA.
+        if (this.userAgent && !headers.has("User-Agent")) {
+            try {
+                headers.set("User-Agent", this.userAgent);
+            }
+            catch {
+                // Some hosts forbid setting User-Agent — swallow.
+            }
+        }
+        // ── Idempotency-Key: caller-supplied wins. Otherwise auto-generate
+        //    for unsafe methods (POST/PATCH/PUT/DELETE) unless explicitly
+        //    disabled. `null` from the caller is an explicit opt-out.
+        const isUnsafe = method === "POST" ||
+            method === "PATCH" ||
+            method === "PUT" ||
+            method === "DELETE";
+        let idempotencyKey;
+        if (options?.idempotencyKey === null) {
+            // explicit opt-out — leave header off
         }
-        // Idempotency-Key — server short-circuits same-key retries within
-        // 24 h to the cached response. Stripe / Twilio convention.
-        if (options?.idempotencyKey) {
-            headers.set("Idempotency-Key", options.idempotencyKey);
+        else if (typeof options?.idempotencyKey === "string") {
+            idempotencyKey = options.idempotencyKey;
         }
+        else if (isUnsafe && !this.disableAutoIdempotency) {
+            idempotencyKey = uuidv4();
+        }
+        if (idempotencyKey) {
+            headers.set("Idempotency-Key", idempotencyKey);
+        }
+        // ── Body inspection for keepalive eligibility. Browser fetch
+        //    enforces a 64 KB cap on keepalive bodies; we play it safe at
+        //    60 KB and skip multipart bodies entirely.
+        const bodyAsString = typeof init.body === "string" ? init.body : "";
+        const keepaliveEligible = isUnsafe &&
+            bodyAsString.length > 0 &&
+            bodyAsString.length < 60_000 &&
+            headers.get("content-type")?.includes("application/json") === true;
         // Caller-supplied signal short-circuits before any work is started —
         // matches DOM fetch() semantics and avoids burning a retry on an
         // already-cancelled request.
@@ -635,25 +841,45 @@ export class OHMCoreClient {
             throw new OHMAbortError();
         }
         let lastError;
-        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            // ── Deadline check before each attempt.
+            if (deadlineAt != null && Date.now() >= deadlineAt) {
+                throw new OHMTimeoutError({
+                    message: `Total request deadline (${totalDeadline}ms) exceeded after ${attempt} attempt(s)`,
+                });
+            }
+            // ── Per-attempt timeout: never exceed the remaining deadline.
+            const remaining = deadlineAt != null ? Math.max(50, deadlineAt - Date.now()) : Infinity;
+            const attemptTimeout = Math.min(perAttemptTimeout, remaining);
             const ac = new AbortController();
-            const t = setTimeout(() => ac.abort(), this.timeoutMs);
-            // Bridge the caller's signal into our internal AbortController so
-            // either source (timeout, user cancel) trips the same fetch abort.
+            const t = setTimeout(() => ac.abort(), attemptTimeout);
             let onCallerAbort;
             if (options?.signal) {
                 onCallerAbort = () => ac.abort();
                 options.signal.addEventListener("abort", onCallerAbort, { once: true });
             }
+            safeHook(this.hooks?.onRequest, {
+                method,
+                url,
+                attempt,
+                idempotencyKey,
+            });
             const tStart = Date.now();
             try {
-                const res = await this.fetchImpl(url, {
+                const fetchInit = {
                     ...init,
                     method,
                     headers,
                     signal: ac.signal,
-                });
+                };
+                if (keepaliveEligible) {
+                    fetchInit.keepalive = true;
+                }
+                const res = await this.fetchImpl(url, fetchInit);
                 const latencyMs = Date.now() - tStart;
+                const requestId = res.headers.get("x-request-id") ||
+                    res.headers.get("x-ohm-request-id") ||
+                    undefined;
                 this.onUsage?.({
                     endpoint: path,
                     method,
@@ -662,30 +888,78 @@ export class OHMCoreClient {
                     latencyMs,
                     retries: attempt,
                 });
+                safeHook(this.hooks?.onResponse, {
+                    method,
+                    url,
+                    status: res.status,
+                    ok: res.ok,
+                    attempt,
+                    latencyMs,
+                    requestId,
+                });
                 if (res.ok) {
-                    // 204 no-content tolerance
                     if (res.status === 204)
                         return undefined;
                     return (await res.json());
                 }
-                if (isRetriableStatus(res.status) && attempt < this.maxRetries) {
-                    await sleep(backoffMs(attempt));
+                if (isRetriableStatus(res.status) && attempt < maxRetries) {
+                    const sleepMs = Math.min(backoffMs(attempt), deadlineAt != null ? Math.max(0, deadlineAt - Date.now() - 50) : Infinity);
+                    if (deadlineAt != null && sleepMs <= 0) {
+                        // No headroom for another attempt — fail now rather than
+                        // sleeping into a guaranteed deadline-exceeded outcome.
+                        throw new OHMTimeoutError({
+                            message: `Total request deadline (${totalDeadline}ms) would be exceeded by retry sleep`,
+                        });
+                    }
+                    await sleep(sleepMs);
                     continue;
                 }
                 throw await this.parseError(res);
             }
             catch (err) {
                 clearTimeout(t);
+                // Hooks first — even for errors we want to surface them to
+                // observability before we throw or retry.
+                const willRetryDecision = (() => {
+                    if (err instanceof OHMError)
+                        return false;
+                    if (options?.signal?.aborted)
+                        return false;
+                    const e = err;
+                    if (e?.name === "AbortError" || e?.code === "ABORT_ERR")
+                        return false;
+                    return attempt < maxRetries;
+                })();
+                safeHook(this.hooks?.onError, {
+                    method,
+                    url,
+                    attempt,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                    willRetry: willRetryDecision,
+                });
                 if (err instanceof OHMError)
                     throw err;
-                // If the caller cancelled, surface that immediately — don't
-                // burn retries on a request the user no longer wants.
                 if (options?.signal?.aborted) {
                     throw new OHMAbortError();
                 }
+                const e = err;
+                if (e?.name === "AbortError" || e?.code === "ABORT_ERR") {
+                    // Distinguish total-deadline timeout from per-attempt timeout
+                    // in the error message — easier triage in support tickets.
+                    const msg = deadlineAt != null && Date.now() >= deadlineAt
+                        ? `Total request deadline (${totalDeadline}ms) exceeded`
+                        : `Request timed out after ${attemptTimeout}ms`;
+                    throw new OHMTimeoutError({ message: msg });
+                }
                 lastError = err;
-                if (attempt < this.maxRetries) {
-                    await sleep(backoffMs(attempt));
+                if (attempt < maxRetries) {
+                    const sleepMs = Math.min(backoffMs(attempt), deadlineAt != null ? Math.max(0, deadlineAt - Date.now() - 50) : Infinity);
+                    if (deadlineAt != null && sleepMs <= 0) {
+                        throw new OHMTimeoutError({
+                            message: `Total request deadline (${totalDeadline}ms) would be exceeded by retry sleep`,
+                        });
+                    }
+                    await sleep(sleepMs);
                     continue;
                 }
             }
@@ -698,43 +972,109 @@ export class OHMCoreClient {
         }
         if (lastError instanceof OHMError)
             throw lastError;
-        throw new OHMServerError({
+        // After all retries exhausted, lastError is a transport-layer
+        // failure (DNS / TCP / TLS / dropped connection). Surface as
+        // OHMNetworkError so customers can pattern-match for "queue
+        // locally" behaviour.
+        throw new OHMNetworkError({
             message: lastError?.message || "Request failed after retries",
-            status: 0,
         });
     }
     async parseError(res) {
         let body = {};
+        let rawBody;
         try {
-            body = await res.json();
+            const text = await res.text();
+            rawBody = text;
+            if (text) {
+                try {
+                    const parsed = JSON.parse(text);
+                    body = parsed;
+                    rawBody = parsed;
+                }
+                catch {
+                    // body wasn't JSON; that's fine for the error path
+                }
+            }
         }
         catch {
-            // body wasn't JSON; that's fine for the error path
+            // body wasn't readable; that's fine for the error path
         }
+        // Capture headers as a plain dict so customers can `console.log` or
+        // forward to their telemetry without dragging a Headers instance.
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key.toLowerCase()] = value;
+        });
         const requestId = res.headers.get("x-request-id") || res.headers.get("x-ohm-request-id") || undefined;
         const message = body?.message || `HTTP ${res.status}`;
+        const base = {
+            message,
+            status: res.status,
+            requestId,
+            responseHeaders,
+            responseBody: rawBody,
+        };
+        // 401 / 403 → auth
         if (res.status === 401 || res.status === 403) {
-            return new OHMAuthError({ message, status: res.status, requestId });
+            return new OHMAuthError(base);
         }
+        // 404 → not found (slug, job id, …). Server may include
+        // `availableSlugs` to power a customer-side picker.
+        if (res.status === 404) {
+            return new OHMNotFoundError({
+                ...base,
+                availableSlugs: body?.availableSlugs,
+            });
+        }
+        // 422 / 400 → validation. Server provides a `fields[]` array of
+        // failing JSON-Schema paths.
         if (res.status === 422 || res.status === 400) {
             return new OHMValidationError({
-                message,
-                status: res.status,
-                requestId,
+                ...base,
                 fields: body?.fields,
             });
         }
+        // 429 → rate limit. Distinct from the org-wide quota class; this
+        // is per-key rate limiting that resets every minute.
         if (res.status === 429) {
+            // Some providers signal quota exhaustion via 429 with a body
+            // marker. When the server explicitly tags it as a quota issue,
+            // surface it as the more specific class so customers can show
+            // an upgrade-plan modal instead of a "slow down" toast.
+            if (body?.code === "quota_exceeded" || body?.errorCode === "quota_exceeded") {
+                return new OHMQuotaExceededError({
+                    ...base,
+                    resetAt: body?.resetAt,
+                    quotaKind: body?.quotaKind,
+                });
+            }
             return new OHMRateLimitError({
-                message,
-                status: res.status,
-                requestId,
+                ...base,
                 retryAfterSec: Number(res.headers.get("retry-after")) ||
                     body?.retryAfterSec ||
                     undefined,
             });
         }
-        return new OHMServerError({ message, status: res.status, requestId });
+        // 402 → payment required (Stripe convention) → quota.
+        if (res.status === 402) {
+            return new OHMQuotaExceededError({
+                ...base,
+                resetAt: body?.resetAt,
+                quotaKind: body?.quotaKind,
+            });
+        }
+        // 504 / gateway timeout → timeout class so customers can pattern
+        // match for "give it another try" UX.
+        if (res.status === 504 || res.status === 408) {
+            return new OHMTimeoutError({
+                message,
+                status: res.status,
+                responseHeaders,
+                responseBody: rawBody,
+            });
+        }
+        return new OHMServerError(base);
     }
 }
 function sleep(ms) {