@diousk/pi-usage-fast 0.1.0

package/src/index.ts

@@ -0,0 +1,116 @@
+export {
+  CODEX_FAST_MODEL_IDS,
+  CODEX_FAST_SERVICE_TIER,
+  CODEX_STANDARD_SERVICE_TIER,
+  codexFastAvailability,
+  codexFastIsEffective,
+  codexFastRequestTier,
+  codexFastStatusLabel,
+  correctCodexFastMessageCost,
+  rewriteCodexFastPayload,
+} from "./codex-fast.js";
+export type {
+  CodexResetAvailability,
+  CodexResetOption,
+  CodexResetOutcome,
+  CodexResetOutcomeCode,
+} from "./codex-resets.js";
+export {
+  consumeCodexResetCredit,
+  listCodexResetCredits,
+  normalizeCodexResetCreditsPayload,
+  resolveCodexResetAuth,
+} from "./codex-resets.js";
+export {
+  abortError,
+  awaitWithDeadline,
+  errorMessage,
+  fingerprintResolvedAuth,
+  redactUsageError,
+  runWithConcurrency,
+  sanitizeDisplayText,
+  UsageCache,
+} from "./core.js";
+export { formatProviderStates, formatUsageReport, formatUsageStatusline } from "./format.js";
+export { normalizeBasetenBillingUsagePayload } from "./providers/baseten.js";
+export { normalizeCodexBackendPayload } from "./providers/codex.js";
+export { normalizeDeepSeekBalancePayload } from "./providers/deepseek.js";
+export {
+  createFireworksAdapter,
+  normalizeFireworksAccountsPayload,
+  normalizeFireworksBillingSummaryPayload,
+} from "./providers/fireworks.js";
+export { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
+export { normalizeKimiCodingUsagePayload } from "./providers/kimi-coding.js";
+export type { MiniMaxProviderId, MiniMaxUsageKind } from "./providers/minimax.js";
+export {
+  miniMaxUsageKind,
+  normalizeMiniMaxUsagePayload,
+} from "./providers/minimax.js";
+export type { MoonshotProviderId } from "./providers/moonshot.js";
+export { normalizeMoonshotBalancePayload } from "./providers/moonshot.js";
+export { normalizeOpenCodeZenPayload } from "./providers/opencode-zen.js";
+export { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
+export { normalizeVercelAIGatewayCreditsPayload } from "./providers/vercel-ai-gateway.js";
+export { normalizeXaiBillingPayload } from "./providers/xai.js";
+export { normalizeZaiQuotaPayload, normalizeZaiSubscriptionPayload } from "./providers/zai.js";
+export {
+  adapterForProvider,
+  isStaleExtensionContextError,
+  providerIsConfigured,
+  queryProviderUsage,
+  resolveUsageAuth,
+  SUPPORTED_ADAPTERS,
+  usageAdapters,
+  XAI_ADAPTER,
+} from "./query.js";
+export type {
+  CodexStatusPercentage,
+  UsageSettings,
+  UsageSettingsRuntime,
+  UsageSettingsState,
+  UsageTargetPublicationCheck,
+} from "./settings.js";
+export {
+  createUsageSettingsRuntime,
+  DEFAULT_USAGE_SETTINGS,
+  loadUsageSettings,
+  normalizeUsageSettings,
+  usageSettingsPath,
+} from "./settings.js";
+export type {
+  BasetenBillingUsagePayload,
+  DeepSeekBalancePayload,
+  FireworksAccountsPayload,
+  FireworksBillingSummaryPayload,
+  KimiCodingUsagePayload,
+  MiniMaxUsagePayload,
+  MoonshotBalancePayload,
+  ProviderUsageState,
+  ResolvedUsageAuth,
+  UsageBucket,
+  UsageDisplayState,
+  UsageMetric,
+  UsageModel,
+  UsageProviderAdapter,
+  UsageProviderTarget,
+  UsageQuerySettings,
+  UsageReport,
+  UsageRequestGuard,
+  UsageSemantics,
+  UsageSemanticsKind,
+  UsageTargetResolver,
+  UsageUnit,
+  VercelAIGatewayCreditsPayload,
+  XaiBillingPayload,
+  XaiUserPayload,
+} from "./types.js";
+export { default } from "./usage.js";
+export type { UsageTargetResolution, UsageTargetSelectOptions } from "./usage-targets.js";
+export {
+  createUsageTargetSelectOptions,
+  isBoundedTargetId,
+  listUsageTargets,
+  normalizeUsageTargets,
+  resolveUsageTarget,
+} from "./usage-targets.js";

package/src/oauth-credential-source.ts

@@ -0,0 +1,117 @@
+import type { OAuthCredential } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, type ExtensionContext, readStoredCredential } from "@earendil-works/pi-coding-agent";
+
+export const OAUTH_CREDENTIAL_SOURCE_CHANNEL = "oauth:credential-source:v1";
+export const OAUTH_CREDENTIAL_READINESS_CHANNEL = "oauth:credential-readiness:v1";
+
+export type StoredCredentialReader = (providerId: string) => unknown;
+
+export type OAuthCredentialCandidates =
+  | { ok: true; candidates: readonly OAuthCredential[]; offeredCount?: number }
+  | { ok: false };
+
+export type OAuthCredentialCandidateReader = {
+  (ctx: ExtensionContext, providerId: string): OAuthCredentialCandidates | Promise<OAuthCredentialCandidates>;
+  waitUntilReady?(ctx: ExtensionContext, providerId: string): Promise<boolean>;
+};
+
+export function createOAuthCredentialCandidateReader(
+  pi: ExtensionAPI,
+  credentialReader: StoredCredentialReader = readStoredCredential,
+): OAuthCredentialCandidateReader {
+  const reader: OAuthCredentialCandidateReader = (ctx, providerId) =>
+    collectOAuthCredentialCandidates(pi, ctx, providerId, credentialReader);
+  reader.waitUntilReady = (ctx, providerId) => waitForOAuthCredentialSources(pi, ctx, providerId);
+  return reader;
+}
+
+export function collectOAuthCredentialCandidates(
+  pi: Pick<ExtensionAPI, "events">,
+  ctx: ExtensionContext,
+  providerId: string,
+  credentialReader: StoredCredentialReader = readStoredCredential,
+): OAuthCredentialCandidates {
+  const candidates: OAuthCredential[] = [];
+  let collecting = true;
+  const request = Object.freeze({
+    session: ctx.sessionManager,
+    provider: providerId,
+    offer(candidate: unknown) {
+      if (!collecting) return;
+      const clone = cloneOAuthCredential(candidate);
+      if (clone) candidates.push(clone);
+    },
+  });
+  try {
+    pi.events.emit(OAUTH_CREDENTIAL_SOURCE_CHANNEL, request);
+  } catch {
+    return { ok: false };
+  } finally {
+    collecting = false;
+  }
+  const offeredCount = candidates.length;
+  try {
+    const fallback = cloneOAuthCredential(credentialReader(providerId));
+    if (fallback) candidates.push(fallback);
+  } catch {
+    // A malformed or unavailable standalone credential is equivalent to no fallback.
+  }
+  return { ok: true, candidates, offeredCount };
+}
+
+async function waitForOAuthCredentialSources(
+  pi: Pick<ExtensionAPI, "events">,
+  ctx: ExtensionContext,
+  providerId: string,
+): Promise<boolean> {
+  const pending: Promise<unknown>[] = [];
+  let collecting = true;
+  const request = Object.freeze({
+    session: ctx.sessionManager,
+    provider: providerId,
+    waitUntil(value: unknown) {
+      if (!collecting || !(value instanceof Promise)) return;
+      pending.push(value);
+    },
+  });
+  try {
+    pi.events.emit(OAUTH_CREDENTIAL_READINESS_CHANNEL, request);
+  } catch {
+    return false;
+  } finally {
+    collecting = false;
+  }
+  try {
+    await Promise.all(pending);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function fallbackOAuthCredentialCandidates(
+  providerId: string,
+  credentialReader: StoredCredentialReader,
+): OAuthCredentialCandidates {
+  try {
+    const credential = cloneOAuthCredential(credentialReader(providerId));
+    return { ok: true, candidates: credential ? [credential] : [], offeredCount: 0 };
+  } catch {
+    return { ok: true, candidates: [], offeredCount: 0 };
+  }
+}
+
+function cloneOAuthCredential(value: unknown): OAuthCredential | undefined {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const clone = structuredClone(value) as OAuthCredential;
+    if (!clone || typeof clone !== "object" || Array.isArray(clone)) return undefined;
+    if (clone.type !== "oauth") return undefined;
+    if (typeof clone.access !== "string" || !clone.access) return undefined;
+    if (typeof clone.refresh !== "string" || !clone.refresh) return undefined;
+    if (typeof clone.expires !== "number" || !Number.isFinite(clone.expires)) return undefined;
+    return clone;
+  } catch {
+    return undefined;
+  }
+}

package/src/providers/baseten.ts

@@ -0,0 +1,51 @@
+import type { BasetenBillingUsagePayload, UsageMetric, UsageReport } from "../types.js";
+
+const DECIMAL_AMOUNT = /^(?:0|[1-9]\d*)(?:\.\d+)?$/u;
+
+export function normalizeBasetenBillingUsagePayload(
+  payload: BasetenBillingUsagePayload,
+  capturedAt: number,
+): UsageReport {
+  if (payload.model_apis_usage === undefined || payload.model_apis_usage === null) {
+    return report(capturedAt, [], ["Baseten returned no Model APIs usage for the last 30 days."]);
+  }
+  const usage = asObject(payload.model_apis_usage);
+  if (!usage) throw new Error("Baseten Model APIs usage was not an object.");
+  const metrics: UsageMetric[] = [
+    metric("gross-usage", "Gross usage", usage.total),
+    metric("credits-used", "Credits used", usage.credits_used),
+    metric("net-subtotal", "Net subtotal", usage.subtotal),
+  ];
+  return report(capturedAt, metrics);
+}
+
+function report(capturedAt: number, metrics: UsageMetric[], notes?: string[]): UsageReport {
+  return {
+    providerId: "baseten",
+    providerName: "Baseten",
+    capturedAt,
+    source: "baseten-billing-usage-summary",
+    semantics: { kind: "api-key", label: "Organization Model APIs spend" },
+    buckets: [],
+    metrics,
+    ...(notes ? { notes } : {}),
+  };
+}
+
+function metric(id: string, label: string, value: unknown): UsageMetric {
+  const amount = decimalAmount(value, label);
+  return { id, label, value: amount, unit: "currency", currency: "USD" };
+}
+
+function decimalAmount(value: unknown, label: string): string {
+  const normalized = typeof value === "number" && Number.isFinite(value) ? String(value) : value;
+  if (typeof normalized !== "string" || normalized.length > 64 || !DECIMAL_AMOUNT.test(normalized)) {
+    throw new Error(`Baseten ${label.toLowerCase()} was not a valid nonnegative amount.`);
+  }
+  return normalized;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}

package/src/providers/codex.ts

@@ -0,0 +1,139 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { CodexBackendPayload, UsageBucket, UsageMetric, UsageReport } from "../types.js";
+
+export function normalizeCodexBackendPayload(payload: CodexBackendPayload, capturedAt: number): UsageReport {
+  const buckets: UsageBucket[] = [];
+  normalizeRateLimitGroup(buckets, "codex", "Codex", payload.rate_limit, false);
+
+  const additional = Array.isArray(payload.additional_rate_limits) ? payload.additional_rate_limits : [];
+  for (const item of additional) {
+    const value = asObject(item);
+    const id = asString(value?.metered_feature) ?? asString(value?.limit_name);
+    if (!value || !id) continue;
+    try {
+      normalizeRateLimitGroup(buckets, id, asString(value.limit_name) ?? id, value.rate_limit, true);
+    } catch {
+      // Optional provider-specific buckets must not hide otherwise useful primary data.
+    }
+  }
+
+  const metrics: UsageMetric[] = [];
+  const credits = asObject(payload.credits);
+  if (credits?.has_credits === true) {
+    if (credits.unlimited === true) {
+      metrics.push({ id: "credits", label: "Credits", value: "unlimited" });
+    } else {
+      const balance = asNumber(credits.balance);
+      if (balance !== undefined) {
+        metrics.push({ id: "credits", label: "Credits", value: balance, unit: "count" });
+      } else {
+        metrics.push({ id: "credits", label: "Credits", value: "available" });
+      }
+    }
+  } else if (credits?.has_credits === false) {
+    metrics.push({ id: "credits", label: "Credits", value: "none" });
+  }
+  const resetCredits = asObject(payload.rate_limit_reset_credits);
+  const resetCount = asNonnegativeInteger(resetCredits?.available_count);
+  if (resetCount !== undefined) {
+    metrics.push({
+      id: "reset-credits",
+      label: "Usage limit resets",
+      value: resetCount,
+      unit: "count",
+    });
+  }
+  if (buckets.length === 0 && metrics.length === 0) {
+    throw new Error("Codex usage endpoint returned no displayable usage data.");
+  }
+
+  const planType = asString(payload.plan_type);
+  return {
+    providerId: "openai-codex",
+    providerName: "OpenAI Codex",
+    capturedAt,
+    source: "codex-pi-auth",
+    semantics: {
+      kind: "consumer-subscription",
+      label: "ChatGPT subscription limits",
+    },
+    buckets,
+    metrics,
+    ...(planType ? { notes: [`Plan: ${planType}`] } : {}),
+  };
+}
+
+function normalizeRateLimitGroup(
+  buckets: UsageBucket[],
+  groupId: string,
+  groupLabel: string,
+  raw: unknown,
+  optional: boolean,
+): void {
+  if (raw === undefined || raw === null) return;
+  const details = asObject(raw);
+  if (!details) {
+    if (optional) return;
+    throw new Error("Codex rate limit was not an object.");
+  }
+  addWindow(buckets, groupId, groupLabel, "primary", details.primary_window);
+  addWindow(buckets, groupId, groupLabel, "secondary", details.secondary_window);
+}
+
+function addWindow(
+  buckets: UsageBucket[],
+  groupId: string,
+  groupLabel: string,
+  position: "primary" | "secondary",
+  raw: unknown,
+): void {
+  if (raw === undefined || raw === null) return;
+  const value = asObject(raw);
+  if (!value) throw new Error("Codex rate-limit window was not an object.");
+  const used = asNumber(value.used_percent);
+  if (used === undefined) return;
+  const seconds = asNumber(value.limit_window_seconds);
+  const resetsAt = asNumber(value.reset_at);
+  buckets.push({
+    id: `${groupId}:${position}`,
+    label: position === "primary" ? "Primary limit" : "Secondary limit",
+    groupId,
+    groupLabel,
+    modelKeys: [groupId, groupLabel],
+    used,
+    remaining: 100 - clampPercent(used),
+    limit: 100,
+    unit: "percent",
+    ...(seconds !== undefined && seconds > 0 ? { windowMinutes: Math.ceil(seconds / 60) } : {}),
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
+  });
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return sanitizeDisplayText(value, 160) || undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function asNonnegativeInteger(value: unknown): number | undefined {
+  const parsed = asNumber(value);
+  if (parsed === undefined || !Number.isSafeInteger(parsed)) return undefined;
+  return Math.max(0, parsed);
+}
+
+function clampPercent(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}

package/src/providers/deepseek.ts

@@ -0,0 +1,80 @@
+import type { DeepSeekBalancePayload, UsageMetric, UsageReport } from "../types.js";
+
+const CURRENCIES = ["CNY", "USD"] as const;
+type DeepSeekCurrency = (typeof CURRENCIES)[number];
+
+const BALANCE_FIELDS = [
+  ["total", "Total balance", "total_balance"],
+  ["granted", "Granted balance", "granted_balance"],
+  ["topped-up", "Topped-up balance", "topped_up_balance"],
+] as const;
+
+export function normalizeDeepSeekBalancePayload(payload: DeepSeekBalancePayload, capturedAt: number): UsageReport {
+  if (typeof payload.is_available !== "boolean") {
+    throw new Error("DeepSeek API balance response availability was not a boolean.");
+  }
+  if (!Array.isArray(payload.balance_infos) || payload.balance_infos.length === 0) {
+    throw new Error("DeepSeek API balance response returned no balance information.");
+  }
+
+  const balances = new Map<DeepSeekCurrency, Record<string, unknown>>();
+  for (const raw of payload.balance_infos) {
+    const balance = asObject(raw);
+    if (!balance) throw new Error("DeepSeek API balance row was not an object.");
+    const currency = deepSeekCurrency(balance.currency);
+    if (!currency) throw new Error("DeepSeek API balance row returned an unsupported currency.");
+    if (balances.has(currency)) {
+      throw new Error(`DeepSeek API balance response repeated ${currency}.`);
+    }
+    for (const [, label, field] of BALANCE_FIELDS) {
+      if (!decimalAmount(balance[field])) {
+        throw new Error(`DeepSeek API balance ${label.toLowerCase()} was not a valid amount.`);
+      }
+    }
+    balances.set(currency, balance);
+  }
+
+  const metrics: UsageMetric[] = [
+    {
+      id: "api-availability",
+      label: "API calls",
+      value: payload.is_available ? "available" : "unavailable",
+    },
+  ];
+  for (const currency of CURRENCIES) {
+    const balance = balances.get(currency);
+    if (!balance) continue;
+    for (const [id, label, field] of BALANCE_FIELDS) {
+      metrics.push({
+        id: `${currency.toLowerCase()}-${id}`,
+        label,
+        value: balance[field] as string,
+        unit: "currency",
+        currency,
+      });
+    }
+  }
+
+  return {
+    providerId: "deepseek",
+    providerName: "DeepSeek",
+    capturedAt,
+    source: "deepseek-balance",
+    semantics: { kind: "api-key", label: "DeepSeek API balance" },
+    buckets: [],
+    metrics,
+  };
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function deepSeekCurrency(value: unknown): DeepSeekCurrency | undefined {
+  return CURRENCIES.find((currency) => currency === value);
+}
+
+function decimalAmount(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 64 && /^(?:0|[1-9]\d*)(?:\.\d+)?$/u.test(value);
+}