@narumitw/pi-usage 0.52.3 → 0.54.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.52.3",
-	"description": "Pi extension that shows current-account usage for Codex, GitHub Copilot, OpenRouter, and OpenCode Zen.",
+	"version": "0.54.0",
+	"description": "Pi extension that shows current-account usage for Codex, Kimi For Coding, GitHub Copilot, OpenRouter, OpenCode Zen, Z.AI, and xAI OAuth subscriptions.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -12,10 +12,16 @@
 		"usage",
 		"quota",
 		"codex",
+		"kimi",
+		"kimi-coding",
 		"copilot",
 		"openrouter",
 		"opencode",
-		"zen"
+		"zen",
+		"zai",
+		"glm",
+		"xai",
+		"grok"
 	],
 	"files": [
 		"src",
@@ -40,12 +46,14 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.10",
 		"@earendil-works/pi-ai": "0.84.3",
 		"@earendil-works/pi-coding-agent": "0.84.3",
+		"@earendil-works/pi-tui": "0.84.3",
 		"@types/node": "26.2.0",
 		"esbuild": "0.28.2",
 		"typescript": "7.0.2"

package/src/format.ts

@@ -19,7 +19,11 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
 	else if (report.providerId === "github-copilot") formatGitHubCopilotReport(lines, report);
 	else if (report.providerId === "openrouter") formatOpenRouterReport(lines, report);
 	else if (report.providerId === "opencode-go") formatOpenCodeZenReport(lines, report);
-	else formatGenericReport(lines, report);
+	else if (report.providerId === "kimi-coding") formatKimiCodingReport(lines, report);
+	else if (report.providerId === "xai") formatXaiReport(lines, report);
+	else if (report.providerId === "zai" || report.providerId === "zai-coding-cn") {
+		formatZaiReport(lines, report);
+	} else formatGenericReport(lines, report);
 
 	if (report.notes) {
 		for (const note of report.notes) lines.push(note);
@@ -37,6 +41,7 @@ export function formatUsageStatusline(report: UsageReport, model?: UsageModel):
 		if (typeof total?.value === "number") return `openrouter ${formatUsd(total.value)} used`;
 	}
 	if (report.providerId === "opencode-go") return formatOpenCodeZenStatusline(report);
+	if (report.providerId === "kimi-coding") return formatKimiCodingStatusline(report);
 	return undefined;
 }
 
@@ -160,6 +165,117 @@ function formatOpenCodeZenStatusline(report: UsageReport): string | undefined {
 	return parts.length > 1 ? parts.join(" ") : undefined;
 }
 
+function formatKimiCodingReport(lines: string[], report: UsageReport): void {
+	for (const bucket of report.buckets) {
+		const reset = bucket.resetsAt ? ` (resets ${formatReset(bucket.resetsAt)})` : "";
+		if (bucket.used === undefined || bucket.limit === undefined) {
+			lines.push(`${`${bucket.label}:`.padEnd(VALUE_COLUMN)}unavailable${reset}`);
+			continue;
+		}
+		lines.push(
+			`${`${bucket.label}:`.padEnd(VALUE_COLUMN)}${bucket.used} of ${bucket.limit} used · ${percentRemaining(bucket)}% left${reset}`,
+		);
+	}
+	const balance = report.metrics.find((metric) => metric.id === "booster-balance");
+	const total = report.metrics.find((metric) => metric.id === "booster-total");
+	const monthlyUsed = report.metrics.find((metric) => metric.id === "booster-monthly-used");
+	const monthlyLimit = report.metrics.find((metric) => metric.id === "booster-monthly-limit");
+	if (!balance && !monthlyUsed && !monthlyLimit) return;
+	lines.push("", "Extra usage wallet:");
+	if (balance) {
+		const totalSuffix = total ? ` of ${formatCurrencyMetric(total)}` : "";
+		lines.push(`${"Balance:".padEnd(VALUE_COLUMN)}${formatCurrencyMetric(balance)}${totalSuffix}`);
+	}
+	if (monthlyUsed) {
+		lines.push(`${"Used this month:".padEnd(VALUE_COLUMN)}${formatCurrencyMetric(monthlyUsed)}`);
+	}
+	if (monthlyLimit) {
+		lines.push(`${"Monthly limit:".padEnd(VALUE_COLUMN)}${formatCurrencyMetric(monthlyLimit)}`);
+	}
+}
+
+function formatKimiCodingStatusline(report: UsageReport): string | undefined {
+	const fiveHour = report.buckets.find((bucket) => bucket.id === "five-hour");
+	const weekly = report.buckets.find((bucket) => bucket.id === "weekly");
+	const subWindow = fiveHour ?? report.buckets.find((bucket) => bucket.id !== "weekly");
+	const selected = [subWindow, weekly].filter(
+		(bucket, index, buckets): bucket is UsageBucket =>
+			bucket !== undefined && buckets.indexOf(bucket) === index,
+	);
+	const parts = ["kimi"];
+	for (const bucket of selected) {
+		if (!bucket.limit || bucket.remaining === undefined) continue;
+		const fallback = bucket.id === "weekly" ? "weekly" : "5h";
+		parts.push(
+			`${percentRemaining(bucket)}% ${formatWindowLabel(bucket.windowMinutes, fallback, true)}`,
+		);
+	}
+	return parts.length > 1 ? parts.join(" ") : undefined;
+}
+
+function formatCurrencyMetric(metric: UsageReport["metrics"][number]): string {
+	if (typeof metric.value !== "number") return String(metric.value);
+	if (!metric.currency) return "unavailable";
+	if (metric.currency === "USD") return `$${metric.value.toFixed(2)}`;
+	if (metric.currency === "CNY") return `¥${metric.value.toFixed(2)}`;
+	return `${metric.value.toFixed(2)} ${metric.currency}`;
+}
+
+function formatXaiReport(lines: string[], report: UsageReport): void {
+	const included = report.buckets.find((bucket) => bucket.id === "included-allowance");
+	if (included) {
+		let value = "unavailable";
+		if (included.unit === "percent" && included.used !== undefined) {
+			value = `${included.used}% used`;
+			if (included.remaining !== undefined) value += ` · ${included.remaining}% left`;
+		} else if (included.used !== undefined) {
+			value = `${formatUsd(included.used)} used`;
+			if (included.limit !== undefined) value += ` of ${formatUsd(included.limit)}`;
+		} else if (included.limit !== undefined) {
+			value = `usage unavailable · ${formatUsd(included.limit)} limit`;
+		}
+		const period = included.period ? ` · ${included.period}` : "";
+		const reset = included.resetsAt ? ` (resets ${formatReset(included.resetsAt)})` : "";
+		lines.push(`${"Included allowance:".padEnd(VALUE_COLUMN)}${value}${period}${reset}`);
+	}
+	const onDemand = report.buckets.find((bucket) => bucket.id === "on-demand");
+	if (onDemand) {
+		let value =
+			onDemand.used === undefined ? "usage unavailable" : `${formatUsd(onDemand.used)} used`;
+		if (onDemand.limit !== undefined) value += ` of ${formatUsd(onDemand.limit)} cap`;
+		lines.push(`${"On-demand usage:".padEnd(VALUE_COLUMN)}${value}`);
+	}
+	for (const metric of report.metrics) {
+		lines.push(
+			`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`,
+		);
+	}
+}
+
+function formatZaiReport(lines: string[], report: UsageReport): void {
+	for (const bucket of report.buckets) {
+		const reset = bucket.resetsAt ? ` (resets ${formatReset(bucket.resetsAt)})` : "";
+		let value = "unavailable";
+		if (bucket.unit === "percent" && bucket.used !== undefined) {
+			value = `${bucket.used}% used`;
+			if (bucket.remaining !== undefined) value += ` · ${bucket.remaining}% left`;
+		} else if (bucket.used !== undefined && bucket.limit !== undefined) {
+			value = `${bucket.used} of ${bucket.limit} used`;
+			if (bucket.remaining !== undefined) value += ` · ${bucket.remaining} left`;
+		} else if (bucket.used !== undefined) {
+			value = `${bucket.used} used`;
+		} else if (bucket.remaining !== undefined) {
+			value = `${bucket.remaining} left`;
+		}
+		lines.push(`${`${bucket.label}:`.padEnd(VALUE_COLUMN)}${value}${reset}`);
+	}
+	for (const metric of report.metrics) {
+		lines.push(
+			`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`,
+		);
+	}
+}
+
 function formatGenericReport(lines: string[], report: UsageReport): void {
 	for (const bucket of report.buckets) {
 		lines.push(

package/src/index.ts

@@ -34,8 +34,11 @@ export {
 export { formatProviderStates, formatUsageReport, formatUsageStatusline } from "./format.js";
 export { normalizeCodexBackendPayload } from "./providers/codex.js";
 export { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
+export { normalizeKimiCodingUsagePayload } from "./providers/kimi-coding.js";
 export { normalizeOpenCodeZenPayload } from "./providers/opencode-zen.js";
 export { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
+export { normalizeXaiBillingPayload } from "./providers/xai.js";
+export { normalizeZaiQuotaPayload } from "./providers/zai.js";
 export {
 	adapterForProvider,
 	isStaleExtensionContextError,
@@ -43,6 +46,8 @@ export {
 	queryProviderUsage,
 	resolveUsageAuth,
 	SUPPORTED_ADAPTERS,
+	usageAdapters,
+	XAI_ADAPTER,
 } from "./query.js";
 export type {
 	UsageSettings,
@@ -57,6 +62,7 @@ export {
 	usageSettingsPath,
 } from "./settings.js";
 export type {
+	KimiCodingUsagePayload,
 	ProviderUsageState,
 	ResolvedUsageAuth,
 	UsageBucket,
@@ -68,5 +74,7 @@ export type {
 	UsageSemantics,
 	UsageSemanticsKind,
 	UsageUnit,
+	XaiBillingPayload,
+	XaiUserPayload,
 } from "./types.js";
 export { default } from "./usage.js";

package/src/providers/kimi-coding.ts

@@ -0,0 +1,276 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { KimiCodingUsagePayload, UsageBucket, UsageMetric, UsageReport } from "../types.js";
+
+const FIVE_HOUR_WINDOW_MINUTES = 300;
+const DAILY_WINDOW_MINUTES = 1_440;
+const WEEKLY_WINDOW_MINUTES = 10_080;
+const FIXED_POINT_UNITS_PER_CENT = 1_000_000;
+
+/**
+ * Source contract revalidated on 2026-08-27.
+ * Pi c49906ec77788625aacbdc53ebca6fbe65bd20f5 defines provider `kimi-coding`,
+ * `https://api.kimi.com/coding`, API-key auth, and OAuth Bearer auth:
+ * https://github.com/earendil-works/pi/blob/c49906ec77788625aacbdc53ebca6fbe65bd20f5/packages/ai/src/providers/kimi-coding.ts
+ * https://github.com/earendil-works/pi/blob/c49906ec77788625aacbdc53ebca6fbe65bd20f5/packages/ai/src/auth/oauth/kimi-coding.ts
+ * Kimi Code 676e4d82240855044fe809fea89ce1dbe8e512cf defines `GET /coding/v1/usages`,
+ * numeric-string plan rows, proto-style windows, and 1,000,000 fixed-point units per cent:
+ * https://github.com/MoonshotAI/kimi-code/blob/676e4d82240855044fe809fea89ce1dbe8e512cf/packages/oauth/src/managed-usage.ts
+ */
+export function normalizeKimiCodingUsagePayload(
+	payload: KimiCodingUsagePayload,
+	capturedAt: number,
+): UsageReport {
+	const root = asObject(payload);
+	if (!root) throw new Error("Kimi Coding usage response was not an object.");
+
+	const candidates: UsageBucket[] = [];
+	let omittedWindow = false;
+	const summary = parseUsageRow(root.usage, WEEKLY_WINDOW_MINUTES, "Weekly window");
+	if (summary) candidates.push(summary);
+	else if (root.usage !== undefined) omittedWindow = true;
+
+	if (Array.isArray(root.limits)) {
+		for (const raw of root.limits) {
+			const item = asObject(raw);
+			const windowMinutes = parseWindowMinutes(item?.window);
+			const label = sanitizedLabel(item?.name);
+			const bucket =
+				windowMinutes === undefined
+					? undefined
+					: parseUsageRow(item?.detail, windowMinutes, label ?? defaultWindowLabel(windowMinutes));
+			if (bucket) candidates.push(bucket);
+			else omittedWindow = true;
+		}
+	} else if (root.limits !== undefined) {
+		omittedWindow = true;
+	}
+
+	const buckets: UsageBucket[] = [];
+	const byWindow = new Map<number, UsageBucket[]>();
+	for (const bucket of candidates) {
+		const windowMinutes = bucket.windowMinutes as number;
+		byWindow.set(windowMinutes, [...(byWindow.get(windowMinutes) ?? []), bucket]);
+	}
+	for (const rows of byWindow.values()) {
+		if (rows.length === 1) buckets.push(rows[0] as UsageBucket);
+		else omittedWindow = true;
+	}
+	buckets.sort((left, right) => (left.windowMinutes ?? 0) - (right.windowMinutes ?? 0));
+
+	const metrics = parseBoosterWallet(root.boosterWallet);
+	if (buckets.length === 0 && metrics.length === 0) {
+		throw new Error("Kimi Coding usage endpoint returned no displayable usage data.");
+	}
+
+	return {
+		providerId: "kimi-coding",
+		providerName: "Kimi For Coding",
+		capturedAt,
+		source: "kimi-managed-usage",
+		semantics: { kind: "consumer-subscription", label: "Kimi Coding Plan usage" },
+		buckets,
+		metrics,
+		...(omittedWindow
+			? { notes: ["Unsupported, malformed, or duplicate plan windows were unavailable."] }
+			: {}),
+	};
+}
+
+function parseUsageRow(
+	value: unknown,
+	windowMinutes: number,
+	label: string,
+): UsageBucket | undefined {
+	const row = asObject(value);
+	if (!row) return undefined;
+	const used = asNonnegativeInteger(row.used);
+	const limit = asNonnegativeInteger(row.limit);
+	if (used === undefined || limit === undefined || limit === 0) return undefined;
+	const resetsAt = asIsoEpochSeconds(row.resetTime);
+	return {
+		id: windowId(windowMinutes),
+		label,
+		used,
+		remaining: Math.max(0, limit - used),
+		limit,
+		unit: "count",
+		windowMinutes,
+		...(resetsAt !== undefined ? { resetsAt } : {}),
+	};
+}
+
+function parseWindowMinutes(value: unknown): number | undefined {
+	const window = asObject(value);
+	if (!window) return undefined;
+	const duration = asPositiveInteger(window.duration);
+	if (duration === undefined) return undefined;
+	const multiplier =
+		window.timeUnit === "TIME_UNIT_MINUTE"
+			? 1
+			: window.timeUnit === "TIME_UNIT_HOUR"
+				? 60
+				: window.timeUnit === "TIME_UNIT_DAY"
+					? 1_440
+					: window.timeUnit === "TIME_UNIT_WEEK"
+						? 10_080
+						: undefined;
+	if (multiplier === undefined) return undefined;
+	const minutes = duration * multiplier;
+	return Number.isSafeInteger(minutes) ? minutes : undefined;
+}
+
+function parseBoosterWallet(value: unknown): UsageMetric[] {
+	const wallet = asObject(value);
+	const balance = asObject(wallet?.balance);
+	if (!wallet || !balance || balance.type !== "BOOSTER") return [];
+	const totalRaw = asPositiveInteger(balance.amount);
+	if (totalRaw === undefined) return [];
+	const leftRaw = asNonnegativeInteger(balance.amountLeft) ?? 0;
+	const monthlyLimit = parseMoney(wallet.monthlyChargeLimit);
+	const monthlyUsed = parseMoney(wallet.monthlyUsed);
+	const currencies = new Set(
+		[monthlyLimit?.currency, monthlyUsed?.currency].filter(
+			(currency): currency is string => currency !== undefined,
+		),
+	);
+	if (currencies.size !== 1) return [];
+	const currency = currencies.values().next().value;
+	if (!currency) return [];
+	const total = fixedPointToMajor(totalRaw);
+	const left = fixedPointToMajor(leftRaw);
+	if (total === undefined || left === undefined) return [];
+
+	const metrics: UsageMetric[] = [
+		{ id: "booster-balance", label: "Balance", value: left, unit: "currency", currency },
+		{ id: "booster-total", label: "Total balance", value: total, unit: "currency", currency },
+	];
+	if (monthlyUsed) {
+		metrics.push({
+			id: "booster-monthly-used",
+			label: "Used this month",
+			value: monthlyUsed.cents / 100,
+			unit: "currency",
+			currency,
+		});
+	}
+	if (wallet.monthlyChargeLimitEnabled === false) {
+		metrics.push({
+			id: "booster-monthly-limit",
+			label: "Monthly limit",
+			value: "unlimited",
+			unit: "currency",
+			currency,
+		});
+	} else if (wallet.monthlyChargeLimitEnabled === true && monthlyLimit) {
+		metrics.push({
+			id: "booster-monthly-limit",
+			label: "Monthly limit",
+			value: monthlyLimit.cents / 100,
+			unit: "currency",
+			currency,
+		});
+	}
+	return metrics;
+}
+
+function parseMoney(value: unknown): { cents: number; currency: string } | undefined {
+	const money = asObject(value);
+	if (!money) return undefined;
+	const cents = asNonnegativeInteger(money.priceInCents);
+	if (cents === undefined) return undefined;
+	const currency = asCurrency(money.currency);
+	if (!currency) return undefined;
+	return { cents, currency };
+}
+
+function fixedPointToMajor(value: number): number | undefined {
+	const cents = value / FIXED_POINT_UNITS_PER_CENT;
+	const roundedCents = cents > 0 && cents < 1 ? 1 : Math.round(cents);
+	const major = roundedCents / 100;
+	return Number.isSafeInteger(roundedCents) && Number.isFinite(major) ? major : undefined;
+}
+
+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 asNonnegativeInteger(value: unknown): number | undefined {
+	if (typeof value === "string" && !/^\d+$/u.test(value)) return undefined;
+	const number = typeof value === "string" ? Number(value) : value;
+	if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 0) return undefined;
+	return number;
+}
+
+function asPositiveInteger(value: unknown): number | undefined {
+	const number = asNonnegativeInteger(value);
+	return number !== undefined && number > 0 ? number : undefined;
+}
+
+function asIsoEpochSeconds(value: unknown): number | undefined {
+	if (typeof value !== "string") return undefined;
+	const match =
+		/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/u.exec(
+			value,
+		);
+	if (!match) return undefined;
+	const [
+		,
+		yearText,
+		monthText,
+		dayText,
+		hourText,
+		minuteText,
+		secondText,
+		,
+		offsetHour,
+		offsetMinute,
+	] = match;
+	const year = Number(yearText);
+	const month = Number(monthText);
+	const day = Number(dayText);
+	const hour = Number(hourText);
+	const minute = Number(minuteText);
+	const second = Number(secondText);
+	if (
+		month < 1 ||
+		month > 12 ||
+		day < 1 ||
+		day > new Date(Date.UTC(year, month, 0)).getUTCDate() ||
+		hour > 23 ||
+		minute > 59 ||
+		second > 59 ||
+		(offsetHour !== undefined && Number(offsetHour) > 23) ||
+		(offsetMinute !== undefined && Number(offsetMinute) > 59)
+	) {
+		return undefined;
+	}
+	const millis = Date.parse(value);
+	return Number.isFinite(millis) && millis >= 0 ? Math.floor(millis / 1000) : undefined;
+}
+
+function sanitizedLabel(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	return sanitizeDisplayText(value, 80) || undefined;
+}
+
+function asCurrency(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const currency = sanitizeDisplayText(value, 3).toUpperCase();
+	return /^[A-Z]{3}$/u.test(currency) ? currency : undefined;
+}
+
+function windowId(minutes: number): string {
+	if (minutes === FIVE_HOUR_WINDOW_MINUTES) return "five-hour";
+	if (minutes === DAILY_WINDOW_MINUTES) return "daily";
+	if (minutes === WEEKLY_WINDOW_MINUTES) return "weekly";
+	return `window-${minutes}-minutes`;
+}
+
+function defaultWindowLabel(minutes: number): string {
+	if (minutes === WEEKLY_WINDOW_MINUTES) return "Weekly window";
+	if (minutes % 10_080 === 0) return `${minutes / 10_080}w window`;
+	if (minutes % 1_440 === 0) return `${minutes / 1_440}d window`;
+	if (minutes % 60 === 0) return `${minutes / 60}h window`;
+	return `${minutes}m window`;
+}

package/src/providers/xai.ts

@@ -0,0 +1,186 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { UsageBucket, UsageMetric, UsageReport, XaiBillingPayload } from "../types.js";
+
+const MAX_SAFE_CENTS = Number.MAX_SAFE_INTEGER;
+
+export function normalizeXaiBillingPayload(
+	payload: XaiBillingPayload,
+	subscriptionTier: unknown,
+	capturedAt: number,
+): UsageReport {
+	const configValue = payload.config;
+	if (configValue !== null && configValue !== undefined && !isRecord(configValue)) {
+		throw new Error("xAI billing response config was not an object or null.");
+	}
+	const config = isRecord(configValue) ? configValue : undefined;
+	const buckets: UsageBucket[] = [];
+	const metrics: UsageMetric[] = [];
+	const notes: string[] = [];
+
+	if (config) {
+		const period = normalizePeriod(
+			config.currentPeriod,
+			config.billingPeriodStart,
+			config.billingPeriodEnd,
+		);
+		const preferredPercent = optionalPercent(config.creditUsagePercent, "creditUsagePercent");
+		if (preferredPercent !== undefined) {
+			buckets.push({
+				id: "included-allowance",
+				label: "Included allowance",
+				used: preferredPercent,
+				remaining: 100 - preferredPercent,
+				unit: "percent",
+				...period,
+			});
+		} else {
+			const limit = optionalUsd(config.monthlyLimit, "monthlyLimit");
+			const used = optionalUsd(config.used, "used");
+			if (limit !== undefined || used !== undefined) {
+				buckets.push({
+					id: "included-allowance",
+					label: "Included allowance",
+					...(limit !== undefined ? { limit } : {}),
+					...(used !== undefined ? { used } : {}),
+					...(limit !== undefined && used !== undefined ? { remaining: limit - used } : {}),
+					unit: "usd",
+					...period,
+				});
+			} else if (period.period || period.resetsAt !== undefined) {
+				buckets.push({
+					id: "included-allowance",
+					label: "Included allowance",
+					unit: "percent",
+					...period,
+				});
+			}
+		}
+
+		const onDemandCap = optionalUsd(config.onDemandCap, "onDemandCap");
+		const onDemandUsed = optionalUsd(config.onDemandUsed, "onDemandUsed");
+		if (onDemandCap !== undefined || onDemandUsed !== undefined) {
+			buckets.push({
+				id: "on-demand",
+				label: "On-demand usage",
+				...(onDemandCap !== undefined ? { limit: onDemandCap } : {}),
+				...(onDemandUsed !== undefined ? { used: onDemandUsed } : {}),
+				...(onDemandCap !== undefined && onDemandUsed !== undefined
+					? { remaining: onDemandCap - onDemandUsed }
+					: {}),
+				unit: "usd",
+			});
+		}
+
+		const prepaidBalance = optionalUsd(config.prepaidBalance, "prepaidBalance");
+		if (prepaidBalance !== undefined) {
+			metrics.push({
+				id: "prepaid-balance",
+				label: "Prepaid balance",
+				value: prepaidBalance,
+				unit: "usd",
+			});
+		}
+	}
+
+	const tier = optionalTier(subscriptionTier);
+	if (tier) metrics.push({ id: "subscription-tier", label: "Plan tier", value: tier });
+	if (!config) notes.push("No xAI consumer billing configuration is available for this account.");
+	else if (buckets.length === 0 && metrics.length === 0) {
+		notes.push("The xAI consumer billing response contained no displayable usage fields.");
+	}
+
+	return {
+		providerId: "xai",
+		providerName: "xAI",
+		capturedAt,
+		source: "cli-chat-proxy.grok.com consumer billing",
+		semantics: {
+			kind: "consumer-subscription",
+			label: "xAI consumer subscription usage",
+		},
+		buckets,
+		metrics,
+		...(notes.length > 0 ? { notes } : {}),
+	};
+}
+
+function normalizePeriod(
+	currentPeriod: unknown,
+	legacyStart: unknown,
+	legacyEnd: unknown,
+): Pick<UsageBucket, "period" | "resetsAt"> {
+	if (currentPeriod !== undefined && currentPeriod !== null && !isRecord(currentPeriod)) {
+		throw new Error("xAI billing currentPeriod was not an object or null.");
+	}
+	if (isRecord(currentPeriod)) {
+		const type = optionalString(currentPeriod.type, "currentPeriod.type");
+		const start = optionalTimestamp(currentPeriod.start, "currentPeriod.start");
+		const end = optionalTimestamp(currentPeriod.end, "currentPeriod.end");
+		return {
+			...(periodLabel(type, start) ? { period: periodLabel(type, start) } : {}),
+			...(end !== undefined ? { resetsAt: end } : {}),
+		};
+	}
+	const start = optionalTimestamp(legacyStart, "billingPeriodStart");
+	const end = optionalTimestamp(legacyEnd, "billingPeriodEnd");
+	return {
+		...(start !== undefined ? { period: "Monthly" } : {}),
+		...(end !== undefined ? { resetsAt: end } : {}),
+	};
+}
+
+function periodLabel(type: string | undefined, start: number | undefined): string | undefined {
+	if (type === "USAGE_PERIOD_TYPE_WEEKLY") return "Weekly";
+	if (type === "USAGE_PERIOD_TYPE_MONTHLY") return "Monthly";
+	if (type)
+		return sanitizeDisplayText(type.replace(/^USAGE_PERIOD_TYPE_/u, "").replaceAll("_", " "), 40);
+	return start === undefined ? undefined : "Current period";
+}
+
+function optionalUsd(value: unknown, field: string): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (!isRecord(value)) throw new Error(`xAI billing ${field} was not a cent wrapper.`);
+	const cents = value.val === undefined ? 0 : value.val;
+	if (!Number.isSafeInteger(cents) || Math.abs(cents as number) > MAX_SAFE_CENTS) {
+		throw new Error(`xAI billing ${field}.val was not a safe signed integer.`);
+	}
+	return (cents as number) / 100;
+}
+
+function optionalPercent(value: unknown, field: string): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+		throw new Error(`xAI billing ${field} was outside 0–100.`);
+	}
+	return value;
+}
+
+function optionalTimestamp(value: unknown, field: string): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length > 80) {
+		throw new Error(`xAI billing ${field} was not a bounded timestamp.`);
+	}
+	const milliseconds = Date.parse(value);
+	if (!Number.isFinite(milliseconds)) throw new Error(`xAI billing ${field} was invalid.`);
+	return Math.floor(milliseconds / 1000);
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length > 80) {
+		throw new Error(`xAI billing ${field} was not a bounded string.`);
+	}
+	return value;
+}
+
+function optionalTier(value: unknown): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length > 160) {
+		throw new Error("xAI subscription tier was not a bounded string or null.");
+	}
+	return sanitizeDisplayText(value, 80) || undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}