@askalf/dario 3.11.0 → 3.11.1

package/dist/analytics.d.ts

@@ -23,6 +23,26 @@ export interface RequestRecord {
     isStream: boolean;
     isOpenAI: boolean;
 }
+/**
+ * The four billing buckets a request can land in, derived from the
+ * `anthropic-ratelimit-unified-representative-claim` response header.
+ *
+ * - `subscription`         — request billed against the user's 5h subscription window (Max/Pro)
+ * - `subscription_fallback` — server-side fallback subscription bucket (rare, still covered)
+ * - `extra_usage`          — overage / pay-as-you-go, paid on top of subscription
+ * - `api`                  — pure API key billing, no subscription involved
+ * - `unknown`              — header absent or unparseable (non-200 responses, stream aborts)
+ *
+ * Exposed in `/analytics` summaries and in verbose per-request logs so
+ * users can see at a glance which bucket their traffic is actually hitting.
+ * See #34 for background.
+ */
+export type BillingBucket = 'subscription' | 'subscription_fallback' | 'extra_usage' | 'api' | 'unknown';
+/**
+ * Map the raw `representative-claim` header value to a human-friendly
+ * billing bucket. Pure function; no state; safe to call from any context.
+ */
+export declare function billingBucketFromClaim(claim: string | null | undefined): BillingBucket;
 export declare class Analytics {
     private records;
     private maxRecords;
@@ -60,27 +80,30 @@ interface PerModelStat {
     avgThinkingTokens: number;
     estimatedCost: number;
 }
+interface WindowStats {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalThinkingTokens: number;
+    estimatedCost: number;
+    avgLatencyMs: number;
+    errorRate: number;
+    claimBreakdown: Record<string, number>;
+    /** Count of requests in each derived billing bucket. See #34. */
+    billingBucketBreakdown: Record<BillingBucket, number>;
+    /**
+     * Percentage of *classified* requests (non-unknown) that hit a
+     * subscription bucket. The headline number for "is dario routing me
+     * through my subscription?" — should be 100% for a clean setup. See #34.
+     */
+    subscriptionPercent: number;
+}
 export interface AnalyticsSummary {
-    window: {
+    window: WindowStats & {
         minutes: number;
         requests: number;
-        totalInputTokens: number;
-        totalOutputTokens: number;
-        totalThinkingTokens: number;
-        estimatedCost: number;
-        avgLatencyMs: number;
-        errorRate: number;
-        claimBreakdown: Record<string, number>;
     };
-    allTime: {
+    allTime: WindowStats & {
         requests: number;
-        totalInputTokens: number;
-        totalOutputTokens: number;
-        totalThinkingTokens: number;
-        estimatedCost: number;
-        avgLatencyMs: number;
-        errorRate: number;
-        claimBreakdown: Record<string, number>;
     };
     perAccount: Record<string, PerAccountStat>;
     perModel: Record<string, PerModelStat>;

package/dist/analytics.js

@@ -5,6 +5,24 @@
  * In-memory rolling window; exposed via the /analytics endpoint when
  * pool mode is active.
  */
+/**
+ * Map the raw `representative-claim` header value to a human-friendly
+ * billing bucket. Pure function; no state; safe to call from any context.
+ */
+export function billingBucketFromClaim(claim) {
+    switch (claim) {
+        case 'five_hour':
+            return 'subscription';
+        case 'five_hour_fallback':
+            return 'subscription_fallback';
+        case 'overage':
+            return 'extra_usage';
+        case 'api':
+            return 'api';
+        default:
+            return 'unknown';
+    }
+}
 // Anthropic pricing (per 1M tokens, USD). Not authoritative — used for
 // rough burn-rate display in the /analytics summary.
 const PRICING = {
@@ -74,6 +92,14 @@ export class Analytics {
                 totalInputTokens: 0, totalOutputTokens: 0, totalThinkingTokens: 0,
                 estimatedCost: 0, avgLatencyMs: 0, errorRate: 0,
                 claimBreakdown: {},
+                billingBucketBreakdown: {
+                    subscription: 0,
+                    subscription_fallback: 0,
+                    extra_usage: 0,
+                    api: 0,
+                    unknown: 0,
+                },
+                subscriptionPercent: 0,
             };
         }
         const totalInput = records.reduce((s, r) => s + r.inputTokens, 0);
@@ -83,9 +109,22 @@ export class Analytics {
         const avgLatency = records.reduce((s, r) => s + r.latencyMs, 0) / records.length;
         const errors = records.filter(r => r.status >= 400).length;
         const claims = {};
+        const buckets = {
+            subscription: 0,
+            subscription_fallback: 0,
+            extra_usage: 0,
+            api: 0,
+            unknown: 0,
+        };
         for (const r of records) {
             claims[r.claim] = (claims[r.claim] ?? 0) + 1;
+            buckets[billingBucketFromClaim(r.claim)]++;
         }
+        const subscriptionHits = buckets.subscription + buckets.subscription_fallback;
+        const billedRequests = records.length - buckets.unknown;
+        const subscriptionPct = billedRequests > 0
+            ? Math.round((subscriptionHits / billedRequests) * 10000) / 100
+            : 0;
         return {
             totalInputTokens: totalInput,
             totalOutputTokens: totalOutput,
@@ -94,6 +133,8 @@ export class Analytics {
             avgLatencyMs: Math.round(avgLatency),
             errorRate: Math.round((errors / records.length) * 10000) / 10000,
             claimBreakdown: claims,
+            billingBucketBreakdown: buckets,
+            subscriptionPercent: subscriptionPct,
         };
     }
     perAccountStats(records) {

package/dist/proxy.js

@@ -8,7 +8,7 @@ import { arch, platform } from 'node:process';
 import { getAccessToken, getStatus } from './oauth.js';
 import { buildCCRequest, reverseMapResponse, createStreamingReverseMapper } from './cc-template.js';
 import { AccountPool, parseRateLimits } from './pool.js';
-import { Analytics } from './analytics.js';
+import { Analytics, billingBucketFromClaim } from './analytics.js';
 import { loadAllAccounts, loadAccount, refreshAccountToken } from './accounts.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI } from './openai-backend.js';
 const ANTHROPIC_API = 'https://api.anthropic.com';
@@ -1039,7 +1039,13 @@ export async function startProxy(opts = {}) {
                     else {
                         overagePct = 'n/a';
                     }
-                    console.log(`[dario] #${requestCount} billing: ${billingClaim} (overage: ${overagePct})`);
+                    // Show the derived billing bucket as the headline, with the raw
+                    // claim value in parens so power users still see the header as-is.
+                    // See #34 — users want "am I actually on subscription?" answered
+                    // at a glance instead of having to memorize that `five_hour` means
+                    // "yes, subscription."
+                    const bucket = billingBucketFromClaim(billingClaim);
+                    console.log(`[dario] #${requestCount} billing: ${bucket} (${billingClaim}, overage: ${overagePct})`);
                 }
                 else if (verbose) {
                     console.log(`[dario] #${requestCount} billing: headers absent (status=${upstream.status})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.11.0",
+  "version": "3.11.1",
   "description": "A local LLM router. One endpoint, every provider — Claude subscriptions, OpenAI, OpenRouter, Groq, local LiteLLM, any OpenAI-compat endpoint — your tools don't need to change.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "tsc && cp src/cc-template-data.json dist/",
-    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/failover-429.mjs && node test/live-fingerprint.mjs",
+    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/live-fingerprint.mjs",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",