@flamai/finesse 0.0.0-stage → 0.1.1

package/dist/index.cjs

@@ -0,0 +1,1785 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIConnectionError: () => APIConnectionError,
+  APIStatusError: () => APIStatusError,
+  APITimeoutError: () => APITimeoutError,
+  AuthenticationError: () => AuthenticationError,
+  BadRequestError: () => BadRequestError,
+  CloneFailedError: () => CloneFailedError,
+  CloneTimeoutError: () => CloneTimeoutError,
+  ConflictError: () => ConflictError,
+  Finesse: () => Finesse,
+  FinesseError: () => FinesseError,
+  InternalServerError: () => InternalServerError,
+  NotFoundError: () => NotFoundError,
+  PayloadTooLargeError: () => PayloadTooLargeError,
+  PaymentRequiredError: () => PaymentRequiredError,
+  PermissionDeniedError: () => PermissionDeniedError,
+  RateLimitError: () => RateLimitError,
+  RealtimeContext: () => RealtimeContext,
+  RealtimeError: () => RealtimeError,
+  RealtimeSession: () => RealtimeSession,
+  SpeechStream: () => SpeechStream,
+  StreamError: () => StreamError,
+  UnprocessableEntityError: () => UnprocessableEntityError,
+  VERSION: () => VERSION,
+  VoicePage: () => VoicePage,
+  VoicePagePromise: () => VoicePagePromise,
+  fileFromPath: () => fileFromPath,
+  isReady: () => isReady
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FinesseError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var APIConnectionError = class extends FinesseError {
+};
+var APITimeoutError = class extends APIConnectionError {
+  constructor(options) {
+    super("Request timed out.", options);
+  }
+};
+var APIStatusError = class extends FinesseError {
+  /** HTTP status. */
+  status;
+  /** Machine-readable code. Branch on this, never on the message. Envelope codes:
+   * `invalid_request`, `unauthorized`, `key_expired`, `token_invalid`, `payment_required`,
+   * `forbidden`, `insufficient_scope`, `voice_not_allowed`, `not_found`, `conflict`,
+   * `idempotency_in_progress`, `payload_too_large`, `invalid_input`, `idempotency_key_reused`,
+   * `rate_limited`, `concurrency_limited`, `internal_error`, `upstream_error`, `upstream_busy`,
+   * `unavailable`; plan denials: `insufficient_credits`, `quota_exhausted`, `feature_disabled`,
+   * `plan_limit_reached`; realtime: `too_many_sessions`. `null` when absent. */
+  code;
+  /** The decoded JSON body, or the raw text when it is not JSON. */
+  body;
+  headers;
+  /** `X-Billing-Remaining` as a number, when sent. */
+  billingRemaining;
+  /** The service's `X-Request-Id` for the failed request; quote it to support. */
+  requestId;
+  constructor(status, message, body2, code, headers) {
+    super(code && code !== message ? `${status}: ${message} (${code})` : `${status}: ${message}`);
+    this.status = status;
+    this.code = code;
+    this.body = body2;
+    this.headers = headers;
+    this.billingRemaining = intOrNull(headers.get("x-billing-remaining"));
+    const fromBody = body2?.request_id;
+    this.requestId = headers.get("x-request-id") ?? (typeof fromBody === "string" ? fromBody : null);
+  }
+  /** Seconds the server asked you to wait (`Retry-After`), when it sent one. */
+  get retryAfter() {
+    const v = this.headers.get("retry-after");
+    if (v === null) return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  /** Plan limit from an entitlement or plan-limit denial, when present. */
+  get limit() {
+    return numberField(this.body, "limit");
+  }
+  /** Amount already used, from an entitlement denial, when present. */
+  get used() {
+    return numberField(this.body, "used");
+  }
+};
+var BadRequestError = class extends APIStatusError {
+};
+var AuthenticationError = class extends APIStatusError {
+};
+var PaymentRequiredError = class extends APIStatusError {
+};
+var PermissionDeniedError = class extends APIStatusError {
+  /** The capped feature for `plan_limit_reached`, e.g. `max_voices`. */
+  get feature() {
+    const b = this.body;
+    return b && typeof b === "object" && typeof b.feature === "string" ? b.feature : null;
+  }
+};
+var NotFoundError = class extends APIStatusError {
+};
+var ConflictError = class extends APIStatusError {
+};
+var PayloadTooLargeError = class extends APIStatusError {
+};
+var UnprocessableEntityError = class extends APIStatusError {
+};
+var RateLimitError = class extends APIStatusError {
+};
+var InternalServerError = class extends APIStatusError {
+};
+var StreamError = class extends FinesseError {
+  code;
+  constructor(code, message = "") {
+    super(message ? `${message} (${code})` : code);
+    this.code = code;
+  }
+};
+var CloneFailedError = class extends FinesseError {
+  job;
+  constructor(job) {
+    const reason = typeof job.error?.message === "string" ? `: ${job.error.message}` : "";
+    super(`Clone job ${job.id} ${job.status}${reason}`);
+    this.job = job;
+  }
+};
+var CloneTimeoutError = class extends FinesseError {
+  constructor(jobId, timeoutMs) {
+    super(`Clone job ${jobId} did not finish within ${timeoutMs / 1e3}s`);
+    this.jobId = jobId;
+    this.timeoutMs = timeoutMs;
+  }
+  jobId;
+  timeoutMs;
+};
+var MAX_MESSAGE = 300;
+var STATUS_ERRORS = {
+  400: BadRequestError,
+  401: AuthenticationError,
+  402: PaymentRequiredError,
+  403: PermissionDeniedError,
+  404: NotFoundError,
+  409: ConflictError,
+  413: PayloadTooLargeError,
+  422: UnprocessableEntityError,
+  429: RateLimitError
+};
+function makeStatusError(status, text, headers, statusText = "") {
+  let body2 = text;
+  try {
+    body2 = text ? JSON.parse(text) : text;
+  } catch {
+  }
+  let message = null;
+  let code = null;
+  if (body2 && typeof body2 === "object" && !Array.isArray(body2)) {
+    const b = body2;
+    if (typeof b.message === "string" && b.message) {
+      message = b.message;
+      if (/^[a-z]+(_[a-z]+)+$/.test(b.message)) code = b.message;
+    }
+    if (typeof b.code === "string" && b.code) {
+      if (!(status === 402 && b.message === "insufficient_credits")) code = b.code;
+    } else if (typeof b.error === "string" && b.error) {
+      code = b.error === "plan limit reached" ? "plan_limit_reached" : b.error;
+      message ??= b.error.replace(/_/g, " ");
+    } else if (b.error && typeof b.error === "object") {
+      const e = b.error;
+      if (typeof e.message === "string" && e.message) message = e.message;
+      if (typeof e.code === "string" && e.code) code = e.code;
+    }
+  } else if (typeof body2 === "string" && body2.trim()) {
+    const flat = body2.split(/\s+/).join(" ").trim();
+    message = flat.length <= MAX_MESSAGE ? flat : flat.slice(0, MAX_MESSAGE - 3) + "...";
+  }
+  message ||= statusText || `HTTP ${status}`;
+  const Cls = STATUS_ERRORS[status] ?? (status >= 500 ? InternalServerError : APIStatusError);
+  return new Cls(status, message, body2, code, headers);
+}
+function intOrNull(value) {
+  if (value === null) return null;
+  const n = Number(value);
+  return Number.isInteger(n) ? n : null;
+}
+function numberField(body2, key) {
+  if (body2 && typeof body2 === "object") {
+    const v = body2[key];
+    if (typeof v === "number") return v;
+  }
+  return null;
+}
+
+// src/version.ts
+var VERSION = "0.1.1";
+
+// src/core.ts
+var DEFAULT_BASE_URL = "https://fi.production.flamapis.com";
+var API_PREFIX = "/flam-voice-svc/api/v1/public";
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_MAX_RETRIES = 2;
+var CLIENT_NAME = `flam-finesse-node/${VERSION}`;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var POST_RETRY_STATUSES = /* @__PURE__ */ new Set([429, 502, 503]);
+var TOKEN_RETRY_STATUSES = /* @__PURE__ */ new Set([429]);
+var UNSENT_CODES = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
+var MAX_BACKOFF_MS = 8e3;
+function env(name) {
+  const proc = globalThis.process;
+  return proc?.env?.[name];
+}
+function isBrowser() {
+  return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+var Core = class {
+  apiKey;
+  accessToken;
+  baseURL;
+  timeout;
+  maxRetries;
+  headers;
+  fetch;
+  logLevel;
+  logger;
+  /** @internal What this client learned about the server; shared by `withOptions` copies. */
+  server = { honoursIdempotencyKeys: false };
+  /** @internal Called with each successful response (used by `withRawResponse`). */
+  onResponse = null;
+  constructor(options = {}) {
+    if (options.apiKey && options.accessToken) {
+      throw new FinesseError("Pass { apiKey } or { accessToken }, not both.");
+    }
+    const accessToken = options.accessToken || null;
+    const apiKey = accessToken ? null : options.apiKey ?? env("FINESSE_API_KEY") ?? null;
+    if (!accessToken && !apiKey) {
+      throw new FinesseError(
+        "No API key. Pass { apiKey } or set the FINESSE_API_KEY environment variable (or pass { accessToken } for a short-lived token)."
+      );
+    }
+    if (apiKey && isBrowser() && !options.dangerouslyAllowBrowser) {
+      throw new FinesseError(
+        "Running in a browser would expose your API key. Mint a short-lived token on your server (tokens.create) and pass { accessToken }, or pass { dangerouslyAllowBrowser: true } for internal tools."
+      );
+    }
+    this.apiKey = apiKey;
+    this.accessToken = accessToken;
+    this.baseURL = (options.baseURL || env("FINESSE_BASE_URL") || DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.headers = {
+      ...accessToken ? { Authorization: `Bearer ${accessToken}` } : { "X-API-Key": apiKey },
+      "X-Finesse-Client": CLIENT_NAME,
+      Accept: "application/json",
+      ...isBrowser() ? {} : { "User-Agent": CLIENT_NAME },
+      ...options.defaultHeaders
+    };
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f)
+      throw new FinesseError("No fetch available. Pass { fetch } (Node 18+ has one built in).");
+    this.fetch = f.bind(globalThis);
+    const level = options.logLevel ?? env("FINESSE_LOG")?.toLowerCase() ?? "off";
+    this.logLevel = level === "debug" || level === "info" ? level : "off";
+    this.logger = options.logger ?? console;
+  }
+  /** @internal A view of this core with other defaults, sharing everything else. */
+  withOptions(overrides) {
+    const view = Object.create(Object.getPrototypeOf(this));
+    Object.assign(view, this, {
+      timeout: overrides.timeout ?? this.timeout,
+      maxRetries: overrides.maxRetries ?? this.maxRetries,
+      headers: { ...this.headers, ...overrides.headers }
+    });
+    return view;
+  }
+  debug(message) {
+    if (this.logLevel === "debug") this.logger.debug(`[finesse] ${message}`);
+  }
+  info(message) {
+    if (this.logLevel !== "off") this.logger.info(`[finesse] ${message}`);
+  }
+  url(path, query) {
+    const url = new URL(`${this.baseURL}${API_PREFIX}${path}`);
+    for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, String(v));
+    return url.toString();
+  }
+  get wsBaseURL() {
+    return this.baseURL.replace(/^http(s?):\/\//, "ws$1://");
+  }
+  /** Send a request, retrying transient failures, and throw on an error status. With
+   * `stream: true` the caller owns the response body. A caller `signal` stops the request and
+   * any further retries, and rejects with the signal's reason. */
+  async request(method, path, opts = {}) {
+    const { signal } = opts;
+    const timeout = opts.timeout ?? this.timeout;
+    const maxRetries = opts.maxRetries ?? this.maxRetries;
+    const baseHeaders = { ...this.headers, ...opts.headers };
+    let key = null;
+    if (opts.idempotent && method === "POST") {
+      const own = Object.keys(baseHeaders).find((k) => k.toLowerCase() === "idempotency-key");
+      key = own ? baseHeaders[own] : randomUUID();
+      if (!own) baseHeaders["Idempotency-Key"] = key;
+    }
+    const retryAs = (response) => {
+      if (key === null) return method;
+      if (response?.headers.get("idempotency-key") === key)
+        this.server.honoursIdempotencyKeys = true;
+      return this.server.honoursIdempotencyKeys ? "GET" : method;
+    };
+    let inProgressUntil = null;
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(signal);
+      const headers = { ...baseHeaders };
+      let body2;
+      if (opts.json !== void 0) {
+        headers["Content-Type"] = "application/json";
+        body2 = JSON.stringify(opts.json);
+      } else if (opts.form) {
+        body2 = opts.form();
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new TimeoutSignal()), timeout);
+      const onAbort = () => controller.abort(signal?.reason);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const release = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const retryAfterError = async (err, sent) => {
+        throwIfAborted(signal);
+        const timedOut = controller.signal.reason instanceof TimeoutSignal;
+        const cautious = this.accessToken !== null || retryAs(null) === "POST";
+        const retry = !cautious || !sent && !timedOut && isUnsent(err);
+        if (attempt < maxRetries && retry) {
+          await sleep(retryDelay(attempt, null), signal);
+          return;
+        }
+        if (timedOut) throw new APITimeoutError({ cause: err });
+        throw new APIConnectionError(errorMessage(err), { cause: err });
+      };
+      const url = this.url(path, opts.query);
+      const where = `${method} ${url.split("?")[0]}`;
+      const started = Date.now();
+      let response;
+      try {
+        response = await this.fetch(url, {
+          method,
+          headers,
+          body: body2,
+          signal: controller.signal
+        });
+      } catch (err) {
+        release();
+        await retryAfterError(err, false);
+        this.info(`retrying ${where} (attempt ${attempt + 1} failed: ${errorMessage(err)})`);
+        continue;
+      }
+      retryAs(response);
+      this.debug(
+        `${where} -> ${response.status} in ${Date.now() - started} ms` + (attempt ? `, attempt ${attempt + 1}` : "") + ` (request id ${response.headers.get("x-request-id") ?? "-"})`
+      );
+      if (response.ok && opts.stream) {
+        clearTimeout(timer);
+        streamCleanups.set(response, () => signal?.removeEventListener("abort", onAbort));
+        this.onResponse?.(response);
+        return response;
+      }
+      let buffer;
+      try {
+        buffer = await response.arrayBuffer();
+      } catch (err) {
+        release();
+        await retryAfterError(err, true);
+        this.info(`retrying ${where} (attempt ${attempt + 1} failed: ${errorMessage(err)})`);
+        continue;
+      }
+      release();
+      if (response.ok) {
+        const empty = response.status === 204 || response.status === 205 || response.status === 304;
+        const buffered = new Response(empty ? null : buffer, {
+          status: response.status,
+          headers: response.headers
+        });
+        this.onResponse?.(buffered);
+        return buffered;
+      }
+      const text = new TextDecoder().decode(buffer);
+      if (key !== null && response.status === 409 && isInProgress(text)) {
+        inProgressUntil ??= Date.now() + timeout;
+        if (Date.now() < inProgressUntil) {
+          const delay = retryDelay(0, response);
+          this.info(`waiting for ${where}: the first attempt is still running`);
+          await sleep(delay, signal);
+          attempt--;
+          continue;
+        }
+      }
+      const statuses = this.accessToken !== null ? TOKEN_RETRY_STATUSES : retryAs(response) === "POST" ? POST_RETRY_STATUSES : RETRY_STATUSES;
+      if (attempt < maxRetries && statuses.has(response.status)) {
+        const delay = retryDelay(attempt, response);
+        this.info(
+          `retrying ${where} in ${Math.round(delay)} ms (attempt ${attempt + 1} failed: HTTP ${response.status})`
+        );
+        await sleep(delay, signal);
+        continue;
+      }
+      throw makeStatusError(response.status, text, response.headers, response.statusText);
+    }
+  }
+  /** Request and decode a JSON success body, stripping the `{status, error, data}` envelope. */
+  async json(method, path, opts = {}) {
+    const response = await this.request(method, path, opts);
+    return unwrap(await response.json());
+  }
+};
+var streamCleanups = /* @__PURE__ */ new WeakMap();
+function releaseStream(response) {
+  streamCleanups.get(response)?.();
+  streamCleanups.delete(response);
+}
+var TimeoutSignal = class extends Error {
+};
+function isInProgress(text) {
+  try {
+    return JSON.parse(text)?.code === "idempotency_in_progress";
+  } catch {
+    return false;
+  }
+}
+function randomUUID() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  const b = new Uint8Array(16);
+  if (c?.getRandomValues) c.getRandomValues(b);
+  else for (let i = 0; i < 16; i++) b[i] = Math.floor(Math.random() * 256);
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+function unwrap(body2) {
+  if (body2 && typeof body2 === "object" && "data" in body2 && body2.error === false) {
+    return body2.data;
+  }
+  return body2;
+}
+function isUnsent(err) {
+  let e = err;
+  for (let i = 0; i < 4 && e; i++) {
+    const code = e.code;
+    if (typeof code === "string" && UNSENT_CODES.has(code)) return true;
+    e = e.cause;
+  }
+  return false;
+}
+function errorMessage(err) {
+  const cause = err?.cause?.message;
+  return cause || (err instanceof Error ? err.message : "") || "Connection error.";
+}
+function retryDelay(attempt, response) {
+  const retryAfter = response?.headers.get("retry-after");
+  if (retryAfter) {
+    let ms = Number(retryAfter) * 1e3;
+    if (Number.isNaN(ms)) ms = Date.parse(retryAfter) - Date.now();
+    if (ms >= 0 && ms <= 6e4) return ms;
+  }
+  const base = Math.min(500 * 2 ** attempt, MAX_BACKOFF_MS);
+  return base * (1 - 0.25 * Math.random());
+}
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function sleep(ms, signal) {
+  throwIfAborted(signal);
+  if (!signal) return wait(ms);
+  let onAbort = () => void 0;
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    await Promise.race([wait(ms), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("This operation was aborted.", "AbortError");
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+function pathId(value) {
+  if (value === "" || value === "." || value === "..") {
+    throw new FinesseError(`Invalid id: ${JSON.stringify(value)}`);
+  }
+  return encodeURIComponent(value);
+}
+
+// src/raw.ts
+function rawClient(core, build) {
+  const namespace = (name) => new Proxy(
+    {},
+    {
+      get(_target, method) {
+        if (typeof method !== "string") return void 0;
+        if (method === "stream") {
+          throw new FinesseError(
+            "speech.stream has no raw form: read headers from the stream itself (stream.billingRemaining, stream.done) instead."
+          );
+        }
+        return async (...args) => {
+          const seen = [];
+          const view = core.withOptions({});
+          view.onResponse = (r) => seen.push(r);
+          const resource = build(view)[name];
+          const fn = resource[method];
+          if (typeof fn !== "function")
+            throw new FinesseError(`No method ${String(name)}.${method}`);
+          const data = await fn.apply(resource, args);
+          const response = seen[0];
+          if (!response) throw new FinesseError("This call made no HTTP request.");
+          return {
+            data,
+            response,
+            status: response.status,
+            headers: response.headers,
+            requestId: response.headers.get("x-request-id")
+          };
+        };
+      }
+    }
+  );
+  const names = Object.keys(build(core));
+  return Object.fromEntries(names.map((name) => [name, namespace(name)]));
+}
+
+// src/realtime.ts
+var DEFAULT_OPEN_TIMEOUT_MS = 6e4;
+var SUBPROTOCOL = "finesse.v1";
+var CLOSE_TIMEOUT_MS = 5e3;
+var MAX_FRAME_BYTES = 1 << 20;
+var RETRYABLE_CLOSES = /* @__PURE__ */ new Set([1001, 1006, 1011, 1012, 1013, 4429]);
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "upstream_closed",
+  "upstream_error",
+  "upstream_busy",
+  "upstream_unavailable",
+  "connection_lost",
+  "service_busy",
+  "stream_billing_error"
+]);
+var RealtimeError = class extends FinesseError {
+  /** Per context: `voice_not_found`, `voice_not_allowed` (the token is limited to other
+   * voices), `invalid_request` (a parameter out of range), a `task_failed` code. Whole session:
+   * `insufficient_credits`, `upstream_unavailable` (the engine could not be reached),
+   * `upstream_busy` (it is at capacity), `upstream_error`, `upstream_closed`,
+   * `connection_lost`, `token_spent`, ... */
+  code;
+  /** The context it applies to, or `null` for the whole session. */
+  contextId;
+  /** The WebSocket close code, when the socket closed. */
+  closeCode;
+  constructor(code, message = "", options = {}) {
+    super(message && message !== code ? `${message} (${code})` : code);
+    this.code = code;
+    this.contextId = options.contextId ?? null;
+    this.closeCode = options.closeCode ?? null;
+  }
+  /** Whether reconnecting and trying again can succeed. */
+  get retryable() {
+    return RETRYABLE_CODES.has(this.code) || this.closeCode !== null && RETRYABLE_CLOSES.has(this.closeCode);
+  }
+};
+function closeError(code, reason) {
+  const c = { closeCode: code };
+  if (code === 1e3) return null;
+  if (code === 1008) return new RealtimeError(reason || "policy_violation", reason, c);
+  if (code === 1009) return new RealtimeError("message_too_big", "A message was too large.", c);
+  if (code === 1011) return new RealtimeError(reason || "upstream_closed", reason, c);
+  if (code === 1013 && (reason === "upstream_busy" || reason === "upstream_unavailable")) {
+    return new RealtimeError(
+      reason,
+      reason === "upstream_busy" ? "The synthesis service is at capacity." : "The synthesis service could not be reached.",
+      c
+    );
+  }
+  if (code === 4401) {
+    return new RealtimeError(
+      "service_auth_failed",
+      "The service could not start the session (a problem on our side).",
+      c
+    );
+  }
+  if (code === 4429) {
+    return new RealtimeError(
+      "service_busy",
+      "The service is at its connection limit. Try again shortly.",
+      c
+    );
+  }
+  if (code === null || code === 1005 || code === 1006) {
+    return new RealtimeError("connection_lost", "The connection dropped.", { closeCode: 1006 });
+  }
+  if (code === 1001 || code === 1012 || code === 1013) {
+    return new RealtimeError(
+      "connection_lost",
+      "The service closed the connection (restart or overload).",
+      c
+    );
+  }
+  return new RealtimeError(reason || "connection_closed", reason, c);
+}
+var END = /* @__PURE__ */ Symbol("end");
+var KNOWN_EVENTS = /* @__PURE__ */ new Set(["task_started", "sentence_done", "task_done", "task_cancelled"]);
+var RealtimeContext = class {
+  constructor(session, options, id) {
+    this.session = session;
+    this.options = options;
+    this.id = id;
+  }
+  session;
+  options;
+  id;
+  cancelled = false;
+  sampleRate = null;
+  audioFormat = null;
+  /** @internal */
+  started = false;
+  /** @internal The socket this context runs on. */
+  socket = null;
+  /** @internal */
+  ended = false;
+  finished = false;
+  items = [];
+  waiter = null;
+  sending = Promise.resolve();
+  /** Send text. Text is billed per character as it is sent. Pass `{ finalize: true }` with the
+   * turn's last text (or call {@link finish}). */
+  send(text, options = {}) {
+    return this.serial(async () => {
+      if (this.cancelled) {
+        throw new RealtimeError("context_cancelled", "This context was cancelled.", {
+          contextId: this.id
+        });
+      }
+      if (this.finished) {
+        throw new RealtimeError("context_finished", "This context was already finalized.", {
+          contextId: this.id
+        });
+      }
+      const finalize = options.finalize ?? false;
+      if (!this.started) {
+        this.started = true;
+        try {
+          await this.session._start(this, text, finalize);
+        } catch (err) {
+          this.started = false;
+          throw err;
+        }
+      } else {
+        this.session._sendText({ type: "task_continue", context_id: this.id }, text, finalize);
+      }
+      if (finalize) this.finished = true;
+    });
+  }
+  /** No more text for this turn: speak what is buffered, then end the context. */
+  finish() {
+    return this.serial(async () => {
+      if (!this.started) {
+        throw new RealtimeError("context_not_started", "Send text before finishing.", {
+          contextId: this.id
+        });
+      }
+      if (!this.finished) {
+        this.session._send({ type: "task_continue", context_id: this.id, finalize: true });
+        this.finished = true;
+      }
+    });
+  }
+  /** Stop this context now. Audio still in flight for it is dropped; iterating it ends with
+   * `task_cancelled`. */
+  async cancel() {
+    if (this.ended || this.cancelled) return;
+    this.cancelled = true;
+    this.finished = true;
+    await this.serial(async () => {
+      if (!this.started) {
+        this._end();
+        return;
+      }
+      try {
+        this.session._send({ type: "task_cancel", context_id: this.id });
+      } catch {
+      }
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    for (; ; ) {
+      while (this.items.length === 0) {
+        await new Promise((resolve) => this.waiter = resolve);
+      }
+      const item = this.items.shift();
+      if (item === END) return;
+      if (item instanceof RealtimeError) throw item;
+      yield item;
+    }
+  }
+  /** Iterate only the PCM of this context. */
+  async *audio() {
+    for await (const event of this) if (event.type === "audio") yield event.pcm;
+  }
+  /** @internal */
+  _put(event) {
+    if (event.type === "task_started") {
+      this.sampleRate = typeof event.sample_rate === "number" ? event.sample_rate : null;
+      this.audioFormat = typeof event.audio_format === "string" ? event.audio_format : null;
+    }
+    this.push(event);
+    if (event.type === "task_done" || event.type === "task_cancelled") this._end();
+  }
+  /** @internal */
+  _fail(error) {
+    if (this.ended) return;
+    this.push(error);
+    this._end();
+  }
+  /** @internal */
+  _end() {
+    if (this.ended) return;
+    this.ended = true;
+    this.push(END);
+    this.session._forget(this);
+  }
+  push(item) {
+    this.items.push(item);
+    const w = this.waiter;
+    this.waiter = null;
+    w?.();
+  }
+  serial(fn) {
+    const run = this.sending.then(fn, fn);
+    this.sending = run.catch(() => void 0);
+    return run;
+  }
+};
+var OPEN = 1;
+function versions() {
+  return globalThis.process?.versions ?? {};
+}
+function globalDialer(headers) {
+  const G = globalThis.WebSocket;
+  if (!G) throw new FinesseError("No WebSocket implementation available.");
+  return {
+    headers,
+    // Bun's WebSocket takes headers as a second-argument option. A token session needs no
+    // headers, so it can use the standard protocols argument everywhere.
+    open: (url, h, _t, protocols) => protocols ? new G(url, protocols) : h ? new G(url, { headers: h }) : new G(url)
+  };
+}
+function denoHasHeaders(version) {
+  const [major = 0, minor = 0] = (version ?? "").split(".").map(Number);
+  return major > 2 || major === 2 && minor >= 5;
+}
+async function defaultDialer() {
+  if (isBrowser()) return globalDialer(false);
+  const v = versions();
+  if (v.bun) return globalDialer(true);
+  const deno = globalThis.Deno;
+  if (deno) return globalDialer(denoHasHeaders(deno.version?.deno));
+  if (!v.node) return globalDialer(false);
+  let mod;
+  try {
+    mod = await import("ws");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+      throw new FinesseError("Realtime in Node needs the `ws` package: npm install ws");
+    }
+    throw err;
+  }
+  const WS = mod.default ?? mod.WebSocket;
+  return {
+    headers: true,
+    open: (url, h, timeoutMs, protocols) => new WS(url, protocols, { headers: h, handshakeTimeout: timeoutMs })
+  };
+}
+var RealtimeSession = class {
+  constructor(core, options = {}) {
+    this.core = core;
+    this.options = options;
+    this.staticToken = options.accessToken ?? core.accessToken;
+  }
+  core;
+  options;
+  ws = null;
+  opening = null;
+  contexts = /* @__PURE__ */ new Map();
+  pendingAudio = null;
+  fatal = null;
+  error = null;
+  openedOnce = false;
+  closed = false;
+  closedWaiters = [];
+  staticToken;
+  tokenSpent = false;
+  get url() {
+    return `${this.core.wsBaseURL}${API_PREFIX}/stream`;
+  }
+  get isOpen() {
+    return this.ws !== null && this.ws.readyState === OPEN;
+  }
+  /**
+   * Open the socket (no-op when open). Throws `AuthenticationError`, `PaymentRequiredError` or
+   * `PermissionDeniedError` when the handshake is refused, `RateLimitError` with
+   * `code === "too_many_sessions"` when the workspace already has its maximum of sessions,
+   * and `APIConnectionError` / `APITimeoutError` when the service can't be reached.
+   */
+  open() {
+    if (this.isOpen) return Promise.resolve();
+    if (this.closed)
+      return Promise.reject(new RealtimeError("session_closed", "This session was closed."));
+    if (this.openedOnce && this.options.autoReconnect === false) {
+      return Promise.reject(
+        this.error ?? new RealtimeError("connection_closed", "The session is closed.")
+      );
+    }
+    this.opening ??= this.dial().finally(() => this.opening = null);
+    return this.opening;
+  }
+  /** Create a context. Nothing is sent until its first `send`. */
+  context(options) {
+    const { context_id, ...rest } = options;
+    const opts = { output_format: "s16le" };
+    for (const [k, v] of Object.entries(rest)) if (v !== void 0) opts[k] = v;
+    return new RealtimeContext(this, opts, context_id ?? randomId());
+  }
+  /** Speak `text` as one complete turn and yield its events. Breaking out of the loop cancels
+   * the turn. */
+  async *say(options) {
+    const { text, ...rest } = options;
+    const ctx = this.context(rest);
+    await ctx.send(text, { finalize: true });
+    try {
+      yield* ctx;
+    } finally {
+      if (!ctx.ended) await ctx.cancel();
+    }
+  }
+  /** End the session: tell the service, then close the socket. */
+  async close() {
+    this.closed = true;
+    await this.opening?.catch(() => void 0);
+    const ws = this.ws;
+    if (ws && ws.readyState === OPEN) {
+      try {
+        ws.send(JSON.stringify({ type: "session_end" }));
+      } catch {
+      }
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, CLOSE_TIMEOUT_MS);
+        this.closedWaiters.push(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+    if (this.ws && this.ws.readyState <= OPEN) this.ws.close(1e3);
+  }
+  // -- internals --
+  /** @internal */
+  async _start(ctx, text, finalize) {
+    await this.open();
+    const live = this.contexts.get(ctx.id);
+    if (live && live !== ctx) {
+      throw new RealtimeError("context_already_exists", "A running context already uses this id.", {
+        contextId: ctx.id
+      });
+    }
+    this.contexts.set(ctx.id, ctx);
+    ctx.socket = this.ws;
+    try {
+      this._sendText({ type: "task_start", context_id: ctx.id, ...ctx.options }, text, finalize);
+    } catch (err) {
+      this.contexts.delete(ctx.id);
+      throw err;
+    }
+  }
+  /** @internal */
+  _send(msg) {
+    if (!this.ws || !this.isOpen) {
+      throw this.error ?? new RealtimeError("connection_closed", "The session is not open.");
+    }
+    this.ws.send(JSON.stringify(msg));
+  }
+  /** @internal Send a `task_start` / `task_continue` frame with `text`. Text that would make
+   * the frame larger than {@link MAX_FRAME_BYTES} is split across `task_continue` frames for
+   * the same context; only the last one carries `finalize`. */
+  _sendText(msg, text, finalize) {
+    const frame = { ...msg, text, finalize };
+    const json = JSON.stringify(frame);
+    if (json.length * 3 <= MAX_FRAME_BYTES || utf8Bytes(json) <= MAX_FRAME_BYTES) {
+      this._send(frame);
+      return;
+    }
+    const next = { type: "task_continue", context_id: msg.context_id };
+    const overhead = Math.max(
+      utf8Bytes(JSON.stringify({ ...msg, text: "", finalize: false })),
+      utf8Bytes(JSON.stringify({ ...next, text: "", finalize: false }))
+    );
+    const pieces = splitText(text, MAX_FRAME_BYTES - overhead);
+    pieces.forEach(
+      (piece, i) => this._send({
+        ...i ? next : msg,
+        text: piece,
+        finalize: finalize && i === pieces.length - 1
+      })
+    );
+  }
+  /** @internal */
+  _forget(ctx) {
+    if (this.contexts.get(ctx.id) === ctx) this.contexts.delete(ctx.id);
+  }
+  /** The token for the next handshake, or `null` to use the API key. A static token is used
+   * first; once a handshake has spent it, `getAccessToken` supplies one per reconnect. */
+  async nextToken() {
+    if (this.staticToken && !this.tokenSpent) return this.staticToken;
+    if (this.options.getAccessToken) {
+      const token = await this.options.getAccessToken();
+      if (typeof token !== "string" || !token) {
+        throw new FinesseError("getAccessToken must return a non-empty token string.");
+      }
+      return token;
+    }
+    if (this.staticToken) {
+      throw new RealtimeError(
+        "token_spent",
+        "This session's access token was used by an earlier connection. Pass { getAccessToken } so a reconnect can fetch a fresh one."
+      );
+    }
+    return null;
+  }
+  async dial() {
+    const timeout = this.options.openTimeout ?? DEFAULT_OPEN_TIMEOUT_MS;
+    const custom = this.options.WebSocket;
+    const dialer = custom ? {
+      headers: !isBrowser(),
+      open: (url2, h, t, protocols2) => h ? new custom(url2, protocols2, { headers: h, handshakeTimeout: t }) : new custom(url2, protocols2)
+    } : await defaultDialer();
+    const token = await this.nextToken();
+    const protocols = token ? [SUBPROTOCOL, token] : void 0;
+    let url = this.url;
+    let headers = null;
+    if (token) {
+      if (dialer.headers) {
+        headers = { ...this.core.headers };
+        delete headers.Accept;
+        delete headers["X-API-Key"];
+        delete headers.Authorization;
+      }
+      const u = new URL(url);
+      u.searchParams.set("client", this.core.headers["X-Finesse-Client"] ?? "");
+      url = u.toString();
+    } else if (dialer.headers) {
+      headers = { ...this.core.headers };
+      delete headers.Accept;
+    } else {
+      if (this.core.logLevel !== "off") warnQueryKey(this.core.logger);
+      const u = new URL(url);
+      u.searchParams.set("api_key", this.core.apiKey ?? "");
+      u.searchParams.set("client", this.core.headers["X-Finesse-Client"] ?? "");
+      url = u.toString();
+    }
+    const ws = dialer.open(url, headers, timeout, protocols);
+    ws.binaryType = "arraybuffer";
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const done = (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (err) {
+          ws.onopen = ws.onclose = null;
+          ws.onerror = () => void 0;
+          try {
+            ws.close();
+          } catch {
+          }
+          reject(err);
+        } else resolve();
+      };
+      const timer = setTimeout(() => done(new APITimeoutError()), timeout);
+      ws.on?.("unexpected-response", (_req, res) => {
+        readResponse(res).then(
+          ({ status, text, headers: headers2 }) => done(makeStatusError(status, text, headers2)),
+          () => done(new APIConnectionError("The service refused the connection."))
+        );
+      });
+      ws.onopen = () => done();
+      let lastError = "";
+      ws.onerror = (ev) => {
+        const e = ev;
+        lastError = e?.error?.message || e?.message || "";
+        setTimeout(() => done(new APIConnectionError(lastError || "Connection error.")), 0);
+      };
+      ws.onclose = (ev) => done(new APIConnectionError(lastError || `Connection closed (${ev.code}).`));
+    });
+    if (this.closed) {
+      ws.close(1e3);
+      throw new RealtimeError("session_closed", "This session was closed.");
+    }
+    if (token && token === this.staticToken) this.tokenSpent = true;
+    this.ws = ws;
+    this.pendingAudio = null;
+    this.fatal = null;
+    this.error = null;
+    this.openedOnce = true;
+    ws.onerror = () => void 0;
+    ws.onmessage = (ev) => {
+      if (this.ws !== ws) return;
+      try {
+        if (typeof ev.data === "string") this.onMessage(ev.data);
+        else this.onAudio(toBytes(ev.data));
+      } catch {
+      }
+    };
+    ws.onclose = (ev) => this.onClose(ws, ev.code, ev.reason);
+  }
+  onClose(ws, code, reason) {
+    if (this.ws !== null && this.ws !== ws) {
+      const err = closeError(code, reason ?? "") ?? new RealtimeError("connection_closed");
+      for (const ctx of [...this.contexts.values()]) if (ctx.socket === ws) ctx._fail(err);
+      return;
+    }
+    this.ws = null;
+    let error = this.fatal;
+    if (error) error.closeCode ??= code;
+    else error = closeError(code, reason ?? "");
+    if (!error && this.contexts.size) {
+      error = new RealtimeError("connection_closed", "The session ended.", { closeCode: code });
+    }
+    this.error = error;
+    for (const ctx of [...this.contexts.values()]) {
+      ctx._fail(error ?? new RealtimeError("connection_closed"));
+    }
+    for (const w of this.closedWaiters.splice(0)) w();
+  }
+  onAudio(frame) {
+    const header = this.pendingAudio;
+    this.pendingAudio = null;
+    if (!header) return;
+    const ctx = this.contexts.get(String(header.context_id));
+    if (!ctx || ctx.cancelled) return;
+    ctx._put({
+      type: "audio",
+      context_id: ctx.id,
+      pcm: frame,
+      sample_rate: ctx.sampleRate,
+      audio_format: ctx.audioFormat,
+      ...numbers(header, ["sentence_index", "chunk_index", "audio_duration_s"])
+    });
+  }
+  onMessage(frame) {
+    let data;
+    try {
+      data = JSON.parse(frame);
+    } catch {
+      return;
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data)) return;
+    const d = data;
+    const kind = d.type;
+    if (kind === "audio_chunk") {
+      this.pendingAudio = d;
+      return;
+    }
+    const cid = typeof d.context_id === "string" ? d.context_id : null;
+    const ctx = cid ? this.contexts.get(cid) : void 0;
+    if (kind === "error") {
+      const err = new RealtimeError(String(d.code || "error"), String(d.message ?? ""), {
+        contextId: cid
+      });
+      if (d.fatal) this.fatal ??= err;
+      else ctx?._fail(err);
+      return;
+    }
+    if (kind === "session_ended") {
+      this.fatal ??= new RealtimeError("session_ended", String(d.reason || "The session ended."));
+      return;
+    }
+    if (!ctx || typeof kind !== "string") return;
+    if (kind === "task_failed") {
+      ctx._fail(
+        new RealtimeError(String(d.code || "task_failed"), String(d.message ?? ""), {
+          contextId: ctx.id
+        })
+      );
+      return;
+    }
+    ctx._put(
+      KNOWN_EVENTS.has(kind) ? { ...d, type: kind, context_id: ctx.id } : { type: "unknown", context_id: ctx.id, event_type: kind, data: d }
+    );
+  }
+};
+var Realtime = class {
+  constructor(core) {
+    this.core = core;
+  }
+  core;
+  /** Open a session. */
+  async connect(options = {}) {
+    const session = new RealtimeSession(this.core, options);
+    await session.open();
+    return session;
+  }
+  /** Create a session without opening it; it opens on first use. */
+  session(options = {}) {
+    return new RealtimeSession(this.core, options);
+  }
+};
+var warnedLoggers = /* @__PURE__ */ new WeakSet();
+function warnQueryKey(logger) {
+  if (warnedLoggers.has(logger)) return;
+  warnedLoggers.add(logger);
+  logger.info(
+    "[finesse] This runtime cannot send WebSocket headers, so the API key goes in the URL (?api_key=), which the service has deprecated. Mint a short-lived token on your server (tokens.create) and connect with { accessToken } or { getAccessToken } instead."
+  );
+}
+function utf8Bytes(s) {
+  return new TextEncoder().encode(s).length;
+}
+function splitText(text, budget) {
+  const pieces = [];
+  let start = 0;
+  let size = 0;
+  for (let i = 0; i < text.length; ) {
+    const c = text.charCodeAt(i);
+    const pair = c >= 55296 && c <= 56319 && (text.charCodeAt(i + 1) & 64512) === 56320 ? 2 : 1;
+    const bytes = pair === 2 ? 4 : escapedBytes(c);
+    if (size + bytes > budget && i > start) {
+      pieces.push(text.slice(start, i));
+      start = i;
+      size = 0;
+    }
+    size += bytes;
+    i += pair;
+  }
+  pieces.push(text.slice(start));
+  return pieces;
+}
+function escapedBytes(c) {
+  if (c === 34 || c === 92) return 2;
+  if (c < 32) return c === 8 || c === 9 || c === 10 || c === 12 || c === 13 ? 2 : 6;
+  if (c < 128) return 1;
+  if (c < 2048) return 2;
+  if (c >= 55296 && c <= 57343) return 6;
+  return 3;
+}
+function randomId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID().replace(/-/g, "");
+  const bytes = new Uint8Array(16);
+  if (c?.getRandomValues) c.getRandomValues(bytes);
+  else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toBytes(data) {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data))
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (Array.isArray(data)) {
+    const parts = data.map(toBytes);
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+      out.set(p, o);
+      o += p.length;
+    }
+    return out;
+  }
+  throw new TypeError("unexpected frame");
+}
+function numbers(obj, keys) {
+  const out = {};
+  for (const k of keys) if (typeof obj[k] === "number") out[k] = obj[k];
+  return out;
+}
+async function readResponse(res) {
+  const r = res;
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(r.headers)) {
+    if (v !== void 0) headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+  }
+  const chunks = [];
+  await new Promise((resolve, reject) => {
+    r.on("data", (c) => chunks.push(c));
+    r.on("end", () => resolve());
+    r.on("error", (e) => reject(e));
+  });
+  const text = new TextDecoder().decode(toBytes(chunks));
+  return { status: r.statusCode, text, headers };
+}
+
+// src/resources/jobs.ts
+var DEFAULT_WAIT_TIMEOUT_MS = 3e5;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var FINISHED = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled", "expired"]);
+var Jobs = class {
+  constructor(core) {
+    this.core = core;
+  }
+  core;
+  get(jobId, options = {}) {
+    return this.core.json("GET", `/jobs/${pathId(jobId)}`, options);
+  }
+  /** Poll until the job finishes and return it. Throws {@link CloneFailedError} if it ends
+   * `failed`, `cancelled` or `expired`, and {@link CloneTimeoutError} on timeout. */
+  async wait(jobId, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const interval = options.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeout;
+    for (; ; ) {
+      const job = await this.get(jobId, { signal: options.signal });
+      options.onUpdate?.(job);
+      if (FINISHED.has(job.status)) {
+        if (job.status !== "succeeded") throw new CloneFailedError(job);
+        return job;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw new CloneTimeoutError(jobId, timeout);
+      await sleep(Math.min(interval, remaining), options.signal);
+    }
+  }
+};
+
+// src/sse.ts
+async function* iterSSE(body2, idleTimeoutMs) {
+  const decoder = new TextDecoder();
+  const reader = body2.getReader();
+  let buffer = "";
+  let event = null;
+  let data = [];
+  function* feed(line) {
+    if (line.endsWith("\r")) line = line.slice(0, -1);
+    if (line === "") {
+      if (data.length || event !== null) yield { event: event ?? "message", data: data.join("\n") };
+      event = null;
+      data = [];
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const i = line.indexOf(":");
+    const field = i === -1 ? line : line.slice(0, i);
+    let value = i === -1 ? "" : line.slice(i + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  }
+  try {
+    for (; ; ) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new APITimeoutError()), idleTimeoutMs);
+      });
+      let result;
+      try {
+        result = await Promise.race([reader.read(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      const { done, value } = result;
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        yield* feed(line);
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer) yield* feed(buffer);
+    yield* feed("");
+  } finally {
+    await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+}
+
+// src/resources/speech.ts
+function body(params) {
+  const { voice_id: _ignored, ...rest } = params;
+  return Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== void 0));
+}
+function intHeader(headers, name) {
+  const v = headers.get(name);
+  if (v === null) return null;
+  const n = Number(v);
+  return Number.isInteger(n) ? n : null;
+}
+function base64ToBytes(b64) {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64) || b64.length % 4 === 1) {
+    throw new StreamError("bad_chunk", "The stream sent an undecodable audio chunk.");
+  }
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+var SpeechStream = class {
+  constructor(core, path, json, options = {}) {
+    this.core = core;
+    this.path = path;
+    this.json = json;
+    this.options = options;
+  }
+  core;
+  path;
+  json;
+  options;
+  sampleRate = null;
+  audioFormat = null;
+  /** Final event (duration, generation id, stored clip URL), once the stream finished. */
+  done = null;
+  billingRemaining = null;
+  consumed = false;
+  async *[Symbol.asyncIterator]() {
+    if (this.consumed) throw new FinesseError("This stream was already consumed; start a new one.");
+    this.consumed = true;
+    const response = await this.core.request("POST", this.path, {
+      ...this.options,
+      json: this.json,
+      stream: true
+    });
+    this.billingRemaining = intHeader(response.headers, "x-billing-remaining");
+    try {
+      if (!response.body) throw new StreamError("stream_incomplete", "The response had no body.");
+      const idle = this.options.timeout ?? this.core.timeout;
+      for await (const ev of iterSSE(response.body, idle)) {
+        const chunk = this.handle(ev.event, ev.data);
+        if (chunk) yield chunk;
+      }
+      if (!this.done) {
+        throw new StreamError("stream_incomplete", "The stream ended before it finished.");
+      }
+    } catch (err) {
+      throwIfAborted(this.options.signal);
+      if (err instanceof FinesseError) throw err;
+      throw new APIConnectionError(
+        err instanceof Error ? err.message : "The stream was interrupted.",
+        { cause: err }
+      );
+    } finally {
+      releaseStream(response);
+    }
+  }
+  /** Consume the stream and return all PCM joined together. */
+  async readAll() {
+    const parts = [];
+    for await (const chunk of this) parts.push(chunk.pcm);
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const p of parts) {
+      out.set(p, offset);
+      offset += p.length;
+    }
+    return out;
+  }
+  handle(event, data) {
+    let payload;
+    try {
+      payload = data ? JSON.parse(data) : {};
+    } catch {
+      return null;
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+    const p = payload;
+    const kind = typeof p.type === "string" && p.type || event;
+    if (kind === "start") {
+      if (typeof p.sample_rate === "number") this.sampleRate = p.sample_rate;
+      if (typeof p.audio_format === "string") this.audioFormat = p.audio_format;
+    } else if (kind === "chunk") {
+      return {
+        pcm: base64ToBytes(typeof p.audio_b64 === "string" ? p.audio_b64 : ""),
+        sampleRate: typeof p.sample_rate === "number" ? p.sample_rate : this.sampleRate,
+        audioFormat: typeof p.audio_format === "string" ? p.audio_format : this.audioFormat,
+        index: typeof p.index === "number" ? p.index : null
+      };
+    } else if (kind === "done") {
+      this.done = p;
+    } else if (kind === "error") {
+      throw new StreamError(
+        typeof p.code === "string" && p.code ? p.code : "stream_error",
+        typeof p.message === "string" ? p.message : ""
+      );
+    }
+    return null;
+  }
+};
+var Speech = class {
+  constructor(core) {
+    this.core = core;
+  }
+  core;
+  /** Synthesize `text` and return the whole clip (`wav` unless `output_format` says otherwise). */
+  async create(params, options = {}) {
+    const response = await this.core.request("POST", `/voices/${pathId(params.voice_id)}/speak`, {
+      ...options,
+      idempotent: true,
+      json: body(params)
+    });
+    const h = response.headers;
+    return {
+      data: new Uint8Array(await response.arrayBuffer()),
+      contentType: h.get("content-type") ?? "audio/wav",
+      sampleRate: intHeader(h, "x-sample-rate"),
+      generationId: h.get("x-generation-id") || null,
+      audioURL: h.get("x-audio-url") || null,
+      billingRemaining: intHeader(h, "x-billing-remaining")
+    };
+  }
+  /** Stream speech as raw PCM chunks (`s16le` unless `output_format` says otherwise):
+   *
+   * ```ts
+   * for await (const chunk of client.speech.stream({ voice_id, text: "Hello" })) play(chunk.pcm);
+   * ```
+   */
+  stream(params, options = {}) {
+    return new SpeechStream(
+      this.core,
+      `/voices/${pathId(params.voice_id)}/stream`,
+      body(params),
+      options
+    );
+  }
+};
+
+// src/resources/tokens.ts
+var Tokens = class {
+  constructor(core) {
+    this.core = core;
+  }
+  core;
+  /** Mint a single-use token. Call this on your server with an API key that has the `tts`
+   * scope, and send only the token to the client:
+   *
+   * ```ts
+   * const { token } = await client.tokens.create({ ttl_seconds: 60, voice_ids: [voiceId] });
+   * ```
+   */
+  async create(params = {}, options = {}) {
+    const json = {};
+    if (params.ttl_seconds !== void 0) json.ttl_seconds = params.ttl_seconds;
+    if (params.voice_ids !== void 0) json.voice_ids = params.voice_ids;
+    return this.core.json("POST", "/tokens", { ...options, json });
+  }
+};
+
+// src/files.ts
+var TYPES = {
+  wav: "audio/wav",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+  webm: "audio/webm"
+};
+function guessType(name) {
+  return TYPES[name.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
+}
+function toBlob(file) {
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    const name = file.name;
+    return { blob: file, filename: typeof name === "string" && name ? name : "audio.wav" };
+  }
+  if (file instanceof Uint8Array || file instanceof ArrayBuffer) {
+    return { blob: new Blob([file]), filename: "audio.wav" };
+  }
+  const { data, filename = "audio.wav" } = file;
+  const contentType = file.contentType ?? guessType(filename);
+  const blob = data instanceof Blob && data.type ? data : new Blob([data], { type: contentType });
+  return { blob, filename };
+}
+async function fileFromPath(path) {
+  const { readFile } = await import("fs/promises");
+  const { basename } = await import("path");
+  const data = await readFile(path);
+  const filename = basename(path);
+  return { data: new Uint8Array(data), filename, contentType: guessType(filename) };
+}
+
+// src/types.ts
+function toVoice(raw) {
+  const v = { ...raw };
+  const labels = v.labels;
+  if (Array.isArray(labels)) {
+    const map = {};
+    for (const item of labels) {
+      if (item && typeof item === "object" && "key" in item) {
+        map[String(item.key)] = String(
+          item.value ?? ""
+        );
+      }
+    }
+    v.labels = map;
+  } else if (!labels || typeof labels !== "object") {
+    v.labels = {};
+  }
+  return v;
+}
+var isReady = (voice) => voice.status === "ready";
+
+// src/resources/voices.ts
+var VoicePage = class {
+  constructor(data, fetchPage) {
+    this.fetchPage = fetchPage;
+    this.voices = (data.voices ?? []).map(toVoice);
+    this.page = Number(data.page ?? 1);
+    this.page_size = Number(data.page_size ?? this.voices.length);
+    this.total = Number(data.total ?? this.voices.length);
+    this.has_more = Boolean(data.has_more);
+  }
+  fetchPage;
+  voices;
+  page;
+  page_size;
+  total;
+  has_more;
+  nextPage() {
+    return this.fetchPage(this.page + 1);
+  }
+  async *iterPages() {
+    let page = this;
+    for (; ; ) {
+      yield page;
+      if (!page.has_more || page.voices.length === 0) return;
+      page = await page.nextPage();
+    }
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.iterPages()) yield* page.voices;
+  }
+};
+function consent(params) {
+  if (params.consent !== true) {
+    throw new FinesseError(
+      "Cloning requires consent: true: you attest that you are the speaker or hold their explicit permission to clone their voice."
+    );
+  }
+  return "true";
+}
+function defined(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+function form(fields, file) {
+  const { blob, filename } = toBlob(file);
+  return () => {
+    const fd = new FormData();
+    for (const [k, v] of Object.entries(fields)) if (v !== void 0) fd.append(k, v);
+    fd.append("file", blob, filename);
+    return fd;
+  };
+}
+var VoicePagePromise = class {
+  constructor(load) {
+    this.load = load;
+  }
+  load;
+  first = null;
+  page() {
+    return this.first ??= this.load();
+  }
+  then(onfulfilled, onrejected) {
+    return this.page().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.page().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.page().finally(onfinally);
+  }
+  async *[Symbol.asyncIterator]() {
+    yield* await this.page();
+  }
+};
+var Voices = class {
+  constructor(core, jobs) {
+    this.core = core;
+    this.jobs = jobs;
+  }
+  core;
+  jobs;
+  /** Your voices (newest first), then the public platform voices.
+   * `for await (const voice of client.voices.list())` walks every page;
+   * `await client.voices.list()` returns just the first page. */
+  list(params = {}, options = {}) {
+    const pageSize = params.page_size ?? 50;
+    const fetchPage = async (page) => {
+      const data = await this.core.json("GET", "/voices", {
+        ...options,
+        query: { page, page_size: pageSize }
+      });
+      return new VoicePage(data, fetchPage);
+    };
+    return new VoicePagePromise(() => fetchPage(params.page ?? 1));
+  }
+  /** One of your voices or a public platform voice. */
+  async get(voiceId, options = {}) {
+    return toVoice(await this.core.json("GET", `/voices/${pathId(voiceId)}`, options));
+  }
+  /** Create an empty `draft` voice. Give it a clip with {@link enroll}, or use {@link clone}. */
+  async create(params, options = {}) {
+    const json = defined({ ...params });
+    return toVoice(await this.core.json("POST", "/voices", { ...options, json, idempotent: true }));
+  }
+  /** Change a voice's metadata. Only the fields you pass change. */
+  async update(voiceId, params, options = {}) {
+    const json = defined({ ...params });
+    return toVoice(
+      await this.core.json("PATCH", `/voices/${pathId(voiceId)}`, { ...options, json })
+    );
+  }
+  /** Delete one of your voices. */
+  async delete(voiceId, options = {}) {
+    await this.core.request("DELETE", `/voices/${pathId(voiceId)}`, options);
+  }
+  /** Create a voice from a reference clip. Returns at once with the voice in `processing` and a
+   * `job_id`; see {@link waitUntilReady} or {@link cloneAndWait}. Requires `consent: true`. */
+  async clone(params, options = {}) {
+    const fields = {
+      consent: consent(params),
+      name: params.name,
+      description: params.description,
+      language: params.language,
+      ref_text: params.ref_text,
+      labels: params.labels ? JSON.stringify(params.labels) : void 0,
+      remove_background_noise: params.remove_background_noise === void 0 ? void 0 : String(params.remove_background_noise)
+    };
+    const result = await this.core.json("POST", "/voices/clone", {
+      ...options,
+      idempotent: true,
+      form: form(fields, params.file)
+    });
+    return { ...result, voice: toVoice(result.voice) };
+  }
+  /** Clone a reference clip into an existing voice of yours. Returns at once. Requires
+   * `consent: true`. */
+  async enroll(voiceId, params, options = {}) {
+    const fields = {
+      consent: consent(params),
+      ref_text: params.ref_text,
+      language: params.language
+    };
+    const result = await this.core.json("POST", `/voices/${pathId(voiceId)}/enroll`, {
+      ...options,
+      idempotent: true,
+      form: form(fields, params.file)
+    });
+    return { ...result, voice: toVoice(result.voice) };
+  }
+  /** Wait for a clone job to finish and return the voice, now `ready`. */
+  async waitUntilReady(clone, options = {}) {
+    await this.jobs.wait(clone.job_id, options);
+    return this.get(clone.voice.id, { signal: options.signal });
+  }
+  /** {@link clone}, then {@link waitUntilReady}. Returns the ready voice. */
+  async cloneAndWait(params, options = {}) {
+    return this.waitUntilReady(await this.clone(params), options);
+  }
+};
+
+// src/client.ts
+function resources(core) {
+  const jobs = new Jobs(core);
+  return {
+    jobs,
+    voices: new Voices(core, jobs),
+    speech: new Speech(core),
+    tokens: new Tokens(core)
+  };
+}
+var Finesse = class _Finesse {
+  voices;
+  jobs;
+  speech;
+  tokens;
+  realtime;
+  /** @internal */
+  _core;
+  constructor(options = {}) {
+    this._core = "_core" in options ? options._core : new Core(options);
+    const r = resources(this._core);
+    this.jobs = r.jobs;
+    this.voices = r.voices;
+    this.speech = r.speech;
+    this.tokens = r.tokens;
+    this.realtime = new Realtime(this._core);
+  }
+  get baseURL() {
+    return this._core.baseURL;
+  }
+  /** A copy of this client with different defaults. Cheap: it shares everything else. */
+  withOptions(options) {
+    return new _Finesse({
+      _core: this._core.withOptions({
+        timeout: options.timeout,
+        maxRetries: options.maxRetries,
+        headers: options.defaultHeaders
+      })
+    });
+  }
+  /** The same calls, each resolving to `{ data, response, status, headers, requestId }`:
+   *
+   * ```ts
+   * const { data: voice, requestId } = await client.withRawResponse.voices.get(id);
+   * ```
+   */
+  get withRawResponse() {
+    return rawClient(this._core, resources);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIConnectionError,
+  APIStatusError,
+  APITimeoutError,
+  AuthenticationError,
+  BadRequestError,
+  CloneFailedError,
+  CloneTimeoutError,
+  ConflictError,
+  Finesse,
+  FinesseError,
+  InternalServerError,
+  NotFoundError,
+  PayloadTooLargeError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  RateLimitError,
+  RealtimeContext,
+  RealtimeError,
+  RealtimeSession,
+  SpeechStream,
+  StreamError,
+  UnprocessableEntityError,
+  VERSION,
+  VoicePage,
+  VoicePagePromise,
+  fileFromPath,
+  isReady
+});
+//# sourceMappingURL=index.cjs.map