usage-panel-opencode 0.0.0-stage → 0.1.0

package/src/core/snapshot.ts

@@ -0,0 +1,276 @@
+import type {
+  SubscriptionAccount,
+  UsageSnapshot,
+  UsageWindow,
+  WindowAvailability,
+  WindowKind,
+} from '../rpc';
+import { maskAccountId, type RedactionOptions, redactText, sanitizeText } from './redact';
+import { normalizeUsageWindow } from './windows';
+
+export interface HeaderUsage {
+  primaryUsedPercent?: number;
+  secondaryUsedPercent?: number;
+  planType?: string;
+}
+
+export interface NormalizeSnapshotInput {
+  account: SubscriptionAccount;
+  service?: unknown;
+  headers?: HeaderUsage | null;
+  fetchedAt?: number | null;
+  serviceFetchedAt?: number | null;
+  detail?: unknown;
+  sensitiveValues?: RedactionOptions['secrets'];
+  sensitiveAccountIds?: RedactionOptions['accountIds'];
+  now?: number;
+}
+
+const WINDOW_ORDER: Record<WindowKind, number> = { five_hour: 0, weekly: 1, other: 2 };
+const KNOWN_WINDOWS = ['five_hour', 'weekly'] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function safeAccount(
+  account: SubscriptionAccount,
+  redaction: Pick<RedactionOptions, 'secrets' | 'accountIds'>,
+): SubscriptionAccount {
+  const rawAccountId = account.accountId;
+  const accountId =
+    typeof rawAccountId === 'string' && /^…[A-Za-z0-9_-]{4}$/.test(rawAccountId)
+      ? rawAccountId
+      : maskAccountId(rawAccountId);
+  const label =
+    typeof account.label === 'string'
+      ? sanitizeText(redactText(account.label, redaction), 100)
+      : account.label;
+  const planHint =
+    typeof account.planHint === 'string'
+      ? redactText(account.planHint, { ...redaction, maxLength: 80 })
+      : account.planHint;
+
+  return {
+    credentialKind: account.credentialKind,
+    ...(label !== undefined ? { label } : {}),
+    ...(accountId ? { accountId } : {}),
+    ...(planHint !== undefined ? { planHint } : {}),
+    ...(account.organization !== undefined ? { organization: account.organization } : {}),
+    ...(account.expiresAt !== undefined ? { expiresAt: account.expiresAt } : {}),
+  };
+}
+
+function planInfo(
+  typeValue: unknown,
+  redaction: Pick<RedactionOptions, 'secrets' | 'accountIds'>,
+): { type: string; label: string } | null {
+  if (typeof typeValue !== 'string') return null;
+  const type = redactText(typeValue, { ...redaction, maxLength: 80 });
+  if (!type) return null;
+  const normalized = type.toLowerCase();
+  const labels: Record<string, string> = {
+    plus: 'Plus',
+    pro: 'Pro',
+    prolite: 'Pro',
+    team: 'Business',
+    business: 'Business',
+    enterprise: 'Enterprise',
+    edu: 'Edu',
+  };
+  return { type, label: labels[normalized] ?? type };
+}
+
+function percentage(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100
+    ? value
+    : null;
+}
+
+function availabilityOf(window: UsageWindow): WindowAvailability {
+  return window.availability ?? (window.applicable ? 'applicable' : 'not_applicable');
+}
+
+function unknownWindow(kind: 'five_hour' | 'weekly', source: 'service' | 'headers'): UsageWindow {
+  return {
+    kind,
+    label: kind === 'five_hour' ? '5 h' : 'Semanal',
+    applicable: false,
+    availability: 'unknown',
+    usedPercent: null,
+    remainingPercent: null,
+    resetsAt: null,
+    source,
+  };
+}
+
+function notApplicableWindow(kind: 'five_hour' | 'weekly'): UsageWindow {
+  return {
+    kind,
+    label: kind === 'five_hour' ? '5 h' : 'Semanal',
+    applicable: false,
+    availability: 'not_applicable',
+    usedPercent: null,
+    remainingPercent: null,
+    resetsAt: null,
+    source: 'service',
+  };
+}
+
+function headerWindow(kind: 'five_hour' | 'weekly', usedPercent: number | undefined): UsageWindow {
+  const used = percentage(usedPercent);
+  return {
+    kind,
+    label: kind === 'five_hour' ? '5 h' : 'Semanal',
+    applicable: used !== null,
+    availability: used === null ? 'unknown' : 'applicable',
+    usedPercent: used,
+    remainingPercent: used === null ? null : Math.round(100 - used),
+    resetsAt: null,
+    source: 'headers',
+  };
+}
+
+function mergeServiceDuplicate(previous: UsageWindow, candidate: UsageWindow): UsageWindow {
+  const preferred =
+    previous.usedPercent === null && candidate.usedPercent !== null ? candidate : previous;
+  return {
+    ...preferred,
+    resetsAt: previous.resetsAt ?? candidate.resetsAt,
+  };
+}
+
+function mergeHeaderValue(existing: UsageWindow, header: UsageWindow): UsageWindow {
+  const existingAvailability = availabilityOf(existing);
+  const headerAvailability = availabilityOf(header);
+
+  // A complete service response is authoritative about a window that does not apply.
+  if (existingAvailability === 'not_applicable') return existing;
+  if (headerAvailability !== 'applicable') return existing;
+
+  // Header observations fill missing evidence but never replace a valid service value or reset.
+  if (existingAvailability === 'unknown') return header;
+  if (existing.usedPercent === null) {
+    return {
+      ...existing,
+      applicable: true,
+      availability: 'applicable',
+      usedPercent: header.usedPercent,
+      remainingPercent: header.remainingPercent,
+    };
+  }
+  return existing;
+}
+
+/** Converts raw service data and/or allowlisted response headers to the stable public snapshot. */
+export function normalizeSnapshot(input: NormalizeSnapshotInput): UsageSnapshot {
+  const service = isRecord(input.service) ? input.service : null;
+  const rateLimit = service && isRecord(service.rate_limit) ? service.rate_limit : null;
+  const redaction: Pick<RedactionOptions, 'secrets' | 'accountIds'> = {
+    secrets: input.sensitiveValues,
+    accountIds: input.sensitiveAccountIds,
+  };
+  const now = typeof input.now === 'number' && Number.isFinite(input.now) ? input.now : Date.now();
+  const serviceFetchedAt =
+    typeof input.serviceFetchedAt === 'number' &&
+    Number.isFinite(input.serviceFetchedAt) &&
+    input.serviceFetchedAt >= 0
+      ? input.serviceFetchedAt
+      : typeof input.fetchedAt === 'number' &&
+          Number.isFinite(input.fetchedAt) &&
+          input.fetchedAt >= 0
+        ? input.fetchedAt
+        : now;
+  const windows = new Map<WindowKind, UsageWindow>();
+  const serviceAvailable = Boolean(rateLimit || planInfo(service?.plan_type, redaction));
+
+  if (rateLimit) {
+    let hasUnclassifiedWindow = false;
+    for (const key of ['primary_window', 'secondary_window'] as const) {
+      const entry = rateLimit[key];
+      if (entry === null) continue;
+      if (entry === undefined) {
+        if (Object.hasOwn(rateLimit, key)) hasUnclassifiedWindow = true;
+        continue;
+      }
+      const normalized = normalizeUsageWindow(entry, 'service', { now: serviceFetchedAt });
+      hasUnclassifiedWindow ||= normalized.kind === 'other';
+      // A malformed/unknown window has no trustworthy identity; known windows remain unknown
+      // below instead of publishing a fabricated "other" quota or treating it as not applicable.
+      if (normalized.kind === 'other' && availabilityOf(normalized) === 'unknown') continue;
+      const existing = windows.get(normalized.kind);
+      windows.set(
+        normalized.kind,
+        existing ? mergeServiceDuplicate(existing, normalized) : normalized,
+      );
+    }
+
+    // Missing fields in a partial payload are unknown. Only a complete pair of fields
+    // provides evidence that an omitted five-hour/weekly window is not applicable.
+    const complete =
+      Object.hasOwn(rateLimit, 'primary_window') && Object.hasOwn(rateLimit, 'secondary_window');
+    for (const kind of KNOWN_WINDOWS) {
+      if (windows.has(kind)) continue;
+      windows.set(
+        kind,
+        complete && !hasUnclassifiedWindow
+          ? notApplicableWindow(kind)
+          : unknownWindow(kind, 'service'),
+      );
+    }
+  } else if (serviceAvailable) {
+    for (const kind of KNOWN_WINDOWS) windows.set(kind, unknownWindow(kind, 'service'));
+  }
+
+  const headers = input.headers;
+  let headersUsed = false;
+  if (headers) {
+    for (const [kind, value] of [
+      ['five_hour', headers.primaryUsedPercent],
+      ['weekly', headers.secondaryUsedPercent],
+    ] as const) {
+      const candidate = headerWindow(kind, value);
+      const existing = windows.get(kind);
+      if (!existing) {
+        windows.set(kind, candidate);
+        headersUsed ||= availabilityOf(candidate) === 'applicable';
+      } else {
+        const merged = mergeHeaderValue(existing, candidate);
+        windows.set(kind, merged);
+        headersUsed ||= merged !== existing;
+      }
+    }
+  }
+
+  const servicePlan = planInfo(service?.plan_type, redaction);
+  const headerPlan = planInfo(headers?.planType, redaction);
+  const plan = servicePlan ?? headerPlan;
+  if (!servicePlan && headerPlan) headersUsed = true;
+
+  const orderedWindows = [...windows.values()].sort(
+    (left, right) => WINDOW_ORDER[left.kind] - WINDOW_ORDER[right.kind],
+  );
+  const originKind =
+    serviceAvailable && headersUsed
+      ? 'mixed'
+      : serviceAvailable
+        ? 'service'
+        : headersUsed
+          ? 'headers'
+          : 'none';
+  const fetchedAt =
+    typeof input.fetchedAt === 'number' && Number.isFinite(input.fetchedAt) && input.fetchedAt >= 0
+      ? input.fetchedAt
+      : null;
+  const detail =
+    typeof input.detail === 'string'
+      ? redactText(input.detail, { ...redaction, maxLength: 160 }) || null
+      : null;
+
+  return {
+    account: safeAccount(input.account, redaction),
+    plan,
+    windows: orderedWindows.slice(0, 8),
+    origin: { kind: originKind, fetchedAt, detail },
+  };
+}

package/src/core/state.ts

@@ -0,0 +1,42 @@
+import type { PanelError, PanelState, UsageSnapshot } from '../rpc';
+
+export interface PanelRuntimeState {
+  state: PanelState;
+  snapshot: UsageSnapshot | null;
+  error: PanelError | null;
+}
+
+export type PanelStateEvent =
+  | { type: 'success'; snapshot: UsageSnapshot }
+  | { type: 'failure'; error: PanelError }
+  | { type: 'no_subscription' }
+  | { type: 'needs_auth'; error?: PanelError }
+  | { type: 'account_changed' }
+  | { type: 'stop' };
+
+export function initialPanelState(): PanelRuntimeState {
+  return { state: 'loading', snapshot: null, error: null };
+}
+
+export function transitionPanelState(
+  current: PanelRuntimeState,
+  event: PanelStateEvent,
+): PanelRuntimeState {
+  switch (event.type) {
+    case 'success':
+      return { state: 'ready', snapshot: event.snapshot, error: null };
+    case 'failure':
+      return current.snapshot
+        ? { state: 'stale', snapshot: current.snapshot, error: event.error }
+        : { state: 'error', snapshot: null, error: event.error };
+    case 'no_subscription':
+      return { state: 'no_subscription', snapshot: null, error: null };
+    case 'needs_auth':
+      return current.snapshot
+        ? { state: 'stale', snapshot: current.snapshot, error: event.error ?? null }
+        : { state: 'needs_auth', snapshot: null, error: event.error ?? null };
+    case 'account_changed':
+    case 'stop':
+      return initialPanelState();
+  }
+}

package/src/core/usage-client.ts

@@ -0,0 +1,168 @@
+import { redactError } from './redact';
+
+export type UsageClientErrorKind =
+  | 'network'
+  | 'rate_limited'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'malformed'
+  | 'unknown';
+
+export interface UsageClientError {
+  kind: UsageClientErrorKind;
+  message: string;
+  retryAfterMs?: number;
+}
+
+export interface UsagePayload {
+  plan_type?: string;
+  rate_limit?: {
+    primary_window?: Record<string, unknown> | null;
+    secondary_window?: Record<string, unknown> | null;
+  };
+}
+
+export type UsageFetchResult =
+  | { ok: true; data: UsagePayload; fetchedAt: number }
+  | { ok: false; error: UsageClientError };
+
+export interface FetchUsageOptions {
+  accessToken: string;
+  accountId?: string | null;
+  signal?: AbortSignal;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  now?: () => number;
+  timeoutMs?: number;
+}
+
+const USAGE_ENDPOINT = 'https://chatgpt.com/backend-api/wham/usage';
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9_-]{4,64}$/;
+const USER_AGENT = 'usage-panel-opencode/0.1.0';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function pickWindow(value: unknown): Record<string, unknown> | null {
+  if (value === null) return null;
+  // Preserve explicit null as a known non-applicable value. Invalid/non-object payloads become
+  // empty objects so the normalizer can mark their availability unknown instead.
+  if (!isRecord(value)) return {};
+  const output: Record<string, unknown> = {};
+  for (const key of ['used_percent', 'limit_window_seconds', 'reset_at', 'reset_after_seconds']) {
+    const field = value[key];
+    if (typeof field === 'number' && Number.isFinite(field)) output[key] = field;
+  }
+  return output;
+}
+
+function pickPayload(value: unknown): UsagePayload | null {
+  if (!isRecord(value)) return null;
+  if (typeof value.plan_type !== 'string' && !isRecord(value.rate_limit)) return null;
+  const payload: UsagePayload = {};
+  if (typeof value.plan_type === 'string') payload.plan_type = value.plan_type;
+  if (isRecord(value.rate_limit)) {
+    payload.rate_limit = {
+      ...(Object.hasOwn(value.rate_limit, 'primary_window')
+        ? { primary_window: pickWindow(value.rate_limit.primary_window) }
+        : {}),
+      ...(Object.hasOwn(value.rate_limit, 'secondary_window')
+        ? { secondary_window: pickWindow(value.rate_limit.secondary_window) }
+        : {}),
+    };
+  }
+  return payload;
+}
+
+function retryAfterMs(value: string | null, now: number): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value.trim());
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
+}
+
+function safeFailure(kind: UsageClientErrorKind, retryAfter?: number): UsageFetchResult {
+  const messages: Record<UsageClientErrorKind, string> = {
+    network: 'No se pudo consultar el consumo de la suscripción.',
+    rate_limited: 'OpenAI limitó temporalmente las consultas de consumo.',
+    unauthorized: 'La conexión de OpenAI necesita volver a autenticarse.',
+    forbidden: 'OpenAI no permitió consultar el consumo de esta cuenta.',
+    malformed: 'OpenAI devolvió datos de consumo con un formato no reconocido.',
+    unknown: 'No se pudo obtener el consumo de la suscripción.',
+  };
+  return {
+    ok: false,
+    error: {
+      kind,
+      message: redactError(messages[kind]),
+      ...(retryAfter !== undefined ? { retryAfterMs: retryAfter } : {}),
+    },
+  };
+}
+
+/** Makes the sole permitted subscription request; response bodies and transport errors never escape raw. */
+export async function fetchUsage(options: FetchUsageOptions): Promise<UsageFetchResult> {
+  if (!options.accessToken) return safeFailure('unauthorized');
+
+  const controller = new AbortController();
+  const timeoutMs =
+    typeof options.timeoutMs === 'number' &&
+    Number.isFinite(options.timeoutMs) &&
+    options.timeoutMs > 0
+      ? options.timeoutMs
+      : 10_000;
+  const now = options.now ?? Date.now;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const abortFromCaller = () => controller.abort(options.signal?.reason);
+  if (options.signal?.aborted) abortFromCaller();
+  else options.signal?.addEventListener('abort', abortFromCaller, { once: true });
+
+  try {
+    const headers = new Headers({
+      accept: 'application/json',
+      authorization: `Bearer ${options.accessToken}`,
+      'user-agent': USER_AGENT,
+    });
+    if (typeof options.accountId === 'string' && ACCOUNT_ID_PATTERN.test(options.accountId)) {
+      headers.set('chatgpt-account-id', options.accountId);
+    }
+
+    const response = await (options.fetchImpl ?? fetch)(USAGE_ENDPOINT, {
+      method: 'GET',
+      // Never forward the bearer token or account id to a redirect destination.
+      redirect: 'error',
+      headers,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const nowMs = now();
+      if (response.status === 401) return safeFailure('unauthorized');
+      if (response.status === 403) return safeFailure('forbidden');
+      if (response.status === 429) {
+        return safeFailure(
+          'rate_limited',
+          retryAfterMs(response.headers.get('retry-after'), nowMs),
+        );
+      }
+      if (response.status >= 500) return safeFailure('network');
+      return safeFailure('unknown');
+    }
+
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      return safeFailure('malformed');
+    }
+    const data = pickPayload(body);
+    if (!data) return safeFailure('malformed');
+    return { ok: true, data, fetchedAt: now() };
+  } catch {
+    return safeFailure('network');
+  } finally {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener('abort', abortFromCaller);
+  }
+}

package/src/core/usage-headers.ts

@@ -0,0 +1,32 @@
+import { sanitizeText } from './redact';
+import type { HeaderUsage } from './snapshot';
+
+type HeaderSource = Headers | Record<string, string | undefined> | null | undefined;
+
+function getHeader(source: HeaderSource, name: string): string | null {
+  if (!source) return null;
+  if (source instanceof Headers) return source.get(name);
+  const match = Object.entries(source).find(([key]) => key.toLowerCase() === name);
+  return match?.[1] ?? null;
+}
+
+function readPercentage(value: string | null): number | undefined {
+  if (value === null || value.trim() === '') return undefined;
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 100 ? parsed : undefined;
+}
+
+/** Reads only the three documented x-codex-* response headers; request authorization is never inspected. */
+export function readUsageHeaders(source: HeaderSource): HeaderUsage | null {
+  const primaryUsedPercent = readPercentage(getHeader(source, 'x-codex-primary-used-percent'));
+  const secondaryUsedPercent = readPercentage(getHeader(source, 'x-codex-secondary-used-percent'));
+  const rawPlan = getHeader(source, 'x-codex-plan-type');
+  const planType = rawPlan ? sanitizeText(rawPlan, 80) : '';
+  const usage: HeaderUsage = {
+    ...(primaryUsedPercent !== undefined ? { primaryUsedPercent } : {}),
+    ...(secondaryUsedPercent !== undefined ? { secondaryUsedPercent } : {}),
+    ...(planType ? { planType } : {}),
+  };
+
+  return Object.keys(usage).length > 0 ? usage : null;
+}

package/src/core/windows.ts

@@ -0,0 +1,102 @@
+import type { UsageWindow, WindowKind, WindowSource } from '../rpc';
+
+export interface WindowNormalizationOptions {
+  now?: number;
+  kindHint?: WindowKind;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function numberField(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function classifyWindow(durationSeconds: number): WindowKind {
+  if (durationSeconds === 18_000) return 'five_hour';
+  if (durationSeconds === 604_800) return 'weekly';
+  return 'other';
+}
+
+function durationLabel(durationSeconds: number): string {
+  if (durationSeconds % 86_400 === 0) return `${durationSeconds / 86_400} d`;
+  if (durationSeconds % 3_600 === 0) return `${durationSeconds / 3_600} h`;
+  if (durationSeconds % 60 === 0) return `${durationSeconds / 60} min`;
+  return `${durationSeconds} s`;
+}
+
+function labelFor(kind: WindowKind, durationSeconds: number | null): string {
+  if (kind === 'five_hour') return '5 h';
+  if (kind === 'weekly') return 'Semanal';
+  return durationSeconds && durationSeconds > 0 ? durationLabel(durationSeconds) : 'Otra ventana';
+}
+
+function resetTime(record: Record<string, unknown>, now: number): number | null {
+  const resetAt = numberField(record, 'reset_at');
+  if (resetAt !== null && resetAt >= 0) return resetAt < 100_000_000_000 ? resetAt * 1000 : resetAt;
+
+  const resetAfter = numberField(record, 'reset_after_seconds');
+  if (resetAfter !== null && resetAfter >= 0) return now + resetAfter * 1000;
+  return null;
+}
+
+function notApplicable(kind: WindowKind): UsageWindow {
+  return {
+    kind,
+    label: labelFor(kind, null),
+    applicable: false,
+    availability: 'not_applicable',
+    usedPercent: null,
+    remainingPercent: null,
+    resetsAt: null,
+    source: 'service',
+  };
+}
+
+function unknownWindow(source: WindowSource): UsageWindow {
+  return {
+    kind: 'other',
+    label: 'Otra ventana',
+    applicable: false,
+    availability: 'unknown',
+    usedPercent: null,
+    remainingPercent: null,
+    resetsAt: null,
+    source,
+  };
+}
+
+/** Normalizes one service window. An absent/null window is only classified when a kind hint is explicit. */
+export function normalizeUsageWindow(
+  rawValue: unknown,
+  source: WindowSource,
+  options: WindowNormalizationOptions = {},
+): UsageWindow {
+  if (rawValue === null) return notApplicable(options.kindHint ?? 'other');
+  if (rawValue === undefined) return unknownWindow(source);
+
+  if (!isRecord(rawValue)) return unknownWindow(source);
+  const raw = rawValue;
+  const duration = numberField(raw, 'limit_window_seconds');
+  if (duration === null) return unknownWindow(source);
+  if (duration !== null && duration <= 0) return notApplicable(options.kindHint ?? 'other');
+
+  const kind = duration !== null && duration > 0 ? classifyWindow(duration) : 'other';
+  const used = numberField(raw, 'used_percent');
+  const validUsed = used !== null && used >= 0 && used <= 100 ? used : null;
+  const now =
+    typeof options.now === 'number' && Number.isFinite(options.now) ? options.now : Date.now();
+
+  return {
+    kind,
+    label: labelFor(kind, duration),
+    applicable: true,
+    availability: 'applicable',
+    usedPercent: validUsed,
+    remainingPercent: validUsed === null ? null : Math.round(100 - validUsed),
+    resetsAt: resetTime(raw, now),
+    source,
+  };
+}