@rayadesu/dsh-billing 0.1.0-rc.8

package/packages/llm-billing/lib/index.js

@@ -0,0 +1,562 @@
+import z from "@deepseek-ai/schemastery";
+import { LlmError, assertUsableApiKey } from "@deepseek-ai/dsh-llm";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+//#region lib/types/balance.js
+/**
+* DeepSeek account-balance capability: the `GET /user/balance` transport and
+* the Remote gateway that exposes one snapshot to trusted clients. The fetch
+* takes an already-resolved endpoint and bearer token so the registering
+* plugin stays the one owner of credential policy; the gateway carries only a
+* `fetchBalance` thunk for the same reason.
+* @module @rayadesu/dsh-llm-billing/balance
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Map a balance HTTP status to a stable LlmError code. */
+function httpErrorCode(status) {
+	if (status === 401 || status === 403) return "AUTH";
+	if (status === 429) return "RATE_LIMIT";
+	if (status >= 500) return "SERVER";
+	return `HTTP_${status}`;
+}
+/**
+* Parse and validate the DeepSeek balance response at the wire boundary.
+* @param body - decoded JSON response body.
+* @returns the validated, detached balance snapshot.
+* @throws {@link LlmError} with code `TRANSPORT` when the body is malformed.
+*/
+function parseDeepSeekBalance(body) {
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw new LlmError("DeepSeek balance response was not a JSON object", "TRANSPORT");
+	const response = body;
+	const isAvailable = response["is_available"];
+	const infos = response["balance_infos"];
+	if (typeof isAvailable !== "boolean" || !Array.isArray(infos)) throw new LlmError("DeepSeek balance response is missing is_available or balance_infos", "TRANSPORT");
+	return {
+		isAvailable,
+		lines: infos.map((info, index) => {
+			if (typeof info !== "object" || info === null || Array.isArray(info)) throw new LlmError(`DeepSeek balance line ${index} is malformed`, "TRANSPORT");
+			const line = info;
+			const currency = line["currency"];
+			const total = line["total_balance"];
+			const granted = line["granted_balance"];
+			const toppedUp = line["topped_up_balance"];
+			if (typeof currency !== "string" || currency.length === 0 || typeof total !== "string" || typeof granted !== "string" || typeof toppedUp !== "string") throw new LlmError(`DeepSeek balance line ${index} has missing or invalid fields`, "TRANSPORT");
+			return {
+				currency,
+				total,
+				granted,
+				toppedUp
+			};
+		})
+	};
+}
+/**
+* Fetch one account-balance snapshot from `{baseURL}/user/balance`.
+* @param baseURL - resolved endpoint base; `/user/balance` is appended.
+* @param apiKey - resolved bearer token for this endpoint.
+* @param signal - optional cancellation.
+* @returns the validated balance snapshot.
+* @throws {@link LlmError} for transport, HTTP, or malformed-response failures.
+*/
+async function fetchDeepSeekBalance(baseURL, apiKey, signal) {
+	let response;
+	try {
+		response = await fetch(`${baseURL}/user/balance`, {
+			method: "GET",
+			headers: {
+				"authorization": `Bearer ${apiKey}`,
+				"accept": "application/json"
+			},
+			...signal === void 0 ? {} : { signal }
+		});
+	} catch (error) {
+		if (signal?.aborted) throw new LlmError("DeepSeek balance request aborted by caller", "ABORTED", { cause: error });
+		throw new LlmError(`DeepSeek balance request to ${baseURL} failed`, "TRANSPORT", { cause: error });
+	}
+	if (!response.ok) throw new LlmError(`DeepSeek balance request failed (HTTP ${response.status})`, httpErrorCode(response.status), { status: response.status });
+	let body;
+	try {
+		body = await response.json();
+	} catch (error) {
+		throw new LlmError("DeepSeek balance response was not valid JSON", "TRANSPORT", { cause: error });
+	}
+	return parseDeepSeekBalance(body);
+}
+/**
+* Remote-only service exposing the DeepSeek account balance and session spend.
+* The plugin that owns connection, credential, and session-history resolution
+* constructs it with the matching thunks, so the Remote boundary never sees an
+* endpoint, key, or the session store.
+*/
+let DeepSeekBalanceGateway = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _getBalance_decorators;
+	let _getSessionSpend_decorators;
+	let _getTodaySpend_decorators;
+	return class DeepSeekBalanceGateway extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_getBalance_decorators = [Remote("getBalance")];
+			_getSessionSpend_decorators = [Remote("getSessionSpend")];
+			_getTodaySpend_decorators = [Remote("getTodaySpend")];
+			__esDecorate(this, null, _getBalance_decorators, {
+				kind: "method",
+				name: "getBalance",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "getBalance" in obj,
+					get: (obj) => obj.getBalance
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _getSessionSpend_decorators, {
+				kind: "method",
+				name: "getSessionSpend",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "getSessionSpend" in obj,
+					get: (obj) => obj.getSessionSpend
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _getTodaySpend_decorators, {
+				kind: "method",
+				name: "getTodaySpend",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "getTodaySpend" in obj,
+					get: (obj) => obj.getTodaySpend
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		options = __runInitializers(this, _instanceExtraInitializers);
+		/**
+		* Register the balance Remote under the `billing` namespace.
+		* @param ctx - owning plugin context.
+		* @param options - balance and spend thunks bound to the plugin's facts.
+		*/
+		constructor(ctx, options) {
+			super(ctx, "billing");
+			this.options = options;
+		}
+		/**
+		* Read the current DeepSeek account balance.
+		* @returns the validated balance snapshot.
+		*/
+		getBalance() {
+			return this.options.fetchBalance();
+		}
+		/**
+		* Read one session's billed spend, priced per event by its peak/off-peak hour.
+		* @param sessionId - the session whose spend to compute.
+		* @returns the session's total cost plus one row per priced model.
+		*/
+		getSessionSpend(sessionId) {
+			return this.options.fetchSessionSpend(sessionId);
+		}
+		/**
+		* Read today's billed spend across every session, priced per event by its
+		* Beijing-time calendar day and peak/off-peak hour.
+		* @returns today's total cost plus one row per priced model.
+		*/
+		getTodaySpend() {
+			return this.options.fetchTodaySpend();
+		}
+	};
+})();
+//#endregion
+//#region lib/types/billing.js
+/**
+* DeepSeek billing: the peak/off-peak pricing table and the per-session spend
+* pricing. Pure functions over session events and the pricing table, so the
+* Remote gateway stays transport-free and the whole spend is testable without
+* a key.
+* @module @rayadesu/dsh-llm-billing/billing
+*/
+/** Published peak-hour windows (Beijing time): 09:00–12:00 and 14:00–18:00. */
+const DEFAULT_PEAK_HOURS = [{
+	start: 9,
+	end: 12
+}, {
+	start: 14,
+	end: 18
+}];
+/** Official peak/off-peak rates (CNY per 1M tokens), effective 2026-08-17. */
+const DEFAULT_MODEL_PRICING = [
+	{
+		model: "deepseek-v4-flash",
+		peak: {
+			cacheHitInput: .1,
+			cacheMissInput: 3,
+			output: 9
+		},
+		offPeak: {
+			cacheHitInput: .05,
+			cacheMissInput: 1.5,
+			output: 4.5
+		}
+	},
+	{
+		model: "deepseek-v4-pro",
+		peak: {
+			cacheHitInput: .3,
+			cacheMissInput: 9,
+			output: 27
+		},
+		offPeak: {
+			cacheHitInput: .15,
+			cacheMissInput: 4.5,
+			output: 13.5
+		}
+	},
+	{
+		model: "deepseek-v4-flash-vision-exp",
+		peak: {
+			cacheHitInput: .1,
+			cacheMissInput: 3,
+			output: 9
+		},
+		offPeak: {
+			cacheHitInput: .05,
+			cacheMissInput: 1.5,
+			output: 4.5
+		}
+	}
+];
+/**
+* Resolve optional configuration to a pricing table, defaulting omitted or
+* empty rows to the published rates. Schemastery materializes an absent
+* `z.array` as `[]` rather than `undefined`, so emptiness — not just absence —
+* selects the defaults. Explicit non-empty rows override the same model; a
+* supplied non-empty `models` list is authoritative.
+* @param config - optional raw billing configuration.
+* @returns the resolved table and peak-hour windows.
+*/
+function resolveBilling(config) {
+	const peakHours = config?.peakHours !== void 0 && config.peakHours.length > 0 ? config.peakHours : DEFAULT_PEAK_HOURS;
+	const rows = config?.models !== void 0 && config.models.length > 0 ? config.models : DEFAULT_MODEL_PRICING;
+	const models = /* @__PURE__ */ new Map();
+	for (const row of rows) models.set(row.model, {
+		peak: row.peak,
+		offPeak: row.offPeak
+	});
+	return {
+		peakHours,
+		models
+	};
+}
+/** The Beijing (Asia/Shanghai, UTC+8, no DST) hour of a timestamp. */
+function beijingHour(now) {
+	return new Date(now.getTime() + 8 * 36e5).getUTCHours();
+}
+/** The Beijing (Asia/Shanghai, UTC+8, no DST) calendar-day key of a timestamp. */
+function beijingDayKey(now) {
+	return new Date(now.getTime() + 8 * 36e5).toISOString().slice(0, 10);
+}
+/**
+* Whether a timestamp falls inside any peak-hour window (Beijing time).
+* @param billing - resolved pricing with peak-hour windows.
+* @param now - the moment to classify.
+* @returns true during peak hours.
+*/
+function isPeak(billing, now) {
+	const hour = beijingHour(now);
+	return billing.peakHours.some(({ start, end }) => hour >= start && hour < end);
+}
+/**
+* Price a set of billed events at the official per-model rates, applying the
+* peak/off-peak table per event by its Beijing-time hour. Each
+* `assistant/message` event with usage contributes cache-hit input, cache-miss
+* input (uncached input plus cache writes), and output (reasoning included)
+* tokens at the rate of its own timestamp, with the three component costs
+* carried separately; a model with usage but no pricing row is omitted (the
+* published table prices only the two V4 rows).
+* @param events - the events to price.
+* @param billing - resolved pricing with peak-hour windows.
+* @param catalog - model display rows, in presentation order.
+* @returns the total cost plus one row per priced model.
+*/
+function priceEvents(events, billing, catalog) {
+	const names = new Map(catalog.map((model) => [model.id, model.name]));
+	const rows = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.type !== "assistant/message") continue;
+		const reported = event.data.usage;
+		if (reported === void 0) continue;
+		const model = event.data.message.source.model;
+		const pricing = billing.models.get(model);
+		if (pricing === void 0) continue;
+		const peak = isPeak(billing, new Date(event.time));
+		const price = peak ? pricing.peak : pricing.offPeak;
+		const hit = reported.cacheReadTokens ?? 0;
+		const miss = reported.inputTokens + (reported.cacheWriteTokens ?? 0);
+		const output = reported.outputTokens;
+		const hitCost = hit * price.cacheHitInput / 1e6;
+		const missCost = miss * price.cacheMissInput / 1e6;
+		const outputCost = output * price.output / 1e6;
+		const cost = hitCost + missCost + outputCost;
+		let row = rows.get(model);
+		if (row === void 0) {
+			row = {
+				cacheHitInputTokens: 0,
+				cacheMissInputTokens: 0,
+				outputTokens: 0,
+				cost: 0,
+				peakCost: 0,
+				offPeakCost: 0,
+				cacheHitInputCost: 0,
+				cacheMissInputCost: 0,
+				outputCost: 0
+			};
+			rows.set(model, row);
+		}
+		row.cacheHitInputTokens += hit;
+		row.cacheMissInputTokens += miss;
+		row.outputTokens += output;
+		row.cost += cost;
+		row.cacheHitInputCost += hitCost;
+		row.cacheMissInputCost += missCost;
+		row.outputCost += outputCost;
+		if (peak) row.peakCost += cost;
+		else row.offPeakCost += cost;
+	}
+	const models = [...rows.entries()].map(([model, row]) => ({
+		model,
+		displayName: names.get(model) ?? model,
+		cost: row.cost,
+		peakCost: row.peakCost,
+		offPeakCost: row.offPeakCost,
+		cacheHitInputTokens: row.cacheHitInputTokens,
+		cacheMissInputTokens: row.cacheMissInputTokens,
+		outputTokens: row.outputTokens,
+		cacheHitInputCost: row.cacheHitInputCost,
+		cacheMissInputCost: row.cacheMissInputCost,
+		outputCost: row.outputCost
+	}));
+	return {
+		total: models.reduce((sum, model) => sum + model.cost, 0),
+		models
+	};
+}
+/**
+* Price one session's complete event log at the official per-model rates.
+* @param events - one session's complete event log.
+* @param billing - resolved pricing with peak-hour windows.
+* @param catalog - model display rows, in presentation order.
+* @returns the session's total cost plus one row per priced model.
+*/
+function computeSessionSpend(events, billing, catalog) {
+	return priceEvents(events, billing, catalog);
+}
+/**
+* Price every event whose Beijing-time calendar day is the day of `now`,
+* aggregating across every session's event log. Events from other Beijing
+* days are ignored, so a caller passes the concatenated logs of all sessions.
+* @param events - every session's complete event log, concatenated.
+* @param billing - resolved pricing with peak-hour windows.
+* @param catalog - model display rows, in presentation order.
+* @param now - the reference moment whose Beijing-time calendar day is "today".
+* @returns today's total cost plus one row per priced model.
+*/
+function computeTodaySpend(events, billing, catalog, now = /* @__PURE__ */ new Date()) {
+	const day = beijingDayKey(now);
+	return priceEvents(events.filter((event) => beijingDayKey(new Date(event.time)) === day), billing, catalog);
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* DeepSeek account balance and session-spend provider, as a standalone host
+* plugin. It resolves the DeepSeek endpoint and API key from its own config and
+* the credential/environment seams, prices each session's billed usage with the
+* peak/off-peak table, and exposes the `billing` Remote (`getBalance`, the
+* per-session `getSessionSpend`, and the all-sessions `getTodaySpend`).
+* @module @rayadesu/dsh-llm-billing
+*/
+const name = "llm-billing";
+const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
+/** Public API default; deployments may point elsewhere via $DEEPSEEK_BASE_URL. */
+const PUBLIC_BASE_URL = "https://api.deepseek.com";
+const DEFAULT_MODELS = [
+	{
+		id: "deepseek-v4-flash",
+		name: "DeepSeek-V4-Flash"
+	},
+	{
+		id: "deepseek-v4-pro",
+		name: "DeepSeek-V4-Pro"
+	},
+	{
+		id: "deepseek-v4-flash-vision-exp",
+		name: "DeepSeek-V4-Flash-Vision-Exp"
+	}
+];
+const billingModel = z.object({
+	id: z.string().required(),
+	name: z.string()
+});
+const tokenPrice = z.object({
+	cacheHitInput: z.number().min(0),
+	cacheMissInput: z.number().min(0),
+	output: z.number().min(0)
+});
+const billingConfig = z.object({
+	peakHours: z.array(z.object({
+		start: z.number().step(1).min(0).max(23),
+		end: z.number().step(1).min(0).max(24)
+	})).default(DEFAULT_PEAK_HOURS),
+	models: z.array(z.object({
+		model: z.string().required(),
+		peak: tokenPrice,
+		offPeak: tokenPrice
+	})).default(DEFAULT_MODEL_PRICING)
+});
+const Config = z.object({
+	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+	baseURL: z.string(),
+	models: z.array(billingModel).default(DEFAULT_MODELS),
+	billing: billingConfig
+});
+/**
+* Read one session's event log: the live SessionStore first, then the
+* persistence backend for a flushed session.
+* @param ctx - plugin context carrying the SessionStore and optional persistence.
+* @param sessionId - the session to read.
+* @returns the session's complete event log.
+* @throws {@link LlmError} with code `NOT_FOUND` when the session is unknown.
+*/
+async function sessionEvents(ctx, sessionId) {
+	const live = ctx.get("sessions")?.get(sessionId);
+	if (live !== void 0) return live.events;
+	const persistence = ctx.get("sessionPersistence");
+	if (persistence !== void 0) for (const header of await persistence.list()) {
+		if (header.id !== sessionId) continue;
+		return (await persistence.inspect(sessionId)).events;
+	}
+	throw new LlmError(`llm-billing: session ${sessionId} not found`, "NOT_FOUND");
+}
+/**
+* Read every session's event log, concatenated: each live SessionStore
+* session first (its log may hold events not yet flushed), then each persisted
+* session that is not live, so no event is counted twice. Events are appended
+* one at a time: spreading a very large log into `push(...)` exceeds the
+* engine's argument limit and throws a stack RangeError.
+* @param ctx - plugin context carrying the SessionStore and optional persistence.
+* @returns every session's complete event log, concatenated.
+*/
+async function allSessionEvents(ctx) {
+	const events = [];
+	const sessions = ctx.get("sessions");
+	const liveIds = /* @__PURE__ */ new Set();
+	if (sessions !== void 0) for (const session of sessions.list()) {
+		liveIds.add(session.id);
+		for (const event of session.events) events.push(event);
+	}
+	const persistence = ctx.get("sessionPersistence");
+	if (persistence !== void 0) for (const header of await persistence.list()) {
+		if (liveIds.has(header.id)) continue;
+		try {
+			const inspection = await persistence.inspect(header.id);
+			for (const event of inspection.events) events.push(event);
+		} catch (error) {
+			ctx.logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
+		}
+	}
+	return events;
+}
+/**
+* Register the `billing` Remote under the `billing` namespace.
+* @param ctx - owning plugin context.
+* @param config - validated plugin config.
+*/
+function apply(ctx, config) {
+	const baseURL = () => config.baseURL ?? launchEnvironmentOf(ctx).get(BASE_URL_ENV)?.value ?? "https://api.deepseek.com";
+	const apiKeyRef = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+	const resolveApiKey = async () => {
+		const credentials = ctx.get("credentials");
+		if (credentials !== void 0) {
+			const hit = await credentials.resolve(apiKeyRef);
+			if (hit !== void 0) return assertUsableApiKey(hit.value, "llm-billing", apiKeyRef);
+		} else {
+			const ambient = launchEnvironmentOf(ctx).get(apiKeyRef);
+			if (ambient !== void 0 && ambient.value.length > 0) return assertUsableApiKey(ambient.value, "llm-billing", apiKeyRef);
+		}
+		throw new LlmError(`llm-billing: no API key; store ${apiKeyRef} through the credentials service or export it`, "MISSING_CREDENTIAL");
+	};
+	const fetchBalance = async () => {
+		const apiKey = await resolveApiKey();
+		return fetchDeepSeekBalance(baseURL(), apiKey);
+	};
+	const fetchSessionSpend = async (sessionId) => {
+		const billing = resolveBilling(config.billing);
+		const catalog = (config.models ?? DEFAULT_MODELS).map((model) => ({
+			id: model.id,
+			name: model.name ?? model.id
+		}));
+		return computeSessionSpend(await sessionEvents(ctx, sessionId), billing, catalog);
+	};
+	const fetchTodaySpend = async () => {
+		const billing = resolveBilling(config.billing);
+		const catalog = (config.models ?? DEFAULT_MODELS).map((model) => ({
+			id: model.id,
+			name: model.name ?? model.id
+		}));
+		return computeTodaySpend(await allSessionEvents(ctx), billing, catalog);
+	};
+	new DeepSeekBalanceGateway(ctx, {
+		fetchBalance,
+		fetchSessionSpend,
+		fetchTodaySpend
+	});
+}
+//#endregion
+export { Config, DEFAULT_MODEL_PRICING, DEFAULT_PEAK_HOURS, DeepSeekBalanceGateway, PUBLIC_BASE_URL, apply, computeSessionSpend, computeTodaySpend, fetchDeepSeekBalance, isPeak, name, parseDeepSeekBalance, resolveBilling };

package/packages/llm-billing/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@rayadesu/dsh-llm-billing`.
+* @module @rayadesu/dsh-llm-billing/invariant
+*/
+const PACKAGE_NAME = "@rayadesu/dsh-llm-billing";
+/** Cordis companion plugin name. */
+const name = "llm-billing-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package is a read-only Remote projection over the
+* provider balance and session logs, and owns no cross-plugin mutable state.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };