@voiceinput/openai 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hirad Arshadiyarahmadi
+
+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,138 @@
+# `@voiceinput/openai`
+
+OpenAI Realtime transcription adapter for VoiceInput. The root export is
+browser-safe; `@voiceinput/openai/server` mints ephemeral client credentials
+with a long-lived API key.
+
+## Install
+
+```bash
+npm install @voiceinput/react@next @voiceinput/openai@next
+```
+
+## Browser adapter
+
+```ts
+import { openai } from "@voiceinput/openai";
+
+const provider = openai({
+  tokenEndpoint: "/api/voice-token",
+});
+```
+
+Pass `provider` to `VoiceInputProvider` or directly to `useVoiceInput`.
+
+### Defaults and shared-option mapping
+
+- Model: `gpt-transcribe` (`OPENAI_DEFAULT_MODEL`)
+- Audio: mono PCM16 at 24 kHz
+- Omitted language: provider automatic detection
+- `language`: normalized to its ISO 639-1 primary language code
+- `vocabulary`: `keywords` for `gpt-live-transcribe*` models; a transcription
+  prompt for committed-turn transcription models
+- `endpointing`: server VAD with 500 ms silence when omitted, manual commit when
+  `false`, or server VAD with the requested `silence_duration_ms`
+- `gpt-live-transcribe*`: manual commit only; omitted endpointing maps to
+  `null`. Explicit server endpointing fails with `unsupported-feature` before
+  permission.
+
+Vocabulary accepts at most 100 trimmed terms, each at most 200 characters and
+without angle brackets or line breaks. Invalid or unsupported settings fail
+before microphone permission with distinct error codes.
+
+### `OpenAIVoiceInputProviderOptions`
+
+| Option          | Purpose                                                            |
+| --------------- | ------------------------------------------------------------------ |
+| `tokenEndpoint` | Required same-origin endpoint that returns an ephemeral credential |
+| `model`         | Model ID; default `gpt-transcribe`                                 |
+| `fetch`         | Test/runtime override for `globalThis.fetch`                       |
+| `webSocket`     | Test/runtime override for `globalThis.WebSocket`                   |
+| `realtimeUrl`   | Realtime WebSocket URL override                                    |
+
+The last three options are provider-factory escape hatches, primarily useful for
+controlled infrastructure and deterministic tests.
+
+## Server token handler
+
+```ts
+import { createOpenAITokenHandler } from "@voiceinput/openai/server";
+
+export const POST = createOpenAITokenHandler({
+  apiKey: process.env.OPENAI_API_KEY!,
+  authorize: async (request) => {
+    const user = await authenticate(request);
+    return user ? { subject: user.id } : null;
+  },
+  rateLimit: async ({ subject }) => {
+    return (await underQuota(subject))
+      ? { allowed: true }
+      : { allowed: false, retryAfterSeconds: 60 };
+  },
+});
+```
+
+The handler accepts only `POST`, always requires `authorize`, sends
+`Cache-Control: no-store`, and never returns or logs the long-lived API key.
+Returning `null` from `authorize` produces `401`. A denied `rateLimit` produces
+`429` before a provider credential is minted. Requests must be JSON and are
+limited to 16 KiB. Authorization and rate-limit callbacks receive independent
+request bodies. If `onTokenIssued` throws, credential delivery fails closed.
+
+### `CreateOpenAITokenHandlerOptions`
+
+| Option                      | Purpose                                                             |
+| --------------------------- | ------------------------------------------------------------------- |
+| `apiKey`                    | Required server-only OpenAI key                                     |
+| `authorize(request)`        | Required application authorization; returns `{ subject }` or `null` |
+| `model`                     | Default model; default `gpt-transcribe`                             |
+| `allowedModels`             | Models a browser request may select; defaults to only `model`       |
+| `organization`, `project`   | Optional OpenAI request headers                                     |
+| `safetyIdentifier(context)` | Optional per-subject OpenAI safety identifier                       |
+| `rateLimit(context)`        | Optional application quota check                                    |
+| `onTokenIssued(metadata)`   | Metadata-only audit callback with subject, model, and expiry        |
+| `fetch`, `clientSecretUrl`  | Transport/endpoint overrides                                        |
+
+`OpenAITokenHandlerContext` contains `request`, `subject`, and `model`.
+`OpenAITokenIssuedMetadata` contains `provider: "openai"`, `subject`, `model`,
+and `expiresAt`.
+
+The default commits separate phrases during a recording, allowing undo and
+correction to work at phrase boundaries. Live checks on 2026-09-04 confirmed
+that `gpt-live-transcribe` rejects server VAD and does not commit until Stop. It
+remains available for earlier interim feedback: set its model in both the
+adapter and token handler and use `endpointing: false`. In that mode a recording
+is one segment; editing its interim suppresses insertion until the next
+recording. See [provider certification](../../docs/provider-certification.md)
+for evidence and the latency tradeoff.
+
+## Public API
+
+Browser root:
+
+- `openai(options)`
+- `OPENAI_DEFAULT_MODEL`
+- `OpenAIVoiceInputProviderOptions`
+
+Server-only entry point:
+
+- `createOpenAITokenHandler(options)`
+- `CreateOpenAITokenHandlerOptions`
+- `OpenAIAuthorization`
+- `OpenAIRateLimitResult`
+- `OpenAITokenHandlerContext`
+- `OpenAITokenIssuedMetadata`
+
+## Security
+
+Import `/server` only from server code. The package export is disabled under the
+browser condition. Never place `OPENAI_API_KEY` in a public environment variable
+or send it to `openai()`. The browser adapter obtains an ephemeral credential
+from your authenticated endpoint and then streams audio directly to OpenAI.
+
+See the
+[Next.js](https://github.com/VoiceInput/voiceinput/blob/main/docs/nextjs.md),
+[Vite/Hono](https://github.com/VoiceInput/voiceinput/blob/main/docs/vite-hono.md),
+and
+[Express](https://github.com/VoiceInput/voiceinput/blob/main/docs/express.md)
+integration guides.

package/dist/index.cjs

@@ -0,0 +1,486 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_session_config = require("./session-config-CmoDDiY6.cjs");
+let _voiceinput_provider_transport = require("@voiceinput/provider/transport");
+let _voiceinput_provider = require("@voiceinput/provider");
+//#region src/index.ts
+const DEFAULT_REALTIME_URL = "wss://api.openai.com/v1/realtime";
+function openai(options) {
+	const model = validateFactoryString(options.model ?? "gpt-transcribe", "model");
+	const tokenEndpoint = validateFactoryString(String(options.tokenEndpoint), "tokenEndpoint");
+	const realtimeUrl = validateFactoryString(options.realtimeUrl ?? DEFAULT_REALTIME_URL, "realtimeUrl");
+	const fetchImplementation = options.fetch ?? globalThis.fetch;
+	const WebSocketImplementation = options.webSocket ?? globalThis.WebSocket;
+	const validateProviderOptions = (transcriptionOptions) => validateOptions(transcriptionOptions, model);
+	return Object.freeze({
+		specificationVersion: "v1",
+		provider: "openai",
+		modelId: model,
+		sampleRate: require_session_config.OPENAI_SAMPLE_RATE,
+		validateOptions: validateProviderOptions,
+		async doOpen(callOptions) {
+			validateProviderOptions(callOptions);
+			return await openSession({
+				callOptions,
+				fetchImplementation,
+				model,
+				realtimeUrl,
+				tokenEndpoint,
+				WebSocketImplementation
+			});
+		}
+	});
+}
+function validateOptions(options, model) {
+	try {
+		require_session_config.validateOpenAITokenRequest({
+			model,
+			...options
+		});
+	} catch (cause) {
+		if (_voiceinput_provider.VoiceInputError.isInstance(cause)) throw cause;
+		throw new _voiceinput_provider.VoiceInputError({
+			code: "invalid-configuration",
+			message: cause instanceof Error ? cause.message : "Invalid OpenAI transcription options.",
+			provider: "openai",
+			cause
+		});
+	}
+}
+async function openSession(options) {
+	const { abortSignal } = options.callOptions;
+	throwIfAborted(abortSignal);
+	if (typeof options.fetchImplementation !== "function") throw unsupportedBrowserFeature("fetch");
+	if (typeof options.WebSocketImplementation !== "function") throw unsupportedBrowserFeature("WebSocket");
+	const tokenRequest = require_session_config.validateOpenAITokenRequest({
+		model: options.model,
+		...options.callOptions
+	});
+	const credential = await requestCredential(options.fetchImplementation, options.tokenEndpoint, tokenRequest, abortSignal);
+	throwIfAborted(abortSignal);
+	return await createSession(new options.WebSocketImplementation(options.realtimeUrl, ["realtime", `openai-insecure-api-key.${credential.value}`]), tokenRequest, abortSignal);
+}
+async function requestCredential(fetchImplementation, tokenEndpoint, tokenRequest, abortSignal) {
+	let response;
+	try {
+		response = await fetchImplementation(tokenEndpoint, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(tokenRequest),
+			credentials: "same-origin",
+			signal: abortSignal
+		});
+	} catch (cause) {
+		throwIfAborted(abortSignal);
+		throw new _voiceinput_provider.VoiceInputError({
+			code: "network-error",
+			message: "Unable to reach the OpenAI token endpoint.",
+			provider: "openai",
+			retryable: true,
+			cause
+		});
+	}
+	if (!response.ok) throw await tokenResponseError(response);
+	let value;
+	try {
+		value = await response.json();
+	} catch (cause) {
+		throw new _voiceinput_provider.VoiceInputError({
+			code: "token-error",
+			message: "The OpenAI token endpoint returned invalid JSON.",
+			provider: "openai",
+			cause
+		});
+	}
+	if (!isRecord(value) || typeof value["value"] !== "string" || value["value"].length === 0 || typeof value["expires_at"] !== "number" || !Number.isFinite(value["expires_at"])) throw new _voiceinput_provider.VoiceInputError({
+		code: "token-error",
+		message: "The OpenAI token endpoint returned an invalid credential.",
+		provider: "openai"
+	});
+	return {
+		value: value["value"],
+		expires_at: value["expires_at"]
+	};
+}
+async function tokenResponseError(response) {
+	const retryAfterMs = parseRetryAfter(response.headers.get("Retry-After"));
+	if (response.status === 401 || response.status === 403) return new _voiceinput_provider.VoiceInputError({
+		code: "unauthorized",
+		message: "The OpenAI token endpoint rejected this request.",
+		provider: "openai"
+	});
+	if (response.status === 429) return new _voiceinput_provider.VoiceInputError({
+		code: "rate-limited",
+		message: "The OpenAI token endpoint rate limit was exceeded.",
+		provider: "openai",
+		retryable: true,
+		...retryAfterMs === void 0 ? {} : { retryAfterMs }
+	});
+	const safeError = await readSafeTokenError(response);
+	if (safeError !== void 0) return new _voiceinput_provider.VoiceInputError({
+		...safeError,
+		provider: "openai"
+	});
+	return new _voiceinput_provider.VoiceInputError({
+		code: "token-error",
+		message: "The OpenAI token endpoint did not issue a credential.",
+		provider: "openai",
+		retryable: response.status >= 500
+	});
+}
+async function readSafeTokenError(response) {
+	if (response.status !== 400 || response.headers.get("X-VoiceInput-Error") !== "1" || response.headers.get("Content-Type")?.split(";", 1)[0]?.trim() !== "application/json") return;
+	const text = await readBoundedErrorText(response);
+	if (text === void 0) return void 0;
+	try {
+		const value = JSON.parse(text);
+		const error = isRecord(value) ? value["error"] : void 0;
+		if (!isRecord(error) || error["code"] !== "invalid-configuration" && error["code"] !== "unsupported-feature" || typeof error["message"] !== "string" || error["message"].length === 0 || error["message"].length > 1e3) return;
+		return {
+			code: error["code"],
+			message: error["message"]
+		};
+	} catch {
+		return;
+	}
+}
+async function readBoundedErrorText(response) {
+	const reader = response.body?.getReader();
+	if (reader === void 0) return void 0;
+	const decoder = new TextDecoder();
+	let bytesRead = 0;
+	let text = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) return text + decoder.decode();
+			bytesRead += value.byteLength;
+			if (bytesRead > 4096) {
+				await reader.cancel().catch(() => {});
+				return;
+			}
+			text += decoder.decode(value, { stream: true });
+		}
+	} catch {
+		return;
+	}
+}
+async function createSession(socket, tokenRequest, abortSignal) {
+	let streamController;
+	const stream = new ReadableStream({ start(controller) {
+		streamController = controller;
+	} });
+	if (streamController === void 0) throw new _voiceinput_provider.VoiceInputError({
+		code: "provider-error",
+		message: "Unable to initialize the OpenAI transcript stream.",
+		provider: "openai"
+	});
+	const transcripts = /* @__PURE__ */ new Map();
+	const transcriptOrder = [];
+	const closedItems = /* @__PURE__ */ new Set();
+	let audioSent = false;
+	let closed = false;
+	let failed = false;
+	let finishing = false;
+	let manualCommitPending = false;
+	let vadCommitPending = false;
+	const manualCommitEventId = "voiceinput-finish";
+	const closeStream = () => {
+		if (closed) return;
+		closed = true;
+		abortSignal.removeEventListener("abort", abort);
+		streamController?.close();
+	};
+	const closeSocket = (reason) => {
+		if (socket.readyState === 1 || socket.readyState === 0) socket.close(1e3, reason);
+	};
+	const finishCleanly = () => {
+		closeStream();
+		closeSocket("finished");
+	};
+	const fail = (error) => {
+		if (closed || failed) return;
+		failed = true;
+		streamController?.enqueue({
+			type: "error",
+			error
+		});
+		closeStream();
+		closeSocket("aborted");
+	};
+	const maybeFinish = () => {
+		if (finishing && !manualCommitPending && !vadCommitPending && transcripts.size === 0) finishCleanly();
+	};
+	const emitInterim = (state) => {
+		if (state.delta && state.delta !== state.lastEmittedInterim) {
+			state.lastEmittedInterim = state.delta;
+			streamController?.enqueue({
+				type: "interim",
+				text: state.delta,
+				segmentId: transcriptOrder[0]
+			});
+		}
+	};
+	const flushFinals = () => {
+		while (transcriptOrder.length > 0) {
+			const itemId = transcriptOrder[0];
+			const state = transcripts.get(itemId);
+			if (state?.final === void 0) {
+				if (state !== void 0) emitInterim(state);
+				break;
+			}
+			transcriptOrder.shift();
+			transcripts.delete(itemId);
+			closedItems.add(itemId);
+			streamController?.enqueue({
+				type: "final",
+				text: state.final,
+				segmentId: itemId
+			});
+		}
+		maybeFinish();
+	};
+	const ensureTranscript = (itemId) => {
+		let state = transcripts.get(itemId);
+		if (state === void 0) {
+			state = { delta: "" };
+			transcripts.set(itemId, state);
+			transcriptOrder.push(itemId);
+		}
+		return state;
+	};
+	const handleMessage = (event) => {
+		if (closed) return;
+		try {
+			const value = JSON.parse(String(event.data));
+			if (!isRecord(value) || typeof value["type"] !== "string") throw new TypeError("OpenAI sent an invalid Realtime event.");
+			const type = value["type"];
+			if (type === "input_audio_buffer.speech_started") {
+				streamController?.enqueue({ type: "speech-start" });
+				return;
+			}
+			if (type === "input_audio_buffer.speech_stopped") {
+				vadCommitPending = true;
+				streamController?.enqueue({ type: "speech-end" });
+				return;
+			}
+			if (type === "input_audio_buffer.committed") {
+				const itemId = readString(value, "item_id");
+				if (closedItems.has(itemId)) return;
+				manualCommitPending = false;
+				vadCommitPending = false;
+				ensureTranscript(itemId);
+				flushFinals();
+				return;
+			}
+			if (type === "conversation.item.input_audio_transcription.delta") {
+				const itemId = readString(value, "item_id");
+				if (closedItems.has(itemId)) return;
+				const state = ensureTranscript(itemId);
+				state.delta += readString(value, "delta");
+				if (transcriptOrder[0] === itemId) emitInterim(state);
+				return;
+			}
+			if (type === "conversation.item.input_audio_transcription.completed") {
+				const itemId = readString(value, "item_id");
+				if (closedItems.has(itemId)) return;
+				ensureTranscript(itemId).final = readString(value, "transcript");
+				flushFinals();
+				return;
+			}
+			if (type === "conversation.item.input_audio_transcription.failed") {
+				fail(normalizeTranscriptionFailure(value));
+				return;
+			}
+			if (type === "error") {
+				if (isExpectedEmptyCommitError(value, manualCommitEventId)) {
+					manualCommitPending = false;
+					maybeFinish();
+					return;
+				}
+				fail(normalizeRealtimeError(value));
+			}
+		} catch (cause) {
+			fail(new _voiceinput_provider.VoiceInputError({
+				code: "provider-error",
+				message: "OpenAI sent an invalid Realtime event.",
+				provider: "openai",
+				cause
+			}));
+		}
+	};
+	const handleClose = (event) => {
+		if (closed) return;
+		if (event.code === 1e3) closeStream();
+		else fail(new _voiceinput_provider.VoiceInputError({
+			code: "network-error",
+			message: "The OpenAI Realtime connection closed unexpectedly.",
+			provider: "openai",
+			retryable: true,
+			cause: event
+		}));
+	};
+	const abort = () => {
+		if (closed) return;
+		closeStream();
+		closeSocket("aborted");
+	};
+	socket.addEventListener("message", handleMessage);
+	socket.addEventListener("close", handleClose);
+	socket.addEventListener("error", () => {
+		fail(new _voiceinput_provider.VoiceInputError({
+			code: "network-error",
+			message: "The OpenAI Realtime connection failed.",
+			provider: "openai",
+			retryable: true
+		}));
+	});
+	abortSignal.addEventListener("abort", abort, { once: true });
+	await waitForOpen(socket, abortSignal);
+	sendEvent(socket, {
+		type: "session.update",
+		session: require_session_config.createOpenAITranscriptionSession(tokenRequest)
+	});
+	return {
+		stream,
+		sendAudio(chunk) {
+			if (closed || finishing) return;
+			audioSent ||= chunk.length > 0;
+			if (chunk.length > 0) return (0, _voiceinput_provider_transport.sendWithBackpressure)(socket, Math.ceil(chunk.byteLength * 4 / 3) + 128, abortSignal, "openai", () => sendEvent(socket, {
+				type: "input_audio_buffer.append",
+				audio: encodePcm16(chunk)
+			}));
+		},
+		finish() {
+			if (closed || finishing) return;
+			finishing = true;
+			if (!audioSent) {
+				finishCleanly();
+				return;
+			}
+			if (!vadCommitPending) {
+				manualCommitPending = true;
+				sendEvent(socket, {
+					type: "input_audio_buffer.commit",
+					event_id: manualCommitEventId
+				});
+			}
+			maybeFinish();
+		},
+		abort
+	};
+}
+function waitForOpen(socket, abortSignal) {
+	if (socket.readyState === 1) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			socket.removeEventListener("open", handleOpen);
+			socket.removeEventListener("error", handleError);
+			abortSignal.removeEventListener("abort", handleAbort);
+		};
+		const handleOpen = () => {
+			cleanup();
+			resolve();
+		};
+		const handleError = (event) => {
+			cleanup();
+			reject(new _voiceinput_provider.VoiceInputError({
+				code: "network-error",
+				message: "Unable to open the OpenAI Realtime connection.",
+				provider: "openai",
+				retryable: true,
+				cause: event
+			}));
+		};
+		const handleAbort = () => {
+			cleanup();
+			reject(abortSignal.reason);
+		};
+		socket.addEventListener("open", handleOpen, { once: true });
+		socket.addEventListener("error", handleError, { once: true });
+		abortSignal.addEventListener("abort", handleAbort, { once: true });
+	});
+}
+function sendEvent(socket, event) {
+	try {
+		socket.send(JSON.stringify(event));
+	} catch (cause) {
+		throw new _voiceinput_provider.VoiceInputError({
+			code: "network-error",
+			message: "Unable to send data to OpenAI Realtime.",
+			provider: "openai",
+			retryable: true,
+			cause
+		});
+	}
+}
+function encodePcm16(chunk) {
+	const bytes = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+	let binary = "";
+	for (let offset = 0; offset < bytes.length; offset += 8192) binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+	return btoa(binary);
+}
+function normalizeRealtimeError(value) {
+	const error = isRecord(value["error"]) ? value["error"] : value;
+	const code = typeof error["code"] === "string" ? error["code"] : "";
+	const message = typeof error["message"] === "string" ? error["message"] : "OpenAI Realtime reported an error.";
+	const rateLimited = code.includes("rate_limit");
+	return new _voiceinput_provider.VoiceInputError({
+		code: rateLimited ? "rate-limited" : "provider-error",
+		message,
+		provider: "openai",
+		retryable: rateLimited || code.includes("server_error"),
+		cause: value
+	});
+}
+function normalizeTranscriptionFailure(value) {
+	const error = isRecord(value["error"]) ? value["error"] : {};
+	return new _voiceinput_provider.VoiceInputError({
+		code: "provider-error",
+		message: typeof error["message"] === "string" ? error["message"] : "OpenAI could not transcribe an audio turn.",
+		provider: "openai",
+		retryable: typeof error["code"] === "string" && error["code"].includes("server_error"),
+		cause: value
+	});
+}
+function isExpectedEmptyCommitError(value, eventId) {
+	const error = isRecord(value["error"]) ? value["error"] : {};
+	return error["code"] === "input_audio_buffer_commit_empty" && error["event_id"] === eventId;
+}
+function readString(value, key) {
+	const result = value[key];
+	if (typeof result !== "string") throw new TypeError(`${key} must be a string.`);
+	return result;
+}
+function parseRetryAfter(value) {
+	if (value === null) return;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds * 1e3);
+	const date = Date.parse(value);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function throwIfAborted(signal) {
+	if (signal.aborted) throw signal.reason;
+}
+function validateFactoryString(value, name) {
+	if (value.trim().length === 0) throw new _voiceinput_provider.VoiceInputError({
+		code: "invalid-configuration",
+		message: `${name} must be a non-empty string.`,
+		provider: "openai"
+	});
+	return value;
+}
+function unsupportedBrowserFeature(feature) {
+	return new _voiceinput_provider.VoiceInputError({
+		code: "unsupported-browser",
+		message: `OpenAI voice input requires browser ${feature} support.`,
+		provider: "openai"
+	});
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+exports.OPENAI_DEFAULT_MODEL = require_session_config.OPENAI_DEFAULT_MODEL;
+exports.openai = openai;
+
+//# sourceMappingURL=index.cjs.map