@happyvertical/speech 0.97.0 → 0.99.0

package/dist/chunks/registry-C_5BakmM.js

@@ -0,0 +1,306 @@
+import { n as SpeechConfigurationError } from "./errors-CQBX3OPS.js";
+//#region src/shared/audio.ts
+/**
+* Audio input normalisation shared by speech adapters: accepts the input
+* shapes callers actually have (Blob, Buffer, Uint8Array, ArrayBuffer,
+* ReadableStream), enforces byte limits while buffering, and derives a
+* multipart filename whose extension matches the MIME type.
+*/
+/** OpenAI caps `/audio/transcriptions` uploads at 25 MB. */
+var DEFAULT_MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+var MIME_EXTENSIONS = {
+	"audio/webm": "webm",
+	"video/webm": "webm",
+	"audio/mp4": "m4a",
+	"audio/m4a": "m4a",
+	"audio/x-m4a": "m4a",
+	"video/mp4": "mp4",
+	"audio/wav": "wav",
+	"audio/wave": "wav",
+	"audio/x-wav": "wav",
+	"audio/vnd.wave": "wav",
+	"audio/ogg": "ogg",
+	"application/ogg": "ogg",
+	"audio/mpeg": "mp3",
+	"audio/mp3": "mp3",
+	"audio/mpga": "mp3",
+	"audio/flac": "flac",
+	"audio/x-flac": "flac"
+};
+/**
+* Strips parameters (e.g. `;codecs=opus`) and lower-cases a MIME type.
+* Returns `undefined` for blank input.
+*/
+function normalizeMimeType(mimeType) {
+	const essence = mimeType?.split(";")[0]?.trim().toLowerCase();
+	return essence ? essence : void 0;
+}
+/**
+* Maps an audio MIME type to the file extension OpenAI-compatible servers use
+* to detect the container format. Codec parameters are ignored, so
+* `audio/webm;codecs=opus` maps to `webm`. Returns `undefined` when unknown.
+*/
+function mimeTypeToAudioExtension(mimeType) {
+	const essence = normalizeMimeType(mimeType);
+	return essence ? MIME_EXTENSIONS[essence] : void 0;
+}
+/**
+* Accepts either an {@link AudioInput} wrapper or a bare {@link AudioSource}
+* and returns a size-checked Blob plus the metadata needed for multipart
+* uploads.
+*/
+async function normalizeAudioInput(input, options = {}) {
+	const wrapped = isAudioInput(input) ? input : { data: input };
+	const { adapter, signal } = options;
+	signal?.throwIfAborted();
+	const maxBytes = resolveMaxBytes(options.maxBytes, adapter);
+	const data = wrapped.data;
+	const blobType = typeof Blob !== "undefined" && data instanceof Blob ? data.type : void 0;
+	const mimeType = options.mimeType ?? wrapped.mimeType ?? wrapped.contentType ?? (blobType || void 0) ?? "application/octet-stream";
+	let blob;
+	if (typeof Blob !== "undefined" && data instanceof Blob) {
+		assertWithinLimit(data.size, maxBytes, adapter);
+		blob = data.type === mimeType ? data : new Blob([data], { type: mimeType });
+	} else if (data instanceof Uint8Array) {
+		assertWithinLimit(data.byteLength, maxBytes, adapter);
+		blob = new Blob([copyBytes(data)], { type: mimeType });
+	} else if (data instanceof ArrayBuffer) {
+		assertWithinLimit(data.byteLength, maxBytes, adapter);
+		blob = new Blob([data], { type: mimeType });
+	} else if (isReadableStream(data)) {
+		const chunks = await readStreamWithLimit(data, maxBytes, adapter, signal);
+		blob = new Blob(chunks, { type: mimeType });
+	} else throw new SpeechConfigurationError("Unsupported audio input: expected Blob, Buffer, Uint8Array, ArrayBuffer, or ReadableStream", adapter);
+	if (blob.size === 0) throw new SpeechConfigurationError("Audio input is empty", adapter);
+	const extension = options.deriveExtension === false ? void 0 : mimeTypeToAudioExtension(mimeType);
+	const basename = options.defaultBasename ?? "audio";
+	const filename = wrapped.filename ?? (extension ? `${basename}.${extension}` : basename);
+	return {
+		blob,
+		mimeType,
+		bytes: blob.size,
+		filename,
+		durationSeconds: wrapped.durationSeconds
+	};
+}
+function isAudioInput(value) {
+	return typeof value === "object" && value !== null && "data" in value && !(typeof Blob !== "undefined" && value instanceof Blob) && !(value instanceof Uint8Array) && !(value instanceof ArrayBuffer) && !isReadableStream(value);
+}
+function isReadableStream(value) {
+	return typeof value === "object" && value !== null && typeof value.getReader === "function";
+}
+function resolveMaxBytes(maxBytes, adapter) {
+	if (maxBytes === void 0) return Number.POSITIVE_INFINITY;
+	if (Number.isNaN(maxBytes) || maxBytes <= 0) throw new SpeechConfigurationError("maxBytes must be a positive number", adapter);
+	return maxBytes;
+}
+function assertWithinLimit(bytes, maxBytes, adapter) {
+	if (bytes > maxBytes) throw new SpeechConfigurationError(`Audio input exceeds maxBytes (${bytes} > ${maxBytes} bytes)`, adapter);
+}
+async function readStreamWithLimit(stream, maxBytes, adapter, signal) {
+	const reader = stream.getReader();
+	const chunks = [];
+	let total = 0;
+	const onAbort = () => {
+		reader.cancel(signal?.reason).catch(() => void 0);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			signal?.throwIfAborted();
+			if (done) break;
+			total += chunkByteLength(value, adapter);
+			if (total > maxBytes) {
+				await reader.cancel().catch(() => void 0);
+				throw new SpeechConfigurationError(`Audio stream exceeds maxBytes (more than ${maxBytes} bytes)`, adapter);
+			}
+			chunks.push(toBytes(value));
+		}
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		reader.releaseLock();
+	}
+	return chunks;
+}
+function chunkByteLength(value, adapter) {
+	if (value instanceof Uint8Array || value instanceof ArrayBuffer) return value.byteLength;
+	throw new SpeechConfigurationError("Audio stream chunks must be Uint8Array or ArrayBuffer", adapter);
+}
+function toBytes(value) {
+	return value instanceof Uint8Array ? copyBytes(value) : new Uint8Array(value.slice(0));
+}
+function copyBytes(bytes) {
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}
+//#endregion
+//#region src/shared/usage.ts
+/**
+* Invokes every configured usage callback in order (adapter-level first, then
+* request-level). Callback errors propagate to the caller so that billing
+* hooks never fail silently.
+*/
+async function reportSpeechUsage(usage, ...callbacks) {
+	for (const callback of callbacks) if (callback) await callback(usage);
+}
+/**
+* Extracts audio seconds from an OpenAI-style `usage` block
+* (`{ type: 'duration', seconds }`).
+*/
+function audioSecondsFromProviderUsage(providerUsage) {
+	if (!providerUsage) return;
+	const seconds = providerUsage.seconds;
+	return typeof seconds === "number" && Number.isFinite(seconds) ? seconds : void 0;
+}
+//#endregion
+//#region src/shared/env.ts
+/**
+* Environment configuration for speech adapters.
+*
+* Transcriber settings resolve in this order (first wins):
+* explicit options → factory context → `HAVE_SPEECH_TRANSCRIBER_*` →
+* legacy `HAVE_SPEECH_STT_*` → gateway `STT_*` aliases.
+*/
+/** Environment variable names read for each transcriber setting, in priority order. */
+var TRANSCRIBER_ENV_KEYS = {
+	type: [
+		"HAVE_SPEECH_TRANSCRIBER_TYPE",
+		"HAVE_SPEECH_STT_TYPE",
+		"HAVE_SPEECH_STT_ADAPTER",
+		"STT_ADAPTER"
+	],
+	baseUrl: [
+		"HAVE_SPEECH_TRANSCRIBER_BASE_URL",
+		"HAVE_SPEECH_STT_BASE_URL",
+		"STT_BASE_URL"
+	],
+	model: [
+		"HAVE_SPEECH_TRANSCRIBER_MODEL",
+		"HAVE_SPEECH_STT_MODEL",
+		"STT_MODEL"
+	],
+	apiKey: [
+		"HAVE_SPEECH_TRANSCRIBER_API_KEY",
+		"HAVE_SPEECH_STT_API_KEY",
+		"STT_API_KEY",
+		"SPEECH_API_KEY"
+	],
+	timeoutMs: [
+		"HAVE_SPEECH_TRANSCRIBER_TIMEOUT",
+		"HAVE_SPEECH_TRANSCRIBER_TIMEOUT_MS",
+		"HAVE_SPEECH_STT_TIMEOUT_MS",
+		"STT_TIMEOUT_MS"
+	],
+	maxBytes: ["HAVE_SPEECH_TRANSCRIBER_MAX_BYTES", "STT_MAX_BYTES"],
+	headers: ["HAVE_SPEECH_TRANSCRIBER_HEADERS", "STT_HEADERS"],
+	path: [
+		"HAVE_SPEECH_TRANSCRIBER_PATH",
+		"HAVE_SPEECH_STT_PATH",
+		"STT_PATH"
+	]
+};
+function readTranscriberEnv(env) {
+	return {
+		type: readEnv(env, ...TRANSCRIBER_ENV_KEYS.type),
+		baseUrl: readEnv(env, ...TRANSCRIBER_ENV_KEYS.baseUrl),
+		model: readEnv(env, ...TRANSCRIBER_ENV_KEYS.model),
+		apiKey: readEnv(env, ...TRANSCRIBER_ENV_KEYS.apiKey),
+		timeoutMs: parseOptionalInteger(readEnv(env, ...TRANSCRIBER_ENV_KEYS.timeoutMs)),
+		maxBytes: parseOptionalInteger(readEnv(env, ...TRANSCRIBER_ENV_KEYS.maxBytes)),
+		headers: parseHeadersEnv(env, TRANSCRIBER_ENV_KEYS.headers),
+		path: readEnv(env, ...TRANSCRIBER_ENV_KEYS.path)
+	};
+}
+function hasTranscriberEnv(env) {
+	return hasAnyEnv(env, ...TRANSCRIBER_ENV_KEYS.type, ...TRANSCRIBER_ENV_KEYS.baseUrl);
+}
+/**
+* Merges explicit transcriber options with the factory context and the
+* environment. Explicit options always win; headers are merged so a
+* per-deployment env header (e.g. a gateway virtual key) can be combined with
+* explicit ones.
+*/
+function resolveTranscriberConfig(options = {}, context = {}) {
+	const fromEnv = readTranscriberEnv(context.env ?? defaultEnv());
+	const headers = mergeHeaderInits(fromEnv.headers, context.headers, options.headers);
+	return {
+		type: options.type ?? fromEnv.type,
+		baseUrl: (options.baseUrl ?? fromEnv.baseUrl)?.trim(),
+		model: options.model ?? fromEnv.model,
+		apiKey: options.apiKey ?? fromEnv.apiKey,
+		timeoutMs: options.timeoutMs ?? fromEnv.timeoutMs,
+		maxBytes: options.maxBytes ?? fromEnv.maxBytes,
+		headers,
+		fetch: options.fetch ?? context.fetch,
+		path: fromEnv.path
+	};
+}
+/** Merges header sets left to right; later sets win per header name. */
+function mergeHeaderInits(...sets) {
+	const present = sets.filter((set) => Boolean(set));
+	if (present.length === 0) return;
+	const merged = new Headers();
+	for (const set of present) new Headers(set).forEach((value, key) => {
+		merged.set(key, value);
+	});
+	return merged;
+}
+function readEnv(env, ...keys) {
+	for (const key of keys) {
+		const value = env[key];
+		if (value?.trim()) return value.trim();
+	}
+}
+function hasAnyEnv(env, ...keys) {
+	return keys.some((key) => Boolean(env[key]?.trim()));
+}
+function parseOptionalInteger(value) {
+	if (!value) return;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function defaultEnv() {
+	return globalThis.process?.env ?? {};
+}
+/**
+* Parses a JSON object of header names to string values. The raw value is
+* never echoed in errors because it may carry credentials.
+*/
+function parseHeadersEnv(env, keys) {
+	for (const key of keys) {
+		const raw = env[key]?.trim();
+		if (!raw) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			throw new SpeechConfigurationError(`${key} must be a JSON object of header names to string values`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Object.values(parsed).every((value) => typeof value === "string")) throw new SpeechConfigurationError(`${key} must be a JSON object of header names to string values`);
+		return parsed;
+	}
+}
+//#endregion
+//#region src/shared/registry.ts
+/** Adapter types that are only available after importing a subpath. */
+var OPTIONAL_TRANSCRIBER_ENTRIES = { local: "@happyvertical/speech/local" };
+var registered = /* @__PURE__ */ new Map();
+function registerOptionalTranscriber(type, factory) {
+	registered.set(type, factory);
+}
+function getOptionalTranscriberFactory(type) {
+	return registered.get(type);
+}
+/** Subpath that registers `type`, when it is an opt-in adapter. */
+function optionalTranscriberEntry(type) {
+	return OPTIONAL_TRANSCRIBER_ENTRIES[type];
+}
+function registeredOptionalTranscribers() {
+	return [...registered.keys()];
+}
+//#endregion
+export { mimeTypeToAudioExtension as _, TRANSCRIBER_ENV_KEYS as a, hasTranscriberEnv as c, parseOptionalInteger as d, readEnv as f, DEFAULT_MAX_AUDIO_BYTES as g, reportSpeechUsage as h, registeredOptionalTranscribers as i, mergeHeaderInits as l, audioSecondsFromProviderUsage as m, optionalTranscriberEntry as n, defaultEnv as o, resolveTranscriberConfig as p, registerOptionalTranscriber as r, hasAnyEnv as s, getOptionalTranscriberFactory as t, parseHeadersEnv as u, normalizeAudioInput as v, normalizeMimeType as y };
+
+//# sourceMappingURL=registry-C_5BakmM.js.map

package/dist/chunks/registry-C_5BakmM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-C_5BakmM.js","names":[],"sources":["../../src/shared/audio.ts","../../src/shared/usage.ts","../../src/shared/env.ts","../../src/shared/registry.ts"],"sourcesContent":["/**\n * Audio input normalisation shared by speech adapters: accepts the input\n * shapes callers actually have (Blob, Buffer, Uint8Array, ArrayBuffer,\n * ReadableStream), enforces byte limits while buffering, and derives a\n * multipart filename whose extension matches the MIME type.\n */\n\nimport { SpeechConfigurationError } from './errors.js';\nimport type { AudioInput, AudioSource } from './types.js';\n\n/** OpenAI caps `/audio/transcriptions` uploads at 25 MB. */\nexport const DEFAULT_MAX_AUDIO_BYTES = 25 * 1024 * 1024;\n\nconst MIME_EXTENSIONS: Record<string, string> = {\n  'audio/webm': 'webm',\n  'video/webm': 'webm',\n  'audio/mp4': 'm4a',\n  'audio/m4a': 'm4a',\n  'audio/x-m4a': 'm4a',\n  'video/mp4': 'mp4',\n  'audio/wav': 'wav',\n  'audio/wave': 'wav',\n  'audio/x-wav': 'wav',\n  'audio/vnd.wave': 'wav',\n  'audio/ogg': 'ogg',\n  'application/ogg': 'ogg',\n  'audio/mpeg': 'mp3',\n  'audio/mp3': 'mp3',\n  'audio/mpga': 'mp3',\n  'audio/flac': 'flac',\n  'audio/x-flac': 'flac',\n};\n\n/**\n * Strips parameters (e.g. `;codecs=opus`) and lower-cases a MIME type.\n * Returns `undefined` for blank input.\n */\nexport function normalizeMimeType(\n  mimeType: string | undefined | null,\n): string | undefined {\n  const essence = mimeType?.split(';')[0]?.trim().toLowerCase();\n  return essence ? essence : undefined;\n}\n\n/**\n * Maps an audio MIME type to the file extension OpenAI-compatible servers use\n * to detect the container format. Codec parameters are ignored, so\n * `audio/webm;codecs=opus` maps to `webm`. Returns `undefined` when unknown.\n */\nexport function mimeTypeToAudioExtension(\n  mimeType: string | undefined | null,\n): string | undefined {\n  const essence = normalizeMimeType(mimeType);\n  return essence ? MIME_EXTENSIONS[essence] : undefined;\n}\n\nexport interface NormalizeAudioOptions {\n  /** MIME type override; wins over `AudioInput.mimeType`/`contentType` and Blob type. */\n  mimeType?: string;\n  /**\n   * Maximum payload size in bytes. `undefined` or `Infinity` disables the\n   * limit. Streams are cancelled as soon as they exceed it.\n   */\n  maxBytes?: number;\n  /** Adapter name recorded on configuration errors. */\n  adapter?: string;\n  /** Aborts buffering (including a pending stream read) with the signal's reason. */\n  signal?: AbortSignal;\n  /** Base filename (without extension) used when the input has none. */\n  defaultBasename?: string;\n  /** Append a MIME-derived extension to the default filename. Default `true`. */\n  deriveExtension?: boolean;\n}\n\nexport interface NormalizedAudio {\n  blob: Blob;\n  /** Full MIME type including parameters, or `application/octet-stream`. */\n  mimeType: string;\n  bytes: number;\n  /** Explicit filename, or `<basename>.<ext>` derived from the MIME type. */\n  filename: string;\n  durationSeconds?: number;\n}\n\n/**\n * Accepts either an {@link AudioInput} wrapper or a bare {@link AudioSource}\n * and returns a size-checked Blob plus the metadata needed for multipart\n * uploads.\n */\nexport async function normalizeAudioInput(\n  input: AudioInput | AudioSource,\n  options: NormalizeAudioOptions = {},\n): Promise<NormalizedAudio> {\n  const wrapped: AudioInput = isAudioInput(input) ? input : { data: input };\n  const { adapter, signal } = options;\n  signal?.throwIfAborted();\n  const maxBytes = resolveMaxBytes(options.maxBytes, adapter);\n  const data = wrapped.data;\n\n  const blobType =\n    typeof Blob !== 'undefined' && data instanceof Blob ? data.type : undefined;\n  const mimeType =\n    options.mimeType ??\n    wrapped.mimeType ??\n    wrapped.contentType ??\n    (blobType || undefined) ??\n    'application/octet-stream';\n\n  let blob: Blob;\n  if (typeof Blob !== 'undefined' && data instanceof Blob) {\n    assertWithinLimit(data.size, maxBytes, adapter);\n    blob = data.type === mimeType ? data : new Blob([data], { type: mimeType });\n  } else if (data instanceof Uint8Array) {\n    assertWithinLimit(data.byteLength, maxBytes, adapter);\n    blob = new Blob([copyBytes(data)], { type: mimeType });\n  } else if (data instanceof ArrayBuffer) {\n    assertWithinLimit(data.byteLength, maxBytes, adapter);\n    blob = new Blob([data], { type: mimeType });\n  } else if (isReadableStream(data)) {\n    const chunks = await readStreamWithLimit(data, maxBytes, adapter, signal);\n    blob = new Blob(chunks, { type: mimeType });\n  } else {\n    throw new SpeechConfigurationError(\n      'Unsupported audio input: expected Blob, Buffer, Uint8Array, ArrayBuffer, or ReadableStream',\n      adapter,\n    );\n  }\n\n  if (blob.size === 0) {\n    throw new SpeechConfigurationError('Audio input is empty', adapter);\n  }\n\n  const extension =\n    options.deriveExtension === false\n      ? undefined\n      : mimeTypeToAudioExtension(mimeType);\n  const basename = options.defaultBasename ?? 'audio';\n  const filename =\n    wrapped.filename ?? (extension ? `${basename}.${extension}` : basename);\n\n  return {\n    blob,\n    mimeType,\n    bytes: blob.size,\n    filename,\n    durationSeconds: wrapped.durationSeconds,\n  };\n}\n\nfunction isAudioInput(value: AudioInput | AudioSource): value is AudioInput {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'data' in value &&\n    !(typeof Blob !== 'undefined' && value instanceof Blob) &&\n    !(value instanceof Uint8Array) &&\n    !(value instanceof ArrayBuffer) &&\n    !isReadableStream(value)\n  );\n}\n\nfunction isReadableStream(value: unknown): value is ReadableStream<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as ReadableStream).getReader === 'function'\n  );\n}\n\nfunction resolveMaxBytes(\n  maxBytes: number | undefined,\n  adapter: string | undefined,\n): number {\n  if (maxBytes === undefined) {\n    return Number.POSITIVE_INFINITY;\n  }\n\n  if (Number.isNaN(maxBytes) || maxBytes <= 0) {\n    throw new SpeechConfigurationError(\n      'maxBytes must be a positive number',\n      adapter,\n    );\n  }\n\n  return maxBytes;\n}\n\nfunction assertWithinLimit(\n  bytes: number,\n  maxBytes: number,\n  adapter: string | undefined,\n): void {\n  if (bytes > maxBytes) {\n    throw new SpeechConfigurationError(\n      `Audio input exceeds maxBytes (${bytes} > ${maxBytes} bytes)`,\n      adapter,\n    );\n  }\n}\n\nasync function readStreamWithLimit(\n  stream: ReadableStream<unknown>,\n  maxBytes: number,\n  adapter: string | undefined,\n  signal: AbortSignal | undefined,\n): Promise<Uint8Array<ArrayBuffer>[]> {\n  const reader = stream.getReader();\n  const chunks: Uint8Array<ArrayBuffer>[] = [];\n  let total = 0;\n  // Cancelling the reader settles any pending read, so an abort cannot hang.\n  const onAbort = () => {\n    reader.cancel(signal?.reason).catch(() => undefined);\n  };\n  signal?.addEventListener('abort', onAbort, { once: true });\n\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n      signal?.throwIfAborted();\n      if (done) {\n        break;\n      }\n\n      // Check the size before copying so one oversized chunk is never duplicated.\n      total += chunkByteLength(value, adapter);\n      if (total > maxBytes) {\n        await reader.cancel().catch(() => undefined);\n        throw new SpeechConfigurationError(\n          `Audio stream exceeds maxBytes (more than ${maxBytes} bytes)`,\n          adapter,\n        );\n      }\n      chunks.push(toBytes(value));\n    }\n  } finally {\n    signal?.removeEventListener('abort', onAbort);\n    reader.releaseLock();\n  }\n\n  return chunks;\n}\n\nfunction chunkByteLength(value: unknown, adapter: string | undefined): number {\n  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {\n    return value.byteLength;\n  }\n\n  throw new SpeechConfigurationError(\n    'Audio stream chunks must be Uint8Array or ArrayBuffer',\n    adapter,\n  );\n}\n\nfunction toBytes(value: unknown): Uint8Array<ArrayBuffer> {\n  return value instanceof Uint8Array\n    ? copyBytes(value)\n    : new Uint8Array((value as ArrayBuffer).slice(0));\n}\n\nfunction copyBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer> {\n  const copy = new Uint8Array(bytes.byteLength);\n  copy.set(bytes);\n  return copy;\n}\n","/**\n * Usage reporting shared by speech adapters.\n *\n * Adapters attach a {@link SpeechUsage} record to their results and call the\n * optional {@link SpeechUsageCallback} so callers can attribute each provider\n * call (for example to a tenant for billing).\n */\n\nexport type SpeechOperation = 'transcription' | 'synthesis';\n\nexport interface SpeechUsage {\n  /** Operation that produced this usage record. */\n  operation: SpeechOperation;\n  /** Adapter type that made the provider call, e.g. `openai-compatible`. */\n  provider: string;\n  /** Model identifier sent to (or reported by) the provider. */\n  model?: string;\n  /** Audio duration in seconds, when the provider or caller reports it. */\n  audioSeconds?: number;\n  /** Size of the audio payload in bytes (uploaded for STT, received for TTS). */\n  bytes?: number;\n  /** Provider usage block, passed through untouched (e.g. OpenAI `usage`). */\n  providerUsage?: Record<string, unknown>;\n}\n\nexport type SpeechUsageCallback = (usage: SpeechUsage) => void | Promise<void>;\n\n/**\n * Invokes every configured usage callback in order (adapter-level first, then\n * request-level). Callback errors propagate to the caller so that billing\n * hooks never fail silently.\n */\nexport async function reportSpeechUsage(\n  usage: SpeechUsage,\n  ...callbacks: Array<SpeechUsageCallback | undefined>\n): Promise<void> {\n  for (const callback of callbacks) {\n    if (callback) {\n      await callback(usage);\n    }\n  }\n}\n\n/**\n * Extracts audio seconds from an OpenAI-style `usage` block\n * (`{ type: 'duration', seconds }`).\n */\nexport function audioSecondsFromProviderUsage(\n  providerUsage: Record<string, unknown> | undefined,\n): number | undefined {\n  if (!providerUsage) {\n    return undefined;\n  }\n\n  const seconds = providerUsage.seconds;\n  return typeof seconds === 'number' && Number.isFinite(seconds)\n    ? seconds\n    : undefined;\n}\n","/**\n * Environment configuration for speech adapters.\n *\n * Transcriber settings resolve in this order (first wins):\n * explicit options → factory context → `HAVE_SPEECH_TRANSCRIBER_*` →\n * legacy `HAVE_SPEECH_STT_*` → gateway `STT_*` aliases.\n */\n\nimport { SpeechConfigurationError } from './errors.js';\nimport type { SpeechFetch } from './types.js';\n\nexport interface SpeechEnv {\n  [key: string]: string | undefined;\n}\n\n/** Environment variable names read for each transcriber setting, in priority order. */\nexport const TRANSCRIBER_ENV_KEYS = {\n  type: [\n    'HAVE_SPEECH_TRANSCRIBER_TYPE',\n    'HAVE_SPEECH_STT_TYPE',\n    'HAVE_SPEECH_STT_ADAPTER',\n    'STT_ADAPTER',\n  ],\n  baseUrl: [\n    'HAVE_SPEECH_TRANSCRIBER_BASE_URL',\n    'HAVE_SPEECH_STT_BASE_URL',\n    'STT_BASE_URL',\n  ],\n  model: [\n    'HAVE_SPEECH_TRANSCRIBER_MODEL',\n    'HAVE_SPEECH_STT_MODEL',\n    'STT_MODEL',\n  ],\n  apiKey: [\n    'HAVE_SPEECH_TRANSCRIBER_API_KEY',\n    'HAVE_SPEECH_STT_API_KEY',\n    'STT_API_KEY',\n    'SPEECH_API_KEY',\n  ],\n  timeoutMs: [\n    'HAVE_SPEECH_TRANSCRIBER_TIMEOUT',\n    'HAVE_SPEECH_TRANSCRIBER_TIMEOUT_MS',\n    'HAVE_SPEECH_STT_TIMEOUT_MS',\n    'STT_TIMEOUT_MS',\n  ],\n  maxBytes: ['HAVE_SPEECH_TRANSCRIBER_MAX_BYTES', 'STT_MAX_BYTES'],\n  headers: ['HAVE_SPEECH_TRANSCRIBER_HEADERS', 'STT_HEADERS'],\n  path: ['HAVE_SPEECH_TRANSCRIBER_PATH', 'HAVE_SPEECH_STT_PATH', 'STT_PATH'],\n} as const;\n\n/** Transcriber settings read from the environment. All fields are optional. */\nexport interface TranscriberEnvConfig {\n  type?: string;\n  baseUrl?: string;\n  model?: string;\n  apiKey?: string;\n  timeoutMs?: number;\n  maxBytes?: number;\n  headers?: Record<string, string>;\n  path?: string;\n}\n\n/** Options shape accepted by {@link resolveTranscriberConfig}. */\nexport interface TranscriberConfigInput {\n  type?: string;\n  baseUrl?: string;\n  model?: string;\n  apiKey?: string;\n  timeoutMs?: number;\n  maxBytes?: number;\n  headers?: HeadersInit;\n  fetch?: SpeechFetch;\n}\n\nexport interface TranscriberConfigContext {\n  env?: SpeechEnv;\n  fetch?: SpeechFetch;\n  headers?: HeadersInit;\n}\n\n/** Resolved transcriber settings. `headers` merges env → context → options. */\nexport interface ResolvedTranscriberConfig {\n  type?: string;\n  baseUrl?: string;\n  model?: string;\n  apiKey?: string;\n  timeoutMs?: number;\n  maxBytes?: number;\n  headers?: Headers;\n  fetch?: SpeechFetch;\n  path?: string;\n}\n\nexport function readTranscriberEnv(env: SpeechEnv): TranscriberEnvConfig {\n  return {\n    type: readEnv(env, ...TRANSCRIBER_ENV_KEYS.type),\n    baseUrl: readEnv(env, ...TRANSCRIBER_ENV_KEYS.baseUrl),\n    model: readEnv(env, ...TRANSCRIBER_ENV_KEYS.model),\n    apiKey: readEnv(env, ...TRANSCRIBER_ENV_KEYS.apiKey),\n    timeoutMs: parseOptionalInteger(\n      readEnv(env, ...TRANSCRIBER_ENV_KEYS.timeoutMs),\n    ),\n    maxBytes: parseOptionalInteger(\n      readEnv(env, ...TRANSCRIBER_ENV_KEYS.maxBytes),\n    ),\n    headers: parseHeadersEnv(env, TRANSCRIBER_ENV_KEYS.headers),\n    path: readEnv(env, ...TRANSCRIBER_ENV_KEYS.path),\n  };\n}\n\nexport function hasTranscriberEnv(env: SpeechEnv): boolean {\n  return hasAnyEnv(\n    env,\n    ...TRANSCRIBER_ENV_KEYS.type,\n    ...TRANSCRIBER_ENV_KEYS.baseUrl,\n  );\n}\n\n/**\n * Merges explicit transcriber options with the factory context and the\n * environment. Explicit options always win; headers are merged so a\n * per-deployment env header (e.g. a gateway virtual key) can be combined with\n * explicit ones.\n */\nexport function resolveTranscriberConfig(\n  options: TranscriberConfigInput = {},\n  context: TranscriberConfigContext = {},\n): ResolvedTranscriberConfig {\n  const fromEnv = readTranscriberEnv(context.env ?? defaultEnv());\n  const headers = mergeHeaderInits(\n    fromEnv.headers,\n    context.headers,\n    options.headers,\n  );\n\n  return {\n    type: options.type ?? fromEnv.type,\n    baseUrl: (options.baseUrl ?? fromEnv.baseUrl)?.trim(),\n    model: options.model ?? fromEnv.model,\n    apiKey: options.apiKey ?? fromEnv.apiKey,\n    timeoutMs: options.timeoutMs ?? fromEnv.timeoutMs,\n    maxBytes: options.maxBytes ?? fromEnv.maxBytes,\n    headers,\n    fetch: options.fetch ?? context.fetch,\n    path: fromEnv.path,\n  };\n}\n\n/** Merges header sets left to right; later sets win per header name. */\nexport function mergeHeaderInits(\n  ...sets: Array<HeadersInit | undefined>\n): Headers | undefined {\n  const present = sets.filter((set): set is HeadersInit => Boolean(set));\n  if (present.length === 0) {\n    return undefined;\n  }\n\n  const merged = new Headers();\n  for (const set of present) {\n    new Headers(set).forEach((value, key) => {\n      merged.set(key, value);\n    });\n  }\n  return merged;\n}\n\nexport function readEnv(env: SpeechEnv, ...keys: string[]): string | undefined {\n  for (const key of keys) {\n    const value = env[key];\n    if (value?.trim()) {\n      return value.trim();\n    }\n  }\n\n  return undefined;\n}\n\nexport function hasAnyEnv(env: SpeechEnv, ...keys: string[]): boolean {\n  return keys.some((key) => Boolean(env[key]?.trim()));\n}\n\nexport function parseOptionalInteger(\n  value: string | undefined,\n): number | undefined {\n  if (!value) {\n    return undefined;\n  }\n\n  const parsed = Number.parseInt(value, 10);\n  return Number.isFinite(parsed) ? parsed : undefined;\n}\n\nexport function defaultEnv(): SpeechEnv {\n  return globalThis.process?.env ?? {};\n}\n\n/**\n * Parses a JSON object of header names to string values. The raw value is\n * never echoed in errors because it may carry credentials.\n */\nexport function parseHeadersEnv(\n  env: SpeechEnv,\n  keys: readonly string[],\n): Record<string, string> | undefined {\n  for (const key of keys) {\n    const raw = env[key]?.trim();\n    if (!raw) {\n      continue;\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      throw new SpeechConfigurationError(\n        `${key} must be a JSON object of header names to string values`,\n      );\n    }\n\n    if (\n      !parsed ||\n      typeof parsed !== 'object' ||\n      Array.isArray(parsed) ||\n      !Object.values(parsed).every((value) => typeof value === 'string')\n    ) {\n      throw new SpeechConfigurationError(\n        `${key} must be a JSON object of header names to string values`,\n      );\n    }\n\n    return parsed as Record<string, string>;\n  }\n\n  return undefined;\n}\n","/**\n * Registry for opt-in transcriber adapters that live behind subpath exports\n * (e.g. `@happyvertical/speech/local`).\n *\n * The core entry never imports those adapters, so their heavy optional peer\n * dependencies are never resolved by bundlers or loaded at runtime unless the\n * caller imports the subpath, which registers its factory here.\n */\n\nimport type { SpeechFactoryContext } from './factory.js';\nimport type {\n  GetTranscriberOptions,\n  Transcriber,\n  TranscriberType,\n} from './types.js';\n\nexport type OptionalTranscriberFactory = (\n  options: GetTranscriberOptions,\n  context: SpeechFactoryContext,\n) => Transcriber | Promise<Transcriber>;\n\n/** Adapter types that are only available after importing a subpath. */\nconst OPTIONAL_TRANSCRIBER_ENTRIES: Partial<Record<TranscriberType, string>> = {\n  local: '@happyvertical/speech/local',\n};\n\nconst registered = new Map<TranscriberType, OptionalTranscriberFactory>();\n\nexport function registerOptionalTranscriber(\n  type: TranscriberType,\n  factory: OptionalTranscriberFactory,\n): void {\n  registered.set(type, factory);\n}\n\nexport function getOptionalTranscriberFactory(\n  type: string,\n): OptionalTranscriberFactory | undefined {\n  return registered.get(type as TranscriberType);\n}\n\n/** Subpath that registers `type`, when it is an opt-in adapter. */\nexport function optionalTranscriberEntry(type: string): string | undefined {\n  return OPTIONAL_TRANSCRIBER_ENTRIES[type as TranscriberType];\n}\n\nexport function registeredOptionalTranscribers(): TranscriberType[] {\n  return [...registered.keys()];\n}\n"],"mappings":"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"}

package/dist/chunks/websocket-CR9uXAuS.js

@@ -0,0 +1,44 @@
+import { n as SpeechConfigurationError } from "./errors-CQBX3OPS.js";
+//#region src/shared/websocket.ts
+/**
+* Minimal WebSocket surface used by streaming adapters. Browser, Node 22+
+* (`globalThis.WebSocket`), Deno, Bun, and the `ws` package all satisfy it.
+*/
+/** True in browsers and web workers, where API keys must never be used. */
+function isBrowserRuntime() {
+	const scope = globalThis;
+	if (scope.process?.versions?.node) return false;
+	return typeof scope.document !== "undefined" || typeof scope.WorkerGlobalScope !== "undefined";
+}
+/**
+* Resolves a socket factory from explicit options, falling back to
+* `globalThis.WebSocket`. Headers are only passed when present, so standard
+* constructors that cannot send them are never handed an options object.
+*/
+function resolveWebSocketFactory(adapter, options) {
+	if (options.createWebSocket) return options.createWebSocket;
+	const Ctor = options.WebSocket ?? globalThis.WebSocket;
+	if (!Ctor) throw new SpeechConfigurationError("No WebSocket implementation available; pass `WebSocket` or `createWebSocket`", adapter);
+	return (url, init) => Object.keys(init.headers).length > 0 ? new Ctor(url, {
+		protocols: init.protocols,
+		headers: init.headers
+	}) : new Ctor(url, init.protocols);
+}
+/** Converts `http(s)://` to `ws(s)://`; leaves `ws(s)://` unchanged. */
+function toWebSocketUrl(url, adapter) {
+	const parsed = new URL(url);
+	if (parsed.protocol === "http:") parsed.protocol = "ws:";
+	else if (parsed.protocol === "https:") parsed.protocol = "wss:";
+	else if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") throw new SpeechConfigurationError(`Unsupported streaming URL protocol: ${parsed.protocol}`, adapter);
+	return parsed.toString();
+}
+/** Converts a message payload to text; returns `undefined` for unsupported data. */
+function messageDataToText(data) {
+	if (typeof data === "string") return data;
+	if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+	if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data);
+}
+//#endregion
+export { toWebSocketUrl as i, messageDataToText as n, resolveWebSocketFactory as r, isBrowserRuntime as t };
+
+//# sourceMappingURL=websocket-CR9uXAuS.js.map

package/dist/chunks/websocket-CR9uXAuS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-CR9uXAuS.js","names":[],"sources":["../../src/shared/websocket.ts"],"sourcesContent":["/**\n * Minimal WebSocket surface used by streaming adapters. Browser, Node 22+\n * (`globalThis.WebSocket`), Deno, Bun, and the `ws` package all satisfy it.\n */\n\nimport { SpeechConfigurationError } from './errors.js';\n\n/** `WebSocket.OPEN`. */\nexport const WEBSOCKET_OPEN = 1;\n\nexport interface SpeechWebSocketMessageEvent {\n  data: unknown;\n}\n\nexport interface SpeechWebSocketCloseEvent {\n  code?: number;\n  reason?: string;\n}\n\n/** The subset of the WHATWG `WebSocket` interface the adapters use. */\nexport interface SpeechWebSocket {\n  readonly readyState: number;\n  readonly bufferedAmount: number;\n  binaryType?: string;\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  addEventListener(type: 'open', listener: (event: unknown) => void): void;\n  addEventListener(\n    type: 'message',\n    listener: (event: SpeechWebSocketMessageEvent) => void,\n  ): void;\n  addEventListener(type: 'error', listener: (event: unknown) => void): void;\n  addEventListener(\n    type: 'close',\n    listener: (event: SpeechWebSocketCloseEvent) => void,\n  ): void;\n}\n\n/** Handshake details passed to a {@link SpeechWebSocketFactory}. */\nexport interface SpeechWebSocketInit {\n  protocols: string[];\n  /** Handshake headers; empty in browsers. */\n  headers: Record<string, string>;\n}\n\nexport type SpeechWebSocketFactory = (\n  url: string,\n  init: SpeechWebSocketInit,\n) => SpeechWebSocket;\n\n/**\n * A WebSocket constructor. Standard constructors accept `protocols`; Node's\n * built-in WebSocket also accepts `{ protocols, headers }`.\n */\nexport type SpeechWebSocketConstructor = new (\n  url: string,\n  protocols?:\n    | string\n    | string[]\n    | { protocols?: string[]; headers?: Record<string, string> },\n) => SpeechWebSocket;\n\n/** True in browsers and web workers, where API keys must never be used. */\nexport function isBrowserRuntime(): boolean {\n  const scope = globalThis as {\n    document?: unknown;\n    WorkerGlobalScope?: unknown;\n    process?: { versions?: { node?: string } };\n  };\n  if (scope.process?.versions?.node) {\n    return false;\n  }\n  return (\n    typeof scope.document !== 'undefined' ||\n    typeof scope.WorkerGlobalScope !== 'undefined'\n  );\n}\n\n/**\n * Resolves a socket factory from explicit options, falling back to\n * `globalThis.WebSocket`. Headers are only passed when present, so standard\n * constructors that cannot send them are never handed an options object.\n */\nexport function resolveWebSocketFactory(\n  adapter: string,\n  options: {\n    createWebSocket?: SpeechWebSocketFactory;\n    WebSocket?: SpeechWebSocketConstructor;\n  },\n): SpeechWebSocketFactory {\n  if (options.createWebSocket) {\n    return options.createWebSocket;\n  }\n\n  const Ctor =\n    options.WebSocket ??\n    (globalThis as { WebSocket?: SpeechWebSocketConstructor }).WebSocket;\n  if (!Ctor) {\n    throw new SpeechConfigurationError(\n      'No WebSocket implementation available; pass `WebSocket` or `createWebSocket`',\n      adapter,\n    );\n  }\n\n  return (url, init) =>\n    Object.keys(init.headers).length > 0\n      ? new Ctor(url, { protocols: init.protocols, headers: init.headers })\n      : new Ctor(url, init.protocols);\n}\n\n/** Converts `http(s)://` to `ws(s)://`; leaves `ws(s)://` unchanged. */\nexport function toWebSocketUrl(url: string, adapter: string): string {\n  const parsed = new URL(url);\n  if (parsed.protocol === 'http:') {\n    parsed.protocol = 'ws:';\n  } else if (parsed.protocol === 'https:') {\n    parsed.protocol = 'wss:';\n  } else if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {\n    throw new SpeechConfigurationError(\n      `Unsupported streaming URL protocol: ${parsed.protocol}`,\n      adapter,\n    );\n  }\n  return parsed.toString();\n}\n\n/** Converts a message payload to text; returns `undefined` for unsupported data. */\nexport function messageDataToText(data: unknown): string | undefined {\n  if (typeof data === 'string') {\n    return data;\n  }\n  if (data instanceof ArrayBuffer) {\n    return new TextDecoder().decode(data);\n  }\n  if (ArrayBuffer.isView(data)) {\n    return new TextDecoder().decode(data);\n  }\n  return undefined;\n}\n"],"mappings":";;;;;;;AA+DA,SAAgB,mBAA4B;CAC1C,MAAM,QAAQ;CAKd,IAAI,MAAM,SAAS,UAAU,MAC3B,OAAO;CAET,OACE,OAAO,MAAM,aAAa,eAC1B,OAAO,MAAM,sBAAsB;AAEvC;;;;;;AAOA,SAAgB,wBACd,SACA,SAIwB;CACxB,IAAI,QAAQ,iBACV,OAAO,QAAQ;CAGjB,MAAM,OACJ,QAAQ,aACP,WAA0D;CAC7D,IAAI,CAAC,MACH,MAAM,IAAI,yBACR,gFACA,OACF;CAGF,QAAQ,KAAK,SACX,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS,IAC/B,IAAI,KAAK,KAAK;EAAE,WAAW,KAAK;EAAW,SAAS,KAAK;CAAQ,CAAC,IAClE,IAAI,KAAK,KAAK,KAAK,SAAS;AACpC;;AAGA,SAAgB,eAAe,KAAa,SAAyB;CACnE,MAAM,SAAS,IAAI,IAAI,GAAG;CAC1B,IAAI,OAAO,aAAa,SACtB,OAAO,WAAW;MACb,IAAI,OAAO,aAAa,UAC7B,OAAO,WAAW;MACb,IAAI,OAAO,aAAa,SAAS,OAAO,aAAa,QAC1D,MAAM,IAAI,yBACR,uCAAuC,OAAO,YAC9C,OACF;CAEF,OAAO,OAAO,SAAS;AACzB;;AAGA,SAAgB,kBAAkB,MAAmC;CACnE,IAAI,OAAO,SAAS,UAClB,OAAO;CAET,IAAI,gBAAgB,aAClB,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,IAAI;CAEtC,IAAI,YAAY,OAAO,IAAI,GACzB,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,IAAI;AAGxC"}

package/dist/conversation/openai-webrtc.d.ts

@@ -0,0 +1,4 @@
+import { OpenAIWebRTCVoiceOptions, VoiceSession } from './types.js';
+/** Browser WebRTC transport. No credentials, Node dependencies or globals are read at import. */
+export declare function createOpenAIWebRTCVoiceSession(options: OpenAIWebRTCVoiceOptions): VoiceSession;
+//# sourceMappingURL=openai-webrtc.d.ts.map

package/dist/conversation/openai-webrtc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-webrtc.d.ts","sourceRoot":"","sources":["../../src/conversation/openai-webrtc.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,wBAAwB,EACxB,YAAY,EAIb,MAAM,YAAY,CAAC;AAIpB,iGAAiG;AACjG,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,wBAAwB,GAChC,YAAY,CAmbd"}

package/dist/conversation/types.d.ts

@@ -0,0 +1,60 @@
+/** Additive speech-to-speech conversation contract; independent of streaming STT. */
+export type VoiceSessionState = 'idle' | 'connecting' | 'connected' | 'closed' | 'failed';
+export interface VoiceTranscript {
+    itemId: string;
+    role: 'user' | 'assistant';
+    text: string;
+    final: boolean;
+}
+export interface VoiceSessionEvents {
+    state: VoiceSessionState;
+    transcript: VoiceTranscript;
+    /** Actual remote playback, rather than model response generation. */
+    speaking: boolean;
+    inputSpeech: boolean;
+    response: {
+        active: boolean;
+        responseId?: string;
+    };
+    usage: Record<string, unknown>;
+    toolCall: {
+        callId: string;
+        name: string;
+        arguments: string;
+    };
+    /** Recoverable protocol/playback errors also use this event. */
+    error: Error;
+}
+export interface VoiceSession {
+    readonly state: VoiceSessionState;
+    /** Coalesced while connecting; terminal sessions cannot be reconnected. */
+    connect(): Promise<void>;
+    sendText(text: string): string;
+    /** Commit buffered microphone input in manual turn mode, then optionally generate a reply. */
+    commitInput(respond?: boolean): void;
+    /** Request a response, e.g. an opening introduction. */
+    respond(instructions?: string): void;
+    /** Cancels active generation and clears unplayed WebRTC audio. */
+    interrupt(): void;
+    setMicMuted(muted: boolean): void;
+    setOutputMuted(muted: boolean): void;
+    /** Submit a tool output without generating a reply. After every tool in the completed response resolves, the host calls respond() once. */
+    submitToolResult(callId: string, result: unknown): void;
+    /** Idempotently releases tracks, peer connection, playback and listeners. */
+    close(): void;
+    on<E extends keyof VoiceSessionEvents>(event: E, listener: (value: VoiceSessionEvents[E]) => void): () => void;
+}
+export interface OpenAIWebRTCVoiceOptions {
+    /** Host-authenticated negotiation: post the offer to your server, return its answer. */
+    negotiate(offer: string, signal: AbortSignal): Promise<string>;
+    /** Called during connect. Ownership transfers to the session, including late resolution. */
+    getMicrophone(): Promise<MediaStream>;
+    audio?: HTMLAudioElement;
+    createPeerConnection?: () => RTCPeerConnection;
+    connectTimeoutMs?: number;
+    /** Starts muted to let the host introduce its character before listening. Default false. */
+    micMuted?: boolean;
+    outputMuted?: boolean;
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/conversation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/conversation/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,eAAe,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,gEAAgE;IAChE,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,2EAA2E;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,8FAA8F;IAC9F,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,wDAAwD;IACxD,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,kEAAkE;IAClE,SAAS,IAAI,IAAI,CAAC;IAClB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,2IAA2I;IAC3I,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACxD,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACnC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC/C,MAAM,IAAI,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,4FAA4F;IAC5F,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,iBAAiB,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/dist/conversation-server.d.ts

@@ -0,0 +1,40 @@
+import { SpeechProviderError } from './shared/errors.js';
+import { StreamingTurnDetection } from './shared/streaming-types.js';
+import { SpeechFetch } from './shared/types.js';
+export interface OpenAIVoiceCallOptions {
+    apiKey: string;
+    /** Fixed by the host, never copied from untrusted browser JSON. */
+    model: string;
+    voice?: string;
+    instructions?: string;
+    transcriptionModel?: string;
+    turnDetection?: StreamingTurnDetection;
+    maxOutputTokens?: number;
+    tools?: Array<{
+        type: 'function';
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    }>;
+    baseUrl?: string;
+    fetch?: SpeechFetch;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface OpenAIVoiceCall {
+    answer: string;
+    callId: string;
+}
+/** Build the GA speech-to-speech session config. Transcription is an optional side channel. */
+export declare function openAIConversationConfig(options: Pick<OpenAIVoiceCallOptions, 'model' | 'voice' | 'instructions' | 'transcriptionModel' | 'turnDetection' | 'maxOutputTokens' | 'tools'>): Record<string, unknown>;
+/** No retries: retrying call creation can create duplicate billable sessions. */
+export declare function createOpenAIVoiceCall(offer: string, options: OpenAIVoiceCallOptions): Promise<OpenAIVoiceCall>;
+export type OpenAIVoiceCallControlOptions = Pick<OpenAIVoiceCallOptions, 'apiKey' | 'baseUrl' | 'fetch' | 'signal' | 'timeoutMs'>;
+/** Hosts should call this on close, idle/hard timeout and failed client setup. */
+export declare function hangupOpenAIVoiceCall(callId: string, options: OpenAIVoiceCallControlOptions): Promise<void>;
+/** Failed setup whose cleanup also failed. The host must reserve admission and retry termination. */
+export declare class VoiceCallSetupError extends SpeechProviderError {
+    readonly callId: string;
+    constructor(callId: string);
+}
+//# sourceMappingURL=conversation-server.d.ts.map

package/dist/conversation-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-server.d.ts","sourceRoot":"","sources":["../src/conversation-server.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,OAAO,EAEL,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,IAAI,CACX,sBAAsB,EACpB,OAAO,GACP,OAAO,GACP,cAAc,GACd,oBAAoB,GACpB,eAAe,GACf,iBAAiB,GACjB,OAAO,CACV,GACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0DzB;AAED,iFAAiF;AACjF,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA0C1B;AAED,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAC9C,sBAAsB,EACtB,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CACxD,CAAC;AAEF,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAKf;AAuFD,qGAAqG;AACrG,qBAAa,mBAAoB,SAAQ,mBAAmB;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAMpC"}