@narumitw/pi-usage 0.54.0 → 0.58.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-usage",
-	"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.",
+	"version": "0.58.0",
+	"description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -11,6 +11,9 @@
 		"pi",
 		"usage",
 		"quota",
+		"balance",
+		"deepseek",
+		"fireworks",
 		"codex",
 		"kimi",
 		"kimi-coding",
@@ -34,9 +37,6 @@
 			"./dist/index.ts"
 		]
 	},
-	"piExtension": {
-		"lifecycle": "stable"
-	},
 	"scripts": {
 		"build": "node scripts/build-runtime.mjs",
 		"check": "npm run build && biome check --vcs-use-ignore-file=false src test scripts package.json tsconfig.json README.md && npm run typecheck",
@@ -50,11 +50,11 @@
 		"@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",
+		"@biomejs/biome": "2.5.11",
+		"@earendil-works/pi-ai": "0.84.4",
+		"@earendil-works/pi-coding-agent": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
+		"@types/node": "26.4.0",
 		"esbuild": "0.28.2",
 		"typescript": "7.0.2"
 	},

package/src/codex-fast-runtime.ts

@@ -24,6 +24,7 @@ export function registerCodexFastMode(
 	pi: ExtensionAPI,
 	settingsRuntime: UsageSettingsRuntime,
 	refreshStatus: (ctx: ExtensionContext) => void,
+	options: { registerSessionStart?: boolean } = {},
 ) {
 	let sessionController = new AbortController();
 	let generation = 0;
@@ -95,41 +96,47 @@ export function registerCodexFastMode(
 		},
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
+	const prepareSession = (ctx: ExtensionContext): Promise<void> => {
+		const sessionId = ctx.sessionManager.getSessionId();
 		generation += 1;
 		sessionController.abort();
 		pendingFastRequests.clear();
 		sessionController = new AbortController();
 		const ownerGeneration = generation;
-		const sessionId = ctx.sessionManager.getSessionId();
-		let state: Readonly<UsageSettingsState>;
-		try {
-			state = await settingsRuntime.reload(sessionController.signal);
-		} catch (error) {
-			if (sessionController.signal.aborted || ownerGeneration !== generation) return;
-			if (ctx.hasUI) {
+		return (async () => {
+			let state: Readonly<UsageSettingsState>;
+			try {
+				state = await settingsRuntime.reload(sessionController.signal);
+			} catch (error) {
+				if (sessionController.signal.aborted || ownerGeneration !== generation) return;
+				if (ctx.hasUI) {
+					ctx.ui.notify(
+						`Could not load pi-usage.json; using defaults. ${errorMessage(error)}`,
+						"warning",
+					);
+				}
+				return;
+			}
+			if (
+				sessionController.signal.aborted ||
+				ownerGeneration !== generation ||
+				ctx.sessionManager.getSessionId() !== sessionId
+			) {
+				return;
+			}
+			if (ctx.hasUI && state.kind === "invalid") {
 				ctx.ui.notify(
-					`Could not load pi-usage.json; using defaults. ${errorMessage(error)}`,
+					`Invalid pi-usage.json; using defaults without overwriting it. ${state.issue}`,
 					"warning",
 				);
 			}
-			return;
-		}
-		if (
-			sessionController.signal.aborted ||
-			ownerGeneration !== generation ||
-			ctx.sessionManager.getSessionId() !== sessionId
-		) {
-			return;
-		}
-		if (ctx.hasUI && state.kind === "invalid") {
-			ctx.ui.notify(
-				`Invalid pi-usage.json; using defaults without overwriting it. ${state.issue}`,
-				"warning",
-			);
-		}
-		refreshStatus(ctx);
-	});
+			refreshStatus(ctx);
+		})();
+	};
+
+	if (options.registerSessionStart !== false) {
+		pi.on("session_start", async (_event, ctx) => prepareSession(ctx));
+	}
 
 	pi.on("before_provider_request", (event, ctx) => {
 		const rewritten = rewriteCodexFastPayload(
@@ -164,6 +171,7 @@ export function registerCodexFastMode(
 	});
 
 	return {
+		prepareSession,
 		availability(model: PiModel | undefined) {
 			return codexFastAvailability(model, settingsRuntime.get().settings.codexFastMode);
 		},

package/src/format.ts

@@ -11,11 +11,19 @@ const VALUE_COLUMN = 29;
 
 export function formatUsageReport(report: UsageReport, displayState: UsageDisplayState): string {
 	const stateLabel = displayState === "current" ? "Current" : "Configured";
-	const lines = [`${report.providerName} Usage · ${stateLabel}`];
+	const title =
+		report.providerId === "deepseek"
+			? "DeepSeek API Balance"
+			: report.providerId === "fireworks"
+				? "Fireworks API Spend"
+				: `${report.providerName} Usage`;
+	const lines = [`${title} · ${stateLabel}`];
 	if (report.accountLabel) lines.push(`Account: ${report.accountLabel}`);
 	lines.push(`Semantics: ${report.semantics.label}`, "");
 
 	if (report.providerId === "openai-codex") formatCodexReport(lines, report);
+	else if (report.providerId === "deepseek") formatDeepSeekReport(lines, report);
+	else if (report.providerId === "fireworks") formatFireworksReport(lines, report);
 	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);
@@ -31,8 +39,17 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
 	return lines.join("\n").trimEnd();
 }
 
-export function formatUsageStatusline(report: UsageReport, model?: UsageModel): string | undefined {
-	if (report.providerId === "openai-codex") return formatCodexStatusline(report, model);
+export function formatUsageStatusline(
+	report: UsageReport,
+	model?: UsageModel,
+	now = Date.now(),
+	showCodexResetCountdown = true,
+): string | undefined {
+	if (report.providerId === "openai-codex") {
+		return formatCodexStatusline(report, model, now, showCodexResetCountdown);
+	}
+	if (report.providerId === "deepseek") return formatDeepSeekStatusline(report);
+	if (report.providerId === "fireworks") return formatFireworksStatusline(report);
 	if (report.providerId === "github-copilot") return formatGitHubCopilotStatusline(report);
 	if (report.providerId === "openrouter") {
 		const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
@@ -42,6 +59,9 @@ export function formatUsageStatusline(report: UsageReport, model?: UsageModel):
 	}
 	if (report.providerId === "opencode-go") return formatOpenCodeZenStatusline(report);
 	if (report.providerId === "kimi-coding") return formatKimiCodingStatusline(report);
+	if (report.providerId === "zai" || report.providerId === "zai-coding-cn") {
+		return formatZaiStatusline(report);
+	}
 	return undefined;
 }
 
@@ -84,6 +104,59 @@ function formatCodexReport(lines: string[], report: UsageReport): void {
 	}
 }
 
+function formatDeepSeekReport(lines: string[], report: UsageReport): void {
+	const availability = report.metrics.find((metric) => metric.id === "api-availability");
+	lines.push(
+		`${"API calls:".padEnd(VALUE_COLUMN)}${availability?.value === "available" ? "Available" : "Unavailable"}`,
+	);
+	for (const currency of ["CNY", "USD"]) {
+		const metrics = report.metrics.filter((metric) => metric.currency === currency);
+		if (metrics.length === 0) continue;
+		lines.push("", `${currency} balance:`);
+		for (const metric of metrics) {
+			lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${currency} ${metric.value}`);
+		}
+	}
+}
+
+function formatDeepSeekStatusline(report: UsageReport): string {
+	const availability = report.metrics.find((metric) => metric.id === "api-availability");
+	if (availability?.value !== "available") return "deepseek API unavailable";
+	const totals = ["CNY", "USD"].flatMap((currency) => {
+		const metric = report.metrics.find(
+			(candidate) => candidate.id === `${currency.toLowerCase()}-total`,
+		);
+		return metric ? [`${currency} ${metric.value}`] : [];
+	});
+	return totals.length > 0 ? `deepseek ${totals.join(" · ")}` : "deepseek balance unavailable";
+}
+
+function formatFireworksReport(lines: string[], report: UsageReport): void {
+	lines.push(`${"Spend window:".padEnd(VALUE_COLUMN)}Last 30 days (rated)`);
+	for (const currency of fireworksCurrencies(report)) {
+		lines.push("", `${currency} rated spend:`);
+		for (const metric of report.metrics) {
+			if (metric.currency !== currency) continue;
+			lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${currency} ${metric.value}`);
+		}
+	}
+}
+
+function formatFireworksStatusline(report: UsageReport): string {
+	const totals = report.metrics.filter((metric) => metric.id.endsWith("-total"));
+	if (totals.length === 0) return "fireworks no rated usage";
+	return `fireworks ${totals.map((metric) => `${metric.currency} ${metric.value}`).join(" · ")}`;
+}
+
+function fireworksCurrencies(report: UsageReport): string[] {
+	const currencies: string[] = [];
+	for (const metric of report.metrics) {
+		if (!metric.currency || currencies.includes(metric.currency)) continue;
+		currencies.push(metric.currency);
+	}
+	return currencies;
+}
+
 function formatGitHubCopilotReport(lines: string[], report: UsageReport): void {
 	const quota = findGitHubCopilotQuota(report);
 	if (!quota || quota.limit === undefined || quota.remaining === undefined) {
@@ -213,6 +286,22 @@ function formatKimiCodingStatusline(report: UsageReport): string | undefined {
 	return parts.length > 1 ? parts.join(" ") : undefined;
 }
 
+function formatZaiStatusline(report: UsageReport): string | undefined {
+	const selected = [
+		report.buckets.find((bucket) => bucket.id === "five-hour"),
+		report.buckets.find((bucket) => bucket.id === "weekly"),
+	];
+	const parts = ["zai"];
+	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";
@@ -289,7 +378,12 @@ function formatGenericReport(lines: string[], report: UsageReport): void {
 	}
 }
 
-function formatCodexStatusline(report: UsageReport, model?: UsageModel): string | undefined {
+function formatCodexStatusline(
+	report: UsageReport,
+	model?: UsageModel,
+	now = Date.now(),
+	showResetCountdown = true,
+): string | undefined {
 	const group = selectCodexGroup(report, model);
 	if (!group) return formatCodexCreditsStatus(report);
 	const buckets = report.buckets.filter((bucket) => (bucket.groupId ?? bucket.id) === group);
@@ -299,10 +393,15 @@ function formatCodexStatusline(report: UsageReport, model?: UsageModel): string
 	];
 	for (const bucket of buckets) {
 		if (bucket.remaining === undefined) continue;
+		const percent = `${clampPercent(bucket.remaining).toFixed(0)}%`;
 		const fallback = bucket.id.endsWith(":secondary") ? "weekly" : "5h";
-		parts.push(
-			`${clampPercent(bucket.remaining).toFixed(0)}% ${formatWindowLabel(bucket.windowMinutes, fallback, true)}`,
-		);
+		const window = formatWindowLabel(bucket.windowMinutes, fallback, true);
+		if (!showResetCountdown) {
+			parts.push(`${percent} ${window}`);
+			continue;
+		}
+		const reset = formatResetCountdown(bucket.resetsAt, now);
+		parts.push(`${percent} ${reset ? `↻ ${reset}` : window}`);
 	}
 	return parts.length > 1 ? parts.join(" ") : formatCodexCreditsStatus(report);
 }
@@ -405,6 +504,26 @@ function formatWindowLabel(
 	return `${minutes}m`;
 }
 
+function formatResetCountdown(resetsAt: number | undefined, now: number): string | undefined {
+	if (resetsAt === undefined || !Number.isFinite(resetsAt) || !Number.isFinite(now))
+		return undefined;
+	const totalMinutes = Math.max(0, Math.ceil((resetsAt * 1_000 - now) / 60_000));
+	const days = Math.floor(totalMinutes / 1_440);
+	const hours = Math.floor((totalMinutes % 1_440) / 60);
+	const minutes = totalMinutes % 60;
+	if (days > 0) {
+		return [
+			`${String(days)}d`,
+			hours > 0 ? `${String(hours)}h` : minutes > 0 ? `${String(minutes)}m` : "",
+		]
+			.filter(Boolean)
+			.join("");
+	}
+	if (hours > 0)
+		return [`${String(hours)}h`, minutes > 0 ? `${String(minutes)}m` : ""].filter(Boolean).join("");
+	return `${String(minutes)}m`;
+}
+
 function formatMetricValue(value: number | string, unit: UsageBucket["unit"] | undefined): string {
 	if (unit === "usd" && typeof value === "number") return formatUsd(value);
 	return String(value);

package/src/index.ts

@@ -33,6 +33,11 @@ export {
 } from "./core.js";
 export { formatProviderStates, formatUsageReport, formatUsageStatusline } from "./format.js";
 export { normalizeCodexBackendPayload } from "./providers/codex.js";
+export { normalizeDeepSeekBalancePayload } from "./providers/deepseek.js";
+export {
+	normalizeFireworksAccountsPayload,
+	normalizeFireworksBillingSummaryPayload,
+} from "./providers/fireworks.js";
 export { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
 export { normalizeKimiCodingUsagePayload } from "./providers/kimi-coding.js";
 export { normalizeOpenCodeZenPayload } from "./providers/opencode-zen.js";
@@ -62,6 +67,9 @@ export {
 	usageSettingsPath,
 } from "./settings.js";
 export type {
+	DeepSeekBalancePayload,
+	FireworksAccountsPayload,
+	FireworksBillingSummaryPayload,
 	KimiCodingUsagePayload,
 	ProviderUsageState,
 	ResolvedUsageAuth,
@@ -70,6 +78,7 @@ export type {
 	UsageMetric,
 	UsageModel,
 	UsageProviderAdapter,
+	UsageQuerySettings,
 	UsageReport,
 	UsageSemantics,
 	UsageSemanticsKind,

package/src/providers/deepseek.ts

@@ -0,0 +1,85 @@
+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)
+	);
+}

package/src/providers/fireworks.ts

@@ -0,0 +1,198 @@
+import { sanitizeDisplayText } from "../core.js";
+import type {
+	FireworksAccountsPayload,
+	FireworksBillingSummaryPayload,
+	UsageMetric,
+	UsageReport,
+} from "../types.js";
+
+const NANOS_PER_UNIT = 1_000_000_000n;
+const CURRENCY_PATTERN = /^[A-Z]{3}$/u;
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/u;
+const INTEGER_PATTERN = /^-?\d+$/u;
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+const MAX_UNITS_CHARS = 20;
+const MAX_NANOS_CHARS = 11;
+
+const SERIES_KEYS = ["serverless", "dedicated", "training", "other"] as const;
+type SeriesKey = (typeof SERIES_KEYS)[number];
+
+const SERIES_LABELS: Readonly<Record<SeriesKey, string>> = {
+	serverless: "Serverless",
+	dedicated: "Dedicated deployments",
+	training: "Training",
+	other: "Other",
+};
+
+export function isFireworksAccountId(value: unknown): value is string {
+	return typeof value === "string" && ACCOUNT_ID_PATTERN.test(value);
+}
+
+export function normalizeFireworksAccountsPayload(payload: FireworksAccountsPayload): string[] {
+	if (!Array.isArray(payload.accounts)) {
+		throw new Error("Fireworks accounts response did not contain an accounts array.");
+	}
+	const accounts: string[] = [];
+	for (const raw of payload.accounts) {
+		const account = asObject(raw);
+		if (!account) throw new Error("Fireworks accounts response row was not an object.");
+		if (typeof account.name !== "string") {
+			throw new Error("Fireworks accounts response omitted the account resource name.");
+		}
+		const match = /^accounts\/([^/]+)$/u.exec(account.name);
+		if (!match || !isFireworksAccountId(match[1])) {
+			throw new Error("Fireworks accounts response returned an unsafe account resource name.");
+		}
+		const accountId = match[1];
+		if (accounts.includes(accountId)) {
+			throw new Error(`Fireworks accounts response repeated ${accountId}.`);
+		}
+		accounts.push(accountId);
+	}
+	return accounts;
+}
+
+export function normalizeFireworksBillingSummaryPayload(
+	payload: FireworksBillingSummaryPayload,
+	accountId: string,
+	capturedAt: number,
+): UsageReport {
+	if (!isFireworksAccountId(accountId)) {
+		throw new Error("Fireworks billing summary received an unsafe account identifier.");
+	}
+	if (payload.lineItems !== undefined && !Array.isArray(payload.lineItems)) {
+		throw new Error("Fireworks billing summary lineItems was not an array.");
+	}
+
+	const totals = new Map<string, Map<SeriesKey, bigint>>();
+	for (const raw of payload.lineItems ?? []) {
+		const lineItem = asObject(raw);
+		if (!lineItem) throw new Error("Fireworks billing line item was not an object.");
+		const cost = moneyAmount(lineItem.totalCost, "line item total cost");
+		const series = seriesKey(lineItem.series);
+		let amounts = totals.get(cost.currency);
+		if (!amounts) {
+			amounts = new Map<SeriesKey, bigint>();
+			totals.set(cost.currency, amounts);
+		}
+		amounts.set(series, (amounts.get(series) ?? 0n) + cost.amount);
+	}
+
+	const metrics: UsageMetric[] = [];
+	for (const [currency, amounts] of totals) {
+		metrics.push({
+			id: `${currency.toLowerCase()}-total`,
+			label: "Total spend",
+			value: formatMoneyAmount(sumSeries(amounts)),
+			unit: "currency",
+			currency,
+		});
+		for (const series of SERIES_KEYS) {
+			const amount = amounts.get(series);
+			if (amount === undefined) continue;
+			metrics.push({
+				id: `${currency.toLowerCase()}-${series}`,
+				label: SERIES_LABELS[series],
+				value: formatMoneyAmount(amount),
+				unit: "currency",
+				currency,
+			});
+		}
+	}
+
+	const notes = [
+		"Rated line items may differ from the final invoice once credits or adjustments are applied.",
+	];
+	if (metrics.length === 0) {
+		notes.push("Fireworks returned no rated line items for the last 30 days.");
+	}
+
+	return {
+		providerId: "fireworks",
+		providerName: "Fireworks",
+		capturedAt,
+		source: "fireworks-billing-summary",
+		semantics: { kind: "api-key", label: "Fireworks API spend" },
+		accountLabel: sanitizeDisplayText(accountId, 80),
+		buckets: [],
+		metrics,
+		notes,
+	};
+}
+
+type RatedMoney = { currency: string; amount: bigint };
+
+function moneyAmount(value: unknown, description: string): RatedMoney {
+	const money = asObject(value);
+	if (!money) throw new Error(`Fireworks billing ${description} was not a money object.`);
+	const currency = typeof money.currencyCode === "string" ? money.currencyCode : undefined;
+	if (!currency || !CURRENCY_PATTERN.test(currency)) {
+		throw new Error(`Fireworks billing ${description} currency was not an ISO 4217 code.`);
+	}
+	// proto3 JSON omits zero-valued money fields, so absent components default to zero.
+	const units =
+		money.units === undefined
+			? 0n
+			: integerComponent(money.units, description, "whole units", MAX_UNITS_CHARS);
+	if (units < INT64_MIN || units > INT64_MAX) {
+		throw new Error(`Fireworks billing ${description} whole units exceeded the int64 range.`);
+	}
+	const nanos =
+		money.nanos === undefined
+			? 0n
+			: integerComponent(money.nanos, description, "nano units", MAX_NANOS_CHARS);
+	if (nanos <= -NANOS_PER_UNIT || nanos >= NANOS_PER_UNIT) {
+		throw new Error(`Fireworks billing ${description} nano units exceeded the Money range.`);
+	}
+	if ((units > 0n && nanos < 0n) || (units < 0n && nanos > 0n)) {
+		throw new Error(`Fireworks billing ${description} mixed unit and nano signs.`);
+	}
+	return { currency, amount: units * NANOS_PER_UNIT + nanos };
+}
+
+function integerComponent(
+	value: unknown,
+	description: string,
+	component: string,
+	maxChars: number,
+): bigint {
+	const text =
+		typeof value === "number" && Number.isSafeInteger(value)
+			? String(value)
+			: typeof value === "string" && INTEGER_PATTERN.test(value)
+				? value
+				: undefined;
+	if (text === undefined || text.length > maxChars) {
+		throw new Error(`Fireworks billing ${description} ${component} was not a bounded integer.`);
+	}
+	return BigInt(text);
+}
+
+function seriesKey(value: unknown): SeriesKey {
+	if (value === undefined || value === null) return "other";
+	if (typeof value !== "string") throw new Error("Fireworks billing line item series was invalid.");
+	if (value === "SERVERLESS") return "serverless";
+	if (value === "DEDICATED_DEPLOYMENT") return "dedicated";
+	if (value === "TRAINING") return "training";
+	return "other";
+}
+
+function sumSeries(amounts: ReadonlyMap<SeriesKey, bigint>): bigint {
+	let total = 0n;
+	for (const amount of amounts.values()) total += amount;
+	return total;
+}
+
+function formatMoneyAmount(amount: bigint): string {
+	const negative = amount < 0n;
+	const magnitude = negative ? -amount : amount;
+	const units = magnitude / NANOS_PER_UNIT;
+	const nanos = (magnitude % NANOS_PER_UNIT).toString().padStart(9, "0").replace(/0+$/u, "");
+	return `${negative ? "-" : ""}${units.toString()}${nanos ? `.${nanos}` : ""}`;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as Record<string, unknown>;
+}