dsh-plugin-subscription-usage 0.0.0-stage → 0.2.0

package/lib/translate/sse.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal SSE byte-stream parser (~30 lines of framing): reassembles chunks,
+ * splits CRLF/LF lines, joins multi-`data:` payloads, skips comments and
+ * non-data fields, and dispatches an event only on its blank-line terminator.
+ * An unterminated tail at EOF is truncation and is dropped, matching the
+ * spec-strict framing the harness's own adapters use.
+ */
+/**
+ * Decode an SSE byte stream into events.
+ * @param stream - raw response bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onActivity - called on every received chunk and comment line; drives the idle watchdog.
+ * @returns events in arrival order.
+ */
+export async function* parseSse(stream, onActivity) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    let dataLines = [];
+    let eventName;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            onActivity?.();
+            pending += decoder.decode(value, { stream: true });
+            let newline = pending.indexOf('\n');
+            while (newline >= 0) {
+                let line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                newline = pending.indexOf('\n');
+                if (line.endsWith('\r'))
+                    line = line.slice(0, -1);
+                if (line.length === 0) {
+                    if (dataLines.length > 0) {
+                        yield { data: dataLines.join('\n'), ...eventName === undefined ? {} : { event: eventName } };
+                    }
+                    dataLines = [];
+                    eventName = undefined;
+                }
+                else if (line.startsWith(':')) {
+                    onActivity?.();
+                }
+                else if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).replace(/^ /, ''));
+                }
+                else if (line.startsWith('event:')) {
+                    eventName = line.slice(6).replace(/^ /, '');
+                }
+            }
+        }
+    }
+    finally {
+        // A terminal SSE frame can precede HTTP EOF; returning or decoding failure
+        // must close the remaining body rather than leave the connection reading.
+        try {
+            await reader.cancel();
+        }
+        catch { /* preserve the original stream outcome */ }
+        reader.releaseLock();
+    }
+}

package/lib/usage/headers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plan-usage windows carried on ordinary model responses. Reading them after
+ * every reply keeps meters current without calling the usage endpoints.
+ *
+ * Shapes observed on 2026-11-08 (docs/features/FEAT-001, ASM-002):
+ * - Codex: `x-codex-{primary,secondary}-used-percent` (0..100),
+ *   `-window-minutes`, `-reset-at` (epoch seconds). Sent on 2xx and 429.
+ * - Claude: `anthropic-ratelimit-unified-{5h,7d}-utilization` (0..1),
+ *   `-reset` (epoch seconds).
+ * Only these fields are read; nothing else from the response is kept.
+ */
+import type { UsageWindow } from '../providers/common.js';
+/** Providers whose replies carry usage headers. */
+export type LiveUsageProvider = 'codex' | 'claude';
+/**
+ * Parse the usage windows a reply carries.
+ * @param provider - the provider that answered.
+ * @param headers - the reply headers.
+ * @returns the windows in session-then-weekly order; empty when the reply carries none.
+ */
+export declare function usageWindowsFromHeaders(provider: LiveUsageProvider, headers: Headers): UsageWindow[];

package/lib/usage/headers.js

@@ -0,0 +1,64 @@
+const MINUTE_MS = 60_000;
+const FIVE_HOURS_MS = 5 * 60 * MINUTE_MS;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * MINUTE_MS;
+/** Read a finite number header, or undefined. */
+function numberHeader(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/** Epoch-seconds header to epoch milliseconds. */
+function epochHeader(headers, name) {
+    const seconds = numberHeader(headers, name);
+    return seconds === undefined || seconds <= 0 ? undefined : seconds * 1000;
+}
+/** Kind from a window length, matching the endpoint parsers' session/weekly split. */
+function kindOf(durationMs, fallback) {
+    if (durationMs === undefined)
+        return fallback;
+    if (durationMs <= 24 * 60 * MINUTE_MS)
+        return 'session';
+    if (durationMs <= 8 * 24 * 60 * MINUTE_MS)
+        return 'weekly';
+    return 'other';
+}
+function codexWindow(headers, slot) {
+    const usedPercent = numberHeader(headers, `x-codex-${slot}-used-percent`);
+    if (usedPercent === undefined)
+        return undefined;
+    const minutes = numberHeader(headers, `x-codex-${slot}-window-minutes`);
+    const durationMs = minutes !== undefined && minutes > 0 ? minutes * MINUTE_MS : undefined;
+    const resetsAt = epochHeader(headers, `x-codex-${slot}-reset-at`);
+    return {
+        kind: kindOf(durationMs, slot === 'primary' ? 'session' : 'weekly'),
+        usedPercent,
+        ...durationMs === undefined ? {} : { durationMs },
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
+}
+function claudeWindow(headers, slot) {
+    const utilization = numberHeader(headers, `anthropic-ratelimit-unified-${slot}-utilization`);
+    if (utilization === undefined)
+        return undefined;
+    const resetsAt = epochHeader(headers, `anthropic-ratelimit-unified-${slot}-reset`);
+    return {
+        kind: slot === '5h' ? 'session' : 'weekly',
+        usedPercent: utilization * 100,
+        durationMs: slot === '5h' ? FIVE_HOURS_MS : SEVEN_DAYS_MS,
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
+}
+/**
+ * Parse the usage windows a reply carries.
+ * @param provider - the provider that answered.
+ * @param headers - the reply headers.
+ * @returns the windows in session-then-weekly order; empty when the reply carries none.
+ */
+export function usageWindowsFromHeaders(provider, headers) {
+    const windows = provider === 'codex'
+        ? [codexWindow(headers, 'primary'), codexWindow(headers, 'secondary')]
+        : [claudeWindow(headers, '5h'), claudeWindow(headers, '7d')];
+    return windows.filter(window => window !== undefined);
+}

package/lib/usage/pace.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pace of one usage window: how much quota is used against how much of the
+ * window has elapsed, and whether the current rate empties the window before
+ * it resets. Pure, so the Host and the browser bundle share one definition.
+ */
+import type { UsageWindow } from '../providers/common.js';
+/** Below this share of elapsed window a burst says little about the whole window. */
+export declare const MIN_FORECAST_ELAPSED = 0.2;
+/** Below this usage the projection is noise. */
+export declare const MIN_FORECAST_USED_PERCENT = 3;
+/** Projected use above this percent turns a window `tight`. */
+export declare const TIGHT_PROJECTED_PERCENT = 85;
+/** Pace of one window. `calm` and `tight` may carry a projection; `over` always does. */
+export type Pace = {
+    state: 'unknown';
+} | {
+    state: 'out';
+    usedPercent: number;
+} | {
+    state: 'calm';
+    usedPercent: number;
+    elapsed?: number;
+    projectedPercent?: number;
+} | {
+    state: 'tight';
+    usedPercent: number;
+    elapsed: number;
+    projectedPercent: number;
+} | {
+    state: 'over';
+    usedPercent: number;
+    elapsed: number;
+    projectedPercent: number;
+    emptyAt: number;
+};
+/** The states a meter colors by. */
+export type PaceState = Pace['state'];
+/**
+ * Compute the pace of one window at `now`.
+ * @param window - the provider-reported window.
+ * @param now - epoch milliseconds.
+ * @returns the pace; `elapsed` is the share of the window passed, 0 to 1.
+ */
+export declare function pace(window: UsageWindow, now: number): Pace;
+/** Whether quota reads as remaining or as consumed. Display only; routing reads `usedPercent`. */
+export type QuotaDisplay = 'left' | 'used';
+/**
+ * The percent a meter shows.
+ * @param window - the window to show.
+ * @param display - left or used.
+ * @returns an integer percent, or undefined when the provider reported none.
+ */
+export declare function displayPercent(window: UsageWindow, display: QuotaDisplay): number | undefined;

package/lib/usage/pace.js

@@ -0,0 +1,48 @@
+/** Below this share of elapsed window a burst says little about the whole window. */
+export const MIN_FORECAST_ELAPSED = 0.2;
+/** Below this usage the projection is noise. */
+export const MIN_FORECAST_USED_PERCENT = 3;
+/** Projected use above this percent turns a window `tight`. */
+export const TIGHT_PROJECTED_PERCENT = 85;
+/**
+ * Compute the pace of one window at `now`.
+ * @param window - the provider-reported window.
+ * @param now - epoch milliseconds.
+ * @returns the pace; `elapsed` is the share of the window passed, 0 to 1.
+ */
+export function pace(window, now) {
+    const used = window.usedPercent;
+    if (!Number.isFinite(used))
+        return { state: 'unknown' };
+    const usedPercent = Math.max(0, Math.min(100, used));
+    if (usedPercent >= 100)
+        return { state: 'out', usedPercent };
+    const { durationMs, resetsAt } = window;
+    if (durationMs === undefined || resetsAt === undefined || !(durationMs > 0) || !Number.isFinite(resetsAt)) {
+        return { state: 'calm', usedPercent };
+    }
+    const elapsed = Math.min(1, Math.max(0, 1 - (resetsAt - now) / durationMs));
+    if (elapsed < MIN_FORECAST_ELAPSED || usedPercent < MIN_FORECAST_USED_PERCENT) {
+        return { state: 'calm', usedPercent, elapsed };
+    }
+    const projectedPercent = usedPercent / elapsed;
+    if (projectedPercent > 100) {
+        const ratePerMs = usedPercent / (elapsed * durationMs);
+        return { state: 'over', usedPercent, elapsed, projectedPercent, emptyAt: now + (100 - usedPercent) / ratePerMs };
+    }
+    if (projectedPercent > TIGHT_PROJECTED_PERCENT)
+        return { state: 'tight', usedPercent, elapsed, projectedPercent };
+    return { state: 'calm', usedPercent, elapsed, projectedPercent };
+}
+/**
+ * The percent a meter shows.
+ * @param window - the window to show.
+ * @param display - left or used.
+ * @returns an integer percent, or undefined when the provider reported none.
+ */
+export function displayPercent(window, display) {
+    if (!Number.isFinite(window.usedPercent))
+        return undefined;
+    const used = Math.round(Math.max(0, Math.min(100, window.usedPercent)));
+    return display === 'left' ? 100 - used : used;
+}

package/lib/usage/service.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Display-side usage reads with a refresh policy per reason, live ingestion
+ * from model replies, and the account that served each session.
+ *
+ * Routing and display share one {@link PoolUsageTracker}, so its negative
+ * cache guards the provider usage endpoints for both.
+ */
+import type { UsageProviderId } from '../usage-providers/index.js';
+import type { ProviderUsage } from '../providers/common.js';
+import type { PoolUsageTracker } from '../providers/pool-usage.js';
+/** Why the Client is reading usage; each reason has its own staleness bound. */
+export type UsageReadReason = 'poll' | 'open' | 'manual';
+/** Opening the popover refetches only snapshots older than this. */
+export declare const OPEN_REFRESH_AFTER_MS = 60000;
+/** A manual refresh of one account fetches at most once in this period. */
+export declare const MANUAL_REFRESH_COOLDOWN_MS = 30000;
+/** A usage snapshot as the Client sees it. */
+export type DisplayUsage = ProviderUsage & {
+    /** `live` when the latest data came from a model reply rather than the usage endpoint. */
+    source?: 'live' | 'endpoint';
+    /** Epoch ms before which another manual refresh returns the cached snapshot. */
+    manualReadyAt?: number;
+};
+/** The account that served a request, and when. */
+export interface ServedAccount {
+    account: string;
+    at: number;
+}
+export interface UsageServiceOptions {
+    tracker: PoolUsageTracker;
+    /** Whether a provider has a usage endpoint at all. */
+    hasEndpoint: (provider: UsageProviderId) => boolean;
+    /** Runs before a manual refresh fetches, so a stale routing cooldown does not outlive the user's retry. */
+    onManualRefresh?: (provider: UsageProviderId, account: string) => void;
+    now?: () => number;
+}
+/** Usage reads and live ingestion for the Client surfaces. */
+export declare class UsageService {
+    private readonly options;
+    private readonly lastManual;
+    private readonly live;
+    private readonly servedBySession;
+    private readonly servedByProvider;
+    private readonly now;
+    /** Bumped whenever a snapshot or serving account changes, so the Client knows to re-read. */
+    revision: number;
+    constructor(options: UsageServiceOptions);
+    /**
+     * Read one account's usage under the policy for `reason`.
+     * A failure cooldown is never bypassed (the tracker answers from its negative cache).
+     */
+    read(provider: UsageProviderId, account: string, reason: UsageReadReason): Promise<DisplayUsage>;
+    /**
+     * Record one model reply: its usage headers and the account that served it.
+     * @returns whether usage changed.
+     */
+    observe(provider: UsageProviderId, account: string, sessionId: string | undefined, headers: Headers): boolean;
+    /** The account that last served `provider`: in this session when known, else anywhere. */
+    servedAccount(provider: UsageProviderId, sessionId?: string): ServedAccount | undefined;
+    /** Forget an account after logout. */
+    forget(provider: UsageProviderId, account?: string): void;
+    private ageOf;
+    private decorate;
+}

package/lib/usage/service.js

@@ -0,0 +1,104 @@
+import { usageWindowsFromHeaders } from './headers.js';
+/** Opening the popover refetches only snapshots older than this. */
+export const OPEN_REFRESH_AFTER_MS = 60_000;
+/** A manual refresh of one account fetches at most once in this period. */
+export const MANUAL_REFRESH_COOLDOWN_MS = 30_000;
+/** Usage reads and live ingestion for the Client surfaces. */
+export class UsageService {
+    options;
+    lastManual = new Map();
+    live = new Set();
+    servedBySession = new Map();
+    servedByProvider = new Map();
+    now;
+    /** Bumped whenever a snapshot or serving account changes, so the Client knows to re-read. */
+    revision = 0;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Read one account's usage under the policy for `reason`.
+     * A failure cooldown is never bypassed (the tracker answers from its negative cache).
+     */
+    async read(provider, account, reason) {
+        if (!this.options.hasEndpoint(provider))
+            return { supported: false };
+        const key = `${provider}/${account}`;
+        const age = this.ageOf(provider, account);
+        let force = false;
+        if (reason === 'open')
+            force = age === undefined || age > OPEN_REFRESH_AFTER_MS;
+        if (reason === 'manual') {
+            const last = this.lastManual.get(key);
+            if (last === undefined || this.now() - last >= MANUAL_REFRESH_COOLDOWN_MS) {
+                force = true;
+                this.lastManual.set(key, this.now());
+                this.options.onManualRefresh?.(provider, account);
+            }
+        }
+        const before = this.options.tracker.fetchedAt(provider, account);
+        const snapshot = await this.options.tracker.displaySnapshotFor(provider, account, force);
+        const after = this.options.tracker.fetchedAt(provider, account);
+        if (after !== before) {
+            this.live.delete(key);
+            this.revision++;
+        }
+        return this.decorate(provider, account, snapshot);
+    }
+    /**
+     * Record one model reply: its usage headers and the account that served it.
+     * @returns whether usage changed.
+     */
+    observe(provider, account, sessionId, headers) {
+        const at = this.now();
+        const served = { account, at };
+        this.servedByProvider.set(provider, served);
+        if (sessionId !== undefined) {
+            const bySession = this.servedBySession.get(sessionId) ?? new Map();
+            bySession.set(provider, served);
+            this.servedBySession.set(sessionId, bySession);
+        }
+        this.revision++;
+        if (provider !== 'codex' && provider !== 'claude')
+            return false;
+        const windows = usageWindowsFromHeaders(provider, headers);
+        if (this.options.tracker.ingest(provider, account, windows, at) === undefined)
+            return false;
+        this.live.add(`${provider}/${account}`);
+        return true;
+    }
+    /** The account that last served `provider`: in this session when known, else anywhere. */
+    servedAccount(provider, sessionId) {
+        return (sessionId === undefined ? undefined : this.servedBySession.get(sessionId)?.get(provider))
+            ?? this.servedByProvider.get(provider);
+    }
+    /** Forget an account after logout. */
+    forget(provider, account) {
+        for (const key of [...this.live])
+            if (key === `${provider}/${account}` || (account === undefined && key.startsWith(`${provider}/`)))
+                this.live.delete(key);
+        const served = this.servedByProvider.get(provider);
+        if (served !== undefined && (account === undefined || served.account === account))
+            this.servedByProvider.delete(provider);
+        for (const bySession of this.servedBySession.values()) {
+            const entry = bySession.get(provider);
+            if (entry !== undefined && (account === undefined || entry.account === account))
+                bySession.delete(provider);
+        }
+        this.revision++;
+    }
+    ageOf(provider, account) {
+        const at = this.options.tracker.fetchedAt(provider, account);
+        return at === undefined || !Number.isFinite(at) ? undefined : this.now() - at;
+    }
+    decorate(provider, account, snapshot) {
+        const key = `${provider}/${account}`;
+        const last = this.lastManual.get(key);
+        return {
+            ...snapshot,
+            source: this.live.has(key) ? 'live' : 'endpoint',
+            ...last === undefined ? {} : { manualReadyAt: last + MANUAL_REFRESH_COOLDOWN_MS },
+        };
+    }
+}

package/lib/usage-providers/common.d.ts

@@ -0,0 +1,23 @@
+/** Helpers shared by the API key usage providers. */
+import type { FetchFn } from '../providers/common.js';
+import type { ProviderUsage } from '../providers/common.js';
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const finite: (value: unknown) => number | undefined;
+/** An epoch in seconds or milliseconds, or an ISO date string, as epoch milliseconds. */
+export declare function timestamp(value: unknown): number | undefined;
+export declare const clampPercent: (value: number) => number;
+/** One key provider: how to read usage with an API key. */
+export interface KeyProvider {
+    id: KeyProviderId;
+    name: string;
+    /** @throws with a message that never contains the key. */
+    fetchUsage(key: string, fetchFn: FetchFn, signal: AbortSignal): Promise<ProviderUsage>;
+}
+/** Ids of the providers that read usage with a pasted API key. */
+export declare const KEY_PROVIDER_IDS: readonly ["zai", "ollama-cloud", "kimi"];
+export type KeyProviderId = (typeof KEY_PROVIDER_IDS)[number];
+export declare const isKeyProviderId: (value: unknown) => value is KeyProviderId;
+export declare class KeyRejectedError extends Error {
+}
+/** GET or POST one JSON endpoint with a bearer key. */
+export declare function bearerJson(name: string, url: string, key: string, fetchFn: FetchFn, signal: AbortSignal, method?: 'GET' | 'POST'): Promise<unknown>;

package/lib/usage-providers/common.js

@@ -0,0 +1,28 @@
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const finite = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/** An epoch in seconds or milliseconds, or an ISO date string, as epoch milliseconds. */
+export function timestamp(value) {
+    const number = finite(value);
+    if (number !== undefined)
+        return number < 1_000_000_000_000 ? number * 1000 : number;
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+export const clampPercent = (value) => Math.min(100, Math.max(0, value));
+/** Ids of the providers that read usage with a pasted API key. */
+export const KEY_PROVIDER_IDS = ['zai', 'ollama-cloud', 'kimi'];
+export const isKeyProviderId = (value) => typeof value === 'string' && KEY_PROVIDER_IDS.includes(value);
+export class KeyRejectedError extends Error {
+}
+/** GET or POST one JSON endpoint with a bearer key. */
+export async function bearerJson(name, url, key, fetchFn, signal, method = 'GET') {
+    const response = await fetchFn(url, { method, headers: { authorization: `Bearer ${key}`, accept: 'application/json' }, signal });
+    if (response.status === 401 || response.status === 403)
+        throw new KeyRejectedError(`${name} rejected the key (HTTP ${response.status})`);
+    if (!response.ok)
+        throw new Error(`${name} returned HTTP ${response.status}`);
+    return response.json();
+}

package/lib/usage-providers/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Usage providers read with a pasted API key. They are separate from the
+ * OAuth `ProviderId` set, which drives login, model routing and the pool.
+ */
+import type { FetchFn, ProviderUsage } from '../providers/common.js';
+import { isKeyProviderId, KEY_PROVIDER_IDS } from './common.js';
+import type { KeyProviderId } from './common.js';
+import { KeyStore } from './keys.js';
+import type { ProviderId } from '../auth/store.js';
+export { isKeyProviderId, KEY_PROVIDER_IDS };
+/** Anything the Usage page can read: an OAuth provider or a key provider. */
+export type UsageProviderId = ProviderId | KeyProviderId;
+export type { KeyProviderId };
+/** The only account a key provider has. */
+export declare const KEY_ACCOUNT = "key";
+/** One key provider as `status` reports it. */
+export interface KeyProviderView {
+    id: KeyProviderId;
+    name: string;
+    configured: boolean;
+    /** Last four characters of the key, for recognition. */
+    tail?: string;
+}
+export declare class KeyUsage {
+    private readonly store;
+    private readonly fetchFn;
+    private readonly onChanged;
+    /** Providers with a stored key; kept in memory so the tracker can look up a fetcher synchronously. */
+    private readonly configured;
+    constructor(store: KeyStore, fetchFn: FetchFn, onChanged: (id: KeyProviderId) => void);
+    /** Load the stored keys once at startup. */
+    load(): Promise<void>;
+    has(id: KeyProviderId): boolean;
+    list(): Promise<KeyProviderView[]>;
+    /** Read usage with the stored key; the tracker polls this. */
+    fetchStored(id: KeyProviderId): Promise<ProviderUsage>;
+    /** Check the key with one usage read, then store it. A bad key stores nothing. */
+    set(id: KeyProviderId, key: string): Promise<void>;
+    remove(id: KeyProviderId): Promise<void>;
+    private fetch;
+}
+export { KeyStore };

package/lib/usage-providers/index.js

@@ -0,0 +1,71 @@
+import { isKeyProviderId, KEY_PROVIDER_IDS } from './common.js';
+import { KeyStore } from './keys.js';
+import { kimi } from './kimi.js';
+import { ollamaCloud } from './ollama-cloud.js';
+import { zai } from './zai.js';
+export { isKeyProviderId, KEY_PROVIDER_IDS };
+const PROVIDERS = { zai, 'ollama-cloud': ollamaCloud, kimi };
+/** The only account a key provider has. */
+export const KEY_ACCOUNT = 'key';
+const KEY_TIMEOUT_MS = 20_000;
+export class KeyUsage {
+    store;
+    fetchFn;
+    onChanged;
+    /** Providers with a stored key; kept in memory so the tracker can look up a fetcher synchronously. */
+    configured = new Set();
+    constructor(store, fetchFn, onChanged) {
+        this.store = store;
+        this.fetchFn = fetchFn;
+        this.onChanged = onChanged;
+    }
+    /** Load the stored keys once at startup. */
+    async load() {
+        this.configured.clear();
+        for (const id of Object.keys(await this.store.read()))
+            if (isKeyProviderId(id))
+                this.configured.add(id);
+    }
+    has(id) {
+        return this.configured.has(id);
+    }
+    async list() {
+        const keys = await this.store.read();
+        return KEY_PROVIDER_IDS.map(id => {
+            const key = keys[id];
+            return { id, name: PROVIDERS[id].name, configured: key !== undefined, ...key === undefined ? {} : { tail: key.slice(-4) } };
+        });
+    }
+    /** Read usage with the stored key; the tracker polls this. */
+    async fetchStored(id) {
+        const key = (await this.store.read())[id];
+        if (key === undefined)
+            throw new Error('No key is stored');
+        return this.fetch(id, key);
+    }
+    /** Check the key with one usage read, then store it. A bad key stores nothing. */
+    async set(id, key) {
+        const trimmed = key.trim();
+        if (trimmed === '')
+            throw new Error('The key is empty');
+        await this.fetch(id, trimmed);
+        await this.store.set(id, trimmed);
+        this.configured.add(id);
+        this.onChanged(id);
+    }
+    async remove(id) {
+        await this.store.remove(id);
+        this.configured.delete(id);
+        this.onChanged(id);
+    }
+    async fetch(id, key) {
+        try {
+            return await PROVIDERS[id].fetchUsage(key, this.fetchFn, AbortSignal.timeout(KEY_TIMEOUT_MS));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(message.split(key).join('…'));
+        }
+    }
+}
+export { KeyStore };

package/lib/usage-providers/keys.d.ts

@@ -0,0 +1,11 @@
+import type { KeyProviderId } from './common.js';
+export type KeyMap = Partial<Record<KeyProviderId, string>>;
+export declare const defaultKeyPath: () => string;
+export declare class KeyStore {
+    private readonly path;
+    constructor(path?: string);
+    read(): Promise<KeyMap>;
+    set(id: KeyProviderId, key: string): Promise<void>;
+    remove(id: KeyProviderId): Promise<void>;
+    private write;
+}

package/lib/usage-providers/keys.js

@@ -0,0 +1,52 @@
+/** The API key store at `~/.dsh/plugins/subscriptions/usage-keys.json`, owner-only. */
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { isKeyProviderId, isRecord } from './common.js';
+export const defaultKeyPath = () => dshHomePath('plugins', 'subscriptions', 'usage-keys.json');
+export class KeyStore {
+    path;
+    constructor(path = defaultKeyPath()) {
+        this.path = path;
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return {};
+            throw error;
+        }
+        const parsed = JSON.parse(text);
+        const keys = {};
+        if (isRecord(parsed)) {
+            for (const [id, value] of Object.entries(parsed)) {
+                if (isKeyProviderId(id) && typeof value === 'string' && value !== '')
+                    keys[id] = value;
+            }
+        }
+        return keys;
+    }
+    async set(id, key) {
+        await this.write({ ...await this.read(), [id]: key });
+    }
+    async remove(id) {
+        const { [id]: _removed, ...rest } = await this.read();
+        await this.write(rest);
+    }
+    async write(keys) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+        try {
+            await writeFile(tmp, JSON.stringify(keys, null, 2), { mode: 0o600 });
+            await chmod(tmp, 0o600);
+            await rename(tmp, this.path);
+        }
+        catch (error) {
+            await rm(tmp, { force: true });
+            throw error;
+        }
+    }
+}

package/lib/usage-providers/kimi.d.ts

@@ -0,0 +1,4 @@
+import type { UsageWindow } from '../providers/common.js';
+import type { KeyProvider } from './common.js';
+export declare function parseKimiUsage(payload: unknown): UsageWindow[];
+export declare const kimi: KeyProvider;