aisubs 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.1 - 2026-10-06
+
+- Add `SubscriptionAuth.onUsage(listener)`: usage that provider responses report about
+  themselves, with no extra request. ChatGPT reads its `x-codex-*` rate-limit headers and
+  GitHub Copilot its `x-quota-snapshot-*` headers; the cached usage snapshot follows along.
+- Add the `usageFromResponse` adapter hook, plus `parseChatGptUsageHeaders`,
+  `parseCopilotUsageHeaders` and `mergeObservedUsage`.
+- `getUsage` (and `SubscriptionAccount.getUsage`) take `force` to bypass the usage cache.
+
 ## 0.4.0 - 2026-10-06
 
 - Breaking: removed the Claude subscription provider, the `aisubs/providers/claude`

package/dist/auth.d.ts

@@ -18,7 +18,8 @@ export interface SubscriptionAccount {
     getAccessToken(): Promise<string>;
     fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
     proxy(path: string, init?: RequestInit): Promise<Response>;
-    getUsage(signal?: AbortSignal): Promise<ProviderUsage | null>;
+    /** `force` reads the provider now instead of answering from the short usage cache. */
+    getUsage(signal?: AbortSignal, force?: boolean): Promise<ProviderUsage | null>;
     getModels(signal?: AbortSignal, force?: boolean): Promise<ProviderModels | null>;
     credentialSummary(): Promise<CredentialSummary>;
     details(signal?: AbortSignal): Promise<SubscriptionAccountDetails>;
@@ -35,6 +36,7 @@ export declare class SubscriptionAuth {
     private readonly usageInflight;
     private readonly modelsInflight;
     private readonly metadataGenerations;
+    private readonly usageListeners;
     private readonly refreshTimeoutMs;
     private readonly usageCacheTtlMs;
     private readonly modelsCacheTtlMs;
@@ -67,11 +69,18 @@ export declare class SubscriptionAuth {
     getAccessToken(provider: ProviderId, account?: string): Promise<string>;
     credentialSummary(provider: ProviderId, account?: string): Promise<CredentialSummary>;
     details(provider: ProviderId, account?: string, signal?: AbortSignal): Promise<SubscriptionAccountDetails>;
+    /**
+     * Calls `listener` with the usage each provider response reports about itself (for example
+     * ChatGPT's rate-limit headers): only the meters that response mentions, as of its arrival.
+     * The cached usage snapshot is updated too. Returns the unsubscribe function.
+     */
+    onUsage(listener: (usage: ProviderUsage) => void): () => void;
+    private observeUsage;
     fetch(provider: ProviderId, input: string | URL | Request, init?: RequestInit, account?: string): Promise<Response>;
     proxy(provider: ProviderId, account: string, path: string, init?: RequestInit): Promise<Response>;
     /** Build an authorized direct-provider request for transports such as WebSocket. */
     authorizeProxyRequest(provider: ProviderId, account: string, path: string, init?: RequestInit): Promise<Request>;
-    getUsage(provider: ProviderId, account?: string, callerSignal?: AbortSignal): Promise<ProviderUsage | null>;
+    getUsage(provider: ProviderId, account?: string, callerSignal?: AbortSignal, force?: boolean): Promise<ProviderUsage | null>;
     getModels(provider: ProviderId, account?: string, callerSignal?: AbortSignal, force?: boolean): Promise<ProviderModels | null>;
     account(provider: ProviderId, account: string): SubscriptionAccount;
 }

package/dist/auth.js

@@ -1,3 +1,4 @@
+import { mergeObservedUsage } from "./usage.js";
 import { errorMessage } from "./utils.js";
 export const DEFAULT_ACCOUNT = "default";
 const ACCOUNT_STORAGE_PREFIX = "$subscription-account$";
@@ -73,6 +74,7 @@ export class SubscriptionAuth {
     usageInflight = new Map();
     modelsInflight = new Map();
     metadataGenerations = new Map();
+    usageListeners = new Set();
     refreshTimeoutMs;
     usageCacheTtlMs;
     modelsCacheTtlMs;
@@ -498,6 +500,38 @@ export class SubscriptionAuth {
         ]);
         return { session, credential, usage, models };
     }
+    /**
+     * Calls `listener` with the usage each provider response reports about itself (for example
+     * ChatGPT's rate-limit headers): only the meters that response mentions, as of its arrival.
+     * The cached usage snapshot is updated too. Returns the unsubscribe function.
+     */
+    onUsage(listener) {
+        this.usageListeners.add(listener);
+        return () => this.usageListeners.delete(listener);
+    }
+    observeUsage(adapter, provider, accountKey, response) {
+        let data;
+        try {
+            data = adapter.usageFromResponse?.(response) ?? null;
+        }
+        catch {
+            return;
+        }
+        if (!data)
+            return;
+        const usage = { provider, accountKey, asOf: Date.now(), ...data };
+        const scope = credentialKey(provider, accountKey);
+        const cached = this.usageCache.get(scope);
+        if (cached?.value) {
+            cached.value = { ...mergeObservedUsage(cached.value, usage), asOf: usage.asOf };
+        }
+        for (const listener of this.usageListeners) {
+            try {
+                listener(usage);
+            }
+            catch { }
+        }
+    }
     async fetch(provider, input, init, account = DEFAULT_ACCOUNT) {
         const adapter = this.adapter(provider);
         const original = createRequest(input, init);
@@ -509,6 +543,7 @@ export class SubscriptionAuth {
             headers.set("cache-control", "no-store");
             const request = new Request(authorized, { cache: "no-store", headers });
             const response = await globalThis.fetch(request);
+            this.observeUsage(adapter, provider, accountKey, response);
             return adapter.normalizeResponse?.(request, response) ?? response;
         };
         if (adapter.supportsFetch === false) {
@@ -560,12 +595,17 @@ export class SubscriptionAuth {
         const normalized = (await adapter.normalizeRequest?.(request.clone())) ?? request;
         return adapter.authorize(normalized, credential);
     }
-    async getUsage(provider, account = DEFAULT_ACCOUNT, callerSignal) {
+    async getUsage(provider, account = DEFAULT_ACCOUNT, callerSignal, force = false) {
         const adapter = this.adapter(provider);
         if (!adapter.getUsage)
             return null;
         const accountKey = normalizeAccountKey(account);
         const scope = credentialKey(provider, accountKey);
+        if (force) {
+            this.usageCache.delete(scope);
+            this.usageInflight.delete(scope);
+            this.metadataGenerations.set(scope, (this.metadataGenerations.get(scope) ?? 0) + 1);
+        }
         return this.cachedMetadata(this.usageCache, this.usageInflight, scope, this.usageCacheTtlMs, callerSignal, async () => {
             const credential = await this.credential(provider, accountKey);
             const timeout = AbortSignal.timeout(this.refreshTimeoutMs);
@@ -613,7 +653,7 @@ export class SubscriptionAuth {
             getAccessToken: () => this.getAccessToken(provider, accountKey),
             fetch: (input, init) => this.fetch(provider, input, init, accountKey),
             proxy: (path, init) => this.proxy(provider, accountKey, path, init),
-            getUsage: (signal) => this.getUsage(provider, accountKey, signal),
+            getUsage: (signal, force) => this.getUsage(provider, accountKey, signal, force),
             getModels: (signal, force) => this.getModels(provider, accountKey, signal, force),
             credentialSummary: () => this.credentialSummary(provider, accountKey),
             details: (signal) => this.details(provider, accountKey, signal),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createSubscriptionAuth, DEFAULT_ACCOUNT, SubscriptionAuth, type SubscriptionAccount, type SubscriptionAuthOptions, } from "./auth.js";
 export { MemoryCredentialStore } from "./memory-store.js";
-export { parseChatGptUsage, parseCopilotUsage, parseGrokUsage } from "./usage.js";
+export { mergeObservedUsage, parseChatGptUsage, parseChatGptUsageHeaders, parseCopilotUsage, parseCopilotUsageHeaders, parseGrokUsage, } from "./usage.js";
 export type { CredentialStore, CoordinatedCredentialStore, CredentialSummary, BrowserLoginPrompt, DeviceLoginPrompt, ImmediateLoginPrompt, LoginAttempt, LoginMode, LoginPrompt, LoginState, OAuthCredential, VersionedCredential, ProviderAdapter, ProviderId, ProviderLogin, ProviderLoginField, ProviderModel, ProviderModels, ProviderSummary, ProviderUsage, ProviderUsageContext, ProviderUsageData, Session, SubscriptionAccountDetails, UsageFact, UsageMeter, UsageResetCredit, UsageResetCredits, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { createSubscriptionAuth, DEFAULT_ACCOUNT, SubscriptionAuth, } from "./auth.js";
 export { MemoryCredentialStore } from "./memory-store.js";
-export { parseChatGptUsage, parseCopilotUsage, parseGrokUsage } from "./usage.js";
+export { mergeObservedUsage, parseChatGptUsage, parseChatGptUsageHeaders, parseCopilotUsage, parseCopilotUsageHeaders, parseGrokUsage, } from "./usage.js";

package/dist/providers/chatgpt.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
-import { parseChatGptUsage } from "../usage.js";
+import { parseChatGptUsage, parseChatGptUsageHeaders } from "../usage.js";
 import { abortableDelay, bearerRequest, isRecord, numberValue, requireAllowedHost, responseJson, stringArray, stringValue, } from "../utils.js";
 const ISSUER = "https://auth.openai.com";
 const DEFAULT_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
@@ -533,6 +533,7 @@ export function chatGptProvider(options = {}) {
             }
             return response;
         },
+        usageFromResponse: (response) => parseChatGptUsageHeaders(response.headers),
         async getUsage({ fetch, signal }) {
             const response = await fetch(USAGE_URL, { headers: { accept: "application/json" }, signal });
             const raw = await responseJson(response, "ChatGPT usage");

package/dist/providers/copilot.js

@@ -1,4 +1,4 @@
-import { copilotPlanName, parseCopilotUsage } from "../usage.js";
+import { copilotPlanName, parseCopilotUsage, parseCopilotUsageHeaders } from "../usage.js";
 import { abortableDelay, bearerRequest, isRecord, numberValue, requireAllowedHost, responseJson, stringArray, stringValue, } from "../utils.js";
 const DEFAULT_CLIENT_ID = "Iv1.b507a08c87ecfe98";
 const EXPIRY_SKEW_MS = 5 * 60_000;
@@ -448,6 +448,7 @@ export function copilotProvider(options = {}) {
                 headers,
             });
         },
+        usageFromResponse: (response) => parseCopilotUsageHeaders(response.headers),
         async getUsage({ credential, signal }) {
             if (!credential.refreshToken)
                 throw new Error("GitHub token is missing");

package/dist/types.d.ts

@@ -189,6 +189,11 @@ export interface ProviderAdapter {
     refresh(credential: OAuthCredential, signal: AbortSignal): Promise<OAuthCredential>;
     authorize(request: Request, credential: OAuthCredential): Request | Promise<Request>;
     getUsage?(context: ProviderUsageContext): Promise<ProviderUsageData | null>;
+    /**
+     * Usage a model response reports about itself (rate-limit or quota headers), so meters stay
+     * current with no extra request. Only the meters the response mentions; `null` when none.
+     */
+    usageFromResponse?(response: Response): ProviderUsageData | null;
     getModels?(context: ProviderUsageContext): Promise<ProviderModel[]>;
     isPermanentRefreshError?(error: unknown): boolean;
 }

package/dist/usage.d.ts

@@ -3,3 +3,21 @@ export declare function parseChatGptUsage(raw: unknown, detailedResetCredits?: u
 export declare function copilotPlanName(raw: unknown): string | undefined;
 export declare function parseCopilotUsage(raw: unknown): ProviderUsageData | null;
 export declare function parseGrokUsage(raw: unknown, userRaw?: unknown, settingsRaw?: unknown): ProviderUsageData | null;
+/**
+ * The plan windows a ChatGPT (Codex) response reports in its headers, the same numbers the usage
+ * endpoint returns: `x-codex-primary-used-percent`, `-window-minutes` and `-reset-at` (unix
+ * seconds), likewise `secondary`, and other metered families as `x-<limit>-primary-…`. Meter ids
+ * match `parseChatGptUsage`, so a reading updates the meters a usage read listed.
+ */
+export declare function parseChatGptUsageHeaders(headers: Headers): ProviderUsageData | null;
+/**
+ * The quotas a GitHub Copilot response reports in `x-quota-snapshot-<quota>` headers, as VS Code
+ * reads them: URL-encoded `ent` (entitlement, -1 unlimited), `rem` (percent remaining) and `rst`
+ * (reset time). Meter ids match `parseCopilotUsage`'s quota snapshot keys.
+ */
+export declare function parseCopilotUsageHeaders(headers: Headers): ProviderUsageData | null;
+/**
+ * `base` with the meters a response reported (`observed`) replaced by id. Meters `base` doesn't
+ * list are left out: a response reports numbers, the usage read decides which meters exist.
+ */
+export declare function mergeObservedUsage<T extends ProviderUsageData>(base: T, observed: ProviderUsageData): T;

package/dist/usage.js

@@ -416,3 +416,85 @@ export function parseGrokUsage(raw, userRaw, settingsRaw) {
             : undefined,
     };
 }
+/**
+ * The plan windows a ChatGPT (Codex) response reports in its headers, the same numbers the usage
+ * endpoint returns: `x-codex-primary-used-percent`, `-window-minutes` and `-reset-at` (unix
+ * seconds), likewise `secondary`, and other metered families as `x-<limit>-primary-…`. Meter ids
+ * match `parseChatGptUsage`, so a reading updates the meters a usage read listed.
+ */
+export function parseChatGptUsageHeaders(headers) {
+    const families = new Set();
+    for (const name of headers.keys()) {
+        const match = /^x-(.+)-(?:primary|secondary)-used-percent$/.exec(name.toLowerCase());
+        if (match)
+            families.add(match[1]);
+    }
+    const meters = [];
+    for (const family of families) {
+        for (const window of ["primary", "secondary"]) {
+            const prefix = `x-${family}-${window}`;
+            const percentUsed = numeric(headers.get(`${prefix}-used-percent`));
+            if (percentUsed == null)
+                continue;
+            const minutes = numeric(headers.get(`${prefix}-window-minutes`));
+            const resetAt = timestamp(headers.get(`${prefix}-reset-at`));
+            const name = headers.get(`x-${family}-limit-name`)?.trim();
+            const label = windowLabel(minutes != null ? minutes * 60 : undefined);
+            meters.push({
+                id: family === "codex" ? window : `${family.replace(/-/g, "_")}:${window}`,
+                label: family === "codex" ? label : `${name || title(family)} / ${label}`,
+                unit: "percent",
+                percentUsed,
+                resetAt,
+            });
+        }
+    }
+    return meters.length ? { meters } : null;
+}
+/**
+ * The quotas a GitHub Copilot response reports in `x-quota-snapshot-<quota>` headers, as VS Code
+ * reads them: URL-encoded `ent` (entitlement, -1 unlimited), `rem` (percent remaining) and `rst`
+ * (reset time). Meter ids match `parseCopilotUsage`'s quota snapshot keys.
+ */
+export function parseCopilotUsageHeaders(headers) {
+    const meters = [];
+    for (const [name, value] of headers) {
+        const match = /^x-quota-snapshot-(.+)$/.exec(name.toLowerCase());
+        if (!match)
+            continue;
+        const params = new URLSearchParams(value);
+        const entitlement = numeric(params.get("ent"));
+        const percentRemaining = numeric(params.get("rem"));
+        if (entitlement == null || percentRemaining == null)
+            continue;
+        const id = match[1];
+        const resetAt = timestamp(params.get("rst"));
+        meters.push(entitlement === -1
+            ? copilotMeter(id, { unlimited: true }, resetAt)
+            : copilotMeter(id, {
+                entitlement,
+                quota_remaining: (entitlement * percentRemaining) / 100,
+                percent_remaining: percentRemaining,
+            }, resetAt));
+    }
+    return meters.length ? { meters } : null;
+}
+/**
+ * `base` with the meters a response reported (`observed`) replaced by id. Meters `base` doesn't
+ * list are left out: a response reports numbers, the usage read decides which meters exist.
+ */
+export function mergeObservedUsage(base, observed) {
+    if (!base.meters?.length || !observed.meters?.length)
+        return base;
+    const byId = new Map(observed.meters.map((meter) => [meter.id, meter]));
+    let changed = false;
+    const meters = base.meters.map((meter) => {
+        const next = byId.get(meter.id);
+        if (!next)
+            return meter;
+        changed = true;
+        // The read's label and unit name the meter; the response only brings its numbers.
+        return { ...next, label: meter.label, unit: meter.unit, window: meter.window };
+    });
+    return changed ? { ...base, meters } : base;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aisubs",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Connect AI provider accounts and use those subscriptions from any local tool or as api.",
   "keywords": [
     "ai",