dsh-plugin-subscriptions 0.1.1 → 0.2.0

package/lib/providers/claude.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { ClaudeSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { ModelEntry } from './common.js';
+import type { FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CLAUDE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 export declare const CLAUDE_AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
 export declare const CLAUDE_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
@@ -40,6 +40,18 @@ export declare function refreshClaude(session: ClaudeSession): Promise<ClaudeSes
  * @returns true when re-login is the only fix.
  */
 export declare function isClaudePermanentRefreshError(error: unknown): boolean;
+export declare const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+/**
+ * Fetch the claude subscription usage from the OAuth usage endpoint (the
+ * source of Claude Code's `/usage` screen). Newer responses carry a
+ * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
+ * buckets — both shapes are read, the array winning when it has entries.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchClaudeUsage(session: ClaudeSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 /** Constructor dependencies for {@link ClaudeAdapter}. */
 export interface ClaudeAdapterOptions {
     models: readonly ModelEntry[];

package/lib/providers/claude.js

@@ -147,6 +147,95 @@ export function isClaudePermanentRefreshError(error) {
     return error instanceof OAuthEndpointError
         && (error.oauthCode === 'invalid_grant' || error.oauthCode === 'invalid_token');
 }
+export const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+/** RFC3339 `resets_at` value → epoch ms, or undefined when absent/unparsable. */
+function claudeResetsAt(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Map one legacy `{utilization, resets_at}` bucket; undefined when null or unusable. */
+function claudeLegacyWindow(value, kind, scope) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const bucket = value;
+    if (typeof bucket.utilization !== 'number' || !Number.isFinite(bucket.utilization))
+        return undefined;
+    const resetsAt = claudeResetsAt(bucket.resets_at);
+    return {
+        kind,
+        ...scope === undefined ? {} : { scope },
+        usedPercent: bucket.utilization,
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
+}
+/** Map the modern `limits` array; empty when absent or carrying nothing usable. */
+function claudeLimitsWindows(value) {
+    if (!Array.isArray(value))
+        return [];
+    const windows = [];
+    for (const raw of value) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const entry = raw;
+        if (typeof entry.percent !== 'number' || !Number.isFinite(entry.percent))
+            continue;
+        const kind = entry.kind === 'session'
+            ? 'session'
+            : entry.kind === 'weekly_all' || entry.kind === 'weekly_scoped' ? 'weekly' : 'other';
+        const scope = entry.scope?.model?.display_name;
+        const resetsAt = claudeResetsAt(entry.resets_at);
+        windows.push({
+            kind,
+            ...typeof scope === 'string' && scope.length > 0 ? { scope } : {},
+            usedPercent: entry.percent,
+            ...resetsAt === undefined ? {} : { resetsAt },
+        });
+    }
+    return windows;
+}
+/**
+ * Fetch the claude subscription usage from the OAuth usage endpoint (the
+ * source of Claude Code's `/usage` screen). Newer responses carry a
+ * structured `limits` array; older ones the flat `five_hour`/`seven_day*`
+ * buckets — both shapes are read, the array winning when it has entries.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export async function fetchClaudeUsage(session, fetchFn = fetch, signal) {
+    const response = await fetchFn(CLAUDE_USAGE_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'anthropic-beta': 'oauth-2025-04-20',
+            // Unrecognized clients are aggressively rate-limited on this endpoint,
+            // so it presents as the CLI like every other subscription request.
+            'user-agent': CLAUDE_CLI_USER_AGENT,
+            'accept': 'application/json',
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'claude usage');
+    const payload = await response.json();
+    const modern = claudeLimitsWindows(payload.limits);
+    if (modern.length > 0)
+        return { supported: true, windows: modern };
+    const windows = [];
+    const legacy = [
+        claudeLegacyWindow(payload.five_hour, 'session'),
+        claudeLegacyWindow(payload.seven_day, 'weekly'),
+        claudeLegacyWindow(payload.seven_day_opus, 'weekly', 'Opus'),
+        claudeLegacyWindow(payload.seven_day_sonnet, 'weekly', 'Sonnet'),
+    ];
+    for (const window of legacy) {
+        if (window !== undefined)
+            windows.push(window);
+    }
+    return { supported: true, windows };
+}
 /** The Claude 4.5 family accepts image input. */
 const CLAUDE_MODALITIES = ['text', 'image'];
 /** Claude wire adapter: one instance serves the `claude` provider route. */

package/lib/providers/codex.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { CodexSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { DiscoveredModel, FetchFn, ModelEntry } from './common.js';
+import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 export declare const CODEX_AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
 export declare const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
@@ -53,6 +53,18 @@ export declare function refreshCodex(session: CodexSession): Promise<CodexSessio
  * @returns true when re-login is the only fix.
  */
 export declare function isCodexPermanentRefreshError(error: unknown): boolean;
+export declare const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+/**
+ * Fetch the codex subscription usage from the ChatGPT backend wham/usage
+ * endpoint (the source of the codex CLI `/status` rate-limit lines). The
+ * primary window is the rolling session (5-hour) lane, the secondary window
+ * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchCodexUsage(session: CodexSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 export declare const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";
 /**
  * Client version sent on the /models catalog request. The backend gates the

package/lib/providers/codex.js

@@ -188,6 +188,62 @@ export function isCodexPermanentRefreshError(error) {
         && error.oauthCode !== undefined
         && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
+export const CODEX_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+/** Map one wham/usage window into a {@link UsageWindow}; undefined when unusable. */
+function codexUsageWindow(value, kind) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const window = value;
+    if (typeof window.used_percent !== 'number' || !Number.isFinite(window.used_percent))
+        return undefined;
+    let resetsAt;
+    if (typeof window.reset_at === 'number' && window.reset_at > 0) {
+        resetsAt = window.reset_at * 1000;
+    }
+    else if (typeof window.reset_after_seconds === 'number' && window.reset_after_seconds > 0) {
+        resetsAt = Date.now() + window.reset_after_seconds * 1000;
+    }
+    return { kind, usedPercent: window.used_percent, ...resetsAt === undefined ? {} : { resetsAt } };
+}
+/**
+ * Fetch the codex subscription usage from the ChatGPT backend wham/usage
+ * endpoint (the source of the codex CLI `/status` rate-limit lines). The
+ * primary window is the rolling session (5-hour) lane, the secondary window
+ * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export async function fetchCodexUsage(session, fetchFn = fetch, signal) {
+    const response = await fetchFn(CODEX_USAGE_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'chatgpt-account-id': session.accountId,
+            'originator': 'codex_cli_rs',
+            'accept': 'application/json',
+            ...attributionHeaders(),
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'codex usage');
+    const payload = await response.json();
+    const windows = [];
+    const primary = codexUsageWindow(payload.rate_limit?.primary_window, 'session');
+    const secondary = codexUsageWindow(payload.rate_limit?.secondary_window, 'weekly');
+    if (primary !== undefined)
+        windows.push(primary);
+    if (secondary !== undefined)
+        windows.push(secondary);
+    return {
+        supported: true,
+        windows,
+        ...typeof payload.plan_type === 'string' && payload.plan_type.length > 0
+            ? { plan: payload.plan_type }
+            : {},
+    };
+}
 export const CODEX_MODELS_URL = 'https://chatgpt.com/backend-api/codex/models';
 /**
  * Client version sent on the /models catalog request. The backend gates the
@@ -295,7 +351,10 @@ export class CodexAdapter extends LlmAdapter {
         if (!this.options.discovery)
             return this.staticModels(provider);
         try {
-            const discovered = await this.catalog.get(() => fetchCodexModels(session, this.options.fetchFn));
+            // The fetcher runs only on a cache miss, and resolves the session
+            // through the refresh-aware path so an expired access token renews here
+            // instead of failing discovery into the static fallback.
+            const discovered = await this.catalog.get(async () => fetchCodexModels(await this.options.tokens.session(), this.options.fetchFn));
             return discovered.map(model => ({
                 provider,
                 id: model.id,
@@ -305,6 +364,11 @@ export class CodexAdapter extends LlmAdapter {
             }));
         }
         catch (error) {
+            // A permanent refresh failure deletes the stored session: the provider
+            // is logged out, so hide it instead of showing a stale static catalog.
+            if (error instanceof LlmError
+                && (error.code === 'MISSING_CREDENTIAL' || error.code === 'INVALID_CREDENTIAL'))
+                return [];
             if (error instanceof OAuthEndpointError && error.status === 401)
                 this.catalog.invalidate();
             this.options.onWarn?.(`codex model discovery failed; using the built-in catalog (${errorChain(error)})`);

package/lib/providers/common.d.ts

@@ -135,6 +135,26 @@ export declare class TokenManager<S extends TimedSession> {
 }
 /** Fetch signature adapters accept for discovery calls (injectable for tests). */
 export type FetchFn = typeof fetch;
+/** One rate-limit window reported by a provider's usage endpoint. */
+export interface UsageWindow {
+    /** Window kind: `session` for the short rolling window, `weekly` for the 7-day one. */
+    kind: 'session' | 'weekly' | 'other';
+    /** Model scope for model-specific windows (e.g. `Opus`), when the provider names one. */
+    scope?: string;
+    /** Percent of the window already consumed (0–100). */
+    usedPercent: number;
+    /** Epoch milliseconds at which the window resets, when the provider discloses it. */
+    resetsAt?: number;
+}
+/** Subscription usage of one provider, as served by the `usage` RPC endpoint. */
+export interface ProviderUsage {
+    /** False when the provider has no usage endpoint (grok); windows are absent then. */
+    supported: boolean;
+    /** Usage windows in display order. */
+    windows?: UsageWindow[];
+    /** Plan name the usage endpoint reported, when present. */
+    plan?: string;
+}
 /** One model discovered from a provider's live model-list endpoint. */
 export interface DiscoveredModel {
     /** Wire model id. */

package/lib/providers/grok.d.ts

@@ -9,7 +9,7 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { GrokSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { DiscoveredModel, FetchFn, ModelEntry } from './common.js';
+import type { DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
 export declare const GROK_API_URL = "https://api.x.ai/v1/responses";
@@ -31,6 +31,13 @@ export declare function grokDiscovery(): Promise<GrokDiscovery>;
  * @returns the flow spec for one attempt.
  */
 export declare function grokFlow(): Promise<FlowSpec>;
+/**
+ * The subscription tier encoded in a grok access token's `tier` claim (no
+ * verification — same trust posture as the other claim reads).
+ * @param accessToken - the stored access token.
+ * @returns the display tier name, or undefined when the claim is absent.
+ */
+export declare function grokTierName(accessToken: string): string | undefined;
 /**
  * Exchange an authorization code for a grok session (form-encoded grant that
  * echoes the PKCE challenge as well as the verifier, per the xAI flow).
@@ -54,6 +61,23 @@ export declare function refreshGrok(session: GrokSession): Promise<GrokSession>;
  * @returns true when re-login is the only fix.
  */
 export declare function isGrokPermanentRefreshError(error: unknown): boolean;
+/**
+ * The Grok Build CLI chat proxy's billing endpoint (the source of the CLI's
+ * `/usage` "Usage limit" panel; see xai-org/grok-build
+ * `extensions/billing.rs`). Forwards to the backend `GetGrokCreditsConfig`.
+ */
+export declare const GROK_BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+/**
+ * Fetch the grok subscription usage from the Grok Build CLI chat proxy. The
+ * newer credits config carries a ready-made percentage plus the current
+ * (typically weekly) period; the legacy shape carries cent-valued
+ * `monthlyLimit`/`used`, from which the percentage is derived.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export declare function fetchGrokUsage(session: GrokSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
 export declare const GROK_MODELS_URL = "https://api.x.ai/v1/models";
 /**
  * Fetch the live grok model list.

package/lib/providers/grok.js

@@ -80,6 +80,34 @@ export async function grokFlow() {
         },
     };
 }
+/**
+ * Display names for the numeric `tier` claim xAI stamps on OAuth access
+ * tokens (the `prod_auth.SubscriptionTier` proto enum; the mapping mirrors
+ * grok-build's `jwt_tier_claim`). Unknown values fall through to the raw
+ * number so a future tier still shows something.
+ */
+const GROK_TIER_NAMES = {
+    0: 'Free',
+    1: 'SuperGrok',
+    2: 'X Basic',
+    3: 'X Premium',
+    4: 'X Premium+',
+    5: 'SuperGrok Heavy',
+    6: 'SuperGrok Lite',
+    7: 'SuperGrok Plus',
+};
+/**
+ * The subscription tier encoded in a grok access token's `tier` claim (no
+ * verification — same trust posture as the other claim reads).
+ * @param accessToken - the stored access token.
+ * @returns the display tier name, or undefined when the claim is absent.
+ */
+export function grokTierName(accessToken) {
+    const tier = decodeJwtPayload(accessToken)?.tier;
+    if (typeof tier !== 'number' || !Number.isInteger(tier))
+        return undefined;
+    return GROK_TIER_NAMES[tier] ?? String(tier);
+}
 /** Pick a display account from an id token's claims. */
 function grokAccount(idToken) {
     const payload = idToken === undefined ? undefined : decodeJwtPayload(idToken);
@@ -172,6 +200,73 @@ export async function refreshGrok(session) {
 export function isGrokPermanentRefreshError(error) {
     return error instanceof OAuthEndpointError && error.oauthCode === 'invalid_grant';
 }
+/**
+ * The Grok Build CLI chat proxy's billing endpoint (the source of the CLI's
+ * `/usage` "Usage limit" panel; see xai-org/grok-build
+ * `extensions/billing.rs`). Forwards to the backend `GetGrokCreditsConfig`.
+ */
+export const GROK_BILLING_URL = 'https://cli-chat-proxy.grok.com/v1/billing?format=credits';
+/** RFC3339 timestamp → epoch ms, or undefined when absent/unparsable. */
+function grokResetsAt(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Fetch the grok subscription usage from the Grok Build CLI chat proxy. The
+ * newer credits config carries a ready-made percentage plus the current
+ * (typically weekly) period; the legacy shape carries cent-valued
+ * `monthlyLimit`/`used`, from which the percentage is derived.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation from the RPC transport.
+ * @returns the mapped usage snapshot.
+ */
+export async function fetchGrokUsage(session, fetchFn = fetch, signal) {
+    const response = await fetchFn(GROK_BILLING_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            // The proxy only honors bearer tokens presented as the Grok CLI.
+            'x-xai-token-auth': 'xai-grok-cli',
+            'accept': 'application/json',
+            ...attributionHeaders(),
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'grok billing');
+    const payload = await response.json();
+    const config = typeof payload.config === 'object' && payload.config !== null ? payload.config : {};
+    const windows = [];
+    if (typeof config.creditUsagePercent === 'number' && Number.isFinite(config.creditUsagePercent)) {
+        const kind = config.currentPeriod?.type === 'USAGE_PERIOD_TYPE_WEEKLY'
+            ? 'weekly'
+            : 'other';
+        const resetsAt = grokResetsAt(config.currentPeriod?.end);
+        windows.push({ kind, usedPercent: config.creditUsagePercent, ...resetsAt === undefined ? {} : { resetsAt } });
+    }
+    else if (typeof config.monthlyLimit?.val === 'number' && config.monthlyLimit.val > 0) {
+        const used = typeof config.used?.val === 'number' ? config.used.val : 0;
+        const resetsAt = grokResetsAt(config.billingPeriodEnd);
+        windows.push({
+            kind: 'other',
+            usedPercent: (used / config.monthlyLimit.val) * 100,
+            ...resetsAt === undefined ? {} : { resetsAt },
+        });
+    }
+    // The upstream billing response rarely carries `subscriptionTier` (the CLI
+    // enriches it locally from its settings cache), so the access token's
+    // `tier` claim is the working fallback.
+    const plan = typeof payload.subscriptionTier === 'string' && payload.subscriptionTier.length > 0
+        ? payload.subscriptionTier
+        : grokTierName(session.accessToken);
+    return {
+        supported: true,
+        windows,
+        ...plan === undefined ? {} : { plan },
+    };
+}
 export const GROK_MODELS_URL = 'https://api.x.ai/v1/models';
 /**
  * Input modalities for one grok model: chat models (grok-4 family) accept
@@ -252,7 +347,10 @@ export class GrokAdapter extends LlmAdapter {
         if (!this.options.discovery)
             return this.staticModels(provider);
         try {
-            const discovered = await this.catalog.get(() => fetchGrokModels(session, this.options.fetchFn));
+            // The fetcher runs only on a cache miss, and resolves the session
+            // through the refresh-aware path so an expired access token renews here
+            // instead of failing discovery into the static fallback.
+            const discovered = await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn));
             return discovered.map(model => ({
                 provider,
                 id: model.id,
@@ -261,6 +359,11 @@ export class GrokAdapter extends LlmAdapter {
             }));
         }
         catch (error) {
+            // A permanent refresh failure deletes the stored session: the provider
+            // is logged out, so hide it instead of showing a stale static catalog.
+            if (error instanceof LlmError
+                && (error.code === 'MISSING_CREDENTIAL' || error.code === 'INVALID_CREDENTIAL'))
+                return [];
             if (error instanceof OAuthEndpointError && error.status === 401)
                 this.catalog.invalidate();
             this.options.onWarn?.(`grok model discovery failed; using the built-in catalog (${errorChain(error)})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscriptions",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Use ChatGPT (Codex), Claude, and Grok (X Premium) subscriptions as DeepSeek Harness LLM providers, with OAuth login from the web Settings page",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,12 @@
       ]
     }
   },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "test": "tsc -p tsconfig.test.json && node --test lib-test/test/",
+    "prepare": "tsdown -c tsdown.prepare.config.ts",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-attachment": "^0.1.0-rc.5",
@@ -75,9 +81,5 @@
     "react": "^18.2.0",
     "tsdown": "^0.15.0",
     "typescript": "^5.8.0"
-  },
-  "scripts": {
-    "build": "tsc && tsdown",
-    "test": "tsc -p tsconfig.test.json && node --test lib-test/test/"
   }
-}
+}