@providerkit/core 0.29.1 → 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 (50) 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/openai-transcription.d.ts +21 -0
  18. package/dist/providers/openai-transcription.d.ts.map +1 -0
  19. package/dist/providers/openai-transcription.js +144 -0
  20. package/dist/providers/openai-transcription.js.map +1 -0
  21. package/dist/providers/transcription-factory.d.ts +30 -0
  22. package/dist/providers/transcription-factory.d.ts.map +1 -0
  23. package/dist/providers/transcription-factory.js +38 -0
  24. package/dist/providers/transcription-factory.js.map +1 -0
  25. package/dist/speech-core.d.ts +2 -17
  26. package/dist/speech-core.d.ts.map +1 -1
  27. package/dist/speech-core.js +10 -50
  28. package/dist/speech-core.js.map +1 -1
  29. package/dist/transcription-core.d.ts +146 -0
  30. package/dist/transcription-core.d.ts.map +1 -0
  31. package/dist/transcription-core.js +193 -0
  32. package/dist/transcription-core.js.map +1 -0
  33. package/dist/transcription.d.ts +7 -0
  34. package/dist/transcription.d.ts.map +1 -0
  35. package/dist/transcription.js +12 -0
  36. package/dist/transcription.js.map +1 -0
  37. package/dist/transport.d.ts +26 -0
  38. package/dist/transport.d.ts.map +1 -1
  39. package/dist/transport.js +57 -2
  40. package/dist/transport.js.map +1 -1
  41. package/package.json +5 -1
  42. package/src/errors.ts +35 -2
  43. package/src/presets.ts +54 -8
  44. package/src/providers/deepgram-transcription.ts +109 -0
  45. package/src/providers/openai-transcription.ts +177 -0
  46. package/src/providers/transcription-factory.ts +68 -0
  47. package/src/speech-core.ts +9 -47
  48. package/src/transcription-core.ts +345 -0
  49. package/src/transcription.ts +24 -0
  50. package/src/transport.ts +77 -3
@@ -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
+ }
@@ -0,0 +1,24 @@
1
+ // `@providerkit/core/transcription`: one recording to its text, the inverse of
2
+ // `@providerkit/core/speech`. It is its own entry point, and `index.ts` does not export it, so
3
+ // an app that only chats loads none of the transcription code.
4
+ //
5
+ // Named, not `export *`: transcription-core.ts also holds helpers the two wires share, and a
6
+ // helper exported here is one this package can never change without a major version.
7
+ export {
8
+ DEFAULT_TRANSCRIPTION_LIMITS,
9
+ TranscriptionError,
10
+ type TranscriptionLimits,
11
+ type TranscriptionProvider,
12
+ type TranscriptionRequest,
13
+ type TranscriptionResult,
14
+ type TranscriptionSegment,
15
+ type TranscriptionShape,
16
+ type TranscriptionUsage,
17
+ } from "./transcription-core.ts";
18
+ // The `fetchImpl` option's type, so a transcription-only app can type its wrapper without the
19
+ // main entry.
20
+ export type { FetchLike } from "./transport.ts";
21
+ export * from "./providers/openai-transcription.ts";
22
+ export * from "./providers/deepgram-transcription.ts";
23
+ export * from "./providers/transcription-factory.ts";
24
+ export { TRANSCRIPTION_PRESET_IDS, type PresetTranscription } from "./presets.ts";
package/src/transport.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  //
5
5
  // Adapters keep only their per-event mapping; everything about being an HTTP
6
6
  // client lives here once.
7
- import { classifyHttp, parseRetryAfterMs, ProviderError } from "./errors.ts";
7
+ import { classifyHttp, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
8
8
  import {
9
9
  parseRateLimitReset,
10
10
  parseRateLimitResponse,
@@ -198,13 +198,17 @@ function originOf(url: string): string {
198
198
  */
199
199
  async function send(opts: RequestInit_, method = "POST", redact = false): Promise<Response> {
200
200
  const doFetch = opts.fetchImpl ?? globalThis.fetch;
201
+ // A Blob (a recording) or a FormData (a multipart upload) goes as itself, and fetch writes its
202
+ // Content-Type: a multipart boundary is one only fetch knows, so a JSON type here would break it.
203
+ const payload = opts.body;
204
+ const raw = payload instanceof Blob || payload instanceof FormData;
201
205
  // Serialized outside the catch below: a body that cannot become JSON is a
202
206
  // bug of ours, and must not be dressed as a network blip and retried.
203
- const body = typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body);
207
+ const body = raw || typeof payload === "string" ? payload : JSON.stringify(payload);
204
208
  try {
205
209
  return await doFetch(opts.url, {
206
210
  method,
207
- headers: { "content-type": "application/json", ...opts.headers },
211
+ headers: raw ? { ...opts.headers } : { "content-type": "application/json", ...opts.headers },
208
212
  body,
209
213
  signal: opts.signal,
210
214
  ...(opts.redirect ? { redirect: opts.redirect } : {}),
@@ -361,6 +365,76 @@ export async function withDeadline<T>(
361
365
  }
362
366
  }
363
367
 
368
+ type ProviderErrorOptions = NonNullable<ConstructorParameters<typeof ProviderError>[3]>;
369
+
370
+ /** How a capability copies one of its own errors, so a subclass comes back as itself
371
+ * with what it carries (the usage a speech or transcription error keeps). */
372
+ export type ErrorRebuild = (err: ProviderError, opts: ProviderErrorOptions) => ProviderError;
373
+
374
+ const plainCopy: ErrorRebuild = (err, opts) =>
375
+ new ProviderError(err.provider, err.kind, err.message, opts);
376
+
377
+ /** Kinds that can land after the vendor started the work it bills for. */
378
+ const REPLAY_UNSAFE: ReadonlySet<ErrorKind> = new Set<ErrorKind>([
379
+ "network",
380
+ "timeout",
381
+ "overload",
382
+ "unknown",
383
+ ]);
384
+
385
+ /**
386
+ * @internal The "could the vendor already have billed this?" rule (invariant 16), for every
387
+ * call that is paid for whole and answered whole: speech and transcription. Kept here, once,
388
+ * so a new capability or a new failure path cannot forget it.
389
+ *
390
+ * - The caller's Stop comes back untouched.
391
+ * - A timeout, a dead socket, a 5xx or anything unclassified may have landed after
392
+ * the vendor started work, so it is marked `shouldRetry: false`, and a vendor's
393
+ * `x-should-retry: true` does not undo that: the header says the vendor thinks a
394
+ * resend is fine, not that the first call was not billed.
395
+ * - Every other kind keeps what it came with. A 429 means the vendor refused before
396
+ * doing any work, so sending it again is safe, and `Retry-After` is honoured by
397
+ * the caller's own retry. `x-should-retry` is believed there, in either direction.
398
+ */
399
+ export function noReplay(
400
+ provider: string,
401
+ error: unknown,
402
+ signal?: AbortSignal,
403
+ rebuild: ErrorRebuild = plainCopy,
404
+ ): unknown {
405
+ if (signal?.aborted) return error;
406
+ const err = ProviderError.from(provider, error);
407
+ if (!REPLAY_UNSAFE.has(err.kind) || err.shouldRetry === false) return err;
408
+ return rebuild(err, {
409
+ status: err.status,
410
+ code: err.code,
411
+ retryAfterMs: err.retryAfterMs,
412
+ resetAtMs: err.resetAtMs,
413
+ window: err.window,
414
+ shouldRetry: false,
415
+ body: err.body,
416
+ cause: err.cause,
417
+ });
418
+ }
419
+
420
+ /**
421
+ * @internal The one place a paid call runs: under one deadline, once, with `noReplay`
422
+ * applied to whatever it throws.
423
+ */
424
+ export async function callOnce<T>(
425
+ provider: string,
426
+ timeoutMs: number,
427
+ signal: AbortSignal | undefined,
428
+ call: (signal: AbortSignal) => Promise<T>,
429
+ rebuild?: ErrorRebuild,
430
+ ): Promise<T> {
431
+ try {
432
+ return await withDeadline(provider, timeoutMs, signal, call);
433
+ } catch (error) {
434
+ throw noReplay(provider, error, signal, rebuild);
435
+ }
436
+ }
437
+
364
438
  /** Pull the `data:` payload out of one SSE frame, joining continuation lines
365
439
  * the way the spec says to. Returns null for a comment or a frame carrying
366
440
  * only an `event:` name. */