zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/countryStats.ts

@@ -0,0 +1,200 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * countryStats.ts
+ *
+ * Buyer-country breakdown of a vendor's revenue, bucketed by UTC calendar year.
+ * Structured for tax reporting: one row per (year, appId, countryCode) with
+ * license count + the vendor's cut in MINA. Both the backend (source of
+ * truth for /stats) and the dashboard UI import from here so the numbers can
+ * never drift between them.
+ *
+ * Purchases attribute to the year the buyer confirmed on-chain (LicenseRecord
+ * `createdAt` ISO timestamp). Legacy records that predate `createdAt` fall
+ * back to slot-derived time. Renewals attribute to the renewal year via
+ * `renewals[i].slot → time`. Refunded purchases contribute zero revenue but
+ * still count the license (a purchase happened even if the money was
+ * returned) — remove `count` from refunded rows client-side if you want a
+ * strictly net view.
+ *
+ * Browser-safe: pure computation, no fs, no fetch.
+ */
+
+import { vendorShareNano, type LicenseRecord } from './licenseRecord.js';
+import { standardVatRate, vatIncludedNano } from './vatRates.js';
+import { zipToState } from './zipToState.js';
+
+export { zipToState } from './zipToState.js';
+
+// LicensingApp charges a 2 % platform fee (200 basis points); the vendor
+// receives the remaining 9 800 bps. Keep this in sync with the on-chain
+// constant in LicensingApp.
+
+// 90 s/slot post-Mesa. Used only for slot→time fallback attribution.
+const SLOT_DURATION_MS = 90_000;
+
+export type CountryBucket = {
+  count: number;         // licenses purchased by buyers from this country (renewals don't bump)
+  revenueMina: number;   // vendor cut in MINA — purchase + renewals combined
+  // What buyers paid (the VAT-inclusive price), before the platform fee —
+  // the VAT base. Refunded purchases count zero, as for revenue.
+  grossMina: number;
+  // Estimated VAT included in grossMina, at the buyer country's standard
+  // rate on each sale's date (zklicensing/vat). Absent for countries
+  // without VAT in the table. An estimate for consumer sales, not tax
+  // advice: reverse-charged business sales and thresholds aren't applied.
+  estimatedVatMina?: number;
+  // The distinct standard rates (percent) applied, sorted; more than one
+  // when the rate changed during the year.
+  vatRates?: number[];
+  // State sub-buckets — populated only for US buyers, derived from
+  // `buyerZip` via zipToState. States are the jurisdictional unit that US
+  // sales-tax filings care about; the raw ZIP stays on the LicenseRecord
+  // for audit trail but isn't rolled up here. Missing entirely on non-US
+  // rows; may be missing on US rows for legacy records that predate ZIP
+  // capture or whose ZIP prefix doesn't resolve to a state.
+  states?: Record<string, { count: number; revenueMina: number; grossMina: number }>;
+};
+export type CountryYearBreakdown = {
+  aggregate: Record<string, CountryBucket>;                       // keyed by ISO-alpha-2 (or '??' when missing)
+  byApp:     Record<string, Record<string, CountryBucket>>;       // appId → country → bucket
+};
+export type CountryBreakdown = {
+  years:  number[];                              // UTC calendar years with activity, most-recent first
+  byYear: Record<number, CountryYearBreakdown>;
+};
+
+// tzOffsetMinutes: signed minutes east of UTC (e.g. +60 for CET, -480 for PST).
+// Purchase/renewal timestamps are shifted by this offset before extracting the
+// calendar year, so the "tax year" cut-over aligns with the operator's local
+// clock instead of hardcoded UTC. Defaults to 0 (UTC) for callers who don't
+// pass it — preserves the pre-tz behavior.
+export function computeCountryBreakdown(
+  apps: { appId: string; zkAppAddress: string }[],
+  records: LicenseRecord[],
+  currentSlot: number,
+  nowMs: number,
+  tzOffsetMinutes: number = 0,
+): CountryBreakdown {
+  const appByAddress = new Map(apps.map(a => [a.zkAppAddress, a.appId] as const));
+  const byYear: Record<number, CountryYearBreakdown> = {};
+  const yearSet = new Set<number>();
+  const tzShiftMs = tzOffsetMinutes * 60_000;
+
+  const ensureYear = (year: number): CountryYearBreakdown => {
+    let yb = byYear[year];
+    if (!yb) {
+      yb = { aggregate: {}, byApp: {} };
+      byYear[year] = yb;
+      yearSet.add(year);
+    }
+    return yb;
+  };
+  const ensureAppBucket = (yb: CountryYearBreakdown, appId: string): Record<string, CountryBucket> => {
+    let ab = yb.byApp[appId];
+    if (!ab) {
+      ab = {};
+      yb.byApp[appId] = ab;
+    }
+    return ab;
+  };
+  const add = (
+    bucket: Record<string, CountryBucket>,
+    code: string,
+    count: number,
+    revenueNano: bigint,
+    grossNano: bigint,
+    saleMs: number | null,
+    state?: string,
+  ): void => {
+    let b = bucket[code];
+    if (!b) {
+      b = { count: 0, revenueMina: 0, grossMina: 0 };
+      bucket[code] = b;
+    }
+    b.count += count;
+    b.revenueMina += Number(revenueNano) / 1e9;
+    b.grossMina += Number(grossNano) / 1e9;
+    // VAT included at the rate in force on the sale date.
+    const rate = code !== '??' && saleMs !== null ? standardVatRate(code, saleMs) : null;
+    if (rate !== null) {
+      b.estimatedVatMina = (b.estimatedVatMina ?? 0) + Number(vatIncludedNano(grossNano, rate).vatNano) / 1e9;
+      if (grossNano > 0n) {
+        const rates = (b.vatRates ??= []);
+        if (!rates.includes(rate)) { rates.push(rate); rates.sort((x, y) => x - y); }
+      }
+    }
+    // State sub-bucket only for US rows whose ZIP resolved to a state.
+    // Non-US or unresolvable rows just add to the country total.
+    if (code === 'US' && state) {
+      const states = b.states ?? (b.states = {});
+      let sb = states[state];
+      if (!sb) {
+        sb = { count: 0, revenueMina: 0, grossMina: 0 };
+        states[state] = sb;
+      }
+      sb.count += count;
+      sb.revenueMina += Number(revenueNano) / 1e9;
+      sb.grossMina += Number(grossNano) / 1e9;
+    }
+  };
+  const slotToMs = (slot: number): number | null => {
+    if (currentSlot <= 0) return null;
+    const ms = nowMs - (currentSlot - slot) * SLOT_DURATION_MS;
+    return Number.isFinite(ms) ? ms : null;
+  };
+  const msToYear = (ms: number | null): number | null => {
+    if (ms === null) return null;
+    const y = new Date(ms + tzShiftMs).getUTCFullYear();
+    return Number.isFinite(y) ? y : null;
+  };
+
+  for (const r of records) {
+    const appId = appByAddress.get(r.zkAppAddress);
+    if (!appId) continue;
+    const country = r.buyerCountry && /^[A-Z]{2}$/.test(r.buyerCountry) ? r.buyerCountry : '??';
+    // Only US rows carry a meaningful ZIP for sales-tax purposes; derive
+    // the state jurisdiction here and let `add` roll it up. Non-US ZIPs
+    // and unresolvable prefixes fall through to country-total only.
+    const state = country === 'US' && r.buyerZip ? zipToState(r.buyerZip) : undefined;
+
+    // Purchase — attribute to the year of confirm-on-chain (createdAt).
+    // Fallback: slot-derived time for legacy records that lack createdAt.
+    let purchaseMs: number | null = null;
+    if (r.createdAt) {
+      const t = new Date(r.createdAt).getTime();
+      if (Number.isFinite(t)) purchaseMs = t;
+    }
+    if (purchaseMs === null && r.purchaseSlot > 0) {
+      purchaseMs = slotToMs(r.purchaseSlot);
+    }
+    const purchaseYear = msToYear(purchaseMs);
+    if (purchaseYear !== null) {
+      const yb = ensureYear(purchaseYear);
+      const ab = ensureAppBucket(yb, appId);
+      const purchaseGross = (!r.refunded && r.purchaseAmount && r.purchaseAmount !== '0') ? BigInt(r.purchaseAmount) : 0n;
+      const purchaseCut = purchaseGross > 0n ? vendorShareNano(purchaseGross) : 0n;
+      add(ab, country, 1, purchaseCut, purchaseGross, purchaseMs, state);
+      add(yb.aggregate, country, 1, purchaseCut, purchaseGross, purchaseMs, state);
+    }
+
+    // Renewals — revenue only (no license count), attributed to renewal year.
+    for (const rn of r.renewals ?? []) {
+      const ms = slotToMs(rn.slot);
+      const y = msToYear(ms);
+      if (y === null) continue;
+      const yb = ensureYear(y);
+      const ab = ensureAppBucket(yb, appId);
+      const gross = BigInt(rn.amount);
+      const cut = vendorShareNano(gross);
+      add(ab, country, 0, cut, gross, ms, state);
+      add(yb.aggregate, country, 0, cut, gross, ms, state);
+    }
+  }
+
+  return {
+    years: Array.from(yearSet).sort((a, b) => b - a),
+    byYear,
+  };
+}