@providerkit/core 0.27.1 → 0.28.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 (84) hide show
  1. package/README.md +15 -0
  2. package/dist/auth/with-token.d.ts +3 -1
  3. package/dist/auth/with-token.d.ts.map +1 -1
  4. package/dist/auth/with-token.js +23 -4
  5. package/dist/auth/with-token.js.map +1 -1
  6. package/dist/errors.d.ts +2 -0
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +6 -0
  9. package/dist/errors.js.map +1 -1
  10. package/dist/fallback.d.ts +6 -4
  11. package/dist/fallback.d.ts.map +1 -1
  12. package/dist/fallback.js +13 -7
  13. package/dist/fallback.js.map +1 -1
  14. package/dist/index.d.ts +1 -1
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +3 -1
  17. package/dist/index.js.map +1 -1
  18. package/dist/key-pool.d.ts.map +1 -1
  19. package/dist/key-pool.js +3 -5
  20. package/dist/key-pool.js.map +1 -1
  21. package/dist/presets.d.ts +50 -0
  22. package/dist/presets.d.ts.map +1 -1
  23. package/dist/presets.js +82 -0
  24. package/dist/presets.js.map +1 -1
  25. package/dist/providers/anthropic.d.ts.map +1 -1
  26. package/dist/providers/anthropic.js +2 -1
  27. package/dist/providers/anthropic.js.map +1 -1
  28. package/dist/providers/factory.js +4 -1
  29. package/dist/providers/factory.js.map +1 -1
  30. package/dist/providers/gemini-speech.d.ts +25 -0
  31. package/dist/providers/gemini-speech.d.ts.map +1 -0
  32. package/dist/providers/gemini-speech.js +172 -0
  33. package/dist/providers/gemini-speech.js.map +1 -0
  34. package/dist/providers/gemini.d.ts.map +1 -1
  35. package/dist/providers/gemini.js +4 -1
  36. package/dist/providers/gemini.js.map +1 -1
  37. package/dist/providers/openai-speech.d.ts +23 -0
  38. package/dist/providers/openai-speech.d.ts.map +1 -0
  39. package/dist/providers/openai-speech.js +86 -0
  40. package/dist/providers/openai-speech.js.map +1 -0
  41. package/dist/providers/openai.d.ts.map +1 -1
  42. package/dist/providers/openai.js +2 -1
  43. package/dist/providers/openai.js.map +1 -1
  44. package/dist/providers/responses.d.ts.map +1 -1
  45. package/dist/providers/responses.js +2 -1
  46. package/dist/providers/responses.js.map +1 -1
  47. package/dist/providers/speech-factory.d.ts +35 -0
  48. package/dist/providers/speech-factory.d.ts.map +1 -0
  49. package/dist/providers/speech-factory.js +47 -0
  50. package/dist/providers/speech-factory.js.map +1 -0
  51. package/dist/speech-core.d.ts +184 -0
  52. package/dist/speech-core.d.ts.map +1 -0
  53. package/dist/speech-core.js +349 -0
  54. package/dist/speech-core.js.map +1 -0
  55. package/dist/speech.d.ts +6 -0
  56. package/dist/speech.d.ts.map +1 -0
  57. package/dist/speech.js +12 -0
  58. package/dist/speech.js.map +1 -0
  59. package/dist/transport.d.ts +42 -0
  60. package/dist/transport.d.ts.map +1 -1
  61. package/dist/transport.js +154 -11
  62. package/dist/transport.js.map +1 -1
  63. package/dist/types.d.ts +10 -0
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js.map +1 -1
  66. package/package.json +6 -1
  67. package/src/auth/with-token.ts +24 -7
  68. package/src/errors.ts +7 -0
  69. package/src/fallback.ts +40 -18
  70. package/src/index.ts +14 -1
  71. package/src/key-pool.ts +38 -37
  72. package/src/presets.ts +113 -0
  73. package/src/providers/anthropic.ts +8 -1
  74. package/src/providers/factory.ts +4 -1
  75. package/src/providers/gemini-speech.ts +232 -0
  76. package/src/providers/gemini.ts +10 -1
  77. package/src/providers/openai-speech.ts +125 -0
  78. package/src/providers/openai.ts +8 -1
  79. package/src/providers/responses.ts +8 -1
  80. package/src/providers/speech-factory.ts +85 -0
  81. package/src/speech-core.ts +507 -0
  82. package/src/speech.ts +24 -0
  83. package/src/transport.ts +185 -11
  84. package/src/types.ts +10 -0
package/src/transport.ts CHANGED
@@ -30,6 +30,13 @@ export interface RequestInit_ {
30
30
  onRateLimit?: (reading: RateLimitReading) => void;
31
31
  /** Whether the turn already stated its finish. See `SseHooks.finished`. */
32
32
  finished?: () => boolean;
33
+ /**
34
+ * Set `"error"` on any call that carries a credential to a host the user typed.
35
+ * A cross-origin redirect keeps custom headers such as `x-goog-api-key`, so a
36
+ * wrong or hostile address would be handed the key. The redirect then fails
37
+ * the call instead of following. Absent: the runtime's default (follow).
38
+ */
39
+ redirect?: RequestRedirect;
33
40
  }
34
41
 
35
42
  export interface SseHooks {
@@ -72,6 +79,16 @@ export function apiUrl(baseUrl: string, path: string): string {
72
79
  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
73
80
  }
74
81
 
82
+ /**
83
+ * `path` under the API version a base URL does not already carry: `/v1` (or
84
+ * `version`) in front, unless the base already ends in a version segment such
85
+ * as `/v1` or `/v4`. The rule the chat adapters each keep inline.
86
+ */
87
+ export function versionedPath(baseUrl: string, path: string, version = "v1"): string {
88
+ const versioned = /\/v\d+[^/]*$/i.test(baseUrl.replace(/\/+$/, ""));
89
+ return `${versioned ? "" : `/${version}`}${path}`;
90
+ }
91
+
75
92
  /**
76
93
  * How long the provider says to wait, read from the RESPONSE rather than from
77
94
  * a thrown error. Headers are authoritative: `Retry-After` first, then the
@@ -109,9 +126,16 @@ export function retryAfterFromHeaders(headers: Headers, now = Date.now()): numbe
109
126
  return undefined;
110
127
  }
111
128
 
112
- /** Turn a non-2xx response into the classified error every caller branches on. */
113
- async function errorFor(provider: string, res: Response): Promise<ProviderError> {
114
- const text = await res.text().catch(() => "");
129
+ /** Most of an error body that is read. Only 2,000 characters are ever kept, and a
130
+ * base URL a user typed (a local server, a proxy) is a place an endless error
131
+ * body can come from. */
132
+ const MAX_ERROR_BODY_BYTES = 64 * 1024;
133
+
134
+ /** Turn a non-2xx response into the classified error every caller branches on.
135
+ * `redact` classifies from the body but keeps none of its words: a vendor's
136
+ * error can echo what the caller sent. */
137
+ async function errorFor(provider: string, res: Response, redact = false): Promise<ProviderError> {
138
+ const text = await readErrorText(res);
115
139
  const kind = classifyHttp(res.status, text);
116
140
  // A window-reset header describes the ACCOUNT, not this failure, and only a
117
141
  // throttle or a quota answer is about the window. Claude OAuth stamps the
@@ -124,9 +148,11 @@ async function errorFor(provider: string, res: Response): Promise<ProviderError>
124
148
  const asked = aboutWindow
125
149
  ? retryAfterFromHeaders(res.headers)
126
150
  : parseRateLimitReset(res.headers).retryAfterMs;
127
- const message = text
128
- ? `${provider} ${res.status}: ${text.slice(0, 500)}`
129
- : `${provider} ${res.status} ${res.statusText}`;
151
+ const message = redact
152
+ ? `${provider} ${res.status}`
153
+ : text
154
+ ? `${provider} ${res.status}: ${text.slice(0, 500)}`
155
+ : `${provider} ${res.status} ${res.statusText}`;
130
156
  const shouldRetryHeader = res.headers.get("x-should-retry");
131
157
  const shouldRetry =
132
158
  shouldRetryHeader === "false" ? false : shouldRetryHeader === "true" ? true : undefined;
@@ -135,11 +161,35 @@ async function errorFor(provider: string, res: Response): Promise<ProviderError>
135
161
  ...reset,
136
162
  shouldRetry,
137
163
  retryAfterMs: asked ?? parseRetryAfterMs({}, text),
138
- body: text.slice(0, 2_000) || undefined,
164
+ ...(redact ? {} : { body: text.slice(0, 2_000) || undefined }),
139
165
  });
140
166
  }
141
167
 
142
- async function send(opts: RequestInit_, method = "POST"): Promise<Response> {
168
+ async function readErrorText(res: Response): Promise<string> {
169
+ try {
170
+ const { bytes } = await readCapped(res.body, MAX_ERROR_BODY_BYTES);
171
+ return new TextDecoder().decode(bytes);
172
+ } catch {
173
+ return "";
174
+ }
175
+ }
176
+
177
+ /** The scheme and host of a URL, nothing a user typed in front of it or after it. */
178
+ function originOf(url: string): string {
179
+ try {
180
+ return new URL(url).origin;
181
+ } catch {
182
+ return "the server";
183
+ }
184
+ }
185
+
186
+ /**
187
+ * `redact` keeps a credential out of a failed send. A runtime that refuses a header
188
+ * (a key with a line break in it, a character outside Latin-1) puts the whole value
189
+ * in its TypeError, so the raw rejection is not kept as `cause`, and the message names
190
+ * the host without its path or any user info a base URL carries.
191
+ */
192
+ async function send(opts: RequestInit_, method = "POST", redact = false): Promise<Response> {
143
193
  const doFetch = opts.fetchImpl ?? globalThis.fetch;
144
194
  // Serialized outside the catch below: a body that cannot become JSON is a
145
195
  // bug of ours, and must not be dressed as a network blip and retried.
@@ -150,6 +200,7 @@ async function send(opts: RequestInit_, method = "POST"): Promise<Response> {
150
200
  headers: { "content-type": "application/json", ...opts.headers },
151
201
  body,
152
202
  signal: opts.signal,
203
+ ...(opts.redirect ? { redirect: opts.redirect } : {}),
153
204
  });
154
205
  } catch (err) {
155
206
  // An aborted signal passes through untouched: the caller's Stop stays
@@ -160,9 +211,12 @@ async function send(opts: RequestInit_, method = "POST"): Promise<Response> {
160
211
  // long run died on its first blip. cc-proxy reads every failed send the
161
212
  // same way.
162
213
  if (opts.signal?.aborted) throw err;
163
- throw new ProviderError(opts.provider, "network", `no response from ${opts.url}`, {
164
- cause: err,
165
- });
214
+ throw new ProviderError(
215
+ opts.provider,
216
+ "network",
217
+ `no response from ${redact ? originOf(opts.url) : opts.url}`,
218
+ redact ? {} : { cause: err },
219
+ );
166
220
  }
167
221
  }
168
222
 
@@ -180,6 +234,126 @@ export async function postJson<T = unknown>(opts: RequestInit_): Promise<T> {
180
234
  return (await res.json()) as T;
181
235
  }
182
236
 
237
+ /**
238
+ * Read a body, keeping at most `maxBytes`. Returns what fit and whether the body
239
+ * went on past it; the rest is cancelled, never read.
240
+ */
241
+ async function readCapped(
242
+ body: ReadableStream<Uint8Array> | null,
243
+ maxBytes: number,
244
+ ): Promise<{ bytes: Uint8Array; over: boolean }> {
245
+ if (!body) return { bytes: new Uint8Array(0), over: false };
246
+ const reader = body.getReader();
247
+ const chunks: Uint8Array[] = [];
248
+ let size = 0;
249
+ let over = false;
250
+ try {
251
+ for (;;) {
252
+ const { done, value } = await reader.read();
253
+ if (done) break;
254
+ const room = maxBytes - size;
255
+ if (value.byteLength > room) {
256
+ chunks.push(value.subarray(0, room));
257
+ size = maxBytes;
258
+ over = true;
259
+ reader.cancel().catch(() => {});
260
+ break;
261
+ }
262
+ chunks.push(value);
263
+ size += value.byteLength;
264
+ }
265
+ } finally {
266
+ reader.releaseLock();
267
+ }
268
+ const bytes = new Uint8Array(size);
269
+ let at = 0;
270
+ for (const chunk of chunks) {
271
+ bytes.set(chunk, at);
272
+ at += chunk.byteLength;
273
+ }
274
+ return { bytes, over };
275
+ }
276
+
277
+ /**
278
+ * Read a whole body, at most `maxBytes`. A `Content-Length` over the cap cancels
279
+ * before a byte is read, and a body that outgrows the cap cancels mid-read:
280
+ * `invalid` with `response_too_large`, and `shouldRetry: false`, because the cap
281
+ * is the caller's and a replay meets it again. A read that dies is `network`,
282
+ * unless the caller's own `signal` aborted it, which passes through untouched.
283
+ */
284
+ export async function readBounded(
285
+ res: Response,
286
+ maxBytes: number,
287
+ provider: string,
288
+ signal?: AbortSignal,
289
+ ): Promise<Uint8Array> {
290
+ const tooLarge = () =>
291
+ new ProviderError(
292
+ provider,
293
+ "invalid",
294
+ `${provider}: the reply is larger than ${maxBytes} bytes`,
295
+ { code: "response_too_large", shouldRetry: false },
296
+ );
297
+ const declared = res.headers.get("content-length");
298
+ if (declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes) {
299
+ res.body?.cancel().catch(() => {});
300
+ throw tooLarge();
301
+ }
302
+ let read: Awaited<ReturnType<typeof readCapped>>;
303
+ try {
304
+ read = await readCapped(res.body, maxBytes);
305
+ } catch (err) {
306
+ if (signal?.aborted) throw err;
307
+ throw new ProviderError(provider, "network", `${provider}: the reply was cut off`, {
308
+ cause: err,
309
+ });
310
+ }
311
+ if (read.over) throw tooLarge();
312
+ return read.bytes;
313
+ }
314
+
315
+ /**
316
+ * POST and return the raw body, bounded. For the endpoints that answer with
317
+ * bytes (audio) or with JSON too large to trust. Same envelope and error
318
+ * classification as `postJson`. `redactErrors` keeps the provider's words out of
319
+ * a failure, and the request's own words too (the full URL, the runtime's rejection):
320
+ * the kind, status and retry hints survive, the text does not.
321
+ */
322
+ export async function postBytes(
323
+ opts: RequestInit_ & { maxBytes: number; redactErrors?: boolean },
324
+ ): Promise<{ bytes: Uint8Array; contentType: string }> {
325
+ const res = await send(opts, "POST", opts.redactErrors);
326
+ if (!res.ok) throw await errorFor(opts.provider, res, opts.redactErrors);
327
+ const contentType = (res.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase();
328
+ return { bytes: await readBounded(res, opts.maxBytes, opts.provider, opts.signal), contentType };
329
+ }
330
+
331
+ /**
332
+ * Run a call that does not stream under one deadline, headers and body together.
333
+ * The caller's Stop passes through exactly as it arrived; only OUR deadline
334
+ * becomes `timeout` (invariant 2). A signal that is already aborted never starts
335
+ * the call.
336
+ */
337
+ export async function withDeadline<T>(
338
+ provider: string,
339
+ timeoutMs: number,
340
+ signal: AbortSignal | undefined,
341
+ run: (signal: AbortSignal) => Promise<T>,
342
+ ): Promise<T> {
343
+ signal?.throwIfAborted();
344
+ const deadline = AbortSignal.timeout(timeoutMs);
345
+ try {
346
+ return await run(signal ? AbortSignal.any([signal, deadline]) : deadline);
347
+ } catch (err) {
348
+ if (deadline.aborted && !signal?.aborted) {
349
+ throw new ProviderError(provider, "timeout", `${provider}: no answer in ${timeoutMs} ms`, {
350
+ cause: err,
351
+ });
352
+ }
353
+ throw err;
354
+ }
355
+ }
356
+
183
357
  /** Pull the `data:` payload out of one SSE frame, joining continuation lines
184
358
  * the way the spec says to. Returns null for a comment or a frame carrying
185
359
  * only an `event:` name. */
package/src/types.ts CHANGED
@@ -356,6 +356,16 @@ export type JsonWithTools = "response_format" | "prompt";
356
356
  export interface StreamOptions {
357
357
  /** Override the provider's bound model for this call. */
358
358
  model?: string;
359
+ /**
360
+ * Maximum attempts at each SDK recovery layer, including the first. Must
361
+ * be a positive integer. Omit to keep normal recovery. `1` prevents another
362
+ * inference request through model, key, host or token fallback, keeping the
363
+ * original failure and normal cooldown or credential renewal for later calls.
364
+ * Values above `1` are PER LAYER, not a total HTTP budget across nested pools.
365
+ * Initial token acquisition and credential refresh are not inference attempts.
366
+ * App-written outer retries need their own limit (`RetryOptions.maxAttempts`).
367
+ */
368
+ maxAttempts?: number;
359
369
  effort?: Effort;
360
370
  /** Output ceiling. On most providers thinking and answer SHARE it, so a
361
371
  * task emitting a large artifact must raise it or the tool-call JSON is