@softure-ai/billing 0.0.0-stage → 0.1.6

package/src/stripe.ts

@@ -0,0 +1,130 @@
+// The Stripe adapter (https://docs.stripe.com/api/checkout/sessions/create): a one-time Checkout
+// session per payment, paid on Stripe's page; the verified webhook (`stripeWebhookRoute` in
+// `/next`) grants the plan once Stripe reports the money. Stripe's HTTP API through `fetch`, like
+// mailing's `resend()`: no SDK, and tests inject `fetch`.
+import { err, ok } from "@softure-ai/core";
+import { CHECKOUT_PARAM, PLAN_FIELD, type CheckoutResult } from "./fields.js";
+import type { PaymentContext, PaymentProvider, PaymentRequest } from "./payment.js";
+import { getLocalizedText } from "./plans.js";
+import { STRIPE_PROVIDER } from "./server/payments.js";
+import { describeStripePriceProblem, toStripeAmount } from "./stripe-currency.js";
+import { STRIPE_METADATA } from "./stripe-webhook.js";
+
+export const STRIPE_API_BASE = "https://api.stripe.com";
+export const STRIPE_SECRET_KEY_ENV = "STRIPE_SECRET_KEY";
+/** How long the Checkout request may take before the buyer sees `billing.payment_failed`. */
+export const STRIPE_TIMEOUT_MS = 10_000;
+
+export interface StripeOptions {
+  /**
+   * The secret API key (`sk_test_...` in the sandbox). Default: `process.env.STRIPE_SECRET_KEY`,
+   * read on every payment, so the configuration loads at build time without the secret.
+   */
+  readonly secretKey?: string;
+  /** Default: `https://api.stripe.com`. For a proxy or a test server. */
+  readonly apiBase?: string;
+  /** Injected in tests; default: the global `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+
+function getReturnUrl(returnUrl: string, result: CheckoutResult, planId: string | null): string {
+  const url = new URL(returnUrl);
+  if (planId !== null) url.searchParams.set(PLAN_FIELD, planId);
+  url.searchParams.set(CHECKOUT_PARAM, result);
+  return url.toString();
+}
+
+/**
+ * The form body of `POST /v1/checkout/sessions` for one payment of the plan: its price as a one-off
+ * line item in Stripe's unit (`toStripeAmount`), the account in `client_reference_id` and the metadata the webhook reads (copied onto
+ * the PaymentIntent, so the charge in Stripe's dashboard names the account too).
+ */
+export function getCheckoutSessionParams(ctx: Pick<PaymentContext, "config">, request: PaymentRequest): URLSearchParams {
+  const { plan, account } = request;
+  const { locale } = ctx.config;
+  const unitAmount = toStripeAmount(plan.price);
+  // The config refuses such a price (`checkPrice`) and `startPayment` checks it first.
+  if (unitAmount === null) throw new Error(`@softure-ai/billing: stripe() cannot charge the price of plan "${plan.id}"`);
+  const params = new URLSearchParams({
+    mode: "payment",
+    locale,
+    client_reference_id: account.id,
+    customer_email: account.email,
+    success_url: getReturnUrl(request.returnUrl, "success", null),
+    cancel_url: getReturnUrl(request.returnUrl, "cancelled", plan.id),
+    "line_items[0][quantity]": "1",
+    "line_items[0][price_data][currency]": plan.price.currency.toLowerCase(),
+    "line_items[0][price_data][unit_amount]": String(unitAmount),
+    "line_items[0][price_data][product_data][name]": getLocalizedText(plan.name, locale),
+    [`metadata[${STRIPE_METADATA.userId}]`]: account.id,
+    [`metadata[${STRIPE_METADATA.planId}]`]: plan.id,
+    [`payment_intent_data[metadata][${STRIPE_METADATA.userId}]`]: account.id,
+    [`payment_intent_data[metadata][${STRIPE_METADATA.planId}]`]: plan.id,
+  });
+  if (plan.description !== undefined) params.set("line_items[0][price_data][product_data][description]", getLocalizedText(plan.description, locale));
+  return params;
+}
+
+/** The hosted page's URL from Stripe's answer, or null when the answer has none. */
+function readCheckoutUrl(payload: unknown): string | null {
+  if (typeof payload !== "object" || payload === null || !Object.hasOwn(payload, "url")) return null;
+  const url: unknown = (payload as Record<string, unknown>).url;
+  return typeof url === "string" && url.startsWith("https://") ? url : null;
+}
+
+/** Stripe's error type and code for the log; its message can echo the request back. */
+function describeStripeError(payload: unknown): string {
+  const error: unknown = typeof payload === "object" && payload !== null ? (payload as Record<string, unknown>).error : null;
+  if (typeof error !== "object" || error === null) return "no error body";
+  const { type, code } = error as Record<string, unknown>;
+  return [type, code].filter((part) => typeof part === "string").join("/") || "no error type";
+}
+
+/** `billing({ payment: stripe() })`: card, BLIK and transfer payments on Stripe Checkout. */
+export function stripe(options: StripeOptions = {}): PaymentProvider {
+  const apiBase = options.apiBase ?? STRIPE_API_BASE;
+  return {
+    name: STRIPE_PROVIDER,
+    collectsInvoiceDetails: false,
+    handsOverRequests: false,
+    checkPrice: describeStripePriceProblem,
+    async startPayment(ctx, request) {
+      const priceProblem = describeStripePriceProblem(request.plan.price);
+      if (priceProblem !== null) {
+        // Only a config built around billing({ ... }) gets here; the options schema refuses it.
+        console.error(`@softure-ai/billing: plan "${request.plan.id}": ${priceProblem}`);
+        return err("billing.payment_failed");
+      }
+      const secretKey = (options.secretKey ?? process.env[STRIPE_SECRET_KEY_ENV] ?? "").trim();
+      if (secretKey === "") {
+        // A deployment without the key cannot take payments until it is set; never the buyer's fault.
+        console.error(`@softure-ai/billing: stripe has no secret key; set ${STRIPE_SECRET_KEY_ENV} or pass stripe({ secretKey })`);
+        return err("billing.payment_failed");
+      }
+      const fetchImpl = options.fetch ?? fetch;
+      let response: Response;
+      try {
+        response = await fetchImpl(new URL("/v1/checkout/sessions", apiBase), {
+          method: "POST",
+          headers: { Authorization: `Bearer ${secretKey}`, "Content-Type": "application/x-www-form-urlencoded" },
+          body: getCheckoutSessionParams(ctx, request),
+          signal: AbortSignal.timeout(STRIPE_TIMEOUT_MS),
+          cache: "no-store",
+        });
+      } catch (error) {
+        // A timeout or a network failure: nothing was created that the buyer can pay.
+        console.error(`@softure-ai/billing: the Stripe checkout for plan "${request.plan.id}" could not be created: ${error instanceof Error ? error.name : typeof error}`);
+        return err("billing.payment_failed");
+      }
+      const payload: unknown = await response.json().catch(() => null);
+      const url = response.ok ? readCheckoutUrl(payload) : null;
+      if (url === null) {
+        console.error(
+          `@softure-ai/billing: Stripe refused the checkout for plan "${request.plan.id}" (HTTP ${String(response.status)}, ${response.ok ? "no checkout url" : describeStripeError(payload)})`,
+        );
+        return err("billing.payment_failed");
+      }
+      return ok({ type: "redirect", url });
+    },
+  };
+}

package/src/ui/access-badge.tsx

@@ -0,0 +1,64 @@
+// A compact label of where an account stands: "Trial · 5 days left", "Paid · until November 30,
+// 2026", "Lifetime access" or "Read-only". Server-safe: it renders from props, so a server
+// component passes the entitlement it read (`CurrentAccessBadge` in `/next` does).
+import { formatMessage, type Locale } from "@softure-ai/core";
+import { type ClassNames, createSlotClassGetter } from "@softure-ai/ui";
+import type { Entitlement } from "../contract.js";
+import type { BillingMessages } from "../messages/index.js";
+import { formatDaysLeft, formatLastDay } from "./format.js";
+
+export type AccessBadgeSlot = "root" | "status" | "detail";
+
+export interface AccessBadgeProps {
+  readonly entitlement: Entitlement;
+  readonly messages: BillingMessages;
+  readonly locale: Locale;
+  /** The app's IANA time zone, for the dates shown. */
+  readonly timezone: string;
+  readonly classNames?: ClassNames<AccessBadgeSlot>;
+  readonly unstyled?: boolean;
+}
+
+type Tone = "neutral" | "success" | "warning" | "danger";
+
+const TONE: Readonly<Record<Tone, string>> = {
+  neutral: "sft:text-foreground",
+  success: "sft:text-success",
+  warning: "sft:text-warning",
+  danger: "sft:text-danger",
+};
+
+function describe(entitlement: Entitlement, messages: BillingMessages, locale: Locale, timezone: string): { status: string; detail?: string; tone: Tone } {
+  switch (entitlement.status) {
+    case "trial":
+      return { status: messages.badge.trial, detail: formatDaysLeft(entitlement.daysLeft, locale, messages), tone: entitlement.isEnding ? "warning" : "neutral" };
+    case "paid":
+      if (entitlement.endsAt === null) return { status: messages.badge.lifetime, tone: "success" };
+      return {
+        status: messages.badge.paid,
+        detail: formatMessage(messages.badge.until, { date: formatLastDay(entitlement.endsAt, locale, timezone) }),
+        tone: entitlement.isEnding ? "warning" : "success",
+      };
+    case "read_only":
+      return { status: messages.badge.readOnly, tone: "danger" };
+  }
+}
+
+export function AccessBadge({ entitlement, messages, locale, timezone, classNames, unstyled }: AccessBadgeProps) {
+  const { status, detail, tone } = describe(entitlement, messages, locale, timezone);
+  const slot = createSlotClassGetter<AccessBadgeSlot>({
+    defaults: {
+      root: "sft:inline-flex sft:items-center sft:gap-1.5 sft:rounded-full sft:border sft:border-border sft:bg-surface sft:px-2.5 sft:py-1 sft:font-sans sft:text-xs",
+      status: `sft:font-medium ${TONE[tone]}`,
+      detail: "sft:text-muted",
+    },
+    classNames,
+    unstyled,
+  });
+  return (
+    <span className={slot("root")} data-status={entitlement.status} data-ending={"isEnding" in entitlement && entitlement.isEnding ? "true" : undefined}>
+      <span className={slot("status")}>{status}</span>
+      {detail === undefined ? null : <span className={slot("detail")}>{detail}</span>}
+    </span>
+  );
+}

package/src/ui/access-notice.tsx

@@ -0,0 +1,73 @@
+// The notice an account sees when its access is about to end or has ended, with a link to pay.
+// It renders nothing while access is not in its reminder window. Server-safe and framework-free:
+// the link goes through an injected `LinkComponent` (Next's `Link` in `/next`).
+import { formatMessage, type Locale } from "@softure-ai/core";
+import { ButtonLink, type ClassNames, createSlotClassGetter, type LinkComponentType } from "@softure-ai/ui";
+import type { Entitlement } from "../contract.js";
+import type { BillingMessages } from "../messages/index.js";
+import { formatLastDay } from "./format.js";
+
+export type AccessNoticeSlot = "root" | "message" | "actions";
+
+export interface AccessNoticeProps {
+  readonly entitlement: Entitlement;
+  readonly messages: BillingMessages;
+  readonly locale: Locale;
+  /** The app's IANA time zone, for the dates shown. */
+  readonly timezone: string;
+  /** Where to pay or renew (`routes.payment`). */
+  readonly paymentHref: string;
+  /** Renders the link; a plain `<a>` when omitted. */
+  readonly LinkComponent?: LinkComponentType;
+  readonly classNames?: ClassNames<AccessNoticeSlot>;
+  readonly unstyled?: boolean;
+}
+
+interface NoticeCopy {
+  readonly text: string;
+  readonly action: string;
+  readonly isEnded: boolean;
+}
+
+/** The notice for this entitlement, or null when there is nothing to say. */
+function getNoticeCopy(entitlement: Entitlement, messages: BillingMessages, locale: Locale, timezone: string): NoticeCopy | null {
+  const copy = messages.notice;
+  switch (entitlement.status) {
+    case "trial":
+      if (!entitlement.isEnding) return null;
+      return { text: formatMessage(copy.trialEnding, { date: formatLastDay(entitlement.endsAt, locale, timezone) }), action: copy.choosePlan, isEnded: false };
+    case "paid":
+      if (!entitlement.isEnding || entitlement.endsAt === null) return null;
+      return { text: formatMessage(copy.paidEnding, { date: formatLastDay(entitlement.endsAt, locale, timezone) }), action: copy.renew, isEnded: false };
+    case "read_only":
+      return entitlement.reason === "trial_ended"
+        ? { text: copy.trialEnded, action: copy.choosePlan, isEnded: true }
+        : { text: copy.paidEnded, action: copy.renew, isEnded: true };
+  }
+}
+
+export function AccessNotice({ entitlement, messages, locale, timezone, paymentHref, LinkComponent, classNames, unstyled }: AccessNoticeProps) {
+  const notice = getNoticeCopy(entitlement, messages, locale, timezone);
+  if (notice === null) return null;
+  const slot = createSlotClassGetter<AccessNoticeSlot>({
+    defaults: {
+      root: `sft:flex sft:flex-col sft:gap-3 sft:rounded-control sft:border sft:px-4 sft:py-2.5 sft:font-sans sft:text-sm sft:text-foreground ${
+        notice.isEnded ? "sft:border-danger/50 sft:bg-danger/10" : "sft:border-border-strong sft:bg-surface-raised"
+      }`,
+      message: "sft:m-0",
+      actions: "sft:flex sft:shrink-0",
+    },
+    classNames,
+    unstyled,
+  });
+  return (
+    <div role="status" className={slot("root")} data-status={entitlement.status}>
+      <p className={slot("message")}>{notice.text}</p>
+      <div className={slot("actions")}>
+        <ButtonLink href={paymentHref} LinkComponent={LinkComponent} variant={notice.isEnded ? "primary" : "secondary"} size="sm" unstyled={unstyled}>
+          {notice.action}
+        </ButtonLink>
+      </div>
+    </div>
+  );
+}

package/src/ui/format.ts

@@ -0,0 +1,25 @@
+// Dates and day counts of an entitlement as the components show them. An end is the first instant
+// without access, so the date shown is the last day with it, in the app's time zone.
+import { formatMessage, selectPlural, type Locale } from "@softure-ai/core";
+import type { PlanPeriod } from "../contract.js";
+import type { BillingMessages } from "../messages/index.js";
+
+/** The last local day covered by an access that ends at `end`, e.g. "October 16, 2026" in en. */
+export function formatLastDay(end: Date, locale: Locale, timezone: string): string {
+  return new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: timezone }).format(new Date(end.getTime() - 1));
+}
+
+/** The local day of an instant, e.g. "October 3, 2026" in en: when something happened, or a first day of access. */
+export function formatDay(instant: Date, locale: Locale, timezone: string): string {
+  return new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: timezone }).format(instant);
+}
+
+export function formatDaysLeft(days: number, locale: Locale, messages: BillingMessages): string {
+  return formatMessage(selectPlural(locale, days, messages.badge.daysLeft), { count: days });
+}
+
+/** How long one payment lasts, as the tiles say it: "per month", "per 3 months", "one-time payment". */
+export function formatPeriod(period: PlanPeriod, locale: Locale, messages: BillingMessages): string {
+  if (period.unit === "lifetime") return messages.pricing.period.lifetime;
+  return formatMessage(selectPlural(locale, period.count, messages.pricing.period[period.unit]), { count: period.count });
+}

package/src/ui/grant-form.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import type { Locale } from "@softure-ai/core";
+import { Button, type ClassNames, createSlotClassGetter, FormError, SelectField, type SelectOption, TextField } from "@softure-ai/ui";
+import { useActionState } from "react";
+import { INITIAL_GRANT_FORM_STATE, type GrantFormState } from "../contract.js";
+import { EMAIL_FIELD, PLAN_FIELD } from "../fields.js";
+import { getBillingErrorMessage, type BillingMessages } from "../messages/index.js";
+
+// The admin form that grants a plan to an account once its payment arrived (the manual adapter):
+// the account's email and the plan. It submits straight to its server action, which checks the
+// admin role first; after a grant it says what the account has now and stays ready for the next.
+
+export type GrantFormAction = (previous: GrantFormState, formData: FormData) => Promise<GrantFormState>;
+
+export type GrantFormSlot = "root" | "form" | "notice";
+
+export interface GrantFormProps {
+  readonly action: GrantFormAction;
+  /** The plans to choose from: id and name in the app's locale. */
+  readonly plans: readonly SelectOption[];
+  readonly messages: BillingMessages;
+  /** Locale of the built-in copy of the ui primitives. */
+  readonly locale?: Locale;
+  readonly classNames?: ClassNames<GrantFormSlot>;
+  readonly unstyled?: boolean;
+}
+
+const DEFAULT_CLASSES: Readonly<Record<GrantFormSlot, string>> = {
+  root: "sft:flex sft:flex-col sft:gap-3 sft:font-sans",
+  form: "sft:flex sft:flex-col sft:gap-3",
+  notice: "sft:m-0 sft:text-sm sft:text-success",
+};
+
+export function GrantForm({ action, plans, messages, locale, classNames, unstyled }: GrantFormProps) {
+  const [state, formAction, isPending] = useActionState(action, INITIAL_GRANT_FORM_STATE);
+  const slot = createSlotClassGetter({ defaults: DEFAULT_CLASSES, classNames, unstyled });
+  const copy = messages.admin;
+  const error = state.error === undefined ? undefined : getBillingErrorMessage(messages, state.error);
+  const isEmailError = state.error === "billing.account_unknown";
+  return (
+    <div className={slot("root")}>
+      <form action={formAction} className={slot("form")}>
+        <TextField
+          // A fresh, empty field after each grant; the typed address after an error.
+          key={`${state.status}:${state.email ?? ""}`}
+          name={EMAIL_FIELD}
+          type="email"
+          label={copy.email}
+          required
+          defaultValue={state.status === "error" ? (state.email ?? "") : ""}
+          error={isEmailError ? error : undefined}
+          locale={locale}
+          unstyled={unstyled}
+        />
+        <SelectField name={PLAN_FIELD} label={copy.plan} options={plans} defaultValue={state.planId} locale={locale} unstyled={unstyled} />
+        <FormError message={isEmailError ? undefined : error} unstyled={unstyled} />
+        <Button type="submit" variant="primary" pending={isPending} unstyled={unstyled}>
+          {isPending ? copy.pending : copy.submit}
+        </Button>
+      </form>
+      {state.status === "granted" ? (
+        <p role="status" className={slot("notice")}>
+          {state.notice}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/src/ui/grant-history.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import type { Locale } from "@softure-ai/core";
+import { Button, type ClassNames, createSlotClassGetter, FormError, TextField } from "@softure-ai/ui";
+import { useActionState } from "react";
+import { INITIAL_ADMIN_ACTION_STATE } from "../contract.js";
+import { EMAIL_FIELD, GRANT_FIELD } from "../fields.js";
+import { getBillingErrorMessage, type BillingMessages } from "../messages/index.js";
+import type { AdminAction } from "./payment-requests.js";
+
+// The admin page's account history: a lookup by email (its action sends the admin to the page with
+// the account's id, so no address lands in a URL) and the account's manual grants and provider
+// payments, newest first, with a Revoke button on each active manual grant. Rows come prepared
+// from the server; the revoke action checks the admin role first and refreshes the page.
+
+export type GrantHistorySlot = "root" | "empty" | "item" | "itemHeader" | "title" | "status" | "details";
+
+/** One grant or payment, prepared on the server. */
+export interface GrantHistoryRow {
+  readonly id: string;
+  /** The plan and where it came from, e.g. "Monthly, granted by hand". */
+  readonly title: string;
+  /** "Active", "Revoked on …", "Paid", "Refunded on …". */
+  readonly statusText: string;
+  /** Whether it still gives access (active or paid); the rest is drawn muted. */
+  readonly isCurrent: boolean;
+  /** The date, the access it added and the amount, one line each. */
+  readonly details: readonly string[];
+  /** Set for an active manual grant: the accessible name of its Revoke button. */
+  readonly revokeLabel: string | null;
+}
+
+export interface GrantHistoryProps {
+  readonly rows: readonly GrantHistoryRow[];
+  readonly revokeAction: AdminAction;
+  readonly messages: BillingMessages;
+  readonly classNames?: ClassNames<GrantHistorySlot>;
+  readonly unstyled?: boolean;
+}
+
+const DEFAULT_CLASSES: Readonly<Record<GrantHistorySlot, string>> = {
+  root: "sft:m-0 sft:flex sft:list-none sft:flex-col sft:gap-3 sft:p-0 sft:font-sans",
+  empty: "sft:m-0 sft:font-sans sft:text-sm sft:text-muted",
+  item: "sft:flex sft:flex-col sft:gap-1 sft:border-t sft:border-border sft:pt-3 sft:first-of-type:border-t-0 sft:first-of-type:pt-0",
+  itemHeader: "sft:flex sft:items-center sft:justify-between sft:gap-2",
+  title: "sft:m-0 sft:text-sm sft:font-semibold sft:text-foreground",
+  status: "sft:text-xs sft:font-medium sft:text-success",
+  details: "sft:m-0 sft:text-xs sft:text-muted",
+};
+
+type Slot = (part: GrantHistorySlot) => string | undefined;
+
+function HistoryItem({ row, revokeAction, messages, slot, unstyled }: { row: GrantHistoryRow; revokeAction: AdminAction; messages: BillingMessages; slot: Slot; unstyled: boolean | undefined }) {
+  const [state, formAction, isPending] = useActionState(revokeAction, INITIAL_ADMIN_ACTION_STATE);
+  const copy = messages.admin.history;
+  return (
+    <li className={slot("item")} data-history-id={row.id}>
+      <div className={slot("itemHeader")}>
+        <p className={slot("title")}>{row.title}</p>
+        {row.revokeLabel === null ? null : (
+          <form action={formAction}>
+            <input type="hidden" name={GRANT_FIELD} value={row.id} />
+            <Button type="submit" variant="danger" size="sm" pending={isPending} aria-label={row.revokeLabel} unstyled={unstyled}>
+              {isPending ? copy.revoking : copy.revoke}
+            </Button>
+          </form>
+        )}
+      </div>
+      <p className={row.isCurrent ? slot("status") : slot("details")}>{row.statusText}</p>
+      {row.details.map((line) => (
+        <p key={line} className={slot("details")}>
+          {line}
+        </p>
+      ))}
+      <FormError message={state.status === "error" ? getBillingErrorMessage(messages, state.error) : undefined} unstyled={unstyled} />
+    </li>
+  );
+}
+
+export function GrantHistory({ rows, revokeAction, messages, classNames, unstyled }: GrantHistoryProps) {
+  const slot = createSlotClassGetter({ defaults: DEFAULT_CLASSES, classNames, unstyled });
+  if (rows.length === 0) return <p className={slot("empty")}>{messages.admin.history.empty}</p>;
+  return (
+    <ul className={slot("root")} aria-label={messages.admin.history.title}>
+      {rows.map((row) => (
+        <HistoryItem key={row.id} row={row} revokeAction={revokeAction} messages={messages} slot={slot} unstyled={unstyled} />
+      ))}
+    </ul>
+  );
+}
+
+export type AccountLookupSlot = "root";
+
+export interface AccountLookupProps {
+  readonly action: AdminAction;
+  readonly messages: BillingMessages;
+  /** Locale of the built-in copy of the ui primitives. */
+  readonly locale?: Locale;
+  readonly classNames?: ClassNames<AccountLookupSlot>;
+  readonly unstyled?: boolean;
+}
+
+/** The email lookup of the history card; a found account reloads the page on its history. */
+export function AccountLookup({ action, messages, locale, classNames, unstyled }: AccountLookupProps) {
+  const [state, formAction, isPending] = useActionState(action, INITIAL_ADMIN_ACTION_STATE);
+  const slot = createSlotClassGetter<AccountLookupSlot>({ defaults: { root: "sft:flex sft:flex-col sft:gap-3 sft:font-sans" }, classNames, unstyled });
+  const copy = messages.admin.history;
+  const error = state.status === "error" ? getBillingErrorMessage(messages, state.error) : undefined;
+  return (
+    <form action={formAction} className={slot("root")}>
+      <TextField
+        key={state.status === "error" ? `error:${state.email ?? ""}` : "lookup"}
+        name={EMAIL_FIELD}
+        type="email"
+        label={copy.email}
+        required
+        defaultValue={state.status === "error" ? (state.email ?? "") : ""}
+        error={error}
+        locale={locale}
+        unstyled={unstyled}
+      />
+      <Button type="submit" variant="secondary" pending={isPending} unstyled={unstyled}>
+        {isPending ? copy.pending : copy.submit}
+      </Button>
+    </form>
+  );
+}

package/src/ui/index.ts

@@ -0,0 +1,25 @@
+// The billing components, to compose into the app's own pages. They render from props (an
+// entitlement or the plans read on the server) and import nothing from `next/*`
+// (docs/02-module-standard.md §5); `/next` renders them wired to the registered configuration.
+export { AccessBadge, type AccessBadgeProps, type AccessBadgeSlot } from "./access-badge.js";
+export { AccessNotice, type AccessNoticeProps, type AccessNoticeSlot } from "./access-notice.js";
+export { formatDay, formatDaysLeft, formatLastDay, formatPeriod } from "./format.js";
+export { GrantForm, type GrantFormAction, type GrantFormProps, type GrantFormSlot } from "./grant-form.js";
+export {
+  AccountLookup,
+  type AccountLookupProps,
+  type AccountLookupSlot,
+  GrantHistory,
+  type GrantHistoryProps,
+  type GrantHistoryRow,
+  type GrantHistorySlot,
+} from "./grant-history.js";
+export { PaymentForm, type PaymentFormAction, type PaymentFormProps, type PaymentFormSlot } from "./payment-form.js";
+export {
+  type AdminAction,
+  PaymentRequestList,
+  type PaymentRequestListProps,
+  type PaymentRequestListSlot,
+  type PaymentRequestRow,
+} from "./payment-requests.js";
+export { PricingTiles, type PricingTilesProps, type PricingTilesSlot } from "./pricing-tiles.js";

package/src/ui/payment-form.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import { formatMessage, type Locale } from "@softure-ai/core";
+import { Button, type ClassNames, createSlotClassGetter, FormError, TextField } from "@softure-ai/ui";
+import { useActionState } from "react";
+import { INITIAL_PAYMENT_FORM_STATE, type PaymentFormState } from "../contract.js";
+import { getInvoiceFieldLimit, INVOICE_FIELDS, INVOICE_LIMITS, PLAN_FIELD } from "../fields.js";
+import { getBillingErrorMessage, type BillingMessages } from "../messages/index.js";
+
+// The form that starts paying for the chosen plan. With a provider that needs them (the manual
+// adapter) it asks for the invoice details; otherwise it is one button that sends the buyer to the
+// provider's checkout. It submits straight to its server action through `useActionState`, so it
+// works before (and without) JavaScript; a requested invoice shows the confirmation instead.
+
+export type PaymentFormAction = (previous: PaymentFormState, formData: FormData) => Promise<PaymentFormState>;
+
+export type PaymentFormSlot = "root" | "form" | "notice";
+
+export interface PaymentFormProps {
+  readonly action: PaymentFormAction;
+  readonly planId: string;
+  /** The plan's name in the app's locale, for the confirmation. */
+  readonly planName: string;
+  /** The buyer's address, for the confirmation. */
+  readonly email: string;
+  /** Asks for the invoice details (the manual adapter); else one checkout button. */
+  readonly collectsInvoiceDetails: boolean;
+  readonly messages: BillingMessages;
+  /** Locale of the built-in copy of the ui primitives. */
+  readonly locale?: Locale;
+  readonly classNames?: ClassNames<PaymentFormSlot>;
+  readonly unstyled?: boolean;
+}
+
+const DEFAULT_CLASSES: Readonly<Record<PaymentFormSlot, string>> = {
+  root: "sft:flex sft:flex-col sft:gap-3 sft:font-sans",
+  form: "sft:flex sft:flex-col sft:gap-3",
+  notice: "sft:m-0 sft:text-sm sft:text-success",
+};
+
+export function PaymentForm({ action, planId, planName, email, collectsInvoiceDetails, messages, locale, classNames, unstyled }: PaymentFormProps) {
+  const [state, formAction, isPending] = useActionState(action, INITIAL_PAYMENT_FORM_STATE);
+  const slot = createSlotClassGetter({ defaults: DEFAULT_CLASSES, classNames, unstyled });
+  if (state.status === "requested") {
+    return (
+      <div className={slot("root")}>
+        <p role="status" className={slot("notice")}>
+          {formatMessage(messages.payment.requested, { plan: planName, email })}
+        </p>
+      </div>
+    );
+  }
+
+  const copy = messages.payment;
+  const values = state.values ?? {};
+  const fieldError = (name: string): string | undefined => {
+    const code = state.fieldErrors?.[name];
+    if (code === undefined) return undefined;
+    const limit = getInvoiceFieldLimit(name);
+    return formatMessage(getBillingErrorMessage(messages, code), limit === undefined ? {} : { max: limit });
+  };
+  const hasFieldErrors = Object.keys(state.fieldErrors ?? {}).length > 0;
+  const formError = state.error === undefined || hasFieldErrors ? undefined : getBillingErrorMessage(messages, state.error);
+  const submitLabel = collectsInvoiceDetails ? copy.requestInvoice : copy.checkout;
+  return (
+    <div className={slot("root")}>
+      <form action={formAction} className={slot("form")}>
+        <input type="hidden" name={PLAN_FIELD} value={planId} />
+        {collectsInvoiceDetails ? (
+          <>
+            <TextField
+              name={INVOICE_FIELDS.name}
+              label={copy.fields.name}
+              autoComplete="name"
+              required
+              maxLength={INVOICE_LIMITS.name}
+              defaultValue={values[INVOICE_FIELDS.name] ?? ""}
+              error={fieldError(INVOICE_FIELDS.name)}
+              locale={locale}
+              unstyled={unstyled}
+            />
+            <TextField
+              name={INVOICE_FIELDS.taxId}
+              label={copy.fields.taxId}
+              maxLength={INVOICE_LIMITS.taxId}
+              defaultValue={values[INVOICE_FIELDS.taxId] ?? ""}
+              error={fieldError(INVOICE_FIELDS.taxId)}
+              locale={locale}
+              unstyled={unstyled}
+            />
+            <TextField
+              name={INVOICE_FIELDS.address}
+              label={copy.fields.address}
+              autoComplete="street-address"
+              required
+              maxLength={INVOICE_LIMITS.address}
+              defaultValue={values[INVOICE_FIELDS.address] ?? ""}
+              error={fieldError(INVOICE_FIELDS.address)}
+              locale={locale}
+              unstyled={unstyled}
+            />
+          </>
+        ) : null}
+        <FormError message={formError} unstyled={unstyled} />
+        <Button type="submit" variant="primary" fullWidth pending={isPending} unstyled={unstyled}>
+          {isPending ? copy.pending : submitLabel}
+        </Button>
+      </form>
+    </div>
+  );
+}