sidekick-shared 0.28.2 → 0.28.3

package/dist/multiProviderQuotaService.js

@@ -293,7 +293,7 @@ class MultiProviderQuotaService {
             await this.refreshPeakHours();
             const creds = await this.readClaudeCredentials();
             if (!creds) {
-                this.handleUnavailableState(makeUnavailableClaudeState('Renew your Claude Max OAuth to view quota', 'auth'));
+                this.handleUnavailableState(makeUnavailableClaudeState('Renew your Claude login to view quota', 'auth'));
                 return;
             }
             const state = await this.fetchClaudeQuota(creds.accessToken);

package/dist/quota.d.ts

@@ -2,7 +2,7 @@ import type { QuotaProviderId } from './providerIds';
 export { QUOTA_PROVIDER_IDS } from './providerIds';
 export type { QuotaProviderId } from './providerIds';
 /**
- * Stateless quota fetcher for Claude Max subscription usage.
+ * Stateless quota fetcher for Claude subscription usage (Pro, Max, Ultra).
  *
  * Calls the Anthropic OAuth usage endpoint and returns utilization data.
  * Polling / eventing is the caller's responsibility.
@@ -12,6 +12,67 @@ export interface QuotaWindow {
     utilization: number;
     /** ISO timestamp when the window resets */
     resetsAt: string;
+    /**
+     * True when the provider reported that this window does not exist for the
+     * account — Claude Ultra has no five-hour session limit (`five_hour: null`),
+     * and a Codex plan can report a primary window without a secondary one.
+     * `utilization`/`resetsAt` are then `0`/`''` placeholders, so readers that
+     * predate the flag keep their old behaviour. Absent or false: the window
+     * applies (it may still be idle, with no reset time yet).
+     */
+    absent?: boolean;
+    /** Window length in milliseconds when the provider reports it (e.g. Codex `window_minutes`). */
+    windowMs?: number;
+}
+/**
+ * One usage meter as reported by the Claude usage endpoint's `limits[]` array.
+ * The server decides which meters exist and in what order; classify on
+ * `kind`, never on `label`.
+ */
+export interface QuotaLimitRow {
+    /** Server meter kind, e.g. `session`, `weekly_all`, `weekly_scoped`. */
+    kind: string;
+    /** Server row group, e.g. `session` or `weekly`. */
+    group: string;
+    /** Display label derived from kind, group, and scope, e.g. `7-Day (Fable)`. */
+    label: string;
+    /** Share of the window used, 0–100. */
+    utilization: number;
+    /** ISO timestamp when the window resets; empty when unknown. */
+    resetsAt: string;
+    /** Window length in milliseconds, derived from the group when known. */
+    windowMs?: number;
+    /** Projected utilization at reset (percentage, capped at 200). */
+    projected?: number;
+    /** Model the meter is scoped to (server display name), e.g. `Fable`. */
+    scopeModel?: string;
+    /** Surface the meter is scoped to (server display name). */
+    scopeSurface?: string;
+    /** Server severity for colouring: `normal`, `warning`, `critical`. */
+    severity?: string;
+    /** The server's headline pick — the row a single-value indicator shows. */
+    isActive?: boolean;
+    /** For scoped weekly meters: how much of the all-models weekly limit this meter may use. */
+    allowancePercentOfWeekly?: number;
+    /** For scoped weekly meters: how much of the all-models weekly limit it has used. */
+    usedPercentOfWeekly?: number;
+}
+/** Claude extra-usage (usage credits) spend for the billing period. */
+export interface QuotaExtraUsage {
+    /** Whether extra usage can currently cover requests. */
+    enabled: boolean;
+    /** Monthly cap in minor units of `currency` (cents for USD); null when uncapped. */
+    monthlyLimit: number | null;
+    /** Spend so far this period, in minor units of `currency`. */
+    usedCredits: number | null;
+    /** Share of the monthly cap used, 0–100. */
+    utilization: number | null;
+    /** ISO 4217 currency code, e.g. `USD`. */
+    currency?: string;
+    /** Number of minor-unit decimals (2 for USD). */
+    decimalPlaces?: number;
+    /** Server reason extra usage is off, e.g. `out_of_credits`. */
+    disabledReason?: string;
 }
 export interface CodexResetCredit {
     title?: string;
@@ -80,8 +141,23 @@ export interface QuotaState {
     resetCredits?: CodexResetCreditsSnapshot;
     /** Provider-specific plan type */
     planType?: string;
+    /** Display name of the subscription plan, e.g. `Pro`, `Max`, `Ultra`. */
+    planLabel?: string;
     /** Provider-specific rate-limit reached reason */
     rateLimitReachedType?: string;
+    /**
+     * Every usage meter the provider reported, in server order (Claude's
+     * `limits[]`). The `session` and `weekly_all` rows duplicate `fiveHour` and
+     * `sevenDay`; use `extraQuotaRows()` for the rest (e.g. a Fable weekly cap).
+     */
+    limits?: QuotaLimitRow[];
+    /** Claude extra-usage (usage credits) spend, when the plan reports it. */
+    extraUsage?: QuotaExtraUsage;
+}
+/** Plan facts read from the Claude OAuth credentials. */
+export interface ClaudePlanInfo {
+    subscriptionType?: string | null;
+    rateLimitTier?: string | null;
 }
 export declare const FIVE_HOUR_WINDOW_MS: number;
 export declare const SEVEN_DAY_WINDOW_MS: number;
@@ -93,6 +169,39 @@ export declare const QUOTA_FRESH_MAX_AGE_MS: number;
 export declare const QUOTA_AGING_MAX_AGE_MS: number;
 /** Classify a cached sample's age. Non-finite or negative ages count as stale. */
 export declare function classifyQuotaFreshness(ageMs: number | undefined): QuotaFreshness;
+/** Whether the provider reports this window for the account at all. */
+export declare function quotaWindowApplies(window: QuotaWindow | null | undefined): boolean;
+/** Whether the window applies and carries a reading worth showing (a reset time or any usage). */
+export declare function quotaWindowHasData(window: QuotaWindow | null | undefined): boolean;
+/**
+ * True when every window of a sample that has a known reset time has already
+ * reset by `nowMs`. Such a sample says nothing about current usage — showing
+ * it as live would print old percentages with "resets now". Samples without
+ * any reset time are never considered expired.
+ */
+export declare function quotaSampleExpired(quota: QuotaState, nowMs?: number): boolean;
+/**
+ * Human label for a window length: `5-Hour`, `Daily`, `Weekly`, `30-Day`, …
+ * Returns `fallback` when the length is unknown or not a whole number of hours.
+ */
+export declare function quotaWindowLabel(windowMs: number | undefined, fallback: string): string;
+/** Compact label for a window length: `5h`, `1d`, `7d`. Returns `fallback` when unknown. */
+export declare function quotaWindowShortLabel(windowMs: number | undefined, fallback: string): string;
+/**
+ * The reported meters that `fiveHour` and `sevenDay` do not already show —
+ * per-model or per-surface weekly caps and any future meter kind.
+ */
+export declare function extraQuotaRows(quota: Pick<QuotaState, 'limits'>): QuotaLimitRow[];
+/**
+ * Display name for a Claude subscription. The 20× tier was renamed Ultra and
+ * the 5× tier Max on 2026-10-30; credentials keep the old tier ids.
+ */
+export declare function claudePlanLabel(plan: ClaudePlanInfo | null | undefined): string | undefined;
+/**
+ * One-line extra-usage summary, e.g. `$12.40 of $200.00 used` or
+ * `$0.00 of $200.00 used · off (out of credits)`.
+ */
+export declare function formatExtraUsage(extra: QuotaExtraUsage): string;
 /** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
 export declare function formatQuotaAge(ageMs: number | undefined): string;
 export interface QuotaProjectionInput {
@@ -112,6 +221,25 @@ export declare function withQuotaProjections<T extends QuotaState>(state: T, opt
     sevenDayWindowMs?: number;
     capturedAt?: string;
 }): T;
+/**
+ * Normalize a Claude OAuth usage-endpoint body into a `QuotaState`.
+ *
+ * - `five_hour`/`seven_day` that are null or missing become `absent` windows
+ *   (Ultra plans have no five-hour session limit), unless `limits[]` carries
+ *   the matching `session`/`weekly_all` meter.
+ * - `limits[]` is kept verbatim as `limits` (with derived labels, window
+ *   lengths, and projections); older servers' `seven_day_opus` /
+ *   `seven_day_sonnet` / `seven_day_overage_included` fill it instead.
+ * - `extra_usage` becomes `extraUsage`.
+ *
+ * Bodies in the original two-window shape produce exactly the state they did
+ * before these fields existed.
+ */
+export declare function quotaStateFromClaudeUsagePayload(payload: unknown, options?: {
+    capturedAt?: string;
+}): QuotaState;
+/** Stamp `planType` / `planLabel` from Claude credential plan facts (no-op without them). */
+export declare function withClaudePlan<T extends QuotaState>(state: T, plan: ClaudePlanInfo | null | undefined): T;
 /**
  * Fetch current quota utilization from the Anthropic OAuth usage API.
  *
@@ -120,8 +248,10 @@ export declare function withQuotaProjections<T extends QuotaState>(state: T, opt
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
  * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
+ * @param options.plan - Plan facts from the same credentials; stamps `planType` and `planLabel`
  * @returns QuotaState with utilization data and elapsed-time projections
  */
 export declare function fetchQuota(accessToken: string, options?: {
     fetchImpl?: typeof fetch;
+    plan?: ClaudePlanInfo | null;
 }): Promise<QuotaState>;

package/dist/quota.js

@@ -2,9 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QUOTA_AGING_MAX_AGE_MS = exports.QUOTA_FRESH_MAX_AGE_MS = exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
 exports.classifyQuotaFreshness = classifyQuotaFreshness;
+exports.quotaWindowApplies = quotaWindowApplies;
+exports.quotaWindowHasData = quotaWindowHasData;
+exports.quotaSampleExpired = quotaSampleExpired;
+exports.quotaWindowLabel = quotaWindowLabel;
+exports.quotaWindowShortLabel = quotaWindowShortLabel;
+exports.extraQuotaRows = extraQuotaRows;
+exports.claudePlanLabel = claudePlanLabel;
+exports.formatExtraUsage = formatExtraUsage;
 exports.formatQuotaAge = formatQuotaAge;
 exports.projectQuotaWindow = projectQuotaWindow;
 exports.withQuotaProjections = withQuotaProjections;
+exports.quotaStateFromClaudeUsagePayload = quotaStateFromClaudeUsagePayload;
+exports.withClaudePlan = withClaudePlan;
 exports.fetchQuota = fetchQuota;
 var providerIds_1 = require("./providerIds");
 Object.defineProperty(exports, "QUOTA_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.QUOTA_PROVIDER_IDS; } });
@@ -27,6 +37,126 @@ function classifyQuotaFreshness(ageMs) {
         return 'aging';
     return 'stale';
 }
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+/** Whether the provider reports this window for the account at all. */
+function quotaWindowApplies(window) {
+    return Boolean(window) && window?.absent !== true;
+}
+/** Whether the window applies and carries a reading worth showing (a reset time or any usage). */
+function quotaWindowHasData(window) {
+    if (!window || window.absent === true)
+        return false;
+    return Boolean(window.resetsAt) || window.utilization > 0;
+}
+function usableWindowMs(windowMs) {
+    return typeof windowMs === 'number' && Number.isFinite(windowMs) && windowMs > 0
+        ? windowMs
+        : undefined;
+}
+/**
+ * True when every window of a sample that has a known reset time has already
+ * reset by `nowMs`. Such a sample says nothing about current usage — showing
+ * it as live would print old percentages with "resets now". Samples without
+ * any reset time are never considered expired.
+ */
+function quotaSampleExpired(quota, nowMs = Date.now()) {
+    const resets = [quota.fiveHour, quota.sevenDay]
+        .filter((window) => !window.absent && window.resetsAt)
+        .map((window) => Date.parse(window.resetsAt))
+        .filter((ms) => Number.isFinite(ms));
+    return resets.length > 0 && resets.every((ms) => ms <= nowMs);
+}
+/**
+ * Human label for a window length: `5-Hour`, `Daily`, `Weekly`, `30-Day`, …
+ * Returns `fallback` when the length is unknown or not a whole number of hours.
+ */
+function quotaWindowLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms === DAY_MS)
+        return 'Daily';
+    if (ms === 7 * DAY_MS)
+        return 'Weekly';
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}-Day`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}-Hour`;
+    return fallback;
+}
+/** Compact label for a window length: `5h`, `1d`, `7d`. Returns `fallback` when unknown. */
+function quotaWindowShortLabel(windowMs, fallback) {
+    const ms = usableWindowMs(windowMs);
+    if (ms === undefined)
+        return fallback;
+    if (ms % DAY_MS === 0)
+        return `${ms / DAY_MS}d`;
+    if (ms % HOUR_MS === 0)
+        return `${ms / HOUR_MS}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return fallback;
+}
+/**
+ * The reported meters that `fiveHour` and `sevenDay` do not already show —
+ * per-model or per-surface weekly caps and any future meter kind.
+ */
+function extraQuotaRows(quota) {
+    return (quota.limits ?? []).filter((row) => row.kind !== 'session' && row.kind !== 'weekly_all');
+}
+/**
+ * Display name for a Claude subscription. The 20× tier was renamed Ultra and
+ * the 5× tier Max on 2026-10-30; credentials keep the old tier ids.
+ */
+function claudePlanLabel(plan) {
+    const tier = plan?.rateLimitTier?.trim().toLowerCase() ?? '';
+    if (tier.includes('ultra') || tier.includes('max_20x'))
+        return 'Ultra';
+    if (tier.includes('max_5x'))
+        return 'Max';
+    const subscription = plan?.subscriptionType?.trim().toLowerCase();
+    if (!subscription)
+        return undefined;
+    return subscription.charAt(0).toUpperCase() + subscription.slice(1);
+}
+function formatMinorUnits(amount, currency, decimals) {
+    const value = amount / 10 ** decimals;
+    if (currency) {
+        try {
+            return new Intl.NumberFormat('en-US', {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: decimals,
+            }).format(value);
+        }
+        catch {
+            return `${value.toFixed(decimals)} ${currency}`;
+        }
+    }
+    return value.toFixed(decimals);
+}
+/**
+ * One-line extra-usage summary, e.g. `$12.40 of $200.00 used` or
+ * `$0.00 of $200.00 used · off (out of credits)`.
+ */
+function formatExtraUsage(extra) {
+    const decimals = typeof extra.decimalPlaces === 'number' &&
+        Number.isInteger(extra.decimalPlaces) &&
+        extra.decimalPlaces >= 0 &&
+        extra.decimalPlaces <= 6
+        ? extra.decimalPlaces
+        : 2;
+    const used = formatMinorUnits(extra.usedCredits ?? 0, extra.currency, decimals);
+    const amount = extra.monthlyLimit !== null
+        ? `${used} of ${formatMinorUnits(extra.monthlyLimit, extra.currency, decimals)} used`
+        : `${used} used`;
+    if (extra.enabled)
+        return amount;
+    const reason = extra.disabledReason ? ` (${extra.disabledReason.replace(/_/g, ' ')})` : '';
+    return `${amount} · off${reason}`;
+}
 /** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
 function formatQuotaAge(ageMs) {
     if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
@@ -65,21 +195,21 @@ function withQuotaProjections(state, options = {}) {
         return state;
     const next = { ...state };
     const capturedAt = options.capturedAt ?? state.capturedAt;
-    if (next.projectedFiveHour == null) {
+    if (next.projectedFiveHour == null && !next.fiveHour.absent) {
         const projected = projectQuotaWindow({
             utilization: next.fiveHour.utilization,
             resetsAt: next.fiveHour.resetsAt,
-            windowMs: options.fiveHourWindowMs ?? exports.FIVE_HOUR_WINDOW_MS,
+            windowMs: options.fiveHourWindowMs ?? usableWindowMs(next.fiveHour.windowMs) ?? exports.FIVE_HOUR_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
             next.projectedFiveHour = projected;
     }
-    if (next.projectedSevenDay == null) {
+    if (next.projectedSevenDay == null && !next.sevenDay.absent) {
         const projected = projectQuotaWindow({
             utilization: next.sevenDay.utilization,
             resetsAt: next.sevenDay.resetsAt,
-            windowMs: options.sevenDayWindowMs ?? exports.SEVEN_DAY_WINDOW_MS,
+            windowMs: options.sevenDayWindowMs ?? usableWindowMs(next.sevenDay.windowMs) ?? exports.SEVEN_DAY_WINDOW_MS,
             capturedAt,
         });
         if (projected !== undefined)
@@ -87,6 +217,235 @@ function withQuotaProjections(state, options = {}) {
     }
     return next;
 }
+// ── Claude usage endpoint payload ──
+/** Hard cap on parsed meter rows, matching Claude Code's own bound. */
+const MAX_LIMIT_ROWS = 64;
+const MAX_LABEL_LENGTH = 128;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableFiniteNumber(value) {
+    return finiteNumber(value) ?? null;
+}
+function shortString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed && trimmed.length <= MAX_LABEL_LENGTH ? trimmed : undefined;
+}
+function displayName(value) {
+    return isRecord(value) ? shortString(value.display_name) : undefined;
+}
+function usageWindow(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        utilization: finiteNumber(value.utilization) ?? 0,
+        resetsAt: typeof value.resets_at === 'string' ? value.resets_at : '',
+    };
+}
+function absentWindow() {
+    return { utilization: 0, resetsAt: '', absent: true };
+}
+function windowMsForMeter(kind, group) {
+    if (kind === 'session' || group === 'session')
+        return exports.FIVE_HOUR_WINDOW_MS;
+    if (group === 'weekly' || kind.startsWith('weekly'))
+        return exports.SEVEN_DAY_WINDOW_MS;
+    if (group === 'daily')
+        return DAY_MS;
+    return undefined;
+}
+function titleCase(value) {
+    return value
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function meterLabel(kind, group, scope) {
+    let base;
+    if (kind === 'session' || group === 'session')
+        base = '5-Hour';
+    else if (group === 'weekly' || kind.startsWith('weekly'))
+        base = '7-Day';
+    else if (group === 'daily')
+        base = 'Daily';
+    else
+        base = titleCase(group || kind) || kind;
+    return scope ? `${base} (${scope})` : base;
+}
+function weeklySharesByIndex(value) {
+    const shares = new Map();
+    if (!Array.isArray(value))
+        return shares;
+    for (const entry of value.slice(0, MAX_LIMIT_ROWS)) {
+        if (!isRecord(entry))
+            continue;
+        const index = finiteNumber(entry.limit_index);
+        if (index === undefined || !Number.isInteger(index) || index < 0)
+            continue;
+        shares.set(index, {
+            allowance: finiteNumber(entry.allowance_percent_of_weekly),
+            used: finiteNumber(entry.used_percent_of_weekly),
+        });
+    }
+    return shares;
+}
+function buildMeterRow(input, capturedAt) {
+    const windowMs = windowMsForMeter(input.kind, input.group);
+    const projected = windowMs !== undefined
+        ? projectQuotaWindow({
+            utilization: input.utilization,
+            resetsAt: input.resetsAt,
+            windowMs,
+            capturedAt,
+        })
+        : undefined;
+    return {
+        kind: input.kind,
+        group: input.group,
+        label: meterLabel(input.kind, input.group, input.scopeModel ?? input.scopeSurface),
+        utilization: input.utilization,
+        resetsAt: input.resetsAt,
+        ...(windowMs !== undefined ? { windowMs } : {}),
+        ...(projected !== undefined ? { projected } : {}),
+        ...(input.scopeModel ? { scopeModel: input.scopeModel } : {}),
+        ...(input.scopeSurface ? { scopeSurface: input.scopeSurface } : {}),
+        ...(input.severity ? { severity: input.severity } : {}),
+        ...(input.isActive !== undefined ? { isActive: input.isActive } : {}),
+        ...(input.share?.allowance !== undefined
+            ? { allowancePercentOfWeekly: input.share.allowance }
+            : {}),
+        ...(input.share?.used !== undefined ? { usedPercentOfWeekly: input.share.used } : {}),
+    };
+}
+function parseLimitRows(value, sharesValue, capturedAt) {
+    if (!Array.isArray(value))
+        return undefined;
+    const shares = weeklySharesByIndex(sharesValue);
+    const rows = [];
+    value.slice(0, MAX_LIMIT_ROWS).forEach((raw, index) => {
+        if (!isRecord(raw))
+            return;
+        const kind = shortString(raw.kind);
+        const percent = finiteNumber(raw.percent);
+        if (!kind || percent === undefined)
+            return;
+        const scope = isRecord(raw.scope) ? raw.scope : undefined;
+        rows.push(buildMeterRow({
+            kind,
+            group: shortString(raw.group) ?? '',
+            utilization: Math.max(0, percent),
+            resetsAt: typeof raw.resets_at === 'string' ? raw.resets_at : '',
+            scopeModel: displayName(scope?.model),
+            scopeSurface: displayName(scope?.surface),
+            severity: shortString(raw.severity),
+            isActive: typeof raw.is_active === 'boolean' ? raw.is_active : undefined,
+            share: shares.get(index),
+        }, capturedAt));
+    });
+    return rows;
+}
+/** Pre-`limits[]` per-model weekly fields, read only when the server sends no `limits[]`. */
+const LEGACY_SCOPED_WEEKLY_FIELDS = [
+    ['seven_day_opus', 'Opus'],
+    ['seven_day_sonnet', 'Sonnet'],
+    ['seven_day_overage_included', 'Fable'],
+];
+function legacyScopedRows(data, capturedAt) {
+    const rows = [];
+    for (const [field, model] of LEGACY_SCOPED_WEEKLY_FIELDS) {
+        const window = usageWindow(data[field]);
+        if (!window)
+            continue;
+        rows.push(buildMeterRow({
+            kind: 'weekly_scoped',
+            group: 'weekly',
+            utilization: window.utilization,
+            resetsAt: window.resetsAt,
+            scopeModel: model,
+        }, capturedAt));
+    }
+    return rows;
+}
+function parseExtraUsage(value) {
+    if (!isRecord(value) || typeof value.is_enabled !== 'boolean')
+        return undefined;
+    const decimalPlaces = finiteNumber(value.decimal_places);
+    return {
+        enabled: value.is_enabled,
+        monthlyLimit: nullableFiniteNumber(value.monthly_limit),
+        usedCredits: nullableFiniteNumber(value.used_credits),
+        utilization: nullableFiniteNumber(value.utilization),
+        ...(shortString(value.currency) ? { currency: shortString(value.currency) } : {}),
+        ...(decimalPlaces !== undefined ? { decimalPlaces } : {}),
+        ...(shortString(value.disabled_reason)
+            ? { disabledReason: shortString(value.disabled_reason) }
+            : {}),
+    };
+}
+function windowFromMeter(row) {
+    return row ? { utilization: row.utilization, resetsAt: row.resetsAt } : null;
+}
+/**
+ * Normalize a Claude OAuth usage-endpoint body into a `QuotaState`.
+ *
+ * - `five_hour`/`seven_day` that are null or missing become `absent` windows
+ *   (Ultra plans have no five-hour session limit), unless `limits[]` carries
+ *   the matching `session`/`weekly_all` meter.
+ * - `limits[]` is kept verbatim as `limits` (with derived labels, window
+ *   lengths, and projections); older servers' `seven_day_opus` /
+ *   `seven_day_sonnet` / `seven_day_overage_included` fill it instead.
+ * - `extra_usage` becomes `extraUsage`.
+ *
+ * Bodies in the original two-window shape produce exactly the state they did
+ * before these fields existed.
+ */
+function quotaStateFromClaudeUsagePayload(payload, options = {}) {
+    const data = isRecord(payload) ? payload : {};
+    const capturedAt = options.capturedAt;
+    const parsedLimits = parseLimitRows(data.limits, data.weekly_scoped_shares, capturedAt);
+    const legacyRows = parsedLimits === undefined ? legacyScopedRows(data, capturedAt) : [];
+    const limits = parsedLimits ?? (legacyRows.length > 0 ? legacyRows : undefined);
+    const fiveHour = usageWindow(data.five_hour) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'session')) ??
+        absentWindow();
+    const sevenDay = usageWindow(data.seven_day) ??
+        windowFromMeter(parsedLimits?.find((row) => row.kind === 'weekly_all')) ??
+        absentWindow();
+    const extraUsage = parseExtraUsage(data.extra_usage);
+    const projectedFiveHour = fiveHour.absent
+        ? undefined
+        : projectQuotaWindow({ ...fiveHour, windowMs: exports.FIVE_HOUR_WINDOW_MS, capturedAt });
+    const projectedSevenDay = sevenDay.absent
+        ? undefined
+        : projectQuotaWindow({ ...sevenDay, windowMs: exports.SEVEN_DAY_WINDOW_MS, capturedAt });
+    return {
+        fiveHour,
+        sevenDay,
+        available: true,
+        projectedFiveHour,
+        projectedSevenDay,
+        ...(limits ? { limits } : {}),
+        ...(extraUsage ? { extraUsage } : {}),
+    };
+}
+/** Stamp `planType` / `planLabel` from Claude credential plan facts (no-op without them). */
+function withClaudePlan(state, plan) {
+    const planLabel = claudePlanLabel(plan);
+    const planType = plan?.subscriptionType?.trim() || undefined;
+    if (!planLabel && !planType)
+        return state;
+    return {
+        ...state,
+        ...(planType ? { planType } : {}),
+        ...(planLabel ? { planLabel } : {}),
+    };
+}
 /**
  * Helper to build an unavailable QuotaState.
  */
@@ -119,6 +478,7 @@ function parseRetryAfterMs(retryAfter) {
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
  * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
+ * @param options.plan - Plan facts from the same credentials; stamps `planType` and `planLabel`
  * @returns QuotaState with utilization data and elapsed-time projections
  */
 async function fetchQuota(accessToken, options = {}) {
@@ -161,26 +521,8 @@ async function fetchQuota(accessToken, options = {}) {
                 httpStatus: res.status,
             });
         }
-        const data = await res.json();
-        const fiveUtil = data.five_hour?.utilization ?? 0;
-        const sevenUtil = data.seven_day?.utilization ?? 0;
-        const fiveResetsAt = data.five_hour?.resets_at ?? '';
-        const sevenResetsAt = data.seven_day?.resets_at ?? '';
-        return {
-            fiveHour: { utilization: fiveUtil, resetsAt: fiveResetsAt },
-            sevenDay: { utilization: sevenUtil, resetsAt: sevenResetsAt },
-            available: true,
-            projectedFiveHour: projectQuotaWindow({
-                utilization: fiveUtil,
-                resetsAt: fiveResetsAt,
-                windowMs: exports.FIVE_HOUR_WINDOW_MS,
-            }),
-            projectedSevenDay: projectQuotaWindow({
-                utilization: sevenUtil,
-                resetsAt: sevenResetsAt,
-                windowMs: exports.SEVEN_DAY_WINDOW_MS,
-            }),
-        };
+        const state = quotaStateFromClaudeUsagePayload(await res.json());
+        return withClaudePlan(state, options.plan);
     }
     catch {
         return unavailableState('Network error', { failureKind: 'network' });

package/dist/quotaHistory.d.ts

@@ -6,6 +6,7 @@
  * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
  * trend visualisations over a 13-week window.
  */
+import type { QuotaState } from './quota';
 import type { RuntimeQuotaProviderId } from './providerIds';
 export type QuotaHistoryRuntimeProvider = RuntimeQuotaProviderId;
 export interface QuotaHistorySample {
@@ -13,13 +14,16 @@ export interface QuotaHistorySample {
     runtimeProvider: QuotaHistoryRuntimeProvider;
     providerId: string;
     workspaceId: string;
+    /** `absent` marks a window the plan does not have (e.g. Ultra's five-hour limit). */
     fiveHour: {
         utilization: number;
         resetsAt: string;
+        absent?: boolean;
     };
     sevenDay: {
         utilization: number;
         resetsAt: string;
+        absent?: boolean;
     };
     available: boolean;
     error?: string;
@@ -54,6 +58,12 @@ export interface QuotaHistoryDailyBucket {
  * Shared between the VS Code extension (workspace folder fsPath) and the CLI (process.cwd()).
  */
 export declare function getWorkspaceIdFromPath(workspacePath: string): string;
+/**
+ * Project a quota window onto the history-sample shape, keeping the `absent`
+ * marker so summaries and the derived snapshot do not mistake "no such
+ * window" for "0% used".
+ */
+export declare function quotaHistoryWindow(window: QuotaState['fiveHour']): QuotaHistorySample['fiveHour'];
 export declare function appendQuotaHistorySample(sample: QuotaHistorySample, options?: QuotaHistoryAppendOptions): Promise<void>;
 export declare function readQuotaHistoryRange(options: QuotaHistoryRangeOptions): Promise<QuotaHistorySample[]>;
 export declare function readQuotaHistoryDailyBuckets(options: QuotaHistoryRangeOptions): Promise<QuotaHistoryDailyBucket[]>;