@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/next/pages.tsx

@@ -0,0 +1,267 @@
+// Pages ready to mount with one line each:
+// `export { PaymentPage as default } from "@softure-ai/billing/next"` at `routes.payment`, and
+// `export { BillingAdminPage as default } from "@softure-ai/billing/next"` at `routes.admin`.
+// Server components: they read the config and the session, and render the forms from `../ui`.
+import { requireRole, requireUser } from "@softure-ai/auth/next";
+import { formatMessage, type Locale, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { ButtonLink, Card, EmptyState } from "@softure-ai/ui";
+import type { PaymentGrant, Plan } from "../contract.js";
+import { ACCOUNT_PARAM, CHECKOUT_PARAM, CHECKOUT_RESULTS, PLAN_FIELD, type CheckoutResult } from "../fields.js";
+import type { BillingMessages } from "../messages/index.js";
+import { findPlan, getLocalizedText } from "../plans.js";
+import { formatPrice } from "../price.js";
+import { getEntitlement } from "../server/entitlements.js";
+import { getAccountHistory, type AccountHistoryEntry } from "../server/grants.js";
+import { getBillingMessages, getBillingOptions, getBillingRoutes } from "../server/options.js";
+import { findAccountById, getBillingPlans, getPaymentProvider } from "../server/plans.js";
+import { listOpenRequests, type OpenPaymentRequest } from "../server/requests.js";
+import { AccessBadge } from "../ui/access-badge.js";
+import { formatDay, formatLastDay, formatPeriod } from "../ui/format.js";
+import { GrantForm } from "../ui/grant-form.js";
+import { AccountLookup, GrantHistory, type GrantHistoryRow } from "../ui/grant-history.js";
+import { PaymentForm } from "../ui/payment-form.js";
+import { PaymentRequestList, type PaymentRequestRow } from "../ui/payment-requests.js";
+import { PricingTiles } from "../ui/pricing-tiles.js";
+import { CurrentAccessBadge } from "./access.js";
+import { dismissRequestAction, findAccountAction, grantPlanAction, grantRequestAction, revokeGrantAction, startPaymentAction } from "./actions.js";
+import { getBillingContext } from "./context.js";
+import { getCurrentEntitlement } from "./current-entitlement.js";
+import { getPlanPaymentHref } from "./pricing.js";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export interface PaymentPageProps {
+  readonly searchParams?: SearchParams;
+}
+
+const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:flex sft:w-full sft:flex-col sft:gap-4 sft:sm:max-w-md sft:px-4 sft:py-4";
+const STACK_CLASS = "sft:flex sft:flex-col sft:gap-4";
+const LEAD_CLASS = "sft:m-0 sft:font-sans sft:text-sm sft:text-muted";
+const NOTICE_CLASS =
+  "sft:m-0 sft:rounded-control sft:border sft:border-border-strong sft:bg-surface-raised sft:px-4 sft:py-2.5 sft:font-sans sft:text-sm sft:text-foreground";
+
+async function readParam(searchParams: SearchParams | undefined, name: string): Promise<string | undefined> {
+  const value = (await searchParams)?.[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function isCheckoutResult(value: string | undefined): value is CheckoutResult {
+  return CHECKOUT_RESULTS.some((result) => result === value);
+}
+
+/**
+ * The plans and, with `?plan=<id>`, the order: the plan's price and the provider's form (the
+ * invoice request of the manual adapter, a checkout button of a hosted provider). Without a session
+ * it sends the visitor to log in and back. A read-only account reaches it too: it is where to pay.
+ * A hosted checkout comes back with `?checkout=success` or `?checkout=cancelled`, shown as a notice
+ * (the access itself changes when the provider's webhook confirms the payment).
+ */
+export async function PaymentPage({ searchParams }: PaymentPageProps) {
+  const config = getSoftureConfig();
+  const route = getBillingRoutes(config).payment;
+  const planId = await readParam(searchParams, PLAN_FIELD);
+  const checkout = await readParam(searchParams, CHECKOUT_PARAM);
+  const user = await requireUser({ next: planId === undefined ? route : getPlanPaymentHref(route, planId), searchParams: await searchParams });
+  const provider = getPaymentProvider(config);
+  const messages = getBillingMessages(config);
+  const copy = messages.payment;
+  const plans = getBillingPlans(config);
+  const plan = planId === undefined ? undefined : findPlan(plans, planId);
+  const planName = plan === undefined ? "" : getLocalizedText(plan.name, config.locale);
+  const checkoutNotice = isCheckoutResult(checkout) ? (checkout === "success" ? copy.checkoutSuccess : copy.checkoutCancelled) : null;
+  const entitlement = await getCurrentEntitlement();
+  // Lifetime access leaves nothing to pay for: no order form (startPayment refuses it too).
+  const hasLifetime = entitlement?.status === "paid" && entitlement.endsAt === null;
+  return (
+    <main className={LAYOUT_CLASS}>
+      <Card title={copy.title} subtitle={copy.lead}>
+        <div className={STACK_CLASS}>
+          {checkoutNotice === null ? null : (
+            <p role="status" className={NOTICE_CLASS} data-checkout={checkout}>
+              {checkoutNotice}
+            </p>
+          )}
+          <div>
+            <CurrentAccessBadge />
+          </div>
+          {hasLifetime ? (
+            <p role="status" className={NOTICE_CLASS} data-lifetime="true">
+              {copy.lifetime}
+            </p>
+          ) : null}
+          <PricingTiles
+            plans={plans}
+            messages={messages}
+            locale={config.locale}
+            getPlanHref={(candidate) => getPlanPaymentHref(route, candidate.id)}
+            selectedPlanId={plan?.id}
+            label={copy.plansLabel}
+          />
+        </div>
+      </Card>
+      {plan === undefined || hasLifetime ? null : (
+        <Card
+          title={copy.orderTitle}
+          subtitle={formatMessage(copy.orderLead, { plan: planName, price: formatPrice(plan.price, config.locale), period: formatPeriod(plan.period, config.locale, messages) })}
+        >
+          <div className={STACK_CLASS}>
+            {provider.collectsInvoiceDetails ? <p className={LEAD_CLASS}>{formatMessage(copy.invoiceLead, { email: user.email })}</p> : null}
+            <PaymentForm
+              action={startPaymentAction}
+              planId={plan.id}
+              planName={planName}
+              email={user.email}
+              collectsInvoiceDetails={provider.collectsInvoiceDetails}
+              messages={messages}
+              locale={config.locale}
+            />
+            <div>
+              <ButtonLink href={route} variant="ghost" size="sm">
+                {copy.changePlan}
+              </ButtonLink>
+            </div>
+          </div>
+        </Card>
+      )}
+    </main>
+  );
+}
+
+/** The plan's name in the app's locale, or its id when the config no longer has it. */
+function getPlanName(plans: readonly Plan[], planId: string, locale: Locale): string {
+  const plan = findPlan(plans, planId);
+  return plan === undefined ? planId : getLocalizedText(plan.name, locale);
+}
+
+interface RowContext {
+  readonly config: SoftureConfig;
+  readonly messages: BillingMessages;
+  readonly plans: readonly Plan[];
+}
+
+function getHistoryHref(config: SoftureConfig, userId: string): string {
+  return `${getBillingRoutes(config).admin}?${new URLSearchParams({ [ACCOUNT_PARAM]: userId }).toString()}`;
+}
+
+function toRequestRow(request: OpenPaymentRequest, { config, messages, plans }: RowContext): PaymentRequestRow {
+  const copy = messages.admin.requests;
+  const values = { email: request.email, plan: getPlanName(plans, request.planId, config.locale) };
+  const { invoice } = request;
+  const details = [formatMessage(copy.requestedOn, { date: formatDay(request.requestedAt, config.locale, config.timezone) })];
+  if (request.price !== null) details.push(formatMessage(copy.price, { price: formatPrice(request.price, config.locale) }));
+  if (invoice === null) details.push(copy.noInvoice);
+  else {
+    details.push(formatMessage(copy.invoice, { name: invoice.name, address: invoice.address }));
+    if (invoice.taxId !== null) details.push(formatMessage(copy.taxId, { taxId: invoice.taxId }));
+  }
+  return {
+    id: request.id,
+    title: formatMessage(copy.line, values),
+    details,
+    historyHref: getHistoryHref(config, request.userId),
+    grantLabel: formatMessage(copy.grantLabel, values),
+    dismissLabel: formatMessage(copy.dismissLabel, values),
+  };
+}
+
+function describeGrant(grant: PaymentGrant | null, { config, messages }: RowContext): string {
+  const copy = messages.admin.history;
+  if (grant === null) return copy.noGrant;
+  if (grant.kind === "lifetime") return copy.lifetime;
+  return formatMessage(copy.period, { from: formatDay(grant.from, config.locale, config.timezone), to: formatLastDay(grant.until, config.locale, config.timezone) });
+}
+
+function toHistoryRow(entry: AccountHistoryEntry, context: RowContext): GrantHistoryRow {
+  const { config, messages, plans } = context;
+  const copy = messages.admin.history;
+  const plan = getPlanName(plans, entry.planId, config.locale);
+  const formatDate = (date: Date) => formatDay(date, config.locale, config.timezone);
+  if (entry.source === "manual") {
+    const isActive = entry.status === "active";
+    return {
+      id: entry.id,
+      title: formatMessage(entry.isFromRequest ? copy.fromRequest : copy.manual, { plan }),
+      statusText: isActive || entry.revokedAt === null ? copy.active : formatMessage(copy.revokedOn, { date: formatDate(entry.revokedAt) }),
+      isCurrent: isActive,
+      details: [
+        entry.price === null
+          ? formatMessage(copy.grantedOn, { date: formatDate(entry.at) })
+          : formatMessage(copy.grantedFor, { amount: formatPrice(entry.price, config.locale), date: formatDate(entry.at) }),
+        describeGrant(entry.grant, context),
+      ],
+      revokeLabel: isActive ? formatMessage(copy.revokeLabel, { plan, date: formatDate(entry.at) }) : null,
+    };
+  }
+  const isPaid = entry.status === "paid";
+  const formatAmount = (amount: number) => formatPrice({ amount, currency: entry.currency }, config.locale);
+  let statusText = copy.paid;
+  if (!isPaid && entry.refundedAt !== null) statusText = formatMessage(copy.refundedOn, { date: formatDate(entry.refundedAt) });
+  else if (entry.refundedAmount > 0) statusText = formatMessage(copy.partlyRefunded, { amount: formatAmount(entry.refundedAmount) });
+  return {
+    id: entry.id,
+    title: formatMessage(copy.provider, { plan, provider: entry.provider }),
+    statusText,
+    isCurrent: isPaid,
+    details: [
+      formatMessage(copy.paidOn, { amount: formatAmount(entry.amount), date: formatDate(entry.at) }),
+      describeGrant(entry.grant, context),
+    ],
+    revokeLabel: null,
+  };
+}
+
+export interface BillingAdminPageProps {
+  readonly searchParams?: SearchParams;
+}
+
+/**
+ * The admin page of manual payments: the open invoice requests (grant or dismiss each), the grant
+ * form, and an account's history (`?account=<id>`, reached by the email lookup or a request's
+ * link) with its access and a revoke button on each active manual grant. Anyone without the role
+ * of `billing({ adminRole })`, signed in or not, gets Next's "not found".
+ */
+export async function BillingAdminPage({ searchParams }: BillingAdminPageProps) {
+  const config = getSoftureConfig();
+  await requireRole(getBillingOptions(config).adminRole);
+  const messages = getBillingMessages(config);
+  const plans = getBillingPlans(config);
+  const context: RowContext = { config, messages, plans };
+  const ctx = await getBillingContext(config);
+  const requests = (await listOpenRequests(ctx)).map((request) => toRequestRow(request, context));
+  const accountId = await readParam(searchParams, ACCOUNT_PARAM);
+  const account = accountId === undefined ? null : await findAccountById(ctx, accountId);
+  const entitlement = account === null ? null : await getEntitlement(ctx, account.id);
+  const history = account === null ? [] : (await getAccountHistory(ctx, account.id)).map((entry) => toHistoryRow(entry, context));
+  const planOptions = plans.map((plan) => ({ value: plan.id, label: getLocalizedText(plan.name, config.locale) }));
+  return (
+    <main className={LAYOUT_CLASS}>
+      <Card title={messages.admin.requests.title} subtitle={messages.admin.requests.lead}>
+        <PaymentRequestList requests={requests} grantAction={grantRequestAction} dismissAction={dismissRequestAction} messages={messages} />
+      </Card>
+      <Card title={messages.admin.title} subtitle={messages.admin.lead}>
+        {planOptions.length === 0 ? (
+          <EmptyState title={messages.admin.noPlans} />
+        ) : (
+          <GrantForm action={grantPlanAction} plans={planOptions} messages={messages} locale={config.locale} />
+        )}
+      </Card>
+      <Card title={messages.admin.history.title} subtitle={messages.admin.history.lead}>
+        <div className={STACK_CLASS}>
+          <AccountLookup action={findAccountAction} messages={messages} locale={config.locale} />
+          {account === null ? null : (
+            <section className={STACK_CLASS} aria-label={formatMessage(messages.admin.history.accountTitle, { email: account.email })}>
+              <p className={LEAD_CLASS}>{formatMessage(messages.admin.history.accountTitle, { email: account.email })}</p>
+              {entitlement === null ? null : (
+                <div>
+                  <AccessBadge entitlement={entitlement} messages={messages} locale={config.locale} timezone={config.timezone} />
+                </div>
+              )}
+              <GrantHistory rows={history} revokeAction={revokeGrantAction} messages={messages} />
+            </section>
+          )}
+        </div>
+      </Card>
+    </main>
+  );
+}

package/src/next/pricing.tsx

@@ -0,0 +1,39 @@
+// The pricing tiles wired to the registered config, for any server component (a landing or a
+// pricing page): `<Pricing LinkComponent={Link} />`. Each tile's button opens the payment page with
+// its plan; the page asks a visitor without a session to log in first.
+import { getSoftureConfig } from "@softure-ai/core/next";
+import type { ClassNames, LinkComponentType } from "@softure-ai/ui";
+import { PLAN_FIELD } from "../fields.js";
+import { getBillingMessages, getBillingRoutes } from "../server/options.js";
+import { getBillingPlans } from "../server/plans.js";
+import { PricingTiles, type PricingTilesSlot } from "../ui/pricing-tiles.js";
+
+export interface PricingProps {
+  /** The app's link component, e.g. Next's `Link`; a plain `<a>` when omitted. */
+  readonly LinkComponent?: LinkComponentType;
+  readonly classNames?: ClassNames<PricingTilesSlot>;
+  readonly unstyled?: boolean;
+}
+
+/** The payment page with a plan chosen. */
+export function getPlanPaymentHref(paymentRoute: string, planId: string): string {
+  return `${paymentRoute}?${PLAN_FIELD}=${encodeURIComponent(planId)}`;
+}
+
+export function Pricing({ LinkComponent, classNames, unstyled }: PricingProps) {
+  const config = getSoftureConfig();
+  const messages = getBillingMessages(config);
+  const payment = getBillingRoutes(config).payment;
+  return (
+    <PricingTiles
+      plans={getBillingPlans(config)}
+      messages={messages}
+      locale={config.locale}
+      getPlanHref={(plan) => getPlanPaymentHref(payment, plan.id)}
+      LinkComponent={LinkComponent}
+      label={messages.payment.plansLabel}
+      classNames={classNames}
+      unstyled={unstyled}
+    />
+  );
+}

package/src/next/route.ts

@@ -0,0 +1,57 @@
+// The Stripe webhook route. Mount it with a rename in app/api/billing/webhook/route.ts:
+// `export { stripeWebhookRoute as POST } from "@softure-ai/billing/next"`, and point a Stripe
+// webhook endpoint at it for `checkout.session.completed`, `checkout.session.async_payment_succeeded`
+// and `charge.refunded`.
+//
+// Stripe calls it from its own servers: no session, no cookies, so it stays outside any auth
+// guard. There is no rate limit on purpose: Stripe sends from a few addresses, and a bucket would
+// drop real payments. The body is capped and the signature checked before the database is touched.
+import { errorLogLabel } from "@softure-ai/core";
+import { readSmallBody } from "@softure-ai/security";
+import { receiveStripeWebhook } from "../server/payments.js";
+import { STRIPE_SIGNATURE_HEADER } from "../stripe-webhook.js";
+import { getBillingContext } from "./context.js";
+
+export const STRIPE_WEBHOOK_SECRET_ENV = "STRIPE_WEBHOOK_SECRET";
+/** Stripe's checkout and charge events are a few kilobytes; anything far larger is not Stripe. */
+export const STRIPE_WEBHOOK_MAX_BYTES = 256 * 1024;
+
+const NO_STORE = { "cache-control": "no-store" };
+
+function answer(status: number): Response {
+  return new Response(null, { status, headers: NO_STORE });
+}
+
+/**
+ * Handles one delivery: 200 once it is recorded (also again, and for events billing ignores), 400
+ * for a delivery that is not signed by Stripe within the tolerance, 413 for an oversized body, 500
+ * when the secret is missing or the database fails, so Stripe retries. A payment whose account or
+ * plan is gone answers 200 and is logged: a retry cannot fix it, the owner refunds it in Stripe.
+ */
+export async function stripeWebhookRoute(request: Request): Promise<Response> {
+  const secret = (process.env[STRIPE_WEBHOOK_SECRET_ENV] ?? "").trim();
+  if (secret === "") {
+    console.error(`@softure-ai/billing: the Stripe webhook has no secret; set ${STRIPE_WEBHOOK_SECRET_ENV}`);
+    return answer(500);
+  }
+  const body = await readSmallBody(request, { maxBytes: STRIPE_WEBHOOK_MAX_BYTES });
+  if (!body.ok) return answer(body.error === "security.body_too_large" ? 413 : 400);
+
+  let received;
+  try {
+    received = await receiveStripeWebhook(await getBillingContext(), {
+      payload: body.value,
+      signature: request.headers.get(STRIPE_SIGNATURE_HEADER),
+      secret,
+    });
+  } catch (error) {
+    console.error(`@softure-ai/billing: a Stripe webhook failed: ${errorLogLabel(error)}`);
+    return answer(500);
+  }
+  if (!received.ok) return answer(400);
+  const { outcome } = received.value;
+  if (outcome.status === "refused") {
+    console.error(`@softure-ai/billing: the paid Stripe checkout ${outcome.checkoutId} granted nothing (${outcome.error}); refund it in the Stripe dashboard`);
+  }
+  return answer(200);
+}

package/src/options.ts

@@ -0,0 +1,128 @@
+// The options an app passes to `billing({ ... })` in softure.config.ts, parsed at startup.
+import { LOCALES } from "@softure-ai/core";
+import { z } from "zod";
+import { parseDay } from "./calendar.js";
+import { PERIOD_UNITS, type PlanPeriod } from "./contract.js";
+import { isPaymentProvider, type PaymentProvider } from "./payment.js";
+import { isSupportedCurrency } from "./price.js";
+
+/** The longest trial or reminder window, in days. */
+export const MAX_DAYS = 365;
+/** The most plans the config declares. */
+export const MAX_PLANS = 12;
+/** The most feature lines one plan lists. */
+export const MAX_FEATURES = 20;
+/** The highest price, in the currency's minor unit. */
+export const MAX_PRICE_AMOUNT = 100_000_000;
+/** The most units one period counts. */
+export const MAX_PERIOD_COUNT = 1000;
+/** How long an open invoice request waits by default before it expires, in days. */
+export const DEFAULT_REQUEST_EXPIRY_DAYS = 30;
+/**
+ * What a partial refund of a provider payment does to access: `pro_rata` takes back the refunded
+ * share of the payment's unused days, `keep_access` takes back nothing until the whole payment is
+ * refunded.
+ */
+export const PARTIAL_REFUND_POLICIES = ["pro_rata", "keep_access"] as const;
+export type PartialRefundPolicy = (typeof PARTIAL_REFUND_POLICIES)[number];
+
+const daysSchema = z.number().int().min(0).max(MAX_DAYS);
+
+/** Kebab-case, at most 64 characters. */
+const PLAN_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/** Copy per locale; a locale without its own text falls back to `en`. */
+const localizedTextSchema = z
+  .partialRecord(z.enum(LOCALES), z.string().trim().min(1).max(500))
+  .refine((text) => text.en !== undefined, "needs at least an en text");
+
+const periodSchema = z.union([
+  z.enum([...PERIOD_UNITS, "lifetime"]).transform((unit): PlanPeriod => (unit === "lifetime" ? { unit } : { unit, count: 1 })),
+  z.strictObject({ unit: z.enum(PERIOD_UNITS), count: z.number().int().min(1).max(MAX_PERIOD_COUNT).default(1) }),
+  z.strictObject({ unit: z.literal("lifetime") }),
+]);
+
+const planSchema = z.strictObject({
+  /** Kebab-case and unique, e.g. `monthly`; the payment page and the providers name the plan by it. */
+  id: z.string().max(64, "must be at most 64 characters").regex(PLAN_ID_PATTERN, "must be kebab-case, e.g. pro-yearly"),
+  name: localizedTextSchema,
+  description: localizedTextSchema.optional(),
+  price: z.strictObject({
+    /** In the currency's minor unit: 2900 is 29.00 PLN. */
+    amount: z.number().int().min(0).max(MAX_PRICE_AMOUNT),
+    currency: z.string().refine((code) => /^[A-Z]{3}$/.test(code) && isSupportedCurrency(code), "must be an upper-case ISO 4217 currency code billing knows, e.g. PLN"),
+  }),
+  /** `"month"`, `"year"`, `"lifetime"`, or `{ unit, count }` such as `{ unit: "month", count: 3 }`. */
+  period: periodSchema,
+  features: z.array(localizedTextSchema).max(MAX_FEATURES).default([]),
+  isFeatured: z.boolean().default(false),
+});
+
+export const billingOptionsSchema = z.strictObject({
+  trial: z
+    .strictObject({
+      /** Length of the trial every account starts with, the registration day included; 0 for none. */
+      days: daysSchema.default(14),
+      /** From how many days left the trial notice shows; 0 never. */
+      reminderDays: daysSchema.default(3),
+      /**
+       * The first day a trial can start, `YYYY-MM-DD` in the app's time zone: an account created
+       * before it (without an entitlement row) gets its trial from this day. For turning billing on
+       * for accounts that already exist.
+       */
+      startsAt: z
+        .string()
+        .refine((day) => parseDay(day) !== null, "must be a calendar day as YYYY-MM-DD, e.g. 2026-11-01")
+        .optional(),
+    })
+    .prefault({}),
+  paid: z
+    .strictObject({
+      /** From how many days left the renewal notice shows; 0 never. Lifetime access never ends. */
+      reminderDays: daysSchema.default(7),
+    })
+    .prefault({}),
+  requests: z
+    .strictObject({
+      /**
+       * Days an open invoice request waits for the admin, counted from the buyer's last ask:
+       * `expireStaleRequests` (run daily) then closes it as `expired` and clears its invoice
+       * details. From 1 to 365.
+       */
+      expireAfterDays: z.number().int().min(1).max(MAX_DAYS).default(DEFAULT_REQUEST_EXPIRY_DAYS),
+    })
+    .prefault({}),
+  /** The plans the pricing tiles and the payment page offer, in the order they show them. */
+  plans: z
+    .array(planSchema)
+    .max(MAX_PLANS)
+    .default([])
+    .superRefine((plans, context) => {
+      const seen = new Set<string>();
+      plans.forEach((plan, index) => {
+        if (seen.has(plan.id)) context.addIssue({ code: "custom", message: `repeats the plan id "${plan.id}"`, path: [index, "id"] });
+        seen.add(plan.id);
+      });
+    }),
+  /** The payment adapter, e.g. `manual({ onRequest })`; the payment page needs one. */
+  payment: z.custom<PaymentProvider>(isPaymentProvider, "must be a payment provider such as manual()").optional(),
+  /**
+   * A partial refund of a provider payment: `pro_rata` takes back the share of the payment's unused
+   * days that the refunded money is of the money not refunded before (whole days, rounded down);
+   * `keep_access` takes back nothing. Either way the refund that completes the amount acts as a
+   * full refund, and a lifetime ends only then.
+   */
+  partialRefunds: z.enum(PARTIAL_REFUND_POLICIES).default("pro_rata"),
+  /** The auth role that may grant plans in the admin page; declared in `auth({ roles })` unless `admin`. */
+  adminRole: z.string().min(1).default("admin"),
+}).superRefine((options, context) => {
+  const { payment } = options;
+  if (payment?.checkPrice === undefined) return;
+  options.plans.forEach((plan, index) => {
+    const problem = payment.checkPrice?.(plan.price) ?? null;
+    if (problem !== null) context.addIssue({ code: "custom", message: problem, path: ["plans", index, "price"] });
+  });
+});
+
+export type BillingOptionsInput = z.input<typeof billingOptionsSchema>;
+export type BillingOptions = z.output<typeof billingOptionsSchema>;

package/src/payment.ts

@@ -0,0 +1,77 @@
+// The contract between the billing module and a payment provider: the manual adapter here, a card
+// or transfer provider later (MO-3). The module validates the request and counts the attempt; the
+// provider starts the payment and says where the buyer goes next. Access is granted afterwards,
+// through `grantPlan` (an admin for manual payments, a verified webhook for a provider).
+import type { Err, ModuleContext, Ok } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import type { Plan, PlanPrice } from "./contract.js";
+
+/** The signed-in account that pays. */
+export interface PaymentAccount {
+  readonly id: string;
+  readonly email: string;
+}
+
+/** What an invoice needs, as the buyer typed it (trimmed). */
+export interface InvoiceDetails {
+  /** A person's or a company's name. */
+  readonly name: string;
+  /** A tax number such as a Polish NIP or an EU VAT id; null when not given. */
+  readonly taxId: string | null;
+  readonly address: string;
+}
+
+export interface PaymentRequest {
+  readonly plan: Plan;
+  readonly account: PaymentAccount;
+  /** The details the payment page asked for; null when the provider collects its own. */
+  readonly invoice: InvoiceDetails | null;
+  /** The payment page as an absolute URL, where a hosted checkout sends the buyer back. */
+  readonly returnUrl: string;
+}
+
+/** Where the buyer goes next. */
+export type PaymentStart =
+  /** A hosted checkout (e.g. a provider's payment page); the browser is sent there. */
+  | { readonly type: "redirect"; readonly url: string }
+  /** The request was handed over (e.g. an invoice requested); access follows once it is paid. */
+  | { readonly type: "requested" };
+
+export type PaymentContext = ModuleContext<Queryable>;
+
+/** A payment adapter for `billing({ payment })`, e.g. `manual({ onRequest })`. */
+export interface PaymentProvider {
+  /** A short lowercase name for logs, e.g. `manual`. */
+  readonly name: string;
+  /** Whether the payment page asks for invoice details before `startPayment`. */
+  readonly collectsInvoiceDetails: boolean;
+  /**
+   * Whether `startPayment` hands a request to the owner and answers `requested` (the manual
+   * adapter) rather than sending the buyer to a checkout. Such a request is stored before the
+   * call, and the call is made once per open request: asking again only refreshes the stored one.
+   */
+  readonly handsOverRequests: boolean;
+  /**
+   * Starts paying for `request.plan`. An expected failure (the provider refused, a notification
+   * could not be sent) is `billing.payment_failed`; anything thrown is a bug or an outage.
+   */
+  startPayment(ctx: PaymentContext, request: PaymentRequest): Promise<Ok<PaymentStart> | Err<"billing.payment_failed">>;
+  /**
+   * Why the provider cannot charge `price` (e.g. a fraction of its currency's unit), or null when it
+   * can. Run for every plan when the config loads, so the deployer meets it, not the buyer.
+   */
+  checkPrice?(price: PlanPrice): string | null;
+}
+
+export function isPaymentProvider(value: unknown): value is PaymentProvider {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<Record<keyof PaymentProvider, unknown>>;
+  return (
+    typeof candidate.name === "string" &&
+    candidate.name !== "" &&
+    typeof candidate.collectsInvoiceDetails === "boolean" &&
+    typeof candidate.handsOverRequests === "boolean" &&
+    typeof candidate.startPayment === "function" &&
+    (candidate.checkPrice === undefined || typeof candidate.checkPrice === "function")
+  );
+}

package/src/plans.ts

@@ -0,0 +1,63 @@
+// Plans from `billing({ plans })`, pure: how long a payment of a plan gives access and the change it
+// makes to an entitlement. Periods run in local calendar days, like trials, so a month bought on
+// 3 October covers every day up to 2 November and ends when 3 November begins in the app's time zone.
+import type { Locale } from "@softure-ai/core";
+import { getDayNumber, getStartOfDay } from "./calendar.js";
+import type { EntitlementEvent, EntitlementRecord, LocalizedText, Plan, PlanPeriod } from "./contract.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAYS_PER_WEEK = 7;
+const MONTHS_PER_YEAR = 12;
+
+/** The text in `locale`, else the `en` text (the options require one). */
+export function getLocalizedText(text: LocalizedText, locale: Locale): string {
+  return text[locale] ?? text.en ?? "";
+}
+
+/** The plan with this id, or undefined. */
+export function findPlan(plans: readonly Plan[], planId: string): Plan | undefined {
+  return plans.find((plan) => plan.id === planId);
+}
+
+/** A day number `months` calendar months later; a day the target month lacks becomes its last day. */
+function addMonths(dayNumber: number, months: number): number {
+  const date = new Date(dayNumber * DAY_MS);
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth() + months;
+  const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+  return Math.floor(Date.UTC(year, month, Math.min(date.getUTCDate(), lastDay)) / DAY_MS);
+}
+
+/**
+ * The end of one period begun at `start`: the start of the local day one period after the start
+ * day. The start day counts as the first day, as for trials. Lifetime periods have no end.
+ */
+export function getPeriodEnd(start: Date, period: Exclude<PlanPeriod, { unit: "lifetime" }>, timezone: string): Date {
+  const day = getDayNumber(start, timezone);
+  switch (period.unit) {
+    case "day":
+      return getStartOfDay(day + period.count, timezone);
+    case "week":
+      return getStartOfDay(day + period.count * DAYS_PER_WEEK, timezone);
+    case "month":
+      return getStartOfDay(addMonths(day, period.count), timezone);
+    case "year":
+      return getStartOfDay(addMonths(day, period.count * MONTHS_PER_YEAR), timezone);
+  }
+}
+
+/** The latest of some instants. */
+function getLatest(first: Date, ...rest: readonly Date[]): Date {
+  return rest.reduce((latest, instant) => (instant > latest ? instant : latest), first);
+}
+
+/**
+ * The change one payment of `plan` makes to `record` at `now`. A paid period starts when the access
+ * the account already has ends (a running trial or paid access), so paying early loses no day; a
+ * lifetime plan grants lifetime access.
+ */
+export function getPlanGrant(record: EntitlementRecord, plan: Plan, now: Date, timezone: string): EntitlementEvent {
+  if (plan.period.unit === "lifetime") return { type: "grant_lifetime" };
+  const start = getLatest(now, record.trialEndsAt, ...(record.paidUntil === null ? [] : [record.paidUntil]));
+  return { type: "grant", until: getPeriodEnd(start, plan.period, timezone) };
+}