@zhangferry-dev/tokendash 1.6.1 → 1.7.0

package/dist/server/quota/quotaService.js

@@ -0,0 +1,163 @@
+import { QuotaError } from './adapter.js';
+import { QuotaCache } from './cache.js';
+import { validateQuotaSnapshot } from './schemas.js';
+/**
+ * Deep quota service. Owns discovery, concurrency, deduplication, caching,
+ * stale-while-revalidate, timeouts, and error classification. Adapters only
+ * detect + fetch + normalize; everything cross-cutting lives here.
+ */
+export class QuotaService {
+    registry;
+    cache;
+    configuredCache;
+    /** Cap concurrent upstream calls so a slow provider can't block the others. */
+    fetchTimeoutMs;
+    /** In-flight promises keyed by provider id, to dedupe concurrent requests. */
+    inflight = new Map();
+    constructor(registry, cache = new QuotaCache(), configuredCache = null, fetchTimeoutMs = 8_000) {
+        this.registry = registry;
+        this.cache = cache;
+        this.configuredCache = configuredCache;
+        this.fetchTimeoutMs = fetchTimeoutMs;
+    }
+    /**
+     * List provider ids that are configured locally. Cheap (no network).
+     * The dashboard only shows these — not-configured providers are excluded.
+     */
+    async discover() {
+        const all = this.registry.list();
+        const checks = await Promise.all(all.map(async (a) => ({ id: a.provider, configured: await safeIsConfigured(a) })));
+        return checks.filter((c) => c.configured).map((c) => c.id);
+    }
+    /**
+     * Fetch one provider's snapshot. Fresh if available; stale-but-retained
+     * on failure; never throws (errors become structured statuses).
+     */
+    async fetchOne(provider) {
+        // 1. Fresh cache hit
+        const fresh = this.cache.getFresh(provider);
+        if (fresh)
+            return fresh;
+        const adapter = this.registry.get(provider);
+        if (!adapter)
+            return null;
+        // 2. Dedupe concurrent requests for the same provider
+        let p = this.inflight.get(provider);
+        if (!p) {
+            p = this.fetchWithTimeout(adapter).finally(() => this.inflight.delete(provider));
+            this.inflight.set(provider, p);
+        }
+        return p;
+    }
+    /**
+     * Fetch all configured providers concurrently. Partial success: one
+     * provider's failure never breaks the others. Order = registry order.
+     */
+    async fetchAll() {
+        const ids = this.configuredCache ?? (await this.discover());
+        const byId = new Map();
+        const snapshots = await Promise.all(ids.map((id) => this.fetchOne(id)));
+        // Preserve registry order regardless of completion order.
+        for (const adapter of this.registry.list()) {
+            const snap = snapshots.find((s) => s?.provider === adapter.provider);
+            if (snap)
+                byId.set(adapter.provider, snap);
+        }
+        return { providers: this.registry.list().map((a) => byId.get(a.provider)).filter((s) => !!s) };
+    }
+    /** Force a refresh of all configured providers, bypassing the cache. */
+    async refreshAll() {
+        // Cache-clear only the freshness gate; stale data is still retained by fetchOne on failure.
+        this.configuredCache?.forEach(() => { });
+        for (const adapter of this.registry.list()) {
+            this.cache.clear(adapter.provider);
+        }
+        return this.fetchAll();
+    }
+    /**
+     * Validate a credential without caching it or writing it to disk. This keeps
+     * the settings form transactional: only credentials accepted upstream are
+     * persisted by the native app.
+     */
+    async validateCredential(provider, credential) {
+        const adapter = this.registry.get(provider);
+        if (!adapter) {
+            return {
+                provider,
+                valid: false,
+                status: { state: 'not_configured', message: 'Unsupported provider' },
+            };
+        }
+        try {
+            const snapshot = await withTimeout(adapter.fetch({ credential }), this.fetchTimeoutMs, provider);
+            const validated = validateQuotaSnapshot(snapshot);
+            return { provider, valid: validated.status.state === 'ok', status: validated.status };
+        }
+        catch (err) {
+            return { provider, valid: false, status: statusForError(err, this.fetchTimeoutMs) };
+        }
+    }
+    async fetchWithTimeout(adapter) {
+        try {
+            const snapshot = await withTimeout(adapter.fetch(), this.fetchTimeoutMs, adapter.provider);
+            const validated = validateQuotaSnapshot(snapshot);
+            this.cache.set(validated);
+            return validated;
+        }
+        catch (err) {
+            return this.handleFailure(adapter, err);
+        }
+    }
+    handleFailure(adapter, err) {
+        const status = statusForError(err, this.fetchTimeoutMs);
+        // Retain last good snapshot as stale.
+        const stale = this.cache.getStale(adapter.provider);
+        if (stale) {
+            return { ...stale, freshness: 'stale', status };
+        }
+        // No prior data — surface the structured error so the user can act on it.
+        return {
+            provider: adapter.provider,
+            displayName: adapter.displayName,
+            fetchedAt: new Date().toISOString(),
+            freshness: 'stale',
+            windows: [],
+            status,
+        };
+    }
+}
+function statusForError(err, timeoutMs) {
+    if (err instanceof QuotaError)
+        return err.status;
+    if (err instanceof TimeoutError) {
+        return { state: 'timed_out', message: `upstream did not respond within ${timeoutMs}ms` };
+    }
+    return { state: 'error', message: redact(err), category: 'unexpected' };
+}
+class TimeoutError extends Error {
+    constructor(provider) {
+        super(`quota fetch timed out: ${provider}`);
+        this.name = 'TimeoutError';
+    }
+}
+function withTimeout(p, ms, provider) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError(provider)), ms);
+        p.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+async function safeIsConfigured(adapter) {
+    try {
+        return await adapter.isConfigured();
+    }
+    catch {
+        return false;
+    }
+}
+/** Strip anything that looks like a token/key from an error before it surfaces. */
+function redact(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.replace(/(sk-[A-Za-z0-9_-]{6,})[A-Za-z0-9_-]*/g, '$1…')
+        .replace(/(Bearer\s+)[A-Za-z0-9._-]+/gi, '$1…')
+        .slice(0, 200);
+}

package/dist/server/quota/schemas.d.ts

@@ -0,0 +1,358 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for the normalized quota contract.
+ *
+ * Provider adapter OUTPUT is validated here before it leaves the service,
+ * so the API response (and the Swift client) can always trust the shape.
+ * Validation is tolerant of additive upstream fields — adapters strip those —
+ * but strict on fields used in calculations.
+ */
+export declare const QuotaWindowSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    usedPercent: z.ZodDefault<z.ZodNumber>;
+    remainingPercent: z.ZodDefault<z.ZodNumber>;
+    used: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    durationMins: z.ZodOptional<z.ZodNumber>;
+    resetsAt: z.ZodOptional<z.ZodString>;
+    isUnlimited: z.ZodOptional<z.ZodBoolean>;
+    modelName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    label: string;
+    usedPercent: number;
+    remainingPercent: number;
+    modelName?: string | undefined;
+    used?: number | undefined;
+    limit?: number | undefined;
+    durationMins?: number | undefined;
+    resetsAt?: string | undefined;
+    isUnlimited?: boolean | undefined;
+}, {
+    id: string;
+    label: string;
+    modelName?: string | undefined;
+    usedPercent?: number | undefined;
+    remainingPercent?: number | undefined;
+    used?: number | undefined;
+    limit?: number | undefined;
+    durationMins?: number | undefined;
+    resetsAt?: string | undefined;
+    isUnlimited?: boolean | undefined;
+}>;
+export declare const QuotaProviderStatusSchema: z.ZodObject<{
+    state: z.ZodEnum<["ok", "auth_failed", "not_configured", "upstream_unavailable", "rate_limited", "malformed_response", "timed_out", "error"]>;
+    message: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+    message?: string | undefined;
+    category?: string | undefined;
+}, {
+    state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+    message?: string | undefined;
+    category?: string | undefined;
+}>;
+export declare const QuotaSnapshotSchema: z.ZodObject<{
+    provider: z.ZodEnum<["codex", "claude", "glm", "minimax", "kimi"]>;
+    displayName: z.ZodString;
+    planName: z.ZodOptional<z.ZodString>;
+    fetchedAt: z.ZodString;
+    freshness: z.ZodEnum<["live", "cached", "stale"]>;
+    windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        usedPercent: z.ZodDefault<z.ZodNumber>;
+        remainingPercent: z.ZodDefault<z.ZodNumber>;
+        used: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        durationMins: z.ZodOptional<z.ZodNumber>;
+        resetsAt: z.ZodOptional<z.ZodString>;
+        isUnlimited: z.ZodOptional<z.ZodBoolean>;
+        modelName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        label: string;
+        usedPercent: number;
+        remainingPercent: number;
+        modelName?: string | undefined;
+        used?: number | undefined;
+        limit?: number | undefined;
+        durationMins?: number | undefined;
+        resetsAt?: string | undefined;
+        isUnlimited?: boolean | undefined;
+    }, {
+        id: string;
+        label: string;
+        modelName?: string | undefined;
+        usedPercent?: number | undefined;
+        remainingPercent?: number | undefined;
+        used?: number | undefined;
+        limit?: number | undefined;
+        durationMins?: number | undefined;
+        resetsAt?: string | undefined;
+        isUnlimited?: boolean | undefined;
+    }>, "many">>;
+    status: z.ZodObject<{
+        state: z.ZodEnum<["ok", "auth_failed", "not_configured", "upstream_unavailable", "rate_limited", "malformed_response", "timed_out", "error"]>;
+        message: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+        message?: string | undefined;
+        category?: string | undefined;
+    }, {
+        state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+        message?: string | undefined;
+        category?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+    status: {
+        state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+        message?: string | undefined;
+        category?: string | undefined;
+    };
+    windows: {
+        id: string;
+        label: string;
+        usedPercent: number;
+        remainingPercent: number;
+        modelName?: string | undefined;
+        used?: number | undefined;
+        limit?: number | undefined;
+        durationMins?: number | undefined;
+        resetsAt?: string | undefined;
+        isUnlimited?: boolean | undefined;
+    }[];
+    displayName: string;
+    fetchedAt: string;
+    freshness: "live" | "cached" | "stale";
+    planName?: string | undefined;
+}, {
+    provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+    status: {
+        state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+        message?: string | undefined;
+        category?: string | undefined;
+    };
+    displayName: string;
+    fetchedAt: string;
+    freshness: "live" | "cached" | "stale";
+    windows?: {
+        id: string;
+        label: string;
+        modelName?: string | undefined;
+        usedPercent?: number | undefined;
+        remainingPercent?: number | undefined;
+        used?: number | undefined;
+        limit?: number | undefined;
+        durationMins?: number | undefined;
+        resetsAt?: string | undefined;
+        isUnlimited?: boolean | undefined;
+    }[] | undefined;
+    planName?: string | undefined;
+}>;
+export declare const QuotaResponseSchema: z.ZodObject<{
+    providers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        provider: z.ZodEnum<["codex", "claude", "glm", "minimax", "kimi"]>;
+        displayName: z.ZodString;
+        planName: z.ZodOptional<z.ZodString>;
+        fetchedAt: z.ZodString;
+        freshness: z.ZodEnum<["live", "cached", "stale"]>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            usedPercent: z.ZodDefault<z.ZodNumber>;
+            remainingPercent: z.ZodDefault<z.ZodNumber>;
+            used: z.ZodOptional<z.ZodNumber>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            durationMins: z.ZodOptional<z.ZodNumber>;
+            resetsAt: z.ZodOptional<z.ZodString>;
+            isUnlimited: z.ZodOptional<z.ZodBoolean>;
+            modelName: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            label: string;
+            usedPercent: number;
+            remainingPercent: number;
+            modelName?: string | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }, {
+            id: string;
+            label: string;
+            modelName?: string | undefined;
+            usedPercent?: number | undefined;
+            remainingPercent?: number | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }>, "many">>;
+        status: z.ZodObject<{
+            state: z.ZodEnum<["ok", "auth_failed", "not_configured", "upstream_unavailable", "rate_limited", "malformed_response", "timed_out", "error"]>;
+            message: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        }, {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+        status: {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        };
+        windows: {
+            id: string;
+            label: string;
+            usedPercent: number;
+            remainingPercent: number;
+            modelName?: string | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }[];
+        displayName: string;
+        fetchedAt: string;
+        freshness: "live" | "cached" | "stale";
+        planName?: string | undefined;
+    }, {
+        provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+        status: {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        };
+        displayName: string;
+        fetchedAt: string;
+        freshness: "live" | "cached" | "stale";
+        windows?: {
+            id: string;
+            label: string;
+            modelName?: string | undefined;
+            usedPercent?: number | undefined;
+            remainingPercent?: number | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }[] | undefined;
+        planName?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    providers: {
+        provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+        status: {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        };
+        windows: {
+            id: string;
+            label: string;
+            usedPercent: number;
+            remainingPercent: number;
+            modelName?: string | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }[];
+        displayName: string;
+        fetchedAt: string;
+        freshness: "live" | "cached" | "stale";
+        planName?: string | undefined;
+    }[];
+}, {
+    providers?: {
+        provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+        status: {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        };
+        displayName: string;
+        fetchedAt: string;
+        freshness: "live" | "cached" | "stale";
+        windows?: {
+            id: string;
+            label: string;
+            modelName?: string | undefined;
+            usedPercent?: number | undefined;
+            remainingPercent?: number | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }[] | undefined;
+        planName?: string | undefined;
+    }[] | undefined;
+}>;
+export declare function validateQuotaSnapshot(data: unknown): {
+    provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+    status: {
+        state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+        message?: string | undefined;
+        category?: string | undefined;
+    };
+    windows: {
+        id: string;
+        label: string;
+        usedPercent: number;
+        remainingPercent: number;
+        modelName?: string | undefined;
+        used?: number | undefined;
+        limit?: number | undefined;
+        durationMins?: number | undefined;
+        resetsAt?: string | undefined;
+        isUnlimited?: boolean | undefined;
+    }[];
+    displayName: string;
+    fetchedAt: string;
+    freshness: "live" | "cached" | "stale";
+    planName?: string | undefined;
+};
+export declare function validateQuotaResponse(data: unknown): {
+    providers: {
+        provider: "claude" | "codex" | "glm" | "minimax" | "kimi";
+        status: {
+            state: "ok" | "auth_failed" | "not_configured" | "upstream_unavailable" | "rate_limited" | "malformed_response" | "timed_out" | "error";
+            message?: string | undefined;
+            category?: string | undefined;
+        };
+        windows: {
+            id: string;
+            label: string;
+            usedPercent: number;
+            remainingPercent: number;
+            modelName?: string | undefined;
+            used?: number | undefined;
+            limit?: number | undefined;
+            durationMins?: number | undefined;
+            resetsAt?: string | undefined;
+            isUnlimited?: boolean | undefined;
+        }[];
+        displayName: string;
+        fetchedAt: string;
+        freshness: "live" | "cached" | "stale";
+        planName?: string | undefined;
+    }[];
+};

package/dist/server/quota/schemas.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for the normalized quota contract.
+ *
+ * Provider adapter OUTPUT is validated here before it leaves the service,
+ * so the API response (and the Swift client) can always trust the shape.
+ * Validation is tolerant of additive upstream fields — adapters strip those —
+ * but strict on fields used in calculations.
+ */
+export const QuotaWindowSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    usedPercent: z.number().min(0).max(100).default(0),
+    remainingPercent: z.number().min(0).max(100).default(0),
+    used: z.number().optional(),
+    limit: z.number().optional(),
+    durationMins: z.number().optional(),
+    resetsAt: z.string().optional(),
+    isUnlimited: z.boolean().optional(),
+    modelName: z.string().optional(),
+});
+export const QuotaProviderStatusSchema = z.object({
+    state: z.enum([
+        'ok',
+        'auth_failed',
+        'not_configured',
+        'upstream_unavailable',
+        'rate_limited',
+        'malformed_response',
+        'timed_out',
+        'error',
+    ]),
+    message: z.string().optional(),
+    category: z.string().optional(),
+});
+export const QuotaSnapshotSchema = z.object({
+    provider: z.enum(['codex', 'claude', 'glm', 'minimax', 'kimi']),
+    displayName: z.string(),
+    planName: z.string().optional(),
+    fetchedAt: z.string(),
+    freshness: z.enum(['live', 'cached', 'stale']),
+    windows: z.array(QuotaWindowSchema).default([]),
+    status: QuotaProviderStatusSchema,
+});
+export const QuotaResponseSchema = z.object({
+    providers: z.array(QuotaSnapshotSchema).default([]),
+});
+export function validateQuotaSnapshot(data) {
+    return QuotaSnapshotSchema.parse(data);
+}
+export function validateQuotaResponse(data) {
+    return QuotaResponseSchema.parse(data);
+}

package/dist/server/quota/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Normalized quota domain types.
+ *
+ * These are provider-neutral. Every provider adapter converts its own
+ * heterogeneous response shape into this contract so the rest of the app
+ * never sees provider-specific fields.
+ *
+ * Mirrored on the Swift side by TokenDashSwift/Sources/TokenDash/Models/APIModels.swift.
+ */
+export type QuotaProviderId = 'codex' | 'claude' | 'glm' | 'minimax' | 'kimi';
+/** A normalized snapshot of one provider's current quota state. */
+export interface QuotaSnapshot {
+    /** Stable provider id, e.g. "codex" | "claude" | "glm" | "minimax" | "kimi". */
+    provider: QuotaProviderId;
+    /** Human-facing name, e.g. "OpenAI Codex". */
+    displayName: string;
+    /** Subscription tier when known, e.g. "Pro" | "Plus" | "LEVEL_INTERMEDIATE". */
+    planName?: string;
+    /** ISO 8601 timestamp of the most recent successful fetch. */
+    fetchedAt: string;
+    /** "live" = fresh this cycle, "cached" = within ttl, "stale" = last good after a failure. */
+    freshness: 'live' | 'cached' | 'stale';
+    /** Independent quota windows. Never merged into one synthetic number. */
+    windows: QuotaWindow[];
+    /** Structured status — never carries secrets, only redacted messages. */
+    status: QuotaProviderStatus;
+}
+/** A single independent quota window (e.g. 5-hour, weekly, MCP-monthly). */
+export interface QuotaWindow {
+    /** Stable per-snapshot id, e.g. "five_hour" | "weekly" | "codex_primary". */
+    id: string;
+    /** Human label, e.g. "5-Hour Window" | "Weekly". */
+    label: string;
+    /** Consumed percentage 0-100. */
+    usedPercent: number;
+    /** Remaining percentage 0-100 (100 - usedPercent). */
+    remainingPercent: number;
+    /** Absolute used value when the provider reports one. */
+    used?: number;
+    /** Absolute limit value when the provider reports one. */
+    limit?: number;
+    /** Window length in minutes (300 = 5h, 10080 = 7d). */
+    durationMins?: number;
+    /** ISO 8601 timestamp when this window resets. */
+    resetsAt?: string;
+    /** True for unlimited / boosted windows. */
+    isUnlimited?: boolean;
+    /** Per-model windows (MiniMax returns per-model buckets). */
+    modelName?: string;
+}
+export type QuotaProviderState = 'ok' | 'auth_failed' | 'not_configured' | 'upstream_unavailable' | 'rate_limited' | 'malformed_response' | 'timed_out' | 'error';
+/**
+ * Structured provider status. Flat shape (not a discriminated union) so it
+ * round-trips cleanly through the Zod schema. Adapters populate `message`
+ * only when it carries actionable detail; `state: 'ok'` omits it.
+ */
+export interface QuotaProviderStatus {
+    state: QuotaProviderState;
+    message?: string;
+    category?: string;
+}
+/** Full API response for GET /api/quota — only configured providers appear. */
+export interface QuotaResponse {
+    providers: QuotaSnapshot[];
+}
+/** A credential proposed by the settings UI but not persisted yet. */
+export interface QuotaCredentialInput {
+    apiKey: string;
+    baseUrl?: string;
+}
+/** Result of checking a proposed credential against its upstream provider. */
+export interface QuotaCredentialValidation {
+    provider: QuotaProviderId;
+    valid: boolean;
+    status: QuotaProviderStatus;
+}

package/dist/server/quota/types.js

@@ -0,0 +1,10 @@
+/**
+ * Normalized quota domain types.
+ *
+ * These are provider-neutral. Every provider adapter converts its own
+ * heterogeneous response shape into this contract so the rest of the app
+ * never sees provider-specific fields.
+ *
+ * Mirrored on the Swift side by TokenDashSwift/Sources/TokenDash/Models/APIModels.swift.
+ */
+export {};