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

package/src/statsClient.ts

@@ -0,0 +1,249 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * statsClient.ts
+ *
+ * Browser-safe HTTP client for the vendor-facing backend endpoints that back
+ * the dashboard: GET /stats, GET /transactions, and GET /apps/vendor/:addr.
+ *
+ * Types mirror the backend's response shapes so a dashboard implementation
+ * (this repo's zklicensing.com dashboard or a third-party one) doesn't have
+ * to re-derive them. New optional fields on the server should be added here
+ * as `?:` so older clients still typecheck against a newer backend.
+ */
+
+import type { CountryBreakdown } from './countryStats.js';
+import type { FiatRateSnapshot } from './licenseRecord.js';
+
+export type Tier = 'monthly' | 'yearly' | 'fiveYear' | 'perpetual';
+
+export type AppRecord = {
+  appId:                  string;
+  name:                   string;
+  description:            string;
+  longDescription?:       string;
+  category:               string;
+  website:                string;
+  // Absent on `status: 'not-deployed'` stub rows (returned by
+  // GET /apps/vendor/:addr?network=… for apps the vendor owns but hasn't
+  // deployed on the queried network). Present on every other projection.
+  zkAppAddress?:          string;
+  vendorAddress:          string;
+  priceMonthlyMina:       number;
+  priceYearlyMina:        number;
+  priceFiveYearMina:      number;
+  pricePerpetualMina:     number;
+  // Also absent on `status: 'not-deployed'` stub rows. See zkAppAddress note.
+  txHash?:                string;
+  verificationKeyHash?:   string;
+  logo?:                  string;
+  // Best favicon URL for the vendor's website, resolved server-side by the
+  // backend (parses `<link rel="icon">` tags on the website). Undefined until
+  // the vendor's next edit for grandfathered apps — clients should fall back
+  // to `${host}/favicon.ico` in that case.
+  iconUrl?:               string;
+  tags?:                  string[];
+  contactEmail?:          string;
+  supportEmail?:          string;
+  country?:               string;
+  status?:                'pending' | 'active' | 'inactive' | 'rejected' | 'not-deployed';
+  rejectionReason?:       string;
+  createdAt:              string;
+  approvedAt?:            string;
+  // Which network this record projection is scoped to. Present on responses
+  // from GET /apps?network=… and GET /apps/vendor/:addr?network=… — the backend
+  // stamps it so a dashboard rendering multiple projections doesn't have to
+  // track the query it made.
+  network?:               'devnet' | 'mainnet';
+  // Sibling networks this app is also deployed to. Empty or omitted when the
+  // app only exists on `network`. Dashboards use this to render "Also deploy
+  // to X →" / "Promote to X →" cross-origin CTAs.
+  alsoOnNetworks?:        ('devnet' | 'mainnet')[];
+  // Per-deployment sync bookkeeping, flattened from AppRecord.deployments[network]
+  // by the backend's network-scoped list handlers.
+  firstEventSlot?:        number;
+  lastSyncedSlot?:        number;
+  onChainVersion?:        number;
+  deploymentHistory?:     unknown[];
+  pendingEdit?:           Partial<AppRecord> & { editedAt: string };
+  // Append-only audit trail of status transitions. Optional so older backends
+  // that don't yet emit it still typecheck.
+  statusHistory?:         { status: string; at: string; actor: string; note?: string }[];
+  // Vendor legal / billing block — collected at registration for compliance
+  // (CRD Art. 6, e-Commerce Directive Art. 5) and reused in the vendor's
+  // tax-year CSV export. All optional here so older backends that don't yet
+  // return these fields still typecheck. `country` (top-level above) is the
+  // billing country and pairs with `billingAddress` — the address struct
+  // intentionally omits a country field to avoid drift.
+  legalName?:             string;
+  billingAddress?:        { line1: string; line2?: string; city: string; postalCode: string };
+  invoiceEmail?:          string;
+  vatId?:                 string;
+  companyRegistrationRegistry?: string;
+  companyRegistrationNumber?:   string;
+  // Consumer-facing policy URLs displayed in SDK buy/renew/refund flows
+  // before the buyer signs (CRD Art. 6(1)(g)/(h) pre-contract disclosures).
+  // Vendors set them at registration; may be omitted on legacy records that
+  // pre-date the field.
+  termsOfServiceUrl?:     string;
+  privacyPolicyUrl?:      string;
+  refundPolicyUrl?:       string;
+  // Registration fee (in MINA) actually paid at deploy time. Stamped from
+  // the backend's REGISTRATION_FEE constant when the record was created.
+  // Absent on pre-persistence records — consumers should fall back to the
+  // legacy flat 100 MINA fee for records without this field.
+  registrationFeeMina?:   number;
+};
+
+export type VendorStatsResponse = {
+  apps:               AppRecord[];
+  activeLicenses:     number;
+  totalLicenses:      number;
+  totalRevenueMina:   number;
+  pendingRevenueMina?: number;
+  // Vendor's post-fee share of refunded purchases, in MINA. Optional so older
+  // backends (pre-refund-tracking) still typecheck against this SDK.
+  refundedRevenueMina?: number;
+  renewalRate:        number | null;
+  monthlyRevenueMina: { month: string; mina: number }[];
+  licensesByTier?:    { monthly: number; yearly: number; fiveYear: number; perpetual: number };
+  deltas:             { revenuePct: number | null };
+  countryBreakdown?:  CountryBreakdown;
+};
+
+export type Transaction = {
+  type:      'purchase' | 'renewal' | 'release' | 'refund';
+  appId:     string;
+  appName:   string;
+  // Only populated on the admin __all response — vendor-scoped queries omit it
+  // since the caller already knows the vendor from the query itself.
+  vendorAddress?: string;
+  tier:      Tier | null;
+  amountMina: number;
+  txHash:    string;
+  date:      string; // ISO
+  // Buyer's ISO-3166 alpha-2 country at purchase (present on purchase rows and
+  // any downstream renewal/refund/release rows for the same record). Optional
+  // for pre-country-capture legacy rows.
+  buyerCountry?: string;
+  buyerZip?: string;        // US buyers only (state-level sales-tax attribution)
+  // VAT evidence: the country of the buyer's IP address at the sale (null:
+  // unknown or private address); absent when the keeper made no lookup.
+  ipCountry?: string | null;
+  // MINA→fiat rates snapshotted at the moment the underlying purchase/renewal
+  // confirmed — same fields as the receipt email. Missing on archive-replayed
+  // records and on rows created before the first successful CoinGecko fetch.
+  fiatSnapshot?: FiatRateSnapshot;
+  // Present when an AI agent gave the buyer's withdrawal waiver under a
+  // standing consent the buyer signed (Terms §7.8).
+  waiverGivenBy?: { agent: string; owner: string; statementSha256: string; issuedAt: string };
+};
+
+export type TransactionsResponse = { transactions: Transaction[] };
+
+export type VendorAppsResponse = { apps: AppRecord[] };
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+// Admin __all mode: pass `adminToken` and omit `vendorAddress` (or pass '__all').
+// Fetches aggregate over every registered app. Server gates with Bearer auth.
+// tzOffsetMinutes: signed minutes east of UTC — shifts tax-year cutovers on the
+// countryBreakdown so a UK vendor's 2026 doesn't include a Dec 31 23:30 PST
+// purchase. Default omitted → UTC bucketing preserved for existing callers.
+export async function fetchVendorStats(opts: {
+  keeperUrl:        string;
+  vendorAddress:    string;
+  network:          'devnet' | 'mainnet';
+  adminToken?:      string;
+  // Vendor dashboard-session bearer for the per-vendor read path. Mutually
+  // exclusive with adminToken (adminToken wins if both set — the '__all'
+  // path never has a session).
+  vendorSessionToken?: string;
+  tzOffsetMinutes?: number;
+  fetcher?:         typeof fetch;
+  signal?:          AbortSignal;
+}): Promise<VendorStatsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const tzQ = typeof opts.tzOffsetMinutes === 'number' ? `&tz=${opts.tzOffsetMinutes}` : '';
+  const resp = await fetcher(
+    `${baseUrl(opts.keeperUrl)}/stats?vendor=${encodeURIComponent(opts.vendorAddress)}&network=${opts.network}${tzQ}`,
+    { signal: opts.signal, headers },
+  );
+  if (!resp.ok) return null;
+  return await resp.json() as VendorStatsResponse;
+}
+
+export async function fetchTransactions(opts: {
+  keeperUrl:      string;
+  vendorAddress:  string;
+  network:        'devnet' | 'mainnet';
+  adminToken?:    string;
+  vendorSessionToken?: string;
+  // Rolling window in days. Default 30. Ignored when both `from` and `to` are
+  // set (explicit range wins) — used for the dashboard's "last N days" view.
+  days?:          number;
+  // Explicit inclusive-start / exclusive-end ISO dates (YYYY-MM-DD). When both
+  // are set the server filters to [from, to) instead of the rolling window.
+  // Used by the CSV export to fetch an exact tax year without over-fetching.
+  from?:          string;
+  to?:            string;
+  fetcher?:       typeof fetch;
+  signal?:        AbortSignal;
+}): Promise<TransactionsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const qs = new URLSearchParams({ vendor: opts.vendorAddress, network: opts.network });
+  if (opts.from && opts.to) {
+    qs.set('from', opts.from);
+    qs.set('to', opts.to);
+  } else {
+    qs.set('days', String(opts.days ?? 30));
+  }
+  const resp = await fetcher(
+    `${baseUrl(opts.keeperUrl)}/transactions?${qs.toString()}`,
+    { signal: opts.signal, headers },
+  );
+  if (!resp.ok) return null;
+  return await resp.json() as TransactionsResponse;
+}
+
+// Admin all-apps mode: pass `adminToken` and set `vendorAddress` to '__all'.
+// Hits GET /apps (no auth needed today; the admin overload just uses a
+// different URL) so vendors visiting their own dashboard still hit the same
+// per-vendor endpoint.
+export async function fetchVendorApps(opts: {
+  keeperUrl:      string;
+  vendorAddress:  string;
+  adminToken?:    string;
+  vendorSessionToken?: string;
+  // Network scope for the vendor projection. Required for the per-vendor path
+  // — the backend returns records projected against `deployments[network]` plus
+  // stub rows for apps the vendor owns but hasn't deployed on this network
+  // (status: 'not-deployed'). Omitted only in admin __all mode.
+  network?:       'devnet' | 'mainnet';
+  fetcher?:       typeof fetch;
+  signal?:        AbortSignal;
+}): Promise<VendorAppsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const isAdminAll = opts.adminToken && opts.vendorAddress === '__all';
+  if (!isAdminAll && !opts.network) {
+    throw new Error("fetchVendorApps: `network` is required for the per-vendor path");
+  }
+  const url = isAdminAll
+    ? `${baseUrl(opts.keeperUrl)}/apps?all=1`
+    : `${baseUrl(opts.keeperUrl)}/apps/vendor/${encodeURIComponent(opts.vendorAddress)}?network=${opts.network}`;
+  const resp = await fetcher(url, { signal: opts.signal, headers });
+  if (!resp.ok) return null;
+  return await resp.json() as VendorAppsResponse;
+}

package/src/successorChain.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * successorChain.ts — the current contract of a lineage (licensing app
+ * generations, permit registry generations), from chain state alone.
+ *
+ * A retired contract names its successor in its state (its retirement,
+ * which the vendor or authority signed, stored it), and the successor's
+ * initialization checked on chain that the predecessor named it. Each hop
+ * here also checks the successor runs a published release and started
+ * from the predecessor's frozen root. A successor not deployed yet
+ * (between retirement and deployment, e.g. across a hard fork) leaves the
+ * retired contract current.
+ */
+
+import { Field, PublicKey } from 'o1js';
+import { readZkappAccount, type ZkappAccount } from './chainHead.js';
+import { LICENSING_APP_STATE } from './contractInterface.js';
+import { PERMIT_REGISTRY_STATE } from './permitInterface.js';
+
+/** Where a contract kind keeps its lineage in state. */
+export type LineageLayout = {
+  /** Contract name for error messages. */
+  name: string;
+  /** State index and value that mark the contract retired. */
+  retiredAt: number;
+  retiredValue: string;
+  /** The tree root a retirement freezes, and where a successor keeps the root it started from. */
+  rootAt: number;
+  ancestorsRootAt: number;
+  successorXAt: number;
+  successorIsOddAt: number;
+};
+
+export const LICENSING_LINEAGE: LineageLayout = {
+  name: 'LicensingApp',
+  retiredAt: LICENSING_APP_STATE.retired, retiredValue: '1',
+  rootAt: LICENSING_APP_STATE.licensesRoot, ancestorsRootAt: LICENSING_APP_STATE.ancestorsRoot,
+  successorXAt: LICENSING_APP_STATE.successorX, successorIsOddAt: LICENSING_APP_STATE.successorIsOdd,
+};
+
+/** A retired registry's authority-keys hash is RETIRED_KEYS_HASH (1). */
+export const PERMIT_LINEAGE: LineageLayout = {
+  name: 'PermitRegistry',
+  retiredAt: PERMIT_REGISTRY_STATE.authorityKeysHash, retiredValue: '1',
+  rootAt: PERMIT_REGISTRY_STATE.permitsRoot, ancestorsRootAt: PERMIT_REGISTRY_STATE.ancestorsRoot,
+  successorXAt: PERMIT_REGISTRY_STATE.successorX, successorIsOddAt: PERMIT_REGISTRY_STATE.successorIsOdd,
+};
+
+export const MAX_LINEAGE_HOPS = 32;
+
+/**
+ * Follows `start`'s successors to the current contract. Returns it with
+ * its account (`found: false` when `start` isn't on chain). Throws when a
+ * named successor is deployed but isn't a published release (`canonicalVks`)
+ * or didn't start from the frozen root.
+ */
+export async function currentOnChain(args: {
+  start: string;
+  layout: LineageLayout;
+  canonicalVks: readonly string[];
+  graphqlUrl: string;
+  fetcher?: typeof fetch;
+}): Promise<{ address: string; account: ZkappAccount }> {
+  const { layout: l } = args;
+  const read = (address: string) => readZkappAccount({ address, graphqlUrl: args.graphqlUrl, fetcher: args.fetcher });
+  let address = args.start;
+  let account = await read(address);
+  for (let hop = 0; hop < MAX_LINEAGE_HOPS; hop++) {
+    const st = account.appState;
+    if (!account.found || !st || st[l.retiredAt] !== l.retiredValue) return { address, account };
+    let next: string;
+    try { next = PublicKey.fromFields([Field(st[l.successorXAt]), Field(st[l.successorIsOddAt])]).toBase58(); } catch { return { address, account }; }
+    const succ = await read(next);
+    if (!succ.found || !succ.appState) return { address, account }; // not deployed yet
+    if (!succ.vkHash || !args.canonicalVks.includes(succ.vkHash)) {
+      throw new Error(`The successor ${next} of ${address} is not a published ${l.name} release`);
+    }
+    if (succ.appState[l.ancestorsRootAt] !== st[l.rootAt]) {
+      throw new Error(`The successor ${next} of ${address} did not start from its frozen root`);
+    }
+    address = next;
+    account = succ;
+  }
+  throw new Error(`${l.name} lineage of ${args.start} is longer than ${MAX_LINEAGE_HOPS} generations`);
+}

package/src/taxId.ts

@@ -0,0 +1,227 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * taxId.ts — `zklicensing/tax-id`
+ *
+ * Vendor tax identifiers: every vendor must have one. This module checks
+ * the format (and, where the scheme has one, the check digit) for the
+ * vendor's country, offline. EU VAT numbers are additionally looked up in
+ * VIES by the keeper; this module only says which numbers go to VIES.
+ *
+ *   checkTaxId('FI', 'FI 1234 5678')  → { ok, scheme: 'eu-vat', normalized: 'FI12345678', vies: { countryCode: 'FI', number: '12345678' } }
+ *   checkTaxId('NO', '974 760 673 MVA') → { ok, scheme: 'no-mva', normalized: 'NO974760673MVA' }
+ *   checkTaxId('BR', '…')              → { ok, scheme: 'other', review: true }   (no known format: admin review)
+ *
+ * Pure and browser-safe: the site uses it for live form feedback.
+ */
+
+export type TaxIdScheme =
+  | 'eu-vat' | 'gb-vat' | 'no-mva' | 'ch-uid' | 'au-abn' | 'nz-gst' | 'ca-bn'
+  | 'us-ein' | 'jp-invoice' | 'in-gstin' | 'sg-gst' | 'other';
+
+export type TaxIdResult =
+  | {
+      ok: true;
+      scheme: TaxIdScheme;
+      /** Canonical form to store and show. */
+      normalized: string;
+      /** EU numbers only: what to look up in VIES (Greece is `EL`, Northern Ireland `XI`). */
+      vies?: { countryCode: string; number: string };
+      /** True when the country has no known format: accepted for an admin to review. */
+      review?: boolean;
+    }
+  | { ok: false; scheme: TaxIdScheme; error: string; example?: string };
+
+/** EU member states, by ISO 3166-1 alpha-2 country code, with their VAT prefix and number format. */
+const EU: Record<string, { prefix: string; re: RegExp; example: string }> = {
+  AT: { prefix: 'AT', re: /^U\d{8}$/, example: 'ATU12345678' },
+  BE: { prefix: 'BE', re: /^[01]\d{9}$/, example: 'BE0123456789' },
+  BG: { prefix: 'BG', re: /^\d{9,10}$/, example: 'BG123456789' },
+  CY: { prefix: 'CY', re: /^\d{8}[A-Z]$/, example: 'CY12345678X' },
+  CZ: { prefix: 'CZ', re: /^\d{8,10}$/, example: 'CZ12345678' },
+  DE: { prefix: 'DE', re: /^\d{9}$/, example: 'DE123456789' },
+  DK: { prefix: 'DK', re: /^\d{8}$/, example: 'DK12345678' },
+  EE: { prefix: 'EE', re: /^\d{9}$/, example: 'EE123456789' },
+  GR: { prefix: 'EL', re: /^\d{9}$/, example: 'EL123456789' },
+  ES: { prefix: 'ES', re: /^[A-Z0-9]\d{7}[A-Z0-9]$/, example: 'ESX1234567X' },
+  FI: { prefix: 'FI', re: /^\d{8}$/, example: 'FI12345678' },
+  FR: { prefix: 'FR', re: /^[A-HJ-NP-Z0-9]{2}\d{9}$/, example: 'FRXX123456789' },
+  HR: { prefix: 'HR', re: /^\d{11}$/, example: 'HR12345678901' },
+  HU: { prefix: 'HU', re: /^\d{8}$/, example: 'HU12345678' },
+  IE: { prefix: 'IE', re: /^(\d{7}[A-W][A-I]?|\d[A-Z+*]\d{5}[A-W])$/, example: 'IE1234567WA' },
+  IT: { prefix: 'IT', re: /^\d{11}$/, example: 'IT12345678901' },
+  LT: { prefix: 'LT', re: /^(\d{9}|\d{12})$/, example: 'LT123456789' },
+  LU: { prefix: 'LU', re: /^\d{8}$/, example: 'LU12345678' },
+  LV: { prefix: 'LV', re: /^\d{11}$/, example: 'LV12345678901' },
+  MT: { prefix: 'MT', re: /^\d{8}$/, example: 'MT12345678' },
+  NL: { prefix: 'NL', re: /^\d{9}B\d{2}$/, example: 'NL123456789B01' },
+  PL: { prefix: 'PL', re: /^\d{10}$/, example: 'PL1234567890' },
+  PT: { prefix: 'PT', re: /^\d{9}$/, example: 'PT123456789' },
+  RO: { prefix: 'RO', re: /^\d{2,10}$/, example: 'RO1234567890' },
+  SE: { prefix: 'SE', re: /^\d{12}$/, example: 'SE123456789012' },
+  SI: { prefix: 'SI', re: /^\d{8}$/, example: 'SI12345678' },
+  SK: { prefix: 'SK', re: /^\d{10}$/, example: 'SK1234567890' },
+};
+
+/** True for the 27 EU member states (ISO codes; Greece is GR here). */
+export function isEuCountry(country: string): boolean {
+  return Object.prototype.hasOwnProperty.call(EU, String(country).toUpperCase());
+}
+
+/** An example of the expected format for `country`, for form placeholders. */
+export function taxIdExample(country: string): string {
+  const c = String(country).toUpperCase();
+  if (isEuCountry(c)) return EU[c].example;
+  return ({
+    GB: 'GB123456789', NO: 'NO123456789MVA', CH: 'CHE-123.456.789 MWST', LI: 'CHE-123.456.789 MWST',
+    AU: '12 345 678 901', NZ: '123-456-789', CA: '123456789RT0001', US: '12-3456789',
+    JP: 'T1234567890123', IN: '22AAAAA0000A1Z5', SG: 'M2-1234567-8',
+  } as Record<string, string>)[c] ?? 'Your national tax or VAT number';
+}
+
+const digits = (s: string) => [...s].map(Number);
+
+function gbCheck(n: string): boolean {
+  const x = digits(n.slice(0, 9));
+  const sum = x.slice(0, 7).reduce((a, v, i) => a + v * (8 - i), 0) + Number(n.slice(7, 9));
+  return sum % 97 === 0 || (sum + 55) % 97 === 0;
+}
+
+/** Weighted mod-11 check used by Norway (org. number) and Switzerland (UID). */
+function mod11(n: string, weights: number[]): boolean {
+  const x = digits(n);
+  let c = 11 - (weights.reduce((a, w, i) => a + w * x[i], 0) % 11);
+  if (c === 11) c = 0;
+  return c !== 10 && c === x[weights.length];
+}
+
+function abnCheck(n: string): boolean {
+  const x = digits(n);
+  x[0] -= 1;
+  return [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19].reduce((a, w, i) => a + w * x[i], 0) % 89 === 0;
+}
+
+function nzCheck(raw: string): boolean {
+  const n = raw.padStart(9, '0');
+  const v = Number(n);
+  if (v < 10_000_000 || v > 150_000_000) return false;
+  const x = digits(n);
+  const calc = (w: number[]) => { const r = w.reduce((a, k, i) => a + k * x[i], 0) % 11; return r === 0 ? 0 : 11 - r; };
+  let c = calc([3, 2, 7, 6, 5, 4, 3, 2]);
+  if (c === 10) c = calc([7, 4, 3, 2, 5, 2, 7, 6]);
+  return c !== 10 && c === x[8];
+}
+
+function luhn(n: string): boolean {
+  let s = 0;
+  [...n].reverse().forEach((ch, i) => { let v = Number(ch); if (i % 2) { v *= 2; if (v > 9) v -= 9; } s += v; });
+  return s % 10 === 0;
+}
+
+const B36 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+function gstinCheck(g: string): boolean {
+  let s = 0;
+  for (let i = 0; i < 14; i++) {
+    const p = B36.indexOf(g[i]) * (i % 2 === 0 ? 1 : 2);
+    s += Math.floor(p / 36) + (p % 36);
+  }
+  return B36[(36 - (s % 36)) % 36] === g[14];
+}
+
+// IRS campus prefixes never issued for an EIN.
+const EIN_INVALID_PREFIXES = new Set(['00', '07', '08', '09', '17', '18', '19', '28', '29', '49', '69', '70', '78', '79', '89', '96', '97']);
+
+/**
+ * Checks `taxId` for a vendor in `country` (ISO 3166-1 alpha-2): the format
+ * and, where the scheme has one, the check digit. Spaces, dots and dashes
+ * are ignored; letters are upper-cased.
+ */
+export function checkTaxId(country: string, taxId: string): TaxIdResult {
+  const c = String(country ?? '').trim().toUpperCase();
+  const raw = String(taxId ?? '').trim().toUpperCase();
+  const compact = raw.replace(/[\s.\-]/g, '');
+  const fail = (scheme: TaxIdScheme, error: string): TaxIdResult => ({ ok: false, scheme, error, example: taxIdExample(c) });
+  if (!compact) return fail('other', 'A tax ID is required');
+  if (compact.length > 30) return fail('other', 'The tax ID is too long');
+
+  if (isEuCountry(c)) {
+    const { prefix, re } = EU[c];
+    // The country prefix is optional on input (some numbers, e.g. Spanish,
+    // may themselves start with a letter, so test the body as given too).
+    const body = compact.startsWith(prefix) && re.test(compact.slice(prefix.length)) ? compact.slice(prefix.length) : compact;
+    if (!re.test(body)) {
+      return fail('eu-vat', /^[A-Z]{2}/.test(compact) && !compact.startsWith(prefix)
+        ? `A VAT number for ${c} starts with ${prefix}` : `Not a valid ${c} VAT number`);
+    }
+    return { ok: true, scheme: 'eu-vat', normalized: prefix + body, vies: { countryCode: prefix, number: body } };
+  }
+
+  switch (c) {
+    case 'GB': {
+      const b = compact.replace(/^GB/, '');
+      if (/^(GD|HA)\d{3}$/.test(b)) return { ok: true, scheme: 'gb-vat', normalized: 'GB' + b };
+      if (!/^(\d{9}|\d{12})$/.test(b)) return fail('gb-vat', 'A UK VAT number is GB and 9 or 12 digits');
+      if (!gbCheck(b)) return fail('gb-vat', 'The UK VAT number\'s check digits are wrong');
+      return { ok: true, scheme: 'gb-vat', normalized: 'GB' + b };
+    }
+    case 'NO': {
+      const b = compact.replace(/^NO/, '').replace(/MVA$/, '');
+      if (!/^\d{9}$/.test(b)) return fail('no-mva', 'A Norwegian VAT number is 9 digits followed by MVA');
+      if (!mod11(b, [3, 2, 7, 6, 5, 4, 3, 2])) return fail('no-mva', 'The organisation number\'s check digit is wrong');
+      return { ok: true, scheme: 'no-mva', normalized: `NO${b}MVA` };
+    }
+    case 'CH': case 'LI': {
+      const m = /^CHE(\d{9})(MWST|TVA|IVA|MVA)?$/.exec(compact);
+      if (!m) return fail('ch-uid', 'A Swiss VAT number is CHE-123.456.789 MWST');
+      if (!mod11(m[1], [5, 4, 3, 2, 7, 6, 5, 4])) return fail('ch-uid', 'The UID\'s check digit is wrong');
+      const d = m[1];
+      return { ok: true, scheme: 'ch-uid', normalized: `CHE-${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6)} ${m[2] ?? 'MWST'}` };
+    }
+    case 'AU': {
+      const b = compact.replace(/^ABN/, '');
+      if (!/^\d{11}$/.test(b)) return fail('au-abn', 'An ABN is 11 digits');
+      if (!abnCheck(b)) return fail('au-abn', 'The ABN\'s check digits are wrong');
+      return { ok: true, scheme: 'au-abn', normalized: `${b.slice(0, 2)} ${b.slice(2, 5)} ${b.slice(5, 8)} ${b.slice(8)}` };
+    }
+    case 'NZ': {
+      if (!/^\d{8,9}$/.test(compact)) return fail('nz-gst', 'A New Zealand GST number is 8 or 9 digits');
+      if (!nzCheck(compact)) return fail('nz-gst', 'The GST number\'s check digit is wrong');
+      const n = compact.padStart(9, '0');
+      return { ok: true, scheme: 'nz-gst', normalized: `${n.slice(0, 3)}-${n.slice(3, 6)}-${n.slice(6)}` };
+    }
+    case 'CA': {
+      const m = /^(\d{9})(RT\d{4})?$/.exec(compact);
+      if (!m) return fail('ca-bn', 'A Canadian business number is 9 digits, optionally followed by RT0001');
+      if (!luhn(m[1])) return fail('ca-bn', 'The business number\'s check digit is wrong');
+      return { ok: true, scheme: 'ca-bn', normalized: m[1] + (m[2] ?? '') };
+    }
+    case 'US': {
+      if (!/^\d{9}$/.test(compact)) return fail('us-ein', 'An EIN is 9 digits (12-3456789)');
+      if (EIN_INVALID_PREFIXES.has(compact.slice(0, 2))) return fail('us-ein', 'No EIN starts with ' + compact.slice(0, 2));
+      return { ok: true, scheme: 'us-ein', normalized: `${compact.slice(0, 2)}-${compact.slice(2)}` };
+    }
+    case 'JP': {
+      // Format only: T and the 13-digit corporate number.
+      const b = compact.replace(/^T/, '');
+      if (!/^\d{13}$/.test(b)) return fail('jp-invoice', 'A Japanese registration number is T and 13 digits');
+      return { ok: true, scheme: 'jp-invoice', normalized: 'T' + b };
+    }
+    case 'IN': {
+      if (!/^\d{2}[A-Z]{5}\d{4}[A-Z][1-9A-Z]Z[0-9A-Z]$/.test(compact)) return fail('in-gstin', 'A GSTIN is 15 characters, like 22AAAAA0000A1Z5');
+      if (!gstinCheck(compact)) return fail('in-gstin', 'The GSTIN\'s check character is wrong');
+      return { ok: true, scheme: 'in-gstin', normalized: compact };
+    }
+    case 'SG': {
+      if (!/^(M[2-9A-Z]\d{7}[0-9A-Z]|\d{8,9}[A-Z]|[TSR]\d{2}[A-Z]{2}\d{4}[A-Z])$/.test(compact)) {
+        return fail('sg-gst', 'Not a Singapore GST registration number');
+      }
+      return { ok: true, scheme: 'sg-gst', normalized: compact };
+    }
+    default: {
+      // No known format: accept sensible input for an admin to review.
+      if (!/^[A-Z0-9]{4,30}$/.test(compact)) return fail('other', 'Use letters and digits only');
+      return { ok: true, scheme: 'other', normalized: raw.replace(/\s+/g, ' '), review: true };
+    }
+  }
+}