@narumitw/pi-usage 0.57.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.57.0",
+	"version": "0.59.0",
 	"description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
 	"type": "module",
 	"license": "MIT",
@@ -13,9 +13,16 @@
 		"quota",
 		"balance",
 		"deepseek",
+		"fireworks",
+		"baseten",
+		"vercel-ai-gateway",
 		"codex",
 		"kimi",
 		"kimi-coding",
+		"moonshot",
+		"moonshotai",
+		"minimax",
+		"token-plan",
 		"copilot",
 		"openrouter",
 		"opencode",

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

@@ -12,18 +12,39 @@ const VALUE_COLUMN = 29;
 export function formatUsageReport(report: UsageReport, displayState: UsageDisplayState): string {
 	const stateLabel = displayState === "current" ? "Current" : "Configured";
 	const title =
-		report.providerId === "deepseek" ? "DeepSeek API Balance" : `${report.providerName} Usage`;
+		report.providerId === "baseten"
+			? "Baseten Model APIs Spend"
+			: report.providerId === "deepseek"
+				? "DeepSeek API Balance"
+				: report.providerId === "fireworks"
+					? "Fireworks API Spend"
+					: report.providerId === "vercel-ai-gateway"
+						? "Vercel AI Gateway Credits"
+						: report.providerId === "moonshotai" || report.providerId === "moonshotai-cn"
+							? `${report.providerName} Balance`
+							: report.providerId === "minimax" || report.providerId === "minimax-cn"
+								? report.source === "minimax-account-balance"
+									? `${report.providerName} API Balance`
+									: `${report.providerName} Token Plan`
+								: `${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);
+	if (report.providerId === "baseten") formatBasetenReport(lines, report);
+	else 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 === "vercel-ai-gateway") formatVercelAIGatewayReport(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);
 	else if (report.providerId === "kimi-coding") formatKimiCodingReport(lines, report);
-	else if (report.providerId === "xai") formatXaiReport(lines, report);
+	else if (report.providerId === "moonshotai" || report.providerId === "moonshotai-cn") {
+		formatMoonshotReport(lines, report);
+	} else if (report.providerId === "minimax" || report.providerId === "minimax-cn") {
+		formatMiniMaxReport(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);
@@ -40,10 +61,13 @@ export function formatUsageStatusline(
 	now = Date.now(),
 	showCodexResetCountdown = true,
 ): string | undefined {
+	if (report.providerId === "baseten") return formatBasetenStatusline(report);
 	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 === "vercel-ai-gateway") return formatVercelAIGatewayStatusline(report);
 	if (report.providerId === "github-copilot") return formatGitHubCopilotStatusline(report);
 	if (report.providerId === "openrouter") {
 		const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
@@ -53,6 +77,12 @@ export function formatUsageStatusline(
 	}
 	if (report.providerId === "opencode-go") return formatOpenCodeZenStatusline(report);
 	if (report.providerId === "kimi-coding") return formatKimiCodingStatusline(report);
+	if (report.providerId === "moonshotai" || report.providerId === "moonshotai-cn") {
+		return formatMoonshotStatusline(report);
+	}
+	if (report.providerId === "minimax" || report.providerId === "minimax-cn") {
+		return formatMiniMaxStatusline(report, model);
+	}
 	if (report.providerId === "zai" || report.providerId === "zai-coding-cn") {
 		return formatZaiStatusline(report);
 	}
@@ -75,6 +105,18 @@ export function formatProviderStates(states: readonly ProviderUsageState[]): str
 		.join("\n\n");
 }
 
+function formatBasetenReport(lines: string[], report: UsageReport): void {
+	lines.push(`${"Spend window:".padEnd(VALUE_COLUMN)}Last 30 days`);
+	for (const metric of report.metrics) {
+		lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}USD ${metric.value}`);
+	}
+}
+
+function formatBasetenStatusline(report: UsageReport): string {
+	const subtotal = report.metrics.find((metric) => metric.id === "net-subtotal");
+	return subtotal ? `baseten USD ${subtotal.value} net` : "baseten no Model APIs usage";
+}
+
 function formatCodexReport(lines: string[], report: UsageReport): void {
 	let previousGroup: string | undefined;
 	for (const bucket of report.buckets) {
@@ -125,6 +167,43 @@ function formatDeepSeekStatusline(report: UsageReport): string {
 	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 formatVercelAIGatewayReport(lines: string[], report: UsageReport): void {
+	for (const metric of report.metrics) {
+		lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}USD ${metric.value}`);
+	}
+}
+
+function formatVercelAIGatewayStatusline(report: UsageReport): string {
+	const balance = report.metrics.find((metric) => metric.id === "credit-balance");
+	return balance ? `vercel USD ${balance.value} left` : "vercel credits unavailable";
+}
+
 function formatGitHubCopilotReport(lines: string[], report: UsageReport): void {
 	const quota = findGitHubCopilotQuota(report);
 	if (!quota || quota.limit === undefined || quota.remaining === undefined) {
@@ -254,6 +333,113 @@ function formatKimiCodingStatusline(report: UsageReport): string | undefined {
 	return parts.length > 1 ? parts.join(" ") : undefined;
 }
 
+function formatMoonshotReport(lines: string[], report: UsageReport): void {
+	for (const metric of report.metrics) {
+		lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${metric.currency} ${metric.value}`);
+	}
+}
+
+function formatMoonshotStatusline(report: UsageReport): string {
+	const available = report.metrics.find((metric) => metric.id === "available-balance");
+	if (!available) return "moonshot balance unavailable";
+	return `moonshot ${available.currency ?? ""} ${available.value}`.replace(/\s+/gu, " ");
+}
+
+function formatMiniMaxReport(lines: string[], report: UsageReport): void {
+	if (report.source === "minimax-account-balance") {
+		for (const metric of report.metrics) {
+			lines.push(`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${metric.currency} ${metric.value}`);
+		}
+		return;
+	}
+	let previousGroup: string | undefined;
+	for (const bucket of report.buckets) {
+		if (bucket.groupId !== previousGroup) lines.push(`${bucket.groupLabel ?? "Token Plan"}:`);
+		previousGroup = bucket.groupId;
+		const reset = bucket.resetsAt ? ` (resets ${formatReset(bucket.resetsAt)})` : "";
+		const value =
+			bucket.period === "unlimited"
+				? "unlimited"
+				: bucket.limit && bucket.remaining !== undefined
+					? `${bucket.remaining} of ${bucket.limit} left · ${percentRemaining(bucket)}%${reset}`
+					: "unavailable";
+		lines.push(`${`${bucket.label}:`.padEnd(VALUE_COLUMN)}${value}`);
+	}
+}
+
+function formatMiniMaxStatusline(report: UsageReport, model?: UsageModel): string | undefined {
+	const prefix = report.providerId === "minimax-cn" ? "minimax cn" : "minimax";
+	if (report.source === "minimax-account-balance") {
+		const available = report.metrics.find((metric) => metric.id === "available-balance");
+		return available ? `${prefix} ${available.currency} ${available.value}` : undefined;
+	}
+	const selectedGroup = selectMiniMaxGroup(report, model);
+	if (!selectedGroup) return undefined;
+	const selected = report.buckets.filter((bucket) => bucket.groupId === selectedGroup);
+	const parts = [prefix];
+	for (const bucket of selected) {
+		const fallback = bucket.id.endsWith(":weekly") ? "weekly" : "5h";
+		const window = formatWindowLabel(bucket.windowMinutes, fallback, true);
+		if (bucket.period === "unlimited") {
+			parts.push(`unlimited ${window}`);
+			continue;
+		}
+		if (!bucket.limit || bucket.remaining === undefined) continue;
+		parts.push(`${percentRemaining(bucket)}% ${window}`);
+	}
+	return parts.length > 1 ? parts.join(" ") : undefined;
+}
+
+function selectMiniMaxGroup(report: UsageReport, model?: UsageModel): string | undefined {
+	const groups = [
+		...new Set(
+			report.buckets
+				.map((bucket) => bucket.groupId)
+				.filter((group): group is string => group !== undefined),
+		),
+	];
+	if (groups.length <= 1) return groups[0];
+	if (model?.provider !== report.providerId) return undefined;
+	const modelKeys = [model.id, model.name]
+		.map(normalizeMiniMaxModelKey)
+		.filter((key): key is string => key !== undefined);
+	const candidates = groups.map((group) => {
+		const bucket = report.buckets.find((candidate) => candidate.groupId === group);
+		const patterns = [bucket?.groupLabel, ...(bucket?.modelKeys ?? []), group]
+			.map(normalizeMiniMaxModelKey)
+			.filter((key): key is string => key !== undefined);
+		return { group, patterns };
+	});
+	const exact = candidates.find(({ patterns }) =>
+		patterns.some((pattern) => !pattern.includes("*") && modelKeys.includes(pattern)),
+	);
+	if (exact) return exact.group;
+	return candidates.find(({ patterns }) =>
+		patterns.some(
+			(pattern) =>
+				pattern.includes("*") && modelKeys.some((key) => wildcardKeyMatches(pattern, key)),
+		),
+	)?.group;
+}
+
+function normalizeMiniMaxModelKey(value: string | undefined): string | undefined {
+	const key = value?.toLowerCase().replace(/[^a-z0-9*]+/gu, "");
+	return key && /[a-z0-9]/u.test(key) ? key : undefined;
+}
+
+function wildcardKeyMatches(pattern: string, value: string): boolean {
+	if (!pattern.includes("*")) return pattern === value;
+	const segments = pattern.split("*").filter(Boolean);
+	let offset = 0;
+	for (const [index, segment] of segments.entries()) {
+		const found = value.indexOf(segment, offset);
+		if (found < 0 || (index === 0 && !pattern.startsWith("*") && found !== 0)) return false;
+		offset = found + segment.length;
+	}
+	const last = segments.at(-1);
+	return pattern.endsWith("*") || (last !== undefined && value.endsWith(last));
+}
+
 function formatZaiStatusline(report: UsageReport): string | undefined {
 	const selected = [
 		report.buckets.find((bucket) => bucket.id === "five-hour"),

package/src/index.ts

@@ -32,12 +32,25 @@ export {
 	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 {
+	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 } from "./providers/zai.js";
 export {
@@ -63,8 +76,13 @@ export {
 	usageSettingsPath,
 } from "./settings.js";
 export type {
+	BasetenBillingUsagePayload,
 	DeepSeekBalancePayload,
+	FireworksAccountsPayload,
+	FireworksBillingSummaryPayload,
 	KimiCodingUsagePayload,
+	MiniMaxUsagePayload,
+	MoonshotBalancePayload,
 	ProviderUsageState,
 	ResolvedUsageAuth,
 	UsageBucket,
@@ -72,10 +90,12 @@ export type {
 	UsageMetric,
 	UsageModel,
 	UsageProviderAdapter,
+	UsageQuerySettings,
 	UsageReport,
 	UsageSemantics,
 	UsageSemanticsKind,
 	UsageUnit,
+	VercelAIGatewayCreditsPayload,
 	XaiBillingPayload,
 	XaiUserPayload,
 } from "./types.js";

package/src/providers/baseten.ts

@@ -0,0 +1,55 @@
+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/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>;
+}