@zhangferry-dev/tokendash 1.6.0 → 1.6.2

package/dist/server/daemon.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TokenDash Daemon — headless Node.js server for the Swift menu bar app.
+ *
+ * Usage: node dist/daemon.cjs [--port <number>]
+ *
+ * The Swift app spawns this process and manages its lifecycle.
+ * Communication happens via:
+ *   - ~/.tokendash/daemon.pid  — PID file (for process management)
+ *   - ~/.tokendash/daemon.port — actual listening port (for Swift discovery)
+ *   - localhost HTTP API       — all existing /api/* routes
+ */
+export {};

package/dist/server/daemon.js

@@ -0,0 +1,176 @@
+/**
+ * TokenDash Daemon — headless Node.js server for the Swift menu bar app.
+ *
+ * Usage: node dist/daemon.cjs [--port <number>]
+ *
+ * The Swift app spawns this process and manages its lifecycle.
+ * Communication happens via:
+ *   - ~/.tokendash/daemon.pid  — PID file (for process management)
+ *   - ~/.tokendash/daemon.port — actual listening port (for Swift discovery)
+ *   - localhost HTTP API       — all existing /api/* routes
+ */
+import { createApp } from './index.js';
+import http from 'node:http';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const DATA_DIR = join(homedir(), '.tokendash');
+const PID_FILE = join(DATA_DIR, 'daemon.pid');
+const PORT_FILE = join(DATA_DIR, 'daemon.port');
+function ensureDataDir() {
+    if (!existsSync(DATA_DIR))
+        mkdirSync(DATA_DIR, { recursive: true });
+}
+function writePidFile() {
+    ensureDataDir();
+    writeFileSync(PID_FILE, String(process.pid), 'utf8');
+}
+function writePortFile(port) {
+    ensureDataDir();
+    writeFileSync(PORT_FILE, String(port), 'utf8');
+}
+function cleanupFiles() {
+    try {
+        if (existsSync(PID_FILE))
+            unlinkSync(PID_FILE);
+    }
+    catch (_) { }
+    try {
+        if (existsSync(PORT_FILE))
+            unlinkSync(PORT_FILE);
+    }
+    catch (_) { }
+}
+// ---------------------------------------------------------------------------
+// Port fallback
+// ---------------------------------------------------------------------------
+function resolvePort() {
+    const args = process.argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--port' && i + 1 < args.length) {
+            const v = parseInt(args[i + 1], 10);
+            if (Number.isInteger(v) && v > 0)
+                return v;
+        }
+    }
+    const envPort = process.env.TOKENDASH_PORT ? parseInt(process.env.TOKENDASH_PORT, 10) : 0;
+    if (Number.isInteger(envPort) && envPort > 0)
+        return envPort;
+    return 3456;
+}
+function listen(app, port) {
+    return new Promise((resolve, reject) => {
+        const server = app.listen(port);
+        const onListen = () => { cleanup(); resolve(server); };
+        const onError = (err) => { cleanup(); reject(err); };
+        const cleanup = () => { server.off('listening', onListen); server.off('error', onError); };
+        server.once('listening', onListen);
+        server.once('error', onError);
+    });
+}
+async function listenWithFallback(app, preferredPort) {
+    let port = preferredPort;
+    for (let attempt = 0; attempt < 20; attempt++, port++) {
+        try {
+            const server = await listen(app, port);
+            return { server, port };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new Error(`No available port starting from ${preferredPort}`);
+}
+// ---------------------------------------------------------------------------
+// Stale daemon check
+// ---------------------------------------------------------------------------
+function killStaleDaemon() {
+    if (!existsSync(PID_FILE))
+        return false;
+    try {
+        const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        // Send SIGTERM to stale process (throws if PID doesn't exist)
+        process.kill(pid, 0); // check if alive
+        // Process exists — try to kill it
+        process.kill(pid, 'SIGTERM');
+        // Give it a moment
+        const deadline = Date.now() + 2000;
+        while (Date.now() < deadline) {
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                break;
+            }
+        }
+        return true;
+    }
+    catch {
+        // Process doesn't exist — stale PID file
+        cleanupFiles();
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    // Kill any stale daemon
+    killStaleDaemon();
+    const preferredPort = resolvePort();
+    const distDir = join(import.meta.url.replace('file://', ''), '..');
+    const app = createApp(preferredPort, distDir);
+    const { server, port } = await listenWithFallback(app, preferredPort);
+    writePidFile();
+    writePortFile(port);
+    // Warm up cache: pre-parse JSONL for all agents so first Swift fetch is fast
+    try {
+        const agentsRes = await new Promise((resolve, reject) => {
+            http.get(`http://127.0.0.1:${port}/api/agents`, (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk; });
+                res.on('end', () => { try {
+                    resolve(JSON.parse(body));
+                }
+                catch (e) {
+                    reject(e);
+                } });
+            }).on('error', reject);
+        });
+        const agents = agentsRes?.available ?? ['claude'];
+        await Promise.all(agents.map((agent) => new Promise((resolve) => {
+            http.get(`http://127.0.0.1:${port}/api/daily?agent=${agent}`, (res) => {
+                res.resume();
+                res.on('end', () => resolve());
+            }).on('error', () => resolve());
+        })));
+    }
+    catch (_) {
+        // Warm-up is best-effort; don't block startup
+    }
+    // Graceful shutdown
+    const shutdown = () => {
+        cleanupFiles();
+        server.close(() => process.exit(0));
+        // Force exit after 5s if server.close hangs
+        setTimeout(() => process.exit(0), 5000);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('uncaughtException', (err) => {
+        console.error('[tokendash-daemon] uncaught:', err);
+        shutdown();
+    });
+}
+main().catch((err) => {
+    console.error('[tokendash-daemon] fatal:', err);
+    cleanupFiles();
+    process.exit(1);
+});

package/dist/server/index.js

@@ -4,7 +4,6 @@ import { fileURLToPath } from 'node:url';
 import { basename, dirname, join, resolve } from 'node:path';
 import { registerApiRoutes } from './routes/api.js';
 import { detectAvailableAgents } from './agentDetection.js';
-import open from 'open';
 const CLI_USAGE = [
     'Usage:',
     '  tokendash',
@@ -12,11 +11,22 @@ const CLI_USAGE = [
     '  tokendash --port <number> [--no-open]',
     '  tokendash --tray [--port <number>]',
 ].join('\n');
+const PACKAGE_NAME = '@zhangferry-dev/tokendash';
 function getPackageVersion() {
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
-    const packageJson = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
-    return packageJson.version ?? 'unknown';
+    const packageJsonPaths = [
+        join(__dirname, '..', '..', 'package.json'), // dist/server/index.js
+        join(__dirname, '..', 'package.json'), // bundled server entrypoint
+    ];
+    for (const packageJsonPath of packageJsonPaths) {
+        if (!existsSync(packageJsonPath))
+            continue;
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        if (packageJson.version)
+            return packageJson.version;
+    }
+    return 'unknown';
 }
 function exitWithCliError(message) {
     console.error(message);
@@ -127,7 +137,7 @@ export function resolveStaticAssetBaseDir(moduleUrl = import.meta.url, baseDir)
     // The CLI entrypoint runs from dist/server/index.js while the Vite assets are
     // emitted to dist/client. Resolve the production asset base to dist instead
     // of dist/server so / resolves to dist/client/index.html in installed npm
-    // packages. Electron passes dist explicitly and is unaffected by this branch.
+    // packages. The native app passes dist explicitly and is unaffected by this branch.
     if (basename(moduleDir) === 'server') {
         return { baseDir: resolve(dirname(moduleDir)), isProduction: true };
     }
@@ -137,7 +147,11 @@ export function createApp(_port, baseDir) {
     const app = express();
     const router = express.Router();
     // Register API routes
-    registerApiRoutes(router);
+    registerApiRoutes(router, {
+        packageName: PACKAGE_NAME,
+        version: getPackageVersion(),
+        dashboardUrl: `http://localhost:${resolvePort(_port)}`,
+    });
     app.use('/api', router);
     const { baseDir: _baseDir, isProduction } = resolveStaticAssetBaseDir(import.meta.url, baseDir);
     const popoverPath = isProduction
@@ -171,21 +185,29 @@ async function main() {
     }
     const version = getPackageVersion();
     const preferredPort = resolvePort(args.port ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : undefined));
-    // --tray mode: launch Electron
+    // --tray mode: launch native Swift menu bar app
     if (args.tray) {
         if (process.platform !== 'darwin') {
             console.error('Error: --tray is only supported on macOS.');
             process.exit(1);
         }
         console.log(`Starting tokendash v${version} in tray mode...`);
-        // @ts-ignore -- electron is installed separately for tray mode
-        const { default: electronPath } = await import('electron');
         const { spawn } = await import('node:child_process');
-        const child = spawn(electronPath, ['.'], {
+        const { resolve } = await import('node:path');
+        const { existsSync } = await import('node:fs');
+        // Find Swift binary: check packaged app first, then dev build
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        const packagedPath = resolve(moduleDir, '..', '..', 'TokenDashSwift', '.build', 'debug', 'TokenDash');
+        const devPath = resolve(moduleDir, '..', '..', 'TokenDashSwift', '.build', 'debug', 'TokenDash');
+        const swiftBin = existsSync(packagedPath) ? packagedPath : devPath;
+        if (!existsSync(swiftBin)) {
+            console.error('Error: TokenDash Swift binary not found. Run "npm run build:swift" first.');
+            process.exit(1);
+        }
+        const child = spawn(swiftBin, [], {
             env: {
                 ...process.env,
                 TOKENDASH_PORT: String(preferredPort),
-                TOKENDASH_TRAY: '1',
             },
             stdio: 'inherit',
         });
@@ -217,11 +239,15 @@ async function main() {
     // Open browser if requested
     if (shouldOpenBrowser) {
         // Small delay to ensure server is ready
-        setTimeout(() => {
+        setTimeout(async () => {
             console.log('Opening dashboard in your browser...');
-            open(`http://localhost:${port}`).catch((err) => {
+            try {
+                const { default: open } = await import('open');
+                await open(`http://localhost:${port}`);
+            }
+            catch (err) {
                 console.warn('Could not open browser:', err.message);
-            });
+            }
         }, 100);
     }
     else {

package/dist/server/insightsCalculator.d.ts

@@ -0,0 +1,15 @@
+import type { DailyEntry, DriverMetric, InsightsResponse, ProjectsResponse } from '../shared/types.js';
+export declare function cacheHitRate(cacheReadTokens: number, inputTokens: number): number;
+export declare function outputInputRatio(outputTokens: number, inputTokens: number): number;
+export interface BuildInsightsOptions {
+    agent: string;
+    project?: string;
+    timezone?: string;
+    daily: DailyEntry[];
+    projects?: ProjectsResponse;
+    topAgent?: DriverMetric;
+    partialAgents?: string[];
+    now?: Date;
+}
+export declare function buildInsightsResponse(options: BuildInsightsOptions): InsightsResponse;
+export declare function mergeDailyResponsesByDate(responses: DailyEntry[][]): DailyEntry[];

package/dist/server/insightsCalculator.js

@@ -0,0 +1,276 @@
+const MIN_BASELINE_ACTIVE_DAYS = 3;
+const BASELINE_ACTIVE_DAYS = 7;
+const MAX_INSIGHTS = 5;
+export function cacheHitRate(cacheReadTokens, inputTokens) {
+    const totalInput = cacheReadTokens + inputTokens;
+    if (totalInput === 0)
+        return 0;
+    return (cacheReadTokens / totalInput) * 100;
+}
+export function outputInputRatio(outputTokens, inputTokens) {
+    if (inputTokens === 0)
+        return 0;
+    return outputTokens / inputTokens;
+}
+function localTodayKey(now = new Date()) {
+    return [
+        now.getFullYear(),
+        String(now.getMonth() + 1).padStart(2, '0'),
+        String(now.getDate()).padStart(2, '0'),
+    ].join('-');
+}
+function emptyDaily(date) {
+    return {
+        date,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        totalTokens: 0,
+        totalCost: 0,
+        modelsUsed: [],
+        modelBreakdowns: [],
+    };
+}
+function mergeEntries(date, entries) {
+    const merged = emptyDaily(date);
+    const models = new Map();
+    for (const entry of entries) {
+        merged.inputTokens += entry.inputTokens;
+        merged.outputTokens += entry.outputTokens;
+        merged.cacheCreationTokens += entry.cacheCreationTokens;
+        merged.cacheReadTokens += entry.cacheReadTokens;
+        merged.totalTokens += entry.totalTokens;
+        merged.totalCost += entry.totalCost;
+        for (const model of entry.modelBreakdowns) {
+            const existing = models.get(model.modelName);
+            if (existing) {
+                existing.inputTokens += model.inputTokens;
+                existing.outputTokens += model.outputTokens;
+                existing.cacheCreationTokens += model.cacheCreationTokens;
+                existing.cacheReadTokens += model.cacheReadTokens;
+                existing.cost += model.cost;
+            }
+            else {
+                models.set(model.modelName, { ...model });
+            }
+        }
+    }
+    merged.modelBreakdowns = [...models.values()];
+    merged.modelsUsed = [...new Set(merged.modelBreakdowns.map(model => model.modelName))];
+    return merged;
+}
+function activeBaselineEntries(daily, today) {
+    return daily
+        .filter(entry => entry.date < today && entry.totalTokens > 0)
+        .sort((a, b) => b.date.localeCompare(a.date))
+        .slice(0, BASELINE_ACTIVE_DAYS);
+}
+function average(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function baselineFrom(entries) {
+    return {
+        activeDays: entries.length,
+        avgTokens: average(entries.map(entry => entry.totalTokens)),
+        avgCost: average(entries.map(entry => entry.totalCost)),
+        avgCacheHitRate: average(entries.map(entry => cacheHitRate(entry.cacheReadTokens, entry.inputTokens))),
+        avgOutputInputRatio: average(entries.map(entry => outputInputRatio(entry.outputTokens, entry.inputTokens))),
+        insufficientData: entries.length < MIN_BASELINE_ACTIVE_DAYS,
+    };
+}
+function driverFromProject(today, projects) {
+    if (!projects)
+        return undefined;
+    const drivers = Object.entries(projects.projects)
+        .map(([name, entries]) => {
+        const todayEntry = mergeEntries(today, entries.filter(entry => entry.date === today));
+        return { name, tokens: todayEntry.totalTokens, cost: todayEntry.totalCost };
+    })
+        .filter(driver => driver.tokens > 0 || driver.cost > 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    const totalTokens = drivers.reduce((sum, driver) => sum + driver.tokens, 0);
+    const top = drivers[0];
+    if (!top || totalTokens === 0)
+        return undefined;
+    return { ...top, share: top.tokens / totalTokens };
+}
+function driverFromModel(todayEntry) {
+    const totalTokens = todayEntry.totalTokens;
+    if (todayEntry.modelBreakdowns.length === 0 || totalTokens === 0)
+        return undefined;
+    const drivers = todayEntry.modelBreakdowns
+        .map(model => ({
+        name: model.modelName,
+        tokens: model.inputTokens + model.outputTokens + model.cacheCreationTokens + model.cacheReadTokens,
+        cost: model.cost,
+    }))
+        .sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
+    const top = drivers[0];
+    if (!top)
+        return undefined;
+    const totalCost = todayEntry.totalCost;
+    const share = totalCost > 0 ? top.cost / totalCost : top.tokens / totalTokens;
+    return { ...top, share };
+}
+function deltaPercent(current, baseline) {
+    if (baseline <= 0)
+        return undefined;
+    return ((current - baseline) / baseline) * 100;
+}
+function addInsight(insights, insight) {
+    if (insight)
+        insights.push(insight);
+}
+function severityRank(severity) {
+    if (severity === 'critical')
+        return 0;
+    if (severity === 'warning')
+        return 1;
+    return 2;
+}
+function sortInsights(insights) {
+    return insights
+        .sort((a, b) => {
+        const severity = severityRank(a.severity) - severityRank(b.severity);
+        if (severity !== 0)
+            return severity;
+        return Math.abs(b.deltaPercent ?? 0) - Math.abs(a.deltaPercent ?? 0);
+    })
+        .slice(0, MAX_INSIGHTS);
+}
+export function buildInsightsResponse(options) {
+    const today = localTodayKey(options.now);
+    const todayEntry = mergeEntries(today, options.daily.filter(entry => entry.date === today));
+    const baselineEntries = activeBaselineEntries(options.daily, today);
+    const baseline = baselineFrom(baselineEntries);
+    const todayCacheHitRate = cacheHitRate(todayEntry.cacheReadTokens, todayEntry.inputTokens);
+    const todayOutputInputRatio = outputInputRatio(todayEntry.outputTokens, todayEntry.inputTokens);
+    const topProject = options.project ? undefined : driverFromProject(today, options.projects);
+    const topModel = driverFromModel(todayEntry);
+    const topDrivers = {
+        ...(topProject ? { project: topProject } : {}),
+        ...(topModel ? { model: topModel } : {}),
+        ...(options.topAgent ? { agent: options.topAgent } : {}),
+    };
+    const insights = [];
+    const tokenDelta = deltaPercent(todayEntry.totalTokens, baseline.avgTokens);
+    const costDelta = deltaPercent(todayEntry.totalCost, baseline.avgCost);
+    const ratioDelta = deltaPercent(todayOutputInputRatio, baseline.avgOutputInputRatio);
+    const isNewHigh = todayEntry.totalTokens > 0 && options.daily
+        .filter(entry => entry.date <= today)
+        .sort((a, b) => b.totalTokens - a.totalTokens)[0]?.date === today;
+    if (!baseline.insufficientData) {
+        addInsight(insights, todayEntry.totalTokens >= baseline.avgTokens * 2 && todayEntry.totalTokens - baseline.avgTokens >= 100_000 && {
+            id: 'token-spike',
+            severity: 'warning',
+            title: `Today is ${Math.round(tokenDelta ?? 0)}% above your 7-day average`,
+            detail: 'Token usage is materially above your recent active-day baseline.',
+            metric: 'tokens',
+            currentValue: todayEntry.totalTokens,
+            baselineValue: baseline.avgTokens,
+            deltaPercent: tokenDelta,
+        });
+        addInsight(insights, todayEntry.totalCost >= baseline.avgCost * 2 && todayEntry.totalCost - baseline.avgCost >= 1 && {
+            id: 'cost-spike',
+            severity: 'warning',
+            title: `Today cost is ${Math.round(costDelta ?? 0)}% above baseline`,
+            detail: 'Estimated spend is materially above your recent active-day baseline.',
+            metric: 'cost',
+            currentValue: todayEntry.totalCost,
+            baselineValue: baseline.avgCost,
+            deltaPercent: costDelta,
+        });
+        addInsight(insights, baseline.avgCacheHitRate - todayCacheHitRate >= 20 && {
+            id: 'cache-drop',
+            severity: 'warning',
+            title: `Cache hit dropped to ${todayCacheHitRate.toFixed(1)}%`,
+            detail: `Recent baseline is ${baseline.avgCacheHitRate.toFixed(1)}%. Context reuse may be lower than usual.`,
+            metric: 'cache',
+            currentValue: todayCacheHitRate,
+            baselineValue: baseline.avgCacheHitRate,
+            deltaPercent: todayCacheHitRate - baseline.avgCacheHitRate,
+        });
+        addInsight(insights, todayOutputInputRatio >= baseline.avgOutputInputRatio * 2 && todayEntry.outputTokens >= 25_000 && {
+            id: 'output-heavy',
+            severity: 'info',
+            title: `Output/input ratio is ${todayOutputInputRatio.toFixed(1)}x`,
+            detail: 'Today is more output-heavy than your recent baseline.',
+            metric: 'ratio',
+            currentValue: todayOutputInputRatio,
+            baselineValue: baseline.avgOutputInputRatio,
+            deltaPercent: ratioDelta,
+        });
+    }
+    addInsight(insights, todayCacheHitRate < 50 && todayEntry.inputTokens >= 50_000 && {
+        id: 'low-cache',
+        severity: 'info',
+        title: `Cache hit is low at ${todayCacheHitRate.toFixed(1)}%`,
+        detail: 'Low cache reuse can raise cost when input volume is high.',
+        metric: 'cache',
+        currentValue: todayCacheHitRate,
+        baselineValue: baseline.insufficientData ? undefined : baseline.avgCacheHitRate,
+    });
+    addInsight(insights, topProject && topProject.share >= 0.5 && {
+        id: 'large-project-driver',
+        severity: 'info',
+        title: `${topProject.name} drives ${Math.round(topProject.share * 100)}% of today's tokens`,
+        detail: 'One project explains most of today’s scoped usage.',
+        metric: 'project',
+        currentValue: topProject.share * 100,
+        driver: topProject,
+    });
+    addInsight(insights, topModel && topModel.share >= 0.5 && {
+        id: 'large-model-driver',
+        severity: 'info',
+        title: `${topModel.name} drives ${Math.round(topModel.share * 100)}% of today’s ${todayEntry.totalCost > 0 ? 'cost' : 'tokens'}`,
+        detail: 'One model explains most of today’s scoped usage.',
+        metric: 'model',
+        currentValue: topModel.share * 100,
+        driver: topModel,
+    });
+    addInsight(insights, isNewHigh && {
+        id: 'new-high',
+        severity: !baseline.insufficientData && todayEntry.totalTokens >= baseline.avgTokens * 2 ? 'critical' : 'info',
+        title: 'Today is the highest day in the last 30 days',
+        detail: baseline.insufficientData ? 'There is not enough baseline data yet, but today is currently the highest observed day.' : 'Today is the highest observed day in the current local history window.',
+        metric: 'tokens',
+        currentValue: todayEntry.totalTokens,
+        baselineValue: baseline.insufficientData ? undefined : baseline.avgTokens,
+        deltaPercent: tokenDelta,
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        scope: {
+            agent: options.agent,
+            ...(options.project ? { project: options.project } : {}),
+            timezone: options.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+            partialAgents: options.partialAgents ?? [],
+        },
+        today: {
+            date: today,
+            totalTokens: todayEntry.totalTokens,
+            totalCost: todayEntry.totalCost,
+            cacheHitRate: todayCacheHitRate,
+            outputInputRatio: todayOutputInputRatio,
+        },
+        baseline,
+        topDrivers,
+        insights: sortInsights(insights),
+    };
+}
+export function mergeDailyResponsesByDate(responses) {
+    const byDate = new Map();
+    for (const daily of responses) {
+        for (const entry of daily) {
+            const entries = byDate.get(entry.date) ?? [];
+            entries.push(entry);
+            byDate.set(entry.date, entries);
+        }
+    }
+    return [...byDate.entries()]
+        .map(([date, entries]) => mergeEntries(date, entries))
+        .sort((a, b) => a.date.localeCompare(b.date));
+}

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

@@ -0,0 +1,47 @@
+import type { QuotaProviderId, QuotaSnapshot, QuotaProviderStatus } from './types.js';
+/**
+ * Structured quota error. Adapters throw this (not generic Error) so the
+ * service can classify the status without inspecting message strings.
+ * Messages must never contain secrets — they reach the API response.
+ */
+export declare class QuotaError extends Error {
+    readonly status: QuotaProviderStatus;
+    constructor(status: QuotaProviderStatus);
+}
+/**
+ * One provider adapter. Responsible only for:
+ *   1. detecting whether the provider is configured (credentials present)
+ *   2. invoking the upstream interface
+ *   3. validating the response
+ *   4. converting to a normalized snapshot
+ *
+ * It does NOT cache, deduplicate, or time out — the service owns those.
+ * Detecting a provider as configured means it appears in the dashboard;
+ * fetch() may still fail with an auth/error status.
+ */
+export interface QuotaAdapter {
+    readonly provider: QuotaProviderId;
+    readonly displayName: string;
+    /** True when credentials/config exist for this provider locally. Cheap, no network. */
+    isConfigured(): Promise<boolean>;
+    /**
+     * Fetch a fresh normalized snapshot. Throws QuotaError on any failure.
+     * Must NOT include secrets in any field of the returned snapshot.
+     */
+    fetch(): Promise<QuotaSnapshot>;
+}
+/**
+ * Registry of all known adapters, keyed by provider id.
+ * Adding a quota provider = ship one adapter + register it here.
+ */
+export declare class QuotaAdapterRegistry {
+    private readonly adapters;
+    register(adapter: QuotaAdapter): void;
+    get(provider: QuotaProviderId): QuotaAdapter | undefined;
+    list(): QuotaAdapter[];
+}
+/** Build a baseline snapshot with shared fields filled in. */
+export declare function baseSnapshot(provider: QuotaProviderId, displayName: string, opts?: {
+    planName?: string;
+    windows?: QuotaSnapshot['windows'];
+}): Pick<QuotaSnapshot, 'provider' | 'displayName' | 'planName' | 'fetchedAt' | 'freshness' | 'windows'>;

package/dist/server/quota/adapter.js

@@ -0,0 +1,41 @@
+/**
+ * Structured quota error. Adapters throw this (not generic Error) so the
+ * service can classify the status without inspecting message strings.
+ * Messages must never contain secrets — they reach the API response.
+ */
+export class QuotaError extends Error {
+    status;
+    constructor(status) {
+        const msg = 'message' in status && status.message ? status.message : '';
+        super(msg ? `${status.state}: ${msg}` : status.state);
+        this.name = 'QuotaError';
+        this.status = status;
+    }
+}
+/**
+ * Registry of all known adapters, keyed by provider id.
+ * Adding a quota provider = ship one adapter + register it here.
+ */
+export class QuotaAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        this.adapters.set(adapter.provider, adapter);
+    }
+    get(provider) {
+        return this.adapters.get(provider);
+    }
+    list() {
+        return Array.from(this.adapters.values());
+    }
+}
+/** Build a baseline snapshot with shared fields filled in. */
+export function baseSnapshot(provider, displayName, opts = {}) {
+    return {
+        provider,
+        displayName,
+        planName: opts.planName,
+        fetchedAt: new Date().toISOString(),
+        freshness: 'live',
+        windows: opts.windows ?? [],
+    };
+}

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

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