@ychris12138/dsh-usage-stats 0.2.10 → 0.3.1

package/lib/balance.js

@@ -11,6 +11,8 @@
  * @module dsh-usage-stats/balance
  */
 
+import { balanceSchemeForProviderId } from "./provider-identity.js";
+
 const SCHEMES = {
 	/** DeepSeek: GET {origin}/user/balance — CNY balance_infos entry. */
 	deepseek: {
@@ -45,6 +47,28 @@ const SCHEMES = {
 			};
 		}
 	},
+	/** OrcaRouter: wallet balance with an OpenAI-compatible billing fallback. */
+	orcarouter: {
+		// OrcaRouter exposes these endpoints under the public /v1 prefix. Keep the
+		// configured origin/path so the normal pinned-network policy still applies
+		// and a provider profile never causes a cross-origin request.
+		balanceURL: (baseURL) => orcaBillingURL(baseURL, "/balance"),
+		subscriptionURL: (baseURL) => orcaBillingURL(baseURL, "/dashboard/billing/subscription"),
+		usageURL: (baseURL) => orcaBillingURL(baseURL, "/dashboard/billing/usage"),
+		query: async (baseURL, apiKey, timeoutMs, fetchImpl) => {
+			// Current deployments expose the wallet's paid/free/promo balance. Older
+			// deployments may not have it, so retain the documented OpenAI-shaped
+			// subscription + usage fallback for compatibility.
+			try {
+				return parseOrcaRouterWallet(await requestJSON(orcaBillingURL(baseURL, "/balance"), apiKey, timeoutMs, fetchImpl));
+			} catch (error) {
+				if (error?.providerStatus !== "unsupported") throw error;
+			}
+			const subscription = await requestJSON(orcaBillingURL(baseURL, "/dashboard/billing/subscription"), apiKey, timeoutMs, fetchImpl);
+			const usage = await requestJSON(orcaBillingURL(baseURL, "/dashboard/billing/usage"), apiKey, timeoutMs, fetchImpl);
+			return parseOrcaRouter(subscription, usage);
+		}
+	},
 	/** Moonshot / Kimi: GET {origin}/v1/users/me/balance — available/cash/voucher. */
 	moonshot: {
 		url: (baseURL) => new URL("/v1/users/me/balance", baseURL).href,
@@ -80,6 +104,74 @@ const SCHEMES = {
 	}
 };
 
+function orcaBillingURL(baseURL, path) {
+	const base = new URL(baseURL);
+	const pathname = base.pathname.replace(/\/+$/, "");
+	const prefix = pathname === "" ? "/v1" : pathname.endsWith("/v1") ? pathname : `${pathname}/v1`;
+	return new URL(`${prefix}${path}`, base.origin).href;
+}
+
+function parseOrcaRouter(subscription, usage) {
+	const total = numberOrNull(subscription?.hard_limit_usd ?? subscription?.soft_limit_usd);
+	// OpenAI-compatible dashboard usage is reported in cents. Keep the unit
+	// conversion in this adapter so `remaining`, `used`, and `limit` share one
+	// consistent currency basis.
+	const usageCents = numberOrNull(usage?.total_usage);
+	if (total === null || usageCents === null || total < 0 || usageCents < 0) {
+		throw providerError("invalid-response", "OrcaRouter billing response is missing numeric quota data");
+	}
+	const used = usageCents / 100;
+	const unlimited = total === 100000000
+		&& numberOrNull(subscription?.soft_limit_usd) === total
+		&& numberOrNull(subscription?.system_hard_limit_usd) === total;
+	return {
+		isAvailable: unlimited || total - used > 0,
+		currency: "USD",
+		total: unlimited ? total : total - used,
+		used,
+		limit: unlimited ? void 0 : total,
+		unlimited,
+		granted: void 0,
+		toppedUp: void 0
+	};
+}
+
+function creditArrayTotal(value, currency, label) {
+	if (value === void 0 || value === null) return 0;
+	if (!Array.isArray(value)) throw providerError("invalid-response", `OrcaRouter ${label} credits are invalid`);
+	let total = 0;
+	for (const entry of value) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw providerError("invalid-response", `OrcaRouter ${label} credits are invalid`);
+		const entryCurrency = typeof entry.unit === "string" && entry.unit.trim() !== "" ? entry.unit.trim().toUpperCase() : currency;
+		if (entryCurrency !== currency) throw providerError("invalid-response", `OrcaRouter ${label} credits use a different currency`);
+		const amount = numberOrNull(entry.balance_usd ?? entry.balance);
+		if (amount === null || amount < 0) throw providerError("invalid-response", `OrcaRouter ${label} credits are missing a numeric balance`);
+		total += amount;
+	}
+	return total;
+}
+
+function parseOrcaRouterWallet(body) {
+	if (body === null || typeof body !== "object" || Array.isArray(body)) throw providerError("invalid-response", "OrcaRouter wallet response is invalid");
+	const currency = typeof body.unit === "string" && body.unit.trim() !== "" ? body.unit.trim().toUpperCase() : null;
+	if (currency === null) throw providerError("invalid-response", "OrcaRouter wallet response is missing currency");
+	const paid = numberOrNull(body.paid_balance);
+	if (paid === null || paid < 0) throw providerError("invalid-response", "OrcaRouter wallet response is missing paid balance");
+	const remaining = paid
+		+ creditArrayTotal(body.free_credit, currency, "free")
+		+ creditArrayTotal(body.promo_credits, currency, "promo");
+	return {
+		isAvailable: remaining > 0,
+		currency,
+		total: remaining,
+		used: void 0,
+		limit: void 0,
+		unlimited: false,
+		granted: void 0,
+		toppedUp: void 0
+	};
+}
+
 function providerError(status, message, httpStatus) {
 	const error = new Error(message);
 	error.providerStatus = status;
@@ -90,34 +182,43 @@ function providerError(status, message, httpStatus) {
 function responseStatus(status) {
 	if (status === 401 || status === 403) return "unauthorized";
 	if (status === 429) return "rate-limited";
+	if (status === 404 || status === 405) return "unsupported";
 	return status >= 500 ? "unavailable" : "invalid-response";
 }
 
-/** Map a provider id (dsh adapter id or pi-ai route) to a balance scheme id. */
-export function balanceSchemeOf(providerId) {
-	if (providerId === "deepseek-official" || providerId === "deepseek") return "deepseek";
-	if (providerId === "openrouter") return "openrouter";
-	if (providerId === "moonshotai" || providerId === "moonshotai-cn" || providerId === "kimi" || providerId === "kimi-coding") return "moonshot";
-	if (providerId === "zai" || providerId === "zai-coding-cn") return "zai";
+function numberOrNull(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
 	return null;
 }
 
-/** Query one provider's balance. Throws on transport/HTTP errors. */
-export async function queryBalance(scheme, baseURL, apiKey, timeoutMs = 15000, fetchImpl = fetch) {
-	const spec = SCHEMES[scheme];
-	if (spec === void 0) throw new Error(`no balance scheme "${scheme}"`);
-	const response = await fetchImpl(spec.url(baseURL), {
-		headers: { authorization: `Bearer ${apiKey}` },
+async function requestJSON(url, apiKey, timeoutMs, fetchImpl) {
+	const response = await fetchImpl(url, {
+		headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" },
 		signal: AbortSignal.timeout(timeoutMs)
 	});
 	if (!response.ok) throw providerError(responseStatus(response.status), `balance API returned HTTP ${response.status}`, response.status);
-	let body;
 	try {
-		body = await response.json();
+		return await response.json();
 	} catch {
 		throw providerError("invalid-response", "balance API returned invalid JSON");
 	}
-	return spec.parse(body);
+}
+
+/** Map a provider id (dsh adapter id or pi-ai route) to a balance scheme id. */
+export function balanceSchemeOf(providerId) {
+	return balanceSchemeForProviderId(providerId);
+}
+
+/** Query one provider's balance. Throws on transport/HTTP errors. */
+export async function queryBalance(scheme, baseURL, apiKey, timeoutMs = 15000, fetchImpl = fetch) {
+	const spec = SCHEMES[scheme];
+	if (spec === void 0) throw new Error(`no balance scheme "${scheme}"`);
+	if (typeof spec.query === "function") return spec.query(baseURL, apiKey, timeoutMs, fetchImpl);
+	return spec.parse(await requestJSON(spec.url(baseURL), apiKey, timeoutMs, fetchImpl));
 }
 
 /** Scheme ids with built-in support (for docs/tests). */

package/lib/billing.js

@@ -0,0 +1,319 @@
+/**
+ * Pure billing derivation over provider-reported usage samples.
+ *
+ * Token accounting remains owned by usage.js/DSH. This module only carries
+ * monetary contributions produced by pricing.js, their provenance, and
+ * fail-closed budget state.
+ *
+ * @module dsh-usage-stats/billing
+ */
+
+import { estimateTokenCost, PRICING_RULES } from "./pricing.js";
+import { PROVIDER_IDENTITY_POLICY_VERSION, resolveProviderIdentity } from "./provider-identity.js";
+
+const ISO_CURRENCY = /^[A-Z]{3}$/;
+
+export const DEFAULT_BUDGET_CONFIG = Object.freeze({
+	currency: "USD",
+	daily: null,
+	monthly: null
+});
+
+function optionalLimit(value, label) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+		throw new Error(`${label} must be a positive finite number or null`);
+	}
+	return value;
+}
+
+/** Validate the public, secret-free daily/monthly budget configuration. */
+export function validateBudgetConfig(raw = {}) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("budgets must be an object");
+	const currency = raw.currency ?? DEFAULT_BUDGET_CONFIG.currency;
+	if (typeof currency !== "string" || !ISO_CURRENCY.test(currency)) throw new Error("budgets.currency must be an uppercase three-letter currency code");
+	return {
+		currency,
+		daily: optionalLimit(raw.daily, "budgets.daily"),
+		monthly: optionalLimit(raw.monthly, "budgets.monthly")
+	};
+}
+
+function safeBaseURLState(baseURL) {
+	if (typeof baseURL !== "string" || baseURL.trim() === "") return { state: "absent" };
+	try {
+		const hostname = new URL(baseURL).hostname.toLowerCase().replace(/\.$/, "");
+		return hostname === "" ? { state: "malformed" } : { state: "hostname", hostname };
+	} catch {
+		return { state: "malformed" };
+	}
+}
+
+function compareProjection(left, right) {
+	const a = JSON.stringify(left);
+	const b = JSON.stringify(right);
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Secret-free provider facts that can change pricing eligibility. */
+export function providerPricingIdentityProjection(providers = [], config = { monitors: {} }) {
+	return (Array.isArray(providers) ? providers : []).map((provider) => {
+		const identity = resolveProviderIdentity(provider, config);
+		return {
+			routeId: identity.routeId,
+			providerFamily: identity.providerFamily,
+			pricingFamily: identity.pricingFamily,
+			confidence: identity.confidence,
+			baseURL: safeBaseURLState(identity.baseURL)
+		};
+	}).sort(compareProjection);
+}
+
+/** Exact pricing catalog + runtime provider-identity fingerprint for cached costs. */
+export function pricingFingerprint({ providers = [], config = { monitors: {} }, rules = PRICING_RULES } = {}) {
+	return JSON.stringify({
+		schemaVersion: 1,
+		providerIdentityPolicy: PROVIDER_IDENTITY_POLICY_VERSION,
+		providerPricingIdentities: providerPricingIdentityProjection(providers, config),
+		pricingCatalog: rules
+	});
+}
+
+function providerProjectionByRoute(fingerprint) {
+	try {
+		const parsed = JSON.parse(fingerprint);
+		if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.providerPricingIdentities)) return null;
+		const byRoute = new Map();
+		for (const projection of parsed.providerPricingIdentities) {
+			if (projection === null || typeof projection !== "object" || typeof projection.routeId !== "string") return null;
+			const entries = byRoute.get(projection.routeId) ?? [];
+			entries.push(projection);
+			byRoute.set(projection.routeId, entries);
+		}
+		for (const entries of byRoute.values()) entries.sort(compareProjection);
+		return byRoute;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Changed route ids, or null when an old fingerprint cannot prove its provider
+ * identity. Callers must treat null as a global fail-closed transition.
+ */
+export function changedProviderPricingRoutes(previousFingerprint, nextFingerprint) {
+	const previous = providerProjectionByRoute(previousFingerprint);
+	const next = providerProjectionByRoute(nextFingerprint);
+	if (previous === null || next === null) return null;
+	const routeIds = new Set([...previous.keys(), ...next.keys()]);
+	return [...routeIds].filter((routeId) => (
+		JSON.stringify(previous.get(routeId) ?? []) !== JSON.stringify(next.get(routeId) ?? [])
+	)).sort();
+}
+
+/** Empty additive monetary accumulator. */
+export function createCostAccumulator() {
+	return {
+		pricedSamples: 0,
+		incompleteSamples: 0,
+		currencies: new Map(),
+		rules: new Map()
+	};
+}
+
+function tokenCount(buckets) {
+	if (buckets === null || typeof buckets !== "object") return 0;
+	return ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]
+		.reduce((sum, key) => sum + (typeof buckets[key] === "number" && Number.isFinite(buckets[key]) && buckets[key] > 0 ? buckets[key] : 0), 0);
+}
+
+function safeSource(source) {
+	if (source === null || typeof source !== "object" || Array.isArray(source)) return null;
+	const kind = typeof source.kind === "string" ? source.kind : null;
+	const provider = typeof source.provider === "string" ? source.provider : null;
+	const url = typeof source.url === "string" ? source.url : null;
+	return kind === null || provider === null || url === null ? null : { kind, provider, url };
+}
+
+/**
+ * Convert one pricing result into an additive contribution. Positive token
+ * usage with no trustworthy estimate is explicitly incomplete.
+ */
+export function costSampleOf(estimate, buckets) {
+	if (tokenCount(buckets) === 0) return { counted: false };
+	if (estimate === null || typeof estimate !== "object"
+		|| typeof estimate.amount !== "number" || !Number.isFinite(estimate.amount) || estimate.amount < 0
+		|| typeof estimate.currency !== "string" || !ISO_CURRENCY.test(estimate.currency)) {
+		return { counted: true, complete: false };
+	}
+	return {
+		counted: true,
+		complete: true,
+		amount: estimate.amount,
+		currency: estimate.currency,
+		ruleId: typeof estimate.ruleId === "string" && estimate.ruleId !== "" ? estimate.ruleId : null,
+		source: safeSource(estimate.source),
+		updatedAt: typeof estimate.updatedAt === "string" ? estimate.updatedAt : null
+	};
+}
+
+function adjustCount(map, key, amount, countDelta) {
+	const previous = map.get(key) ?? { amount: 0, count: 0 };
+	const next = { amount: previous.amount + amount, count: previous.count + countDelta };
+	if (next.count <= 0) map.delete(key);
+	else map.set(key, next);
+}
+
+/** Add (`direction=1`) or subtract (`direction=-1`) one cost contribution. */
+export function applyCostSample(target, sample, direction = 1) {
+	if (sample?.counted !== true) return target;
+	if (direction !== 1 && direction !== -1) throw new Error("cost sample direction must be 1 or -1");
+	if (sample.complete !== true) {
+		target.incompleteSamples = Math.max(0, target.incompleteSamples + direction);
+		return target;
+	}
+	target.pricedSamples = Math.max(0, target.pricedSamples + direction);
+	adjustCount(target.currencies, sample.currency, direction * sample.amount, direction);
+	if (sample.ruleId !== null) {
+		const previous = target.rules.get(sample.ruleId) ?? { count: 0, source: sample.source, updatedAt: sample.updatedAt };
+		const count = previous.count + direction;
+		if (count <= 0) target.rules.delete(sample.ruleId);
+		else target.rules.set(sample.ruleId, {
+			count,
+			source: previous.source ?? sample.source,
+			updatedAt: previous.updatedAt ?? sample.updatedAt
+		});
+	}
+	return target;
+}
+
+/** Merge one complete accumulator into another. */
+export function mergeCostAccumulator(target, source) {
+	target.pricedSamples += source.pricedSamples;
+	target.incompleteSamples += source.incompleteSamples;
+	for (const [currency, entry] of source.currencies) adjustCount(target.currencies, currency, entry.amount, entry.count);
+	for (const [ruleId, entry] of source.rules) {
+		const previous = target.rules.get(ruleId);
+		target.rules.set(ruleId, previous === void 0 ? { ...entry } : {
+			count: previous.count + entry.count,
+			source: previous.source ?? entry.source,
+			updatedAt: previous.updatedAt ?? entry.updatedAt
+		});
+	}
+	return target;
+}
+
+function provenanceOf(accumulator) {
+	const entries = [...accumulator.rules.entries()].filter(([, entry]) => entry.count > 0).sort(([a], [b]) => a.localeCompare(b));
+	const sources = new Map();
+	let updatedAt = null;
+	for (const [, entry] of entries) {
+		if (entry.source !== null) sources.set(JSON.stringify(entry.source), entry.source);
+		if (typeof entry.updatedAt === "string" && (updatedAt === null || entry.updatedAt > updatedAt)) updatedAt = entry.updatedAt;
+	}
+	return {
+		ruleIds: entries.map(([ruleId]) => ruleId),
+		source: sources.size === 1 ? [...sources.values()][0] : null,
+		updatedAt
+	};
+}
+
+/** Render an accumulator; any unpriced sample or mixed currency fails closed. */
+export function renderCost(accumulator) {
+	const sampleCount = accumulator.pricedSamples + accumulator.incompleteSamples;
+	const complete = sampleCount > 0 && accumulator.incompleteSamples === 0 && accumulator.currencies.size === 1;
+	const [currency, currencyEntry] = complete ? [...accumulator.currencies.entries()][0] : [null, null];
+	return {
+		estimatedCost: complete ? currencyEntry.amount : null,
+		currency,
+		costComplete: complete,
+		pricing: provenanceOf(accumulator)
+	};
+}
+
+/** JSON-safe cost accumulator for the incremental cache. */
+export function serializeCostAccumulator(accumulator) {
+	return {
+		pricedSamples: accumulator.pricedSamples,
+		incompleteSamples: accumulator.incompleteSamples,
+		currencies: Object.fromEntries([...accumulator.currencies].map(([currency, entry]) => [currency, { ...entry }])),
+		rules: Object.fromEntries([...accumulator.rules].map(([ruleId, entry]) => [ruleId, { ...entry }]))
+	};
+}
+
+/** Lenient cache restore; invalid fields degrade to an empty/incomplete-safe state. */
+export function parseCostAccumulator(raw) {
+	const accumulator = createCostAccumulator();
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return accumulator;
+	accumulator.pricedSamples = Number.isSafeInteger(raw.pricedSamples) && raw.pricedSamples >= 0 ? raw.pricedSamples : 0;
+	accumulator.incompleteSamples = Number.isSafeInteger(raw.incompleteSamples) && raw.incompleteSamples >= 0 ? raw.incompleteSamples : 0;
+	for (const [currency, entry] of Object.entries(raw.currencies ?? {})) {
+		if (!ISO_CURRENCY.test(currency) || entry === null || typeof entry !== "object"
+			|| typeof entry.amount !== "number" || !Number.isFinite(entry.amount)
+			|| !Number.isSafeInteger(entry.count) || entry.count <= 0) continue;
+		accumulator.currencies.set(currency, { amount: entry.amount, count: entry.count });
+	}
+	for (const [ruleId, entry] of Object.entries(raw.rules ?? {})) {
+		if (ruleId === "" || entry === null || typeof entry !== "object" || !Number.isSafeInteger(entry.count) || entry.count <= 0) continue;
+		accumulator.rules.set(ruleId, {
+			count: entry.count,
+			source: safeSource(entry.source),
+			updatedAt: typeof entry.updatedAt === "string" ? entry.updatedAt : null
+		});
+	}
+	return accumulator;
+}
+
+/** Build the only provider-aware bridge from session route identity to pricing.js. */
+export function createUsageCostEstimator(providers, config = { monitors: {} }, currency = "USD", rules = PRICING_RULES) {
+	const byId = new Map((Array.isArray(providers) ? providers : []).map((provider) => [provider.id, provider]));
+	return ({ providerId, model, timestamp, buckets }) => {
+		const provider = byId.get(providerId) ?? { id: providerId, displayName: providerId };
+		const identity = resolveProviderIdentity(provider, config);
+		return estimateTokenCost({ identity, model, timestamp, currency, buckets }, rules);
+	};
+}
+
+/** Budget threshold policy: 80% warns, 100% is critical. */
+export function budgetLevel(percent) {
+	if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0) return "unknown";
+	if (percent >= 100) return "critical";
+	if (percent >= 80) return "warning";
+	return "normal";
+}
+
+function budgetWindow(limit, currency, accumulator) {
+	const sampleCount = accumulator.pricedSamples + accumulator.incompleteSamples;
+	const rendered = renderCost(accumulator);
+	const knownEmpty = sampleCount === 0;
+	const compatible = knownEmpty || rendered.costComplete && rendered.currency === currency;
+	const estimatedSpend = compatible ? (knownEmpty ? 0 : rendered.estimatedCost) : null;
+	const percent = limit === null || estimatedSpend === null ? null : estimatedSpend / limit * 100;
+	return {
+		limit,
+		currency,
+		estimatedSpend,
+		percent,
+		costComplete: compatible,
+		level: limit === null ? "disabled" : budgetLevel(percent)
+	};
+}
+
+function localDayKey(timeMs) {
+	const date = new Date(timeMs);
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+
+/** Render current local-day and local-month budget state from day costs. */
+export function renderBudgetSummary(dayCosts, config = DEFAULT_BUDGET_CONFIG, now = Date.now()) {
+	const day = localDayKey(now);
+	const month = day.slice(0, 7);
+	const daily = dayCosts.get(day)?.total ?? createCostAccumulator();
+	const monthly = createCostAccumulator();
+	for (const [date, entry] of dayCosts) if (date.startsWith(month)) mergeCostAccumulator(monthly, entry.total);
+	return {
+		currency: config.currency,
+		daily: budgetWindow(config.daily, config.currency, daily),
+		monthly: budgetWindow(config.monthly, config.currency, monthly)
+	};
+}