@slkiser/opencode-quota 5.0.3 → 6.0.0-beta.1

package/dist/core/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The v6 quota data model: rows with stable ids, one snapshot per provider, and one error
+ * vocabulary. The server builds these; the TUI, Web text and the CLI only read them. Every
+ * value is plain JSON, because snapshots travel over the RPC and are saved to disk.
+ */
+import type { QuotaExportProvider } from "../lib/quota-export-types.js";
+import type { ClientSettings } from "../settings/schema.js";
+/** What a row's number means (ADR 0001: the 7 legacy result types become 5). */
+export type RowType = "quota" | "budget" | "usage" | "balance" | "status";
+/** How the number was acquired (ADR 0001: the 5 legacy methods become 4). */
+export type RowMethod = "remote_api" | "dashboard_scrape" | "local_cli" | "local_estimation";
+export type RowAuthority = "provider_reported" | "locally_derived";
+/** The period a quota row covers; drives short labels, preferred windows and reset notices. */
+export type QuotaWindow = "rpm" | "hour" | "five_hour" | "session" | "day" | "week" | "month" | "year" | "mcp" | "code_review";
+/** A count unit is singular, for example "request"; the text adds the plural. */
+export type AmountUnit = {
+    kind: "currency";
+    code: string;
+} | {
+    kind: "count";
+    unit: string;
+} | {
+    kind: "custom";
+    symbol: string;
+};
+/** An exact number: `decimal` is a canonical decimal string such as "12.5" or "-3". */
+export type Amount = {
+    decimal: string;
+    unit: AmountUnit;
+};
+export type QuotaRow = {
+    /** `${providerId}.${key}`, for example "anthropic.weekly_fable"; the hide/rename/order key. */
+    id: string;
+    providerId: string;
+    /** Account or plan shown after the provider name, for example "work" or "SuperGrok". */
+    account?: string;
+    /** Default label, for example "5h", "Weekly", "Fable", "Balance". */
+    label: string;
+    type: RowType;
+    method: RowMethod;
+    authority: RowAuthority;
+    window?: QuotaWindow;
+    prominence: "primary" | "supplementary";
+    /** Raw percent left; display rounds and clamps. May be below 0 when over quota. */
+    percentRemaining?: number;
+    used?: Amount;
+    limit?: Amount;
+    remaining?: Amount;
+    /** The value of a usage or balance row. */
+    amount?: Amount;
+    /** The value of a yes/no status row. */
+    flag?: boolean;
+    /** Text value, for example "Unlimited" or a custom provider's own summary. */
+    text?: string;
+    /** ISO time the window resets. */
+    resetsAt?: string;
+    /** ISO time the window started (pace marker and runs-out estimate). */
+    windowStartedAt?: string;
+};
+export type QuotaErrorCode = "not_configured" | "login_expired" | "no_plan" | "rate_limited" | "timeout" | "network" | "provider_error" | "bad_response" | "no_data" | "local_tool" | "internal";
+export type QuotaError = {
+    code: QuotaErrorCode;
+    /** HTTP status, when the provider answered with one. */
+    status?: number;
+    /** When the provider said to try again. */
+    retryAtMs?: number;
+    /** The local program involved, for `local_tool`, for example "Claude CLI". */
+    tool?: string;
+    /** For `local_tool`: true when the program is missing rather than failing. */
+    missing?: boolean;
+    /** The provider's own message, scrubbed; no report shows it. */
+    detail?: string;
+};
+export type DebugDetail = {
+    key: string;
+    value: string;
+};
+export type ProviderSnapshot = {
+    providerId: string;
+    /** Registration label, for example "Anthropic" or "Copilot". */
+    label: string;
+    /** The last good rows; a failed refresh keeps them. */
+    rows: QuotaRow[];
+    /** When `rows` were fetched. */
+    okAtMs?: number;
+    /** When the last attempt ended. */
+    checkedAtMs?: number;
+    /** Why the last attempt failed. */
+    error?: QuotaError;
+    refreshing: boolean;
+    /** Provider facts for /quota_status only. */
+    debug: DebugDetail[];
+    /**
+     * This provider's part of the export file from its last check in this server process.
+     * Kept in memory only and never sent to clients.
+     */
+    exportPart?: QuotaExportProvider;
+};
+/** A quota window that reset since the last check; each TUI shows it once (by `id`). */
+export type ResetNotice = {
+    id: string;
+    rowId: string;
+    providerId: string;
+    account?: string;
+    label: string;
+    window: QuotaWindow;
+    percentRemaining: number;
+    atMs: number;
+};
+/** One model's input tokens in a session: new input, cache reads and cache writes. */
+export type SessionModelInput = {
+    modelID: string;
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
+/** Tokens a session used so far (with its subagents when the words say "tree"). */
+export type SessionTokens = {
+    input: number;
+    cachedInput: number;
+    output: number;
+    /** Each model with input tokens, for the sidebar's low cache line; absent when none had any. */
+    models?: SessionModelInput[];
+};
+/** "58% left", "58% remaining", "58%", or "42% used". */
+type PercentStyle = "left" | "remaining" | "bare" | "used";
+/** How a time until a reset reads: "4.5d" (smart), "2h 14m", "2h14m", "2h", or "2.2h". */
+export type ResetStyle = "smart" | "exact" | "compact" | "short" | "decimal";
+/** The words every surface uses, on every client (TUI, Web, Desktop, CLI). */
+export type Words = {
+    percent: PercentStyle;
+    reset: ResetStyle;
+    /** Decimals of the "decimal" reset style. */
+    resetDecimals: number;
+    /**
+     * How the sidebar, the collapsed panel, the status line and toasts name a row: "short" by
+     * its window ("5h", "7d") unless another row of its provider has the same one, "full" by its
+     * label. A row you renamed shows your name in both.
+     */
+    rowNames: "short" | "full";
+    /** "detailed" also shows supplementary rows. */
+    detail: "summary" | "detailed";
+    /** Show only the providers serving the session's current model. */
+    onlyCurrentModel: boolean;
+    /** Session tokens of this session, or with its subagents. */
+    sessionTokens: "current" | "tree";
+};
+/** A session's model: its id and OpenCode's provider id. */
+export type SessionModel = {
+    id?: string;
+    providerID?: string;
+};
+export type QuotaSnapshot = {
+    version: 6;
+    /** Enabled and available providers, in registration order. */
+    providers: ProviderSnapshot[];
+    /** With a session: the providers serving its current model (the "current model only" filter). */
+    currentModelProviderIds?: string[];
+    /**
+     * With a session: for a provider whose rows serve different models (the custom providers,
+     * one definition each), the row id prefixes that serve its current model, by provider id.
+     * Every row is still checked; under "current model only" just these show.
+     */
+    currentModelRowPrefixes?: Record<string, string[]>;
+    /** With a session: the tokens it used so far. */
+    sessionTokens?: SessionTokens;
+    /**
+     * The OpenCode provider id each custom definition serves, by the prefix of its row ids
+     * (`quota-providers.custom.<definition id>.`); absent without custom definitions.
+     */
+    customRowProviders?: Record<string, string>;
+    /** The server's words; clients use their defaults until the server sends them. */
+    words?: Words;
+    /** All editable file settings, refreshed with every settings change. */
+    settings?: ClientSettings;
+    /** This server converted v5 settings into the file; a TUI announces it once. */
+    settingsConverted?: boolean;
+    resetNotices: ResetNotice[];
+    generatedAtMs: number;
+    /** Random for each server start; revisions compare only within one server. */
+    serverId: string;
+    /** Grows with every snapshot the server builds: of two, the higher revision is newer. */
+    revision: number;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":""}

package/dist/core/usage-ranges.d.ts

@@ -0,0 +1,46 @@
+export declare const USAGE_RANGES: readonly [{
+    readonly range: "today";
+    readonly label: "Today";
+}, {
+    readonly range: "24h";
+    readonly label: "24 hours";
+}, {
+    readonly range: "7d";
+    readonly label: "7 days";
+}, {
+    readonly range: "30d";
+    readonly label: "30 days";
+}, {
+    readonly range: "90d";
+    readonly label: "90 days";
+}, {
+    readonly range: "all";
+    readonly label: "All time";
+}, {
+    readonly range: "session";
+    readonly label: "This session";
+}, {
+    readonly range: "between";
+    readonly label: "Between";
+}];
+export type UsageRange = (typeof USAGE_RANGES)[number]["range"];
+export declare const DEFAULT_USAGE_RANGE: UsageRange;
+/** The 4.x and 5.x token commands (`system.oldCommands`), each `/quota_usage` on its range. */
+export declare const OLD_USAGE_COMMANDS: Readonly<Record<string, UsageRange>>;
+export declare function usageRangeLabel(range: UsageRange): string;
+type UsageArguments = {
+    ok: true;
+    range: UsageRange;
+    from?: string;
+    to?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The range a `/quota_usage` command asks for: nothing is the default range, "between" takes
+ * two dates in order.
+ */
+export declare function parseUsageArguments(text: string): UsageArguments;
+export {};
+//# sourceMappingURL=usage-ranges.d.ts.map

package/dist/core/usage-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ranges.d.ts","sourceRoot":"","sources":["../../src/core/usage-ranges.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,YAAY;aACrB,KAAK,EAAE,OAAO;aAAE,KAAK,EAAE,OAAO;;aAC9B,KAAK,EAAE,KAAK;aAAE,KAAK,EAAE,UAAU;;aAC/B,KAAK,EAAE,IAAI;aAAE,KAAK,EAAE,QAAQ;;aAC5B,KAAK,EAAE,KAAK;aAAE,KAAK,EAAE,SAAS;;aAC9B,KAAK,EAAE,KAAK;aAAE,KAAK,EAAE,SAAS;;aAC9B,KAAK,EAAE,KAAK;aAAE,KAAK,EAAE,UAAU;;aAC/B,KAAK,EAAE,SAAS;aAAE,KAAK,EAAE,cAAc;;aACvC,KAAK,EAAE,SAAS;aAAE,KAAK,EAAE,SAAS;EAC5B,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;AAEhE,eAAO,MAAM,mBAAmB,EAAE,UAAoB,CAAC;AAEvD,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CASnE,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEzD;AAMD,KAAK,cAAc,GACf;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AASjC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAiBhE"}

package/dist/core/usage-ranges.js

@@ -0,0 +1,72 @@
+/**
+ * The usage ranges, in the order every surface lists them, with their user-facing labels.
+ * Pure data and parsing: the TUI loads this file without any server code.
+ *
+ * - "24h" is the rolling last 24 hours; "today", "7d", "30d" and "90d" are local calendar days,
+ *   today included.
+ * - "all" is the whole history.
+ * - "session" is the session plus its subagent sessions.
+ * - A bare `/quota_usage` and the Usage tab start on "today".
+ * - "between" takes two local dates, both included.
+ */
+import { parseCalendarDate } from "../lib/calendar-date.js";
+export const USAGE_RANGES = [
+    { range: "today", label: "Today" },
+    { range: "24h", label: "24 hours" },
+    { range: "7d", label: "7 days" },
+    { range: "30d", label: "30 days" },
+    { range: "90d", label: "90 days" },
+    { range: "all", label: "All time" },
+    { range: "session", label: "This session" },
+    { range: "between", label: "Between" },
+];
+export const DEFAULT_USAGE_RANGE = "today";
+/** The 4.x and 5.x token commands (`system.oldCommands`), each `/quota_usage` on its range. */
+export const OLD_USAGE_COMMANDS = {
+    tokens_today: "today",
+    tokens_daily: "24h",
+    tokens_weekly: "7d",
+    tokens_monthly: "30d",
+    tokens_all: "all",
+    tokens_session: "session",
+    tokens_session_all: "session",
+    tokens_between: "between",
+};
+export function usageRangeLabel(range) {
+    return USAGE_RANGES.find((item) => item.range === range)?.label ?? range;
+}
+function isUsageRange(text) {
+    return USAGE_RANGES.some((item) => item.range === text);
+}
+const USAGE_ARGUMENTS_HELP = "Usage: /quota_usage [today | 24h | 7d | 30d | 90d | all | session | between YYYY-MM-DD YYYY-MM-DD]";
+function argumentsError(problem) {
+    return { ok: false, error: `${problem}\n${USAGE_ARGUMENTS_HELP}` };
+}
+/**
+ * The range a `/quota_usage` command asks for: nothing is the default range, "between" takes
+ * two dates in order.
+ */
+export function parseUsageArguments(text) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return { ok: true, range: DEFAULT_USAGE_RANGE };
+    const [range, ...rest] = words;
+    if (!isUsageRange(range))
+        return argumentsError(`Unknown range "${range}".`);
+    if (range !== "between") {
+        return rest.length === 0
+            ? { ok: true, range }
+            : argumentsError(`The range ${range} takes no dates.`);
+    }
+    if (rest.length !== 2)
+        return argumentsError("between needs two dates.");
+    const [from, to] = rest;
+    for (const date of [from, to]) {
+        if (!parseCalendarDate(date))
+            return argumentsError(`"${date}" is not a date like 2026-01-31.`);
+    }
+    if (to < from)
+        return argumentsError(`${to} is before ${from}.`);
+    return { ok: true, range, from, to };
+}
+//# sourceMappingURL=usage-ranges.js.map

package/dist/core/usage-ranges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ranges.js","sourceRoot":"","sources":["../../src/core/usage-ranges.ts"],"names":[],"mappings":"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"}

package/dist/core/usage.d.ts

@@ -0,0 +1,100 @@
+import { type PricingSnapshotSource } from "../lib/modelsdev-pricing.js";
+import type { UsageRange } from "./usage-ranges.js";
+export { DEFAULT_USAGE_RANGE, parseUsageArguments, USAGE_RANGES, type UsageRange, usageRangeLabel, } from "./usage-ranges.js";
+export type UsageQuery = {
+    range: UsageRange;
+    /** The session for "session", which also counts its subagent sessions. */
+    sessionID?: string;
+    /** Local dates like "2026-01-31" for "between", both included. */
+    from?: string;
+    to?: string;
+};
+/** Token counts by kind; `processed` = `cachedInput` + `uncachedInput` + `output`. */
+type UsageTokens = {
+    processed: number;
+    cachedInput: number;
+    uncachedInput: number;
+    output: number;
+};
+/** Cost or tokens by the kinds that have their own price. */
+export type UsageByType = {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Output and reasoning. */
+    output: number;
+};
+/** One breakdown line. Shares are 0..1 of the report's total, and 0 when that total is 0. */
+export type UsageRow = {
+    costUsd: number;
+    costShare: number;
+    /** Processed tokens. */
+    tokens: number;
+    tokenShare: number;
+    /** Processed tokens of models without a price; they add no cost. */
+    unpricedTokens: number;
+};
+export type UsageProviderRow = UsageRow & {
+    /** OpenCode's provider id, for example "anthropic" or "github-copilot". */
+    providerID: string;
+    sessions: number;
+};
+/** `date` is a local day like "2026-01-31". */
+export type UsageDayRow = UsageRow & {
+    date: string;
+};
+export type UsageModelRow = UsageRow & {
+    providerID: string;
+    modelID: string;
+    priced: boolean;
+    costByType: UsageByType;
+    tokensByType: UsageByType;
+    /** The model's days with usage, oldest first; days without usage are left out. */
+    days: Array<{
+        date: string;
+        costUsd: number;
+        tokens: number;
+    }>;
+};
+export type UsageReport = {
+    range: UsageRange;
+    /** The time window (epoch ms, both included); absent for "all" and "session". */
+    sinceMs?: number;
+    untilMs?: number;
+    /** Present for "session". */
+    sessionID?: string;
+    generatedAtMs: number;
+    totals: {
+        costUsd: number;
+        sessions: number;
+        tokens: UsageTokens;
+        tokensByType: UsageByType;
+        costByType: UsageByType;
+        cacheSavingsUsd: number;
+        unpricedTokens: number;
+        /** `unpricedTokens` / `tokens.processed`. */
+        unpricedShare: number;
+    };
+    /** Most cost first, then most tokens. */
+    providers: UsageProviderRow[];
+    /** Most cost first, then most tokens. */
+    models: UsageModelRow[];
+    /** Every local day of the range (or from the first to the last message), oldest first. */
+    days: UsageDayRow[];
+};
+/**
+ * The usage report for `query` at `nowMs`. Identical questions (same database, price list,
+ * local day and query) share one read of the history: a request made while the same
+ * report is being built waits for it, and a finished report answers again for 30 s, so its
+ * numbers can be up to 30 s old. A failed report is not kept.
+ */
+export declare function usageReport(query: UsageQuery, nowMs?: number): Promise<UsageReport>;
+/**
+ * Downloads the price list from models.dev now, whatever its age. With the settings on the
+ * built-in price list, the download is kept but reports keep using the built-in one.
+ */
+export declare function downloadPrices(source: PricingSnapshotSource): Promise<{
+    ok: boolean;
+    message: string;
+}>;
+//# sourceMappingURL=usage.d.ts.map

package/dist/core/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"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"}