@softure-ai/billing 0.0.0-stage → 0.1.5

package/migrations/0004_create_requests_and_grants.sql

@@ -0,0 +1,58 @@
+-- Manual payments in the admin page: the invoice requests buyers send (listed until the admin
+-- grants or dismisses them) and the plans the admin grants by hand, each with what it added, so a
+-- mistaken grant is revoked by taking back only that. Provider payments stay in billing.payments.
+-- Invoice details are personal data kept only while a request is open: the closing update clears
+-- them (payment_requests_details_while_open).
+-- Rollback: DROP TABLE billing.manual_grants; DROP TABLE billing.payment_requests; then
+--   DELETE FROM softure.migrations WHERE module = 'billing' AND version = 4;
+CREATE TABLE payment_requests (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id uuid NOT NULL REFERENCES auth.users (id) ON DELETE CASCADE,
+  plan_id text NOT NULL CHECK (length(plan_id) BETWEEN 1 AND 64),
+  -- The invoice details as the buyer typed them (trimmed); NULL once the request is closed, or
+  -- when the provider collects its own.
+  invoice_name text CHECK (length(invoice_name) BETWEEN 1 AND 200),
+  invoice_tax_id text CHECK (length(invoice_tax_id) BETWEEN 1 AND 32),
+  invoice_address text CHECK (length(invoice_address) BETWEEN 1 AND 500),
+  status text NOT NULL CHECK (status IN ('open', 'granted', 'dismissed')),
+  requested_at timestamptz NOT NULL,
+  closed_at timestamptz,
+  CONSTRAINT payment_requests_closed_at_with_status CHECK ((status = 'open') = (closed_at IS NULL)),
+  CONSTRAINT payment_requests_closed_after_requested CHECK (closed_at IS NULL OR closed_at >= requested_at),
+  CONSTRAINT payment_requests_name_with_address CHECK ((invoice_name IS NULL) = (invoice_address IS NULL)),
+  CONSTRAINT payment_requests_tax_id_with_name CHECK (invoice_tax_id IS NULL OR invoice_name IS NOT NULL),
+  CONSTRAINT payment_requests_details_while_open CHECK (status = 'open' OR invoice_name IS NULL)
+);
+
+-- One open request per account and plan: asking again refreshes it instead of adding a row.
+CREATE UNIQUE INDEX payment_requests_one_open ON payment_requests (user_id, plan_id) WHERE status = 'open';
+CREATE INDEX payment_requests_open_by_age ON payment_requests (requested_at) WHERE status = 'open';
+
+CREATE TABLE manual_grants (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id uuid NOT NULL REFERENCES auth.users (id) ON DELETE CASCADE,
+  plan_id text NOT NULL CHECK (length(plan_id) BETWEEN 1 AND 64),
+  -- The request the grant answered; NULL for a grant typed in by email.
+  request_id uuid UNIQUE REFERENCES payment_requests (id) ON DELETE SET NULL,
+  -- The admins who granted and revoked it; NULL once their account is gone.
+  granted_by uuid REFERENCES auth.users (id) ON DELETE SET NULL,
+  granted_at timestamptz NOT NULL,
+  -- What the grant added, as billing.payments records it (0003).
+  grant_kind text NOT NULL CHECK (grant_kind IN ('period', 'lifetime')),
+  granted_from timestamptz,
+  granted_until timestamptz,
+  status text NOT NULL CHECK (status IN ('active', 'revoked')),
+  revoked_at timestamptz,
+  revoked_by uuid REFERENCES auth.users (id) ON DELETE SET NULL,
+  CONSTRAINT manual_grants_grant_shape CHECK (
+    CASE grant_kind
+      WHEN 'period' THEN granted_from IS NOT NULL AND granted_until IS NOT NULL AND granted_until > granted_from
+      ELSE granted_from IS NULL AND granted_until IS NULL
+    END
+  ),
+  CONSTRAINT manual_grants_revoked_at_with_status CHECK ((status = 'revoked') = (revoked_at IS NOT NULL)),
+  CONSTRAINT manual_grants_revoked_by_when_revoked CHECK (revoked_by IS NULL OR status = 'revoked'),
+  CONSTRAINT manual_grants_revoked_after_granted CHECK (revoked_at IS NULL OR revoked_at >= granted_at)
+);
+
+CREATE INDEX manual_grants_user_id ON manual_grants (user_id);

package/migrations/0005_record_refunded_amounts.sql

@@ -0,0 +1,18 @@
+-- Partial refunds: how much of each provider payment was refunded so far, in the currency's minor
+-- unit, as the provider reports it (Stripe's cumulative `amount_refunded`). A delivery whose amount
+-- is not above the stored one changes nothing, so repeated and stale deliveries are harmless. A
+-- payment stays `paid` while part of it is refunded and turns `refunded` when all of it is.
+-- Rollback: ALTER TABLE billing.payments DROP CONSTRAINT payments_refunded_amount_by_status;
+--   ALTER TABLE billing.payments DROP COLUMN refunded_amount; then
+--   DELETE FROM softure.migrations WHERE module = 'billing' AND version = 5;
+ALTER TABLE payments ADD COLUMN refunded_amount bigint NOT NULL DEFAULT 0;
+
+-- Payments refunded before this migration were refunded in full.
+UPDATE payments SET refunded_amount = amount WHERE status = 'refunded';
+
+ALTER TABLE payments ADD CONSTRAINT payments_refunded_amount_by_status CHECK (
+  CASE status
+    WHEN 'refunded' THEN refunded_amount = amount
+    ELSE refunded_amount >= 0 AND (refunded_amount < amount OR amount = 0)
+  END
+);

package/migrations/0006_record_request_handover_and_prices.sql

@@ -0,0 +1,38 @@
+-- Invoice requests are stored before the provider hands them to the owner, and the owner hears of
+-- an open request once: handed_over_at is set by a conditional update that claims the hand-over
+-- and cleared again when it fails, so the next ask retries. Requests and manual grants record the
+-- plan's price (what was quoted, what was granted). Open requests nobody asks again for expire
+-- (status 'expired', details cleared like any closed request). Invoice details refuse control
+-- characters, so a name cannot add lines to the owner's mail; the CHECKs are NOT VALID, so older
+-- rows are not rewritten, while every insert and update is checked.
+-- Rollback: UPDATE billing.payment_requests SET status = 'dismissed' WHERE status = 'expired';
+--   ALTER TABLE billing.payment_requests DROP CONSTRAINT payment_requests_status_check, then
+--   ADD CONSTRAINT payment_requests_status_check CHECK (status IN ('open', 'granted', 'dismissed'));
+--   ALTER TABLE billing.payment_requests DROP CONSTRAINT payment_requests_invoice_name_printable,
+--   DROP CONSTRAINT payment_requests_invoice_tax_id_printable, DROP CONSTRAINT payment_requests_invoice_address_printable,
+--   DROP CONSTRAINT payment_requests_price_pair, DROP COLUMN handed_over_at, DROP COLUMN amount, DROP COLUMN currency;
+--   ALTER TABLE billing.manual_grants DROP CONSTRAINT manual_grants_price_pair, DROP COLUMN amount, DROP COLUMN currency;
+--   then DELETE FROM softure.migrations WHERE module = 'billing' AND version = 6;
+ALTER TABLE payment_requests ADD COLUMN handed_over_at timestamptz;
+
+-- Every open request stored before this migration was stored after its hand-over succeeded.
+UPDATE payment_requests SET handed_over_at = requested_at WHERE status = 'open';
+
+-- The plan's price when the request was asked for or last refreshed, in the currency's minor
+-- unit; NULL on rows stored before this migration (the config is not in a migration's reach).
+ALTER TABLE payment_requests ADD COLUMN amount bigint CHECK (amount >= 0);
+ALTER TABLE payment_requests ADD COLUMN currency text CHECK (currency ~ '^[A-Z]{3}$');
+ALTER TABLE payment_requests ADD CONSTRAINT payment_requests_price_pair CHECK ((amount IS NULL) = (currency IS NULL));
+
+-- What the grant was for: the price its request quoted, else the plan's price when granted.
+ALTER TABLE manual_grants ADD COLUMN amount bigint CHECK (amount >= 0);
+ALTER TABLE manual_grants ADD COLUMN currency text CHECK (currency ~ '^[A-Z]{3}$');
+ALTER TABLE manual_grants ADD CONSTRAINT manual_grants_price_pair CHECK ((amount IS NULL) = (currency IS NULL));
+
+ALTER TABLE payment_requests DROP CONSTRAINT payment_requests_status_check;
+ALTER TABLE payment_requests ADD CONSTRAINT payment_requests_status_check CHECK (status IN ('open', 'granted', 'dismissed', 'expired'));
+
+-- C0 controls, DEL and C1 controls (Unicode Cc); NUL cannot be stored in text at all.
+ALTER TABLE payment_requests ADD CONSTRAINT payment_requests_invoice_name_printable CHECK (invoice_name !~ '[\x01-\x1f\x7f-\x9f]') NOT VALID;
+ALTER TABLE payment_requests ADD CONSTRAINT payment_requests_invoice_tax_id_printable CHECK (invoice_tax_id !~ '[\x01-\x1f\x7f-\x9f]') NOT VALID;
+ALTER TABLE payment_requests ADD CONSTRAINT payment_requests_invoice_address_printable CHECK (invoice_address !~ '[\x01-\x1f\x7f-\x9f]') NOT VALID;

package/migrations/0007_record_failed_refunds.sql

@@ -0,0 +1,27 @@
+-- Failed refunds: a provider refund that fails after billing acted on it (Stripe `refund.failed`)
+-- gives back what it took. Each failure is stored once per refund id, so a repeated delivery gives
+-- back nothing twice. A payment keeps the local days refunds took from its period
+-- (`taken_back_days`), so a failure can give them back, and the time of the newest charge snapshot
+-- it recorded (`refunds_seen_at`, the event's `created`), so a failure of a refund billing never
+-- counted gives back nothing and a snapshot taken before a failure is corrected by it.
+-- Rollback: DROP TABLE billing.refund_failures;
+--   ALTER TABLE billing.payments DROP COLUMN taken_back_days, DROP COLUMN refunds_seen_at; then
+--   DELETE FROM softure.migrations WHERE module = 'billing' AND version = 7;
+ALTER TABLE payments ADD COLUMN taken_back_days integer NOT NULL DEFAULT 0 CHECK (taken_back_days >= 0);
+ALTER TABLE payments ADD COLUMN refunds_seen_at timestamptz;
+
+-- Refunds recorded before this migration were seen when they were recorded (or before now).
+UPDATE payments SET refunds_seen_at = COALESCE(refunded_at, now()) WHERE refunded_amount > 0;
+
+CREATE TABLE refund_failures (
+  payment_id uuid NOT NULL REFERENCES payments (id) ON DELETE CASCADE,
+  -- The provider's refund id (a Stripe Refund, `re_...`).
+  refund_id text NOT NULL CHECK (length(refund_id) BETWEEN 1 AND 255),
+  -- What the refund was for, in the currency's minor unit.
+  amount bigint NOT NULL CHECK (amount >= 0),
+  -- When the provider created the refund, and when it reported the failure (the event's time).
+  refund_created_at timestamptz NOT NULL,
+  failed_at timestamptz NOT NULL,
+  recorded_at timestamptz NOT NULL,
+  PRIMARY KEY (payment_id, refund_id)
+);

package/migrations/0008_record_request_handover_claims.sql

@@ -0,0 +1,9 @@
+-- A hand-over left without an answer (the process stopped between the claim and `onRequest`'s
+-- answer) is handed over again by a later ask. The claim moves to its own column,
+-- handover_claimed_at, which blocks other asks for a bounded time only; handed_over_at now records
+-- a hand-over that answered Ok and is never repeated. Rows from before keep handed_over_at: they
+-- count as handed over (a claim left behind before this migration cannot be told apart).
+-- Rollback: ALTER TABLE billing.payment_requests DROP COLUMN handover_claimed_at; then
+--   DELETE FROM softure.migrations WHERE module = 'billing' AND version = 8;
+--   (the previous code reads handed_over_at as a claim again: nothing is handed over twice).
+ALTER TABLE payment_requests ADD COLUMN handover_claimed_at timestamptz;

package/migrations/0009_record_pending_charge_states.sql

@@ -0,0 +1,16 @@
+-- Pending charge states: Stripe does not order events, so a new refund's `charge.refunded` can arrive
+-- before the failure of an earlier refund of the same charge. Its `amount_refunded` then reports no
+-- more than billing counts, and applying it would undo nothing billing knows of. A payment keeps the
+-- newest such state it did not apply (the raw total and the event's `created`), so the failure that
+-- explains it applies it after giving back the failed refund: the new refund is taken back once.
+-- Applying a state at or after the kept one's time clears it.
+-- Rollback: ALTER TABLE billing.payments DROP CONSTRAINT payments_pending_charge_state_shape;
+--   ALTER TABLE billing.payments DROP COLUMN pending_refunded_amount, DROP COLUMN pending_refunds_seen_at; then
+--   DELETE FROM softure.migrations WHERE module = 'billing' AND version = 9;
+ALTER TABLE payments ADD COLUMN pending_refunded_amount bigint;
+ALTER TABLE payments ADD COLUMN pending_refunds_seen_at timestamptz;
+
+ALTER TABLE payments ADD CONSTRAINT payments_pending_charge_state_shape CHECK (
+  (pending_refunded_amount IS NULL AND pending_refunds_seen_at IS NULL)
+  OR (pending_refunded_amount IS NOT NULL AND pending_refunded_amount >= 0 AND pending_refunds_seen_at IS NOT NULL)
+);

package/module.json

@@ -0,0 +1,23 @@
+{
+  "id": "billing",
+  "version": "0.1.5",
+  "dependsOn": { "security": "^0.1.0", "auth": "^0.1.0" },
+  "dbSchema": "billing",
+  "tables": ["entitlements", "payments", "payment_requests", "manual_grants"],
+  "env": [
+    {
+      "name": "STRIPE_SECRET_KEY",
+      "required": false,
+      "description": "Secret API key of the stripe() payment adapter (sk_test_... in the sandbox), read on every payment; not needed with stripe({ secretKey }) or another adapter."
+    },
+    {
+      "name": "STRIPE_WEBHOOK_SECRET",
+      "required": false,
+      "description": "Signing secret (whsec_...) of the Stripe webhook endpoint that points at stripeWebhookRoute; required when that route is mounted."
+    }
+  ],
+  "switches": [],
+  "routes": { "payment": "/payment", "admin": "/admin/billing", "webhook": "/api/billing/webhook" },
+  "mount": [{ "kind": "route-handler", "path": "app/api/billing/webhook/route.ts", "export": "stripeWebhookRoute" }],
+  "privacy": { "exports": true, "deletes": true }
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@softure-ai/billing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.5",
+  "description": "SOFTURE AI billing module: trial, paid and read-only entitlements from a pure state machine, billing.entitlements apart from auth.users, a write guard for server actions, access badge and notice components, a privacy contributor, reminder mail before access ends over @softure-ai/mailing, manual invoice requests handed to the owner once and expired after a configurable age, grant-plan and revoke-grant ops scripts, and import-entitlements and pin-trials ops scripts for accounts that exist before billing is turned on.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOFTURE/AI.git",
+    "directory": "modules/billing"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "migrations",
+    "module.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "@softure-ai/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "@softure-ai/source": "./src/server/index.ts",
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./mailing": {
+      "@softure-ai/source": "./src/mailing/index.ts",
+      "types": "./dist/mailing/index.d.ts",
+      "default": "./dist/mailing/index.js"
+    },
+    "./next": {
+      "@softure-ai/source": "./src/next/index.ts",
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./scripts": {
+      "@softure-ai/source": "./src/scripts/index.ts",
+      "types": "./dist/scripts/index.d.ts",
+      "default": "./dist/scripts/index.js"
+    },
+    "./ui": {
+      "@softure-ai/source": "./src/ui/index.ts",
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@softure-ai/auth": "^0.1.0",
+    "@softure-ai/core": "^0.1.0",
+    "@softure-ai/db": "^0.1.0",
+    "@softure-ai/ops": "^0.1.0",
+    "@softure-ai/security": "^0.1.0",
+    "@softure-ai/ui": "^0.1.0",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@softure-ai/mailing": "^0.1.0",
+    "drizzle-orm": "^0.45.2",
+    "next": "^16.0.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@softure-ai/mailing": {
+      "optional": true
+    }
+  }
+}

package/src/calendar.ts

@@ -0,0 +1,90 @@
+// Calendar days in the app's IANA time zone, without a date library: trials end at the start of a
+// local day and "days left" counts local days, as people do.
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function getFormatter(timezone: string): Intl.DateTimeFormat {
+  let format = formatters.get(timezone);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timezone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+    formatters.set(timezone, format);
+  }
+  return format;
+}
+
+/** The local wall-clock time of an instant, read as if it were UTC (milliseconds). */
+function getLocalWallTime(instant: number, timezone: string): number {
+  const parts = Object.fromEntries(
+    getFormatter(timezone)
+      .formatToParts(instant)
+      .map((part) => [part.type, part.value]),
+  );
+  return Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute), Number(parts.second));
+}
+
+/** The calendar day of an instant in a time zone, as a day count; two of them subtract to days. */
+export function getDayNumber(instant: Date, timezone: string): number {
+  return Math.floor(getLocalWallTime(instant.getTime(), timezone) / DAY_MS);
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+
+/**
+ * The instant a local day starts (00:00 there). Two passes settle the offset across a DST change.
+ * In a zone that skips midnight itself (America/Santiago, America/Havana) 00:00 does not exist and
+ * the passes land in the previous day, so the result moves on by hours to the first instant of
+ * the day: 01:00 after a one-hour gap.
+ */
+export function getStartOfDay(dayNumber: number, timezone: string): Date {
+  const wallTime = dayNumber * DAY_MS;
+  let instant = wallTime;
+  for (let pass = 0; pass < 2; pass += 1) instant = wallTime - (getLocalWallTime(instant, timezone) - instant);
+  for (let step = 0; step < 3 && getDayNumber(new Date(instant), timezone) < dayNumber; step += 1) {
+    instant = Math.floor(instant / HOUR_MS) * HOUR_MS + HOUR_MS;
+  }
+  return new Date(instant);
+}
+
+/**
+ * The end of a trial of `days` days begun at `start`: the start of the local day `days` days after
+ * the start day. The start day counts as the first day, so a 14-day trial begun on 3 October ends
+ * when 17 October begins. Zero days ends it at the start of the start day: no trial.
+ */
+export function getTrialEnd(start: Date, days: number, timezone: string): Date {
+  return getStartOfDay(getDayNumber(start, timezone) + days, timezone);
+}
+
+/**
+ * Local calendar days of access left before `end`, today included: 1 on the last day. Assumes
+ * `end` is after `now`.
+ */
+export function getDaysLeft(end: Date, now: Date, timezone: string): number {
+  return getDayNumber(new Date(end.getTime() - 1), timezone) - getDayNumber(now, timezone) + 1;
+}
+
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * The day number (as `getDayNumber` counts) of a `YYYY-MM-DD` calendar day, or null when the text
+ * is not one (`2026-1-1`, `2026-02-30`).
+ */
+export function parseDay(day: string): number | null {
+  const match = DAY_PATTERN.exec(day);
+  if (match === null) return null;
+  const [year, month, date] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const wallTime = Date.UTC(year, month - 1, date);
+  const parsed = new Date(wallTime);
+  if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() !== month - 1 || parsed.getUTCDate() !== date) return null;
+  return wallTime / DAY_MS;
+}

package/src/contract.ts

@@ -0,0 +1,181 @@
+// Result types and error codes of the billing module. No user-facing copy here: the UI translates
+// codes through `messages` (docs/02-module-standard.md §6).
+import type { CoreErrorCode, Locale } from "@softure-ai/core";
+import type { InvoiceFieldErrorCode } from "./invoice.js";
+
+export type BillingErrorCode =
+  /** The account may read but not write: its trial or its paid access ended. */
+  | "billing.read_only"
+  /** No account has this id. */
+  | "billing.account_unknown"
+  /** A grant or a trial extension that ends now or earlier. */
+  | "billing.end_not_in_future";
+
+/** Every code a guarded write can show: the guard's own and the generic ones. */
+export type BillingFormErrorCode = BillingErrorCode | CoreErrorCode;
+
+export const ENTITLEMENT_STATUSES = ["trial", "paid", "read_only"] as const;
+
+export type EntitlementStatus = (typeof ENTITLEMENT_STATUSES)[number];
+
+/** What is stored per account (or derived for an account without a row). */
+export interface EntitlementRecord {
+  /** The first instant the trial no longer covers. */
+  readonly trialEndsAt: Date;
+  /**
+   * The first instant dated paid access no longer covers; null when never paid or revoked. Kept
+   * under lifetime access, so a refunded lifetime falls back to the periods bought beside it.
+   */
+  readonly paidUntil: Date | null;
+  /** Paid access without an end; it wins over `paidUntil`. */
+  readonly isLifetime: boolean;
+}
+
+/** Where an account stands at one instant: the state machine's answer. */
+export type Entitlement =
+  | {
+      readonly status: "trial";
+      readonly endsAt: Date;
+      /** Calendar days of access left in the app's time zone, today included. */
+      readonly daysLeft: number;
+      /** Inside the trial reminder window: time to show the notice. */
+      readonly isEnding: boolean;
+    }
+  | {
+      readonly status: "paid";
+      /** Null for lifetime access. */
+      readonly endsAt: Date | null;
+      /** Null for lifetime access. */
+      readonly daysLeft: number | null;
+      /** Inside the paid reminder window; never for lifetime access. */
+      readonly isEnding: boolean;
+    }
+  | {
+      readonly status: "read_only";
+      /** When write access ended. */
+      readonly since: Date;
+      /** Which access ended last. */
+      readonly reason: "trial_ended" | "paid_ended";
+    };
+
+/** A change to an account's entitlement, applied by `changeEntitlement`. */
+export type EntitlementEvent =
+  /** Paid access until `until`; never shortens a later end already granted. */
+  | { readonly type: "grant"; readonly until: Date }
+  /** Paid access without an end; the dated end stays beside it. */
+  | { readonly type: "grant_lifetime" }
+  /** Removes all paid access (a mistaken grant), lifetime included; the trial stays as it was. */
+  | { readonly type: "revoke" }
+  /**
+   * Moves dated paid access back to end at `until` (a refunded period); never lengthens it. An end
+   * at or before the trial's end drops dated paid access: the account is back on its trial.
+   */
+  | { readonly type: "shorten"; readonly until: Date }
+  /** Ends lifetime access (a refunded lifetime); dated paid access stays. */
+  | { readonly type: "end_lifetime" }
+  /** Moves the trial end to `until`; never shortens it. */
+  | { readonly type: "extend_trial"; readonly until: Date }
+  /**
+   * Merges a record carried over from another system (`importEntitlement`): each end only moves
+   * later and lifetime only turns on, so an import never takes access away and a repeat changes
+   * nothing. Ends may lie in the past: an ended trial or period is recorded as it was. Null keeps
+   * what the account has.
+   */
+  | { readonly type: "import"; readonly trialEndsAt: Date | null; readonly paidUntil: Date | null; readonly isLifetime: boolean };
+
+/** What one payment of a plan added to an account, stored with the payment so a refund takes back only that. */
+export type PaymentGrant =
+  /** A paid period from where access ended (or the payment's instant) to the period's end. */
+  | { readonly kind: "period"; readonly from: Date; readonly until: Date }
+  | { readonly kind: "lifetime" };
+
+/** Copy per locale; a locale without its own text falls back to `en`. */
+export type LocalizedText = Readonly<Partial<Record<Locale, string>>>;
+
+export const PERIOD_UNITS = ["day", "week", "month", "year"] as const;
+
+export type PeriodUnit = (typeof PERIOD_UNITS)[number];
+
+/** How long one payment of a plan gives access: `count` units, or for good. */
+export type PlanPeriod = { readonly unit: PeriodUnit; readonly count: number } | { readonly unit: "lifetime" };
+
+/** A price in the currency's minor unit (cents, grosze; whole yen for JPY), as payment providers take it. */
+export interface PlanPrice {
+  readonly amount: number;
+  /** ISO 4217, upper case, e.g. `PLN`, `EUR`. */
+  readonly currency: string;
+}
+
+/** A plan from `billing({ plans })`. */
+export interface Plan {
+  /** Kebab-case, unique; the payment page and the payment providers name the plan by it. */
+  readonly id: string;
+  readonly name: LocalizedText;
+  readonly description?: LocalizedText;
+  readonly price: PlanPrice;
+  readonly period: PlanPeriod;
+  /** What the plan includes, one line each, in the order the tile lists them. */
+  readonly features: readonly LocalizedText[];
+  /** Drawn as the recommended plan. */
+  readonly isFeatured: boolean;
+}
+
+/** Why a payment could not start. */
+export type PaymentErrorCode =
+  /** A plan id the config does not declare: a tampered or outdated form. */
+  | "billing.plan_unknown"
+  /** An invoice field is missing, too long or has control characters; `fieldErrors` says which. */
+  | "billing.invoice_details_invalid"
+  /** The payment provider refused or failed; nothing was charged or requested. */
+  | "billing.payment_failed"
+  /** The account has lifetime access: there is nothing left to pay for or grant. */
+  | "billing.lifetime_active";
+
+/** Every code the payment form can show, the invoice fields' own included. */
+export type PaymentFormErrorCode = PaymentErrorCode | InvoiceFieldErrorCode | "security.rate_limited" | CoreErrorCode;
+
+/** Every code the admin grant form can show. */
+export type GrantFormErrorCode = "billing.plan_unknown" | "billing.account_unknown" | "billing.lifetime_active" | "auth.forbidden" | CoreErrorCode;
+
+/** Why an admin could not act on a request or a manual grant. */
+export type AdminErrorCode =
+  /** The request was granted or dismissed already, or never existed. */
+  | "billing.request_closed"
+  /** The grant was revoked already, or never existed. */
+  | "billing.grant_revoked";
+
+/** Every code the admin page's buttons and account lookup can show. */
+export type AdminActionErrorCode = AdminErrorCode | GrantFormErrorCode;
+
+/** What the payment action returns to its form (`useActionState`). */
+export interface PaymentFormState {
+  readonly status: "idle" | "requested" | "error";
+  readonly error?: PaymentFormErrorCode;
+  /** Errors of single invoice fields, by field name. */
+  readonly fieldErrors?: Readonly<Record<string, PaymentFormErrorCode>>;
+  /** The invoice details as typed, to fill the fields again after an error. */
+  readonly values?: Readonly<Record<string, string>>;
+}
+
+export const INITIAL_PAYMENT_FORM_STATE: PaymentFormState = { status: "idle" };
+
+/** What the admin grant action returns to its form (`useActionState`). */
+export interface GrantFormState {
+  readonly status: "idle" | "granted" | "error";
+  readonly error?: GrantFormErrorCode;
+  /** After a grant: what the account has now, in the app's copy. */
+  readonly notice?: string;
+  /** The email and plan as sent, to fill the form again after an error. */
+  readonly email?: string;
+  readonly planId?: string;
+}
+
+export const INITIAL_GRANT_FORM_STATE: GrantFormState = { status: "idle" };
+
+/** What an admin button (grant or dismiss a request, revoke a grant, find an account) returns to its form. */
+export type AdminActionState =
+  | { readonly status: "idle" }
+  | { readonly status: "done" }
+  | { readonly status: "error"; readonly error: AdminActionErrorCode; readonly email?: string };
+
+export const INITIAL_ADMIN_ACTION_STATE: AdminActionState = { status: "idle" };

package/src/currency-digits.ts

@@ -0,0 +1,37 @@
+// The minor unit billing pins for each currency it accepts: a plan's `price.amount` counts these
+// units on every runtime, whatever the runtime's `Intl` (CLDR) says. Source: ISO 4217 List One,
+// published 2024-06-25, without fund codes, `N.A.` units (metals, XDR, XTS, XXX ...) and UYW (a wage
+// index unit), plus the two choices below. CLDR differs from ISO on AFN, ALL, IRR, KPW, LAK, LBP,
+// MMK, RSD, SOS, SYP and YER (0 instead of 2) and IQD (0 instead of 3), and its HUF and TWD digits
+// have changed between Node builds; billing follows ISO, as Stripe does for all but MGA.
+
+/** ISO 4217 codes by the digits of their minor unit. */
+const CODES_BY_DIGITS: Readonly<Record<0 | 2 | 3, readonly string[]>> = {
+  0: [
+    "BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW", "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+    // Override: ISO writes 2, but one ariary is five iraimbilanja (not a decimal subunit), and CLDR
+    // and Stripe both count it without a minor unit.
+    "MGA",
+  ],
+  2: [
+    "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BMD", "BND",
+    "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CNY", "COP", "CRC", "CUC", "CUP", "CVE",
+    "CZK", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GTQ",
+    "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IRR", "JMD", "KES", "KGS", "KHR", "KPW", "KYD", "KZT",
+    "LAK", "LBP", "LKR", "LRD", "LSL", "MAD", "MDL", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN",
+    "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "QAR", "RON",
+    "RSD", "RUB", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP",
+    "SZL", "THB", "TJS", "TMT", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "USD", "UYU", "UZS", "VED", "VES", "WST",
+    "XCD", "YER", "ZAR", "ZMW", "ZWG",
+    // Addition: the Caribbean guilder, which replaced ANG on 2025-03-31, after the pinned list.
+    "XCG",
+  ],
+  3: ["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"],
+};
+
+/** Digits of the minor unit per currency code billing accepts, e.g. `PLN: 2`, `JPY: 0`, `KWD: 3`. */
+export const CURRENCY_MINOR_UNIT_DIGITS: Readonly<Record<string, number>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CODES_BY_DIGITS).flatMap(([digits, codes]) => codes.map((code) => [code, Number(digits)] as const)),
+  ),
+);