@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/messages/pl.ts

@@ -0,0 +1,152 @@
+import type { en } from "./en.js";
+
+export const pl: typeof en = {
+  badge: {
+    trial: "Okres próbny",
+    paid: "Opłacone",
+    lifetime: "Dostęp dożywotni",
+    readOnly: "Tylko odczyt",
+    daysLeft: { one: "został {count} dzień", few: "zostały {count} dni", many: "zostało {count} dni", other: "zostało {count} dnia" },
+    until: "do {date}",
+  },
+  notice: {
+    trialEnding: "Okres próbny kończy się {date}. Wybierz plan, żeby potem dalej wprowadzać zmiany.",
+    paidEnding: "Dostęp kończy się {date}. Przedłuż go, żeby potem dalej wprowadzać zmiany.",
+    trialEnded: "Okres próbny się skończył. Twoje dane są bezpieczne i nadal możesz je przeglądać; wybierz plan, żeby znów wprowadzać zmiany.",
+    paidEnded: "Dostęp się skończył. Twoje dane są bezpieczne i nadal możesz je przeglądać; przedłuż go, żeby znów wprowadzać zmiany.",
+    choosePlan: "Wybierz plan",
+    renew: "Przedłuż dostęp",
+  },
+  reminderMail: {
+    trialEnding: {
+      subject: "Okres próbny kończy się {date}",
+      body: "Okres próbny kończy się {date}. Wybierz plan, żeby potem dalej wprowadzać zmiany; Twoje dane i tak pozostaną bezpieczne.",
+    },
+    paidEnding: {
+      subject: "Dostęp kończy się {date}",
+      body: "Dostęp kończy się {date}. Przedłuż go, żeby potem dalej wprowadzać zmiany; Twoje dane i tak pozostaną bezpieczne.",
+    },
+    trialEnded: {
+      subject: "Okres próbny się skończył",
+      body: "Okres próbny się skończył. Twoje dane są bezpieczne i nadal możesz je przeglądać; wybierz plan, żeby znów wprowadzać zmiany.",
+    },
+    paidEnded: {
+      subject: "Dostęp się skończył",
+      body: "Dostęp się skończył. Twoje dane są bezpieczne i nadal możesz je przeglądać; przedłuż go, żeby znów wprowadzać zmiany.",
+    },
+  },
+  pricing: {
+    period: {
+      day: { one: "za dzień", few: "za {count} dni", many: "za {count} dni", other: "za {count} dnia" },
+      week: { one: "za tydzień", few: "za {count} tygodnie", many: "za {count} tygodni", other: "za {count} tygodnia" },
+      month: { one: "za miesiąc", few: "za {count} miesiące", many: "za {count} miesięcy", other: "za {count} miesiąca" },
+      year: { one: "za rok", few: "za {count} lata", many: "za {count} lat", other: "za {count} roku" },
+      lifetime: "płatność jednorazowa",
+    },
+    featured: "Polecany",
+    choose: "Wybierz {plan}",
+    empty: "Nie ma jeszcze dostępnych planów.",
+  },
+  payment: {
+    title: "Wybierz plan",
+    lead: "Wybierz plan dla siebie. Płatny dostęp zaczyna się, gdy skończy się obecny.",
+    plansLabel: "Plany",
+    orderTitle: "Twoje zamówienie",
+    orderLead: "{plan}, {price} {period}",
+    changePlan: "Wybierz inny plan",
+    invoiceLead: "Fakturę wyślemy na adres {email}. Dostęp zacznie się po jej opłaceniu.",
+    fields: {
+      name: "Imię i nazwisko lub firma",
+      taxId: "NIP (opcjonalnie)",
+      address: "Adres do faktury",
+    },
+    requestInvoice: "Poproś o fakturę",
+    checkout: "Przejdź do płatności",
+    pending: "Wysyłanie…",
+    requested: "Dziękujemy! Prośba o fakturę za {plan} została wysłana. Fakturę wyślemy na adres {email}; dostęp zacznie się po jej opłaceniu.",
+    checkoutSuccess: "Dziękujemy za płatność! Dostęp zaktualizujemy, gdy płatność zostanie potwierdzona, zwykle w ciągu minuty.",
+    checkoutCancelled: "Płatność została anulowana i nic nie pobrano. Możesz spróbować ponownie albo wybrać inny plan.",
+    lifetime: "Masz dostęp dożywotni: nie ma już za co płacić.",
+  },
+  admin: {
+    title: "Nadaj dostęp",
+    lead: "Nadaj plan kontu, gdy wpłynie płatność. Płatny okres zaczyna się, gdy skończy się obecny dostęp konta.",
+    email: "E-mail konta",
+    plan: "Plan",
+    submit: "Nadaj plan",
+    pending: "Nadawanie…",
+    granted: "{email} ma teraz {plan}.",
+    grantedUntil: "{email} ma teraz {plan}, z dostępem do {date}.",
+    noPlans: "Nie ma planów do nadania: dodaj je w billing({ plans }).",
+    requests: {
+      title: "Prośby o fakturę",
+      lead: "Prośby wysłane ze strony płatności. Nadaj plan, gdy faktura zostanie opłacona, albo odrzuć prośbę.",
+      empty: "Brak otwartych próśb.",
+      line: "{email} – {plan}",
+      requestedOn: "Wysłana {date}",
+      price: "Cena: {price}",
+      invoice: "Faktura na: {name}, {address}",
+      taxId: "NIP: {taxId}",
+      noInvoice: "Bez danych do faktury",
+      grant: "Nadaj",
+      granting: "Nadawanie…",
+      dismiss: "Odrzuć",
+      dismissing: "Odrzucanie…",
+      history: "Historia",
+      grantLabel: "Nadaj {plan} dla {email}",
+      dismissLabel: "Odrzuć prośbę {email} o {plan}",
+    },
+    history: {
+      title: "Historia konta",
+      lead: "Znajdź konto, żeby zobaczyć jego dostęp, plany nadane ręcznie i płatności.",
+      email: "Znajdź konto po e-mailu",
+      submit: "Pokaż historię",
+      pending: "Szukanie…",
+      accountTitle: "Historia konta {email}",
+      empty: "Brak nadań i płatności.",
+      manual: "{plan}, nadany ręcznie",
+      fromRequest: "{plan}, nadany z prośby",
+      provider: "{plan}, opłacony przez {provider}",
+      grantedOn: "Nadany {date}",
+      grantedFor: "Nadany {date} za {amount}",
+      paidOn: "Zapłacono {amount}, {date}",
+      period: "Dostęp od {from} do {to}",
+      lifetime: "Dostęp dożywotni",
+      noGrant: "Zapisana, zanim zaczęliśmy zapisywać nadania",
+      active: "Aktywny",
+      revokedOn: "Cofnięty {date}",
+      paid: "Opłacona",
+      refundedOn: "Zwrócona {date}",
+      partlyRefunded: "Opłacona, zwrócono {amount}",
+      revoke: "Cofnij",
+      revoking: "Cofanie…",
+      revokeLabel: "Cofnij {plan} nadany {date}",
+    },
+  },
+  errors: {
+    billing: {
+      read_only: "Konto jest w trybie tylko do odczytu. Wybierz plan, żeby wprowadzać zmiany.",
+      account_unknown: "Żadne konto nie ma tego adresu e-mail.",
+      end_not_in_future: "Data końca musi być w przyszłości.",
+      plan_unknown: "Ten plan nie jest już dostępny. Wybierz inny.",
+      invoice_details_invalid: "Sprawdź dane do faktury poniżej.",
+      invoice_field_required: "Wypełnij to pole.",
+      invoice_field_too_long: "Użyj najwyżej {max} znaków.",
+      invoice_field_control_characters: "Usuń znaki nowej linii, tabulatory i inne znaki sterujące.",
+      payment_failed: "Nie udało się rozpocząć płatności. Spróbuj za chwilę.",
+      lifetime_active: "To konto ma już dostęp dożywotni: nie ma za co płacić ani czego nadawać.",
+      request_closed: "Ta prośba została już obsłużona lub odrzucona.",
+      grant_revoked: "Ten dostęp został już cofnięty.",
+    },
+    security: {
+      rate_limited: "Zbyt wiele prób. Spróbuj później.",
+    },
+    auth: {
+      forbidden: "Nie masz uprawnień do tej operacji.",
+    },
+    core: {
+      database_failed: "Coś poszło nie tak po naszej stronie. Spróbuj za chwilę.",
+      unexpected: "Coś poszło nie tak po naszej stronie. Spróbuj za chwilę.",
+    },
+  },
+};

package/src/next/access.tsx

@@ -0,0 +1,55 @@
+// The badge and the notice for the signed-in account, wired to the registered config: one line in
+// any server component (`<CurrentAccessBadge />`, `<CurrentAccessNotice />`). Without a session
+// they render nothing.
+import { getSoftureConfig } from "@softure-ai/core/next";
+import type { ClassNames, LinkComponentType } from "@softure-ai/ui";
+import { getBillingMessages, getBillingRoutes } from "../server/options.js";
+import { AccessBadge, type AccessBadgeSlot } from "../ui/access-badge.js";
+import { AccessNotice, type AccessNoticeSlot } from "../ui/access-notice.js";
+import { getCurrentEntitlement } from "./current-entitlement.js";
+
+export interface CurrentAccessBadgeProps {
+  readonly classNames?: ClassNames<AccessBadgeSlot>;
+  readonly unstyled?: boolean;
+}
+
+export async function CurrentAccessBadge({ classNames, unstyled }: CurrentAccessBadgeProps) {
+  const entitlement = await getCurrentEntitlement();
+  if (entitlement === null) return null;
+  const config = getSoftureConfig();
+  return (
+    <AccessBadge
+      entitlement={entitlement}
+      messages={getBillingMessages(config)}
+      locale={config.locale}
+      timezone={config.timezone}
+      classNames={classNames}
+      unstyled={unstyled}
+    />
+  );
+}
+
+export interface CurrentAccessNoticeProps {
+  /** The app's link component, e.g. Next's `Link`; a plain `<a>` when omitted. */
+  readonly LinkComponent?: LinkComponentType;
+  readonly classNames?: ClassNames<AccessNoticeSlot>;
+  readonly unstyled?: boolean;
+}
+
+export async function CurrentAccessNotice({ LinkComponent, classNames, unstyled }: CurrentAccessNoticeProps) {
+  const entitlement = await getCurrentEntitlement();
+  if (entitlement === null) return null;
+  const config = getSoftureConfig();
+  return (
+    <AccessNotice
+      entitlement={entitlement}
+      messages={getBillingMessages(config)}
+      locale={config.locale}
+      timezone={config.timezone}
+      paymentHref={getBillingRoutes(config).payment}
+      LinkComponent={LinkComponent}
+      classNames={classNames}
+      unstyled={unstyled}
+    />
+  );
+}

package/src/next/actions.ts

@@ -0,0 +1,176 @@
+"use server";
+
+// The billing server actions. Each reads the account from the session (never from a bound
+// argument, which the client controls, docs/02 §8) before it reads the form: the payment action
+// needs a signed-in account, the admin actions the admin role. Unexpected failures become
+// `safeError` codes. Next refuses an action whose Origin does not match the host. An admin action
+// that changed something revalidates the admin page, so its lists show the change.
+import type { AuthUser } from "@softure-ai/auth";
+import { authorizeRole, requireUser } from "@softure-ai/auth/next";
+import { errorLogLabel, formatMessage, safeError, type CoreErrorCode, type Err, type Ok, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { revalidatePath } from "next/cache";
+import { redirect } from "next/navigation";
+import type { AdminActionErrorCode, AdminActionState, GrantFormState, PaymentFormState } from "../contract.js";
+import { ACCOUNT_PARAM, EMAIL_FIELD, GRANT_FIELD, INVOICE_FIELDS, PLAN_FIELD, REQUEST_FIELD } from "../fields.js";
+import { findPlan, getLocalizedText } from "../plans.js";
+import { grantPaymentRequest, grantPlanManually, revokeManualGrant } from "../server/grants.js";
+import { getBillingMessages, getBillingOptions, getBillingRoutes } from "../server/options.js";
+import { findAccountByEmail, getBillingPlans, startPayment } from "../server/plans.js";
+import type { BillingContext } from "../server/entitlements.js";
+import { dismissPaymentRequest } from "../server/requests.js";
+import { formatLastDay } from "../ui/format.js";
+import { getBillingContext } from "./context.js";
+
+/** Longer values are cut: the server functions refuse them anyway, and nothing huge is echoed back. */
+const MAX_FIELD_LENGTH = 1024;
+
+function readText(formData: FormData, name: string): string {
+  const value = formData.get(name);
+  return typeof value === "string" ? value.slice(0, MAX_FIELD_LENGTH) : "";
+}
+
+function reportFailure(operation: string, error: unknown): CoreErrorCode {
+  console.error(`@softure-ai/billing: ${operation} failed: ${errorLogLabel(error)}`);
+  return safeError(error).error;
+}
+
+/**
+ * Starts paying for the plan of the form. Without a session it redirects to the login page and
+ * back to the payment page. A hosted checkout is a redirect; a manual request answers `requested`.
+ */
+export async function startPaymentAction(_previous: PaymentFormState, formData: FormData): Promise<PaymentFormState> {
+  const config = getSoftureConfig();
+  const user = await requireUser({ next: getBillingRoutes(config).payment });
+  const planId = readText(formData, PLAN_FIELD);
+  const invoice = { name: readText(formData, INVOICE_FIELDS.name), taxId: readText(formData, INVOICE_FIELDS.taxId), address: readText(formData, INVOICE_FIELDS.address) };
+  const values = { [INVOICE_FIELDS.name]: invoice.name, [INVOICE_FIELDS.taxId]: invoice.taxId, [INVOICE_FIELDS.address]: invoice.address };
+
+  let result;
+  try {
+    result = await startPayment(await getBillingContext(config), { account: { id: user.id, email: user.email }, planId, invoice });
+  } catch (error) {
+    return { status: "error", error: reportFailure("starting a payment", error), values };
+  }
+  if (!result.ok) return { status: "error", error: result.error, ...("fieldErrors" in result ? { fieldErrors: result.fieldErrors } : {}), values };
+  // Outside the try: Next's redirect works by throwing.
+  if (result.value.type === "redirect") redirect(result.value.url);
+  return { status: "requested" };
+}
+
+function refreshAdminPage(config: SoftureConfig): void {
+  revalidatePath(getBillingRoutes(config).admin);
+}
+
+/** The signed-in admin, or the refusal: the role of `billing({ adminRole })`, from the session. */
+async function authorizeAdmin(config: SoftureConfig): Promise<Ok<AuthUser> | Err<"auth.forbidden">> {
+  return authorizeRole(getBillingOptions(config).adminRole);
+}
+
+/**
+ * Grants one payment of a plan to the account with the form's email and records it in the
+ * account's history. Only for the role of `billing({ adminRole })`, checked from the session
+ * before the form is read. An account with lifetime access is refused.
+ */
+export async function grantPlanAction(_previous: GrantFormState, formData: FormData): Promise<GrantFormState> {
+  const config = getSoftureConfig();
+  const admin = await authorizeAdmin(config);
+  if (!admin.ok) return { status: "error", error: admin.error };
+  const email = readText(formData, EMAIL_FIELD).trim();
+  const planId = readText(formData, PLAN_FIELD);
+  const echo = { email, planId };
+
+  const plan = findPlan(getBillingPlans(config), planId);
+  if (plan === undefined) return { status: "error", error: "billing.plan_unknown", ...echo };
+  let result;
+  try {
+    const ctx = await getBillingContext(config);
+    const account = await findAccountByEmail(ctx, email);
+    if (account === null) return { status: "error", error: "billing.account_unknown", ...echo };
+    result = await grantPlanManually(ctx, { userId: account.id, planId: plan.id, adminId: admin.value.id });
+    if (result.ok) {
+      refreshAdminPage(config);
+      const messages = getBillingMessages(config).admin;
+      const { entitlement } = result.value;
+      const values = { email: account.email, plan: getLocalizedText(plan.name, config.locale) };
+      const notice =
+        entitlement.status === "paid" && entitlement.endsAt !== null
+          ? formatMessage(messages.grantedUntil, { ...values, date: formatLastDay(entitlement.endsAt, config.locale, config.timezone) })
+          : formatMessage(messages.granted, values);
+      return { status: "granted", notice, planId };
+    }
+  } catch (error) {
+    return { status: "error", error: reportFailure("granting a plan", error), ...echo };
+  }
+  // No request was given, so it is never closed; an account deleted meanwhile is unknown.
+  const error = result.error === "billing.request_closed" ? "billing.account_unknown" : result.error;
+  return { status: "error", error, ...echo };
+}
+
+interface AdminChange {
+  readonly operation: string;
+  /** The form field that names the row. */
+  readonly field: string;
+  readonly change: (ctx: BillingContext, id: string, adminId: string) => Promise<{ readonly ok: true } | Err<AdminActionErrorCode>>;
+}
+
+/** Runs one admin change on the row the form names: role first, then the change, then a refresh. */
+async function runAdminChange(formData: FormData, { operation, field, change }: AdminChange): Promise<AdminActionState> {
+  const config = getSoftureConfig();
+  const admin = await authorizeAdmin(config);
+  if (!admin.ok) return { status: "error", error: admin.error };
+  const id = readText(formData, field);
+  try {
+    const result = await change(await getBillingContext(config), id, admin.value.id);
+    if (!result.ok) return { status: "error", error: result.error };
+  } catch (error) {
+    return { status: "error", error: reportFailure(operation, error) };
+  }
+  refreshAdminPage(config);
+  return { status: "done" };
+}
+
+/** Grants the plan of the form's open request and closes it (admin role). */
+export async function grantRequestAction(_previous: AdminActionState, formData: FormData): Promise<AdminActionState> {
+  return runAdminChange(formData, {
+    operation: "granting a payment request",
+    field: REQUEST_FIELD,
+    change: (ctx, requestId, adminId) => grantPaymentRequest(ctx, { requestId, adminId }),
+  });
+}
+
+/** Closes the form's open request without a grant (admin role). */
+export async function dismissRequestAction(_previous: AdminActionState, formData: FormData): Promise<AdminActionState> {
+  return runAdminChange(formData, { operation: "dismissing a payment request", field: REQUEST_FIELD, change: (ctx, requestId) => dismissPaymentRequest(ctx, requestId) });
+}
+
+/** Revokes the form's manual grant, taking back only what it added (admin role). */
+export async function revokeGrantAction(_previous: AdminActionState, formData: FormData): Promise<AdminActionState> {
+  return runAdminChange(formData, {
+    operation: "revoking a manual grant",
+    field: GRANT_FIELD,
+    change: (ctx, grantId, adminId) => revokeManualGrant(ctx, { grantId, adminId }),
+  });
+}
+
+/**
+ * Finds the account with the form's email and sends the admin to its history on the admin page,
+ * by the account's id: an email address never lands in a URL (admin role).
+ */
+export async function findAccountAction(_previous: AdminActionState, formData: FormData): Promise<AdminActionState> {
+  const config = getSoftureConfig();
+  const admin = await authorizeAdmin(config);
+  if (!admin.ok) return { status: "error", error: admin.error };
+  const email = readText(formData, EMAIL_FIELD).trim();
+  let accountId;
+  try {
+    const account = await findAccountByEmail(await getBillingContext(config), email);
+    if (account === null) return { status: "error", error: "billing.account_unknown", email };
+    accountId = account.id;
+  } catch (error) {
+    return { status: "error", error: reportFailure("finding an account", error), email };
+  }
+  // Outside the try: Next's redirect works by throwing.
+  redirect(`${getBillingRoutes(config).admin}?${new URLSearchParams({ [ACCOUNT_PARAM]: accountId }).toString()}`);
+}
+

package/src/next/context.ts

@@ -0,0 +1,18 @@
+// What the adapter hands the server functions: the registered config, the process-wide database
+// handle and the wall clock. Every billing request comes through here, so a broken setup (an
+// undeclared `adminRole`) fails on the first one.
+import { systemClock, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { getSharedDatabase } from "@softure-ai/db";
+import type { BillingContext } from "../server/entitlements.js";
+import { assertAdminRoleDeclared } from "../server/setup.js";
+
+export async function getBillingContext(config: SoftureConfig = getSoftureConfig()): Promise<BillingContext> {
+  assertAdminRoleDeclared(config);
+  if (config.database === null) {
+    // Unreachable for a validated config: the module has a database schema.
+    throw new Error("@softure-ai/billing: softure.config.ts has no database; billing needs one");
+  }
+  const { db } = await getSharedDatabase(config.database.url);
+  return { db, clock: systemClock, config };
+}

package/src/next/current-entitlement.ts

@@ -0,0 +1,36 @@
+// The signed-in account's entitlement and the write guard, for server components, actions and route
+// handlers. React's `cache` makes the lookup once per request; nothing is cached across requests,
+// so a grant shows on the next one.
+import type { AuthUser } from "@softure-ai/auth";
+import { getCurrentUser, requireUser, type RequireUserOptions } from "@softure-ai/auth/next";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { cache } from "react";
+import type { Entitlement } from "../contract.js";
+import { getEntitlement } from "../server/entitlements.js";
+import { getBillingContext } from "./context.js";
+
+/** The entitlement of the request's account, or null without a session. Database failures propagate. */
+export const getCurrentEntitlement = cache(async (): Promise<Entitlement | null> => {
+  const user = await getCurrentUser();
+  if (user === null) return null;
+  return getEntitlement(await getBillingContext(), user.id);
+});
+
+/** What a write may go ahead with. */
+export interface WriteAccess {
+  readonly user: AuthUser;
+  readonly entitlement: Entitlement;
+}
+
+/**
+ * The guard for an app's write actions; call it before reading any input. Without a session it
+ * redirects to the login page (as `requireUser`); a read-only account gets `billing.read_only` for
+ * the action to return to its form. Never a reason to skip the action's own authorization.
+ */
+export async function requireWriteAccess(options: RequireUserOptions = {}): Promise<Ok<WriteAccess> | Err<"billing.read_only">> {
+  const user = await requireUser(options);
+  const entitlement = await getCurrentEntitlement();
+  // The session's account exists, so it has an entitlement; null would mean it vanished mid-request.
+  if (entitlement === null || entitlement.status === "read_only") return err("billing.read_only");
+  return ok({ user, entitlement });
+}

package/src/next/index.ts

@@ -0,0 +1,11 @@
+// The Next.js adapter of @softure-ai/billing: the signed-in account's entitlement, the write guard
+// for server actions, the badge and notice, the pricing tiles, the payment and admin pages and
+// their actions, and the Stripe webhook route, wired to the registered configuration
+// (docs/02-module-standard.md §8).
+export { CurrentAccessBadge, type CurrentAccessBadgeProps, CurrentAccessNotice, type CurrentAccessNoticeProps } from "./access.js";
+export { dismissRequestAction, findAccountAction, grantPlanAction, grantRequestAction, revokeGrantAction, startPaymentAction } from "./actions.js";
+export { getBillingContext } from "./context.js";
+export { getCurrentEntitlement, requireWriteAccess, type WriteAccess } from "./current-entitlement.js";
+export { BillingAdminPage, type BillingAdminPageProps, PaymentPage, type PaymentPageProps } from "./pages.js";
+export { getPlanPaymentHref, Pricing, type PricingProps } from "./pricing.js";
+export { STRIPE_WEBHOOK_MAX_BYTES, STRIPE_WEBHOOK_SECRET_ENV, stripeWebhookRoute } from "./route.js";

package/src/next/next-modules.d.ts

@@ -0,0 +1,21 @@
+// Billing's adapter imports `@softure-ai/auth/next`, whose sources import these specifiers.
+// Next.js has no `exports` map, so NodeNext resolution (tsconfig.base.json) only finds
+// `next/navigation.js` and `next/headers.js`. The code must still import the bare specifiers:
+// Next's bundler aliases them per runtime, and the `.js` form bypasses the alias (measured:
+// `next build` failed to collect a route handler importing `next/navigation.js`, MODULE_UNPARSABLE
+// on the vendored app-router context). These declarations give the bare specifiers their types.
+declare module "next/navigation" {
+  export * from "next/navigation.js";
+}
+
+declare module "next/headers" {
+  export * from "next/headers.js";
+}
+
+declare module "next/server" {
+  export * from "next/server.js";
+}
+
+declare module "next/cache" {
+  export * from "next/cache.js";
+}