@providerkit/core 0.29.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +25 -4
  2. package/dist/errors.d.ts.map +1 -1
  3. package/dist/errors.js +29 -2
  4. package/dist/errors.js.map +1 -1
  5. package/dist/jev.d.ts +123 -0
  6. package/dist/jev.d.ts.map +1 -0
  7. package/dist/jev.js +278 -0
  8. package/dist/jev.js.map +1 -0
  9. package/dist/presets.d.ts +35 -4
  10. package/dist/presets.d.ts.map +1 -1
  11. package/dist/presets.js +32 -8
  12. package/dist/presets.js.map +1 -1
  13. package/dist/providers/deepgram-transcription.d.ts +24 -0
  14. package/dist/providers/deepgram-transcription.d.ts.map +1 -0
  15. package/dist/providers/deepgram-transcription.js +84 -0
  16. package/dist/providers/deepgram-transcription.js.map +1 -0
  17. package/dist/providers/elevenlabs-speech.d.ts +1 -1
  18. package/dist/providers/elevenlabs-speech.d.ts.map +1 -1
  19. package/dist/providers/elevenlabs-speech.js +1 -1
  20. package/dist/providers/elevenlabs-speech.js.map +1 -1
  21. package/dist/providers/openai-transcription.d.ts +21 -0
  22. package/dist/providers/openai-transcription.d.ts.map +1 -0
  23. package/dist/providers/openai-transcription.js +144 -0
  24. package/dist/providers/openai-transcription.js.map +1 -0
  25. package/dist/providers/transcription-factory.d.ts +30 -0
  26. package/dist/providers/transcription-factory.d.ts.map +1 -0
  27. package/dist/providers/transcription-factory.js +38 -0
  28. package/dist/providers/transcription-factory.js.map +1 -0
  29. package/dist/speech-core.d.ts +2 -17
  30. package/dist/speech-core.d.ts.map +1 -1
  31. package/dist/speech-core.js +10 -50
  32. package/dist/speech-core.js.map +1 -1
  33. package/dist/transcription-core.d.ts +146 -0
  34. package/dist/transcription-core.d.ts.map +1 -0
  35. package/dist/transcription-core.js +193 -0
  36. package/dist/transcription-core.js.map +1 -0
  37. package/dist/transcription.d.ts +7 -0
  38. package/dist/transcription.d.ts.map +1 -0
  39. package/dist/transcription.js +12 -0
  40. package/dist/transcription.js.map +1 -0
  41. package/dist/transport.d.ts +26 -0
  42. package/dist/transport.d.ts.map +1 -1
  43. package/dist/transport.js +57 -2
  44. package/dist/transport.js.map +1 -1
  45. package/package.json +5 -1
  46. package/src/errors.ts +35 -2
  47. package/src/presets.ts +54 -8
  48. package/src/providers/deepgram-transcription.ts +109 -0
  49. package/src/providers/elevenlabs-speech.ts +2 -2
  50. package/src/providers/openai-transcription.ts +177 -0
  51. package/src/providers/transcription-factory.ts +68 -0
  52. package/src/speech-core.ts +9 -47
  53. package/src/transcription-core.ts +345 -0
  54. package/src/transcription.ts +24 -0
  55. package/src/transport.ts +77 -3
@@ -0,0 +1,177 @@
1
+ // The OpenAI transcription wire: POST {base}/audio/transcriptions, multipart in, JSON out.
2
+ // Serves OpenAI and any server that copies the route (Groq, a local Whisper server, a proxy).
3
+ // One request per call; transcription-core.ts says why.
4
+ //
5
+ // Three things depend on the model, from OpenAI's speech-to-text guide and transcription
6
+ // reference (read 2026-11-11):
7
+ // - `gpt-transcribe` takes the language as `languages[]`; every other model takes `language`,
8
+ // and the guide says not to send both.
9
+ // - Only `gpt-4o-transcribe-diarize` labels speakers, in `diarized_json`, and it needs a
10
+ // `chunking_strategy` for anything over 30 seconds.
11
+ // - Only Whisper models return timed segments without speakers, in `verbose_json`. The rest
12
+ // answer `json`: the text alone.
13
+ import { attributionHeaders, type Attribution } from "../attribution.ts";
14
+ import {
15
+ asRecord,
16
+ inBandFailure,
17
+ MAX_REPLY_BYTES,
18
+ mediaType,
19
+ parseObject,
20
+ prepareTranscription,
21
+ readSegments,
22
+ resolveLimits,
23
+ seconds,
24
+ transcribeOnce,
25
+ unusable,
26
+ type TranscriptionLimits,
27
+ type TranscriptionProvider,
28
+ type TranscriptionUsage,
29
+ } from "../transcription-core.ts";
30
+ import { apiUrl, postBytes, versionedPath, type FetchLike } from "../transport.ts";
31
+
32
+ export interface OpenAITranscriptionConfig extends TranscriptionLimits, Attribution {
33
+ /** "" sends no Authorization header, for a local server that wants none. */
34
+ apiKey: string;
35
+ model: string;
36
+ /** Default `https://api.openai.com`. */
37
+ baseUrl?: string;
38
+ /** Default `/v1/audio/transcriptions`, or `/audio/transcriptions` when the base already ends
39
+ * in a version. */
40
+ path?: string;
41
+ /** The preset id. Names the provider in errors and on `TranscriptionProvider.id`. Default
42
+ * "openai". */
43
+ id?: string;
44
+ headers?: Record<string, string>;
45
+ /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
46
+ fetchImpl?: FetchLike;
47
+ }
48
+
49
+ // The server reads the format from the file name, so the name carries the extension the media
50
+ // type stands for. The formats are the ones the reference lists.
51
+ const EXTENSION: Readonly<Record<string, string>> = {
52
+ "audio/flac": "flac",
53
+ "audio/x-flac": "flac",
54
+ "audio/mpeg": "mp3",
55
+ "audio/mp3": "mp3",
56
+ "audio/mp4": "m4a",
57
+ "audio/m4a": "m4a",
58
+ "audio/x-m4a": "m4a",
59
+ "video/mp4": "mp4",
60
+ "video/mpeg": "mpeg",
61
+ "audio/ogg": "ogg",
62
+ "audio/wav": "wav",
63
+ "audio/wave": "wav",
64
+ "audio/x-wav": "wav",
65
+ "audio/vnd.wave": "wav",
66
+ "audio/webm": "webm",
67
+ "video/webm": "webm",
68
+ };
69
+
70
+ /** A type the table knows names the file; otherwise a `File` keeps its own name. */
71
+ function fileName(audio: Blob): string {
72
+ const extension = EXTENSION[mediaType(audio.type)];
73
+ if (extension) return `audio.${extension}`;
74
+ return audio instanceof File && audio.name ? audio.name : "audio";
75
+ }
76
+
77
+ const count = (value: unknown): number | undefined =>
78
+ typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
79
+
80
+ /**
81
+ * The provider's own usage, or nothing. Token counts that do not add up are dropped whole: a
82
+ * wrong number in a ledger is worse than a missing one. The audio and text parts are kept only
83
+ * when they fit inside the input.
84
+ */
85
+ function readUsage(raw: unknown): TranscriptionUsage | undefined {
86
+ const usage = asRecord(raw);
87
+ if (usage?.type === "duration") {
88
+ const billed = seconds(usage.seconds);
89
+ return billed === undefined ? undefined : { type: "duration", seconds: billed };
90
+ }
91
+ if (usage?.type !== "tokens") return undefined;
92
+ const input = count(usage.input_tokens);
93
+ const output = count(usage.output_tokens);
94
+ const total = count(usage.total_tokens);
95
+ if (input === undefined || output === undefined || total === undefined) return undefined;
96
+ if (!Number.isSafeInteger(input + output) || total < input + output) return undefined;
97
+ const details = asRecord(usage.input_token_details);
98
+ const audio = count(details?.audio_tokens);
99
+ const text = count(details?.text_tokens);
100
+ const parts = audio !== undefined && text !== undefined && audio + text <= input;
101
+ return {
102
+ type: "tokens",
103
+ inputTokens: input,
104
+ outputTokens: output,
105
+ totalTokens: total,
106
+ ...(parts ? { audioTokens: audio, textTokens: text } : {}),
107
+ };
108
+ }
109
+
110
+ export function createOpenAITranscriptionProvider(
111
+ config: OpenAITranscriptionConfig,
112
+ ): TranscriptionProvider {
113
+ const id = config.id ?? "openai";
114
+ const provider = `transcription:${id}`;
115
+ const baseUrl = config.baseUrl ?? "https://api.openai.com";
116
+ const limits = resolveLimits(config);
117
+ return {
118
+ id,
119
+ model: config.model,
120
+ async transcribe(request) {
121
+ const { audio, model, language, diarize } = prepareTranscription(provider, request, {
122
+ apiKey: config.apiKey,
123
+ keyRequired: false,
124
+ model: config.model,
125
+ maxAudioBytes: limits.maxAudioBytes,
126
+ });
127
+ return transcribeOnce(provider, limits.timeoutMs, request, async (signal) => {
128
+ const form = new FormData();
129
+ form.append("file", audio, fileName(audio));
130
+ form.append("model", model);
131
+ // The models take ISO 639-1 ("pt"), so a BCP-47 tag goes as its language subtag.
132
+ if (language) {
133
+ const code = language.split("-")[0]!.toLowerCase();
134
+ form.append(model.startsWith("gpt-transcribe") ? "languages[]" : "language", code);
135
+ }
136
+ if (diarize) {
137
+ // A model that cannot label speakers answers this with a 400, which is the honest
138
+ // refusal: speakers asked for and silently dropped would read as one voice.
139
+ form.append("response_format", "diarized_json");
140
+ form.append("chunking_strategy", "auto");
141
+ } else if (/whisper/i.test(model)) {
142
+ form.append("response_format", "verbose_json");
143
+ }
144
+ const { bytes } = await postBytes({
145
+ url: apiUrl(baseUrl, config.path ?? versionedPath(baseUrl, "/audio/transcriptions")),
146
+ headers: {
147
+ ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
148
+ ...attributionHeaders(config, config.headers),
149
+ ...config.headers,
150
+ },
151
+ body: form,
152
+ provider,
153
+ signal,
154
+ redirect: "error",
155
+ maxBytes: MAX_REPLY_BYTES,
156
+ ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
157
+ });
158
+ const body = parseObject(bytes);
159
+ const usage = readUsage(body?.usage);
160
+ // A failure inside a 200 is still a failure (invariant 11).
161
+ if (body?.error !== undefined && body.error !== null) throw inBandFailure(provider, body);
162
+ if (typeof body?.text !== "string") {
163
+ throw unusable(provider, "the reply holds no transcript", usage);
164
+ }
165
+ const durationSeconds = seconds(body.duration);
166
+ signal.throwIfAborted();
167
+ return {
168
+ text: body.text.trim(),
169
+ segments: readSegments(body.segments, "text", diarize),
170
+ ...(durationSeconds !== undefined ? { durationSeconds } : {}),
171
+ ...(usage ? { usage } : {}),
172
+ model,
173
+ };
174
+ });
175
+ },
176
+ };
177
+ }
@@ -0,0 +1,68 @@
1
+ // The transcription twin of `createSpeechProvider`: name a preset, hand over a key, get a
2
+ // transcription provider. The preset row (`ProviderPreset.transcription`) picks the wire.
3
+ import {
4
+ PROVIDER_PRESETS,
5
+ TRANSCRIPTION_PRESET_IDS,
6
+ type ProviderPreset,
7
+ type ProviderPresetId,
8
+ } from "../presets.ts";
9
+ import type { Attribution } from "../attribution.ts";
10
+ import type { TranscriptionLimits, TranscriptionProvider } from "../transcription-core.ts";
11
+ import { createOpenAITranscriptionProvider } from "./openai-transcription.ts";
12
+ import type { FetchLike } from "../transport.ts";
13
+
14
+ export interface TranscriptionProviderConfig extends TranscriptionLimits, Attribution {
15
+ apiKey: string;
16
+ /** Absent: the preset's `transcription.defaultModel`. A preset without one needs this. */
17
+ model?: string;
18
+ /**
19
+ * Replaces the preset's host, for a server that copies its route (Groq, a local Whisper
20
+ * server, a proxy). The preset's default model is a fact about its own host, so it does not
21
+ * follow you here: pass the `model`.
22
+ */
23
+ baseUrl?: string;
24
+ headers?: Record<string, string>;
25
+ /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
26
+ fetchImpl?: FetchLike;
27
+ }
28
+
29
+ /**
30
+ * Build a transcription provider for a preset that can transcribe. A preset without a
31
+ * `transcription` row throws, naming the ones that do (`TRANSCRIPTION_PRESET_IDS`). Deepgram is
32
+ * not a chat preset: `createDeepgramTranscriptionProvider` builds it.
33
+ *
34
+ * ```ts
35
+ * const listen = createTranscriptionProvider("openai", { apiKey });
36
+ * const { text } = await listen.transcribe({ audio: file });
37
+ * ```
38
+ */
39
+ export function createTranscriptionProvider(
40
+ id: ProviderPresetId,
41
+ config: TranscriptionProviderConfig,
42
+ ): TranscriptionProvider {
43
+ const preset: ProviderPreset = PROVIDER_PRESETS[id];
44
+ const spec = preset.transcription;
45
+ if (!spec) {
46
+ throw new Error(
47
+ `[providerkit] Preset "${id}" has no transcription endpoint. Presets that do: ${TRANSCRIPTION_PRESET_IDS.join(", ")}. Deepgram has its own: createDeepgramTranscriptionProvider.`,
48
+ );
49
+ }
50
+ // A default is a fact about the host that documented it.
51
+ const own = config.baseUrl === undefined;
52
+ const model = config.model ?? (own ? spec.defaultModel : undefined);
53
+ if (!model) {
54
+ throw new Error(
55
+ `[providerkit] Transcription on "${id}" has no default model${own ? "" : " for another host"}. Pass a model.`,
56
+ );
57
+ }
58
+ const shared = {
59
+ ...config,
60
+ id,
61
+ model,
62
+ baseUrl: config.baseUrl ?? spec.baseUrl ?? preset.baseUrl,
63
+ };
64
+ switch (spec.shape) {
65
+ case "openai":
66
+ return createOpenAITranscriptionProvider(shared);
67
+ }
68
+ }
@@ -10,7 +10,7 @@
10
10
  // 2. Audio is named by its own bytes, not by what was asked for. Many servers ignore
11
11
  // the format they were sent, and "WebM with an MP4 name" is not MP4.
12
12
  import { ProviderError, streamError, type ErrorKind } from "./errors.ts";
13
- import { withDeadline } from "./transport.ts";
13
+ import { callOnce, noReplay as sharedNoReplay, type ErrorRebuild } from "./transport.ts";
14
14
  import type { TokenUsage } from "./types.ts";
15
15
 
16
16
  export const SPEECH_FORMATS = ["wav", "pcm", "mp3", "opus", "aac", "flac"] as const;
@@ -178,63 +178,25 @@ export function prepareSpeech(
178
178
  return { text, voice, format };
179
179
  }
180
180
 
181
- const REPLAY_UNSAFE: ReadonlySet<ErrorKind> = new Set<ErrorKind>([
182
- "network",
183
- "timeout",
184
- "overload",
185
- "unknown",
186
- ]);
187
-
188
- function neverRetry(err: ProviderError): ProviderError {
189
- const opts = {
190
- status: err.status,
191
- code: err.code,
192
- retryAfterMs: err.retryAfterMs,
193
- resetAtMs: err.resetAtMs,
194
- window: err.window,
195
- shouldRetry: false,
196
- body: err.body,
197
- cause: err.cause,
198
- };
199
- return err instanceof SpeechError
181
+ /** A `SpeechError` comes back as itself, with the usage it carries. */
182
+ const asSpeechError: ErrorRebuild = (err, opts) =>
183
+ err instanceof SpeechError
200
184
  ? new SpeechError(err.provider, err.kind, err.message, { ...opts, usage: err.usage })
201
185
  : new ProviderError(err.provider, err.kind, err.message, opts);
202
- }
203
186
 
204
- /**
205
- * @internal The "could the vendor already have billed this?" rule, applied in one
206
- * place so a new failure path cannot forget it.
207
- *
208
- * - The caller's Stop comes back untouched.
209
- * - A timeout, a dead socket, a 5xx or anything unclassified may have landed after
210
- * the vendor started work, so it is marked `shouldRetry: false`, and a vendor's
211
- * `x-should-retry: true` does not undo that: the header says the vendor thinks a
212
- * resend is fine, not that the first call was not billed.
213
- * - Every other kind keeps what it came with. A 429 means the vendor refused before
214
- * doing any work, so sending it again is safe, and `Retry-After` is honoured by
215
- * the caller's own retry. `x-should-retry` is believed there, in either direction.
216
- */
187
+ /** @internal The shared no-replay rule (`transport.ts`), keeping a `SpeechError` whole. */
217
188
  export function noReplay(provider: string, error: unknown, signal?: AbortSignal): unknown {
218
- if (signal?.aborted) return error;
219
- const err = ProviderError.from(provider, error);
220
- return REPLAY_UNSAFE.has(err.kind) && err.shouldRetry !== false ? neverRetry(err) : err;
189
+ return sharedNoReplay(provider, error, signal, asSpeechError);
221
190
  }
222
191
 
223
- /**
224
- * @internal The one place a call runs: under one deadline, once, and with the
225
- * no-replay rule applied to whatever it throws. Both wires go through here.
226
- */
227
- export async function synthesizeOnce<T>(
192
+ /** @internal One paid call, once, under one deadline. All three wires go through here. */
193
+ export function synthesizeOnce<T>(
228
194
  provider: string,
229
195
  timeoutMs: number,
230
196
  request: SpeechRequest,
231
197
  call: (signal: AbortSignal) => Promise<T>,
232
198
  ): Promise<T> {
233
- try {
234
- return await withDeadline(provider, timeoutMs, request.signal, call);
235
- } catch (error) {
236
- throw noReplay(provider, error, request.signal);
237
- }
199
+ return callOnce(provider, timeoutMs, request.signal, call, asSpeechError);
238
200
  }
239
201
 
240
202
  // ── failures ──────────────────────────────────────────────────────────────
@@ -0,0 +1,345 @@
1
+ // Transcription: one recording in, its text out. The inverse of speech, and a third kind of
2
+ // client next to `Provider`, reached through `@providerkit/core/transcription` so a chat-only
3
+ // app never loads it.
4
+ //
5
+ // This file holds what both wires share: the types, the error, the checks made before a
6
+ // request, and the rule that a paid transcription is never replayed. A recording is billed by
7
+ // its length the moment the vendor starts on it, so a timeout or a dropped socket after the
8
+ // upload may already have cost money. One request per call (invariant 16).
9
+ import { ProviderError, streamError, type ErrorKind } from "./errors.ts";
10
+ import { callOnce, type ErrorRebuild } from "./transport.ts";
11
+
12
+ /** Which wire listens. A second shape is one new file and one preset row. */
13
+ export type TranscriptionShape = "openai";
14
+
15
+ export interface TranscriptionRequest {
16
+ /**
17
+ * The recording. A `File` is a `Blob`. Its `type` is required ("audio/wav", "audio/mpeg"):
18
+ * Deepgram reads the format from the Content-Type it becomes, OpenAI from the file name it
19
+ * implies. Empty, untyped or over `maxAudioBytes` is refused before any request.
20
+ */
21
+ audio: Blob;
22
+ /** This call's model. Absent: the provider's. */
23
+ model?: string;
24
+ /** BCP-47, such as "pt-BR". Absent: the provider detects the language. */
25
+ language?: string;
26
+ /** Label who speaks each segment. Absent or false: no speaker labels. */
27
+ diarize?: boolean;
28
+ /** The caller's Stop. Never retried and never turned into a timeout. */
29
+ signal?: AbortSignal;
30
+ }
31
+
32
+ export interface TranscriptionSegment {
33
+ /** Seconds from the start of the recording. */
34
+ start: number;
35
+ end: number;
36
+ text: string;
37
+ /**
38
+ * Who spoke, as the provider labels them: Deepgram counts from 0, OpenAI sends a string.
39
+ * Only when `diarize` was asked for and the provider said.
40
+ */
41
+ speaker?: number | string;
42
+ }
43
+
44
+ /**
45
+ * What the provider stated it billed for, in its own unit. Never estimated. Deepgram states
46
+ * none: it bills by the recording's length, which is `durationSeconds`.
47
+ */
48
+ export type TranscriptionUsage =
49
+ | {
50
+ type: "tokens";
51
+ inputTokens: number;
52
+ outputTokens: number;
53
+ totalTokens: number;
54
+ /** The parts of `inputTokens` that were audio and prompt text, when stated. */
55
+ audioTokens?: number;
56
+ textTokens?: number;
57
+ }
58
+ | { type: "duration"; seconds: number };
59
+
60
+ export interface TranscriptionResult {
61
+ /** The whole transcript. "" when nobody spoke. */
62
+ text: string;
63
+ /** Timed pieces of the transcript. Empty when the wire or the model gives none. */
64
+ segments: TranscriptionSegment[];
65
+ /** The recording's length in seconds, as the provider stated it. Never estimated. */
66
+ durationSeconds?: number;
67
+ /** Only when the provider reported it. */
68
+ usage?: TranscriptionUsage;
69
+ /** The model that was asked for. */
70
+ model: string;
71
+ }
72
+
73
+ export interface TranscriptionProvider {
74
+ readonly id: string;
75
+ readonly model: string;
76
+ /**
77
+ * Exactly one HTTP request. No retry, no fallback, no second key. Throws a
78
+ * `ProviderError`; a reply that arrived but holds no usable transcript throws a
79
+ * `TranscriptionError`, which keeps the usage the provider billed for it.
80
+ */
81
+ transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
82
+ }
83
+
84
+ export interface TranscriptionLimits {
85
+ /** Largest recording sent, in bytes. Default 25 MiB, OpenAI's documented limit; Deepgram's
86
+ * own wire defaults to its 2 GB. Over it is refused before any request. Never cut. */
87
+ maxAudioBytes?: number;
88
+ /** One deadline for the whole call: the upload, the work and the reply. Default 600,000:
89
+ * ten minutes, past which Deepgram itself answers 504. */
90
+ timeoutMs?: number;
91
+ }
92
+
93
+ export const DEFAULT_TRANSCRIPTION_LIMITS = {
94
+ maxAudioBytes: 25 * 1024 * 1024,
95
+ timeoutMs: 600_000,
96
+ } as const satisfies Required<TranscriptionLimits>;
97
+
98
+ /**
99
+ * The largest reply read. A transcript is text, and an hour of speech with every word timed is
100
+ * a few megabytes, so this only stops a runaway server from filling an MV3 worker's memory.
101
+ */
102
+ export const MAX_REPLY_BYTES = 64 * 1024 * 1024;
103
+
104
+ type ProviderErrorOptions = NonNullable<ConstructorParameters<typeof ProviderError>[3]>;
105
+
106
+ /**
107
+ * A reply that arrived but holds no usable transcript, or a failure the provider reported
108
+ * inside a 200. Carries the usage the provider stated for it, because it billed that: a caller
109
+ * that drops this loses the only record of the charge. Plain `ProviderError`s carry no usage.
110
+ */
111
+ export class TranscriptionError extends ProviderError {
112
+ readonly usage?: TranscriptionUsage;
113
+
114
+ constructor(
115
+ provider: string,
116
+ kind: ErrorKind,
117
+ message: string,
118
+ opts: ProviderErrorOptions & { usage?: TranscriptionUsage } = {},
119
+ ) {
120
+ const { usage, ...rest } = opts;
121
+ super(provider, kind, message, rest);
122
+ this.name = "TranscriptionError";
123
+ this.usage = usage;
124
+ }
125
+ }
126
+
127
+ /** @internal Positive integers or a RangeError, at build time, never mid-call. */
128
+ export function resolveLimits(
129
+ config: TranscriptionLimits,
130
+ maxAudioBytes: number = DEFAULT_TRANSCRIPTION_LIMITS.maxAudioBytes,
131
+ ): Required<TranscriptionLimits> {
132
+ const limits = {
133
+ maxAudioBytes: config.maxAudioBytes ?? maxAudioBytes,
134
+ timeoutMs: config.timeoutMs ?? DEFAULT_TRANSCRIPTION_LIMITS.timeoutMs,
135
+ };
136
+ for (const [name, value] of Object.entries(limits)) {
137
+ if (!Number.isSafeInteger(value) || value < 1) {
138
+ throw new RangeError(`[providerkit] ${name} must be a positive integer`);
139
+ }
140
+ }
141
+ return limits;
142
+ }
143
+
144
+ const refuse = (provider: string, code: string, message: string, kind: ErrorKind = "invalid") =>
145
+ new ProviderError(provider, kind, `${provider}: ${message}`, { code, shouldRetry: false });
146
+
147
+ /** Space to tilde. Anything else in a header value is refused or altered by a runtime, which
148
+ * then quotes the value, key included, in its error. */
149
+ const HEADER_SAFE = /^[\x20-\x7e]*$/;
150
+
151
+ /** The media type without its parameters, lowercased: "audio/ogg; codecs=opus" is "audio/ogg". */
152
+ export const mediaType = (type: string) => type.split(";")[0]!.trim().toLowerCase();
153
+
154
+ /**
155
+ * @internal Check what the call carries and fill in its model. Throws BEFORE any request, so a
156
+ * recording that cannot go is never uploaded, and a refusal costs nothing.
157
+ */
158
+ export function prepareTranscription(
159
+ provider: string,
160
+ request: TranscriptionRequest,
161
+ defaults: {
162
+ /** Checked, never echoed. */
163
+ apiKey: string;
164
+ /** Deepgram has no keyless mode; a local OpenAI-shaped server may. */
165
+ keyRequired: boolean;
166
+ model: string;
167
+ maxAudioBytes: number;
168
+ },
169
+ ): { audio: Blob; model: string; language?: string; diarize: boolean } {
170
+ if (!HEADER_SAFE.test(defaults.apiKey) || (defaults.keyRequired && !defaults.apiKey)) {
171
+ throw refuse(
172
+ provider,
173
+ "key_invalid",
174
+ "the API key is empty or holds a character that cannot be sent in a header (a line break or a character outside plain ASCII). Paste the key again",
175
+ "auth",
176
+ );
177
+ }
178
+ const { audio } = request;
179
+ if (!(audio instanceof Blob) || audio.size === 0) {
180
+ throw refuse(provider, "audio_empty", "there is no audio to transcribe");
181
+ }
182
+ if (!mediaType(audio.type)) {
183
+ throw refuse(
184
+ provider,
185
+ "audio_type_missing",
186
+ 'the audio has no media type. Give the Blob one, such as new Blob([bytes], { type: "audio/wav" })',
187
+ );
188
+ }
189
+ if (audio.size > defaults.maxAudioBytes) {
190
+ throw refuse(
191
+ provider,
192
+ "audio_too_large",
193
+ `the audio is ${audio.size} bytes and the limit is ${defaults.maxAudioBytes}`,
194
+ );
195
+ }
196
+ const model = (request.model ?? defaults.model ?? "").trim();
197
+ if (!model) throw refuse(provider, "model_required", "name a model");
198
+ const language = request.language?.trim();
199
+ return { audio, model, ...(language ? { language } : {}), diarize: request.diarize === true };
200
+ }
201
+
202
+ /** A `TranscriptionError` comes back as itself, with the usage it carries. */
203
+ const asTranscriptionError: ErrorRebuild = (err, opts) =>
204
+ err instanceof TranscriptionError
205
+ ? new TranscriptionError(err.provider, err.kind, err.message, { ...opts, usage: err.usage })
206
+ : new ProviderError(err.provider, err.kind, err.message, opts);
207
+
208
+ // Both vendors' words for a recording they could not read. Deepgram: "Bad Request: failed to
209
+ // process audio: corrupt or unsupported data". OpenAI: "Invalid file format. Supported formats:
210
+ // [...]" and "Audio file might be corrupted or unsupported". Read 2026-11-11.
211
+ const AUDIO_UNREADABLE: readonly RegExp[] = [
212
+ /failed to process audio/i,
213
+ /corrupt(?:ed)? or unsupported/i,
214
+ /(?:invalid|unrecognized|unsupported) file format/i,
215
+ /could not be decoded/i,
216
+ ];
217
+
218
+ /**
219
+ * The classifier calls a refused recording `invalid`, the same as any request we got wrong.
220
+ * The fix is a different file, so it is named by `code`: `audio_too_large` for a 413, and
221
+ * `audio_invalid` when the vendor says it could not read the audio. The kind stays.
222
+ */
223
+ function audioRefusalCode(error: ProviderError): string | undefined {
224
+ if (error.status === 413) return "audio_too_large";
225
+ if (AUDIO_UNREADABLE.some((pattern) => pattern.test(error.body ?? ""))) return "audio_invalid";
226
+ return undefined;
227
+ }
228
+
229
+ function nameAudioRefusal(error: unknown): unknown {
230
+ if (!(error instanceof ProviderError) || error.kind !== "invalid" || error.code) return error;
231
+ const code = audioRefusalCode(error);
232
+ if (!code) return error;
233
+ return new ProviderError(error.provider, error.kind, error.message, {
234
+ status: error.status,
235
+ code,
236
+ shouldRetry: false,
237
+ body: error.body,
238
+ cause: error.cause,
239
+ });
240
+ }
241
+
242
+ /**
243
+ * @internal The one place a call runs: under one deadline, once, with a refused recording
244
+ * named and the no-replay rule applied to whatever it throws. Both wires go through here.
245
+ */
246
+ export function transcribeOnce<T>(
247
+ provider: string,
248
+ timeoutMs: number,
249
+ request: TranscriptionRequest,
250
+ call: (signal: AbortSignal) => Promise<T>,
251
+ ): Promise<T> {
252
+ return callOnce(
253
+ provider,
254
+ timeoutMs,
255
+ request.signal,
256
+ (signal) =>
257
+ call(signal).catch((error: unknown) => {
258
+ throw nameAudioRefusal(error);
259
+ }),
260
+ asTranscriptionError,
261
+ );
262
+ }
263
+
264
+ // ── replies ───────────────────────────────────────────────────────────────
265
+
266
+ /** @internal A reply that arrived but cannot be used. Never retried: it was billed. */
267
+ export function unusable(
268
+ provider: string,
269
+ message: string,
270
+ usage?: TranscriptionUsage,
271
+ ): TranscriptionError {
272
+ return new TranscriptionError(provider, "unknown", `${provider}: ${message}`, {
273
+ code: "bad_reply",
274
+ shouldRetry: false,
275
+ ...(usage ? { usage } : {}),
276
+ });
277
+ }
278
+
279
+ /**
280
+ * @internal A failure the provider reported inside a 200 (a gateway that answers 200 with a
281
+ * JSON error). Classified like any other failure, with the same words-over-status rules, and
282
+ * the provider's words kept: unlike speech, nothing the caller sent can come back in them.
283
+ */
284
+ export function inBandFailure(provider: string, envelope: unknown): TranscriptionError {
285
+ const found = streamError(provider, envelope);
286
+ return new TranscriptionError(provider, found.kind, found.message, {
287
+ status: found.status,
288
+ code: found.code,
289
+ retryAfterMs: found.retryAfterMs,
290
+ resetAtMs: found.resetAtMs,
291
+ window: found.window,
292
+ body: found.body,
293
+ });
294
+ }
295
+
296
+ /** @internal */
297
+ export function asRecord(value: unknown): Record<string, unknown> | undefined {
298
+ return typeof value === "object" && value !== null && !Array.isArray(value)
299
+ ? (value as Record<string, unknown>)
300
+ : undefined;
301
+ }
302
+
303
+ /** @internal The reply as a JSON object, or `undefined` for anything else. */
304
+ export function parseObject(bytes: Uint8Array): Record<string, unknown> | undefined {
305
+ try {
306
+ return asRecord(JSON.parse(new TextDecoder().decode(bytes)));
307
+ } catch {
308
+ return undefined;
309
+ }
310
+ }
311
+
312
+ /** @internal A finite, non-negative number of seconds, or `undefined`. */
313
+ export const seconds = (value: unknown): number | undefined =>
314
+ typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
315
+
316
+ /**
317
+ * @internal The segments that check out: a start and an end in seconds, end not before start,
318
+ * and text. A malformed one is skipped rather than guessed at. `speaker` is read only when the
319
+ * caller asked for speakers, so a provider that stamps speaker 0 on everyone without being asked
320
+ * does not label a monologue.
321
+ */
322
+ export function readSegments(
323
+ raw: unknown,
324
+ textKey: string,
325
+ diarize: boolean,
326
+ ): TranscriptionSegment[] {
327
+ if (!Array.isArray(raw)) return [];
328
+ const segments: TranscriptionSegment[] = [];
329
+ for (const entry of raw) {
330
+ const segment = asRecord(entry);
331
+ const start = seconds(segment?.start);
332
+ const end = seconds(segment?.end);
333
+ const text = segment?.[textKey];
334
+ if (start === undefined || end === undefined || end < start || typeof text !== "string") {
335
+ continue;
336
+ }
337
+ const speaker = segment?.speaker;
338
+ const labelled =
339
+ diarize &&
340
+ ((typeof speaker === "number" && Number.isSafeInteger(speaker) && speaker >= 0) ||
341
+ (typeof speaker === "string" && speaker !== ""));
342
+ segments.push({ start, end, text: text.trim(), ...(labelled ? { speaker } : {}) });
343
+ }
344
+ return segments;
345
+ }