@ychris12138/dsh-usage-stats 0.3.0 → 0.3.1

package/lib/index.js

@@ -1,7 +1,8 @@
 /**
  * dsh-usage-stats — server half.
  *
- * Registers nine read-only, loopback-only endpoints on the web server:
+ * Registers nine read-only, loopback-only data endpoints plus one explicit
+ * loopback-only OrcaRouter settings action on the web server:
  *   GET /api/usage-stats/usage         — per-day token usage across every session
  *   GET /api/usage-stats/providers     — configured providers + balance schemes
  *   GET /api/usage-stats/balance       — balance for one provider (?provider=<id>)
@@ -11,6 +12,7 @@
  *   GET /api/usage-stats/export/daily.csv — daily provider/model usage export
  *   GET /api/usage-stats/export/sessions.csv — per-session usage export
  *   GET /api/usage-stats/export.json — versioned usage/account-safe export
+ *   GET|POST /api/usage-stats/integrations/orcarouter — status / explicit add
  *
  * Provider configuration is read straight from the harness settings
  * (`llm-deepseek` for the official DeepSeek route, `llm-pi-ai` for every
@@ -41,6 +43,7 @@ import { applyUsageDelta, createUsageState, currentSessionContext, mergeBillingI
 import { ACCOUNT_REFRESH_MS, createAccountService, validateAccountConfig } from "./accounts.js";
 import { changedProviderPricingRoutes, createUsageCostEstimator, parseCostAccumulator, pricingFingerprint, renderBudgetSummary, serializeCostAccumulator, validateBudgetConfig } from "./billing.js";
 import { dailyCsv, jsonExport, sessionsCsv } from "./export.js";
+import { addOrcaRouterPreset, orcaRouterIntegrationState } from "./orcarouter.js";
 
 /** Stable Cordis plugin name. */
 const name = "usage-stats";
@@ -57,6 +60,7 @@ const SESSION_CONTEXT_PATH = "/api/usage-stats/session-context";
 const DAILY_EXPORT_PATH = "/api/usage-stats/export/daily.csv";
 const SESSIONS_EXPORT_PATH = "/api/usage-stats/export/sessions.csv";
 const JSON_EXPORT_PATH = "/api/usage-stats/export.json";
+const ORCAROUTER_INTEGRATION_PATH = "/api/usage-stats/integrations/orcarouter";
 const UPSTREAM_TIMEOUT_MS = 15000;
 const CACHE_VERSION = 5;
 
@@ -138,6 +142,29 @@ function rejectForeignCaller(req, res) {
 	return true;
 }
 
+/**
+ * Fence the sole settings mutation. The custom action header makes this a
+ * non-simple browser request, so a foreign page cannot CSRF the loopback route
+ * without a CORS preflight (the exact route never grants CORS).
+ */
+function rejectForeignMutation(req, res) {
+	if (req.method !== "POST") {
+		json(res, 405, { ok: false, error: "method-not-allowed" });
+		return true;
+	}
+	const peer = req.socket?.remoteAddress;
+	if (!isLoopbackAddress(peer) || !isLoopbackHostHeader(req)) {
+		json(res, 403, { ok: false, error: "forbidden" });
+		return true;
+	}
+	const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"].toLowerCase() : "";
+	if (!contentType.startsWith("application/json") || req.headers["x-dsh-usage-stats-action"] !== "add-orcarouter") {
+		json(res, 403, { ok: false, error: "forbidden-action" });
+		return true;
+	}
+	return false;
+}
+
 //#region incremental cache
 /** Cache file location under the dsh home. */
 function cachePath() {
@@ -466,7 +493,14 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 							resetUsageState(state);
 						}
 						const fresh = wasPersisted ? events.filter((event) => event.seq > (state.consumed ?? 0)) : events;
-						const contiguous = fresh.length === 0 ? state.consumed === 0 : fresh[0].seq === state.consumed + 1;
+						// readFrom is inclusive: an unchanged log returns exactly the
+						// already-folded cursor event (seq === consumed). An empty
+						// fresh slice with the cursor still present is therefore NOT a
+						// rewrite — only a log that no longer contains the cursor
+						// (truncated/rewritten) must refold from scratch.
+						const contiguous = fresh.length === 0
+							? wasPersisted && events.some((event) => event.seq === (state.consumed ?? 0))
+							: fresh[0].seq === state.consumed + 1;
 						if (!contiguous && state.consumed > 0) {
 							// Log truncated or rewritten: refold the whole log.
 							resetUsageState(state);
@@ -644,9 +678,8 @@ export async function collectActiveAccountIds(ctx, config = { monitors: {} }) {
 async function handleSessionContext(ctx, config, accounts, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		// Client loader entries carry module identity, not the server Cordis
-		// config. Keep the display policy server-owned on this existing request:
-		// a hidden Pill performs no usage fold or account read and renders null.
+		// Preserve the v0.3.0 API response for the legacy display flag even though
+		// the current client no longer renders any composer UI.
 		if (config.display?.currentSessionPill === false) {
 			json(res, 200, { ok: true, context: null, display: { currentSessionPill: false } });
 			return;
@@ -703,6 +736,37 @@ async function handleProviders(ctx, accounts, req, res) {
 	}
 }
 
+/** Read secret-free preset state or perform the user's explicit path mutation. */
+async function handleOrcaRouterIntegration(ctx, req, res) {
+	if (req.method === "GET") {
+		if (rejectForeignCaller(req, res)) return;
+		try {
+			json(res, 200, { ok: true, integration: orcaRouterIntegrationState(ctx.get("settings")) });
+		} catch (error) {
+			ctx.logger.warn(`usage-stats: OrcaRouter integration status failed: ${String(error)}`);
+			json(res, 500, { ok: false, error: "internal", message: "settings status unavailable" });
+		}
+		return;
+	}
+	if (rejectForeignMutation(req, res)) return;
+	try {
+		const integration = await addOrcaRouterPreset(ctx.get("settings"));
+		if (!integration.available) {
+			json(res, 409, { ok: false, error: "settings-unavailable", message: "DSH provider settings are not writable" });
+			return;
+		}
+		json(res, 200, { ok: true, integration });
+	} catch (error) {
+		const conflict = error?.code === "SETTINGS_CONFLICT";
+		ctx.logger.warn(`usage-stats: OrcaRouter settings mutation failed (${conflict ? "conflict" : "rejected"})`);
+		json(res, conflict ? 409 : 422, {
+			ok: false,
+			error: conflict ? "settings-conflict" : "settings-update-rejected",
+			message: conflict ? "provider settings changed; retry the action" : "DSH rejected the provider preset"
+		});
+	}
+}
+
 async function selectedProviderId(req, accounts) {
 	const url = new URL(req.url ?? "/", "http://x");
 	const requested = url.searchParams.get("provider");
@@ -895,7 +959,8 @@ export function startBackgroundRefresh(ctx, accounts, deps = {}) {
 }
 
 /**
- * Plugin body: register the nine exact routes and start background refresh.
+ * Plugin body: register nine data routes plus the explicit integration route,
+ * then start background refresh.
  * @param ctx - plugin context carrying webServer, credentials, sessions, sessionPersistence, settings, and llm.
  */
 const Config = {
@@ -967,6 +1032,11 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 		path: SESSION_CONTEXT_PATH,
 		handler: (req, res) => handleSessionContext(ctx, config, accounts, req, res)
 	}), "usage-stats: session context route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: ORCAROUTER_INTEGRATION_PATH,
+		handler: (req, res) => handleOrcaRouterIntegration(ctx, req, res)
+	}), "usage-stats: optional OrcaRouter integration route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: DAILY_EXPORT_PATH,
@@ -988,4 +1058,4 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 	}), "usage-stats: background usage/account refresh");
 }
 
-export { apply, Config, inject, name, USAGE_PATH, PROVIDERS_PATH, BALANCE_PATH, SUBSCRIPTIONS_PATH, ACCOUNT_PATH, SESSION_CONTEXT_PATH, DAILY_EXPORT_PATH, SESSIONS_EXPORT_PATH, JSON_EXPORT_PATH, configuredProviders, totalTokens, validateConfig, zeroBuckets };
+export { apply, Config, inject, name, USAGE_PATH, PROVIDERS_PATH, BALANCE_PATH, SUBSCRIPTIONS_PATH, ACCOUNT_PATH, SESSION_CONTEXT_PATH, DAILY_EXPORT_PATH, SESSIONS_EXPORT_PATH, JSON_EXPORT_PATH, ORCAROUTER_INTEGRATION_PATH, configuredProviders, totalTokens, validateConfig, zeroBuckets };

package/lib/orcarouter.js

@@ -0,0 +1,79 @@
+/**
+ * Optional OrcaRouter provider preset and its narrow DSH settings mutation.
+ *
+ * The plugin never edits settings.yaml directly and never installs this route
+ * during startup. A caller must explicitly request the single path mutation;
+ * an existing `orcarouter` profile always wins unchanged.
+ *
+ * @module dsh-usage-stats/orcarouter
+ */
+
+const SETTINGS_NAMESPACE = "llm-pi-ai";
+const PROVIDER_ID = "orcarouter";
+
+export const ORCAROUTER_PROFILE = Object.freeze({
+	displayName: "OrcaRouter",
+	apiKeyEnv: "ORCAROUTER_API_KEY",
+	api: "openai-completions",
+	baseURL: "https://api.orcarouter.ai/v1",
+	models: Object.freeze([Object.freeze({ id: "orcarouter/auto", name: "OrcaRouter Auto" })])
+});
+
+function descriptorOf(settings) {
+	if (typeof settings?.describe !== "function") return null;
+	const descriptors = settings.describe({ redactSecrets: true });
+	if (!Array.isArray(descriptors)) return null;
+	return descriptors.find((entry) => entry?.ns === SETTINGS_NAMESPACE) ?? null;
+}
+function hasOrcaRouter(descriptor) {
+	const providers = descriptor?.value?.providers;
+	return providers !== null && typeof providers === "object" && !Array.isArray(providers)
+		&& Object.hasOwn(providers, PROVIDER_ID);
+}
+
+/** Secret-free availability state suitable for the browser integration card. */
+export function orcaRouterIntegrationState(settings) {
+	const descriptor = descriptorOf(settings);
+	const available = descriptor !== null && typeof settings?.mutate === "function" && settings.writable !== false;
+	return {
+		available,
+		installed: descriptor !== null && hasOrcaRouter(descriptor)
+	};
+}
+
+function detachedProfile() {
+	return {
+		displayName: ORCAROUTER_PROFILE.displayName,
+		apiKeyEnv: ORCAROUTER_PROFILE.apiKeyEnv,
+		api: ORCAROUTER_PROFILE.api,
+		baseURL: ORCAROUTER_PROFILE.baseURL,
+		models: ORCAROUTER_PROFILE.models.map((model) => ({ ...model }))
+	};
+}
+
+/**
+ * Add the preset with one revision-guarded path mutation. This preserves all
+ * unrelated providers and converges cleanly if another writer adds the same
+ * route between our read and write.
+ */
+export async function addOrcaRouterPreset(settings) {
+	const before = descriptorOf(settings);
+	const available = before !== null && typeof settings?.mutate === "function" && settings.writable !== false;
+	if (!available) return { available: false, installed: hasOrcaRouter(before), added: false };
+	if (hasOrcaRouter(before)) return { available: true, installed: true, added: false };
+
+	try {
+		await settings.mutate(SETTINGS_NAMESPACE, [{
+			op: "set",
+			path: ["providers", PROVIDER_ID],
+			value: detachedProfile()
+		}], before.revision);
+		return { available: true, installed: true, added: true };
+	} catch (error) {
+		if (error?.code === "SETTINGS_CONFLICT") {
+			const after = descriptorOf(settings);
+			if (hasOrcaRouter(after)) return { available: true, installed: true, added: false };
+		}
+		throw error;
+	}
+}

package/lib/provider-identity.js

@@ -20,6 +20,7 @@ const ADAPTER_IDENTITIES = Object.freeze({
 	"openrouter-balance": { providerFamily: "openrouter", pricingFamily: "openrouter" },
 	"moonshot-balance": { providerFamily: "moonshot", pricingFamily: "moonshot" },
 	"zai-balance": { providerFamily: "zai", pricingFamily: "zai" },
+	"orcarouter-balance": { providerFamily: "orcarouter", pricingFamily: "unknown" },
 	general: { providerFamily: "unknown", pricingFamily: "unknown" },
 	"new-api": { providerFamily: "new-api", pricingFamily: "unknown" },
 	sub2api: { providerFamily: "sub2api", pricingFamily: "unknown" },
@@ -48,6 +49,7 @@ const CANONICAL_ROUTES = Object.freeze({
 	minimaxi: { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
 	"minimax-cn": { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
 	"minimax-coding": { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
+	orcarouter: { providerFamily: "orcarouter", accountAdapter: "orcarouter-balance", pricingFamily: "unknown", balanceScheme: "orcarouter" },
 	passion: { providerFamily: "sub2api", accountAdapter: "sub2api", pricingFamily: "unknown", balanceScheme: null }
 });
 
@@ -66,6 +68,7 @@ function hostnameOf(baseURL) {
 
 function hostRule(hostname) {
 	if (hostname === "api.deepseek.com") return { providerFamily: "deepseek", accountAdapter: "deepseek-balance" };
+	if (hostname === "api.orcarouter.ai") return { providerFamily: "orcarouter", accountAdapter: "orcarouter-balance", pricingFamily: "unknown" };
 	if (hostname === "passionapi.com" || hostname.endsWith(".passionapi.com")) return { providerFamily: "sub2api", accountAdapter: "sub2api", pricingFamily: "unknown" };
 	if (hostname === "ollama.com" || hostname.endsWith(".ollama.com")) return { providerFamily: "ollama", accountAdapter: "ollama" };
 	return null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ychris12138/dsh-usage-stats",
   "description": "Token usage, provider accounts, session cost estimates, budgets, and exports for the dsh web GUI",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ychris12138/dsh-usage-stats.git"
@@ -23,6 +23,7 @@
     "docs/images/usage-panel.svg",
     "docs/release-checklist.md",
     "docs/release-notes-v0.3.0.md",
+    "docs/release-notes-v0.3.1.md",
     "scripts/install.mjs",
     "README.md",
     "LICENSE",
@@ -51,10 +52,10 @@
     }
   },
   "scripts": {
-    "check": "npm run check:release && node --check lib/index.js && node --check lib/usage.js && node --check lib/billing.js && node --check lib/pricing.js && node --check lib/network.js && node --check lib/provider-identity.js && node --check lib/balance.js && node --check lib/subscriptions.js && node --check lib/accounts.js && node --check lib/export.js && node --check lib/client.js && node --check scripts/install.mjs && node --check scripts/smoke-client.mjs && node --check scripts/test-overlay-layering.mjs && node --check scripts/test-bundle.mjs && node --check scripts/test-install.mjs && node --check scripts/test-server.mjs && node --check scripts/test-export.mjs && node --check scripts/test-provider-identity.mjs && node --check scripts/test-pricing.mjs && node --check scripts/test-billing.mjs && node --check scripts/test-balance.mjs && node --check scripts/test-subscriptions.mjs && node --check scripts/test-accounts.mjs && node --check scripts/release-metadata.mjs && node --check scripts/check-release-metadata.mjs && node --check scripts/sync-release-version.mjs && node --check scripts/validate-fold.mjs && node --check scripts/verify-raw.mjs && node --check scripts/check-balance.mjs",
+    "check": "npm run check:release && node --check lib/index.js && node --check lib/usage.js && node --check lib/billing.js && node --check lib/pricing.js && node --check lib/network.js && node --check lib/provider-identity.js && node --check lib/orcarouter.js && node --check lib/balance.js && node --check lib/subscriptions.js && node --check lib/accounts.js && node --check lib/export.js && node --check lib/client.js && node --check scripts/install.mjs && node --check scripts/smoke-client.mjs && node --check scripts/test-overlay-layering.mjs && node --check scripts/test-bundle.mjs && node --check scripts/test-install.mjs && node --check scripts/test-server.mjs && node --check scripts/test-export.mjs && node --check scripts/test-provider-identity.mjs && node --check scripts/test-orcarouter.mjs && node --check scripts/test-pricing.mjs && node --check scripts/test-billing.mjs && node --check scripts/test-balance.mjs && node --check scripts/test-subscriptions.mjs && node --check scripts/test-accounts.mjs && node --check scripts/release-metadata.mjs && node --check scripts/check-release-metadata.mjs && node --check scripts/sync-release-version.mjs && node --check scripts/validate-fold.mjs && node --check scripts/verify-raw.mjs && node --check scripts/check-balance.mjs",
     "check:release": "node scripts/check-release-metadata.mjs",
     "release:sync": "node scripts/sync-release-version.mjs",
-    "test": "npm run test:bundle && npm run test:client && npm run test:overlay && npm run test:server && npm run test:export && npm run test:provider-identity && npm run test:pricing && npm run test:billing && npm run test:balance && npm run test:subscriptions && npm run test:accounts && npm run test:install",
+    "test": "npm run test:bundle && npm run test:client && npm run test:overlay && npm run test:server && npm run test:export && npm run test:provider-identity && npm run test:orcarouter && npm run test:pricing && npm run test:billing && npm run test:balance && npm run test:subscriptions && npm run test:accounts && npm run test:install",
     "test:bundle": "node scripts/test-bundle.mjs",
     "test:client": "node scripts/smoke-client.mjs",
     "test:overlay": "node scripts/test-overlay-layering.mjs",
@@ -62,6 +63,7 @@
     "test:server": "node scripts/test-server.mjs",
     "test:export": "node scripts/test-export.mjs",
     "test:provider-identity": "node scripts/test-provider-identity.mjs",
+    "test:orcarouter": "node scripts/test-orcarouter.mjs",
     "test:pricing": "node scripts/test-pricing.mjs",
     "test:billing": "node scripts/test-billing.mjs",
     "test:balance": "node scripts/test-balance.mjs",