@narumitw/pi-usage 0.57.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.57.0",
+	"version": "0.58.0",
 	"description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
 	"type": "module",
 	"license": "MIT",
@@ -13,6 +13,7 @@
 		"quota",
 		"balance",
 		"deepseek",
+		"fireworks",
 		"codex",
 		"kimi",
 		"kimi-coding",

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,13 +12,18 @@ 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 === "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);
@@ -44,6 +49,7 @@ export function formatUsageStatusline(
 		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");
@@ -125,6 +131,32 @@ 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 formatGitHubCopilotReport(lines: string[], report: UsageReport): void {
 	const quota = findGitHubCopilotQuota(report);
 	if (!quota || quota.limit === undefined || quota.remaining === undefined) {

package/src/index.ts

@@ -34,6 +34,10 @@ export {
 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";
@@ -64,6 +68,8 @@ export {
 } from "./settings.js";
 export type {
 	DeepSeekBalancePayload,
+	FireworksAccountsPayload,
+	FireworksBillingSummaryPayload,
 	KimiCodingUsagePayload,
 	ProviderUsageState,
 	ResolvedUsageAuth,
@@ -72,6 +78,7 @@ export type {
 	UsageMetric,
 	UsageModel,
 	UsageProviderAdapter,
+	UsageQuerySettings,
 	UsageReport,
 	UsageSemantics,
 	UsageSemanticsKind,

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>;
+}

package/src/query.ts

@@ -7,6 +7,11 @@ import {
 } from "./oauth-credential-source.js";
 import { normalizeCodexBackendPayload } from "./providers/codex.js";
 import { normalizeDeepSeekBalancePayload } from "./providers/deepseek.js";
+import {
+	isFireworksAccountId,
+	normalizeFireworksAccountsPayload,
+	normalizeFireworksBillingSummaryPayload,
+} from "./providers/fireworks.js";
 import { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
 import { normalizeKimiCodingUsagePayload } from "./providers/kimi-coding.js";
 import { normalizeOpenCodeZenPayload } from "./providers/opencode-zen.js";
@@ -16,6 +21,8 @@ import { normalizeZaiQuotaPayload } from "./providers/zai.js";
 import type {
 	CodexBackendPayload,
 	DeepSeekBalancePayload,
+	FireworksAccountsPayload,
+	FireworksBillingSummaryPayload,
 	GitHubCopilotUsagePayload,
 	KimiCodingUsagePayload,
 	OpenCodeZenPayload,
@@ -23,6 +30,7 @@ import type {
 	PiModel,
 	ResolvedUsageAuth,
 	UsageProviderAdapter,
+	UsageQuerySettings,
 	UsageReport,
 	XaiBillingPayload,
 	XaiUserPayload,
@@ -31,6 +39,9 @@ import type {
 
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
+const FIREWORKS_BILLING_SUMMARY_ORIGIN = "https://api.fireworks.ai";
+const FIREWORKS_SPEND_WINDOW_DAYS = 30;
+const FIREWORKS_MAX_ACCOUNT_PAGES = 5;
 const GITHUB_COPILOT_USAGE_URL = "https://api.github.com/copilot_internal/user";
 const OPENROUTER_KEY_URL = "https://openrouter.ai/api/v1/key";
 const OPENCODE_GO_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
@@ -122,6 +133,35 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 			return normalizeOpenRouterKeyPayload(payload as OpenRouterKeyPayload, Date.now());
 		},
 	},
+	{
+		id: "fireworks",
+		displayName: "Fireworks",
+		semantics: { kind: "api-key", label: "Fireworks API spend" },
+		async query(auth, signal, timeoutMs, guard, settings) {
+			if (!guard) throw new Error("Fireworks API spend requires request-boundary revalidation.");
+			const startedAt = Date.now();
+			await guard();
+			const accountId = await resolveFireworksAccountId(
+				auth,
+				signal,
+				remainingTimeout(timeoutMs, startedAt, "resolving the Fireworks account"),
+				guard,
+				settings?.fireworksAccountId,
+			);
+			await guard();
+			const billingWindowAt = Date.now();
+			const payload = (await fetchProviderJson(
+				fireworksBillingSummaryUrl(accountId, billingWindowAt),
+				auth,
+				signal,
+				remainingTimeout(timeoutMs, startedAt, "fetching Fireworks rated spend"),
+				"Fireworks billing summary endpoint",
+				{ redirect: "error" },
+			)) as FireworksBillingSummaryPayload;
+			await guard();
+			return normalizeFireworksBillingSummaryPayload(payload, accountId, Date.now());
+		},
+	},
 	{
 		id: "opencode-go",
 		displayName: "OpenCode Go",
@@ -370,9 +410,10 @@ export async function queryProviderUsage(
 	signal: AbortSignal,
 	timeoutMs: number,
 	guard?: UsageRequestGuard,
+	settings?: Readonly<UsageQuerySettings>,
 ): Promise<UsageReport> {
 	try {
-		return await adapter.query(auth, signal, timeoutMs, guard);
+		return await adapter.query(auth, signal, timeoutMs, guard, settings);
 	} catch (error) {
 		if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
 		throw new Error(redactUsageError(errorMessage(error), auth.secrets));
@@ -733,6 +774,7 @@ function hasOfficialUrlOrigin(value: string, providerId: string): boolean {
 		const url = new URL(value);
 		if (providerId === "openai-codex") return url.origin === "https://chatgpt.com";
 		if (providerId === "deepseek") return url.origin === "https://api.deepseek.com";
+		if (providerId === "fireworks") return url.origin === FIREWORKS_BILLING_SUMMARY_ORIGIN;
 		if (providerId === "openrouter") return url.origin === "https://openrouter.ai";
 		if (providerId === "opencode-go") return url.origin === "https://opencode.ai";
 		if (providerId === "kimi-coding") return url.origin === "https://api.kimi.com";
@@ -771,12 +813,108 @@ function validatedXaiUserId(value: unknown): string {
 	return value;
 }
 
-function remainingTimeout(timeoutMs: number, startedAt: number): number {
+function remainingTimeout(
+	timeoutMs: number,
+	startedAt: number,
+	description = "fetching xAI consumer usage",
+): number {
 	const remaining = timeoutMs - (Date.now() - startedAt);
-	if (remaining <= 0) throw new Error("Timed out while fetching xAI consumer usage.");
+	if (remaining <= 0) throw new Error(`Timed out while ${description}.`);
 	return remaining;
 }
 
+// Fireworks requires an account slug for its billing endpoints; discover it through the
+// documented account listing, requiring an explicit slug when a key can see several accounts.
+async function resolveFireworksAccountId(
+	auth: ResolvedUsageAuth,
+	signal: AbortSignal,
+	timeoutMs: number,
+	guard: () => Promise<void>,
+	configuredAccountId: string | undefined,
+): Promise<string> {
+	if (configuredAccountId !== undefined && !isFireworksAccountId(configuredAccountId)) {
+		throw new Error("The Fireworks account setting was not a safe account slug.");
+	}
+	const startedAt = Date.now();
+	const accounts: string[] = [];
+	let pageToken: string | undefined;
+	for (let page = 0; page < FIREWORKS_MAX_ACCOUNT_PAGES; page += 1) {
+		await guard();
+		const payload = (await fetchProviderJson(
+			fireworksAccountsUrl(pageToken),
+			auth,
+			signal,
+			remainingTimeout(timeoutMs, startedAt, "fetching Fireworks accounts"),
+			"Fireworks accounts endpoint",
+			{ redirect: "error" },
+		)) as FireworksAccountsPayload;
+		for (const accountId of normalizeFireworksAccountsPayload(
+			payload as FireworksAccountsPayload,
+		)) {
+			if (accounts.includes(accountId)) {
+				throw new Error(`Fireworks accounts listing repeated ${accountId}.`);
+			}
+			accounts.push(accountId);
+			if (configuredAccountId === accountId) return accountId;
+		}
+		pageToken = fireworksNextPageToken(payload.nextPageToken);
+		if (!pageToken) break;
+	}
+	if (pageToken) {
+		throw new Error(
+			configuredAccountId
+				? `The configured Fireworks account was not found within the first ${FIREWORKS_MAX_ACCOUNT_PAGES} listing pages.`
+				: `Fireworks account listing exceeded ${FIREWORKS_MAX_ACCOUNT_PAGES} pages; set fireworksAccountId in pi-usage.json to an account returned in those pages.`,
+		);
+	}
+	if (accounts.length === 0) {
+		throw new Error("Fireworks account discovery returned no accounts for this API key.");
+	}
+	if (configuredAccountId) {
+		throw new Error(
+			"The configured Fireworks account does not match an account visible to this API key.",
+		);
+	}
+	if (accounts.length === 1) return accounts[0] as string;
+	const preview = accounts.slice(0, 8).join(", ");
+	const suffix = accounts.length > 8 ? ` …and ${accounts.length - 8} more` : "";
+	throw new Error(
+		`The Fireworks key can see ${accounts.length} accounts (${preview}${suffix}); set fireworksAccountId in pi-usage.json to one of them.`,
+	);
+}
+
+function fireworksAccountsUrl(pageToken: string | undefined): string {
+	const url = new URL("/v1/accounts", FIREWORKS_BILLING_SUMMARY_ORIGIN);
+	url.searchParams.set("pageSize", "200");
+	if (pageToken !== undefined) url.searchParams.set("pageToken", pageToken);
+	return url.toString();
+}
+
+function fireworksNextPageToken(value: unknown): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || !value || value.length > 512) {
+		throw new Error("Fireworks accounts listing returned an invalid page token.");
+	}
+	return value;
+}
+
+function fireworksBillingSummaryUrl(accountId: string, startedAt: number): string {
+	const dayMs = 24 * 60 * 60 * 1000;
+	const dayFloor = (time: number) => `${new Date(time).toISOString().slice(0, 10)}T00:00:00Z`;
+	const url = new URL(
+		`/v1/accounts/${accountId}/billing/summary`,
+		FIREWORKS_BILLING_SUMMARY_ORIGIN,
+	);
+	// The endpoint aggregates by UTC date; endTime is exclusive, so the window includes today
+	// plus the preceding 29 dates.
+	url.searchParams.set(
+		"startTime",
+		dayFloor(startedAt - (FIREWORKS_SPEND_WINDOW_DAYS - 1) * dayMs),
+	);
+	url.searchParams.set("endTime", dayFloor(startedAt + dayMs));
+	return url.toString();
+}
+
 function zaiMonitorUrl(baseUrl: string | undefined): string {
 	const base = baseUrl?.trim();
 	if (!base) throw new Error("Z.AI model base URL is unavailable.");

package/src/settings.ts

@@ -3,6 +3,7 @@ import { constants } from "node:fs";
 import { chmod, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isFireworksAccountId } from "./providers/fireworks.js";
 
 export const USAGE_SETTINGS_FILE = "pi-usage.json";
 export const MAX_USAGE_SETTINGS_BYTES = 64 * 1024;
@@ -10,6 +11,7 @@ export const MAX_USAGE_SETTINGS_BYTES = 64 * 1024;
 export interface UsageSettings {
 	codexFastMode: boolean;
 	codexStatusResetCountdown: boolean;
+	fireworksAccountId?: string;
 }
 
 export const DEFAULT_USAGE_SETTINGS: Readonly<UsageSettings> = Object.freeze({
@@ -60,6 +62,12 @@ export function normalizeUsageSettings(value: unknown): UsageSettings | undefine
 	) {
 		return undefined;
 	}
+	if (
+		Object.hasOwn(value, "fireworksAccountId") &&
+		!isFireworksAccountId(value.fireworksAccountId)
+	) {
+		return undefined;
+	}
 	return {
 		codexFastMode:
 			typeof value.codexFastMode === "boolean"
@@ -69,6 +77,9 @@ export function normalizeUsageSettings(value: unknown): UsageSettings | undefine
 			typeof value.codexStatusResetCountdown === "boolean"
 				? value.codexStatusResetCountdown
 				: DEFAULT_USAGE_SETTINGS.codexStatusResetCountdown,
+		...(isFireworksAccountId(value.fireworksAccountId)
+			? { fireworksAccountId: value.fireworksAccountId }
+			: {}),
 	};
 }
 
@@ -172,7 +183,11 @@ async function saveUsageSettingsPatch(
 	if (latest.kind === "invalid") {
 		throw new Error("Cannot overwrite an invalid pi-usage.json; repair it and reload first");
 	}
-	const document = { ...latest.document, ...patch };
+	const document = { ...latest.document };
+	for (const [key, value] of Object.entries(patch)) {
+		if (value === undefined) delete document[key];
+		else document[key] = value;
+	}
 	const settings = normalizeUsageSettings(document);
 	if (!settings) throw new Error("Refusing to save invalid pi-usage settings");
 	const directory = dirname(path);

package/src/types.ts

@@ -55,6 +55,10 @@ export interface ResolvedUsageAuth {
 	model: PiModel;
 }
 
+export interface UsageQuerySettings {
+	fireworksAccountId?: string;
+}
+
 export interface UsageProviderAdapter {
 	id: string;
 	displayName: string;
@@ -65,6 +69,7 @@ export interface UsageProviderAdapter {
 		signal: AbortSignal,
 		timeoutMs: number,
 		guard?: () => Promise<void>,
+		settings?: Readonly<UsageQuerySettings>,
 	): Promise<UsageReport>;
 }
 
@@ -89,6 +94,15 @@ export type DeepSeekBalancePayload = {
 	balance_infos?: unknown;
 };
 
+export type FireworksAccountsPayload = {
+	accounts?: unknown;
+	nextPageToken?: unknown;
+};
+
+export type FireworksBillingSummaryPayload = {
+	lineItems?: unknown;
+};
+
 export type GitHubCopilotUsagePayload = {
 	login?: unknown;
 	copilot_plan?: unknown;