@starci/ai-router 0.4.0 → 0.5.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 (49) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +133 -40
  3. package/dist/ai-router.service.d.ts +2 -2
  4. package/dist/ai-router.service.js +4 -2
  5. package/dist/attempt.d.ts +26 -0
  6. package/dist/attempt.js +29 -0
  7. package/dist/classify.d.ts +40 -0
  8. package/dist/classify.js +145 -0
  9. package/dist/config.d.ts +30 -5
  10. package/dist/config.js +184 -24
  11. package/dist/env.d.ts +70 -0
  12. package/dist/env.js +152 -0
  13. package/dist/errors.d.ts +1 -3
  14. package/dist/errors.js +4 -23
  15. package/dist/fake.d.ts +624 -5
  16. package/dist/fake.js +177 -21
  17. package/dist/gateway/config-file.d.ts +8 -3
  18. package/dist/gateway/config-file.js +53 -8
  19. package/dist/gateway/gateway.d.ts +2 -0
  20. package/dist/gateway/gateway.js +19 -3
  21. package/dist/gateway/index.d.ts +10 -1
  22. package/dist/gateway/index.js +5 -0
  23. package/dist/gateway/serve.js +7 -2
  24. package/dist/headers.d.ts +1 -1
  25. package/dist/headers.js +12 -6
  26. package/dist/pool.d.ts +37 -16
  27. package/dist/pool.js +173 -48
  28. package/dist/providers.d.ts +34 -0
  29. package/dist/providers.js +22 -0
  30. package/dist/router.js +108 -105
  31. package/dist/secrets.d.ts +8 -0
  32. package/dist/secrets.js +22 -0
  33. package/dist/shapes.d.ts +11 -0
  34. package/dist/shapes.js +124 -0
  35. package/dist/state-stores.d.ts +38 -0
  36. package/dist/state-stores.js +101 -0
  37. package/dist/store.d.ts +26 -7
  38. package/dist/store.js +64 -2
  39. package/dist/testing.d.ts +2 -2
  40. package/dist/testing.js +1 -1
  41. package/dist/types.d.ts +126 -38
  42. package/dist/wire/anthropic.d.ts +21 -0
  43. package/dist/wire/anthropic.js +322 -0
  44. package/dist/wire/index.d.ts +5 -0
  45. package/dist/wire/index.js +7 -0
  46. package/dist/wire/wire.d.ts +42 -0
  47. package/dist/wire/wire.js +35 -0
  48. package/docs/design.md +279 -0
  49. package/package.json +13 -3
package/dist/fake.d.ts CHANGED
@@ -10,11 +10,18 @@ export interface FakeStream {
10
10
  /** Goes silent for `stallMs` after this many content chunks (an idle provider). */
11
11
  readonly stallAfter?: number;
12
12
  readonly stallMs?: number;
13
- /** `network` breaks the body; `error-event` streams an OpenAI error object. Default `network`. */
13
+ /** `network` breaks the body; `error-event` streams the provider's error object. Default `network`. */
14
14
  readonly failWith?: "network" | "error-event";
15
15
  /** Ends with a chunk that carries usage. Default true. */
16
16
  readonly includeUsage?: boolean;
17
17
  }
18
+ /** One tool call a scripted reply makes; `arguments` is the JSON text, streamed in `argumentChunks` pieces when given. */
19
+ export interface FakeToolCall {
20
+ readonly id: string;
21
+ readonly name: string;
22
+ readonly arguments: string;
23
+ readonly argumentChunks?: readonly string[];
24
+ }
18
25
  /** One scripted answer. Everything is optional: the default is a 200 chat reply `ok`. */
19
26
  export interface FakeReply {
20
27
  readonly status?: number;
@@ -25,6 +32,8 @@ export interface FakeReply {
25
32
  readonly error?: "network";
26
33
  /** The chat reply text. Default `ok`. */
27
34
  readonly text?: string;
35
+ /** Tool calls the reply makes (OpenAI `tool_calls`, Anthropic `tool_use` blocks). */
36
+ readonly toolCalls?: readonly FakeToolCall[];
28
37
  readonly usage?: Usage;
29
38
  /** The vector of every embedding. Default `[0.1, 0.2, 0.3]`. */
30
39
  readonly embedding?: readonly number[];
@@ -36,7 +45,7 @@ export interface FakeReply {
36
45
  export interface FakeMatch {
37
46
  /** The provider's base URL the request starts with. */
38
47
  readonly baseUrl?: string;
39
- /** The bearer key value (a test value). */
48
+ /** The key value sent as a bearer token or as `x-api-key` (a test value). */
40
49
  readonly key?: string;
41
50
  readonly model?: string;
42
51
  readonly path?: string;
@@ -45,14 +54,16 @@ export interface FakeMatch {
45
54
  export interface FakeCall {
46
55
  readonly url: string;
47
56
  readonly path: string;
48
- /** The bearer key value sent (a test value). */
57
+ /** The key value sent (a test value), from `authorization: Bearer` or `x-api-key`. */
49
58
  readonly key: string;
50
59
  readonly model: string;
51
60
  readonly stream: boolean;
61
+ /** `anthropic` for a request to `/messages`, else `openai`. */
62
+ readonly protocol: "openai" | "anthropic";
52
63
  readonly headers: Readonly<Record<string, string>>;
53
64
  readonly body: Readonly<Record<string, unknown>>;
54
65
  }
55
- /** A scriptable OpenAI-compatible provider that answers in process, for consumers' tests. */
66
+ /** A scriptable provider that answers in process, OpenAI-compatible and Anthropic Messages alike, for consumers' tests. */
56
67
  export interface FakeProvider {
57
68
  /** Pass as `PoolConfig.fetch`. */
58
69
  readonly fetch: FetchLike;
@@ -63,5 +74,613 @@ export interface FakeProvider {
63
74
  /** Forgets every script and call. */
64
75
  reset(): void;
65
76
  }
66
- /** Creates a fake OpenAI-compatible provider: deterministic replies, latency, errors, 429s and streams by script. */
77
+ /** The failure cases every provider's fake errors cover. */
78
+ export type FakeErrorCase = "rate_limited" | "quota_exhausted" | "invalid_key" | "overloaded" | "bad_request";
79
+ /**
80
+ * Each provider's real error answers (status, body, headers) as its docs showed them on 2026-10-31 (docs/design.md,
81
+ * the classification table), for a spec to script with `fake.on(match, PROVIDER_ERRORS.anthropic.quota_exhausted)`.
82
+ * Extra cases name a provider's second shape of one class (Anthropic's monthly spend cap, OpenRouter's free daily cap).
83
+ */
84
+ export declare const PROVIDER_ERRORS: Readonly<{
85
+ openai: {
86
+ rate_limited: {
87
+ status: number;
88
+ headers: {
89
+ "retry-after": string;
90
+ "x-ratelimit-remaining-requests": string;
91
+ "x-ratelimit-reset-requests": string;
92
+ };
93
+ body: {
94
+ error: {
95
+ message: string;
96
+ type: string;
97
+ param: null;
98
+ code: string;
99
+ };
100
+ };
101
+ };
102
+ quota_exhausted: {
103
+ status: number;
104
+ body: {
105
+ error: {
106
+ message: string;
107
+ type: string;
108
+ param: null;
109
+ code: string;
110
+ };
111
+ };
112
+ };
113
+ credit_exhausted: {
114
+ status: number;
115
+ body: {
116
+ error: {
117
+ message: string;
118
+ type: string;
119
+ param: null;
120
+ code: string;
121
+ };
122
+ };
123
+ };
124
+ usage_limit: {
125
+ status: number;
126
+ body: {
127
+ error: {
128
+ message: string;
129
+ type: string;
130
+ param: null;
131
+ code: string;
132
+ };
133
+ };
134
+ };
135
+ invalid_key: {
136
+ status: number;
137
+ body: {
138
+ error: {
139
+ message: string;
140
+ type: string;
141
+ param: null;
142
+ code: string;
143
+ };
144
+ };
145
+ };
146
+ overloaded: {
147
+ status: number;
148
+ headers: {
149
+ "retry-after": string;
150
+ };
151
+ body: {
152
+ error: {
153
+ message: string;
154
+ type: string;
155
+ param: null;
156
+ code: string;
157
+ };
158
+ };
159
+ };
160
+ bad_request: {
161
+ status: number;
162
+ body: {
163
+ error: {
164
+ message: string;
165
+ type: string;
166
+ param: string;
167
+ code: string;
168
+ };
169
+ };
170
+ };
171
+ };
172
+ anthropic: {
173
+ rate_limited: {
174
+ status: number;
175
+ headers: {
176
+ "retry-after": string;
177
+ "anthropic-ratelimit-requests-remaining": string;
178
+ "anthropic-ratelimit-requests-reset": string;
179
+ };
180
+ body: {
181
+ type: string;
182
+ error: {
183
+ type: string;
184
+ message: string;
185
+ };
186
+ request_id: string;
187
+ };
188
+ };
189
+ quota_exhausted: {
190
+ status: number;
191
+ body: {
192
+ type: string;
193
+ error: {
194
+ type: string;
195
+ message: string;
196
+ };
197
+ request_id: string;
198
+ };
199
+ };
200
+ spend_cap: {
201
+ status: number;
202
+ body: {
203
+ type: string;
204
+ error: {
205
+ type: string;
206
+ message: string;
207
+ details: {
208
+ error_code: string;
209
+ };
210
+ };
211
+ request_id: string;
212
+ };
213
+ };
214
+ usage_limit: {
215
+ status: number;
216
+ body: {
217
+ type: string;
218
+ error: {
219
+ type: string;
220
+ message: string;
221
+ };
222
+ request_id: string;
223
+ };
224
+ };
225
+ invalid_key: {
226
+ status: number;
227
+ body: {
228
+ type: string;
229
+ error: {
230
+ type: string;
231
+ message: string;
232
+ };
233
+ request_id: string;
234
+ };
235
+ };
236
+ overloaded: {
237
+ status: number;
238
+ body: {
239
+ type: string;
240
+ error: {
241
+ type: string;
242
+ message: string;
243
+ };
244
+ request_id: string;
245
+ };
246
+ };
247
+ bad_request: {
248
+ status: number;
249
+ body: {
250
+ type: string;
251
+ error: {
252
+ type: string;
253
+ message: string;
254
+ };
255
+ request_id: string;
256
+ };
257
+ };
258
+ };
259
+ openrouter: {
260
+ rate_limited: {
261
+ status: number;
262
+ headers: {
263
+ "X-RateLimit-Limit": string;
264
+ "X-RateLimit-Remaining": string;
265
+ "X-RateLimit-Reset": string;
266
+ };
267
+ body: {
268
+ error: {
269
+ code: number;
270
+ message: string;
271
+ metadata: {};
272
+ };
273
+ };
274
+ };
275
+ quota_exhausted: {
276
+ status: number;
277
+ body: {
278
+ error: {
279
+ code: number;
280
+ message: string;
281
+ metadata: {
282
+ limit_source: string;
283
+ };
284
+ };
285
+ };
286
+ };
287
+ key_limit: {
288
+ status: number;
289
+ body: {
290
+ error: {
291
+ code: number;
292
+ message: string;
293
+ metadata: {
294
+ limit_source: string;
295
+ };
296
+ };
297
+ };
298
+ };
299
+ in_flight_budget: {
300
+ status: number;
301
+ headers: {
302
+ "retry-after": string;
303
+ };
304
+ body: {
305
+ error: {
306
+ code: number;
307
+ message: string;
308
+ metadata: {
309
+ limit_source: string;
310
+ };
311
+ };
312
+ };
313
+ };
314
+ free_daily: {
315
+ status: number;
316
+ body: {
317
+ error: {
318
+ code: number;
319
+ message: string;
320
+ metadata: {};
321
+ };
322
+ };
323
+ };
324
+ invalid_key: {
325
+ status: number;
326
+ body: {
327
+ error: {
328
+ code: number;
329
+ message: string;
330
+ metadata: {};
331
+ };
332
+ };
333
+ };
334
+ overloaded: {
335
+ status: number;
336
+ body: {
337
+ error: {
338
+ code: number;
339
+ message: string;
340
+ metadata: {
341
+ provider_name: string;
342
+ raw: string;
343
+ };
344
+ };
345
+ };
346
+ };
347
+ moderation: {
348
+ status: number;
349
+ body: {
350
+ error: {
351
+ code: number;
352
+ message: string;
353
+ metadata: {
354
+ reasons: string[];
355
+ };
356
+ };
357
+ };
358
+ };
359
+ bad_request: {
360
+ status: number;
361
+ body: {
362
+ error: {
363
+ code: number;
364
+ message: string;
365
+ metadata: {};
366
+ };
367
+ };
368
+ };
369
+ in_body: {
370
+ status: number;
371
+ body: {
372
+ error: {
373
+ code: number;
374
+ message: string;
375
+ metadata: {
376
+ error_type: string;
377
+ };
378
+ };
379
+ };
380
+ };
381
+ };
382
+ qwen: {
383
+ rate_limited: {
384
+ status: number;
385
+ body: {
386
+ error: {
387
+ code: string;
388
+ message: string;
389
+ type: string;
390
+ };
391
+ };
392
+ };
393
+ token_rate: {
394
+ status: number;
395
+ body: {
396
+ error: {
397
+ code: string;
398
+ message: string;
399
+ type: string;
400
+ };
401
+ };
402
+ };
403
+ quota_exhausted: {
404
+ status: number;
405
+ body: {
406
+ error: {
407
+ code: string;
408
+ message: string;
409
+ type: string;
410
+ };
411
+ };
412
+ };
413
+ free_tier: {
414
+ status: number;
415
+ body: {
416
+ error: {
417
+ code: string;
418
+ message: string;
419
+ type: string;
420
+ };
421
+ };
422
+ };
423
+ invalid_key: {
424
+ status: number;
425
+ body: {
426
+ error: {
427
+ code: string;
428
+ message: string;
429
+ type: string;
430
+ };
431
+ };
432
+ };
433
+ overloaded: {
434
+ status: number;
435
+ body: {
436
+ error: {
437
+ code: string;
438
+ message: string;
439
+ type: string;
440
+ };
441
+ };
442
+ };
443
+ bad_request: {
444
+ status: number;
445
+ body: {
446
+ error: {
447
+ code: string;
448
+ message: string;
449
+ type: string;
450
+ };
451
+ };
452
+ };
453
+ };
454
+ deepseek: {
455
+ rate_limited: {
456
+ status: number;
457
+ body: {
458
+ error: {
459
+ message: string;
460
+ type: string;
461
+ param: null;
462
+ code: string;
463
+ };
464
+ };
465
+ };
466
+ quota_exhausted: {
467
+ status: number;
468
+ body: {
469
+ error: {
470
+ message: string;
471
+ type: string;
472
+ param: null;
473
+ code: string;
474
+ };
475
+ };
476
+ };
477
+ invalid_key: {
478
+ status: number;
479
+ body: {
480
+ error: {
481
+ message: string;
482
+ type: string;
483
+ param: null;
484
+ code: string;
485
+ };
486
+ };
487
+ };
488
+ overloaded: {
489
+ status: number;
490
+ body: {
491
+ error: {
492
+ message: string;
493
+ type: string;
494
+ param: null;
495
+ code: string;
496
+ };
497
+ };
498
+ };
499
+ bad_request: {
500
+ status: number;
501
+ body: {
502
+ error: {
503
+ message: string;
504
+ type: string;
505
+ param: null;
506
+ code: string;
507
+ };
508
+ };
509
+ };
510
+ };
511
+ gemini: {
512
+ rate_limited: {
513
+ status: number;
514
+ body: {
515
+ error: {
516
+ code: number;
517
+ message: string;
518
+ status: string;
519
+ };
520
+ }[];
521
+ };
522
+ quota_exhausted: {
523
+ status: number;
524
+ body: {
525
+ error: {
526
+ code: string;
527
+ message: string;
528
+ };
529
+ };
530
+ };
531
+ prepay: {
532
+ status: number;
533
+ body: {
534
+ error: {
535
+ code: string;
536
+ message: string;
537
+ };
538
+ };
539
+ };
540
+ invalid_key: {
541
+ status: number;
542
+ body: {
543
+ error: {
544
+ code: number;
545
+ message: string;
546
+ status: string;
547
+ };
548
+ }[];
549
+ };
550
+ leaked_key: {
551
+ status: number;
552
+ body: {
553
+ error: {
554
+ code: string;
555
+ message: string;
556
+ };
557
+ };
558
+ };
559
+ overloaded: {
560
+ status: number;
561
+ body: {
562
+ error: {
563
+ code: string;
564
+ message: string;
565
+ };
566
+ };
567
+ };
568
+ bad_request: {
569
+ status: number;
570
+ body: {
571
+ error: {
572
+ code: string;
573
+ message: string;
574
+ };
575
+ };
576
+ };
577
+ };
578
+ groq: {
579
+ rate_limited: {
580
+ status: number;
581
+ headers: {
582
+ "retry-after": string;
583
+ "x-ratelimit-remaining-tokens": string;
584
+ "x-ratelimit-reset-tokens": string;
585
+ };
586
+ body: {
587
+ error: {
588
+ message: string;
589
+ type: string;
590
+ code: string;
591
+ };
592
+ };
593
+ };
594
+ quota_exhausted: {
595
+ status: number;
596
+ headers: {
597
+ "x-ratelimit-remaining-requests": string;
598
+ "x-ratelimit-reset-requests": string;
599
+ };
600
+ body: {
601
+ error: {
602
+ message: string;
603
+ type: string;
604
+ code: string;
605
+ };
606
+ };
607
+ };
608
+ invalid_key: {
609
+ status: number;
610
+ body: {
611
+ error: {
612
+ message: string;
613
+ type: string;
614
+ code: string;
615
+ };
616
+ };
617
+ };
618
+ overloaded: {
619
+ status: number;
620
+ body: {
621
+ error: {
622
+ message: string;
623
+ type: string;
624
+ };
625
+ };
626
+ };
627
+ bad_request: {
628
+ status: number;
629
+ body: {
630
+ error: {
631
+ message: string;
632
+ type: string;
633
+ };
634
+ };
635
+ };
636
+ };
637
+ "openai-compatible": {
638
+ rate_limited: {
639
+ status: number;
640
+ body: {
641
+ error: {
642
+ message: string;
643
+ type: string;
644
+ };
645
+ };
646
+ };
647
+ quota_exhausted: {
648
+ status: number;
649
+ body: {
650
+ error: {
651
+ message: string;
652
+ type: string;
653
+ };
654
+ };
655
+ };
656
+ invalid_key: {
657
+ status: number;
658
+ body: {
659
+ error: {
660
+ message: string;
661
+ type: string;
662
+ };
663
+ };
664
+ };
665
+ overloaded: {
666
+ status: number;
667
+ body: {
668
+ error: {
669
+ message: string;
670
+ type: string;
671
+ };
672
+ };
673
+ };
674
+ bad_request: {
675
+ status: number;
676
+ body: {
677
+ error: {
678
+ message: string;
679
+ type: string;
680
+ };
681
+ };
682
+ };
683
+ };
684
+ }>;
685
+ /** Creates a fake provider: deterministic replies, latency, errors, 429s and streams by script, in either protocol. */
67
686
  export declare function createFakeProvider(): FakeProvider;