@flow-state-dev/voice-openai 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fixpoint Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @flow-state-dev/voice-openai
+
+OpenAI implementation of the `VoiceProvider` contract: batch text-to-speech, batch transcription, and the OpenAI voice catalog. Use it directly, or compose it with another provider via `createCompositeVoiceProvider`.
+
+`VoiceProvider` is the framework's single-object voice contract: one provider exposes some combination of `speak`, `speakStream`, `transcribe`, and `listVoices`, and declares which ones it supports via an `abilities` flags object. Callers branch on the flags (or the matching `canSpeak` / `canTranscribe` runtime type guards) instead of holding separate resolver objects per surface.
+
+## Installation
+
+```bash
+pnpm add @flow-state-dev/voice-openai openai
+```
+
+`openai` is a direct dependency of this package, not a peer — it ships with the package so you don't have to pin a compatible version yourself. You only need to install it explicitly if your app calls the SDK directly elsewhere.
+
+## Quick start
+
+```ts
+import { OpenAIVoiceProvider } from "@flow-state-dev/voice-openai";
+
+const provider = new OpenAIVoiceProvider({ apiKey: process.env.OPENAI_API_KEY });
+
+const { audio, mediaType } = await provider.speak({ text: "Hello, world." });
+// audio: Uint8Array (MP3 by default), mediaType: "audio/mpeg"
+```
+
+Pass it to your flow router via the M1 voice config; until the router migration lands you can still consume the provider directly in custom blocks.
+
+## Configuration
+
+```ts
+new OpenAIVoiceProvider({
+  apiKey:       process.env.OPENAI_API_KEY,
+  baseURL:      "https://my-proxy.example.com/v1", // optional
+  organization: "org-...",                          // optional
+  project:      "proj_...",                         // optional
+  ttsModel:     "gpt-4o-mini-tts",                 // default
+  sttModel:     "gpt-4o-mini-transcribe",          // default
+  voice:        "alloy",                            // default
+});
+```
+
+| Option | Purpose |
+| --- | --- |
+| `apiKey` | OpenAI API key. Omit to let the SDK read `OPENAI_API_KEY` from the environment. |
+| `baseURL` | Override the API endpoint. The SDK also reads `OPENAI_BASE_URL` from the environment when this is omitted. |
+| `organization` | OpenAI organization id, forwarded to the SDK. |
+| `project` | OpenAI project id, forwarded to the SDK. |
+| `ttsModel` | Default model for `speak()`. Caller-supplied `SpeakOptions.model` overrides per call. |
+| `sttModel` | Default model for `transcribe()`. Caller-supplied `TranscribeOptions.model` overrides per call. |
+| `voice` | Default voice id for `speak()`. Caller-supplied `SpeakOptions.voice` overrides per call. |
+| `client` | Escape hatch: supply a pre-configured `OpenAI` client. When set, the other client-config options (`apiKey`, `baseURL`, `organization`, `project`) are ignored. |
+
+## Abilities
+
+| Ability | Value | Notes |
+| --- | --- | --- |
+| `speak` | `true` | Batch TTS via `audio.speech.create`. |
+| `speakStream` | `false` | Not in scope for M1. OpenAI's SDK does support streaming via `stream_format`; expect a follow-up. For now, compose with another provider for streaming. |
+| `transcribe` | `true` | Batch STT via `audio.transcriptions.create`. |
+| `listVoices` | `true` | Static catalog; OpenAI does not expose a discovery endpoint. |
+
+## Voice catalog
+
+`listVoices()` returns a 13-entry static list:
+
+```
+alloy, ash, ballad, coral, echo, fable, nova, onyx,
+sage, shimmer, verse, marin, cedar
+```
+
+`marin` and `cedar` are only available on `gpt-4o-mini-tts`. They declare this via `supportedModels: ["gpt-4o-mini-tts"]`. Every other entry omits `supportedModels`, which by convention means "supported by every OpenAI TTS model" — there's no implicit allowlist to forget about.
+
+The catalog is hand-maintained. When OpenAI ships a new voice, update `src/voice-catalog.ts`.
+
+## Output formats
+
+`SpeakOptions.outputFormat` accepts six values; the returned `mediaType` follows OpenAI's encoding directly:
+
+| `outputFormat` | `mediaType` |
+| --- | --- |
+| `mp3` (default) | `audio/mpeg` |
+| `opus` | `audio/ogg; codecs=opus` |
+| `aac` | `audio/aac` |
+| `flac` | `audio/flac` |
+| `wav` | `audio/wav` |
+| `pcm` | `audio/pcm;rate=24000` |
+
+PCM output is raw 24 kHz 16-bit little-endian mono. Unsupported values throw `VoiceError({ kind: "format_unsupported" })` synchronously, before any network call.
+
+## Provider-specific options
+
+`SpeakOptions.providerOptions.openai.instructions` is forwarded as OpenAI's `instructions` parameter (style guidance like "speak slowly and warmly"). This field is only valid on `gpt-4o-mini-tts*` models. Passing it with `tts-1` / `tts-1-hd` throws `VoiceError({ kind: "invalid_input" })` at the provider boundary rather than wasting a 400 round-trip.
+
+## Error handling
+
+Every method translates SDK errors into `VoiceError`, a discriminated class with a `kind` field. Branch on `kind` and inspect `retryable` instead of parsing message strings:
+
+```ts
+import { VoiceError } from "@flow-state-dev/core";
+
+try {
+  await provider.speak({ text: "hello" });
+} catch (err) {
+  if (err instanceof VoiceError) {
+    if (err.kind === "rate_limit" && err.retryable) {
+      // back off and retry
+    } else if (err.kind === "auth") {
+      // surface to the operator
+    }
+  }
+}
+```
+
+Full mapping:
+
+| OpenAI SDK error | `VoiceError.kind` | `retryable` |
+| --- | --- | --- |
+| `APIUserAbortError` | `aborted` | `false` |
+| `AuthenticationError` (401) | `auth` | `false` |
+| `PermissionDeniedError` (403) | `auth` | `false` |
+| `RateLimitError` (429) | `rate_limit` | `true` |
+| `NotFoundError` (404) | `not_found` | `false` |
+| `BadRequestError` (400) — format signal | `format_unsupported` | `false` |
+| `BadRequestError` (400) — otherwise | `invalid_input` | `false` |
+| `UnprocessableEntityError` (422) | `invalid_input` (or `format_unsupported`) | `false` |
+| `InternalServerError` (≥500) | `provider_unavailable` | `true` |
+| `APIConnectionError` / `APIConnectionTimeoutError` | `network` | `true` |
+| `APIError` (other) | `unknown` | `false` |
+| Anything else | `unknown` | `false` |
+
+The "format signal" heuristic looks at `err.code`, `err.param`, and the message; bad-format 400s become `format_unsupported`, generic bad inputs stay `invalid_input`.
+
+## Composing with another provider
+
+```ts
+import { createCompositeVoiceProvider } from "@flow-state-dev/core";
+import { OpenAIVoiceProvider } from "@flow-state-dev/voice-openai";
+// import { ElevenLabsVoiceProvider } from "@flow-state-dev/voice-elevenlabs";
+
+const openai = new OpenAIVoiceProvider({ apiKey: process.env.OPENAI_API_KEY });
+
+const composite = createCompositeVoiceProvider({
+  // speak:      new ElevenLabsVoiceProvider({ ... }),  // streaming-capable provider
+  transcribe: openai,
+  listVoices: openai,
+});
+```
+
+Each ability slot can come from a different provider. Slots whose underlying provider doesn't advertise the matching ability show up as `false` in the composite's `abilities` rather than as a runtime failure.
+
+## What's not in M1
+
+- **Streaming TTS.** OpenAI's SDK supports it via `stream_format`, but the framework's pipeline doesn't need it from OpenAI yet, so the surface is left off the provider. ElevenLabs is the canonical streaming provider in M2.
+- **Custom-voice helpers.** The SDK accepts custom voice ids; the catalog lists OpenAI's prebuilt voices only. Pass a custom voice via `SpeakOptions.voice` if you need one.
+- **Realtime API.** Out of M1 scope.
+- **Live-API integration tests.** The unit tests mock the SDK at its boundary. Live-credentials tests live under `packages/integration-tests/` and arrive in a follow-up.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/** Public surface of `@flow-state-dev/voice-openai`. */
+export { OpenAIVoiceProvider } from "./openai-voice-provider";
+export type { OpenAIVoiceProviderOptions } from "./openai-voice-provider";
+export { OPENAI_VOICE_CATALOG } from "./voice-catalog";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+/** Public surface of `@flow-state-dev/voice-openai`. */
+export { OpenAIVoiceProvider } from "./openai-voice-provider";
+export { OPENAI_VOICE_CATALOG } from "./voice-catalog";
+//# sourceMappingURL=index.js.map

package/dist/openai-voice-provider.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `OpenAIVoiceProvider`: implements the `VoiceProvider` contract against the
+ * official `openai` SDK. Exposes batch `speak`, batch `transcribe`, and a
+ * static `listVoices` catalog. `speakStream` is intentionally absent —
+ * `abilities.speakStream === false`.
+ */
+import OpenAI from "openai";
+import type { SpeakOptions, SpeakResult, TranscribeOptions, TranscribeResult, VoiceAbilities, VoiceInfo, VoiceProvider } from "@flow-state-dev/core";
+/** Constructor options for {@link OpenAIVoiceProvider}. */
+export interface OpenAIVoiceProviderOptions {
+    /**
+     * OpenAI API key. Omit to fall back to the SDK's default behaviour, which
+     * reads `OPENAI_API_KEY` from the environment.
+     */
+    apiKey?: string;
+    /** Override the API base URL (Azure-OpenAI compatible endpoints, proxies). */
+    baseURL?: string;
+    /** OpenAI organization id, forwarded to the SDK. */
+    organization?: string;
+    /** OpenAI project id, forwarded to the SDK. */
+    project?: string;
+    /** Default TTS model for `speak()`. Defaults to `"gpt-4o-mini-tts"`. */
+    ttsModel?: string;
+    /** Default STT model for `transcribe()`. Defaults to `"gpt-4o-mini-transcribe"`. */
+    sttModel?: string;
+    /** Default voice for `speak()`. Defaults to `"alloy"`. */
+    voice?: string;
+    /**
+     * Escape hatch: supply a pre-configured `OpenAI` client. When set, all
+     * other client-configuration options (`apiKey`, `baseURL`, `organization`,
+     * `project`) are ignored — the caller owns the client.
+     */
+    client?: OpenAI;
+}
+/**
+ * OpenAI-backed `VoiceProvider`. Single-instance, reusable across requests;
+ * the underlying SDK client is shared, so HTTP-keep-alive and per-instance
+ * options (org, project) are honoured for the instance's lifetime.
+ */
+export declare class OpenAIVoiceProvider implements VoiceProvider {
+    readonly providerName = "openai";
+    readonly id: string;
+    readonly abilities: VoiceAbilities;
+    readonly defaultModels: {
+        speak: string;
+        transcribe: string;
+    };
+    private readonly client;
+    private readonly defaultVoice;
+    constructor(opts?: OpenAIVoiceProviderOptions);
+    speak(o: SpeakOptions): Promise<SpeakResult>;
+    transcribe(o: TranscribeOptions): Promise<TranscribeResult>;
+    listVoices(): Promise<VoiceInfo[]>;
+}
+//# sourceMappingURL=openai-voice-provider.d.ts.map

package/dist/openai-voice-provider.js

@@ -0,0 +1,182 @@
+/**
+ * `OpenAIVoiceProvider`: implements the `VoiceProvider` contract against the
+ * official `openai` SDK. Exposes batch `speak`, batch `transcribe`, and a
+ * static `listVoices` catalog. `speakStream` is intentionally absent —
+ * `abilities.speakStream === false`.
+ */
+import { createHash } from "node:crypto";
+import OpenAI, { toFile } from "openai";
+import { VoiceError } from "@flow-state-dev/core";
+import { mapOutputFormat, mediaTypeForFormat } from "./output-format";
+import { translateError } from "./translate-error";
+import { OPENAI_VOICE_CATALOG } from "./voice-catalog";
+/**
+ * OpenAI-backed `VoiceProvider`. Single-instance, reusable across requests;
+ * the underlying SDK client is shared, so HTTP-keep-alive and per-instance
+ * options (org, project) are honoured for the instance's lifetime.
+ */
+export class OpenAIVoiceProvider {
+    providerName = "openai";
+    id;
+    abilities = {
+        speak: true,
+        speakStream: false,
+        transcribe: true,
+        listVoices: true,
+    };
+    defaultModels;
+    client;
+    defaultVoice;
+    constructor(opts = {}) {
+        const ttsModel = opts.ttsModel ?? "gpt-4o-mini-tts";
+        const sttModel = opts.sttModel ?? "gpt-4o-mini-transcribe";
+        this.defaultModels = { speak: ttsModel, transcribe: sttModel };
+        this.defaultVoice = opts.voice ?? "alloy";
+        this.client =
+            opts.client ??
+                new OpenAI({
+                    apiKey: opts.apiKey,
+                    baseURL: opts.baseURL,
+                    organization: opts.organization,
+                    project: opts.project,
+                });
+        // Read identity fields from the resolved client so a caller-supplied
+        // `opts.client` contributes its own baseURL/org/project to the id
+        // instead of degenerating to all-`undefined`. Never include `apiKey`.
+        this.id = deriveId({
+            ttsModel,
+            sttModel,
+            voice: this.defaultVoice,
+            baseURL: this.client.baseURL,
+            organization: this.client.organization ?? undefined,
+            project: this.client.project ?? undefined,
+        });
+    }
+    async speak(o) {
+        const model = o.model ?? this.defaultModels.speak;
+        const voice = o.voice ?? this.defaultVoice;
+        const responseFormat = mapOutputFormat(o.outputFormat);
+        // `instructions` is rejected by OpenAI on the legacy `tts-1` / `tts-1-hd`
+        // models. Pre-validate at the boundary so callers get a typed error
+        // rather than a 400 round-trip.
+        const providerOpts = o.providerOptions?.openai;
+        const instructions = providerOpts?.instructions;
+        if (instructions !== undefined && (model === "tts-1" || model === "tts-1-hd")) {
+            throw new VoiceError({
+                kind: "invalid_input",
+                provider: "openai",
+                message: `instructions is not supported on legacy TTS models (tts-1, tts-1-hd); got model="${model}"`,
+            });
+        }
+        try {
+            const response = await this.client.audio.speech.create({
+                input: o.text,
+                model,
+                // The SDK's `voice` union is narrower than OpenAI's actual catalog
+                // (it lags new voices and never accepts custom voice ids). The
+                // catalog truth lives in `voice-catalog.ts`.
+                voice: voice,
+                response_format: responseFormat,
+                speed: o.speed,
+                instructions,
+            }, { signal: o.signal });
+            const audio = new Uint8Array(await response.arrayBuffer());
+            return { audio, mediaType: mediaTypeForFormat(responseFormat) };
+        }
+        catch (err) {
+            throw translateError(err);
+        }
+    }
+    async transcribe(o) {
+        const model = o.model ?? this.defaultModels.transcribe;
+        const file = await coerceUploadable(o.audio, o.mediaType);
+        try {
+            const result = await this.client.audio.transcriptions.create({
+                file,
+                model,
+                language: o.language,
+                response_format: "json",
+            }, { signal: o.signal });
+            // `json` always returns an object; the string overload only fires for
+            // `text` / `srt` / `vtt`. Handle both so the type assertion stays honest.
+            const text = typeof result === "string" ? result : result.text;
+            // OpenAI's `json` response doesn't echo a language field. Preserve the
+            // caller's hint so the result shape stays useful for downstream code.
+            return { text, language: o.language };
+        }
+        catch (err) {
+            throw translateError(err);
+        }
+    }
+    async listVoices() {
+        // Deep-copy entries: `supportedModels` is a mutable array on each entry,
+        // so a shallow spread would let callers mutate the module-global catalog.
+        return OPENAI_VOICE_CATALOG.map((v) => ({
+            ...v,
+            ...(v.supportedModels !== undefined
+                ? { supportedModels: [...v.supportedModels] }
+                : {}),
+        }));
+    }
+}
+/**
+ * Builds a stable, opaque `id` from the instance's defining configuration.
+ * Identical options produce identical ids across processes (useful for
+ * registry deduplication and structured logging). The API key is NEVER
+ * included so the id is safe to log.
+ */
+function deriveId(fields) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify(fields))
+        .digest("hex")
+        .slice(0, 12);
+    return `openai:${hash}`;
+}
+/**
+ * Normalizes `TranscribeOptions.audio` into something the SDK accepts as
+ * its `file` parameter. `Blob` passes through; `Uint8Array` is wrapped via
+ * `toFile()` with a filename whose extension matches `mediaType` so OpenAI
+ * can infer the audio format. `Uint8Array` without `mediaType` throws.
+ */
+async function coerceUploadable(audio, mediaType) {
+    if (audio instanceof Blob)
+        return audio;
+    if (mediaType === undefined) {
+        throw new VoiceError({
+            kind: "invalid_input",
+            provider: "openai",
+            message: "transcribe(audio: Uint8Array) requires mediaType — pass mediaType: 'audio/mpeg' (etc.) so OpenAI can infer the format.",
+        });
+    }
+    return toFile(audio, filenameForMediaType(mediaType), { type: mediaType });
+}
+/**
+ * Maps common audio MIME types to a filename with the matching extension.
+ * Unrecognized subtypes fall back to using the subtype itself as the
+ * extension (e.g. `audio/mp4` → `audio.mp4`), which is OpenAI's preferred
+ * inference signal.
+ */
+function filenameForMediaType(mediaType) {
+    const known = {
+        "audio/mpeg": "audio.mp3",
+        "audio/mp3": "audio.mp3",
+        "audio/wav": "audio.wav",
+        "audio/x-wav": "audio.wav",
+        "audio/webm": "audio.webm",
+        "audio/ogg": "audio.ogg",
+        "audio/flac": "audio.flac",
+        "audio/m4a": "audio.m4a",
+        "audio/mp4": "audio.mp4",
+    };
+    const normalized = mediaType.split(";")[0].trim().toLowerCase();
+    if (normalized in known)
+        return known[normalized];
+    const slash = normalized.indexOf("/");
+    if (slash !== -1) {
+        const subtype = normalized.slice(slash + 1).replace(/^x-/, "");
+        if (subtype.length > 0)
+            return `audio.${subtype}`;
+    }
+    return "audio.bin";
+}
+//# sourceMappingURL=openai-voice-provider.js.map

package/dist/output-format.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Maps caller-supplied `SpeakOptions.outputFormat` strings onto OpenAI's
+ * `response_format` values, and onto MIME media types the returned
+ * `SpeakResult.mediaType` field carries.
+ *
+ * Unknown formats throw `VoiceError({ kind: "format_unsupported" })`
+ * synchronously so callers fail fast at the provider boundary rather than
+ * after the network round-trip.
+ */
+declare const ALLOWED: readonly ["mp3", "opus", "aac", "flac", "wav", "pcm"];
+type OpenAIResponseFormat = (typeof ALLOWED)[number];
+/**
+ * Validates and normalizes a caller-supplied output format. Returns `"mp3"`
+ * when the caller doesn't specify one (matches OpenAI's own default and the
+ * pre-`VoiceProvider` pipeline behaviour).
+ */
+export declare function mapOutputFormat(format: string | undefined): OpenAIResponseFormat;
+/** MIME media type for an OpenAI response format. */
+export declare function mediaTypeForFormat(format: OpenAIResponseFormat): string;
+export {};
+//# sourceMappingURL=output-format.d.ts.map

package/dist/output-format.js

@@ -0,0 +1,42 @@
+/**
+ * Maps caller-supplied `SpeakOptions.outputFormat` strings onto OpenAI's
+ * `response_format` values, and onto MIME media types the returned
+ * `SpeakResult.mediaType` field carries.
+ *
+ * Unknown formats throw `VoiceError({ kind: "format_unsupported" })`
+ * synchronously so callers fail fast at the provider boundary rather than
+ * after the network round-trip.
+ */
+import { VoiceError } from "@flow-state-dev/core";
+const ALLOWED = ["mp3", "opus", "aac", "flac", "wav", "pcm"];
+const MIME = {
+    mp3: "audio/mpeg",
+    opus: "audio/ogg; codecs=opus",
+    aac: "audio/aac",
+    flac: "audio/flac",
+    wav: "audio/wav",
+    // OpenAI's PCM output is 24 kHz 16-bit little-endian mono.
+    pcm: "audio/pcm;rate=24000",
+};
+/**
+ * Validates and normalizes a caller-supplied output format. Returns `"mp3"`
+ * when the caller doesn't specify one (matches OpenAI's own default and the
+ * pre-`VoiceProvider` pipeline behaviour).
+ */
+export function mapOutputFormat(format) {
+    if (format === undefined)
+        return "mp3";
+    if (ALLOWED.includes(format)) {
+        return format;
+    }
+    throw new VoiceError({
+        kind: "format_unsupported",
+        provider: "openai",
+        message: `outputFormat "${format}" is not supported by OpenAI TTS. Allowed: ${ALLOWED.join(", ")}.`,
+    });
+}
+/** MIME media type for an OpenAI response format. */
+export function mediaTypeForFormat(format) {
+    return MIME[format];
+}
+//# sourceMappingURL=output-format.js.map

package/dist/translate-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Translates errors thrown by the `openai` SDK into the framework's typed
+ * `VoiceError` discriminated by `kind`. Callers branch on `kind` and inspect
+ * `retryable` instead of parsing message strings or sniffing SDK class names.
+ *
+ * `VoiceError` instances pass through unchanged so the translator is
+ * idempotent: helpers that throw `VoiceError` directly (`mapOutputFormat`,
+ * `coerceUploadable`, the instructions guard) don't get re-wrapped when
+ * they bubble through a translation site.
+ */
+import { VoiceError } from "@flow-state-dev/core";
+/**
+ * Maps any thrown value from an OpenAI SDK call to a `VoiceError`. Already
+ * a `VoiceError` → returned as-is. Recognized `OpenAI.*Error` subclasses →
+ * mapped to their canonical `kind`. Anything else → `kind: "unknown"`.
+ */
+export declare function translateError(err: unknown): VoiceError;
+//# sourceMappingURL=translate-error.d.ts.map

package/dist/translate-error.js

@@ -0,0 +1,130 @@
+/**
+ * Translates errors thrown by the `openai` SDK into the framework's typed
+ * `VoiceError` discriminated by `kind`. Callers branch on `kind` and inspect
+ * `retryable` instead of parsing message strings or sniffing SDK class names.
+ *
+ * `VoiceError` instances pass through unchanged so the translator is
+ * idempotent: helpers that throw `VoiceError` directly (`mapOutputFormat`,
+ * `coerceUploadable`, the instructions guard) don't get re-wrapped when
+ * they bubble through a translation site.
+ */
+import OpenAI from "openai";
+import { VoiceError } from "@flow-state-dev/core";
+/**
+ * Maps any thrown value from an OpenAI SDK call to a `VoiceError`. Already
+ * a `VoiceError` → returned as-is. Recognized `OpenAI.*Error` subclasses →
+ * mapped to their canonical `kind`. Anything else → `kind: "unknown"`.
+ */
+export function translateError(err) {
+    if (err instanceof VoiceError)
+        return err;
+    if (err instanceof OpenAI.APIUserAbortError) {
+        return new VoiceError({
+            kind: "aborted",
+            provider: "openai",
+            message: err.message,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.AuthenticationError ||
+        err instanceof OpenAI.PermissionDeniedError) {
+        return new VoiceError({
+            kind: "auth",
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.RateLimitError) {
+        return new VoiceError({
+            kind: "rate_limit",
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.NotFoundError) {
+        return new VoiceError({
+            kind: "not_found",
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.BadRequestError ||
+        err instanceof OpenAI.UnprocessableEntityError) {
+        const kind = looksLikeFormatError(err) ? "format_unsupported" : "invalid_input";
+        return new VoiceError({
+            kind,
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.InternalServerError) {
+        return new VoiceError({
+            kind: "provider_unavailable",
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.APIConnectionError) {
+        // Also catches APIConnectionTimeoutError, which extends APIConnectionError.
+        return new VoiceError({
+            kind: "network",
+            provider: "openai",
+            message: err.message,
+            cause: err,
+        });
+    }
+    if (err instanceof OpenAI.APIError) {
+        return new VoiceError({
+            kind: "unknown",
+            provider: "openai",
+            message: err.message,
+            status: err.status,
+            cause: err,
+        });
+    }
+    return new VoiceError({
+        kind: "unknown",
+        provider: "openai",
+        message: err instanceof Error ? err.message : String(err),
+        cause: err,
+    });
+}
+/**
+ * Heuristic for "is this 400/422 about an unsupported audio format?"
+ * OpenAI doesn't have a dedicated error class for format failures, so we
+ * sniff the structured fields the SDK exposes (`code`, `param`, `error`)
+ * before falling back to `invalid_input`.
+ */
+function looksLikeFormatError(err) {
+    const anyErr = err;
+    if (anyErr.code === "unsupported_format")
+        return true;
+    if (anyErr.code === "invalid_value" && anyErr.param === "response_format")
+        return true;
+    if (anyErr.param === "response_format")
+        return true;
+    if (anyErr.param === "file" &&
+        typeof anyErr.message === "string" &&
+        anyErr.message.toLowerCase().includes("format")) {
+        return true;
+    }
+    const inner = anyErr.error;
+    if (inner !== undefined &&
+        inner.type === "invalid_request_error" &&
+        inner.code === "invalid_value" &&
+        (inner.param === "response_format" || inner.param === "file")) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=translate-error.js.map

package/dist/voice-catalog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Static catalog of OpenAI's prebuilt TTS voices. Returned by
+ * `OpenAIVoiceProvider.listVoices()`.
+ *
+ * Convention: `supportedModels === undefined` means "supported by every
+ * OpenAI TTS model". Voices that are only available on a subset (currently
+ * `marin` and `cedar`, which require `gpt-4o-mini-tts`) declare the
+ * intersection explicitly via `supportedModels`.
+ *
+ * OpenAI does not expose a discovery endpoint for TTS voices; the catalog
+ * is updated manually when OpenAI publishes new entries.
+ */
+import type { VoiceInfo } from "@flow-state-dev/core";
+export declare const OPENAI_VOICE_CATALOG: readonly VoiceInfo[];
+//# sourceMappingURL=voice-catalog.d.ts.map

package/dist/voice-catalog.js

@@ -0,0 +1,28 @@
+/**
+ * Static catalog of OpenAI's prebuilt TTS voices. Returned by
+ * `OpenAIVoiceProvider.listVoices()`.
+ *
+ * Convention: `supportedModels === undefined` means "supported by every
+ * OpenAI TTS model". Voices that are only available on a subset (currently
+ * `marin` and `cedar`, which require `gpt-4o-mini-tts`) declare the
+ * intersection explicitly via `supportedModels`.
+ *
+ * OpenAI does not expose a discovery endpoint for TTS voices; the catalog
+ * is updated manually when OpenAI publishes new entries.
+ */
+export const OPENAI_VOICE_CATALOG = [
+    { id: "alloy", name: "Alloy", provider: "openai" },
+    { id: "ash", name: "Ash", provider: "openai" },
+    { id: "ballad", name: "Ballad", provider: "openai" },
+    { id: "coral", name: "Coral", provider: "openai" },
+    { id: "echo", name: "Echo", provider: "openai" },
+    { id: "fable", name: "Fable", provider: "openai" },
+    { id: "nova", name: "Nova", provider: "openai" },
+    { id: "onyx", name: "Onyx", provider: "openai" },
+    { id: "sage", name: "Sage", provider: "openai" },
+    { id: "shimmer", name: "Shimmer", provider: "openai" },
+    { id: "verse", name: "Verse", provider: "openai" },
+    { id: "marin", name: "Marin", provider: "openai", supportedModels: ["gpt-4o-mini-tts"] },
+    { id: "cedar", name: "Cedar", provider: "openai", supportedModels: ["gpt-4o-mini-tts"] },
+];
+//# sourceMappingURL=voice-catalog.js.map

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@flow-state-dev/voice-openai",
+  "version": "0.1.1",
+  "description": "OpenAI voice transport for flow-state-dev.",
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "workflow",
+    "typescript",
+    "flow-state-dev",
+    "voice",
+    "openai",
+    "realtime",
+    "transport"
+  ],
+  "homepage": "https://flow-state.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fixpoint-labs/flow-state-dev.git",
+    "directory": "packages/voice-openai"
+  },
+  "bugs": {
+    "url": "https://github.com/fixpoint-labs/flow-state-dev/issues"
+  },
+  "author": "Fixpoint Labs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "openai": "^6.38.0",
+    "@flow-state-dev/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "node ../../scripts/typecheck.mjs",
+    "lint": "echo 'lint not configured yet'",
+    "test": "vitest run --root .",
+    "test:watch": "vitest --root ."
+  }
+}