@subvalue/cli 0.1.5 → 0.1.6

package/README.md

@@ -42,7 +42,7 @@ npm run demo
 - **Receipt:** local canvas preview and PNG export of the exact same pixels. No projects, paths, requests or sessions in exports.
 - **Settings:** Sources, Billing, USD, Privacy / data. Inactive providers stay here, with optional manual inclusion.
 
-First run shows detected history, then offers subscription plans directly for each provider with imported usage. Choose a plan, a custom USD amount, or **No subscription** independently for Codex and Claude Code. No subscription requires no amount and never implies API billing. **Set up later** leaves billing unknown.
+First run offers subscription plans for each provider with imported usage. Choose a plan, a custom USD amount, or **No subscription · API** independently for Codex and Claude Code. Subscription + API is available as a checkbox. Unconfigured or legacy no-subscription settings default to API as an editable preference; this does not prove how any historical request was billed. Actual API payments remain unknown until entered for a specific period.
 
 Month opens a floating calendar-month picker (including historical months). Previous/next arrows move by one calendar month, seven or thirty days for rolling presets, or the selected custom duration. Comparisons use the full declared monthly price for each complete calendar month selected. The current month is marked In progress. 7D, 30D and partial custom ranges show API-equivalent usage without subscription comparisons. Custom ranges covering whole calendar months compare the corresponding number of monthly charges. Amounts and API prices are USD; no invented exchange rates. Billing declarations do not overwrite historical records or prove their original billing mode. Settings offers bundled, verified ChatGPT/Claude plan presets and a custom amount. Annual presets retain the exact annual price divided by 12, with per-seat plans labeled.
 
@@ -68,7 +68,11 @@ Codex excludes inherited ordinal prefixes, uses cumulative deltas, suppresses re
 
 The versioned catalog supports mappings with confidence and primary-source provenance, half-open effective intervals, cache reads/writes, Claude cache durations, and long-context bands. Rates and release evidence were checked against [OpenAI pricing](https://developers.openai.com/api/docs/pricing) and [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing) on **2026-10-05**. Historical versions include the July 30 Luna/Terra reductions and August 21 Sol promotion. Exact public GPT-5.6/6 and Claude identifiers carry mapping provenance; long-context rates use the verified 272k request threshold. New-model launch days use their documented initial API-equivalent rate. Calendar-dated changes between rates remain unknown because their exact UTC switch time is not documented. Sol pricing after the confirmed promotion remains unavailable. See [the pricing evidence ledger](dist/PRICING.md). Internal/unknown model identifiers are never mapped by resemblance.
 
-Overview and receipt display the sum of priceable events; the compact priced percentage identifies partial pricing, and unpriced model identities remain visible in Details. No guessed price or zero is assigned to unknown events. Both views share a display comparison of the known priced amount with the declared full-month subscription: Observed Value / You Saved is their difference, and Value Multiple is their ratio. The normalized summary still marks the full-usage cost and comparison unknown when pricing is incomplete. Partial coverage remains visible; these observed values do not infer a certain outcome or an exact break-even date. No subscription, unknown billing, and legacy API/mixed settings have no subscription comparison. Combined subscription comparisons require a declared subscription for every active provider.
+Overview and receipt display the sum of priceable events; partial pricing stays visible and unknown model prices are never invented. Value is the displayed API equivalent minus total paid; Value Multiple is API equivalent divided by total paid (subscription plus declared API payments). A missing payment stays unknown; an explicit zero is accepted but cannot be a multiplier denominator. Comparisons remain limited to complete calendar months. Partial pricing uses observed values without a certain outcome or break-even date.
+
+Expense controls appear inside a provider card only for mixed billing, or when that provider has no subscription while the other active provider has a subscription. Select a plan using the same menu as onboarding, or enter actual API spend; mixed mode starts its editable API field at $0. **Save** applies only to the displayed period and provider. A complete single month is stored as a monthly override, shared by Month and an equivalent Custom selection. Other ranges use an exact civil-date range key; amounts are not copied to other selections. API spend over several whole months is a total for that range and is counted once. Settings also provides per-period editing and reset to the default. Saved overrides survive changes to the usual plan, receipt theme changes and relaunch. The scanner and usage records are unchanged.
+
+When an active provider has not supplied its expenses, a labeled comparison uses only providers with known expenses; the overall API-equivalent figure still includes all observed usage. Empty periods show imported history bounds.
 
 ## Architecture
 

package/dist/packages/cli/src/server.js

@@ -9,6 +9,8 @@ import { demoData } from '../../core/src/demo.js';
 import {
   defaultSettings,
                    
+               
+                
                 
                    
 } from '../../core/src/types.js';
@@ -17,6 +19,7 @@ import {
 import { isRecord } from '../../core/src/metadata.js';
 import { safeDirectory } from '../../core/src/security.js';
 import { subscriptionPlan } from '../../core/src/subscriptions.js';
+import { shiftCalendarDays } from '../../core/src/calendar.js';
 const mime                         = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
@@ -29,6 +32,34 @@ const billingModes = ['UNKNOWN', 'SUBSCRIPTION', 'NO_SUBSCRIPTION', 'API', 'MIXE
 const isBillingMode = (value         )                       =>
   billingModes.some((mode) => mode === value);
 
+function validateBilling(provider          , value         , monthly = false)          {
+  if (!isRecord(value) || !isBillingMode(value.mode)) throw new Error('Invalid billing settings');
+  const amount = (n         ) =>
+    n === null || (typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1000000);
+  if (!amount(value.monthly)) throw new Error('Invalid subscription amount');
+  if (value.apiSpend !== undefined && !amount(value.apiSpend)) throw new Error('Invalid API spend');
+  if (!monthly && value.apiSpend != null) throw new Error('API spend belongs to a specific month');
+  const planId = value.planId;
+  if (planId != null && typeof planId !== 'string') throw new Error('Invalid subscription plan');
+  const plan = planId == null ? undefined : subscriptionPlan(provider, planId);
+  if (planId != null && !plan) throw new Error('Invalid subscription plan');
+  const subscribed = value.mode === 'SUBSCRIPTION' || value.mode === 'MIXED';
+  if (
+    subscribed &&
+    plan &&
+    (value.monthly === null || Math.abs(Number(value.monthly) - plan.monthly) > 0.005)
+  )
+    throw new Error('Subscription amount does not match the selected plan');
+  return {
+    mode: value.mode,
+    monthly: subscribed ? (plan?.monthly ?? (value.monthly                 )) : null,
+    ...(subscribed && planId !== undefined ? { planId: plan?.id ?? null } : {}),
+    ...(monthly &&
+    (value.mode === 'API' || value.mode === 'MIXED' || value.mode === 'NO_SUBSCRIPTION')
+      ? { apiSpend: (value.apiSpend                             ) ?? null }
+      : {}),
+  };
+}
 export function validateSettings(value         )           {
   if (!isRecord(value) || value.currency !== 'USD' || typeof value.onboarded !== 'boolean')
     throw new Error('Invalid settings');
@@ -42,33 +73,49 @@ export function validateSettings(value         )           {
     settings.receiptTheme = value.receiptTheme;
   }
   for (const provider of ['codex', 'claude']         ) {
-    const billing = value.billing[provider];
-    const included = value.include[provider];
-    if (!isRecord(billing) || !isBillingMode(billing.mode) || typeof included !== 'boolean')
-      throw new Error('Invalid billing settings');
-    const monthly = billing.monthly;
-    if (
-      monthly !== null &&
-      (typeof monthly !== 'number' || !Number.isFinite(monthly) || monthly < 0 || monthly > 1000000)
-    )
-      throw new Error('Invalid subscription amount');
-    const planId = billing.planId;
-    if (planId != null && typeof planId !== 'string') throw new Error('Invalid subscription plan');
-    const plan = planId == null ? undefined : subscriptionPlan(provider, planId);
-    if (planId != null && !plan) throw new Error('Invalid subscription plan');
-    if (
-      billing.mode === 'SUBSCRIPTION' &&
-      plan &&
-      (monthly === null || Math.abs(monthly - plan.monthly) > 0.005)
-    )
-      throw new Error('Subscription amount does not match the selected plan');
-    settings.billing[provider] = {
-      mode: billing.mode,
-      monthly: billing.mode === 'SUBSCRIPTION' ? (plan?.monthly ?? monthly) : null,
-    };
-    if (billing.mode === 'SUBSCRIPTION' && planId !== undefined)
-      settings.billing[provider].planId = plan?.id ?? null;
-    settings.include[provider] = included;
+    if (typeof value.include[provider] !== 'boolean') throw new Error('Invalid billing settings');
+    settings.billing[provider] = validateBilling(provider, value.billing[provider]);
+    settings.include[provider] = value.include[provider];
+  }
+  if (value.monthlyBilling !== undefined) {
+    if (!isRecord(value.monthlyBilling) || Object.keys(value.monthlyBilling).length > 240)
+      throw new Error('Invalid monthly billing');
+    settings.monthlyBilling = {};
+    for (const [month, providers] of Object.entries(value.monthlyBilling)) {
+      if (
+        !/^(?:19|20|21)\d{2}-(?:0[1-9]|1[0-2])$/.test(month) ||
+        !isRecord(providers) ||
+        Object.keys(providers).some((provider) => provider !== 'codex' && provider !== 'claude')
+      )
+        throw new Error('Invalid monthly billing');
+      const entry                                     = {};
+      for (const provider of ['codex', 'claude']         )
+        if (providers[provider] !== undefined)
+          entry[provider] = validateBilling(provider, providers[provider], true);
+      settings.monthlyBilling[month] = entry;
+    }
+  }
+  if (value.periodBilling !== undefined) {
+    if (!isRecord(value.periodBilling) || Object.keys(value.periodBilling).length > 240)
+      throw new Error('Invalid period billing');
+    settings.periodBilling = {};
+    for (const [key, providers] of Object.entries(value.periodBilling)) {
+      const [from, to] = key.split(':');
+      if (
+        !/^\d{4}-\d{2}-\d{2}:\d{4}-\d{2}-\d{2}$/.test(key) ||
+        shiftCalendarDays(from, 0) === null ||
+        shiftCalendarDays(to, 0) === null ||
+        from > to ||
+        !isRecord(providers) ||
+        Object.keys(providers).some((p) => p !== 'codex' && p !== 'claude')
+      )
+        throw new Error('Invalid period billing');
+      const entry                                     = {};
+      for (const provider of ['codex', 'claude']         )
+        if (providers[provider] !== undefined)
+          entry[provider] = validateBilling(provider, providers[provider], true);
+      settings.periodBilling[key] = entry;
+    }
   }
   return settings;
 }

package/dist/packages/core/src/billing.js

@@ -0,0 +1,112 @@
+                                                                           
+                                                           
+import { fullCalendarMonths, shiftCalendarMonth } from './calendar.js';
+
+function civilDate(date      )         {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+export function billingPeriodKey(range       )         {
+  return (
+    (range.calendarFrom ?? civilDate(new Date(range.from))) +
+    ':' +
+    (range.calendarTo ?? civilDate(new Date(Date.parse(range.until) - 1)))
+  );
+}
+export function withPeriodBilling(
+  settings          ,
+  provider          ,
+  range       ,
+  billing                ,
+)           {
+  const next = structuredClone(settings),
+    exactKey = billingPeriodKey(range),
+    monthly = fullCalendarMonths(range) === 1,
+    key = monthly ? exactKey.slice(0, 7) : exactKey,
+    declarations = monthly ? (next.monthlyBilling ??= {}) : (next.periodBilling ??= {});
+  // A rolling range can share dates with a calendar month. Editing that month
+  // supersedes an earlier exact-date declaration instead of leaving a stale override.
+  if (monthly && next.periodBilling?.[exactKey]?.[provider]) {
+    delete next.periodBilling[exactKey][provider];
+    if (!Object.keys(next.periodBilling[exactKey]).length) delete next.periodBilling[exactKey];
+  }
+  declarations[key] ??= {};
+  if (billing) declarations[key][provider] = billing;
+  else delete declarations[key][provider];
+  if (!Object.keys(declarations[key]).length) delete declarations[key];
+  return next;
+}
+export function billingForSelection(settings          , provider          , range       )          {
+  const exact = settings.periodBilling?.[billingPeriodKey(range)]?.[provider];
+  if (exact) return exact;
+  if (fullCalendarMonths(range) === 1)
+    return billingForMonth(settings, provider, billingPeriodKey(range).slice(0, 7));
+  return billingForMonth({ ...settings, monthlyBilling: undefined }, provider, '');
+}
+
+/** Keep the dashboard action limited to mixed billing or a second provider without a plan. */
+export function showExpenseAction(
+  provider                 ,
+  providers                   ,
+)          {
+  if (!provider.records) return false;
+  if (provider.mode === 'MIXED') return true;
+  return (
+    (provider.mode === 'API' ||
+      provider.mode === 'NO_SUBSCRIPTION' ||
+      provider.mode === 'UNKNOWN') &&
+    providers.some(
+      (other) =>
+        other.provider !== provider.provider &&
+        other.records > 0 &&
+        (other.mode === 'SUBSCRIPTION' || other.mode === 'MIXED') &&
+        (other.monthly != null || (other.comparison.subscription ?? 0) > 0),
+    )
+  );
+}
+
+/** A default is a user preference, not evidence of how a historical request was billed. */
+export function billingForMonth(settings          , provider          , month        )          {
+  const saved = settings.monthlyBilling?.[month]?.[provider] ?? settings.billing[provider];
+  return {
+    ...saved,
+    mode: saved.mode === 'UNKNOWN' || saved.mode === 'NO_SUBSCRIPTION' ? 'API' : saved.mode,
+  };
+}
+
+export function billingForRange(settings          , provider          , range       ) {
+  const count = fullCalendarMonths(range);
+  const exact = settings.periodBilling?.[billingPeriodKey(range)]?.[provider];
+  const start = new Date(range.from);
+  const first =
+    range.calendarFrom?.slice(0, 7) ??
+    `${start.getFullYear()}-${String(start.getMonth() + 1).padStart(2, '0')}`;
+  const months = Array.from(
+    { length: count ?? 1 },
+    (_, index) => exact ?? billingForMonth(settings, provider, shiftCalendarMonth(first, index) ),
+  );
+  const mode              = months.every((b) => b.mode === months[0].mode)
+    ? months[0].mode
+    : 'MIXED';
+  const subscriptionKnown = months.every((b) => b.mode === 'API' || b.monthly !== null);
+  const apiKnown = months.every((b) => b.mode === 'SUBSCRIPTION' || b.apiSpend != null);
+  const subscription =
+    count !== null && subscriptionKnown
+      ? months.reduce((total, b) => total + (b.mode === 'API' ? 0 : b.monthly ), 0)
+      : null;
+  const apiSpend =
+    count !== null && apiKnown
+      ? exact
+        ? exact.mode === 'SUBSCRIPTION'
+          ? 0
+          : exact.apiSpend 
+        : months.reduce((total, b) => total + (b.mode === 'SUBSCRIPTION' ? 0 : b.apiSpend ), 0)
+      : null;
+  return {
+    mode,
+    monthly: months.length === 1 ? months[0].monthly : null,
+    subscription,
+    apiSpend,
+    paid: subscription !== null && apiSpend !== null ? subscription + apiSpend : null,
+    needsBilling: !subscriptionKnown || !apiKnown,
+  };
+}

package/dist/packages/core/src/summary.js

@@ -1,3 +1,4 @@
+import { billingForRange } from './billing.js';
                                                                                 
 import { priceRecord, catalog,              } from './pricing/index.js';
 import { fullCalendarMonths, shiftCalendarDays } from './calendar.js';
@@ -88,6 +89,8 @@ export function dateRange(
   return { ...range, calendarMonths: fullCalendarMonths(range) };
 }
                              
+                           
+                       
                               
                        
                      
@@ -118,6 +121,7 @@ export function subscriptionForRange(monthly        , range       )
                          
                
                          
+                         
                        
                       
                
@@ -199,52 +203,46 @@ export function summarize(
     const historyPartial = !demo; // Local transcripts cannot prove that all historical requests were retained.
     const completePricing = rows.length > 0 && priced.length === rows.length;
     const apiEquivalent = completePricing ? subtotal : null;
-    const billing = settings.billing[provider];
-    const subscription =
-      billing.mode === 'SUBSCRIPTION' && billing.monthly !== null
-        ? subscriptionForRange(billing.monthly, range)
-        : null;
-    let comparison = neutral(
-      billing.mode === 'NO_SUBSCRIPTION'
-        ? 'No subscription'
-        : billing.mode === 'API'
-          ? 'API usage'
-          : billing.mode === 'MIXED'
-            ? 'Mixed billing'
-            : billing.mode === 'UNKNOWN'
-              ? 'Billing not set'
-              : fullCalendarMonths(range) === null
-                ? 'Choose a full month'
-                : subscription === null
-                  ? 'Subscription price not set'
-                  : !completePricing
-                    ? 'Pricing unavailable'
-                    : 'Partial history',
-      subscription,
-    );
-    if (completePricing && subscription !== null) {
-      const value = apiEquivalent  - subscription;
+    const billing = billingForRange(settings, provider, range);
+    const { subscription, apiSpend, paid } = billing;
+    let comparison             = {
+      ...neutral(
+        fullCalendarMonths(range) === null
+          ? 'Choose a full month'
+          : paid === null
+            ? 'Expenses not set'
+            : 'Partial history',
+        subscription,
+      ),
+      apiSpend,
+      paid,
+    };
+    if (completePricing && paid !== null) {
+      const value = apiEquivalent  - paid;
       let accumulated = 0;
       let breakEven                = null;
       for (const d of daily) {
         accumulated += d[provider] ?? 0;
-        if (accumulated >= subscription) {
+        if (accumulated >= paid) {
           breakEven = d.date;
           break;
         }
       }
       comparison = {
         subscription,
+        apiSpend,
+        paid,
         value,
-        roi: subscription > 0 ? apiEquivalent  / subscription : null,
+        roi: paid > 0 ? apiEquivalent  / paid : null,
         breakEven: historyPartial ? null : breakEven,
-        outcome: historyPartial
-          ? 'neutral'
-          : value > 0
-            ? 'positive'
-            : value < 0
-              ? 'negative'
-              : 'neutral',
+        outcome:
+          historyPartial || subscription === 0
+            ? 'neutral'
+            : value > 0
+              ? 'positive'
+              : value < 0
+                ? 'negative'
+                : 'neutral',
         reason: historyPartial ? 'Observed usage · Partial history' : null,
       };
     }
@@ -299,6 +297,7 @@ export function summarize(
       comparison,
       mode: billing.mode,
       monthly: billing.monthly,
+      needsBilling: billing.needsBilling,
       first: timestamps[0] ?? null,
       last: timestamps.at(-1) ?? null,
       days: new Set(timestamps.map((t) => t.slice(0, 10))).size,
@@ -311,43 +310,43 @@ export function summarize(
   const known = active.filter((p) => p.knownSubtotal !== null);
   const knownSubtotal = known.length ? known.reduce((n, p) => n + p.knownSubtotal , 0) : null;
   const apiEquivalent = count > 0 && pricedRecords === count ? knownSubtotal : null;
-  const subs = active.filter((p) => p.mode === 'SUBSCRIPTION');
-  let comparison = neutral(
-    active.some((p) => p.mode !== 'SUBSCRIPTION')
-      ? 'Subscription comparison unavailable'
-      : 'Partial history',
-  );
-  if (
-    subs.length &&
-    subs.length === active.length &&
-    subs.every((p) => p.comparison.value !== null)
-  ) {
-    const subscription = subs.reduce((n, p) => n + p.comparison.subscription , 0);
-    const value = apiEquivalent  - subscription;
-    let accumulated = 0,
-      breakEven                = null;
-    if (demo)
-      for (const d of daily) {
-        accumulated += (d.codex ?? 0) + (d.claude ?? 0);
-        if (accumulated >= subscription) {
-          breakEven = d.date;
-          break;
+  let comparison             = neutral('Expenses not set');
+  if (active.length && active.every((p) => p.comparison.paid != null)) {
+    const subscription = active.reduce((n, p) => n + p.comparison.subscription , 0),
+      apiSpend = active.reduce((n, p) => n + p.comparison.apiSpend , 0),
+      paid = subscription + apiSpend;
+    comparison = { ...neutral('Partial history', subscription), apiSpend, paid };
+    if (apiEquivalent !== null) {
+      const value = apiEquivalent - paid;
+      let accumulated = 0,
+        breakEven                = null;
+      if (demo)
+        for (const d of daily) {
+          accumulated += (d.codex ?? 0) + (d.claude ?? 0);
+          if (accumulated >= paid) {
+            breakEven = d.date;
+            break;
+          }
         }
-      }
-    comparison = {
-      subscription,
-      value,
-      roi: subscription > 0 ? apiEquivalent  / subscription : null,
-      breakEven,
-      outcome: demo ? (value > 0 ? 'positive' : value < 0 ? 'negative' : 'neutral') : 'neutral',
-      reason: demo ? null : 'Observed usage · Partial history',
-    };
-  } else if (
-    subs.length &&
-    subs.length === active.length &&
-    subs.every((p) => p.comparison.subscription !== null)
-  )
-    comparison.subscription = subs.reduce((n, p) => n + p.comparison.subscription , 0);
+      comparison = {
+        subscription,
+        apiSpend,
+        paid,
+        value,
+        roi: paid > 0 ? apiEquivalent / paid : null,
+        breakEven,
+        outcome:
+          demo && subscription > 0
+            ? value > 0
+              ? 'positive'
+              : value < 0
+                ? 'negative'
+                : 'neutral'
+            : 'neutral',
+        reason: demo ? null : 'Observed usage · Partial history',
+      };
+    }
+  }
   const confidence = active.length
     ? ['INCOMPLETE', 'LOW', 'MEDIUM', 'HIGH'].find((q) => active.some((p) => p.confidence === q)) 
     : 'NO DATA';

package/dist/packages/core/src/types.js

@@ -1,7 +1,13 @@
                                           
                                                                
-// API and MIXED remain readable for existing local settings.
                                                                                            
+                          
+                    
+                         
+                         
+                                                                                   
+                           
+ 
                               
              
                            
@@ -60,7 +66,9 @@
                   
                                      
                                   
-                                                                                                   
+                                     
+                                                                      
+                                                                     
  
 export const defaultSettings = ()           => ({
   onboarded: false,