@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/services/idempotency.d.ts

@@ -0,0 +1,49 @@
+import type { ChatMessage } from '@srouter/shared/types.js';
+/** Replay window for completed idempotent responses (default 24h). */
+export declare function idempotencyTtlMs(): number;
+export declare function hashIdempotencyKey(key: string): string;
+/** Canonical fingerprint of the request content that produced a response. */
+export declare function computeIdempotencyFingerprint(input: {
+    model?: string;
+    messages: ChatMessage[];
+    temperature?: number | null;
+    top_p?: number | null;
+    max_tokens?: number | null;
+    tools?: unknown;
+    tool_choice?: unknown;
+}): string;
+export type IdempotencyClaimResult = {
+    kind: 'replay';
+    status: number;
+    body: unknown;
+} | {
+    kind: 'conflict';
+} | {
+    kind: 'miss';
+};
+/**
+ * Attempt to claim a completed idempotent response for the given key hash.
+ *
+ * Returns:
+ *   - { kind: 'replay', ... } when a completed claim with the SAME fingerprint
+ *     exists and is still inside the replay window — the caller should replay
+ *     it verbatim without touching a provider.
+ *   - { kind: 'conflict' } when a completed claim exists but its fingerprint
+ *     differs — the caller must return 409 idempotency_key_conflict.
+ *   - { kind: 'miss' } when there is no usable claim — proceed normally and
+ *     persist the result on success.
+ */
+export declare function lookupIdempotencyReplay(keyHash: string, fingerprint: string, now?: number): IdempotencyClaimResult;
+/**
+ * Persist a completed response for future replays. Replaces any previous claim
+ * for the same key hash. Expired rows are swept lazily for this key first.
+ */
+export declare function storeIdempotencyResult(keyHash: string, fingerprint: string, status: number, body: unknown, executionId?: string, now?: number): void;
+/**
+ * Delete an idempotency claim (e.g. after a failed generation that the caller
+ * does not want replayed). Fail-safe.
+ */
+export declare function clearIdempotencyResult(keyHash: string): void;
+/** Normalize an Idempotency-Key header: trim, non-empty, ≤ 255 UTF-8 bytes. */
+export declare function normalizeIdempotencyKey(raw: string | string[] | undefined): string | null;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/services/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/services/idempotency.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAW5D,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,MAAM,CAWT;AAID,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,GAAG,SAAa,GACf,sBAAsB,CAwBxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,WAAW,CAAC,EAAE,MAAM,EACpB,GAAG,SAAa,GACf,IAAI,CA6BN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAM5D;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMzF"}

package/dist/services/idempotency.js

@@ -0,0 +1,140 @@
+// Idempotency-Key support for non-streaming chat requests.
+//
+// Free-tier quota is a scarce asset: a client that times out and retries the
+// same non-streaming request currently burns a second free-tier slot for an
+// answer it already received. This module lets callers opt in to idempotent
+// retries via the `Idempotency-Key` header:
+//
+//   - Only a SHA-256 hash of the caller's key is stored, never the raw key.
+//   - A request fingerprint (canonical SHA-256 of model + messages + sampling
+//     params) is bound to the key, so reusing the same key with different
+//     content is a 409 conflict, not a silent wrong answer.
+//   - On success the original HTTP status + body are persisted to SQLite and
+//     replayed for later requests with the same key + fingerprint — zero
+//     provider cost, mirroring what the response cache does for exact-match
+//     hits, but scoped per caller (key) instead of per request content.
+//   - A duplicate that arrives while the original request is still running is
+//     NOT deduplicated: only completed responses are claimed, so both attempts
+//     execute. Guarding the in-flight window needs a pending-claim state with
+//     its own (short) TTL so a crash cannot wedge a key for a day; that is
+//     deliberately out of scope here.
+//
+// Storage is the idempotency_claims table (see db/migrations). All writes are
+// guarded so a DB failure degrades to "no idempotency" rather than throwing in
+// the proxy hot path (mirrors services/cache.ts).
+import crypto from 'crypto';
+import { getDb } from '../db/index.js';
+// ── Config (read per call so tests can flip it live) ──
+function envNum(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** Replay window for completed idempotent responses (default 24h). */
+export function idempotencyTtlMs() {
+    return envNum('IDEMPOTENCY_TTL_MS', 24 * 60 * 60 * 1000);
+}
+// ── Key / fingerprint helpers ──
+export function hashIdempotencyKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+}
+/** Canonical fingerprint of the request content that produced a response. */
+export function computeIdempotencyFingerprint(input) {
+    const stable = JSON.stringify({
+        model: input.model ?? null,
+        messages: input.messages,
+        temperature: input.temperature ?? null,
+        top_p: input.top_p ?? null,
+        max_tokens: input.max_tokens ?? null,
+        tools: input.tools ?? null,
+        tool_choice: input.tool_choice ?? null,
+    });
+    return crypto.createHash('sha256').update(stable).digest('hex');
+}
+/**
+ * Attempt to claim a completed idempotent response for the given key hash.
+ *
+ * Returns:
+ *   - { kind: 'replay', ... } when a completed claim with the SAME fingerprint
+ *     exists and is still inside the replay window — the caller should replay
+ *     it verbatim without touching a provider.
+ *   - { kind: 'conflict' } when a completed claim exists but its fingerprint
+ *     differs — the caller must return 409 idempotency_key_conflict.
+ *   - { kind: 'miss' } when there is no usable claim — proceed normally and
+ *     persist the result on success.
+ */
+export function lookupIdempotencyReplay(keyHash, fingerprint, now = Date.now()) {
+    try {
+        const db = getDb();
+        const row = db.prepare(`SELECT request_fingerprint, response_status, response_body
+         FROM idempotency_claims
+        WHERE key_hash = ? AND expires_at_ms > ?`).get(keyHash, now);
+        if (!row)
+            return { kind: 'miss' };
+        if (row.request_fingerprint !== fingerprint)
+            return { kind: 'conflict' };
+        let body;
+        try {
+            body = JSON.parse(row.response_body);
+        }
+        catch {
+            // Corrupt stored body — treat as a miss and let the caller regenerate.
+            return { kind: 'miss' };
+        }
+        return { kind: 'replay', status: row.response_status, body };
+    }
+    catch {
+        // DB unavailable: degrade to no idempotency rather than failing the request.
+        return { kind: 'miss' };
+    }
+}
+/**
+ * Persist a completed response for future replays. Replaces any previous claim
+ * for the same key hash. Expired rows are swept lazily for this key first.
+ */
+export function storeIdempotencyResult(keyHash, fingerprint, status, body, executionId, now = Date.now()) {
+    try {
+        const db = getDb();
+        const ttl = idempotencyTtlMs();
+        db.prepare('DELETE FROM idempotency_claims WHERE key_hash = ? AND expires_at_ms <= ?')
+            .run(keyHash, now);
+        db.prepare(`INSERT INTO idempotency_claims
+         (key_hash, request_fingerprint, response_status, response_body, execution_id, created_at_ms, expires_at_ms)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(key_hash) DO UPDATE SET
+         request_fingerprint = excluded.request_fingerprint,
+         response_status = excluded.response_status,
+         response_body = excluded.response_body,
+         execution_id = excluded.execution_id,
+         created_at_ms = excluded.created_at_ms,
+         expires_at_ms = excluded.expires_at_ms`).run(keyHash, fingerprint, status, JSON.stringify(body), executionId ?? null, now, now + ttl);
+    }
+    catch {
+        // DB unavailable: idempotency is best-effort; the response already went out.
+    }
+}
+/**
+ * Delete an idempotency claim (e.g. after a failed generation that the caller
+ * does not want replayed). Fail-safe.
+ */
+export function clearIdempotencyResult(keyHash) {
+    try {
+        getDb().prepare('DELETE FROM idempotency_claims WHERE key_hash = ?').run(keyHash);
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Normalize an Idempotency-Key header: trim, non-empty, ≤ 255 UTF-8 bytes. */
+export function normalizeIdempotencyKey(raw) {
+    if (raw === undefined)
+        return null;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const trimmed = (value ?? '').trim();
+    if (!trimmed || Buffer.byteLength(trimmed, 'utf8') > 255)
+        return null;
+    return trimmed;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/services/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/services/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/services/key-budget.d.ts

@@ -0,0 +1,74 @@
+import type { BudgetPeriod, ConcreteBudgetPeriod, BudgetPeriodSource } from '@srouter/shared/types.js';
+/** Re-exported so consumers can import the shared types from here. */
+export type { BudgetPeriod, ConcreteBudgetPeriod, BudgetPeriodSource };
+export declare const BUDGET_PERIODS: readonly ConcreteBudgetPeriod[];
+export declare function asBudgetPeriod(raw: unknown): BudgetPeriod;
+/** Cast a stored/external value to a concrete period (auto is never stored). */
+export declare function asConcreteBudgetPeriod(raw: unknown): ConcreteBudgetPeriod;
+/** Resolve the auto budget period for a platform from the catalog. */
+export declare function resolveAutoPeriod(platform: string): {
+    period: ConcreteBudgetPeriod;
+    source: BudgetPeriodSource;
+};
+/** Synchronize an auto-mode key's concrete period with the catalog. */
+export declare function syncAutoBudgetPeriod(keyId: number): {
+    mode: 'auto' | 'manual';
+    period: ConcreteBudgetPeriod;
+    source: BudgetPeriodSource;
+};
+export interface MonthlyBudgetCaps {
+    /** 0 = unlimited (the default, unchanged behaviour). */
+    requestCap: number;
+    /** 0 = unlimited. */
+    tokenCap: number;
+    /** UTC window the caps are counted against. */
+    period: ConcreteBudgetPeriod;
+    /** Whether the period is auto-resolved or manually chosen. */
+    mode: 'auto' | 'manual';
+    /** For 'auto': why the period was chosen. */
+    source: BudgetPeriodSource;
+}
+export interface MonthlyUsage {
+    /** Successful requests in the current period. */
+    requests: number;
+    /** Sum of (input_tokens + output_tokens) over those successes. */
+    tokens: number;
+}
+export type BudgetVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'monthly_request_cap' | 'monthly_token_cap';
+    retryAfterSec: number;
+};
+/** Ledger bucket for a period at `now` — must match the trigger's SQL. */
+export declare function periodBucket(period: ConcreteBudgetPeriod, now?: number): string;
+export declare function getMonthlyBudgetCaps(keyId: number): MonthlyBudgetCaps;
+export declare function setMonthlyBudgetCaps(keyId: number, patch: Partial<Pick<MonthlyBudgetCaps, 'requestCap' | 'tokenCap'>>): boolean;
+export declare function getMonthlyUsage(keyId: number, period?: ConcreteBudgetPeriod, now?: number): MonthlyUsage;
+/**
+ * Check a key against its caps, taking the current period's successful usage
+ * plus the tokens THIS request would add. Returns allowed when both caps are
+ * 0 (unlimited) or neither would be exceeded.
+ */
+export declare function checkMonthlyBudget(keyId: number, estimatedTokens: number, now?: number): BudgetVerdict;
+/** Check and reserve synchronously before dispatch; release on every terminal path. */
+export declare function reserveMonthlyBudget(keyId: number, estimatedTokens: number): {
+    allowed: true;
+    release: () => void;
+} | Extract<BudgetVerdict, {
+    allowed: false;
+}>;
+/** Seconds from `now` until the next boundary of the period — the Retry-After value. */
+export declare function secondsUntilNextPeriod(period: ConcreteBudgetPeriod, now?: number): number;
+/** Seconds from `now` until the next UTC month boundary (monthly default). */
+export declare function secondsUntilNextMonth(now?: number): number;
+/** ISO timestamp of the next period boundary (for headers / diagnostics). */
+export declare function nextResetAt(period: ConcreteBudgetPeriod, now?: number): string;
+/** ISO timestamp of the next UTC month boundary (monthly default). */
+export declare function nextMonthResetAt(now?: number): string;
+/** Soonest period boundary among the keys currently blocked by their caps —
+ *  what the routing exhaustion body advertises as the retry time. Falls back
+ *  to the next month when no capped key is blocked. */
+export declare function soonestBudgetResetAt(now?: number): string;
+//# sourceMappingURL=key-budget.d.ts.map

package/dist/services/key-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-budget.d.ts","sourceRoot":"","sources":["../../src/services/key-budget.ts"],"names":[],"mappings":"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"}

package/dist/services/key-budget.js

@@ -0,0 +1,200 @@
+/**
+ * Per-key budget (#1158, period-aware): optional request/token caps per
+ * api_keys row, enforced against the CURRENT UTC period's successful
+ * requests. The period is chosen per key to match the provider's reset
+ * cycle: daily (next 00:00 UTC), weekly (next Monday 00:00 UTC) or monthly
+ * (1st 00:00 UTC, the original behaviour and the default).
+ *
+ * A key at its cap returns `quota_exceeded` (429) with a Retry-After of
+ * "seconds until the next period boundary" — the semantic GateLLM-style
+ * rejection so an agent knows when the window resets instead of hammering
+ * a 429.
+ *
+ * Successful usage is retained in key_monthly_usage independently of
+ * analytics retention. Buckets are namespaced per period ('d:YYYY-MM-DD',
+ * 'w:YYYY-MM-DD' Monday, bare 'YYYY-MM' month) so switching a key's period
+ * starts the new counter at zero instead of reinterpreting old rows — see
+ * migration 20261005_000001_key_budget_period, whose trigger mirrors
+ * periodBucket() exactly. Active requests reserve their estimated tokens
+ * until their route is released. Actual provider usage is settled by the
+ * request-log transaction; token estimates are an admission guard, not an
+ * exact upstream billing cap. Caps are opt-in (0 = unlimited).
+ *
+ * AUTO MODE: a key may leave its period to the provider's catalog
+ * declaration (`budget_period_mode = 'auto'`). resolveAutoPeriod() reads the
+ * `models` table for that platform — a per-day limit field (tpd_limit or
+ * rpd_limit) means the provider resets daily, a non-empty
+ * monthly_token_budget means a monthly allowance, otherwise the unknown
+ * fallback is monthly. The resolved CONCRETE period is written into
+ * `budget_period` (the trigger reads that column and must stay concrete —
+ * 'auto' is never stored there); `budget_period_mode` stays 'auto' so the
+ * UI can tell a resolved key from a manually-picked one. Weekly is never
+ * produced by auto resolution: the catalog carries no weekly field, so
+ * weekly remains a manual choice only.
+ */
+import { getDb } from '../db/index.js';
+export const BUDGET_PERIODS = ['daily', 'weekly', 'monthly'];
+export function asBudgetPeriod(raw) {
+    return raw === 'daily' || raw === 'weekly' || raw === 'monthly' ? raw : 'monthly';
+}
+/** Cast a stored/external value to a concrete period (auto is never stored). */
+export function asConcreteBudgetPeriod(raw) {
+    return raw === 'daily' || raw === 'weekly' ? raw : 'monthly';
+}
+/** Resolve the auto budget period for a platform from the catalog. */
+export function resolveAutoPeriod(platform) {
+    const db = getDb();
+    const row = db.prepare(`SELECT
+      EXISTS(SELECT 1 FROM models WHERE platform = ? AND (tpd_limit IS NOT NULL OR rpd_limit IS NOT NULL)) AS has_daily,
+      EXISTS(SELECT 1 FROM models WHERE platform = ? AND monthly_token_budget <> '') AS has_monthly`).get(platform, platform);
+    if (row.has_daily)
+        return { period: 'daily', source: 'daily-limit' };
+    if (row.has_monthly)
+        return { period: 'monthly', source: 'monthly-label' };
+    return { period: 'monthly', source: 'fallback' };
+}
+/** Synchronize an auto-mode key's concrete period with the catalog. */
+export function syncAutoBudgetPeriod(keyId) {
+    const row = getDb().prepare('SELECT platform, budget_period, budget_period_mode FROM api_keys WHERE id = ?').get(keyId);
+    if (!row)
+        return { mode: 'manual', period: 'monthly', source: 'manual' };
+    if (row.budget_period_mode === 'manual') {
+        return { mode: 'manual', period: asConcreteBudgetPeriod(row.budget_period), source: 'manual' };
+    }
+    const resolved = resolveAutoPeriod(row.platform);
+    if (resolved.period !== row.budget_period) {
+        getDb().prepare('UPDATE api_keys SET budget_period = ? WHERE id = ?').run(resolved.period, keyId);
+    }
+    return { mode: 'auto', period: resolved.period, source: resolved.source };
+}
+/** Ledger bucket for a period at `now` — must match the trigger's SQL. */
+export function periodBucket(period, now = Date.now()) {
+    const d = new Date(now);
+    if (period === 'monthly')
+        return d.toISOString().slice(0, 7);
+    const day = d.toISOString().slice(0, 10);
+    if (period === 'daily')
+        return `d:${day}`;
+    const mondayMs = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - ((d.getUTCDay() + 6) % 7));
+    return `w:${new Date(mondayMs).toISOString().slice(0, 10)}`;
+}
+function utcNextPeriodStartMs(period, now) {
+    const d = new Date(now);
+    if (period === 'monthly') {
+        const month = d.getUTCMonth() + 1;
+        return Date.UTC(d.getUTCFullYear() + Math.floor(month / 12), month % 12, 1);
+    }
+    if (period === 'daily') {
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+    }
+    // weekly: Monday of this UTC week + 7 days
+    const mondayDate = d.getUTCDate() - ((d.getUTCDay() + 6) % 7);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), mondayDate + 7);
+}
+// These requests belong to this process and remain reserved until completion,
+// even if a stream outlives the short rate-limit lease timeout. A restarted
+// process has no active requests; completed usage remains in SQLite.
+const reservations = new WeakMap();
+function activeReservations() {
+    const db = getDb();
+    let active = reservations.get(db);
+    if (!active) {
+        active = new Set();
+        reservations.set(db, active);
+    }
+    return active;
+}
+export function getMonthlyBudgetCaps(keyId) {
+    const sync = syncAutoBudgetPeriod(keyId);
+    const row = getDb().prepare('SELECT monthly_request_cap, monthly_token_cap FROM api_keys WHERE id = ?').get(keyId);
+    if (!row)
+        return { requestCap: 0, tokenCap: 0, period: 'monthly', mode: 'manual', source: 'manual' };
+    return { requestCap: row.monthly_request_cap, tokenCap: row.monthly_token_cap, period: sync.period, mode: sync.mode, source: sync.source };
+}
+export function setMonthlyBudgetCaps(keyId, patch) {
+    const sets = [];
+    const values = [];
+    if (patch.requestCap !== undefined) {
+        sets.push('monthly_request_cap = ?');
+        values.push(patch.requestCap);
+    }
+    if (patch.tokenCap !== undefined) {
+        sets.push('monthly_token_cap = ?');
+        values.push(patch.tokenCap);
+    }
+    if (sets.length === 0)
+        return false;
+    const result = getDb().prepare(`UPDATE api_keys SET ${sets.join(', ')} WHERE id = ?`).run(...values, keyId);
+    return result.changes > 0;
+}
+export function getMonthlyUsage(keyId, period = 'monthly', now = Date.now()) {
+    const row = getDb().prepare(`SELECT requests, tokens FROM key_monthly_usage WHERE key_id = ? AND month = ?`).get(keyId, periodBucket(period, now));
+    return { requests: Number(row?.requests ?? 0), tokens: Number(row?.tokens ?? 0) };
+}
+/**
+ * Check a key against its caps, taking the current period's successful usage
+ * plus the tokens THIS request would add. Returns allowed when both caps are
+ * 0 (unlimited) or neither would be exceeded.
+ */
+export function checkMonthlyBudget(keyId, estimatedTokens, now = Date.now()) {
+    const caps = getMonthlyBudgetCaps(keyId);
+    if (caps.requestCap <= 0 && caps.tokenCap <= 0)
+        return { allowed: true };
+    const usage = getMonthlyUsage(keyId, caps.period, now);
+    for (const reservation of activeReservations()) {
+        if (reservation.keyId !== keyId)
+            continue;
+        usage.requests++;
+        usage.tokens += reservation.tokens;
+    }
+    if (caps.requestCap > 0 && usage.requests >= caps.requestCap) {
+        return { allowed: false, reason: 'monthly_request_cap', retryAfterSec: secondsUntilNextPeriod(caps.period, now) };
+    }
+    if (caps.tokenCap > 0 && (usage.tokens >= caps.tokenCap || usage.tokens + Math.max(0, estimatedTokens) > caps.tokenCap)) {
+        return { allowed: false, reason: 'monthly_token_cap', retryAfterSec: secondsUntilNextPeriod(caps.period, now) };
+    }
+    return { allowed: true };
+}
+/** Check and reserve synchronously before dispatch; release on every terminal path. */
+export function reserveMonthlyBudget(keyId, estimatedTokens) {
+    const verdict = checkMonthlyBudget(keyId, estimatedTokens);
+    if (!verdict.allowed)
+        return verdict;
+    const active = activeReservations();
+    const reservation = { keyId, tokens: Math.max(0, estimatedTokens) };
+    active.add(reservation);
+    return { allowed: true, release: () => { active.delete(reservation); } };
+}
+/** Seconds from `now` until the next boundary of the period — the Retry-After value. */
+export function secondsUntilNextPeriod(period, now = Date.now()) {
+    return Math.max(1, Math.floor((utcNextPeriodStartMs(period, now) - now) / 1000));
+}
+/** Seconds from `now` until the next UTC month boundary (monthly default). */
+export function secondsUntilNextMonth(now = Date.now()) {
+    return secondsUntilNextPeriod('monthly', now);
+}
+/** ISO timestamp of the next period boundary (for headers / diagnostics). */
+export function nextResetAt(period, now = Date.now()) {
+    return new Date(utcNextPeriodStartMs(period, now)).toISOString();
+}
+/** ISO timestamp of the next UTC month boundary (monthly default). */
+export function nextMonthResetAt(now = Date.now()) {
+    return nextResetAt('monthly', now);
+}
+/** Soonest period boundary among the keys currently blocked by their caps —
+ *  what the routing exhaustion body advertises as the retry time. Falls back
+ *  to the next month when no capped key is blocked. */
+export function soonestBudgetResetAt(now = Date.now()) {
+    const rows = getDb().prepare('SELECT id FROM api_keys WHERE monthly_request_cap > 0 OR monthly_token_cap > 0').all();
+    let soonestMs = utcNextPeriodStartMs('monthly', now);
+    for (const row of rows) {
+        const caps = getMonthlyBudgetCaps(row.id);
+        if (checkMonthlyBudget(row.id, 0, now).allowed)
+            continue;
+        const atMs = utcNextPeriodStartMs(caps.period, now);
+        if (atMs < soonestMs)
+            soonestMs = atMs;
+    }
+    return new Date(soonestMs).toISOString();
+}
+//# sourceMappingURL=key-budget.js.map

package/dist/services/key-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-budget.js","sourceRoot":"","sources":["../../src/services/key-budget.ts"],"names":[],"mappings":"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"}

package/dist/services/media.d.ts

@@ -0,0 +1,123 @@
+/** Platforms with a media adapter below. catalog-sync gates media rows on this
+ *  (decoupled from the chat provider registry — e.g. SiliconFlow is media-only). */
+export declare const MEDIA_PLATFORMS: Set<string>;
+/** Video uses a dedicated optional catalog registry so binaries that predate
+ *  this modality ignore the rows instead of accidentally ingesting them as
+ *  chat models. Keep its adapter allowlist separate for the same reason. */
+export declare const VIDEO_PLATFORMS: Set<string>;
+/** Platforms with a speech-to-text adapter below. catalog-sync gates the
+ *  catalog's `transcriptionModels` entries on this, the way MEDIA_PLATFORMS
+ *  gates the generative-media rows. */
+export declare const TRANSCRIPTION_PLATFORMS: Set<string>;
+export type MediaModality = 'image' | 'video' | 'audio' | 'transcription';
+export interface MediaModelRow {
+    id: number;
+    platform: string;
+    model_id: string;
+    display_name: string;
+    modality: MediaModality;
+    priority: number;
+    enabled: number;
+    quota_label: string;
+    key_id: number | null;
+    meta_json: string | null;
+}
+export declare class MediaError extends Error {
+    status: number;
+    /** Optional machine-readable error code surfaced in the OpenAI-shaped body. */
+    code?: string;
+    /** Back-off the upstream provider stated (`Retry-After` header), in
+     *  milliseconds — relayed to the client so an SDK sleeps the stated amount
+     *  instead of hammering the chain, mirroring the embeddings path. */
+    retryAfterMs?: number;
+    constructor(message: string, status: number, code?: string, retryAfterMs?: number);
+}
+export interface ImageResult {
+    platform: string;
+    modelId: string;
+    images: Array<{
+        b64_json?: string;
+        url?: string;
+    }>;
+}
+export interface SpeechResult {
+    platform: string;
+    modelId: string;
+    audio: Buffer;
+    contentType: string;
+}
+export interface VideoResult {
+    platform: string;
+    modelId: string;
+    video: Buffer;
+    contentType: string;
+}
+export interface ImageParams {
+    prompt: string;
+    n?: number;
+    size?: string;
+}
+export interface SpeechParams {
+    input: string;
+    voice?: string;
+    format?: string;
+}
+export interface VideoParams {
+    prompt: string;
+    duration?: number;
+    aspectRatio?: '16:9' | '9:16';
+    image?: string;
+    seed?: number;
+    audio?: boolean;
+}
+export declare function listMediaModels(modality: MediaModality): MediaModelRow[];
+/** All media models (both modalities, including disabled) for the dashboard. */
+export declare function listAllMediaModels(): MediaModelRow[];
+/** Generate image(s), failing over across providers serving the modality. */
+export declare function runImageGeneration(model: string | undefined, params: ImageParams): Promise<ImageResult>;
+/** Generate a video, failing over across catalogued text-to-video providers.
+ *  `clientSignal` is the API caller's connection: when it aborts, the in-flight
+ *  upstream request is dropped and no further provider is tried. */
+export declare function runVideoGeneration(model: string | undefined, params: VideoParams, clientSignal?: AbortSignal): Promise<VideoResult>;
+/** Per-model adapter metadata carried on the catalog entry (meta_json). */
+export interface TranscriptionMeta {
+    /** Subtitle formats the provider returns natively (e.g. ['vtt']). Formats
+     *  not produced natively by the chain are refused with 400 at the route. */
+    subtitleFormats?: string[];
+    /** Provider upload ceiling in bytes; absent = MAX_TRANSCRIPTION_BYTES. */
+    maxBytes?: number | null;
+    /** Adapter request flavor where one platform hosts more than one deployment
+     *  style. Cloudflare: 'json' = JSON body with base64 audio (large-v3-turbo),
+     *  'binary' = raw bytes (plain whisper, the default). */
+    requestStyle?: string | null;
+}
+/** Global upload ceiling enforced by the route (multer) so it can reject
+ *  early with a clean OpenAI-shaped 413 instead of buffering an upload no
+ *  provider can accept. Per-model catalog `maxBytes` may only lower this. */
+export declare const MAX_TRANSCRIPTION_BYTES: number;
+export interface TranscriptionParams {
+    file: Buffer;
+    filename: string;
+    mimeType?: string;
+    language?: string;
+    prompt?: string;
+    temperature?: number;
+    /** 'json' | 'text' | 'verbose_json' | 'vtt' (srt is rejected at the route). */
+    responseFormat: string;
+}
+export interface TranscriptionResult {
+    platform: string;
+    modelId: string;
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: unknown[];
+    vtt?: string;
+}
+/** Transcribe audio, failing over across STT providers. 429s bench the
+ *  (platform, model, key) triple through the standard cooldown machinery so a
+ *  rate-limited key is skipped on subsequent requests, exactly like chat. */
+export declare function runTranscription(model: string | undefined, p: TranscriptionParams): Promise<TranscriptionResult>;
+/** Synthesize speech, failing over across providers serving the modality. */
+export declare function runSpeech(model: string | undefined, params: SpeechParams): Promise<SpeechResult>;
+//# sourceMappingURL=media.d.ts.map

package/dist/services/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/services/media.ts"],"names":[],"mappings":"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"}