@lacspace/keypool 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,42 @@
+# @lacspace/keypool
+
+**Turn five free keys into one big quota.** Provider-agnostic API-key rotation and rate-limit accounting: pool N keys per provider, track RPM/RPD/TPM/TPD per key (and per model — Groq's token-per-day is per model), round-robin among healthy keys, cool down on `429` using `retry-after`, and quarantine invalid keys. `pick()` hands you a usable key or `null`; `report()` feeds the outcome back. Persist state through a tiny adapter so every process shares one pool. Zero dependencies, isomorphic.
+
+```bash
+npm i @lacspace/keypool
+```
+
+```ts
+import { createKeypool, kvStore } from "@lacspace/keypool";
+
+const pool = createKeypool({
+  keys: [
+    { id: "gem-1", provider: "gemini", secret: process.env.GEMINI_1! },
+    { id: "gem-2", provider: "gemini", secret: process.env.GEMINI_2! },
+    { id: "gem-3", provider: "gemini", secret: process.env.GEMINI_3! },
+  ],
+  providerLimits: { gemini: { rpm: 15, rpd: 1500, tpm: 1_000_000 } },
+  store: kvStore(myMongoKv),   // shared across PM2 workers
+});
+
+const picked = await pool.pick("gemini", "gemini-2.0-flash", estTokens);
+if (!picked) throw new Error("all keys cooling down / quota spent");
+try {
+  const res = await callGemini(picked.secret, prompt);
+  await pool.report(picked.id, { ok: true, tokens: res.usage.total, model: "gemini-2.0-flash" });
+} catch (e) {
+  await pool.report(picked.id, { ok: false, status: e.status, headers: e.headers });
+}
+```
+
+- **Windowed accounting** — RPM/RPD/TPM/TPD roll automatically; `pick(provider, model, estTokens)` only returns a key that can afford the call.
+- **Per-model buckets** — `modelLimits["groq:llama-3.3-70b"]` are tracked separately, because that's how the provider counts.
+- **429 aware** — cools a key down for `retry-after` (seconds or an HTTP date), or a default window; recovers automatically.
+- **Invalid quarantine** — a `401/403` sidelines a key until you `reinstate(id, newSecret)`.
+- **Priority + round-robin** — prefer some keys, otherwise spread load least-recently-used first, deterministically.
+- **Shared state** — pass a `KeypoolStore` (Mongo/Redis/KV) so multiple processes don't each burn the same quota; `kvStore(kv)` wraps any `{get,set}`.
+
+Secrets live only in memory on the `KeySpec`; the persisted state is counters and health, never the key. Exports `createKeypool`, `kvStore`, and the state types.
+
+## Licence
+[Lacspace Free Licence v1.0](https://developer.lacspace.com/licenses/lacspace-free-1.0) — free for personal and commercial use.

package/dist/index.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+// src/index.ts
+var MIN = 6e4;
+var DAY = 864e5;
+function emptyBucket(now) {
+  return { minStart: now, minReq: 0, minTok: 0, dayStart: now, dayReq: 0, dayTok: 0 };
+}
+function rollBucket(b, now) {
+  if (now - b.minStart >= MIN) {
+    b.minStart = now;
+    b.minReq = 0;
+    b.minTok = 0;
+  }
+  if (now - b.dayStart >= DAY) {
+    b.dayStart = now;
+    b.dayReq = 0;
+    b.dayTok = 0;
+  }
+}
+function headerGet(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === "function") return headers.get(name);
+  const h = headers;
+  const found = h[name] ?? h[name.toLowerCase()] ?? h[name.toUpperCase()];
+  return found === void 0 || found === null ? null : String(found);
+}
+function createKeypool(options) {
+  const now = options.now ?? (() => Date.now());
+  const cooldownMs = options.defaultCooldownMs ?? MIN;
+  const store = options.store;
+  const specs = /* @__PURE__ */ new Map();
+  for (const k of options.keys) specs.set(k.id, k);
+  let state = {};
+  let loaded = false;
+  const ensureLoaded = async () => {
+    if (loaded) return;
+    const fromStore = store ? await store.load() : null;
+    for (const spec of options.keys) {
+      state[spec.id] = fromStore?.[spec.id] ?? {
+        id: spec.id,
+        provider: spec.provider,
+        cooldownUntil: 0,
+        invalid: false,
+        buckets: {},
+        lastUsed: 0
+      };
+    }
+    loaded = true;
+  };
+  const persist = async () => {
+    if (store) await store.save(state);
+  };
+  const limitsFor = (spec, model) => ({
+    ...options.providerLimits?.[spec.provider] ?? {},
+    ...options.modelLimits?.[`${spec.provider}:${model}`] ?? {},
+    ...spec.limits ?? {}
+  });
+  const bucketOf = (ks, model, t) => {
+    let b = ks.buckets[model];
+    if (!b) {
+      b = emptyBucket(t);
+      ks.buckets[model] = b;
+    }
+    rollBucket(b, t);
+    return b;
+  };
+  const canAfford = (spec, ks, model, estTokens, t) => {
+    if (ks.invalid) return false;
+    if (ks.cooldownUntil > t) return false;
+    const lim = limitsFor(spec, model);
+    const b = bucketOf(ks, model, t);
+    if (lim.rpm !== void 0 && b.minReq + 1 > lim.rpm) return false;
+    if (lim.rpd !== void 0 && b.dayReq + 1 > lim.rpd) return false;
+    if (lim.tpm !== void 0 && b.minTok + estTokens > lim.tpm) return false;
+    if (lim.tpd !== void 0 && b.dayTok + estTokens > lim.tpd) return false;
+    return true;
+  };
+  const candidates = (provider, model, estTokens, t) => {
+    const out = [];
+    for (const spec of options.keys) {
+      if (spec.provider !== provider) continue;
+      const ks = state[spec.id];
+      if (canAfford(spec, ks, model, estTokens, t)) out.push({ spec, ks });
+    }
+    out.sort(
+      (a, b) => (b.spec.priority ?? 0) - (a.spec.priority ?? 0) || a.ks.lastUsed - b.ks.lastUsed || a.spec.id.localeCompare(b.spec.id)
+    );
+    return out;
+  };
+  return {
+    async pick(provider, model = "", estTokens = 0) {
+      await ensureLoaded();
+      const t = now();
+      const cand = candidates(provider, model, estTokens, t)[0];
+      if (!cand) return null;
+      const b = bucketOf(cand.ks, model, t);
+      b.minReq += 1;
+      b.dayReq += 1;
+      b.minTok += estTokens;
+      b.dayTok += estTokens;
+      cand.ks.lastUsed = t;
+      await persist();
+      return { id: cand.spec.id, secret: cand.spec.secret, provider, model };
+    },
+    async report(id, result) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      const t = now();
+      const model = result.model ?? Object.keys(ks.buckets)[0] ?? "";
+      const b = bucketOf(ks, model, t);
+      if (result.tokens !== void 0) {
+        b.minTok += result.tokens;
+        b.dayTok += result.tokens;
+      }
+      const retryAfter = headerGet(result.headers, "retry-after");
+      const status = result.status ?? (result.ok ? 200 : 0);
+      if (status === 401 || status === 403) {
+        ks.invalid = true;
+      } else if (status === 429) {
+        let waitMs = cooldownMs;
+        if (retryAfter) {
+          const n = Number(retryAfter);
+          waitMs = Number.isFinite(n) ? n * 1e3 : Math.max(0, new Date(retryAfter).getTime() - t) || cooldownMs;
+        }
+        ks.cooldownUntil = t + waitMs;
+      } else if (result.ok) {
+        if (ks.cooldownUntil <= t) ks.cooldownUntil = 0;
+      }
+      await persist();
+    },
+    async note(id, model, tokens) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      const b = bucketOf(ks, model, now());
+      b.minTok += tokens;
+      b.dayTok += tokens;
+      await persist();
+    },
+    async reinstate(id, secret) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      ks.invalid = false;
+      ks.cooldownUntil = 0;
+      if (secret) {
+        const spec = specs.get(id);
+        if (spec) spec.secret = secret;
+      }
+      await persist();
+    },
+    async states() {
+      await ensureLoaded();
+      return JSON.parse(JSON.stringify(state));
+    },
+    async available(provider, model = "", estTokens = 0) {
+      await ensureLoaded();
+      return candidates(provider, model, estTokens, now()).length;
+    }
+  };
+}
+function kvStore(kv, key = "keypool:state") {
+  return {
+    async load() {
+      const raw = await kv.get(key);
+      return raw ? JSON.parse(raw) : null;
+    },
+    async save(states) {
+      await kv.set(key, JSON.stringify(states));
+    }
+  };
+}
+
+exports.createKeypool = createKeypool;
+exports.kvStore = kvStore;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { BucketState, KeypoolStore, KeySpec, KeyState, Limits, ReportInput } from \"./types.js\";\n\nexport type { BucketState, KeypoolStore, KeySpec, KeyState, Limits, ReportInput } from \"./types.js\";\n\nexport interface KeypoolOptions {\n  keys: KeySpec[];\n  /** Default limits per provider, applied to every key unless the key overrides. */\n  providerLimits?: Record<string, Limits>;\n  /** Per-model limit overrides, e.g. { \"groq:llama-3.3-70b\": { tpd: 500000 } }. Key format `provider:model`. */\n  modelLimits?: Record<string, Limits>;\n  /** Cooldown (ms) applied on a 429 when no retry-after header is present. Default 60000. */\n  defaultCooldownMs?: number;\n  /** Persistence adapter for cross-process sharing. Default: in-memory only. */\n  store?: KeypoolStore;\n  /** Injectable clock (ms). */\n  now?: () => number;\n}\n\nexport interface Pick {\n  id: string;\n  secret: string;\n  provider: string;\n  model: string;\n}\n\nexport interface Keypool {\n  /**\n   * Pick the best healthy key for (provider, model) that can afford ~estTokens,\n   * or null if every key is cooling down / quota-exhausted / invalid.\n   */\n  pick(provider: string, model?: string, estTokens?: number): Promise<Pick | null>;\n  /** Report the outcome of a call so counters, cooldowns and quarantine update. */\n  report(id: string, result: ReportInput): Promise<void>;\n  /** Reserve usage yourself (when you don't call report), e.g. optimistic accounting. */\n  note(id: string, model: string, tokens: number): Promise<void>;\n  /** Clear a key's invalid quarantine (after you rotated the secret). */\n  reinstate(id: string, secret?: string): Promise<void>;\n  /** Snapshot of every key's state. */\n  states(): Promise<Record<string, KeyState>>;\n  /** How many keys are pickable right now for a provider/model. */\n  available(provider: string, model?: string, estTokens?: number): Promise<number>;\n}\n\nconst MIN = 60_000;\nconst DAY = 86_400_000;\n\nfunction emptyBucket(now: number): BucketState {\n  return { minStart: now, minReq: 0, minTok: 0, dayStart: now, dayReq: 0, dayTok: 0 };\n}\n\nfunction rollBucket(b: BucketState, now: number): void {\n  if (now - b.minStart >= MIN) {\n    b.minStart = now;\n    b.minReq = 0;\n    b.minTok = 0;\n  }\n  if (now - b.dayStart >= DAY) {\n    b.dayStart = now;\n    b.dayReq = 0;\n    b.dayTok = 0;\n  }\n}\n\nfunction headerGet(headers: ReportInput[\"headers\"], name: string): string | null {\n  if (!headers) return null;\n  if (typeof (headers as { get?: unknown }).get === \"function\") return (headers as { get(n: string): string | null }).get(name);\n  const h = headers as Record<string, string | number | null | undefined>;\n  const found = h[name] ?? h[name.toLowerCase()] ?? h[name.toUpperCase()];\n  return found === undefined || found === null ? null : String(found);\n}\n\nexport function createKeypool(options: KeypoolOptions): Keypool {\n  const now = options.now ?? (() => Date.now());\n  const cooldownMs = options.defaultCooldownMs ?? MIN;\n  const store = options.store;\n  const specs = new Map<string, KeySpec>();\n  for (const k of options.keys) specs.set(k.id, k);\n\n  // Live state, hydrated from the store if present.\n  let state: Record<string, KeyState> = {};\n  let loaded = false;\n\n  const ensureLoaded = async () => {\n    if (loaded) return;\n    const fromStore = store ? await store.load() : null;\n    for (const spec of options.keys) {\n      state[spec.id] = fromStore?.[spec.id] ?? {\n        id: spec.id,\n        provider: spec.provider,\n        cooldownUntil: 0,\n        invalid: false,\n        buckets: {},\n        lastUsed: 0,\n      };\n    }\n    loaded = true;\n  };\n\n  const persist = async () => {\n    if (store) await store.save(state);\n  };\n\n  const limitsFor = (spec: KeySpec, model: string): Limits => ({\n    ...(options.providerLimits?.[spec.provider] ?? {}),\n    ...(options.modelLimits?.[`${spec.provider}:${model}`] ?? {}),\n    ...(spec.limits ?? {}),\n  });\n\n  const bucketOf = (ks: KeyState, model: string, t: number): BucketState => {\n    let b = ks.buckets[model];\n    if (!b) {\n      b = emptyBucket(t);\n      ks.buckets[model] = b;\n    }\n    rollBucket(b, t);\n    return b;\n  };\n\n  const canAfford = (spec: KeySpec, ks: KeyState, model: string, estTokens: number, t: number): boolean => {\n    if (ks.invalid) return false;\n    if (ks.cooldownUntil > t) return false;\n    const lim = limitsFor(spec, model);\n    const b = bucketOf(ks, model, t);\n    if (lim.rpm !== undefined && b.minReq + 1 > lim.rpm) return false;\n    if (lim.rpd !== undefined && b.dayReq + 1 > lim.rpd) return false;\n    if (lim.tpm !== undefined && b.minTok + estTokens > lim.tpm) return false;\n    if (lim.tpd !== undefined && b.dayTok + estTokens > lim.tpd) return false;\n    return true;\n  };\n\n  const candidates = (provider: string, model: string, estTokens: number, t: number): { spec: KeySpec; ks: KeyState }[] => {\n    const out: { spec: KeySpec; ks: KeyState }[] = [];\n    for (const spec of options.keys) {\n      if (spec.provider !== provider) continue;\n      const ks = state[spec.id]!;\n      if (canAfford(spec, ks, model, estTokens, t)) out.push({ spec, ks });\n    }\n    // Highest priority, then least-recently-used (round-robin), then id for stability.\n    out.sort(\n      (a, b) =>\n        (b.spec.priority ?? 0) - (a.spec.priority ?? 0) ||\n        a.ks.lastUsed - b.ks.lastUsed ||\n        a.spec.id.localeCompare(b.spec.id),\n    );\n    return out;\n  };\n\n  return {\n    async pick(provider, model = \"\", estTokens = 0) {\n      await ensureLoaded();\n      const t = now();\n      const cand = candidates(provider, model, estTokens, t)[0];\n      if (!cand) return null;\n      // Optimistically reserve one request + estimated tokens so concurrent picks spread out.\n      const b = bucketOf(cand.ks, model, t);\n      b.minReq += 1;\n      b.dayReq += 1;\n      b.minTok += estTokens;\n      b.dayTok += estTokens;\n      cand.ks.lastUsed = t;\n      await persist();\n      return { id: cand.spec.id, secret: cand.spec.secret, provider, model };\n    },\n\n    async report(id, result) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      const t = now();\n      const model = result.model ?? Object.keys(ks.buckets)[0] ?? \"\";\n      const b = bucketOf(ks, model, t);\n\n      // Reconcile token count if the caller reserved an estimate at pick().\n      if (result.tokens !== undefined) {\n        b.minTok += result.tokens; // add ACTUAL on top of the estimate reserved at pick; callers can pass a delta if they prefer\n        b.dayTok += result.tokens;\n      }\n\n      // Absorb provider-reported remaining/limits when present.\n      const retryAfter = headerGet(result.headers, \"retry-after\");\n      const status = result.status ?? (result.ok ? 200 : 0);\n\n      if (status === 401 || status === 403) {\n        ks.invalid = true;\n      } else if (status === 429) {\n        let waitMs = cooldownMs;\n        if (retryAfter) {\n          const n = Number(retryAfter);\n          waitMs = Number.isFinite(n) ? n * 1000 : Math.max(0, new Date(retryAfter).getTime() - t) || cooldownMs;\n        }\n        ks.cooldownUntil = t + waitMs;\n      } else if (result.ok) {\n        // clear any stale cooldown on a clean success\n        if (ks.cooldownUntil <= t) ks.cooldownUntil = 0;\n      }\n      await persist();\n    },\n\n    async note(id, model, tokens) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      const b = bucketOf(ks, model, now());\n      b.minTok += tokens;\n      b.dayTok += tokens;\n      await persist();\n    },\n\n    async reinstate(id, secret) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      ks.invalid = false;\n      ks.cooldownUntil = 0;\n      if (secret) {\n        const spec = specs.get(id);\n        if (spec) spec.secret = secret;\n      }\n      await persist();\n    },\n\n    async states() {\n      await ensureLoaded();\n      return JSON.parse(JSON.stringify(state));\n    },\n\n    async available(provider, model = \"\", estTokens = 0) {\n      await ensureLoaded();\n      return candidates(provider, model, estTokens, now()).length;\n    },\n  };\n}\n\n/** A KeypoolStore backed by any {get,set} KV (JSON string values). Handy over Mongo/Redis. */\nexport function kvStore(kv: { get(k: string): Promise<string | null> | string | null; set(k: string, v: string): Promise<void> | void }, key = \"keypool:state\"): KeypoolStore {\n  return {\n    async load() {\n      const raw = await kv.get(key);\n      return raw ? (JSON.parse(raw) as Record<string, KeyState>) : null;\n    },\n    async save(states) {\n      await kv.set(key, JSON.stringify(states));\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,108 @@
+/** Per-window limits for a provider or a specific model. Any field omitted = unlimited. */
+interface Limits {
+    /** Requests per minute. */
+    rpm?: number;
+    /** Requests per day. */
+    rpd?: number;
+    /** Tokens per minute. */
+    tpm?: number;
+    /** Tokens per day. */
+    tpd?: number;
+}
+interface KeySpec {
+    /** Unique id for this key (never the secret itself — store a label or hash). */
+    id: string;
+    provider: string;
+    /** The secret. Held in memory only; never persisted by the built-in memory adapter's snapshot of counters. */
+    secret: string;
+    /** Optional per-key limit overrides (else provider/model defaults apply). */
+    limits?: Limits;
+    /** Priority — higher is preferred among equally-healthy keys. Default 0. */
+    priority?: number;
+}
+/** Rolling counters + health for one key, per model bucket. */
+interface BucketState {
+    /** minute window start (epoch ms) and counts */
+    minStart: number;
+    minReq: number;
+    minTok: number;
+    /** day window start (epoch ms) and counts */
+    dayStart: number;
+    dayReq: number;
+    dayTok: number;
+}
+interface KeyState {
+    id: string;
+    provider: string;
+    /** epoch ms until which the key is cooling down (0 = healthy). */
+    cooldownUntil: number;
+    /** true if quarantined (invalid key) — never picked until cleared. */
+    invalid: boolean;
+    /** per-model buckets, keyed by model id ("" = provider-wide bucket). */
+    buckets: Record<string, BucketState>;
+    /** round-robin tiebreaker cursor. */
+    lastUsed: number;
+}
+/** A persistence adapter so multiple processes share pool state. All async-friendly. */
+interface KeypoolStore {
+    load(): Record<string, KeyState> | null | Promise<Record<string, KeyState> | null>;
+    save(states: Record<string, KeyState>): void | Promise<void>;
+}
+interface ReportInput {
+    ok: boolean;
+    /** HTTP status of the response, if any. */
+    status?: number;
+    /** Tokens actually consumed by the call (input+output). */
+    tokens?: number;
+    /** Raw response headers (or a subset). `retry-after` and rate-limit remaining headers are read when present. */
+    headers?: Record<string, string | number | null | undefined> | {
+        get(name: string): string | null;
+    };
+    /** Model used (defaults to the model passed to pick). */
+    model?: string;
+}
+
+interface KeypoolOptions {
+    keys: KeySpec[];
+    /** Default limits per provider, applied to every key unless the key overrides. */
+    providerLimits?: Record<string, Limits>;
+    /** Per-model limit overrides, e.g. { "groq:llama-3.3-70b": { tpd: 500000 } }. Key format `provider:model`. */
+    modelLimits?: Record<string, Limits>;
+    /** Cooldown (ms) applied on a 429 when no retry-after header is present. Default 60000. */
+    defaultCooldownMs?: number;
+    /** Persistence adapter for cross-process sharing. Default: in-memory only. */
+    store?: KeypoolStore;
+    /** Injectable clock (ms). */
+    now?: () => number;
+}
+interface Pick {
+    id: string;
+    secret: string;
+    provider: string;
+    model: string;
+}
+interface Keypool {
+    /**
+     * Pick the best healthy key for (provider, model) that can afford ~estTokens,
+     * or null if every key is cooling down / quota-exhausted / invalid.
+     */
+    pick(provider: string, model?: string, estTokens?: number): Promise<Pick | null>;
+    /** Report the outcome of a call so counters, cooldowns and quarantine update. */
+    report(id: string, result: ReportInput): Promise<void>;
+    /** Reserve usage yourself (when you don't call report), e.g. optimistic accounting. */
+    note(id: string, model: string, tokens: number): Promise<void>;
+    /** Clear a key's invalid quarantine (after you rotated the secret). */
+    reinstate(id: string, secret?: string): Promise<void>;
+    /** Snapshot of every key's state. */
+    states(): Promise<Record<string, KeyState>>;
+    /** How many keys are pickable right now for a provider/model. */
+    available(provider: string, model?: string, estTokens?: number): Promise<number>;
+}
+declare function createKeypool(options: KeypoolOptions): Keypool;
+/** A KeypoolStore backed by any {get,set} KV (JSON string values). Handy over Mongo/Redis. */
+declare function kvStore(kv: {
+    get(k: string): Promise<string | null> | string | null;
+    set(k: string, v: string): Promise<void> | void;
+}, key?: string): KeypoolStore;
+
+export { type BucketState, type KeySpec, type KeyState, type Keypool, type KeypoolOptions, type KeypoolStore, type Limits, type Pick, type ReportInput, createKeypool, kvStore };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/** Per-window limits for a provider or a specific model. Any field omitted = unlimited. */
+interface Limits {
+    /** Requests per minute. */
+    rpm?: number;
+    /** Requests per day. */
+    rpd?: number;
+    /** Tokens per minute. */
+    tpm?: number;
+    /** Tokens per day. */
+    tpd?: number;
+}
+interface KeySpec {
+    /** Unique id for this key (never the secret itself — store a label or hash). */
+    id: string;
+    provider: string;
+    /** The secret. Held in memory only; never persisted by the built-in memory adapter's snapshot of counters. */
+    secret: string;
+    /** Optional per-key limit overrides (else provider/model defaults apply). */
+    limits?: Limits;
+    /** Priority — higher is preferred among equally-healthy keys. Default 0. */
+    priority?: number;
+}
+/** Rolling counters + health for one key, per model bucket. */
+interface BucketState {
+    /** minute window start (epoch ms) and counts */
+    minStart: number;
+    minReq: number;
+    minTok: number;
+    /** day window start (epoch ms) and counts */
+    dayStart: number;
+    dayReq: number;
+    dayTok: number;
+}
+interface KeyState {
+    id: string;
+    provider: string;
+    /** epoch ms until which the key is cooling down (0 = healthy). */
+    cooldownUntil: number;
+    /** true if quarantined (invalid key) — never picked until cleared. */
+    invalid: boolean;
+    /** per-model buckets, keyed by model id ("" = provider-wide bucket). */
+    buckets: Record<string, BucketState>;
+    /** round-robin tiebreaker cursor. */
+    lastUsed: number;
+}
+/** A persistence adapter so multiple processes share pool state. All async-friendly. */
+interface KeypoolStore {
+    load(): Record<string, KeyState> | null | Promise<Record<string, KeyState> | null>;
+    save(states: Record<string, KeyState>): void | Promise<void>;
+}
+interface ReportInput {
+    ok: boolean;
+    /** HTTP status of the response, if any. */
+    status?: number;
+    /** Tokens actually consumed by the call (input+output). */
+    tokens?: number;
+    /** Raw response headers (or a subset). `retry-after` and rate-limit remaining headers are read when present. */
+    headers?: Record<string, string | number | null | undefined> | {
+        get(name: string): string | null;
+    };
+    /** Model used (defaults to the model passed to pick). */
+    model?: string;
+}
+
+interface KeypoolOptions {
+    keys: KeySpec[];
+    /** Default limits per provider, applied to every key unless the key overrides. */
+    providerLimits?: Record<string, Limits>;
+    /** Per-model limit overrides, e.g. { "groq:llama-3.3-70b": { tpd: 500000 } }. Key format `provider:model`. */
+    modelLimits?: Record<string, Limits>;
+    /** Cooldown (ms) applied on a 429 when no retry-after header is present. Default 60000. */
+    defaultCooldownMs?: number;
+    /** Persistence adapter for cross-process sharing. Default: in-memory only. */
+    store?: KeypoolStore;
+    /** Injectable clock (ms). */
+    now?: () => number;
+}
+interface Pick {
+    id: string;
+    secret: string;
+    provider: string;
+    model: string;
+}
+interface Keypool {
+    /**
+     * Pick the best healthy key for (provider, model) that can afford ~estTokens,
+     * or null if every key is cooling down / quota-exhausted / invalid.
+     */
+    pick(provider: string, model?: string, estTokens?: number): Promise<Pick | null>;
+    /** Report the outcome of a call so counters, cooldowns and quarantine update. */
+    report(id: string, result: ReportInput): Promise<void>;
+    /** Reserve usage yourself (when you don't call report), e.g. optimistic accounting. */
+    note(id: string, model: string, tokens: number): Promise<void>;
+    /** Clear a key's invalid quarantine (after you rotated the secret). */
+    reinstate(id: string, secret?: string): Promise<void>;
+    /** Snapshot of every key's state. */
+    states(): Promise<Record<string, KeyState>>;
+    /** How many keys are pickable right now for a provider/model. */
+    available(provider: string, model?: string, estTokens?: number): Promise<number>;
+}
+declare function createKeypool(options: KeypoolOptions): Keypool;
+/** A KeypoolStore backed by any {get,set} KV (JSON string values). Handy over Mongo/Redis. */
+declare function kvStore(kv: {
+    get(k: string): Promise<string | null> | string | null;
+    set(k: string, v: string): Promise<void> | void;
+}, key?: string): KeypoolStore;
+
+export { type BucketState, type KeySpec, type KeyState, type Keypool, type KeypoolOptions, type KeypoolStore, type Limits, type Pick, type ReportInput, createKeypool, kvStore };

package/dist/index.js

@@ -0,0 +1,176 @@
+// src/index.ts
+var MIN = 6e4;
+var DAY = 864e5;
+function emptyBucket(now) {
+  return { minStart: now, minReq: 0, minTok: 0, dayStart: now, dayReq: 0, dayTok: 0 };
+}
+function rollBucket(b, now) {
+  if (now - b.minStart >= MIN) {
+    b.minStart = now;
+    b.minReq = 0;
+    b.minTok = 0;
+  }
+  if (now - b.dayStart >= DAY) {
+    b.dayStart = now;
+    b.dayReq = 0;
+    b.dayTok = 0;
+  }
+}
+function headerGet(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === "function") return headers.get(name);
+  const h = headers;
+  const found = h[name] ?? h[name.toLowerCase()] ?? h[name.toUpperCase()];
+  return found === void 0 || found === null ? null : String(found);
+}
+function createKeypool(options) {
+  const now = options.now ?? (() => Date.now());
+  const cooldownMs = options.defaultCooldownMs ?? MIN;
+  const store = options.store;
+  const specs = /* @__PURE__ */ new Map();
+  for (const k of options.keys) specs.set(k.id, k);
+  let state = {};
+  let loaded = false;
+  const ensureLoaded = async () => {
+    if (loaded) return;
+    const fromStore = store ? await store.load() : null;
+    for (const spec of options.keys) {
+      state[spec.id] = fromStore?.[spec.id] ?? {
+        id: spec.id,
+        provider: spec.provider,
+        cooldownUntil: 0,
+        invalid: false,
+        buckets: {},
+        lastUsed: 0
+      };
+    }
+    loaded = true;
+  };
+  const persist = async () => {
+    if (store) await store.save(state);
+  };
+  const limitsFor = (spec, model) => ({
+    ...options.providerLimits?.[spec.provider] ?? {},
+    ...options.modelLimits?.[`${spec.provider}:${model}`] ?? {},
+    ...spec.limits ?? {}
+  });
+  const bucketOf = (ks, model, t) => {
+    let b = ks.buckets[model];
+    if (!b) {
+      b = emptyBucket(t);
+      ks.buckets[model] = b;
+    }
+    rollBucket(b, t);
+    return b;
+  };
+  const canAfford = (spec, ks, model, estTokens, t) => {
+    if (ks.invalid) return false;
+    if (ks.cooldownUntil > t) return false;
+    const lim = limitsFor(spec, model);
+    const b = bucketOf(ks, model, t);
+    if (lim.rpm !== void 0 && b.minReq + 1 > lim.rpm) return false;
+    if (lim.rpd !== void 0 && b.dayReq + 1 > lim.rpd) return false;
+    if (lim.tpm !== void 0 && b.minTok + estTokens > lim.tpm) return false;
+    if (lim.tpd !== void 0 && b.dayTok + estTokens > lim.tpd) return false;
+    return true;
+  };
+  const candidates = (provider, model, estTokens, t) => {
+    const out = [];
+    for (const spec of options.keys) {
+      if (spec.provider !== provider) continue;
+      const ks = state[spec.id];
+      if (canAfford(spec, ks, model, estTokens, t)) out.push({ spec, ks });
+    }
+    out.sort(
+      (a, b) => (b.spec.priority ?? 0) - (a.spec.priority ?? 0) || a.ks.lastUsed - b.ks.lastUsed || a.spec.id.localeCompare(b.spec.id)
+    );
+    return out;
+  };
+  return {
+    async pick(provider, model = "", estTokens = 0) {
+      await ensureLoaded();
+      const t = now();
+      const cand = candidates(provider, model, estTokens, t)[0];
+      if (!cand) return null;
+      const b = bucketOf(cand.ks, model, t);
+      b.minReq += 1;
+      b.dayReq += 1;
+      b.minTok += estTokens;
+      b.dayTok += estTokens;
+      cand.ks.lastUsed = t;
+      await persist();
+      return { id: cand.spec.id, secret: cand.spec.secret, provider, model };
+    },
+    async report(id, result) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      const t = now();
+      const model = result.model ?? Object.keys(ks.buckets)[0] ?? "";
+      const b = bucketOf(ks, model, t);
+      if (result.tokens !== void 0) {
+        b.minTok += result.tokens;
+        b.dayTok += result.tokens;
+      }
+      const retryAfter = headerGet(result.headers, "retry-after");
+      const status = result.status ?? (result.ok ? 200 : 0);
+      if (status === 401 || status === 403) {
+        ks.invalid = true;
+      } else if (status === 429) {
+        let waitMs = cooldownMs;
+        if (retryAfter) {
+          const n = Number(retryAfter);
+          waitMs = Number.isFinite(n) ? n * 1e3 : Math.max(0, new Date(retryAfter).getTime() - t) || cooldownMs;
+        }
+        ks.cooldownUntil = t + waitMs;
+      } else if (result.ok) {
+        if (ks.cooldownUntil <= t) ks.cooldownUntil = 0;
+      }
+      await persist();
+    },
+    async note(id, model, tokens) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      const b = bucketOf(ks, model, now());
+      b.minTok += tokens;
+      b.dayTok += tokens;
+      await persist();
+    },
+    async reinstate(id, secret) {
+      await ensureLoaded();
+      const ks = state[id];
+      if (!ks) return;
+      ks.invalid = false;
+      ks.cooldownUntil = 0;
+      if (secret) {
+        const spec = specs.get(id);
+        if (spec) spec.secret = secret;
+      }
+      await persist();
+    },
+    async states() {
+      await ensureLoaded();
+      return JSON.parse(JSON.stringify(state));
+    },
+    async available(provider, model = "", estTokens = 0) {
+      await ensureLoaded();
+      return candidates(provider, model, estTokens, now()).length;
+    }
+  };
+}
+function kvStore(kv, key = "keypool:state") {
+  return {
+    async load() {
+      const raw = await kv.get(key);
+      return raw ? JSON.parse(raw) : null;
+    },
+    async save(states) {
+      await kv.set(key, JSON.stringify(states));
+    }
+  };
+}
+
+export { createKeypool, kvStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA2CA,IAAM,GAAA,GAAM,GAAA;AACZ,IAAM,GAAA,GAAM,KAAA;AAEZ,SAAS,YAAY,GAAA,EAA0B;AAC7C,EAAA,OAAO,EAAE,QAAA,EAAU,GAAA,EAAK,MAAA,EAAQ,CAAA,EAAG,MAAA,EAAQ,CAAA,EAAG,QAAA,EAAU,GAAA,EAAK,MAAA,EAAQ,CAAA,EAAG,MAAA,EAAQ,CAAA,EAAE;AACpF;AAEA,SAAS,UAAA,CAAW,GAAgB,GAAA,EAAmB;AACrD,EAAA,IAAI,GAAA,GAAM,CAAA,CAAE,QAAA,IAAY,GAAA,EAAK;AAC3B,IAAA,CAAA,CAAE,QAAA,GAAW,GAAA;AACb,IAAA,CAAA,CAAE,MAAA,GAAS,CAAA;AACX,IAAA,CAAA,CAAE,MAAA,GAAS,CAAA;AAAA,EACb;AACA,EAAA,IAAI,GAAA,GAAM,CAAA,CAAE,QAAA,IAAY,GAAA,EAAK;AAC3B,IAAA,CAAA,CAAE,QAAA,GAAW,GAAA;AACb,IAAA,CAAA,CAAE,MAAA,GAAS,CAAA;AACX,IAAA,CAAA,CAAE,MAAA,GAAS,CAAA;AAAA,EACb;AACF;AAEA,SAAS,SAAA,CAAU,SAAiC,IAAA,EAA6B;AAC/E,EAAA,IAAI,CAAC,SAAS,OAAO,IAAA;AACrB,EAAA,IAAI,OAAQ,OAAA,CAA8B,GAAA,KAAQ,YAAY,OAAQ,OAAA,CAA8C,IAAI,IAAI,CAAA;AAC5H,EAAA,MAAM,CAAA,GAAI,OAAA;AACV,EAAA,MAAM,KAAA,GAAQ,CAAA,CAAE,IAAI,CAAA,IAAK,CAAA,CAAE,IAAA,CAAK,WAAA,EAAa,CAAA,IAAK,CAAA,CAAE,IAAA,CAAK,WAAA,EAAa,CAAA;AACtE,EAAA,OAAO,UAAU,MAAA,IAAa,KAAA,KAAU,IAAA,GAAO,IAAA,GAAO,OAAO,KAAK,CAAA;AACpE;AAEO,SAAS,cAAc,OAAA,EAAkC;AAC9D,EAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,GAAA,KAAQ,MAAM,KAAK,GAAA,EAAI,CAAA;AAC3C,EAAA,MAAM,UAAA,GAAa,QAAQ,iBAAA,IAAqB,GAAA;AAChD,EAAA,MAAM,QAAQ,OAAA,CAAQ,KAAA;AACtB,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAqB;AACvC,EAAA,KAAA,MAAW,KAAK,OAAA,CAAQ,IAAA,QAAY,GAAA,CAAI,CAAA,CAAE,IAAI,CAAC,CAAA;AAG/C,EAAA,IAAI,QAAkC,EAAC;AACvC,EAAA,IAAI,MAAA,GAAS,KAAA;AAEb,EAAA,MAAM,eAAe,YAAY;AAC/B,IAAA,IAAI,MAAA,EAAQ;AACZ,IAAA,MAAM,SAAA,GAAY,KAAA,GAAQ,MAAM,KAAA,CAAM,MAAK,GAAI,IAAA;AAC/C,IAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,IAAA,EAAM;AAC/B,MAAA,KAAA,CAAM,KAAK,EAAE,CAAA,GAAI,SAAA,GAAY,IAAA,CAAK,EAAE,CAAA,IAAK;AAAA,QACvC,IAAI,IAAA,CAAK,EAAA;AAAA,QACT,UAAU,IAAA,CAAK,QAAA;AAAA,QACf,aAAA,EAAe,CAAA;AAAA,QACf,OAAA,EAAS,KAAA;AAAA,QACT,SAAS,EAAC;AAAA,QACV,QAAA,EAAU;AAAA,OACZ;AAAA,IACF;AACA,IAAA,MAAA,GAAS,IAAA;AAAA,EACX,CAAA;AAEA,EAAA,MAAM,UAAU,YAAY;AAC1B,IAAA,IAAI,KAAA,EAAO,MAAM,KAAA,CAAM,IAAA,CAAK,KAAK,CAAA;AAAA,EACnC,CAAA;AAEA,EAAA,MAAM,SAAA,GAAY,CAAC,IAAA,EAAe,KAAA,MAA2B;AAAA,IAC3D,GAAI,OAAA,CAAQ,cAAA,GAAiB,IAAA,CAAK,QAAQ,KAAK,EAAC;AAAA,IAChD,GAAI,OAAA,CAAQ,WAAA,GAAc,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,CAAA,EAAI,KAAK,CAAA,CAAE,CAAA,IAAK,EAAC;AAAA,IAC3D,GAAI,IAAA,CAAK,MAAA,IAAU;AAAC,GACtB,CAAA;AAEA,EAAA,MAAM,QAAA,GAAW,CAAC,EAAA,EAAc,KAAA,EAAe,CAAA,KAA2B;AACxE,IAAA,IAAI,CAAA,GAAI,EAAA,CAAG,OAAA,CAAQ,KAAK,CAAA;AACxB,IAAA,IAAI,CAAC,CAAA,EAAG;AACN,MAAA,CAAA,GAAI,YAAY,CAAC,CAAA;AACjB,MAAA,EAAA,CAAG,OAAA,CAAQ,KAAK,CAAA,GAAI,CAAA;AAAA,IACtB;AACA,IAAA,UAAA,CAAW,GAAG,CAAC,CAAA;AACf,IAAA,OAAO,CAAA;AAAA,EACT,CAAA;AAEA,EAAA,MAAM,YAAY,CAAC,IAAA,EAAe,EAAA,EAAc,KAAA,EAAe,WAAmB,CAAA,KAAuB;AACvG,IAAA,IAAI,EAAA,CAAG,SAAS,OAAO,KAAA;AACvB,IAAA,IAAI,EAAA,CAAG,aAAA,GAAgB,CAAA,EAAG,OAAO,KAAA;AACjC,IAAA,MAAM,GAAA,GAAM,SAAA,CAAU,IAAA,EAAM,KAAK,CAAA;AACjC,IAAA,MAAM,CAAA,GAAI,QAAA,CAAS,EAAA,EAAI,KAAA,EAAO,CAAC,CAAA;AAC/B,IAAA,IAAI,GAAA,CAAI,QAAQ,MAAA,IAAa,CAAA,CAAE,SAAS,CAAA,GAAI,GAAA,CAAI,KAAK,OAAO,KAAA;AAC5D,IAAA,IAAI,GAAA,CAAI,QAAQ,MAAA,IAAa,CAAA,CAAE,SAAS,CAAA,GAAI,GAAA,CAAI,KAAK,OAAO,KAAA;AAC5D,IAAA,IAAI,GAAA,CAAI,QAAQ,MAAA,IAAa,CAAA,CAAE,SAAS,SAAA,GAAY,GAAA,CAAI,KAAK,OAAO,KAAA;AACpE,IAAA,IAAI,GAAA,CAAI,QAAQ,MAAA,IAAa,CAAA,CAAE,SAAS,SAAA,GAAY,GAAA,CAAI,KAAK,OAAO,KAAA;AACpE,IAAA,OAAO,IAAA;AAAA,EACT,CAAA;AAEA,EAAA,MAAM,UAAA,GAAa,CAAC,QAAA,EAAkB,KAAA,EAAe,WAAmB,CAAA,KAAiD;AACvH,IAAA,MAAM,MAAyC,EAAC;AAChD,IAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,IAAA,EAAM;AAC/B,MAAA,IAAI,IAAA,CAAK,aAAa,QAAA,EAAU;AAChC,MAAA,MAAM,EAAA,GAAK,KAAA,CAAM,IAAA,CAAK,EAAE,CAAA;AACxB,MAAA,IAAI,SAAA,CAAU,IAAA,EAAM,EAAA,EAAI,KAAA,EAAO,SAAA,EAAW,CAAC,CAAA,EAAG,GAAA,CAAI,IAAA,CAAK,EAAE,IAAA,EAAM,EAAA,EAAI,CAAA;AAAA,IACrE;AAEA,IAAA,GAAA,CAAI,IAAA;AAAA,MACF,CAAC,GAAG,CAAA,KAAA,CACD,CAAA,CAAE,KAAK,QAAA,IAAY,CAAA,KAAM,CAAA,CAAE,IAAA,CAAK,QAAA,IAAY,CAAA,CAAA,IAC7C,EAAE,EAAA,CAAG,QAAA,GAAW,CAAA,CAAE,EAAA,CAAG,QAAA,IACrB,CAAA,CAAE,KAAK,EAAA,CAAG,aAAA,CAAc,CAAA,CAAE,IAAA,CAAK,EAAE;AAAA,KACrC;AACA,IAAA,OAAO,GAAA;AAAA,EACT,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,CAAK,QAAA,EAAU,KAAA,GAAQ,EAAA,EAAI,YAAY,CAAA,EAAG;AAC9C,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,MAAM,IAAI,GAAA,EAAI;AACd,MAAA,MAAM,OAAO,UAAA,CAAW,QAAA,EAAU,OAAO,SAAA,EAAW,CAAC,EAAE,CAAC,CAAA;AACxD,MAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAElB,MAAA,MAAM,CAAA,GAAI,QAAA,CAAS,IAAA,CAAK,EAAA,EAAI,OAAO,CAAC,CAAA;AACpC,MAAA,CAAA,CAAE,MAAA,IAAU,CAAA;AACZ,MAAA,CAAA,CAAE,MAAA,IAAU,CAAA;AACZ,MAAA,CAAA,CAAE,MAAA,IAAU,SAAA;AACZ,MAAA,CAAA,CAAE,MAAA,IAAU,SAAA;AACZ,MAAA,IAAA,CAAK,GAAG,QAAA,GAAW,CAAA;AACnB,MAAA,MAAM,OAAA,EAAQ;AACd,MAAA,OAAO,EAAE,EAAA,EAAI,IAAA,CAAK,IAAA,CAAK,EAAA,EAAI,QAAQ,IAAA,CAAK,IAAA,CAAK,MAAA,EAAQ,QAAA,EAAU,KAAA,EAAM;AAAA,IACvE,CAAA;AAAA,IAEA,MAAM,MAAA,CAAO,EAAA,EAAI,MAAA,EAAQ;AACvB,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,MAAM,EAAA,GAAK,MAAM,EAAE,CAAA;AACnB,MAAA,IAAI,CAAC,EAAA,EAAI;AACT,MAAA,MAAM,IAAI,GAAA,EAAI;AACd,MAAA,MAAM,KAAA,GAAQ,OAAO,KAAA,IAAS,MAAA,CAAO,KAAK,EAAA,CAAG,OAAO,CAAA,CAAE,CAAC,CAAA,IAAK,EAAA;AAC5D,MAAA,MAAM,CAAA,GAAI,QAAA,CAAS,EAAA,EAAI,KAAA,EAAO,CAAC,CAAA;AAG/B,MAAA,IAAI,MAAA,CAAO,WAAW,MAAA,EAAW;AAC/B,QAAA,CAAA,CAAE,UAAU,MAAA,CAAO,MAAA;AACnB,QAAA,CAAA,CAAE,UAAU,MAAA,CAAO,MAAA;AAAA,MACrB;AAGA,MAAA,MAAM,UAAA,GAAa,SAAA,CAAU,MAAA,CAAO,OAAA,EAAS,aAAa,CAAA;AAC1D,MAAA,MAAM,MAAA,GAAS,MAAA,CAAO,MAAA,KAAW,MAAA,CAAO,KAAK,GAAA,GAAM,CAAA,CAAA;AAEnD,MAAA,IAAI,MAAA,KAAW,GAAA,IAAO,MAAA,KAAW,GAAA,EAAK;AACpC,QAAA,EAAA,CAAG,OAAA,GAAU,IAAA;AAAA,MACf,CAAA,MAAA,IAAW,WAAW,GAAA,EAAK;AACzB,QAAA,IAAI,MAAA,GAAS,UAAA;AACb,QAAA,IAAI,UAAA,EAAY;AACd,UAAA,MAAM,CAAA,GAAI,OAAO,UAAU,CAAA;AAC3B,UAAA,MAAA,GAAS,OAAO,QAAA,CAAS,CAAC,CAAA,GAAI,CAAA,GAAI,MAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,IAAI,KAAK,UAAU,CAAA,CAAE,OAAA,EAAQ,GAAI,CAAC,CAAA,IAAK,UAAA;AAAA,QAC9F;AACA,QAAA,EAAA,CAAG,gBAAgB,CAAA,GAAI,MAAA;AAAA,MACzB,CAAA,MAAA,IAAW,OAAO,EAAA,EAAI;AAEpB,QAAA,IAAI,EAAA,CAAG,aAAA,IAAiB,CAAA,EAAG,EAAA,CAAG,aAAA,GAAgB,CAAA;AAAA,MAChD;AACA,MAAA,MAAM,OAAA,EAAQ;AAAA,IAChB,CAAA;AAAA,IAEA,MAAM,IAAA,CAAK,EAAA,EAAI,KAAA,EAAO,MAAA,EAAQ;AAC5B,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,MAAM,EAAA,GAAK,MAAM,EAAE,CAAA;AACnB,MAAA,IAAI,CAAC,EAAA,EAAI;AACT,MAAA,MAAM,CAAA,GAAI,QAAA,CAAS,EAAA,EAAI,KAAA,EAAO,KAAK,CAAA;AACnC,MAAA,CAAA,CAAE,MAAA,IAAU,MAAA;AACZ,MAAA,CAAA,CAAE,MAAA,IAAU,MAAA;AACZ,MAAA,MAAM,OAAA,EAAQ;AAAA,IAChB,CAAA;AAAA,IAEA,MAAM,SAAA,CAAU,EAAA,EAAI,MAAA,EAAQ;AAC1B,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,MAAM,EAAA,GAAK,MAAM,EAAE,CAAA;AACnB,MAAA,IAAI,CAAC,EAAA,EAAI;AACT,MAAA,EAAA,CAAG,OAAA,GAAU,KAAA;AACb,MAAA,EAAA,CAAG,aAAA,GAAgB,CAAA;AACnB,MAAA,IAAI,MAAA,EAAQ;AACV,QAAA,MAAM,IAAA,GAAO,KAAA,CAAM,GAAA,CAAI,EAAE,CAAA;AACzB,QAAA,IAAI,IAAA,OAAW,MAAA,GAAS,MAAA;AAAA,MAC1B;AACA,MAAA,MAAM,OAAA,EAAQ;AAAA,IAChB,CAAA;AAAA,IAEA,MAAM,MAAA,GAAS;AACb,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,OAAO,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AAAA,IACzC,CAAA;AAAA,IAEA,MAAM,SAAA,CAAU,QAAA,EAAU,KAAA,GAAQ,EAAA,EAAI,YAAY,CAAA,EAAG;AACnD,MAAA,MAAM,YAAA,EAAa;AACnB,MAAA,OAAO,WAAW,QAAA,EAAU,KAAA,EAAO,SAAA,EAAW,GAAA,EAAK,CAAA,CAAE,MAAA;AAAA,IACvD;AAAA,GACF;AACF;AAGO,SAAS,OAAA,CAAQ,EAAA,EAAiH,GAAA,GAAM,eAAA,EAA+B;AAC5K,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,GAAO;AACX,MAAA,MAAM,GAAA,GAAM,MAAM,EAAA,CAAG,GAAA,CAAI,GAAG,CAAA;AAC5B,MAAA,OAAO,GAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA,GAAiC,IAAA;AAAA,IAC/D,CAAA;AAAA,IACA,MAAM,KAAK,MAAA,EAAQ;AACjB,MAAA,MAAM,GAAG,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,SAAA,CAAU,MAAM,CAAC,CAAA;AAAA,IAC1C;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import type { BucketState, KeypoolStore, KeySpec, KeyState, Limits, ReportInput } from \"./types.js\";\n\nexport type { BucketState, KeypoolStore, KeySpec, KeyState, Limits, ReportInput } from \"./types.js\";\n\nexport interface KeypoolOptions {\n  keys: KeySpec[];\n  /** Default limits per provider, applied to every key unless the key overrides. */\n  providerLimits?: Record<string, Limits>;\n  /** Per-model limit overrides, e.g. { \"groq:llama-3.3-70b\": { tpd: 500000 } }. Key format `provider:model`. */\n  modelLimits?: Record<string, Limits>;\n  /** Cooldown (ms) applied on a 429 when no retry-after header is present. Default 60000. */\n  defaultCooldownMs?: number;\n  /** Persistence adapter for cross-process sharing. Default: in-memory only. */\n  store?: KeypoolStore;\n  /** Injectable clock (ms). */\n  now?: () => number;\n}\n\nexport interface Pick {\n  id: string;\n  secret: string;\n  provider: string;\n  model: string;\n}\n\nexport interface Keypool {\n  /**\n   * Pick the best healthy key for (provider, model) that can afford ~estTokens,\n   * or null if every key is cooling down / quota-exhausted / invalid.\n   */\n  pick(provider: string, model?: string, estTokens?: number): Promise<Pick | null>;\n  /** Report the outcome of a call so counters, cooldowns and quarantine update. */\n  report(id: string, result: ReportInput): Promise<void>;\n  /** Reserve usage yourself (when you don't call report), e.g. optimistic accounting. */\n  note(id: string, model: string, tokens: number): Promise<void>;\n  /** Clear a key's invalid quarantine (after you rotated the secret). */\n  reinstate(id: string, secret?: string): Promise<void>;\n  /** Snapshot of every key's state. */\n  states(): Promise<Record<string, KeyState>>;\n  /** How many keys are pickable right now for a provider/model. */\n  available(provider: string, model?: string, estTokens?: number): Promise<number>;\n}\n\nconst MIN = 60_000;\nconst DAY = 86_400_000;\n\nfunction emptyBucket(now: number): BucketState {\n  return { minStart: now, minReq: 0, minTok: 0, dayStart: now, dayReq: 0, dayTok: 0 };\n}\n\nfunction rollBucket(b: BucketState, now: number): void {\n  if (now - b.minStart >= MIN) {\n    b.minStart = now;\n    b.minReq = 0;\n    b.minTok = 0;\n  }\n  if (now - b.dayStart >= DAY) {\n    b.dayStart = now;\n    b.dayReq = 0;\n    b.dayTok = 0;\n  }\n}\n\nfunction headerGet(headers: ReportInput[\"headers\"], name: string): string | null {\n  if (!headers) return null;\n  if (typeof (headers as { get?: unknown }).get === \"function\") return (headers as { get(n: string): string | null }).get(name);\n  const h = headers as Record<string, string | number | null | undefined>;\n  const found = h[name] ?? h[name.toLowerCase()] ?? h[name.toUpperCase()];\n  return found === undefined || found === null ? null : String(found);\n}\n\nexport function createKeypool(options: KeypoolOptions): Keypool {\n  const now = options.now ?? (() => Date.now());\n  const cooldownMs = options.defaultCooldownMs ?? MIN;\n  const store = options.store;\n  const specs = new Map<string, KeySpec>();\n  for (const k of options.keys) specs.set(k.id, k);\n\n  // Live state, hydrated from the store if present.\n  let state: Record<string, KeyState> = {};\n  let loaded = false;\n\n  const ensureLoaded = async () => {\n    if (loaded) return;\n    const fromStore = store ? await store.load() : null;\n    for (const spec of options.keys) {\n      state[spec.id] = fromStore?.[spec.id] ?? {\n        id: spec.id,\n        provider: spec.provider,\n        cooldownUntil: 0,\n        invalid: false,\n        buckets: {},\n        lastUsed: 0,\n      };\n    }\n    loaded = true;\n  };\n\n  const persist = async () => {\n    if (store) await store.save(state);\n  };\n\n  const limitsFor = (spec: KeySpec, model: string): Limits => ({\n    ...(options.providerLimits?.[spec.provider] ?? {}),\n    ...(options.modelLimits?.[`${spec.provider}:${model}`] ?? {}),\n    ...(spec.limits ?? {}),\n  });\n\n  const bucketOf = (ks: KeyState, model: string, t: number): BucketState => {\n    let b = ks.buckets[model];\n    if (!b) {\n      b = emptyBucket(t);\n      ks.buckets[model] = b;\n    }\n    rollBucket(b, t);\n    return b;\n  };\n\n  const canAfford = (spec: KeySpec, ks: KeyState, model: string, estTokens: number, t: number): boolean => {\n    if (ks.invalid) return false;\n    if (ks.cooldownUntil > t) return false;\n    const lim = limitsFor(spec, model);\n    const b = bucketOf(ks, model, t);\n    if (lim.rpm !== undefined && b.minReq + 1 > lim.rpm) return false;\n    if (lim.rpd !== undefined && b.dayReq + 1 > lim.rpd) return false;\n    if (lim.tpm !== undefined && b.minTok + estTokens > lim.tpm) return false;\n    if (lim.tpd !== undefined && b.dayTok + estTokens > lim.tpd) return false;\n    return true;\n  };\n\n  const candidates = (provider: string, model: string, estTokens: number, t: number): { spec: KeySpec; ks: KeyState }[] => {\n    const out: { spec: KeySpec; ks: KeyState }[] = [];\n    for (const spec of options.keys) {\n      if (spec.provider !== provider) continue;\n      const ks = state[spec.id]!;\n      if (canAfford(spec, ks, model, estTokens, t)) out.push({ spec, ks });\n    }\n    // Highest priority, then least-recently-used (round-robin), then id for stability.\n    out.sort(\n      (a, b) =>\n        (b.spec.priority ?? 0) - (a.spec.priority ?? 0) ||\n        a.ks.lastUsed - b.ks.lastUsed ||\n        a.spec.id.localeCompare(b.spec.id),\n    );\n    return out;\n  };\n\n  return {\n    async pick(provider, model = \"\", estTokens = 0) {\n      await ensureLoaded();\n      const t = now();\n      const cand = candidates(provider, model, estTokens, t)[0];\n      if (!cand) return null;\n      // Optimistically reserve one request + estimated tokens so concurrent picks spread out.\n      const b = bucketOf(cand.ks, model, t);\n      b.minReq += 1;\n      b.dayReq += 1;\n      b.minTok += estTokens;\n      b.dayTok += estTokens;\n      cand.ks.lastUsed = t;\n      await persist();\n      return { id: cand.spec.id, secret: cand.spec.secret, provider, model };\n    },\n\n    async report(id, result) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      const t = now();\n      const model = result.model ?? Object.keys(ks.buckets)[0] ?? \"\";\n      const b = bucketOf(ks, model, t);\n\n      // Reconcile token count if the caller reserved an estimate at pick().\n      if (result.tokens !== undefined) {\n        b.minTok += result.tokens; // add ACTUAL on top of the estimate reserved at pick; callers can pass a delta if they prefer\n        b.dayTok += result.tokens;\n      }\n\n      // Absorb provider-reported remaining/limits when present.\n      const retryAfter = headerGet(result.headers, \"retry-after\");\n      const status = result.status ?? (result.ok ? 200 : 0);\n\n      if (status === 401 || status === 403) {\n        ks.invalid = true;\n      } else if (status === 429) {\n        let waitMs = cooldownMs;\n        if (retryAfter) {\n          const n = Number(retryAfter);\n          waitMs = Number.isFinite(n) ? n * 1000 : Math.max(0, new Date(retryAfter).getTime() - t) || cooldownMs;\n        }\n        ks.cooldownUntil = t + waitMs;\n      } else if (result.ok) {\n        // clear any stale cooldown on a clean success\n        if (ks.cooldownUntil <= t) ks.cooldownUntil = 0;\n      }\n      await persist();\n    },\n\n    async note(id, model, tokens) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      const b = bucketOf(ks, model, now());\n      b.minTok += tokens;\n      b.dayTok += tokens;\n      await persist();\n    },\n\n    async reinstate(id, secret) {\n      await ensureLoaded();\n      const ks = state[id];\n      if (!ks) return;\n      ks.invalid = false;\n      ks.cooldownUntil = 0;\n      if (secret) {\n        const spec = specs.get(id);\n        if (spec) spec.secret = secret;\n      }\n      await persist();\n    },\n\n    async states() {\n      await ensureLoaded();\n      return JSON.parse(JSON.stringify(state));\n    },\n\n    async available(provider, model = \"\", estTokens = 0) {\n      await ensureLoaded();\n      return candidates(provider, model, estTokens, now()).length;\n    },\n  };\n}\n\n/** A KeypoolStore backed by any {get,set} KV (JSON string values). Handy over Mongo/Redis. */\nexport function kvStore(kv: { get(k: string): Promise<string | null> | string | null; set(k: string, v: string): Promise<void> | void }, key = \"keypool:state\"): KeypoolStore {\n  return {\n    async load() {\n      const raw = await kv.get(key);\n      return raw ? (JSON.parse(raw) as Record<string, KeyState>) : null;\n    },\n    async save(states) {\n      await kv.set(key, JSON.stringify(states));\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@lacspace/keypool",
+  "version": "1.0.0",
+  "description": "Provider-agnostic API-key rotation and rate-limit accounting — pool N free keys per provider, track RPM/RPD/TPM/TPD windows from response headers and 429 retry-after, round-robin among healthy keys, cool down on 429, quarantine invalid keys, and keep per-model buckets (Groq TPD is per model). pick(provider, model, estTokens) → key | null; report(key, result). Persist state via a tiny adapter so multiple processes share the pool. Zero-dependency, isomorphic, typed.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": { "build": "tsup", "prepublishOnly": "npm run build" },
+  "keywords": ["api-key", "key-rotation", "rate-limit", "keypool", "round-robin", "429", "retry-after", "quota", "rpm", "tpm", "gemini", "groq", "openai", "free-tier", "zero-dependency", "isomorphic", "typescript"],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/keypool",
+  "repository": { "type": "git", "url": "git+https://github.com/lacspace/npm-packages.git", "directory": "keypool" },
+  "bugs": { "url": "https://github.com/lacspace/npm-packages/issues" },
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" }
+}