@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/entitlement.ts

@@ -0,0 +1,84 @@
+// The entitlement state machine, pure: a record and an instant give the status, and an event gives
+// the next record. No database and no clock here, so every transition is a plain unit test.
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { getDaysLeft } from "./calendar.js";
+import type { BillingErrorCode, Entitlement, EntitlementEvent, EntitlementRecord } from "./contract.js";
+
+export interface EntitlementPolicy {
+  /** The app's IANA time zone: days left are counted there. */
+  readonly timezone: string;
+  /** From how many days left a trial counts as ending; 0 never. */
+  readonly trialReminderDays: number;
+  /** From how many days left paid access counts as ending; 0 never. */
+  readonly paidReminderDays: number;
+}
+
+/**
+ * The status of `record` at `now`. Paid access wins over the trial; access covers instants before
+ * its end, so at the end itself the account is read-only.
+ */
+export function resolveEntitlement(record: EntitlementRecord, now: Date, policy: EntitlementPolicy): Entitlement {
+  if (record.isLifetime) return { status: "paid", endsAt: null, daysLeft: null, isEnding: false };
+  if (record.paidUntil !== null && now < record.paidUntil) {
+    const daysLeft = getDaysLeft(record.paidUntil, now, policy.timezone);
+    return { status: "paid", endsAt: record.paidUntil, daysLeft, isEnding: daysLeft <= policy.paidReminderDays };
+  }
+  if (now < record.trialEndsAt) {
+    const daysLeft = getDaysLeft(record.trialEndsAt, now, policy.timezone);
+    return { status: "trial", endsAt: record.trialEndsAt, daysLeft, isEnding: daysLeft <= policy.trialReminderDays };
+  }
+  if (record.paidUntil !== null && record.paidUntil > record.trialEndsAt) return { status: "read_only", since: record.paidUntil, reason: "paid_ended" };
+  return { status: "read_only", since: record.trialEndsAt, reason: "trial_ended" };
+}
+
+/** Whether an account in this state may write. */
+export function hasWriteAccess(entitlement: Entitlement): boolean {
+  return entitlement.status !== "read_only";
+}
+
+/** The later of two instants. */
+function getLater(first: Date, second: Date): Date {
+  return first > second ? first : second;
+}
+
+/** The earlier of two instants. */
+function getEarlier(first: Date, second: Date): Date {
+  return first < second ? first : second;
+}
+
+/**
+ * The record after `event` at `now`. Grants and trial extensions must end after `now` and never
+ * shorten what the account already has; an import never shortens either, but may record past ends;
+ * a revoke ends paid access, lifetime included. The dated end lives on under lifetime access: a
+ * grant still extends it, and ending lifetime falls back to it.
+ */
+export function applyEntitlementEvent(record: EntitlementRecord, event: EntitlementEvent, now: Date): Ok<EntitlementRecord> | Err<BillingErrorCode> {
+  switch (event.type) {
+    case "grant": {
+      if (event.until <= now) return err("billing.end_not_in_future");
+      const paidUntil = record.paidUntil === null ? event.until : getLater(record.paidUntil, event.until);
+      return ok({ ...record, paidUntil });
+    }
+    case "grant_lifetime":
+      return ok({ ...record, isLifetime: true });
+    case "revoke":
+      return ok({ ...record, paidUntil: null, isLifetime: false });
+    case "shorten": {
+      if (record.paidUntil === null) return ok(record);
+      const paidUntil = getEarlier(record.paidUntil, event.until);
+      // Paid access that would end inside the trial adds nothing: the account is back on its trial.
+      return ok({ ...record, paidUntil: paidUntil > record.trialEndsAt ? paidUntil : null });
+    }
+    case "end_lifetime":
+      return ok({ ...record, isLifetime: false });
+    case "extend_trial":
+      if (event.until <= now) return err("billing.end_not_in_future");
+      return ok({ ...record, trialEndsAt: getLater(record.trialEndsAt, event.until) });
+    case "import":
+      return ok({
+        trialEndsAt: event.trialEndsAt === null ? record.trialEndsAt : getLater(record.trialEndsAt, event.trialEndsAt),
+        paidUntil: event.paidUntil === null || (record.paidUntil !== null && record.paidUntil >= event.paidUntil) ? record.paidUntil : event.paidUntil,
+        isLifetime: record.isLifetime || event.isLifetime,
+      });
+  }
+}

package/src/fields.ts

@@ -0,0 +1,37 @@
+// Form field names shared by the forms (`/ui`) and the actions that read them (`/next`).
+export const PLAN_FIELD = "plan";
+export const EMAIL_FIELD = "email";
+
+export const INVOICE_FIELDS = {
+  name: "invoiceName",
+  taxId: "invoiceTaxId",
+  address: "invoiceAddress",
+} as const;
+
+export type InvoiceField = (typeof INVOICE_FIELDS)[keyof typeof INVOICE_FIELDS];
+
+export const INVOICE_LIMITS = {
+  name: 200,
+  taxId: 32,
+  address: 500,
+} as const;
+
+/** The limit of the invoice field with this form name, for the too-long message. */
+export function getInvoiceFieldLimit(field: string): number | undefined {
+  const key = (Object.keys(INVOICE_FIELDS) as (keyof typeof INVOICE_FIELDS)[]).find((name) => INVOICE_FIELDS[name] === field);
+  return key === undefined ? undefined : INVOICE_LIMITS[key];
+}
+
+/** The payment page's parameter a hosted checkout returns with: `?checkout=success` or `?checkout=cancelled`. */
+export const CHECKOUT_PARAM = "checkout";
+
+export const CHECKOUT_RESULTS = ["success", "cancelled"] as const;
+
+export type CheckoutResult = (typeof CHECKOUT_RESULTS)[number];
+
+/** The admin page's hidden fields: the request a button grants or dismisses, the grant one revokes. */
+export const REQUEST_FIELD = "request";
+export const GRANT_FIELD = "grant";
+
+/** The admin page's parameter that names the account whose history it shows (its id, never its email). */
+export const ACCOUNT_PARAM = "account";

package/src/index.ts

@@ -0,0 +1,163 @@
+// Public API of @softure-ai/billing: the module factory for softure.config.ts, its rate limit bucket,
+// the manual and Stripe payment adapters, Stripe's webhook signature, the pure entitlement state
+// machine and plan periods, prices, types, messages and the tables. Reading and changing
+// entitlements, granting plans, starting payments and recording provider payments is in
+// `@softure-ai/billing/server`, the Next.js adapter (write guard, payment and admin pages, actions,
+// the Stripe webhook route, current badge and notice) in `/next`, the components in `/ui`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { billingMessages } from "./messages/index.js";
+import { billingOptionsSchema } from "./options.js";
+import { checkBillingTables } from "./server/health.js";
+import { billingPrivacyContributor } from "./server/privacy.js";
+
+export const MODULE_ID = "billing";
+
+/**
+ * The rate limit bucket payments consume, with its default to spread into `security({ buckets })`:
+ * `billing-payment` per account (a payment page sent again and again).
+ */
+export const BILLING_RATE_LIMIT_BUCKETS = {
+  "billing-payment": { limit: 5, windowMinutes: 60 },
+} as const;
+
+/**
+ * Enables entitlements, plans and payments in `softure.config.ts` (after `security` and `auth`):
+ * `billing({ trial: { days: 14 }, plans: [{ id: "monthly", name: { en: "Monthly" }, price: { amount: 2900, currency: "PLN" }, period: "month" }], payment: stripe() })`
+ * (or `manual({ onRequest })` for invoices).
+ */
+export const billing = defineModule({
+  manifest: {
+    id: MODULE_ID,
+    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 },
+  },
+  messages: billingMessages,
+  options: billingOptionsSchema,
+  migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+  privacy: billingPrivacyContributor,
+  health: checkBillingTables,
+});
+
+export { getDayNumber, getDaysLeft, getStartOfDay, getTrialEnd, parseDay } from "./calendar.js";
+export {
+  ENTITLEMENT_STATUSES,
+  INITIAL_ADMIN_ACTION_STATE,
+  INITIAL_GRANT_FORM_STATE,
+  INITIAL_PAYMENT_FORM_STATE,
+  PERIOD_UNITS,
+  type AdminActionErrorCode,
+  type AdminActionState,
+  type AdminErrorCode,
+  type BillingErrorCode,
+  type BillingFormErrorCode,
+  type Entitlement,
+  type EntitlementEvent,
+  type EntitlementRecord,
+  type EntitlementStatus,
+  type GrantFormErrorCode,
+  type GrantFormState,
+  type LocalizedText,
+  type PaymentErrorCode,
+  type PaymentFormErrorCode,
+  type PaymentFormState,
+  type PaymentGrant,
+  type PeriodUnit,
+  type Plan,
+  type PlanPeriod,
+  type PlanPrice,
+} from "./contract.js";
+export { applyEntitlementEvent, hasWriteAccess, resolveEntitlement, type EntitlementPolicy } from "./entitlement.js";
+export { CHECKOUT_PARAM, CHECKOUT_RESULTS, type CheckoutResult } from "./fields.js";
+export { invoiceDetailsSchema, type InvoiceFieldErrorCode } from "./invoice.js";
+export { manual, type ManualPaymentOptions } from "./manual.js";
+export { billingMessages, getBillingErrorMessage, type BillingMessages } from "./messages/index.js";
+export {
+  DEFAULT_REQUEST_EXPIRY_DAYS,
+  MAX_DAYS,
+  MAX_FEATURES,
+  MAX_PERIOD_COUNT,
+  MAX_PLANS,
+  MAX_PRICE_AMOUNT,
+  PARTIAL_REFUND_POLICIES,
+  type PartialRefundPolicy,
+  type BillingOptions,
+  type BillingOptionsInput,
+} from "./options.js";
+export {
+  isPaymentProvider,
+  type InvoiceDetails,
+  type PaymentAccount,
+  type PaymentContext,
+  type PaymentProvider,
+  type PaymentRequest,
+  type PaymentStart,
+} from "./payment.js";
+export { findPlan, getLocalizedText, getPeriodEnd, getPlanGrant } from "./plans.js";
+export {
+  getPaymentGrant,
+  getRefundEvent,
+  getRestoredDays,
+  getTakenBackDays,
+  getUnusedDays,
+  isFullShare,
+  moveBackByDays,
+  moveForwardByDays,
+  type RefundShare,
+  type RefundTiming,
+  type RestoredDaysInput,
+} from "./refund.js";
+export {
+  ACCESS_REMINDER_KINDS,
+  DEFAULT_CATCH_UP_DAYS,
+  getAccessReminder,
+  getAccessReminderScope,
+  MAX_CATCH_UP_DAYS,
+  type AccessReminder,
+  type AccessReminderInput,
+  type AccessReminderKind,
+} from "./reminder.js";
+export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+export { formatPrice, getMinorUnitDigits, isSupportedCurrency } from "./price.js";
+export { billingSchema, entitlements, manualGrants, paymentRequests, payments } from "./schema.js";
+export { getCheckoutSessionParams, stripe, STRIPE_API_BASE, STRIPE_SECRET_KEY_ENV, STRIPE_TIMEOUT_MS, type StripeOptions } from "./stripe.js";
+export {
+  describeStripePriceProblem,
+  fromStripeAmount,
+  getStripeMinorUnitDigits,
+  STRIPE_THREE_DECIMAL_CURRENCIES,
+  STRIPE_ZERO_DECIMAL_CURRENCIES,
+  toStripeAmount,
+} from "./stripe-currency.js";
+export {
+  parseStripeEvent,
+  readStripeWebhook,
+  signStripePayload,
+  STRIPE_METADATA,
+  STRIPE_SIGNATURE_HEADER,
+  STRIPE_SIGNATURE_TOLERANCE_SECONDS,
+  verifyStripeSignature,
+  type FailedRefund,
+  type PaidCheckout,
+  type SignStripePayloadInput,
+  type StripeWebhookError,
+  type StripeWebhookEvent,
+  type VerifyStripeSignatureInput,
+} from "./stripe-webhook.js";

package/src/invoice.ts

@@ -0,0 +1,58 @@
+// Invoice details as the payment form sends them, parsed at the boundary by a zod schema: each
+// field trimmed, the name and the address required, each within its limit, and no control
+// characters (Unicode Cc: line breaks, tabs, escapes) anywhere, so a name cannot add lines to the
+// owner's mail. Every field problem has its own code, so the form says what to fix.
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { z } from "zod";
+import { INVOICE_FIELDS, INVOICE_LIMITS, type InvoiceField } from "./fields.js";
+import type { InvoiceDetails } from "./payment.js";
+
+/** Invoice details as the form sent them, untrimmed. */
+export interface InvoiceInput {
+  readonly name: string;
+  readonly taxId: string;
+  readonly address: string;
+}
+
+/** Why one invoice field was refused. */
+export type InvoiceFieldErrorCode =
+  /** The name or the address is empty. */
+  | "billing.invoice_field_required"
+  /** Longer than `INVOICE_LIMITS` allows the field. */
+  | "billing.invoice_field_too_long"
+  /** A line break, a tab or another control character. */
+  | "billing.invoice_field_control_characters";
+
+export type InvoiceDetailsError = Err<"billing.invoice_details_invalid"> & {
+  readonly fieldErrors: Readonly<Partial<Record<InvoiceField, InvoiceFieldErrorCode>>>;
+};
+
+const CONTROL_CHARACTER = /\p{Cc}/u;
+
+function createFieldSchema(limit: number, isRequired: boolean) {
+  return z
+    .string()
+    .trim()
+    .refine((value) => !CONTROL_CHARACTER.test(value), { message: "billing.invoice_field_control_characters", abort: true })
+    .refine((value) => !isRequired || value !== "", { message: "billing.invoice_field_required", abort: true })
+    .refine((value) => value.length <= limit, { message: "billing.invoice_field_too_long", abort: true });
+}
+
+export const invoiceDetailsSchema = z.strictObject({
+  name: createFieldSchema(INVOICE_LIMITS.name, true),
+  taxId: createFieldSchema(INVOICE_LIMITS.taxId, false).transform((taxId) => (taxId === "" ? null : taxId)),
+  address: createFieldSchema(INVOICE_LIMITS.address, true),
+});
+
+/** Trimmed invoice details, or the first problem of each field that has one. */
+export function parseInvoiceDetails(input: InvoiceInput): Ok<InvoiceDetails> | InvoiceDetailsError {
+  const parsed = invoiceDetailsSchema.safeParse({ name: input.name, taxId: input.taxId, address: input.address });
+  if (parsed.success) return ok(parsed.data);
+  const fieldErrors: Partial<Record<InvoiceField, InvoiceFieldErrorCode>> = {};
+  for (const issue of parsed.error.issues) {
+    const key = issue.path[0] as keyof typeof INVOICE_FIELDS;
+    // Each refinement's message is one of the codes above; the first problem of a field wins.
+    fieldErrors[INVOICE_FIELDS[key]] ??= issue.message as InvoiceFieldErrorCode;
+  }
+  return { ...err("billing.invoice_details_invalid"), fieldErrors };
+}

package/src/mailing/index.ts

@@ -0,0 +1,11 @@
+// The mailing adapter of @softure-ai/billing: reminder mail before and after access ends, through
+// `@softure-ai/mailing` (an optional peer dependency; only apps that import this entry need it).
+export {
+  DEFAULT_REMINDER_PAUSE_MS,
+  renderAccessReminderMail,
+  sendAccessReminders,
+  type AccessReminderMail,
+  type AccessReminderMailInput,
+  type AccessReminderSummary,
+  type SendAccessRemindersOptions,
+} from "./reminder-mail.js";

package/src/mailing/reminder-mail.ts

@@ -0,0 +1,108 @@
+// The reminder mail: the in-app notice's four states as a mail, sent once per account, kind and
+// end through `@softure-ai/mailing`'s delivery ledger. A transactional mail (an account notice): no
+// unsubscribe link, never suppressed. The copy comes from billing's dictionary in the app's locale;
+// the link to the payment page is placed by the code, so a copy override cannot drop it.
+import { formatMessage, type ModuleContext } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import type { OutgoingMail } from "@softure-ai/mailing";
+import { deliverOnce } from "@softure-ai/mailing/server";
+import type { BillingMessages } from "../messages/index.js";
+import { getAccessReminderScope, type AccessReminderKind } from "../reminder.js";
+import { getBillingMessages, getBillingRoutes } from "../server/options.js";
+import { findAccessReminders, type FindAccessRemindersOptions } from "../server/reminders.js";
+import { formatLastDay } from "../ui/format.js";
+
+/** Pause between two mails a provider was called for: Resend allows two requests per second. */
+export const DEFAULT_REMINDER_PAUSE_MS = 500;
+
+export interface AccessReminderMailInput {
+  readonly kind: AccessReminderKind;
+  /** The last day with access, as the app's locale writes it (`formatLastDay`). */
+  readonly lastDay: string;
+  /** The payment page's absolute URL. */
+  readonly link: string;
+}
+
+/** The subject and bodies of a reminder mail, without the recipient. */
+export type AccessReminderMail = Pick<OutgoingMail, "subject" | "text"> & { readonly html: string };
+
+export interface SendAccessRemindersOptions extends FindAccessRemindersOptions {
+  /** Milliseconds to wait after each mail a provider was called for. Default 500; 0 never waits. */
+  readonly pauseMs?: number;
+  /** How to wait; tests pass their own. */
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+export interface AccessReminderSummary {
+  /** Accounts due a reminder this run. */
+  readonly due: number;
+  /** Mails sent now. */
+  readonly sent: number;
+  /** Mails an earlier run sent (or refused), or another run is sending right now. */
+  readonly skipped: number;
+  /** Mails refused for good (an invalid address, the provider rejected it). */
+  readonly rejected: number;
+  /** Mails the provider could not take now; the next run sends them. */
+  readonly retryLater: number;
+}
+
+const COPY_KEYS = {
+  "trial-ending": "trialEnding",
+  "paid-ending": "paidEnding",
+  "trial-ended": "trialEnded",
+  "paid-ended": "paidEnded",
+} as const satisfies Record<AccessReminderKind, keyof BillingMessages["reminderMail"]>;
+
+const HTML_ESCAPES: Readonly<Record<string, string>> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character);
+}
+
+/**
+ * Renders a reminder from `messages` (one locale's dictionary, overrides applied): a plain-text body
+ * with the notice's link text and the bare link, and an HTML body with the link as an anchor.
+ */
+export function renderAccessReminderMail(messages: BillingMessages, input: AccessReminderMailInput): AccessReminderMail {
+  const copy = messages.reminderMail[COPY_KEYS[input.kind]];
+  const action = input.kind.startsWith("trial-") ? messages.notice.choosePlan : messages.notice.renew;
+  const values = { date: input.lastDay };
+  const subject = formatMessage(copy.subject, values);
+  const body = formatMessage(copy.body, values);
+  const text = [body, `${action}: ${input.link}`].join("\n\n");
+  const html = [`<p>${escapeHtml(body)}</p>`, `<p><a href="${escapeHtml(input.link)}">${escapeHtml(action)}</a></p>`].join("\n");
+  return { subject, text, html };
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Mails every account due a reminder (`findAccessReminders`) through mailing's delivery ledger, so
+ * each account gets one mail per kind and end however often the run repeats or overlaps. Call it
+ * on a schedule (a daily cron job running a script). Needs `mailing({ ... })` in the config; a
+ * database failure propagates (the next run resumes, and the ledger keeps it from mailing twice).
+ */
+export async function sendAccessReminders(ctx: ModuleContext<Queryable>, options: SendAccessRemindersOptions = {}): Promise<AccessReminderSummary> {
+  const { pauseMs = DEFAULT_REMINDER_PAUSE_MS, sleep = wait, ...findOptions } = options;
+  const due = await findAccessReminders(ctx, findOptions);
+  const messages = getBillingMessages(ctx.config);
+  const link = new URL(getBillingRoutes(ctx.config).payment, ctx.config.appOrigin).href;
+  const counts = { sent: 0, skipped: 0, rejected: 0, retryLater: 0 };
+
+  for (const reminder of due) {
+    const lastDay = formatLastDay(reminder.endsAt, ctx.config.locale, ctx.config.timezone);
+    const mail = renderAccessReminderMail(messages, { kind: reminder.kind, lastDay, link });
+    const outcome = await deliverOnce(ctx, { scope: getAccessReminderScope(reminder.kind, reminder.userId, reminder.endsAt), mail: { to: reminder.email, ...mail } });
+    if (outcome.status === "done" || outcome.status === "in-flight") {
+      counts.skipped += 1;
+      continue;
+    }
+    if (outcome.status === "sent") counts.sent += 1;
+    else if (outcome.status === "rejected") counts.rejected += 1;
+    else counts.retryLater += 1;
+    if (pauseMs > 0) await sleep(pauseMs);
+  }
+  return { due: due.length, ...counts };
+}

package/src/manual.ts

@@ -0,0 +1,31 @@
+// The manual payment adapter: the buyer asks for an invoice on the payment page, the app hands the
+// request to its owner (`onRequest`: a mail, a ticket), and the owner grants the plan in the admin
+// page once the invoice is paid. Nothing is charged here; `startPayment` stores the request before
+// it is handed over, so the admin page lists it, and hands an open request over once.
+import { err, ok, type Err, type ErrorCode, type Ok } from "@softure-ai/core";
+import type { PaymentContext, PaymentProvider, PaymentRequest } from "./payment.js";
+
+export interface ManualPaymentOptions {
+  /**
+   * Hands a request to the owner. An `Err` tells the buyer the request did not go through
+   * (`billing.payment_failed`, its code is logged); a throw is reported as an unexpected failure.
+   */
+  readonly onRequest: (request: PaymentRequest, ctx: PaymentContext) => Promise<Ok<undefined> | Err<ErrorCode>>;
+}
+
+/** `billing({ payment: manual({ onRequest }) })`: invoices requested by the buyer, access granted by an admin. */
+export function manual(options: ManualPaymentOptions): PaymentProvider {
+  return {
+    name: "manual",
+    collectsInvoiceDetails: true,
+    handsOverRequests: true,
+    async startPayment(ctx, request) {
+      const handed = await options.onRequest(request, ctx);
+      if (!handed.ok) {
+        console.error(`@softure-ai/billing: the manual payment request for plan "${request.plan.id}" was not handed over: ${handed.error}`);
+        return err("billing.payment_failed");
+      }
+      return ok({ type: "requested" });
+    },
+  };
+}

package/src/messages/en.ts

@@ -0,0 +1,150 @@
+export const en = {
+  badge: {
+    trial: "Trial",
+    paid: "Paid",
+    lifetime: "Lifetime access",
+    readOnly: "Read-only",
+    daysLeft: { one: "{count} day left", few: "{count} days left", many: "{count} days left", other: "{count} days left" },
+    until: "until {date}",
+  },
+  notice: {
+    trialEnding: "Your trial ends on {date}. Choose a plan to keep writing after that.",
+    paidEnding: "Your access ends on {date}. Renew it to keep writing after that.",
+    trialEnded: "Your trial has ended. Your data is safe and you can still read it; choose a plan to write again.",
+    paidEnded: "Your access has ended. Your data is safe and you can still read it; renew it to write again.",
+    choosePlan: "Choose a plan",
+    renew: "Renew access",
+  },
+  reminderMail: {
+    trialEnding: {
+      subject: "Your trial ends on {date}",
+      body: "Your trial ends on {date}. Choose a plan to keep writing after that; your data stays safe either way.",
+    },
+    paidEnding: {
+      subject: "Your access ends on {date}",
+      body: "Your access ends on {date}. Renew it to keep writing after that; your data stays safe either way.",
+    },
+    trialEnded: {
+      subject: "Your trial has ended",
+      body: "Your trial has ended. Your data is safe and you can still read it; choose a plan to write again.",
+    },
+    paidEnded: {
+      subject: "Your access has ended",
+      body: "Your access has ended. Your data is safe and you can still read it; renew it to write again.",
+    },
+  },
+  pricing: {
+    period: {
+      day: { one: "per day", few: "per {count} days", many: "per {count} days", other: "per {count} days" },
+      week: { one: "per week", few: "per {count} weeks", many: "per {count} weeks", other: "per {count} weeks" },
+      month: { one: "per month", few: "per {count} months", many: "per {count} months", other: "per {count} months" },
+      year: { one: "per year", few: "per {count} years", many: "per {count} years", other: "per {count} years" },
+      lifetime: "one-time payment",
+    },
+    featured: "Recommended",
+    choose: "Choose {plan}",
+    empty: "No plans are available yet.",
+  },
+  payment: {
+    title: "Choose a plan",
+    lead: "Pick the plan that suits you. Paid access starts when your current access ends.",
+    plansLabel: "Plans",
+    orderTitle: "Your order",
+    orderLead: "{plan}, {price} {period}",
+    changePlan: "Choose another plan",
+    invoiceLead: "We will send an invoice to {email}. Your access starts once it is paid.",
+    fields: {
+      name: "Name or company",
+      taxId: "Tax ID (optional)",
+      address: "Billing address",
+    },
+    requestInvoice: "Request an invoice",
+    checkout: "Go to payment",
+    pending: "Sending…",
+    requested: "Thank you! Your invoice request for {plan} has been sent. We will email the invoice to {email}; your access starts once it is paid.",
+    checkoutSuccess: "Thank you for your payment! Your access is updated as soon as the payment is confirmed, usually within a minute.",
+    checkoutCancelled: "The payment was cancelled and nothing was charged. You can try again or choose another plan.",
+    lifetime: "You have lifetime access: there is nothing left to pay for.",
+  },
+  admin: {
+    title: "Grant access",
+    lead: "Grant a plan to an account once its payment has arrived. A paid period starts when the account's current access ends.",
+    email: "Account email",
+    plan: "Plan",
+    submit: "Grant plan",
+    pending: "Granting…",
+    granted: "{email} now has {plan}.",
+    grantedUntil: "{email} now has {plan}, with access until {date}.",
+    noPlans: "There are no plans to grant: add them to billing({ plans }).",
+    requests: {
+      title: "Invoice requests",
+      lead: "Requests sent from the payment page. Grant the plan once the invoice is paid, or dismiss the request.",
+      empty: "No open requests.",
+      line: "{email} · {plan}",
+      requestedOn: "Requested on {date}",
+      price: "Price: {price}",
+      invoice: "Invoice to: {name}, {address}",
+      taxId: "Tax ID: {taxId}",
+      noInvoice: "No invoice details",
+      grant: "Grant",
+      granting: "Granting…",
+      dismiss: "Dismiss",
+      dismissing: "Dismissing…",
+      history: "History",
+      grantLabel: "Grant {plan} to {email}",
+      dismissLabel: "Dismiss the request of {email} for {plan}",
+    },
+    history: {
+      title: "Account history",
+      lead: "Find an account to see its access, the plans granted to it by hand and its payments.",
+      email: "Find an account by email",
+      submit: "Show history",
+      pending: "Searching…",
+      accountTitle: "History of {email}",
+      empty: "No grants or payments yet.",
+      manual: "{plan}, granted by hand",
+      fromRequest: "{plan}, granted from a request",
+      provider: "{plan}, paid with {provider}",
+      grantedOn: "Granted on {date}",
+      grantedFor: "Granted for {amount} on {date}",
+      paidOn: "Paid {amount} on {date}",
+      period: "Access from {from} to {to}",
+      lifetime: "Lifetime access",
+      noGrant: "Recorded before grants were stored",
+      active: "Active",
+      revokedOn: "Revoked on {date}",
+      paid: "Paid",
+      refundedOn: "Refunded on {date}",
+      partlyRefunded: "Paid, {amount} refunded",
+      revoke: "Revoke",
+      revoking: "Revoking…",
+      revokeLabel: "Revoke {plan} granted on {date}",
+    },
+  },
+  errors: {
+    billing: {
+      read_only: "Your account is read-only. Choose a plan to make changes.",
+      account_unknown: "No account has this email address.",
+      end_not_in_future: "The end date must be in the future.",
+      plan_unknown: "This plan is no longer available. Choose another one.",
+      invoice_details_invalid: "Check the invoice details below.",
+      invoice_field_required: "Fill in this field.",
+      invoice_field_too_long: "Use at most {max} characters.",
+      invoice_field_control_characters: "Remove line breaks, tabs and other control characters.",
+      payment_failed: "The payment could not be started. Try again in a moment.",
+      lifetime_active: "This account already has lifetime access: there is nothing to pay for or grant.",
+      request_closed: "This request was granted or dismissed already.",
+      grant_revoked: "This grant was revoked already.",
+    },
+    security: {
+      rate_limited: "Too many attempts. Try again later.",
+    },
+    auth: {
+      forbidden: "You are not allowed to do this.",
+    },
+    core: {
+      database_failed: "Something went wrong on our side. Try again in a moment.",
+      unexpected: "Something went wrong on our side. Try again in a moment.",
+    },
+  },
+};

package/src/messages/index.ts

@@ -0,0 +1,18 @@
+import type { AdminActionErrorCode, BillingFormErrorCode, GrantFormErrorCode, PaymentFormErrorCode } from "../contract.js";
+import { en } from "./en.js";
+import { pl } from "./pl.js";
+
+export type BillingMessages = typeof en;
+
+/** Complete default dictionaries; apps pass partial overrides per locale. */
+export const billingMessages = { en, pl };
+
+/** The copy for an error code; an unknown code gets the generic failure. */
+export function getBillingErrorMessage(messages: BillingMessages, code: BillingFormErrorCode | PaymentFormErrorCode | GrantFormErrorCode | AdminActionErrorCode): string {
+  const separator = code.lastIndexOf(".");
+  const namespace = code.slice(0, separator);
+  const name = code.slice(separator + 1);
+  const groups = messages.errors as Readonly<Record<string, Readonly<Record<string, string>>>>;
+  const group = Object.hasOwn(groups, namespace) ? groups[namespace] : undefined;
+  return (group !== undefined && Object.hasOwn(group, name) ? group[name] : undefined) ?? messages.errors.core.unexpected;
+}