@maci0/dsh-quota-check 0.12.2

package/lib/types/host.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * The plugin installs from outside the harness checkout and has no runtime
+ * dependency on harness packages: the services it reaches are typed here, and
+ * a composition that mounts none of them simply omits that capability. The
+ * same shape also lets the unit tests drive `apply` with a plain fake context.
+ *
+ * @module dsh-quota-check/host
+ */
+/** Disposer returned by every host registration. */
+export type Disposable = () => void;
+/** One registered settings namespace, as `describe()` reports it. */
+export interface SettingsDescriptorLike {
+    /** Registered namespace name, e.g. `llm-pi-ai`. */
+    readonly ns: string;
+    /** Current resolved value: schema defaults, then base, then the user layer. */
+    readonly value: unknown;
+}
+/** One configurable provider route, as the LLM registry declares it. */
+export interface ConfigurableProviderLike {
+    /** Route id the model picker shows, e.g. `zai`. */
+    readonly provider: string;
+    /** Display name for the provider, when it declares one. */
+    readonly displayName?: string;
+    /** Settings namespace holding this route's profile. */
+    readonly settingsNs: string;
+    /** Path inside that namespace's value to this route's profile. */
+    readonly settingsPath: readonly string[];
+}
+/** The slice of the LLM registry this plugin reads. */
+export interface LlmRegistryLike {
+    /**
+     * List every declared configurable provider, registered or dormant.
+     * @returns detached directory entries in declaration order.
+     */
+    listConfigurableProviders(): readonly ConfigurableProviderLike[];
+}
+/** The slice of the credentials service this plugin reads. */
+export interface CredentialsLike {
+    /**
+     * Resolve one credential reference to its value.
+     * @param ref - environment-variable-style reference name.
+     * @returns the resolved value, or `undefined` when nothing is stored.
+     */
+    resolve(ref: string): Promise<{
+        readonly value: string;
+    } | undefined>;
+}
+/** Request subset the trust fence reads. */
+export interface RequestLike {
+    /** Request method, uppercased by the caller. */
+    readonly method?: string | undefined;
+    /** Request target, including the query string. */
+    readonly url?: string | undefined;
+    /** Request headers, read by the composition's trust fence. */
+    readonly headers: object | undefined;
+}
+/** Response subset this plugin writes. */
+export interface ResponseLike {
+    /** HTTP status code. */
+    statusCode: number;
+    /** Set one response header. */
+    setHeader(name: string, value: string): void;
+    /** End the response, optionally with a body. */
+    end(body?: string): void;
+}
+/** One exact-path route registration. */
+export interface WebRouteLike {
+    /** Match kind; this plugin registers only exact paths. */
+    readonly kind: 'exact';
+    /** Absolute pathname, no trailing slash. */
+    readonly path: string;
+    /** Owns the full response lifecycle. */
+    handler: (req: RequestLike, res: ResponseLike) => void | Promise<void>;
+}
+/** The slice of the HTTP carrier this plugin registers on. */
+export interface WebServerLike {
+    /**
+     * Register one route.
+     * @param route - path, match kind, and handler.
+     * @returns the disposer that withdraws it.
+     */
+    register(route: WebRouteLike): Disposable;
+}
+/** The composition's trust fence. */
+export interface ConnectionLike {
+    /**
+     * Reject an untrusted or unauthenticated request.
+     * @param request - headers of the incoming request.
+     * @returns the rejection status, or `undefined` when the request may proceed.
+     */
+    requestRejection(request: {
+        readonly headers: object | undefined;
+    }): 401 | 403 | undefined;
+}
+/**
+ * Structural view of the Cordis context the host half uses.
+ *
+ * `inject` guarantees `webServer` and `connection`; everything else is
+ * optional and read through `get`, so a composition without the settings,
+ * credentials, or LLM seam degrades to "no figure to report" instead of
+ * failing to mount.
+ */
+export interface HostContext {
+    /** Bind a registration's lifetime to this plugin's fiber. */
+    effect(callback: () => Disposable | void, label?: string): unknown;
+    /**
+     * Subscribe to a host event. This plugin watches `loader/volatile-update`,
+     * which is what a settings write emits once the live row references moved.
+     * @param event - the event name.
+     * @param listener - the callback.
+     * @returns the disposer that removes this listener.
+     */
+    on(event: 'loader/volatile-update', listener: () => void): Disposable;
+    /** Read one optional service. */
+    get(name: string): unknown;
+    /** Structured log surface. */
+    readonly logger: {
+        warn(message: string): void;
+        error(message: string): void;
+    };
+    /** HTTP route carrier (guaranteed by `inject`). */
+    readonly webServer: WebServerLike;
+    /** Trust fence the route checks first (guaranteed by `inject`). */
+    readonly connection: ConnectionLike;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * dsh-quota-check: one statusbar figure for the provider the current session
+ * is using: the remaining balance on a pure API-billing route, or the plan
+ * quota on a subscription route.
+ *
+ * Two halves, one endpoint:
+ *
+ * - this host half owns the provider credential and the outbound request, and
+ *   serves one JSON reply from `GET /quota-check?provider=<id>`. That is the
+ *   only way a browser half can reach a provider key: the key stays in this
+ *   process, and the browser only ever sees the formatted figure.
+ * - `lib/client.js` registers the chip in `conversation.composer.dock` (the
+ *   statusbar row directly under the composer and its model selector) and
+ *   asks this route for the provider the session's model selection names.
+ *
+ * Which endpoints answer is `probes.ts`; the credential and the reading are
+ * resolved once per provider and cached for {@link DEFAULT_CACHE_SECONDS}, so
+ * a rerender, a session switch, or a second tab never multiplies provider
+ * traffic.
+ *
+ * @module dsh-quota-check
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { HostContext } from './host.ts';
+/** Plugin name as it appears in the loader. */
+export declare const name = "quota-check";
+/**
+ * The route carrier, and the trust fence the route checks first: without
+ * `connection` nothing would refuse a cross-origin or unauthenticated caller,
+ * so the plugin waits for it rather than serving unfenced.
+ */
+export declare const inject: string[];
+/** The route the browser half reads. */
+export declare const ROUTE = "/quota-check";
+/** Seconds one provider's reading is served without re-asking the provider. */
+export declare const DEFAULT_CACHE_SECONDS = 60;
+/** Per-request ceiling for a provider call, in milliseconds. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Seconds the browser half waits between re-reads, unless configured otherwise. */
+export declare const DEFAULT_REFRESH_SECONDS = 300;
+/**
+ * Configuration this plugin's row resolves to, as `apply` receives it.
+ *
+ * Every field is `volatile()`, so the loader hands a live reference rather than
+ * a value: the settings document accepts writes only under a volatile node, and
+ * the Plugins page's Quota check card edits exactly these three. Each is read
+ * per request, so a save changes the next reading, cache window, and polling
+ * cadence without remounting the route.
+ */
+export interface Config {
+    /** Seconds a reading stays cached. `0` re-asks on every request. @default 60 */
+    readonly cacheSeconds: Volatile<number>;
+    /** Per-request provider deadline in milliseconds. @default 10000 */
+    readonly timeoutMs: Volatile<number>;
+    /** Seconds between the browser half's re-reads. @default 300 */
+    readonly refreshSeconds: Volatile<number>;
+}
+/** Raw row values, as a profile patch states them and as direct callers pass them. */
+export type Options = {
+    [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : Config[K];
+};
+/**
+ * Row schema as Cordis resolves it: what this plugin's `config` is validated
+ * against, and where each default lives. Every value here is a deployment
+ * choice (the cadences and the deadline vary by machine), so none is a
+ * constant only this plugin could change, and all three are editable from the
+ * Plugins page.
+ */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    cacheSeconds: Schema<number, number, "volatile-defined">;
+    timeoutMs: Schema<number, number, "volatile-defined">;
+    refreshSeconds: Schema<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    cacheSeconds: Schema<number, number, "volatile-defined">;
+    timeoutMs: Schema<number, number, "volatile-defined">;
+    refreshSeconds: Schema<number, number, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Turn a row (live references or plain values) into validated plain options.
+ * @param row - the configured row.
+ * @returns the resolved options, defaults filled by the schema.
+ */
+export declare function resolveRow(row?: Config | Options): Required<Options>;
+/** One provider's answer, as the browser half reads it. */
+export interface QuotaReport {
+    /** Route id the report belongs to. */
+    readonly provider: string;
+    /** Display name for the route, when the registry declares one. */
+    readonly displayName: string;
+    /** `ok` renders the figure; `unsupported` and `error` render nothing. */
+    readonly status: 'ok' | 'unsupported' | 'error';
+    /** Which kind of figure this is, on `ok`. */
+    readonly kind?: 'balance' | 'quota';
+    /** Compact statusbar text, on `ok`. */
+    readonly text?: string;
+    /** Tooltip detail lines, on `ok`. */
+    readonly lines?: readonly string[];
+    /** Remaining quota as a percentage, on `ok` when the reading is metered. */
+    readonly remaining?: number;
+    /** Why there is no figure, on `unsupported` and `error`. */
+    readonly message?: string;
+    /** When the reading was taken, epoch milliseconds. */
+    readonly fetchedAt: number;
+    /** How long the browser half should wait before re-reading, in milliseconds. */
+    readonly refreshMs: number;
+}
+/**
+ * Mount the host half.
+ * @param ctx - host context carrying the route carrier.
+ * @param config - this plugin's row configuration.
+ */
+export declare function apply(ctx: HostContext, row?: Config | Options): void;

package/lib/types/local-usage.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local CLI credentials for the subscription providers: where the token lives,
+ * when it is stale, how it rotates, and the exact headers the vendor's usage
+ * endpoint expects.
+ *
+ * These four providers bill a plan, not a key, so there is no settings API key
+ * to resolve: the token already sits on this machine, written by the CLI the
+ * human signed into. This module is the port of `quota-widget`'s fetchers
+ * (`~/Desktop/Projects/quota-widget/package/contents/code/fetch_quota.py`);
+ * it keeps the observable behavior (file paths, expiry skews, refresh bodies,
+ * and the write-back that keeps the CLI itself signed in) and drops the parts
+ * a statusbar chip does not need (disk caches, Retry-After sleeps, the TUI
+ * JSON shape).
+ *
+ * Rotation writes back only through an atomic replace in the file's own
+ * directory, mode 0600, preserving every other field, so a crash mid-write can
+ * never leave a CLI with a truncated credential.
+ *
+ * @module dsh-quota-check/local-usage
+ */
+/** The subscription providers whose credentials live on this machine. */
+export type LocalProvider = 'claude' | 'codex' | 'grok' | 'cursor';
+/** One outbound request built from a local credential. */
+export interface LocalRequest {
+    /** Absolute URL to GET. */
+    readonly url: string;
+    /** Headers the vendor expects, including the credential itself. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** Options for reading a local credential. */
+export interface LocalOptions {
+    /** Home directory the CLI files hang off; defaults to the running user's. */
+    readonly home?: string;
+    /** Refresh even when the token looks unexpired; the 401 retry path uses this. */
+    readonly forceRefresh?: boolean;
+    /** Deadline for each token-endpoint request, in milliseconds. */
+    readonly timeoutMs: number;
+}
+/**
+ * Build the outbound requests for one subscription provider.
+ * @param provider - which CLI credential to read.
+ * @param options - home directory, forced-refresh flag, and token-request deadline.
+ * @returns one or two requests, or `[]` when nothing usable is on disk.
+ */
+export declare function localRequests(provider: LocalProvider, options: LocalOptions): Promise<readonly LocalRequest[]>;

package/lib/types/probes.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Provider quota/balance probes: which endpoint answers for a provider route,
+ * and how its payload becomes one statusbar line plus tooltip detail.
+ *
+ * A probe resolves from a provider id and an optional configured base URL, and
+ * a parser turns a decoded JSON payload into a {@link ProbeReading}. Host-only
+ * concerns (credentials, HTTP, caching) live in `index.ts`, which is what
+ * makes these rules testable without a network. One exception: an endpoint whose
+ * ids the configuration cannot name (OmniRoute asks per upstream connection)
+ * declares `requests`, which reads the listing before the host asks each id.
+ *
+ * Four endpoints report a *server-side* figure: DeepSeek's `/user/balance`,
+ * OpenRouter's `/credits`, the z.ai / BigModel Coding Plan quota, and LiteLLM's
+ * `/key/info` (spend and remaining budget for the calling key). LiteLLM is also
+ * the fallback for any otherwise-unknown route with a configured base URL,
+ * because a proxy deployment names its routes after the models it serves, not
+ * after the proxy: an unknown host that answers `/key/info` is a LiteLLM. A
+ * route whose host publishes neither resolves no probe and the statusbar stays
+ * empty.
+ *
+ * @module dsh-quota-check/probes
+ */
+import type { LocalProvider, LocalRequest } from './local-usage.ts';
+/** Short reading for one provider: the chip text and its tooltip lines. */
+export interface ProbeReading {
+    /** Compact statusbar text, e.g. `¥110.00` or `GLM 58%`. */
+    readonly text: string;
+    /** Tooltip detail lines, in display order. */
+    readonly lines: readonly string[];
+    /** Remaining quota as a percentage, when the reading is a metered quota. */
+    readonly remaining?: number;
+}
+/** What one provider reports: a spendable balance, or a plan quota. */
+export type ProbeKind = 'balance' | 'quota';
+/**
+ * The bodies a probe asked for, aligned with its requests: `undefined` marks a
+ * request that failed, so a two-meter provider (Grok's weekly and monthly
+ * calls) still reports when only one of them answered.
+ */
+export type ProbePayloads = readonly (unknown | undefined)[];
+/** What a probe that discovers its own endpoints is handed. */
+export interface ProbeExpandContext {
+    /** The route's resolved credential. */
+    readonly key: string;
+    /** Per-request deadline in milliseconds, for the listing request itself. */
+    readonly timeoutMs: number;
+}
+/**
+ * Build a probe's requests from an earlier answer, for endpoints whose ids the
+ * route's configuration cannot name.
+ * @param context - the credential and deadline to list with.
+ * @returns the requests to ask, in the order their payloads arrive.
+ */
+export type ProbeExpander = (context: ProbeExpandContext) => Promise<readonly LocalRequest[]>;
+/** Everything a probe shares, whatever its credential source. */
+interface ProbeBase {
+    /** Which kind of figure this is. */
+    readonly kind: ProbeKind;
+    /** Credential references tried when the provider configuration names none. */
+    readonly envNames?: readonly string[];
+    /**
+     * Requests discovered from an earlier answer, for a route whose endpoint
+     * names an id only the provider itself knows.
+     */
+    readonly requests?: ProbeExpander;
+    /**
+     * True when this probe is a guess about a host the route never named: an
+     * absent endpoint or an unconfigured credential then means the host is not
+     * that product, which is absent data rather than a failed reading.
+     */
+    readonly tentative?: boolean;
+    /**
+     * Turn the decoded payloads into a reading.
+     * @param payloads - decoded JSON bodies, in request order.
+     * @returns the reading, or `null` when none carries a usable figure.
+     */
+    parse(payloads: ProbePayloads): ProbeReading | null;
+}
+/**
+ * One probe: the endpoint it reads, and the credential that endpoint expects.
+ * A key probe fetches one URL with a bearer token resolved from settings; a
+ * local probe reads the subscription credential a CLI left on this machine and
+ * may ask two endpoints of the same account.
+ */
+export type Probe = ProbeBase & ({
+    /**
+     * Absolute URL to GET with the provider's bearer credential. Absent when
+     * the probe discovers its own requests instead.
+     */
+    readonly url?: string;
+    readonly local?: undefined;
+} | {
+    /** Local CLI credential this endpoint reads instead of a settings key. */
+    readonly local: LocalProvider;
+    readonly url?: undefined;
+});
+/**
+ * Format an amount for the statusbar.
+ * @param amount - absolute amount.
+ * @param currency - ISO currency code, when the provider reports one.
+ * @returns symbol-prefixed amount with two decimals, or the amount with its code.
+ */
+export declare function formatMoney(amount: number, currency?: string): string;
+/**
+ * Resolve the probe answering for one provider route.
+ *
+ * A configured base URL decides alone when it names a known host, because the
+ * host is the endpoint that actually answers. The provider id only decides
+ * when no base URL is configured (the route relies on its library's own
+ * default), so a route named after a provider but pointed somewhere else (a
+ * local vLLM serving DeepSeek weights, or Vertex-hosted Claude, say) is never
+ * read from that provider's own subscription credential.
+ *
+ * The subscription probes come first among the id-based rules because their
+ * host is the vendor itself, not a reseller: a route called `anthropic` with no
+ * base URL is Claude Code's plan meter, while `google-vertex-anthropic` carries
+ * a googleapis.com host and resolves nothing.
+ *
+ * A route that names no vendor and still has a base URL gets the LiteLLM
+ * key-budget probe, which is how a proxy deployment is recognized at all.
+ * @param providerId - route id as the model picker names it, e.g. `deepseek-official`.
+ * @param baseURL - the route's configured base URL, when it has one.
+ * @returns the probe, or `undefined` when no balance or quota route is known.
+ */
+export declare function resolveProbe(providerId: string, baseURL?: string): Probe | undefined;
+export {};

package/lib/types/util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Narrowing helpers shared by the probes, the local-usage reader, and the
+ * route: every provider answer is an unknown until one of these reads it.
+ *
+ * @module util
+ */
+/** Narrow an unknown to an indexable object. */
+export declare function record(value: unknown): Record<string, unknown> | undefined;
+/** Read one field as a non-empty string, or `undefined`. */
+export declare function stringOf(value: unknown): string | undefined;
+/** Read one field as a finite number, or `undefined`. */
+export declare function numberOf(value: unknown): number | undefined;
+/** Parse an ISO timestamp as epoch milliseconds, or `undefined`. */
+export declare function isoToMs(value: unknown): number | undefined;

package/lib/util.js

@@ -0,0 +1,28 @@
+/**
+ * Narrowing helpers shared by the probes, the local-usage reader, and the
+ * route: every provider answer is an unknown until one of these reads it.
+ *
+ * @module util
+ */
+/** Narrow an unknown to an indexable object. */
+export function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Read one field as a non-empty string, or `undefined`. */
+export function stringOf(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Read one field as a finite number, or `undefined`. */
+export function numberOf(value) {
+    const parsed = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof parsed === 'number' && Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Parse an ISO timestamp as epoch milliseconds, or `undefined`. */
+export function isoToMs(value) {
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Quota",
+    "description": "Show the selected provider's quota and API balance in the composer."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "额度",
+    "description": "在输入栏显示当前提供商的额度与 API 余额。"
+  }
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@maci0/dsh-quota-check",
+  "version": "0.12.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "description": "Quota and API-balance readout for the selected provider, in the DeepSeek Harness composer statusbar.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bunx --bun tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "bunx --bun tsc -p tsconfig.json",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.1",
+    "@types/node": "^22.20.2",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-quota-check.git"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-ui-renderer": "*",
+    "@deepseek-ai/dsh-client-ui-session": "*",
+    "@deepseek-ai/dsh-client-ui-conversation": "*",
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-ui-settings": "*",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-conversation": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-plugin-manager": {
+      "optional": true
+    }
+  }
+}