@starci/ai-router 0.5.0 → 0.6.1

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.1 - 2026-11-13
4
+
5
+ - Changed: the README's examples use neutral profile, label and owner names. No code changes.
6
+
7
+ ## 0.6.0 - 2026-11-08
8
+
9
+ - Added: `AiRouterError`, `KeyAdminError` and `MountedKeyError` extend `DomainError` of `@starci/common` (a runtime dependency), so an app and its canon recognise them as coded errors. `AiRouterError.code` is `AI_ROUTER_<CLASS>` (`AI_ROUTER_ERROR_CODES`, `AiRouterErrorCode`, exported); the two key errors keep their code values. Class names, fields and messages are unchanged.
10
+ - Changed: the eight local copies of the non-array object guard are `isPlainRecord` of `@starci/common`; behaviour is identical.
11
+ - Changed: requires `@starci/common` 1.0.1 (exact), the one copy an app installs, so `DomainError` stays one class (this version had not reached npm).
12
+
3
13
  ## 0.5.0 - 2026-10-31
4
14
 
5
15
  Many providers below, each with an array of keys, behind one virtual key per app above; a key whose quota is spent or
package/README.md CHANGED
@@ -138,7 +138,7 @@ providers:
138
138
  models: [{ id: openai/gpt-4o-mini, aliases: [fast] }]
139
139
  defaults: { fallbacks: [smart], deadlineMs: 60000 }
140
140
  profiles:
141
- lesson: { model: fast, fallbacks: [smart] }
141
+ chat: { model: fast, fallbacks: [smart] }
142
142
  grading: { model: smart, allowFallback: false, maxAttempts: 3 }
143
143
  ```
144
144
 
@@ -152,7 +152,7 @@ profiles:
152
152
  | `GET /health` | none; the admin token adds the pool's breakers and keys | `{ "status": "ok" }`, or `degraded` when no provider has a usable key |
153
153
  | `/admin/keys...` | admin token | the [admin API](#admin-api) |
154
154
 
155
- A request's `model` names a profile (`lesson`) or a pool model by id or alias (`gpt-4o-mini`, `fast`); a profile wins
155
+ A request's `model` names a profile (`chat`) or a pool model by id or alias (`gpt-4o-mini`, `fast`); a profile wins
156
156
  when a name is both. A profile call routes by the profile's policy; a direct model call falls back only to the pool
157
157
  defaults' fallbacks that the key may call itself. The answer is the provider's OpenAI body without the router's
158
158
  `routing`; the response carries `x-request-id`, and a unary one `x-ai-router-model` (the model that answered) and
@@ -216,7 +216,7 @@ AiRouterGatewayModule.registerAsync({
216
216
  keys: await openSqliteKeyStore("/data/keys.sqlite"),
217
217
  mountedKeys: [
218
218
  // The secret is sk-starci-<label>- and at least 32 letters, digits, "_" or "-": openssl rand -hex 24
219
- { label: "nivo_lite", secret: () => readFileSync("/run/secrets/nivo_lite_ai_key", "utf8").trim(), profiles: ["lesson"], owner: "nivo-lite", quota: { costPerMonth: 20 } },
219
+ { label: "app_one", secret: () => readFileSync("/run/secrets/app_one_ai_key", "utf8").trim(), profiles: ["chat"], owner: "app-one", quota: { costPerMonth: 20 } },
220
220
  ],
221
221
  listen: true,
222
222
  }),
@@ -254,7 +254,7 @@ Guarded by `Authorization: Bearer <admin token>` (403 `admin_disabled` when no t
254
254
 
255
255
  ```sh
256
256
  RUN="node node_modules/@starci/ai-router/dist/gateway/run.js"
257
- $RUN keys create --label lesson_app --profiles lesson --rpm 60 --cost-per-month 20 --config pool.yaml
257
+ $RUN keys create --label chat_app --profiles chat --rpm 60 --cost-per-month 20 --config pool.yaml
258
258
  $RUN keys list --config pool.yaml
259
259
  $RUN keys usage key_1a2b3c4d5e6f7a8b --from 2026-10-01 --config pool.yaml
260
260
  $RUN keys rotate key_1a2b3c4d5e6f7a8b --url http://gateway:8080 # admin token from AI_ROUTER_ADMIN_TOKEN
@@ -273,7 +273,7 @@ LangChain (JS):
273
273
  import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai"
274
274
 
275
275
  const llm = new ChatOpenAI({
276
- model: "lesson", // a profile, or a pool model such as "gpt-4o-mini"
276
+ model: "chat", // a profile, or a pool model such as "gpt-4o-mini"
277
277
  apiKey: process.env.STARCI_AI_KEY, // sk-starci-...
278
278
  configuration: { baseURL: "http://127.0.0.1:3002/v1" },
279
279
  })
@@ -283,7 +283,7 @@ for await (const chunk of await llm.stream("Count to five.")) process.stdout.wri
283
283
  const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small", apiKey: process.env.STARCI_AI_KEY, configuration: { baseURL: "http://127.0.0.1:3002/v1" } })
284
284
  ```
285
285
 
286
- LangChain (Python): `ChatOpenAI(model="lesson", api_key=..., base_url="http://127.0.0.1:3002/v1")`.
286
+ LangChain (Python): `ChatOpenAI(model="chat", api_key=..., base_url="http://127.0.0.1:3002/v1")`.
287
287
 
288
288
  The OpenAI SDK, or any compatible client:
289
289
 
@@ -291,12 +291,12 @@ The OpenAI SDK, or any compatible client:
291
291
  import OpenAI from "openai"
292
292
 
293
293
  const client = new OpenAI({ apiKey: process.env.STARCI_AI_KEY, baseURL: "http://127.0.0.1:3002/v1" })
294
- const completion = await client.chat.completions.create({ model: "lesson", messages: [{ role: "user", content: "hi" }] })
294
+ const completion = await client.chat.completions.create({ model: "chat", messages: [{ role: "user", content: "hi" }] })
295
295
  ```
296
296
 
297
297
  ```sh
298
298
  curl http://127.0.0.1:3002/v1/chat/completions -H "Authorization: Bearer $STARCI_AI_KEY" \
299
- -H "content-type: application/json" -d '{"model":"lesson","stream":true,"messages":[{"role":"user","content":"hi"}]}'
299
+ -H "content-type: application/json" -d '{"model":"chat","stream":true,"messages":[{"role":"user","content":"hi"}]}'
300
300
  ```
301
301
 
302
302
  ### Deploy
@@ -356,7 +356,7 @@ fails with an `AiRouterError` saying the port is unknown and `listen.port` is th
356
356
  (`127.0.0.1`) and is `0.0.0.0` only when you set it. With `serve`, `gateway.appPort` plus `gateway.portOffset`
357
357
  (default 1) does the same; it cannot be combined with `gateway.port`.
358
358
 
359
- A client of an API on 3001 uses `http://127.0.0.1:3002/v1` as its OpenAI base URL: LangChain (below), OpenClaw, or any
359
+ A client of an API on 3001 uses `http://127.0.0.1:3002/v1` as its OpenAI base URL: LangChain (below) or any
360
360
  OpenAI-compatible agent, with a virtual `sk-starci-...` key as its API key.
361
361
 
362
362
  ## Use it in a Nest app
@@ -477,9 +477,10 @@ the options the same way (`AiRouterModuleOptions<"strict">`) to keep the two in
477
477
  `x-request-id` and `idempotency-key` on every attempt of the call, so a provider that deduplicates sees one request.
478
478
  `headers` adds headers to this call; it can never replace `authorization`.
479
479
 
480
- Every failure is an `AiRouterError` with `errorClass`, `retryable`, `status`, `provider`, `key` (alias), `model`,
480
+ Every failure is an `AiRouterError`, a `DomainError` of `@starci/common` whose `code` is `AI_ROUTER_` and its class in upper case
481
+ (`AI_ROUTER_QUOTA`; the table is `AI_ROUTER_ERROR_CODES`) and whose `message` is the sentence. It carries `errorClass`, `retryable`, `status`, `provider`, `key` (alias), `model`,
481
482
  `requestId`, `attempts` (every failed attempt: where and why), `afterFirstToken` and `retryAt` (when a 429 said to
482
- come back).
483
+ come back). `KeyAdminError` and `MountedKeyError` are `DomainError`s too, coded by the values listed for the gateway keys below.
483
484
 
484
485
  On application shutdown (`app.close()`, or a signal after `enableShutdownHooks()`), the service aborts every call still
485
486
  in flight through it (a stream ends with `cancelled`), rejects later calls as `cancelled`, and releases the `on`
package/dist/classify.js CHANGED
@@ -1,6 +1,4 @@
1
- function isRecord(value) {
2
- return typeof value === "object" && value !== null && !Array.isArray(value);
3
- }
1
+ import { isPlainRecord } from "@starci/common";
4
2
  function text(value) {
5
3
  if (typeof value === "string")
6
4
  return value;
@@ -16,11 +14,11 @@ function text(value) {
16
14
  */
17
15
  export function readProviderError(body, status) {
18
16
  const root = Array.isArray(body) ? body[0] : body;
19
- const error = isRecord(root) ? (isRecord(root.error) ? root.error : typeof root.code === "string" ? root : undefined) : undefined;
17
+ const error = isPlainRecord(root) ? (isPlainRecord(root.error) ? root.error : typeof root.code === "string" ? root : undefined) : undefined;
20
18
  if (error === undefined)
21
19
  return { status, type: "", code: "", detail: "", message: typeof body === "string" ? body : "" };
22
- const details = isRecord(error.details) ? error.details : {};
23
- const metadata = isRecord(error.metadata) ? error.metadata : {};
20
+ const details = isPlainRecord(error.details) ? error.details : {};
21
+ const metadata = isPlainRecord(error.metadata) ? error.metadata : {};
24
22
  const numeric = typeof error.code === "number" ? error.code : undefined;
25
23
  return {
26
24
  status: status ?? numeric,
package/dist/errors.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { DomainError } from "@starci/common";
1
2
  import type { ErrorClass } from "./types.js";
2
3
  /** One failed attempt as an error lists it: where it went and why it failed, never a key value. */
3
4
  export interface AttemptFailure {
@@ -24,8 +25,12 @@ export interface AiRouterErrorInit {
24
25
  }
25
26
  /** True for a class another key, provider or model may succeed at. */
26
27
  export declare function isRetryable(errorClass: ErrorClass): boolean;
27
- /** The one error the router throws. `errorClass` says why; `attempts` lists every failed attempt of the call. */
28
- export declare class AiRouterError extends Error {
28
+ /** The stable code of each error class: what an `AiRouterError` carries as its `code`. */
29
+ export declare const AI_ROUTER_ERROR_CODES: Readonly<Record<ErrorClass, `AI_ROUTER_${Uppercase<ErrorClass>}`>>;
30
+ /** A code of `AiRouterError`: `AI_ROUTER_` and its error class in upper case. */
31
+ export type AiRouterErrorCode = (typeof AI_ROUTER_ERROR_CODES)[ErrorClass];
32
+ /** The one error the router throws, a `DomainError` of `@starci/common` coded by its class. `errorClass` says why; `attempts` lists every failed attempt of the call; `message` is the sentence, never the code. */
33
+ export declare class AiRouterError extends DomainError<AiRouterErrorCode> {
29
34
  readonly errorClass: ErrorClass;
30
35
  readonly retryable: boolean;
31
36
  readonly status: number | undefined;
package/dist/errors.js CHANGED
@@ -1,11 +1,27 @@
1
+ import { DomainError } from "@starci/common";
1
2
  import { classifyFailure } from "./classify.js";
2
3
  const RETRYABLE = new Set(["rate_limit", "quota", "auth", "transient", "timeout", "network", "stream"]);
3
4
  /** True for a class another key, provider or model may succeed at. */
4
5
  export function isRetryable(errorClass) {
5
6
  return RETRYABLE.has(errorClass);
6
7
  }
7
- /** The one error the router throws. `errorClass` says why; `attempts` lists every failed attempt of the call. */
8
- export class AiRouterError extends Error {
8
+ /** The stable code of each error class: what an `AiRouterError` carries as its `code`. */
9
+ export const AI_ROUTER_ERROR_CODES = {
10
+ rate_limit: "AI_ROUTER_RATE_LIMIT",
11
+ quota: "AI_ROUTER_QUOTA",
12
+ auth: "AI_ROUTER_AUTH",
13
+ transient: "AI_ROUTER_TRANSIENT",
14
+ timeout: "AI_ROUTER_TIMEOUT",
15
+ network: "AI_ROUTER_NETWORK",
16
+ stream: "AI_ROUTER_STREAM",
17
+ invalid_request: "AI_ROUTER_INVALID_REQUEST",
18
+ cancelled: "AI_ROUTER_CANCELLED",
19
+ deadline: "AI_ROUTER_DEADLINE",
20
+ no_candidate: "AI_ROUTER_NO_CANDIDATE",
21
+ config: "AI_ROUTER_CONFIG",
22
+ };
23
+ /** The one error the router throws, a `DomainError` of `@starci/common` coded by its class. `errorClass` says why; `attempts` lists every failed attempt of the call; `message` is the sentence, never the code. */
24
+ export class AiRouterError extends DomainError {
9
25
  errorClass;
10
26
  retryable;
11
27
  status;
@@ -18,7 +34,8 @@ export class AiRouterError extends Error {
18
34
  retryAt;
19
35
  /** Builds the error from its fields. */
20
36
  constructor(init) {
21
- super(init.message);
37
+ super({ code: AI_ROUTER_ERROR_CODES[init.errorClass] });
38
+ this.message = init.message;
22
39
  this.name = "AiRouterError";
23
40
  this.errorClass = init.errorClass;
24
41
  this.retryable = isRetryable(init.errorClass);
package/dist/fake.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  /**
2
3
  * Each provider's real error answers (status, body, headers) as its docs showed them on 2026-10-31 (docs/design.md,
3
4
  * the classification table), for a spec to script with `fake.on(match, PROVIDER_ERRORS.anthropic.quota_exhausted)`.
@@ -74,9 +75,6 @@ export const PROVIDER_ERRORS = Object.freeze({
74
75
  bad_request: { status: 400, body: { error: { message: "bad request", type: "invalid_request_error" } } },
75
76
  },
76
77
  });
77
- function isRecord(value) {
78
- return typeof value === "object" && value !== null && !Array.isArray(value);
79
- }
80
78
  function wait(ms, signal) {
81
79
  return new Promise((resolve, reject) => {
82
80
  const aborted = () => (signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
@@ -280,7 +278,7 @@ export function createFakeProvider() {
280
278
  const url = new URL(input);
281
279
  const headers = headerRecord(init);
282
280
  const parsed = typeof init.body === "string" ? JSON.parse(init.body) : {};
283
- const body = isRecord(parsed) ? parsed : {};
281
+ const body = isPlainRecord(parsed) ? parsed : {};
284
282
  const call = {
285
283
  url: input,
286
284
  path: url.pathname,
@@ -1,3 +1,4 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  import { readFile } from "node:fs/promises";
2
3
  import { dirname, extname, resolve } from "node:path";
3
4
  import { parse as parseYaml } from "yaml";
@@ -94,9 +95,6 @@ const SECRET_HEADER = /authorization|api[-_]?key|token|secret|cookie/i;
94
95
  function configError(message) {
95
96
  return new AiRouterError({ errorClass: "config", message });
96
97
  }
97
- function isRecord(value) {
98
- return typeof value === "object" && value !== null && !Array.isArray(value);
99
- }
100
98
  function check(value, schema, where) {
101
99
  if (schema === "string") {
102
100
  if (typeof value !== "string")
@@ -141,7 +139,7 @@ function check(value, schema, where) {
141
139
  });
142
140
  return;
143
141
  }
144
- if (!isRecord(value))
142
+ if (!isPlainRecord(value))
145
143
  throw configError(`${where} must be a mapping`);
146
144
  if ("map" in schema) {
147
145
  for (const [name, item] of Object.entries(value))
@@ -197,11 +195,11 @@ export function parseGatewayConfig(raw, base = process.cwd(), env = process.env)
197
195
  const file = raw;
198
196
  const providers = file.providers.map((provider, index) => {
199
197
  const where = `config.providers[${String(index)}]`;
200
- for (const name of Object.keys(isRecord(provider.headers) ? provider.headers : {})) {
198
+ for (const name of Object.keys(isPlainRecord(provider.headers) ? provider.headers : {})) {
201
199
  if (SECRET_HEADER.test(name))
202
200
  throw configError(`${where}.headers.${name} would carry a secret in the config file; give keys under keys[] by reference`);
203
201
  }
204
- const listed = Array.isArray(provider.keys) ? provider.keys.filter(isRecord) : [];
202
+ const listed = Array.isArray(provider.keys) ? provider.keys.filter(isPlainRecord) : [];
205
203
  const prefix = typeof provider.keysFromEnv === "string" ? provider.keysFromEnv : undefined;
206
204
  if (prefix === undefined && listed.length === 0)
207
205
  throw configError(`${where} needs keys or keysFromEnv`);
@@ -249,14 +247,14 @@ export function parseGatewayConfig(raw, base = process.cwd(), env = process.env)
249
247
  port,
250
248
  host: gateway.host ?? "127.0.0.1",
251
249
  maxBodyBytes,
252
- adminToken: isRecord(gateway.adminToken) ? secretRef(gateway.adminToken, "config.gateway.adminToken", base) : null,
250
+ adminToken: isPlainRecord(gateway.adminToken) ? secretRef(gateway.adminToken, "config.gateway.adminToken", base) : null,
253
251
  keyStore: store.type === "sqlite" ? { type: "sqlite", path: store.path === ":memory:" ? ":memory:" : resolve(base, store.path ?? "") } : { type: "memory" },
254
252
  },
255
253
  };
256
254
  }
257
255
  /** A store setting with its path resolved from the config file's folder; memory when absent. */
258
256
  function storeOf(value, where, base) {
259
- if (!isRecord(value) || value.type !== "sqlite")
257
+ if (!isPlainRecord(value) || value.type !== "sqlite")
260
258
  return { type: "memory" };
261
259
  if (typeof value.path !== "string")
262
260
  throw configError(`${where}.path is required for a sqlite store`);
@@ -1,3 +1,4 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
2
3
  import { createServer } from "node:http";
3
4
  import { AiRouterError } from "../errors.js";
@@ -22,9 +23,6 @@ class GatewayError extends Error {
22
23
  }
23
24
  const DEFAULT_MAX_BODY = 4 * 1024 * 1024;
24
25
  const MINUTE = 60_000;
25
- function isRecord(value) {
26
- return typeof value === "object" && value !== null && !Array.isArray(value);
27
- }
28
26
  function errorBody(error) {
29
27
  return { error: { message: error.message, type: error.type, param: null, code: error.code } };
30
28
  }
@@ -255,7 +253,7 @@ export function createGateway(router, options) {
255
253
  const started = clock();
256
254
  try {
257
255
  const body = await readBody(request, maxBody);
258
- if (!isRecord(body))
256
+ if (!isPlainRecord(body))
259
257
  throw new GatewayError(400, "invalid_request", "the request body must be a JSON object");
260
258
  if (operation === "chat" && !Array.isArray(body.messages))
261
259
  throw new GatewayError(400, "invalid_request", "messages is required");
@@ -307,7 +305,7 @@ export function createGateway(router, options) {
307
305
  const headers = { "x-request-id": requestId };
308
306
  const controller = controllerFor(response);
309
307
  // Usage is always asked of the provider, for the key's accounting; the client gets the usage chunk only if it asked.
310
- const asked = isRecord(body.stream_options) ? body.stream_options : {};
308
+ const asked = isPlainRecord(body.stream_options) ? body.stream_options : {};
311
309
  const wantsUsage = asked.include_usage === true;
312
310
  const call = { ...callBody(body, routed), stream_options: { ...asked, include_usage: true } };
313
311
  const slot = {};
@@ -435,7 +433,7 @@ export function createGateway(router, options) {
435
433
  }
436
434
  if (method === "PATCH") {
437
435
  const patch = await readBody(request, maxBody);
438
- if (!isRecord(patch))
436
+ if (!isPlainRecord(patch))
439
437
  throw new GatewayError(400, "invalid_key_spec", "the update must be a JSON object");
440
438
  send(response, 200, await admin.update(id, patch));
441
439
  return;
@@ -1,5 +1,5 @@
1
- export { AiRouterError } from "../errors.js";
2
- export type { AttemptFailure } from "../errors.js";
1
+ export { AI_ROUTER_ERROR_CODES, AiRouterError } from "../errors.js";
2
+ export type { AiRouterErrorCode, AttemptFailure } from "../errors.js";
3
3
  export { createRouter } from "../router.js";
4
4
  export { classifyFailure, readProviderError } from "../classify.js";
5
5
  export type { Classified, ProviderErrorInfo } from "../classify.js";
@@ -1,4 +1,4 @@
1
- export { AiRouterError } from "../errors.js";
1
+ export { AI_ROUTER_ERROR_CODES, AiRouterError } from "../errors.js";
2
2
  export { createRouter } from "../router.js";
3
3
  export { classifyFailure, readProviderError } from "../classify.js";
4
4
  export { keysFromEnv, poolFromEnv, providersFromEnv, virtualKeyFromEnv } from "../env.js";
@@ -1,3 +1,4 @@
1
+ import { DomainError } from "@starci/common";
1
2
  import type { MaybePromise, RouterCatalog } from "../types.js";
2
3
  /** The limits of one virtual key; an absent field is no limit. Days and months are UTC. */
3
4
  export interface KeyQuota {
@@ -122,8 +123,7 @@ export declare class MemoryKeyStore implements KeyStore {
122
123
  usage(id: string, from: string, to: string): readonly UsageRow[];
123
124
  }
124
125
  /** Why an admin operation was refused: an unknown id, an invalid spec, a change to a revoked key, or a change to a mounted key. */
125
- export declare class KeyAdminError extends Error {
126
- readonly code: "not_found" | "invalid" | "revoked" | "mounted";
126
+ export declare class KeyAdminError extends DomainError<"not_found" | "invalid" | "revoked" | "mounted"> {
127
127
  /** Builds the error. */
128
128
  constructor(code: KeyAdminError["code"], message: string);
129
129
  }
@@ -131,8 +131,7 @@ export declare class KeyAdminError extends Error {
131
131
  * Why the gateway refused to start over its mounted keys: an invalid key, a label given twice, or a secret or id a
132
132
  * stored key already holds. It names the label and the key id, never the secret.
133
133
  */
134
- export declare class MountedKeyError extends Error {
135
- readonly code: "invalid" | "duplicate_label" | "collision";
134
+ export declare class MountedKeyError extends DomainError<"invalid" | "duplicate_label" | "collision"> {
136
135
  /** The label of the mounted key refused. */
137
136
  readonly label: string;
138
137
  /** Builds the error. */
@@ -1,3 +1,4 @@
1
+ import { DomainError } from "@starci/common";
1
2
  import { createHash, randomBytes } from "node:crypto";
2
3
  /** Adds a request to a day row; the stores share it so a row means the same everywhere. */
3
4
  export function addToRow(row, keyId, day, delta) {
@@ -57,28 +58,26 @@ export class MemoryKeyStore {
57
58
  }
58
59
  }
59
60
  /** Why an admin operation was refused: an unknown id, an invalid spec, a change to a revoked key, or a change to a mounted key. */
60
- export class KeyAdminError extends Error {
61
- code;
61
+ export class KeyAdminError extends DomainError {
62
62
  /** Builds the error. */
63
63
  constructor(code, message) {
64
- super(message);
64
+ super({ code });
65
+ this.message = message;
65
66
  this.name = "KeyAdminError";
66
- this.code = code;
67
67
  }
68
68
  }
69
69
  /**
70
70
  * Why the gateway refused to start over its mounted keys: an invalid key, a label given twice, or a secret or id a
71
71
  * stored key already holds. It names the label and the key id, never the secret.
72
72
  */
73
- export class MountedKeyError extends Error {
74
- code;
73
+ export class MountedKeyError extends DomainError {
75
74
  /** The label of the mounted key refused. */
76
75
  label;
77
76
  /** Builds the error. */
78
77
  constructor(code, label, message) {
79
- super(message);
78
+ super({ code });
79
+ this.message = message;
80
80
  this.name = "MountedKeyError";
81
- this.code = code;
82
81
  this.label = label;
83
82
  }
84
83
  }
package/dist/router.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  import { AttemptError } from "./attempt.js";
2
3
  import { classifyFailure } from "./classify.js";
3
4
  import { buildCatalog, resolvePolicy, resolveSettings, validateConfig } from "./config.js";
@@ -155,9 +156,6 @@ function chatNeed(request, streaming, policy) {
155
156
  function hasToken(chunk) {
156
157
  return chunk.choices.some((choice) => Object.entries(choice.delta).some(([field, value]) => field !== "role" && value !== null && value !== undefined && value !== "" && !(Array.isArray(value) && value.length === 0)));
157
158
  }
158
- function isRecord(value) {
159
- return typeof value === "object" && value !== null && !Array.isArray(value);
160
- }
161
159
  function statusOf(error) {
162
160
  return error.status === undefined ? {} : { status: error.status };
163
161
  }
@@ -165,8 +163,8 @@ function statusOf(error) {
165
163
  function failureOf(lane, status, body, info, fallback) {
166
164
  const classified = classifyFailure(presetOf(lane.provider).kind, status, body);
167
165
  const root = Array.isArray(body) ? body[0] : body;
168
- const error = isRecord(root) && isRecord(root.error) ? root.error : root;
169
- const detail = isRecord(error) && typeof error.message === "string" ? error.message : typeof body === "string" && body !== "" ? body : fallback;
166
+ const error = isPlainRecord(root) && isPlainRecord(root.error) ? root.error : root;
167
+ const detail = isPlainRecord(error) && typeof error.message === "string" ? error.message : typeof body === "string" && body !== "" ? body : fallback;
170
168
  const message = status === undefined ? detail : `HTTP ${String(status)}: ${detail}`;
171
169
  return new AttemptError(classified.errorClass, message, {
172
170
  ...(status === undefined ? {} : { status }),
@@ -421,10 +419,10 @@ export function createRouter(config) {
421
419
  catch (error) {
422
420
  throw scope.cause === null ? new AttemptError("transient", "the provider answered a body that is not JSON") : scope.classify(error);
423
421
  }
424
- if (!isRecord(json) && !Array.isArray(json))
422
+ if (!isPlainRecord(json) && !Array.isArray(json))
425
423
  throw new AttemptError("transient", "the provider answered a body that is not an object");
426
424
  // An error inside a 200 body (OpenRouter does this) is classified like an error status.
427
- if (!isRecord(json) || (json.error !== undefined && json.error !== null))
425
+ if (!isPlainRecord(json) || (json.error !== undefined && json.error !== null))
428
426
  throw failureOf(pick.lane, undefined, json, null, "the provider answered an error");
429
427
  const parsed = parse(json, pick.lane);
430
428
  const latencyMs = Date.now() - started;
package/dist/shapes.js CHANGED
@@ -1,12 +1,10 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  /**
2
3
  * Reads provider answers into the router's typed shapes, field by field. A provider's extra fields (DeepSeek's
3
4
  * `reasoning_content`, a `refusal`, `system_fingerprint`) ride along; a body without the fields the router reads is
4
5
  * refused (undefined), and the attempt fails as a malformed answer.
5
6
  */
6
7
  const ASSISTANT = "assistant";
7
- function isRecord(value) {
8
- return typeof value === "object" && value !== null && !Array.isArray(value);
9
- }
10
8
  function text(value, fallback = "") {
11
9
  return typeof value === "string" ? value : fallback;
12
10
  }
@@ -15,18 +13,18 @@ function number(value, fallback = 0) {
15
13
  }
16
14
  /** The usage of an answer, when it reports prompt tokens. */
17
15
  export function readUsage(value) {
18
- if (!isRecord(value) || typeof value.prompt_tokens !== "number")
16
+ if (!isPlainRecord(value) || typeof value.prompt_tokens !== "number")
19
17
  return undefined;
20
18
  const completion = typeof value.completion_tokens === "number" ? { completion_tokens: value.completion_tokens } : {};
21
19
  return { ...value, prompt_tokens: value.prompt_tokens, ...completion, total_tokens: number(value.total_tokens, value.prompt_tokens + number(value.completion_tokens)) };
22
20
  }
23
21
  function toolCall(value) {
24
- if (!isRecord(value) || !isRecord(value.function) || typeof value.id !== "string" || typeof value.function.name !== "string")
22
+ if (!isPlainRecord(value) || !isPlainRecord(value.function) || typeof value.id !== "string" || typeof value.function.name !== "string")
25
23
  return undefined;
26
24
  return { id: value.id, type: "function", function: { name: value.function.name, arguments: text(value.function.arguments, "{}") } };
27
25
  }
28
26
  function choice(value, at) {
29
- if (!isRecord(value) || !isRecord(value.message))
27
+ if (!isPlainRecord(value) || !isPlainRecord(value.message))
30
28
  return undefined;
31
29
  const message = value.message;
32
30
  const calls = Array.isArray(message.tool_calls) ? message.tool_calls.map(toolCall).filter((call) => call !== undefined) : [];
@@ -55,9 +53,9 @@ export function readCompletion(json) {
55
53
  };
56
54
  }
57
55
  function toolDelta(value, at) {
58
- if (!isRecord(value))
56
+ if (!isPlainRecord(value))
59
57
  return undefined;
60
- const fn = isRecord(value.function) ? value.function : undefined;
58
+ const fn = isPlainRecord(value.function) ? value.function : undefined;
61
59
  return {
62
60
  index: number(value.index, at),
63
61
  ...(typeof value.id === "string" ? { id: value.id } : {}),
@@ -73,9 +71,9 @@ export function readChunk(json) {
73
71
  return undefined;
74
72
  const choices = [];
75
73
  for (const [at, entry] of json.choices.entries()) {
76
- if (!isRecord(entry))
74
+ if (!isPlainRecord(entry))
77
75
  return undefined;
78
- const delta = isRecord(entry.delta) ? entry.delta : {};
76
+ const delta = isPlainRecord(entry.delta) ? entry.delta : {};
79
77
  const calls = Array.isArray(delta.tool_calls) ? delta.tool_calls.map(toolDelta).filter((call) => call !== undefined) : undefined;
80
78
  const { role, content } = delta;
81
79
  const rest = Object.fromEntries(Object.entries(delta).filter(([field]) => field !== "role" && field !== "content" && field !== "tool_calls"));
@@ -111,7 +109,7 @@ export function readEmbeddings(json) {
111
109
  return undefined;
112
110
  const data = [];
113
111
  for (const [at, entry] of json.data.entries()) {
114
- if (!isRecord(entry))
112
+ if (!isPlainRecord(entry))
115
113
  return undefined;
116
114
  const vector = entry.embedding;
117
115
  const numbers = Array.isArray(vector) ? vector.filter((value) => typeof value === "number") : undefined;
package/dist/store.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  /** A record with nothing known: a closed breaker, an enabled key, unknown headroom, nothing spent. */
2
3
  export const EMPTY_RECORD = Object.freeze({
3
4
  breaker: "closed",
@@ -18,9 +19,6 @@ export const EMPTY_RECORD = Object.freeze({
18
19
  spendMonth: "",
19
20
  spendMonthCost: 0,
20
21
  });
21
- function isRecord(value) {
22
- return typeof value === "object" && value !== null && !Array.isArray(value);
23
- }
24
22
  function num(value, fallback) {
25
23
  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
26
24
  }
@@ -41,7 +39,7 @@ function reason(value) {
41
39
  * value that is not a record at all reads as undefined. Durable adapters parse their JSON through it.
42
40
  */
43
41
  export function toHealthRecord(value) {
44
- if (!isRecord(value))
42
+ if (!isPlainRecord(value))
45
43
  return undefined;
46
44
  return {
47
45
  breaker: value.breaker === "open" ? "open" : "closed",
@@ -1,5 +1,5 @@
1
+ import { isPlainRecord } from "@starci/common";
1
2
  import { AttemptError } from "../attempt.js";
2
- import { isRecord } from "./wire.js";
3
3
  /**
4
4
  * The Anthropic Messages API (`POST /v1/messages`, read 2026-10-31 at platform.claude.com/docs/en/api/messages and
5
5
  * /build-with-claude/streaming) behind the OpenAI chat-completions shape. docs/design.md, "The Anthropic adapter", maps
@@ -19,11 +19,11 @@ function textOf(content) {
19
19
  return content;
20
20
  if (!Array.isArray(content))
21
21
  return "";
22
- return content.map((part) => (isRecord(part) && typeof part.text === "string" ? part.text : "")).join("");
22
+ return content.map((part) => (isPlainRecord(part) && typeof part.text === "string" ? part.text : "")).join("");
23
23
  }
24
24
  /** An OpenAI `image_url` part as an Anthropic image block: a data URL becomes base64, anything else a URL source. */
25
25
  function imageBlock(part) {
26
- const image = isRecord(part.image_url) ? part.image_url.url : part.image_url;
26
+ const image = isPlainRecord(part.image_url) ? part.image_url.url : part.image_url;
27
27
  if (typeof image !== "string")
28
28
  throw refuse("an image_url part has no url");
29
29
  const data = /^data:([^;,]+);base64,(.*)$/s.exec(image);
@@ -41,7 +41,7 @@ function blocks(content) {
41
41
  throw refuse("message content must be a string or a list of parts");
42
42
  const out = [];
43
43
  for (const part of content) {
44
- if (!isRecord(part))
44
+ if (!isPlainRecord(part))
45
45
  continue;
46
46
  if (part.type === "text") {
47
47
  if (typeof part.text === "string" && part.text !== "")
@@ -55,7 +55,7 @@ function blocks(content) {
55
55
  return out;
56
56
  }
57
57
  function toolUse(call) {
58
- if (!isRecord(call) || !isRecord(call.function) || typeof call.id !== "string" || typeof call.function.name !== "string")
58
+ if (!isPlainRecord(call) || !isPlainRecord(call.function) || typeof call.id !== "string" || typeof call.function.name !== "string")
59
59
  throw refuse("a tool call needs an id and a function name");
60
60
  const raw = call.function.arguments;
61
61
  let input = {};
@@ -67,7 +67,7 @@ function toolUse(call) {
67
67
  throw refuse(`the arguments of tool call ${call.id} are not JSON`);
68
68
  }
69
69
  }
70
- if (!isRecord(input))
70
+ if (!isPlainRecord(input))
71
71
  throw refuse(`the arguments of tool call ${call.id} must be a JSON object`);
72
72
  return { type: "tool_use", id: call.id, name: call.function.name, input };
73
73
  }
@@ -88,7 +88,7 @@ function conversation(messages) {
88
88
  turns.push({ role, content });
89
89
  };
90
90
  for (const message of messages) {
91
- if (!isRecord(message))
91
+ if (!isPlainRecord(message))
92
92
  throw refuse("every message must be an object");
93
93
  const role = message.role;
94
94
  if (role === "system" || role === "developer") {
@@ -116,13 +116,13 @@ function tools(list) {
116
116
  if (!Array.isArray(list) || list.length === 0)
117
117
  return undefined;
118
118
  return list.map((tool) => {
119
- if (!isRecord(tool) || tool.type !== "function" || !isRecord(tool.function))
119
+ if (!isPlainRecord(tool) || tool.type !== "function" || !isPlainRecord(tool.function))
120
120
  return tool;
121
121
  const fn = tool.function;
122
122
  return {
123
123
  name: fn.name,
124
124
  ...(typeof fn.description === "string" ? { description: fn.description } : {}),
125
- input_schema: isRecord(fn.parameters) ? fn.parameters : { type: "object", properties: {} },
125
+ input_schema: isPlainRecord(fn.parameters) ? fn.parameters : { type: "object", properties: {} },
126
126
  ...(fn.strict === true ? { strict: true } : {}),
127
127
  };
128
128
  });
@@ -135,7 +135,7 @@ function toolChoice(choice, parallel) {
135
135
  out = { type: "none" };
136
136
  else if (choice === "required")
137
137
  out = { type: "any" };
138
- else if (isRecord(choice) && isRecord(choice.function) && typeof choice.function.name === "string")
138
+ else if (isPlainRecord(choice) && isPlainRecord(choice.function) && typeof choice.function.name === "string")
139
139
  out = { type: "tool", name: choice.function.name };
140
140
  if (parallel === false)
141
141
  out = { ...(out ?? { type: "auto" }), disable_parallel_tool_use: true };
@@ -148,10 +148,10 @@ export function toAnthropicRequest(body, model, stream, provider) {
148
148
  const { system, turns } = conversation(body.messages);
149
149
  const format = body.response_format;
150
150
  let outputConfig = body.output_config;
151
- if (isRecord(format) && format.type === "json_object")
151
+ if (isPlainRecord(format) && format.type === "json_object")
152
152
  system.push("Answer with one JSON object and nothing else.");
153
- if (isRecord(format) && format.type === "json_schema" && isRecord(format.json_schema) && isRecord(format.json_schema.schema)) {
154
- outputConfig = { ...(isRecord(outputConfig) ? outputConfig : {}), format: { type: "json_schema", schema: format.json_schema.schema } };
153
+ if (isPlainRecord(format) && format.type === "json_schema" && isPlainRecord(format.json_schema) && isPlainRecord(format.json_schema.schema)) {
154
+ outputConfig = { ...(isPlainRecord(outputConfig) ? outputConfig : {}), format: { type: "json_schema", schema: format.json_schema.schema } };
155
155
  }
156
156
  const maxTokens = [body.max_completion_tokens, body.max_tokens].find((value) => typeof value === "number") ?? provider.defaultMaxTokens ?? ANTHROPIC_DEFAULT_MAX_TOKENS;
157
157
  const stop = typeof body.stop === "string" ? [body.stop] : Array.isArray(body.stop) ? body.stop : undefined;
@@ -200,7 +200,7 @@ function count(value) {
200
200
  }
201
201
  /** Anthropic usage as OpenAI usage: the prompt counts the cache reads and writes, which Anthropic lists apart. */
202
202
  export function usageOf(usage, outputOverride) {
203
- if (!isRecord(usage))
203
+ if (!isPlainRecord(usage))
204
204
  return undefined;
205
205
  const cached = count(usage.cache_read_input_tokens);
206
206
  const prompt = count(usage.input_tokens) + count(usage.cache_creation_input_tokens) + cached;
@@ -209,7 +209,7 @@ export function usageOf(usage, outputOverride) {
209
209
  }
210
210
  /** An Anthropic message as an OpenAI `chat.completion`. */
211
211
  export function fromAnthropicMessage(json) {
212
- const content = Array.isArray(json.content) ? json.content.filter(isRecord) : [];
212
+ const content = Array.isArray(json.content) ? json.content.filter(isPlainRecord) : [];
213
213
  const text = content
214
214
  .filter((block) => block.type === "text" && typeof block.text === "string")
215
215
  .map((block) => String(block.text))
@@ -257,23 +257,23 @@ export const anthropicWire = {
257
257
  yield { kind: "malformed" };
258
258
  continue;
259
259
  }
260
- if (!isRecord(data))
260
+ if (!isPlainRecord(data))
261
261
  continue;
262
262
  switch (data.type) {
263
263
  case "message_start": {
264
- const message = isRecord(data.message) ? data.message : {};
264
+ const message = isPlainRecord(data.message) ? data.message : {};
265
265
  if (typeof message.id === "string")
266
266
  id = message.id;
267
267
  if (typeof message.model === "string")
268
268
  model = message.model;
269
269
  inputUsage = message.usage;
270
- if (isRecord(message.usage))
270
+ if (isPlainRecord(message.usage))
271
271
  output = count(message.usage.output_tokens);
272
272
  yield chunk({ role: "assistant", content: "" });
273
273
  break;
274
274
  }
275
275
  case "content_block_start": {
276
- const block = isRecord(data.content_block) ? data.content_block : {};
276
+ const block = isPlainRecord(data.content_block) ? data.content_block : {};
277
277
  const index = count(data.index);
278
278
  if (block.type === "tool_use") {
279
279
  const call = toolIndex.size;
@@ -285,7 +285,7 @@ export const anthropicWire = {
285
285
  break;
286
286
  }
287
287
  case "content_block_delta": {
288
- const delta = isRecord(data.delta) ? data.delta : {};
288
+ const delta = isPlainRecord(data.delta) ? data.delta : {};
289
289
  if (delta.type === "text_delta" && typeof delta.text === "string")
290
290
  yield chunk({ content: delta.text });
291
291
  else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
@@ -296,9 +296,9 @@ export const anthropicWire = {
296
296
  break;
297
297
  }
298
298
  case "message_delta": {
299
- const delta = isRecord(data.delta) ? data.delta : {};
299
+ const delta = isPlainRecord(data.delta) ? data.delta : {};
300
300
  // message_delta's usage is cumulative: the last one is the total.
301
- if (isRecord(data.usage) && typeof data.usage.output_tokens === "number")
301
+ if (isPlainRecord(data.usage) && typeof data.usage.output_tokens === "number")
302
302
  output = data.usage.output_tokens;
303
303
  yield chunk({}, finishReason(delta.stop_reason));
304
304
  break;
@@ -36,7 +36,5 @@ export interface Wire {
36
36
  /** A provider stream as OpenAI chunks; the router stops at the end of the iterable. */
37
37
  chunks(events: AsyncIterable<SseEvent>): AsyncGenerator<WireEvent, void, undefined>;
38
38
  }
39
- /** True for a plain object. */
40
- export declare function isRecord(value: unknown): value is Record<string, unknown>;
41
39
  /** The OpenAI chat-completions and embeddings API with a bearer key, which every OpenAI-compatible provider speaks. */
42
40
  export declare const openAiWire: Wire;
package/dist/wire/wire.js CHANGED
@@ -1,7 +1,4 @@
1
- /** True for a plain object. */
2
- export function isRecord(value) {
3
- return typeof value === "object" && value !== null && !Array.isArray(value);
4
- }
1
+ import { isPlainRecord } from "@starci/common";
5
2
  /** The OpenAI chat-completions and embeddings API with a bearer key, which every OpenAI-compatible provider speaks. */
6
3
  export const openAiWire = {
7
4
  secretHeaders: ["authorization"],
@@ -21,7 +18,7 @@ export const openAiWire = {
21
18
  yield { kind: "malformed" };
22
19
  continue;
23
20
  }
24
- if (!isRecord(json))
21
+ if (!isPlainRecord(json))
25
22
  continue;
26
23
  // OpenRouter streams an error mid-stream as a chunk with a top-level error (and finish_reason "error").
27
24
  if (json.error !== undefined && json.error !== null) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/ai-router",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
4
4
  "description": "A router for OpenAI-compatible calls across many providers (Anthropic through a protocol adapter, OpenRouter, Qwen, DeepSeek, OpenAI, Gemini, Groq and any OpenAI-compatible endpoint), each with an array of keys, behind one virtual key: an OpenAI-compatible gateway with virtual keys, quotas and usage, a NestJS module (AiRouterModule, AiRouterService, AiRouterGatewayModule), and createRouter for plain Node, with health-aware selection, a persisted key blacklist for spent quotas and refused secrets, circuit breakers, rate-limit awareness, failover across providers and models by profile, pinned embeddings, config from env and redacted telemetry.",
5
5
  "keywords": [
6
6
  "ai",
@@ -91,6 +91,7 @@
91
91
  },
92
92
  "devDependencies": {
93
93
  "@eslint/js": "10.0.1",
94
+ "@starci/common": "file:../common",
94
95
  "@nestjs/common": "12.1.3",
95
96
  "@nestjs/core": "12.1.3",
96
97
  "@nestjs/testing": "12.1.3",
@@ -103,6 +104,7 @@
103
104
  "typescript-eslint": "8.72.0"
104
105
  },
105
106
  "dependencies": {
107
+ "@starci/common": "1.0.1",
106
108
  "yaml": "^2.9.1"
107
109
  },
108
110
  "peerDependenciesMeta": {
@@ -115,5 +117,7 @@
115
117
  "reflect-metadata": {
116
118
  "optional": "true"
117
119
  }
118
- }
120
+ },
121
+ "gitHead": "5ba3e3393ad44562f0245d829949e70a2313af81",
122
+ "starciSource": "236cf93297937b0438f9af5156b9a4794d2d1c54c05b91331e0fd16db80cbae6"
119
123
  }