@zhangferry-dev/tokendash 1.6.1 → 1.7.0

package/dist/server/quota/adapters/kimi.js

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { readStoredCredential } from '../credentialsFile.js';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { QuotaError, baseSnapshot } from '../adapter.js';
+import { fetchJsonWithTimeout, HttpError, classifyHttpError, windowFromCounts } from '../helpers.js';
+/**
+ * Kimi Code adapter.
+ *
+ * Source: `GET https://api.kimi.com/coding/v1/usages`, Bearer auth with the
+ * OAuth token stored by the Kimi CLI at ~/.kimi/credentials/kimi-code.json.
+ * Returns a primary weekly `usage` block plus an arbitrary-length `limits[]`
+ * array of windows (e.g. a 5-hour rolling window).
+ *
+ * Token lifetime is ~1h, so we refresh it from auth.kimi.com before it
+ * expires and persist the new tokens back to the same file (the Kimi CLI
+ * reads the same file, so both stay in sync).
+ */
+const KIMI_CLIENT_ID = '17e5f671-d194-4dfb-9706-5516cb48c098';
+const KIMI_BASE = 'https://api.kimi.com/coding/v1';
+const KIMI_AUTH = 'https://auth.kimi.com/api/oauth/token';
+export const kimiAdapter = {
+    provider: 'kimi',
+    displayName: 'Kimi Code',
+    async isConfigured() {
+        const cred = readCredentials();
+        return !!cred && !!cred.access_token;
+    },
+    async fetch(options) {
+        const credPath = credentialsPath();
+        let cred = options?.credential?.apiKey
+            ? { access_token: options.credential.apiKey, token_type: 'Bearer' }
+            : readCredentials();
+        if (!cred || !cred.access_token) {
+            throw new QuotaError({ state: 'not_configured', message: 'run `kimi` to log in first' });
+        }
+        // Refresh proactively if within 5 min of expiry.
+        const nowSec = Math.floor(Date.now() / 1000);
+        if (cred.expires_at && cred.expires_at - nowSec < 300 && cred.refresh_token) {
+            cred = await refreshToken(credPath, cred.refresh_token).catch(() => cred);
+        }
+        let data;
+        try {
+            data = (await fetchJsonWithTimeout(`${KIMI_BASE}/usages`, {
+                headers: {
+                    Authorization: `Bearer ${cred.access_token}`,
+                    Accept: 'application/json',
+                },
+            }));
+        }
+        catch (err) {
+            throw classifyFetchError(err);
+        }
+        const windows = [];
+        // Primary weekly usage.
+        if (data.usage) {
+            const { used, limit } = toCounts(data.usage);
+            if (limit > 0) {
+                windows.push(windowFromCounts('kimi_weekly', 'Weekly', used, limit, {
+                    durationMins: 10080,
+                    resetsAt: normalizeIso(data.usage.resetTime),
+                }));
+            }
+        }
+        // Arbitrary-length limits[] (e.g. 5-hour rolling window).
+        for (let i = 0; i < (data.limits?.length ?? 0); i++) {
+            const entry = data.limits[i];
+            const detail = entry?.detail;
+            if (!detail)
+                continue;
+            const { used, limit } = toCounts(detail);
+            if (limit <= 0)
+                continue;
+            const mins = minutesForWindow(entry?.window);
+            windows.push(windowFromCounts(`kimi_limit_${i}`, mins ? `${durationLabel(mins)} Window` : `Window ${i + 1}`, used, limit, {
+                durationMins: mins,
+                resetsAt: normalizeIso(detail.resetTime),
+            }));
+        }
+        const snap = baseSnapshot('kimi', 'Kimi Code', {
+            planName: data.user?.membership?.level ? prettifyLevel(data.user.membership.level) : undefined,
+            windows,
+        });
+        return { ...snap, status: { state: 'ok' } };
+    },
+};
+function classifyFetchError(err) {
+    if (err instanceof HttpError) {
+        const c = classifyHttpError(err);
+        return new QuotaError(c);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return new QuotaError({ state: 'upstream_unavailable', message: msg.slice(0, 200) });
+}
+/** Kimi returns limit/remaining as STRINGS — coerce and invert to used. */
+function toCounts(detail) {
+    const limit = toNumber(detail.limit);
+    const remaining = toNumber(detail.remaining);
+    if (limit <= 0)
+        return { used: 0, limit: 0 };
+    return { used: Math.max(0, limit - remaining), limit };
+}
+function toNumber(v) {
+    if (v === undefined || v === null)
+        return 0;
+    const n = typeof v === 'string' ? parseFloat(v) : v;
+    return Number.isFinite(n) ? n : 0;
+}
+function minutesForWindow(window) {
+    if (!window?.duration)
+        return undefined;
+    const unit = (window.timeUnit || '').toUpperCase();
+    if (unit.includes('HOUR'))
+        return window.duration * 60;
+    if (unit.includes('DAY'))
+        return window.duration * 1440;
+    return window.duration; // default minutes
+}
+function durationLabel(mins) {
+    if (mins >= 10080)
+        return 'Weekly';
+    if (mins >= 1440)
+        return `${Math.round(mins / 1440)}-Day`;
+    if (mins >= 60)
+        return `${Math.round(mins / 60)}-Hour`;
+    return `${mins}m`;
+}
+function normalizeIso(s) {
+    return s ? new Date(s).toISOString() : undefined;
+}
+function prettifyLevel(level) {
+    // "LEVEL_INTERMEDIATE" -> "Intermediate"
+    return level.replace(/^LEVEL_/, '').toLowerCase().replace(/(^|_)(\w)/g, (_, __, c) => ' ' + c.toUpperCase()).trim();
+}
+function kimiDataDir() {
+    return process.env.KIMI_DATA_DIR || join(homedir(), '.kimi');
+}
+function credentialsPath() {
+    return join(kimiDataDir(), 'credentials', 'kimi-code.json');
+}
+function readCredentials() {
+    // 0. Token entered in-app (via the credential sheet) — highest priority.
+    // Treated as a bare access token; no refresh token, so it's used as-is.
+    const stored = readStoredCredential('kimi');
+    if (stored?.apiKey) {
+        return { access_token: stored.apiKey, token_type: 'Bearer' };
+    }
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function refreshToken(credPath, refreshToken) {
+    const body = new URLSearchParams({
+        client_id: KIMI_CLIENT_ID,
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+    });
+    const res = await fetch(KIMI_AUTH, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body,
+    });
+    if (!res.ok)
+        throw new Error(`token refresh failed: HTTP ${res.status}`);
+    const tokens = (await res.json());
+    const updated = {
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token || refreshToken,
+        expires_at: Math.floor(Date.now() / 1000) + (tokens.expires_in ?? 3600),
+        token_type: tokens.token_type || 'Bearer',
+    };
+    // Persist back so the Kimi CLI and this adapter share the refreshed token.
+    try {
+        writeFileSync(credPath, JSON.stringify(updated, null, 2), 'utf8');
+    }
+    catch {
+        // Best-effort; the in-memory token still works for this request.
+    }
+    return updated;
+}

package/dist/server/quota/adapters/minimax.d.ts

@@ -0,0 +1,2 @@
+import type { QuotaAdapter } from '../adapter.js';
+export declare const minimaxAdapter: QuotaAdapter;

package/dist/server/quota/adapters/minimax.js

@@ -0,0 +1,82 @@
+import { QuotaError, baseSnapshot } from '../adapter.js';
+import { fetchJsonWithTimeout, HttpError, classifyHttpError, windowFromCounts, unixToIso } from '../helpers.js';
+import { readStoredCredential } from '../credentialsFile.js';
+export const minimaxAdapter = {
+    provider: 'minimax',
+    displayName: 'MiniMax Coding Plan',
+    async isConfigured() {
+        return !!resolveCredential();
+    },
+    async fetch(options) {
+        const cred = resolveCredential(options?.credential);
+        if (!cred) {
+            throw new QuotaError({ state: 'not_configured', message: 'set MINIMAX_API_KEY (Subscription Key)' });
+        }
+        let data;
+        try {
+            data = (await fetchJsonWithTimeout(`${cred.base}/v1/token_plan/remains`, {
+                headers: {
+                    Authorization: `Bearer ${cred.key}`,
+                    'Content-Type': 'application/json',
+                },
+            }));
+        }
+        catch (err) {
+            throw classifyFetchError(err);
+        }
+        if (data.base_resp?.status_code && data.base_resp.status_code !== 0) {
+            throw new QuotaError({
+                state: 'upstream_unavailable',
+                message: data.base_resp.status_msg || `MiniMax error ${data.base_resp.status_code}`,
+            });
+        }
+        const windows = [];
+        for (const m of data.model_remains ?? []) {
+            const model = m.model_name ?? 'MiniMax';
+            const intervalTotal = m.current_interval_total_count ?? 0;
+            const intervalRemaining = m.current_interval_usage_count ?? 0;
+            // used = total - remaining (the "*_usage_count" fields are misnamed).
+            if (intervalTotal > 0) {
+                windows.push(windowFromCounts(`minimax_5h_${model}`, `5-Hour · ${model}`, Math.max(0, intervalTotal - intervalRemaining), intervalTotal, { durationMins: 300, resetsAt: unixToIso(m.end_time) }));
+            }
+            const weeklyTotal = m.current_weekly_total_count ?? 0;
+            const weeklyRemaining = m.current_weekly_usage_count ?? 0;
+            if (weeklyTotal > 0) {
+                windows.push(windowFromCounts(`minimax_weekly_${model}`, `Weekly · ${model}`, Math.max(0, weeklyTotal - weeklyRemaining), weeklyTotal, { durationMins: 10080 }));
+            }
+        }
+        const snap = baseSnapshot('minimax', 'MiniMax Coding Plan', { windows });
+        return { ...snap, status: { state: 'ok' } };
+    },
+};
+function classifyFetchError(err) {
+    if (err instanceof HttpError) {
+        const c = classifyHttpError(err);
+        return new QuotaError(c);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return new QuotaError({ state: 'upstream_unavailable', message: msg.slice(0, 200) });
+}
+function resolveCredential(proposed) {
+    if (proposed?.apiKey) {
+        const region = (process.env.MINIMAX_REGION || '').toLowerCase();
+        const base = proposed.baseUrl || (region === 'cn' ? 'https://www.minimaxi.com' : 'https://www.minimax.io');
+        return { key: proposed.apiKey, base };
+    }
+    // 0. Key entered in-app (via the credential sheet) — highest priority.
+    const stored = readStoredCredential('minimax');
+    if (stored) {
+        const region = (process.env.MINIMAX_REGION || '').toLowerCase();
+        const base = stored.baseUrl || (region === 'cn' ? 'https://www.minimaxi.com' : 'https://www.minimax.io');
+        return { key: stored.apiKey, base };
+    }
+    const key = process.env.MINIMAX_API_KEY || process.env.MINIMAX_SUBSCRIPTION_KEY;
+    if (!key)
+        return null;
+    // minimax.io = global, minimaxi.com = China.
+    const region = (process.env.MINIMAX_REGION || '').toLowerCase();
+    const base = region === 'cn'
+        ? (process.env.MINIMAX_BASE_URL || 'https://www.minimaxi.com')
+        : (process.env.MINIMAX_BASE_URL || 'https://www.minimax.io');
+    return { key, base };
+}

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

@@ -0,0 +1,20 @@
+import type { QuotaSnapshot } from './types.js';
+/**
+ * Per-provider quota cache.
+ *
+ * Keeps the last successful snapshot so a transient refresh failure returns
+ * stale-but-useful data (marked freshness "stale") instead of erasing it.
+ * The cache is in-memory only — quota snapshots are live and short-lived,
+ * so disk persistence (unlike the usage cache) adds no value.
+ */
+export declare class QuotaCache {
+    private readonly ttlMs;
+    private readonly store;
+    constructor(ttlMs?: number);
+    /** Fresh cached snapshot, or null if expired / absent. */
+    getFresh(provider: string): QuotaSnapshot | null;
+    /** Last successful snapshot regardless of TTL (for stale-while-revalidate). */
+    getStale(provider: string): QuotaSnapshot | null;
+    set(snapshot: QuotaSnapshot): void;
+    clear(provider?: string): void;
+}

package/dist/server/quota/cache.js

@@ -0,0 +1,44 @@
+/**
+ * Per-provider quota cache.
+ *
+ * Keeps the last successful snapshot so a transient refresh failure returns
+ * stale-but-useful data (marked freshness "stale") instead of erasing it.
+ * The cache is in-memory only — quota snapshots are live and short-lived,
+ * so disk persistence (unlike the usage cache) adds no value.
+ */
+export class QuotaCache {
+    ttlMs;
+    store = new Map();
+    constructor(ttlMs = 60_000) {
+        this.ttlMs = ttlMs;
+    }
+    /** Fresh cached snapshot, or null if expired / absent. */
+    getFresh(provider) {
+        const entry = this.store.get(provider);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt)
+            return null;
+        return { ...entry.snapshot, freshness: 'cached' };
+    }
+    /** Last successful snapshot regardless of TTL (for stale-while-revalidate). */
+    getStale(provider) {
+        const entry = this.store.get(provider);
+        if (!entry)
+            return null;
+        return { ...entry.snapshot, freshness: 'stale' };
+    }
+    set(snapshot) {
+        this.store.set(snapshot.provider, {
+            snapshot,
+            expiresAt: Date.now() + this.ttlMs,
+            updatedAt: Date.now(),
+        });
+    }
+    clear(provider) {
+        if (provider)
+            this.store.delete(provider);
+        else
+            this.store.clear();
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Reads the cross-process credential bridge file written by the Swift app's
+ * CredentialSheet (~/.tokendash/credentials.json). Adapters check this FIRST —
+ * before env vars and settings.json — so a key entered in-app wins.
+ *
+ * Read fresh on each call (no cache) so a credential saved via the sheet takes
+ * effect on the very next quota refresh. The file is tiny, so the cost is nil.
+ */
+export interface StoredCredential {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare function readStoredCredential(provider: string): StoredCredential | null;

package/dist/server/quota/credentialsFile.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export function readStoredCredential(provider) {
+    try {
+        const path = join(homedir(), '.tokendash', 'credentials.json');
+        if (!existsSync(path))
+            return null;
+        const all = JSON.parse(readFileSync(path, 'utf8'));
+        const entry = all?.[provider];
+        if (entry && typeof entry === 'object' && typeof entry.apiKey === 'string') {
+            const apiKey = entry.apiKey;
+            if (!apiKey)
+                return null;
+            const baseUrl = entry.baseUrl;
+            return { apiKey, baseUrl: typeof baseUrl === 'string' ? baseUrl : undefined };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { QuotaWindow } from './types.js';
+/** Shared helpers for provider adapters. */
+/** Convert a Unix timestamp (seconds or ms) to ISO 8601, or undefined. */
+export declare function unixToIso(unix: number | string | null | undefined): string | undefined;
+/** Clamp a percentage to 0-100. */
+export declare function clampPercent(v: number): number;
+/** Build a QuotaWindow from used/limit percentages. */
+export declare function windowFromPercent(id: string, label: string, usedPercent: number, opts?: {
+    durationMins?: number;
+    resetsAt?: string;
+    used?: number;
+    limit?: number;
+    modelName?: string;
+    isUnlimited?: boolean;
+}): QuotaWindow;
+/** Build a QuotaWindow from absolute used/limit counts. */
+export declare function windowFromCounts(id: string, label: string, used: number, limit: number, opts?: {
+    durationMins?: number;
+    resetsAt?: string;
+    modelName?: string;
+}): QuotaWindow;
+/**
+ * Fetch JSON with a timeout. Adapters that hit HTTP APIs use this so they
+ * share redaction + abort behavior. Returns parsed JSON or throws.
+ */
+export declare function fetchJsonWithTimeout(url: string, opts?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<unknown>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/** Map an HTTP status to a coarse auth/upstream classification. */
+export declare function classifyHttpError(err: HttpError): {
+    state: 'auth_failed' | 'rate_limited' | 'upstream_unavailable';
+    message: string;
+};

package/dist/server/quota/helpers.js

@@ -0,0 +1,93 @@
+/** Shared helpers for provider adapters. */
+/** Convert a Unix timestamp (seconds or ms) to ISO 8601, or undefined. */
+export function unixToIso(unix) {
+    if (unix === null || unix === undefined || unix === '')
+        return undefined;
+    const n = typeof unix === 'string' ? parseInt(unix, 10) : unix;
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    // Codex/MiniMax use seconds or ms; disambiguate by magnitude.
+    const ms = n > 1e12 ? n : n * 1000;
+    return new Date(ms).toISOString();
+}
+/** Clamp a percentage to 0-100. */
+export function clampPercent(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    return Math.max(0, Math.min(100, v));
+}
+/** Round to 1 decimal place so 61.1999... → 61.2, integers unchanged. */
+function round1(v) {
+    return Math.round(v * 10) / 10;
+}
+/** Build a QuotaWindow from used/limit percentages. */
+export function windowFromPercent(id, label, usedPercent, opts = {}) {
+    const used = round1(clampPercent(usedPercent));
+    return {
+        id,
+        label,
+        usedPercent: used,
+        remainingPercent: round1(100 - used),
+        durationMins: opts.durationMins,
+        resetsAt: opts.resetsAt,
+        used: opts.used,
+        limit: opts.limit,
+        modelName: opts.modelName,
+        isUnlimited: opts.isUnlimited,
+    };
+}
+/** Build a QuotaWindow from absolute used/limit counts. */
+export function windowFromCounts(id, label, used, limit, opts = {}) {
+    if (limit <= 0) {
+        return { id, label, usedPercent: 0, remainingPercent: 100, used, limit, isUnlimited: true, ...opts };
+    }
+    const pct = round1(clampPercent((used / limit) * 100));
+    return {
+        id,
+        label,
+        usedPercent: pct,
+        remainingPercent: round1(100 - pct),
+        used,
+        limit,
+        ...opts,
+    };
+}
+/**
+ * Fetch JSON with a timeout. Adapters that hit HTTP APIs use this so they
+ * share redaction + abort behavior. Returns parsed JSON or throws.
+ */
+export async function fetchJsonWithTimeout(url, opts = {}) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 8_000);
+    try {
+        const res = await fetch(url, { headers: opts.headers, signal: ctrl.signal });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new HttpError(res.status, body.slice(0, 200));
+        }
+        return await res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'HttpError';
+    }
+}
+/** Map an HTTP status to a coarse auth/upstream classification. */
+export function classifyHttpError(err) {
+    if (err.status === 401 || err.status === 403) {
+        return { state: 'auth_failed', message: 'credential rejected by provider' };
+    }
+    if (err.status === 429) {
+        return { state: 'rate_limited', message: 'provider throttled the request' };
+    }
+    return { state: 'upstream_unavailable', message: `provider returned HTTP ${err.status}` };
+}

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

@@ -0,0 +1,5 @@
+import { QuotaCache } from './cache.js';
+import { QuotaService } from './quotaService.js';
+export type { QuotaCredentialInput, QuotaCredentialValidation, QuotaSnapshot, QuotaWindow, QuotaProviderStatus, QuotaResponse, QuotaProviderId, } from './types.js';
+export declare const quotaCache: QuotaCache;
+export declare const quotaService: QuotaService;

package/dist/server/quota/index.js

@@ -0,0 +1,23 @@
+/**
+ * Quota module entry point.
+ *
+ * Builds the singleton adapter registry + service. The rest of the server
+ * imports `quotaService` from here; adapters are wired in registration order,
+ * which becomes the dashboard display order.
+ */
+import { QuotaAdapterRegistry } from './adapter.js';
+import { QuotaCache } from './cache.js';
+import { QuotaService } from './quotaService.js';
+import { codexAdapter } from './adapters/codex.js';
+import { claudeAdapter } from './adapters/claude.js';
+import { glmAdapter } from './adapters/glm.js';
+import { minimaxAdapter } from './adapters/minimax.js';
+import { kimiAdapter } from './adapters/kimi.js';
+const registry = new QuotaAdapterRegistry();
+registry.register(claudeAdapter);
+registry.register(codexAdapter);
+registry.register(glmAdapter);
+registry.register(minimaxAdapter);
+registry.register(kimiAdapter);
+export const quotaCache = new QuotaCache();
+export const quotaService = new QuotaService(registry, quotaCache);

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

@@ -0,0 +1,43 @@
+import type { QuotaCredentialInput, QuotaCredentialValidation, QuotaSnapshot, QuotaProviderId, QuotaResponse } from './types.js';
+import type { QuotaAdapterRegistry } from './adapter.js';
+import { QuotaCache } from './cache.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 declare class QuotaService {
+    private readonly registry;
+    private readonly cache;
+    private readonly configuredCache;
+    /** Cap concurrent upstream calls so a slow provider can't block the others. */
+    private readonly fetchTimeoutMs;
+    /** In-flight promises keyed by provider id, to dedupe concurrent requests. */
+    private readonly inflight;
+    constructor(registry: QuotaAdapterRegistry, cache?: QuotaCache, configuredCache?: QuotaProviderId[] | null, fetchTimeoutMs?: number);
+    /**
+     * List provider ids that are configured locally. Cheap (no network).
+     * The dashboard only shows these — not-configured providers are excluded.
+     */
+    discover(): Promise<QuotaProviderId[]>;
+    /**
+     * Fetch one provider's snapshot. Fresh if available; stale-but-retained
+     * on failure; never throws (errors become structured statuses).
+     */
+    fetchOne(provider: QuotaProviderId): Promise<QuotaSnapshot | null>;
+    /**
+     * Fetch all configured providers concurrently. Partial success: one
+     * provider's failure never breaks the others. Order = registry order.
+     */
+    fetchAll(): Promise<QuotaResponse>;
+    /** Force a refresh of all configured providers, bypassing the cache. */
+    refreshAll(): Promise<QuotaResponse>;
+    /**
+     * 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.
+     */
+    validateCredential(provider: QuotaProviderId, credential: QuotaCredentialInput): Promise<QuotaCredentialValidation>;
+    private fetchWithTimeout;
+    private handleFailure;
+}