@providerkit/core 0.29.1 → 0.31.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 (163) hide show
  1. package/README.md +58 -9
  2. package/THIRD_PARTY_NOTICES +144 -0
  3. package/dist/auth/chatgpt-models.js.map +1 -1
  4. package/dist/auth/oauth.d.ts.map +1 -1
  5. package/dist/auth/oauth.js.map +1 -1
  6. package/dist/capability.js.map +1 -1
  7. package/dist/context.d.ts +4 -3
  8. package/dist/context.d.ts.map +1 -1
  9. package/dist/context.js +19 -5
  10. package/dist/context.js.map +1 -1
  11. package/dist/decisions.js.map +1 -1
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js +29 -2
  14. package/dist/errors.js.map +1 -1
  15. package/dist/fallback.d.ts +3 -0
  16. package/dist/fallback.d.ts.map +1 -1
  17. package/dist/fallback.js +9 -5
  18. package/dist/fallback.js.map +1 -1
  19. package/dist/gate.js.map +1 -1
  20. package/dist/hosted/anthropic.d.ts +30 -0
  21. package/dist/hosted/anthropic.d.ts.map +1 -0
  22. package/dist/hosted/anthropic.js +465 -0
  23. package/dist/hosted/anthropic.js.map +1 -0
  24. package/dist/hosted/gemini.d.ts +22 -0
  25. package/dist/hosted/gemini.d.ts.map +1 -0
  26. package/dist/hosted/gemini.js +440 -0
  27. package/dist/hosted/gemini.js.map +1 -0
  28. package/dist/hosted/openai.d.ts +33 -0
  29. package/dist/hosted/openai.d.ts.map +1 -0
  30. package/dist/hosted/openai.js +107 -0
  31. package/dist/hosted/openai.js.map +1 -0
  32. package/dist/hosted/responses.d.ts +28 -0
  33. package/dist/hosted/responses.d.ts.map +1 -0
  34. package/dist/hosted/responses.js +358 -0
  35. package/dist/hosted/responses.js.map +1 -0
  36. package/dist/hosted/shared.d.ts +107 -0
  37. package/dist/hosted/shared.d.ts.map +1 -0
  38. package/dist/hosted/shared.js +264 -0
  39. package/dist/hosted/shared.js.map +1 -0
  40. package/dist/hosted/types.d.ts +191 -0
  41. package/dist/hosted/types.d.ts.map +1 -0
  42. package/dist/hosted/types.js +10 -0
  43. package/dist/hosted/types.js.map +1 -0
  44. package/dist/hosted.d.ts +33 -0
  45. package/dist/hosted.d.ts.map +1 -0
  46. package/dist/hosted.js +61 -0
  47. package/dist/hosted.js.map +1 -0
  48. package/dist/index.d.ts +8 -7
  49. package/dist/index.d.ts.map +1 -1
  50. package/dist/index.js +8 -7
  51. package/dist/index.js.map +1 -1
  52. package/dist/key-pool.d.ts.map +1 -1
  53. package/dist/key-pool.js.map +1 -1
  54. package/dist/presets.d.ts +36 -5
  55. package/dist/presets.d.ts.map +1 -1
  56. package/dist/presets.js +32 -8
  57. package/dist/presets.js.map +1 -1
  58. package/dist/providers/anthropic.d.ts +75 -1
  59. package/dist/providers/anthropic.d.ts.map +1 -1
  60. package/dist/providers/anthropic.js +207 -135
  61. package/dist/providers/anthropic.js.map +1 -1
  62. package/dist/providers/deepgram-transcription.d.ts +24 -0
  63. package/dist/providers/deepgram-transcription.d.ts.map +1 -0
  64. package/dist/providers/deepgram-transcription.js +84 -0
  65. package/dist/providers/deepgram-transcription.js.map +1 -0
  66. package/dist/providers/factory.d.ts +10 -0
  67. package/dist/providers/factory.d.ts.map +1 -1
  68. package/dist/providers/factory.js +31 -23
  69. package/dist/providers/factory.js.map +1 -1
  70. package/dist/providers/gemini.d.ts +123 -1
  71. package/dist/providers/gemini.d.ts.map +1 -1
  72. package/dist/providers/gemini.js +114 -54
  73. package/dist/providers/gemini.js.map +1 -1
  74. package/dist/providers/hosted-codecs.d.ts +10 -0
  75. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  76. package/dist/providers/hosted-codecs.js +8 -0
  77. package/dist/providers/hosted-codecs.js.map +1 -0
  78. package/dist/providers/openai-transcription.d.ts +21 -0
  79. package/dist/providers/openai-transcription.d.ts.map +1 -0
  80. package/dist/providers/openai-transcription.js +144 -0
  81. package/dist/providers/openai-transcription.js.map +1 -0
  82. package/dist/providers/openai.d.ts +69 -0
  83. package/dist/providers/openai.d.ts.map +1 -1
  84. package/dist/providers/openai.js +38 -14
  85. package/dist/providers/openai.js.map +1 -1
  86. package/dist/providers/responses.d.ts +123 -0
  87. package/dist/providers/responses.d.ts.map +1 -1
  88. package/dist/providers/responses.js +57 -22
  89. package/dist/providers/responses.js.map +1 -1
  90. package/dist/providers/speech-factory.js.map +1 -1
  91. package/dist/providers/transcription-factory.d.ts +30 -0
  92. package/dist/providers/transcription-factory.d.ts.map +1 -0
  93. package/dist/providers/transcription-factory.js +38 -0
  94. package/dist/providers/transcription-factory.js.map +1 -0
  95. package/dist/registry.d.ts +3 -0
  96. package/dist/registry.d.ts.map +1 -1
  97. package/dist/registry.js +8 -4
  98. package/dist/registry.js.map +1 -1
  99. package/dist/retry.js.map +1 -1
  100. package/dist/speech-core.d.ts +2 -17
  101. package/dist/speech-core.d.ts.map +1 -1
  102. package/dist/speech-core.js +10 -50
  103. package/dist/speech-core.js.map +1 -1
  104. package/dist/tools.d.ts.map +1 -1
  105. package/dist/tools.js.map +1 -1
  106. package/dist/transcription-core.d.ts +146 -0
  107. package/dist/transcription-core.d.ts.map +1 -0
  108. package/dist/transcription-core.js +193 -0
  109. package/dist/transcription-core.js.map +1 -0
  110. package/dist/transcription.d.ts +7 -0
  111. package/dist/transcription.d.ts.map +1 -0
  112. package/dist/transcription.js +12 -0
  113. package/dist/transcription.js.map +1 -0
  114. package/dist/transport.d.ts +26 -0
  115. package/dist/transport.d.ts.map +1 -1
  116. package/dist/transport.js +57 -2
  117. package/dist/transport.js.map +1 -1
  118. package/dist/turn.d.ts +10 -1
  119. package/dist/turn.d.ts.map +1 -1
  120. package/dist/turn.js +53 -1
  121. package/dist/turn.js.map +1 -1
  122. package/dist/types.d.ts +51 -0
  123. package/dist/types.d.ts.map +1 -1
  124. package/dist/types.js.map +1 -1
  125. package/dist/usage.d.ts +10 -1
  126. package/dist/usage.d.ts.map +1 -1
  127. package/dist/usage.js +40 -2
  128. package/dist/usage.js.map +1 -1
  129. package/dist/watchdog.d.ts +6 -0
  130. package/dist/watchdog.d.ts.map +1 -1
  131. package/dist/watchdog.js +10 -2
  132. package/dist/watchdog.js.map +1 -1
  133. package/package.json +14 -5
  134. package/src/context.ts +21 -5
  135. package/src/errors.ts +35 -2
  136. package/src/fallback.ts +21 -6
  137. package/src/hosted/anthropic.ts +512 -0
  138. package/src/hosted/gemini.ts +510 -0
  139. package/src/hosted/openai.ts +137 -0
  140. package/src/hosted/responses.ts +420 -0
  141. package/src/hosted/shared.ts +341 -0
  142. package/src/hosted/types.ts +214 -0
  143. package/src/hosted.ts +101 -0
  144. package/src/index.ts +64 -7
  145. package/src/presets.ts +54 -8
  146. package/src/providers/anthropic.ts +252 -143
  147. package/src/providers/deepgram-transcription.ts +109 -0
  148. package/src/providers/factory.ts +127 -82
  149. package/src/providers/gemini.ts +184 -60
  150. package/src/providers/hosted-codecs.ts +29 -0
  151. package/src/providers/openai-transcription.ts +177 -0
  152. package/src/providers/openai.ts +52 -15
  153. package/src/providers/responses.ts +93 -24
  154. package/src/providers/transcription-factory.ts +68 -0
  155. package/src/registry.ts +14 -4
  156. package/src/speech-core.ts +9 -47
  157. package/src/transcription-core.ts +345 -0
  158. package/src/transcription.ts +24 -0
  159. package/src/transport.ts +77 -3
  160. package/src/turn.ts +55 -1
  161. package/src/types.ts +62 -1
  162. package/src/usage.ts +32 -2
  163. package/src/watchdog.ts +12 -2
@@ -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. */
package/src/turn.ts CHANGED
@@ -9,6 +9,7 @@
9
9
  // turn that said nothing is not judged here: that is `requireContent`'s call
10
10
  // (invariant 13), made where the retry that can fix it still can.
11
11
  import { ProviderError } from "./errors.ts";
12
+ import type { Citation, HostedCall, HostedItems, HostedToolType } from "./hosted/types.ts";
12
13
  import {
13
14
  EMPTY_USAGE,
14
15
  type ChatMessage,
@@ -19,6 +20,9 @@ import {
19
20
  type ToolCall,
20
21
  } from "./types.ts";
21
22
 
23
+ /** A hosted call while it assembles: its type may not be stated yet. */
24
+ type AssemblingCall = Omit<HostedCall, "type"> & { type?: HostedToolType };
25
+
22
26
  /** One drained turn: the message a loop appends, whose `toolCalls` are the
23
27
  * calls it runs, and what the turn cost. */
24
28
  export interface Turn {
@@ -43,8 +47,12 @@ export interface Turn {
43
47
  * for (const call of turn.message.toolCalls ?? []) history.push(await run(call));
44
48
  * ```
45
49
  *
50
+ * Hosted calls (a vendor's search, fetch or code run) land in `hostedCalls`,
51
+ * never in `toolCalls`: there is nothing for the loop to run.
52
+ *
46
53
  * @throws {ProviderError} `overload` when a tool call ends the stream with no
47
- * name. Whatever the stream itself throws passes through unchanged.
54
+ * name, or a hosted call with no type. Whatever the stream itself throws
55
+ * passes through unchanged.
48
56
  */
49
57
  export async function collectTurn(stream: AsyncIterable<ProviderChunk>): Promise<Turn> {
50
58
  let content = "";
@@ -56,6 +64,9 @@ export async function collectTurn(stream: AsyncIterable<ProviderChunk>): Promise
56
64
  let reasoningDetails: unknown[] | undefined;
57
65
  let reasoningItems: ReasoningItems | undefined;
58
66
  const calls = new Map<number, ToolCall>();
67
+ const hosted = new Map<number, AssemblingCall>();
68
+ const citations: Citation[] = [];
69
+ let hostedItems: HostedItems | undefined;
59
70
  // Cumulative on some providers and final-only on others: the LAST one wins.
60
71
  let usage: TokenUsage = EMPTY_USAGE;
61
72
  let finishReason: FinishReason | null = null;
@@ -85,6 +96,27 @@ export async function collectTurn(stream: AsyncIterable<ProviderChunk>): Promise
85
96
  call.arguments += delta.arguments ?? "";
86
97
  calls.set(delta.index, call);
87
98
  }
99
+ for (const delta of chunk.hosted ?? []) {
100
+ // The same rule as a tool call's identity: the last value stated wins,
101
+ // so a skeleton's blanks never erase what the closing event says. A
102
+ // call's place in the answer is where the text was when it first
103
+ // appeared, unless the adapter said otherwise (Gemini's grounding record
104
+ // arrives after the answer and covers it from 0).
105
+ const call = hosted.get(delta.index) ?? { id: "", status: "running", at: content.length };
106
+ if (delta.id) call.id = delta.id;
107
+ if (delta.type) call.type = delta.type;
108
+ if (delta.status) call.status = delta.status;
109
+ if (delta.input) call.input = { ...call.input, ...delta.input };
110
+ if (delta.codeDelta) {
111
+ call.input = { ...call.input, code: (call.input?.code ?? "") + delta.codeDelta };
112
+ }
113
+ if (delta.output) call.output = delta.output;
114
+ if (delta.error) call.error = delta.error;
115
+ if (delta.at !== undefined) call.at = delta.at;
116
+ hosted.set(delta.index, call);
117
+ }
118
+ if (chunk.citations?.length) citations.push(...chunk.citations);
119
+ if (chunk.hostedItems) hostedItems = chunk.hostedItems;
88
120
  if (chunk.usage) usage = chunk.usage;
89
121
  if (chunk.finishReason) finishReason = chunk.finishReason;
90
122
  }
@@ -110,6 +142,19 @@ export async function collectTurn(stream: AsyncIterable<ProviderChunk>): Promise
110
142
  );
111
143
  }
112
144
  const toolCalls = indexed.map(([, call]) => call);
145
+ const hostedCalls = [...hosted]
146
+ .sort(([a], [b]) => a - b)
147
+ .map(([index, { type, ...call }]): HostedCall => {
148
+ // A record that never says what ran can't be shown or counted: the
149
+ // vendor's frame was broken, as with a nameless tool call above.
150
+ if (type) return { ...call, type };
151
+ const provider = source?.provider ?? "turn";
152
+ throw new ProviderError(
153
+ provider,
154
+ "overload",
155
+ `${provider}: hosted call ${call.id || `at index ${index}`} never said which tool ran`,
156
+ );
157
+ });
113
158
 
114
159
  return {
115
160
  message: {
@@ -119,6 +164,9 @@ export async function collectTurn(stream: AsyncIterable<ProviderChunk>): Promise
119
164
  ...(reasoningDetails ? { reasoningDetails } : {}),
120
165
  ...(reasoningItems ? { reasoningItems } : {}),
121
166
  ...(toolCalls.length > 0 ? { toolCalls } : {}),
167
+ ...(hostedCalls.length > 0 ? { hostedCalls } : {}),
168
+ ...(citations.length > 0 ? { citations } : {}),
169
+ ...(hostedItems ? { hostedItems } : {}),
122
170
  },
123
171
  usage,
124
172
  finishReason,
@@ -139,6 +187,10 @@ export interface Completion {
139
187
  * for none. Before this field a drained turn that called a tool read as a
140
188
  * turn that said nothing. */
141
189
  toolCalls: ToolCall[];
190
+ /** Present only when the vendor ran its own tools. See ChatMessage.hostedCalls. */
191
+ hostedCalls?: HostedCall[];
192
+ /** Present only when the answer cites sources. See ChatMessage.citations. */
193
+ citations?: Citation[];
142
194
  usage: TokenUsage;
143
195
  finishReason: FinishReason | null;
144
196
  model: string;
@@ -158,6 +210,8 @@ export async function drainStream(
158
210
  ...(message.reasoningDetails ? { reasoningDetails: message.reasoningDetails } : {}),
159
211
  ...(message.reasoningItems ? { reasoningItems: message.reasoningItems } : {}),
160
212
  toolCalls: message.toolCalls ?? [],
213
+ ...(message.hostedCalls ? { hostedCalls: message.hostedCalls } : {}),
214
+ ...(message.citations ? { citations: message.citations } : {}),
161
215
  usage,
162
216
  finishReason,
163
217
  model: source?.model ?? model,