@softure-ai/billing 0.0.0-stage → 0.1.6

package/src/server/entitlements.ts

@@ -0,0 +1,227 @@
+// Reading and changing an account's entitlement. An account without a row is on the trial that
+// starts at its `auth.users.created_at` (or at `trial.startsAt` when later), derived on every read,
+// so reads never write. A change pins that derived record into a row first, then applies the event
+// under the row's lock.
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type ModuleContext, type Ok } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { and, asc, eq, gt, isNull } from "drizzle-orm";
+import { getDayNumber, getStartOfDay, parseDay } from "../calendar.js";
+import type { BillingErrorCode, Entitlement, EntitlementEvent, EntitlementRecord } from "../contract.js";
+import { applyEntitlementEvent, resolveEntitlement } from "../entitlement.js";
+import { entitlements } from "../schema.js";
+import { getBillingOptions, getEntitlementPolicy } from "./options.js";
+import { isUserId } from "./user-id.js";
+
+export type BillingContext = ModuleContext<Queryable>;
+
+/**
+ * The local day an account without a row starts its trial on: the day it was created, or
+ * `trial.startsAt` when that is later.
+ */
+function getTrialStartDay(ctx: Pick<BillingContext, "config">, accountCreatedAt: Date): number {
+  const createdDay = getDayNumber(accountCreatedAt, ctx.config.timezone);
+  const floorDay = getTrialFloorDay(ctx);
+  return floorDay === null ? createdDay : Math.max(createdDay, floorDay);
+}
+
+/** The day number of `trial.startsAt`, or null without one. */
+export function getTrialFloorDay(ctx: Pick<BillingContext, "config">): number | null {
+  const { startsAt } = getBillingOptions(ctx.config).trial;
+  if (startsAt === undefined) return null;
+  const day = parseDay(startsAt);
+  // The option's schema refused anything else at startup.
+  if (day === null) throw new Error(`@softure-ai/billing: trial.startsAt "${startsAt}" is not a calendar day`);
+  return day;
+}
+
+/**
+ * The trial an account without a row is on: `trial.days` from the day it was created, or from
+ * `trial.startsAt` for an account created before that day.
+ */
+export function getDefaultRecord(ctx: Pick<BillingContext, "config">, accountCreatedAt: Date): EntitlementRecord {
+  const trialEndsAt = getStartOfDay(getTrialStartDay(ctx, accountCreatedAt) + getBillingOptions(ctx.config).trial.days, ctx.config.timezone);
+  return { trialEndsAt, paidUntil: null, isLifetime: false };
+}
+
+export interface PinEntitlementRowInput {
+  readonly userId: string;
+  /** The account's `auth.users.created_at`, which its derived trial starts from. */
+  readonly accountCreatedAt: Date;
+}
+
+/**
+ * Writes the account's derived trial into a row when it has none (exactly what reads derive), so a
+ * check made before the first change has a row to lock: a concurrent change that inserted first is
+ * waited for. Returns whether this call inserted the row. The caller holds the account (key share)
+ * and runs it in its transaction.
+ */
+export async function pinEntitlementRow(ctx: Pick<BillingContext, "db" | "config" | "clock">, input: PinEntitlementRowInput): Promise<boolean> {
+  const now = ctx.clock.now();
+  const inserted = await ctx.db
+    .insert(entitlements)
+    .values({ userId: input.userId, ...getDefaultRecord(ctx, input.accountCreatedAt), createdAt: now, updatedAt: now })
+    .onConflictDoNothing({ target: entitlements.userId })
+    .returning();
+  return inserted.length > 0;
+}
+
+/** The account's stored or derived record, or null when no account has this id. */
+export async function findEntitlementRecord(ctx: Pick<BillingContext, "db" | "config">, userId: string): Promise<EntitlementRecord | null> {
+  if (!isUserId(userId)) return null;
+  const [row] = await ctx.db
+    .select({
+      accountCreatedAt: users.createdAt,
+      trialEndsAt: entitlements.trialEndsAt,
+      paidUntil: entitlements.paidUntil,
+      isLifetime: entitlements.isLifetime,
+    })
+    .from(users)
+    .leftJoin(entitlements, eq(entitlements.userId, users.id))
+    .where(eq(users.id, userId));
+  if (row === undefined) return null;
+  if (row.trialEndsAt === null) return getDefaultRecord(ctx, row.accountCreatedAt);
+  return { trialEndsAt: row.trialEndsAt, paidUntil: row.paidUntil, isLifetime: row.isLifetime ?? false };
+}
+
+/** Where the account stands now, or null when no account has this id. Database errors propagate. */
+export async function getEntitlement(ctx: BillingContext, userId: string): Promise<Entitlement | null> {
+  const record = await findEntitlementRecord(ctx, userId);
+  return record === null ? null : resolveEntitlement(record, ctx.clock.now(), getEntitlementPolicy(ctx.config));
+}
+
+/**
+ * The write guard without a framework: `Ok` with the entitlement when the account may write,
+ * `billing.read_only` when it may only read, `billing.account_unknown` without an account.
+ */
+export async function checkWriteAccess(ctx: BillingContext, userId: string): Promise<Ok<Entitlement> | Err<"billing.read_only" | "billing.account_unknown">> {
+  const entitlement = await getEntitlement(ctx, userId);
+  if (entitlement === null) return err("billing.account_unknown");
+  return entitlement.status === "read_only" ? err("billing.read_only") : ok(entitlement);
+}
+
+/** The stored record of an account, locked until the transaction ends, or undefined. */
+async function lockStoredRecord(tx: Queryable, userId: string): Promise<EntitlementRecord | undefined> {
+  const [row] = await tx
+    .select({ trialEndsAt: entitlements.trialEndsAt, paidUntil: entitlements.paidUntil, isLifetime: entitlements.isLifetime })
+    .from(entitlements)
+    .where(eq(entitlements.userId, userId))
+    .for("update");
+  return row;
+}
+
+/** The event to apply, decided from the account's current record under its lock. */
+export type EntitlementEventResolver = (record: EntitlementRecord, now: Date) => EntitlementEvent;
+
+/**
+ * Applies `event` to the account's entitlement in one transaction and returns where it stands
+ * after; a refused event writes nothing. An account without a row gets one holding its derived
+ * trial with the event applied, so the trial end never moves when a row appears. A concurrent
+ * change that inserted first is waited for and applied on. Database errors propagate.
+ *
+ * `event` may be a function of the current record (a paid period that starts where access ends,
+ * `grantPlan`); it runs under the lock, so two changes at once both count.
+ */
+export async function changeEntitlement(
+  ctx: BillingContext,
+  userId: string,
+  event: EntitlementEvent | EntitlementEventResolver,
+): Promise<Ok<Entitlement> | Err<BillingErrorCode>> {
+  if (!isUserId(userId)) return err("billing.account_unknown");
+  const resolveEvent: EntitlementEventResolver = typeof event === "function" ? event : () => event;
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    const policy = getEntitlementPolicy(ctx.config);
+    // A shared lock: the account cannot be deleted under the change, other changes still read it.
+    const [account] = await tx.select({ createdAt: users.createdAt }).from(users).where(eq(users.id, userId)).for("key share");
+    if (account === undefined) return err("billing.account_unknown");
+
+    const stored = await lockStoredRecord(tx, userId);
+    if (stored === undefined) {
+      const derived = getDefaultRecord(ctx, account.createdAt);
+      const next = applyEntitlementEvent(derived, resolveEvent(derived, now), now);
+      if (!next.ok) return next;
+      const inserted = await tx
+        .insert(entitlements)
+        .values({ userId, ...next.value, createdAt: now, updatedAt: now })
+        .onConflictDoNothing({ target: entitlements.userId })
+        .returning();
+      if (inserted.length > 0) return ok(resolveEntitlement(next.value, now, policy));
+    }
+
+    // The row existed, or a concurrent change inserted it after the read above (the insert waited
+    // for that transaction, so the row is visible now).
+    const current = stored ?? (await lockStoredRecord(tx, userId));
+    if (current === undefined) throw new Error("@softure-ai/billing: an entitlement row vanished while it was being changed");
+    const next = applyEntitlementEvent(current, resolveEvent(current, now), now);
+    if (!next.ok) return next;
+    await tx
+      .update(entitlements)
+      .set({ ...next.value, updatedAt: now })
+      .where(eq(entitlements.userId, userId));
+    return ok(resolveEntitlement(next.value, now, policy));
+  });
+}
+
+export interface ImportEntitlementInput {
+  readonly userId: string;
+  /** The trial end the other system knew; omitted or null keeps the account's own. */
+  readonly trialEndsAt?: Date | null;
+  /** The end of the paid period it knew; omitted or null adds none. */
+  readonly paidUntil?: Date | null;
+  /** Whether it had lifetime access. */
+  readonly isLifetime?: boolean;
+}
+
+/**
+ * Records what another system knew about an account (a trial end, a paid period, lifetime access)
+ * through `changeEntitlement`: merged onto the account's current record, each end only moving
+ * later, so an import never takes access away and a repeat changes nothing. Not a recorded grant:
+ * it is not in the account's history. Database errors propagate.
+ */
+export async function importEntitlement(ctx: BillingContext, input: ImportEntitlementInput): Promise<Ok<Entitlement> | Err<"billing.account_unknown">> {
+  const changed = await changeEntitlement(ctx, input.userId, {
+    type: "import",
+    trialEndsAt: input.trialEndsAt ?? null,
+    paidUntil: input.paidUntil ?? null,
+    isLifetime: input.isLifetime ?? false,
+  });
+  if (changed.ok) return changed;
+  if (changed.error === "billing.account_unknown") return err(changed.error);
+  // An import event is never refused.
+  throw new Error(`@softure-ai/billing: importing an entitlement failed with ${changed.error}`);
+}
+
+/** How many accounts `pinDerivedTrials` reads and writes at a time. */
+const PIN_BATCH_SIZE = 500;
+
+/**
+ * Writes the derived trial of every account without a row into a row (exactly what reads derive,
+ * `trial.startsAt` included), so a later change of `trial.days`, `trial.startsAt` or the time zone
+ * moves no existing trial. A row written meanwhile by a change is kept. Returns how many rows it
+ * wrote. Run it in a transaction (the `pin-trials` script does) to pin all or nothing. Database
+ * errors propagate.
+ */
+export async function pinDerivedTrials(ctx: BillingContext): Promise<number> {
+  const now = ctx.clock.now();
+  let pinned = 0;
+  let after: string | null = null;
+  for (;;) {
+    const accounts: { id: string; createdAt: Date }[] = await ctx.db
+      .select({ id: users.id, createdAt: users.createdAt })
+      .from(users)
+      .leftJoin(entitlements, eq(entitlements.userId, users.id))
+      .where(after === null ? isNull(entitlements.userId) : and(isNull(entitlements.userId), gt(users.id, after)))
+      .orderBy(asc(users.id))
+      .limit(PIN_BATCH_SIZE);
+    const last = accounts.at(-1);
+    if (last === undefined) return pinned;
+    const inserted = await ctx.db
+      .insert(entitlements)
+      .values(accounts.map((account) => ({ userId: account.id, ...getDefaultRecord(ctx, account.createdAt), createdAt: now, updatedAt: now })))
+      .onConflictDoNothing({ target: entitlements.userId })
+      .returning();
+    pinned += inserted.length;
+    after = last.id;
+  }
+}

package/src/server/grants.ts

@@ -0,0 +1,227 @@
+// Plans an admin grants by hand (the manual adapter's second half): each grant is recorded in
+// `billing.manual_grants` with what it added, who granted it and the request it answered, so a
+// mistaken one is revoked by taking back only that, and an account's history lists it beside its
+// provider payments. Locks follow `refundPayment`'s order (account, then the entitlement, then the
+// grant or request row), so none of them deadlock. A grant pins the account's derived row before it
+// locks it, so its lifetime check holds even before the account's first change.
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { and, desc, eq } from "drizzle-orm";
+import type { AdminErrorCode, Entitlement, PaymentGrant, PlanPrice } from "../contract.js";
+import { findPlan } from "../plans.js";
+import { entitlements, manualGrants, paymentRequests, payments } from "../schema.js";
+import { findEntitlementRecord, pinEntitlementRow, type BillingContext } from "./entitlements.js";
+import { getGrantColumns, readGrant } from "./payments.js";
+import { applyPlan, getBillingPlans } from "./plans.js";
+import { findOpenRequest, getClosedRequestColumns, readPrice } from "./requests.js";
+import { hasActiveManualLifetime, hasPaidLifetimePayment, lockEntitlementRow, takeBackGrant } from "./take-back.js";
+import { isUserId, isUuid } from "./user-id.js";
+
+export interface GrantPlanManuallyInput {
+  readonly userId: string;
+  readonly planId: string;
+  /** The admin who grants; null for a grant without one (a script). */
+  readonly adminId: string | null;
+  /** The open request this grant answers; it is closed in the same transaction. */
+  readonly requestId?: string;
+}
+
+export interface ManualGrantResult {
+  readonly grantId: string;
+  /** Where the account stands after the grant. */
+  readonly entitlement: Entitlement;
+}
+
+export type GrantPlanManuallyError = "billing.plan_unknown" | "billing.account_unknown" | "billing.lifetime_active" | "billing.request_closed";
+
+/**
+ * Grants one payment of a plan by hand and records it, in one transaction: a paid period that
+ * starts when the account's current access ends, or lifetime access. Refuses an account that has
+ * lifetime access already, and a request that is no longer open; every refusal writes nothing.
+ * Database errors propagate.
+ */
+export async function grantPlanManually(ctx: BillingContext, input: GrantPlanManuallyInput): Promise<Ok<ManualGrantResult> | Err<GrantPlanManuallyError>> {
+  const plan = findPlan(getBillingPlans(ctx.config), input.planId);
+  if (plan === undefined) return err("billing.plan_unknown");
+  if (!isUserId(input.userId)) return err("billing.account_unknown");
+  if (input.requestId !== undefined && !isUuid(input.requestId)) return err("billing.request_closed");
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    // A shared lock: the account cannot be deleted before the grant below.
+    const [account] = await tx.select({ createdAt: users.createdAt }).from(users).where(eq(users.id, input.userId)).for("key share");
+    if (account === undefined) return err("billing.account_unknown");
+    // The entitlement pinned and locked before the check, so a lifetime granted meanwhile is seen
+    // here, also by a grant that started before the account had a row.
+    const isPinned = await pinEntitlementRow({ ...ctx, db: tx }, { userId: input.userId, accountCreatedAt: account.createdAt });
+    await lockEntitlementRow(tx, input.userId);
+    const record = await findEntitlementRecord({ ...ctx, db: tx }, input.userId);
+    if (record?.isLifetime === true) return err("billing.lifetime_active");
+
+    // The price the grant is for: what its request quoted, else the plan's price now.
+    let price: PlanPrice = plan.price;
+    if (input.requestId !== undefined) {
+      const [closed] = await tx
+        .update(paymentRequests)
+        .set(getClosedRequestColumns("granted", now))
+        .where(and(eq(paymentRequests.id, input.requestId), eq(paymentRequests.userId, input.userId), eq(paymentRequests.status, "open")))
+        .returning();
+      // The request was granted or dismissed meanwhile, or is another account's: undo the pin, so
+      // the refusal writes nothing (the row is this transaction's, nobody else has seen it).
+      if (closed === undefined) {
+        if (isPinned) await tx.delete(entitlements).where(eq(entitlements.userId, input.userId));
+        return err("billing.request_closed");
+      }
+      price = readPrice(closed.amount, closed.currency) ?? price;
+    }
+
+    const applied = await applyPlan({ ...ctx, db: tx }, input.userId, input.planId);
+    // The plan and the locked account were checked above, and a plan grant always ends later.
+    if (!applied.ok) throw new Error(`@softure-ai/billing: granting plan "${input.planId}" by hand failed with ${applied.error}`);
+    const { grant } = applied.value;
+    // A plan grant always adds a period of at least a day, or lifetime access.
+    if (grant === null) throw new Error(`@softure-ai/billing: plan "${input.planId}" was granted by hand but added nothing`);
+    const [row] = await tx
+      .insert(manualGrants)
+      .values({
+        userId: input.userId,
+        planId: input.planId,
+        requestId: input.requestId ?? null,
+        grantedBy: input.adminId,
+        grantedAt: now,
+        ...getGrantColumns(grant),
+        grantKind: grant.kind,
+        status: "active",
+        amount: price.amount,
+        currency: price.currency,
+      })
+      .returning();
+    if (row === undefined) throw new Error("@softure-ai/billing: recording a manual grant returned no row");
+    return ok({ grantId: row.id, entitlement: applied.value.entitlement });
+  });
+}
+
+export interface GrantPaymentRequestInput {
+  readonly requestId: string;
+  readonly adminId: string | null;
+}
+
+/** Grants the plan an open request asked for and closes the request (`grantPlanManually`). */
+export async function grantPaymentRequest(ctx: BillingContext, input: GrantPaymentRequestInput): Promise<Ok<ManualGrantResult> | Err<GrantPlanManuallyError>> {
+  const request = await findOpenRequest(ctx.db, input.requestId);
+  if (request === undefined) return err("billing.request_closed");
+  return grantPlanManually(ctx, { userId: request.userId, planId: request.planId, adminId: input.adminId, requestId: input.requestId });
+}
+
+export interface RevokeManualGrantInput {
+  readonly grantId: string;
+  readonly adminId: string | null;
+}
+
+/**
+ * Revokes a manual grant and takes back what it added, in one transaction: a period loses its
+ * unused days (later periods move back), a lifetime ends unless another active manual lifetime or a
+ * paid lifetime payment still gives it. `billing.grant_revoked` when it was revoked before or never
+ * existed. Database errors propagate.
+ */
+export async function revokeManualGrant(ctx: BillingContext, input: RevokeManualGrantInput): Promise<Ok<Entitlement> | Err<Extract<AdminErrorCode, "billing.grant_revoked">>> {
+  if (!isUuid(input.grantId)) return err("billing.grant_revoked");
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    const [found] = await tx.select({ userId: manualGrants.userId }).from(manualGrants).where(eq(manualGrants.id, input.grantId));
+    if (found === undefined) return err("billing.grant_revoked");
+    // The account first (the lock order of every change), the entitlement, then the conditional update.
+    await tx.select({ id: users.id }).from(users).where(eq(users.id, found.userId)).for("key share");
+    await lockEntitlementRow(tx, found.userId);
+    const [revoked] = await tx
+      .update(manualGrants)
+      .set({ status: "revoked", revokedAt: now, revokedBy: input.adminId })
+      .where(and(eq(manualGrants.id, input.grantId), eq(manualGrants.status, "active")))
+      .returning();
+    // Revoked by a concurrent click, or erased with the account in the meantime.
+    if (revoked === undefined) return err("billing.grant_revoked");
+    const { entitlement } = await takeBackGrant(
+      { ...ctx, db: tx },
+      {
+        userId: found.userId,
+        grant: readGrant(revoked),
+        now,
+        hasOtherLifetime: async () => (await hasActiveManualLifetime(tx, found.userId, revoked.id)) || (await hasPaidLifetimePayment(tx, found.userId)),
+      },
+    );
+    return ok(entitlement);
+  });
+}
+
+/** One line of an account's history: a grant typed in by an admin, or a payment a provider reported. */
+export type AccountHistoryEntry =
+  | {
+      readonly source: "manual";
+      readonly id: string;
+      readonly planId: string;
+      readonly at: Date;
+      readonly grant: PaymentGrant;
+      readonly status: "active" | "revoked";
+      readonly revokedAt: Date | null;
+      /** Whether it answered an invoice request. */
+      readonly isFromRequest: boolean;
+      /** What it was granted for; null for a grant recorded before prices were. */
+      readonly price: PlanPrice | null;
+    }
+  | {
+      readonly source: "provider";
+      readonly id: string;
+      readonly provider: string;
+      readonly planId: string;
+      readonly at: Date;
+      /** Null for a payment recorded before grants were. */
+      readonly grant: PaymentGrant | null;
+      readonly amount: number;
+      readonly currency: string;
+      readonly status: "paid" | "refunded";
+      readonly refundedAt: Date | null;
+      /** The total refunded so far: part of `amount` while the payment is still paid. */
+      readonly refundedAmount: number;
+    };
+
+/** How many entries of each source the history reads. */
+export const ACCOUNT_HISTORY_LIMIT = 100;
+
+/** The account's manual grants and provider payments, newest first. Database errors propagate. */
+export async function getAccountHistory(ctx: Pick<BillingContext, "db">, userId: string): Promise<readonly AccountHistoryEntry[]> {
+  if (!isUserId(userId)) return [];
+  const grantRows = await ctx.db
+    .select()
+    .from(manualGrants)
+    .where(eq(manualGrants.userId, userId))
+    .orderBy(desc(manualGrants.grantedAt), desc(manualGrants.id))
+    .limit(ACCOUNT_HISTORY_LIMIT);
+  const paymentRows = await ctx.db
+    .select()
+    .from(payments)
+    .where(eq(payments.userId, userId))
+    .orderBy(desc(payments.paidAt), desc(payments.id))
+    .limit(ACCOUNT_HISTORY_LIMIT);
+  const entries: AccountHistoryEntry[] = [];
+  for (const row of grantRows) {
+    const grant = readGrant(row);
+    // The CHECK on manual_grants requires a complete grant on every row.
+    if (grant === null) throw new Error(`@softure-ai/billing: manual grant ${row.id} has no grant recorded`);
+    entries.push({ source: "manual", id: row.id, planId: row.planId, at: row.grantedAt, grant, status: row.status, revokedAt: row.revokedAt, isFromRequest: row.requestId !== null, price: readPrice(row.amount, row.currency) });
+  }
+  for (const row of paymentRows) {
+    entries.push({
+      source: "provider",
+      id: row.id,
+      provider: row.provider,
+      planId: row.planId,
+      at: row.paidAt,
+      grant: readGrant(row),
+      amount: row.amount,
+      currency: row.currency,
+      status: row.status,
+      refundedAt: row.refundedAt,
+      refundedAmount: row.refundedAmount,
+    });
+  }
+  return entries.sort((first, second) => second.at.getTime() - first.at.getTime());
+}

package/src/server/health.ts

@@ -0,0 +1,18 @@
+// The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the entitlements,
+// payments, payment requests and manual grants tables exist and answer, i.e. `softure migrate` ran,
+// and the setup is sound (`adminRole` is declared), so a deploy fails before traffic. It reads no rows.
+import { ok, type HealthCheck } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { sql } from "drizzle-orm";
+import { assertAdminRoleDeclared } from "./setup.js";
+
+export const checkBillingTables: HealthCheck = async (context) => {
+  assertAdminRoleDeclared(context.config);
+  // Core types `db` as unknown; the health route passes the @softure-ai/db handle.
+  const db = context.db as Queryable;
+  await db.execute(sql`select 1 from billing.entitlements limit 0`);
+  await db.execute(sql`select 1 from billing.payments limit 0`);
+  await db.execute(sql`select 1 from billing.payment_requests limit 0`);
+  await db.execute(sql`select 1 from billing.manual_grants limit 0`);
+  return ok();
+};

package/src/server/index.ts

@@ -0,0 +1,83 @@
+// Server-only API of @softure-ai/billing. Every function receives the module context
+// (`{ db, clock, config }`) and never reads request scope; `next/*` imports are not allowed here.
+export {
+  changeEntitlement,
+  checkWriteAccess,
+  findEntitlementRecord,
+  getDefaultRecord,
+  getEntitlement,
+  importEntitlement,
+  pinDerivedTrials,
+  type BillingContext,
+  type EntitlementEventResolver,
+  type ImportEntitlementInput,
+} from "./entitlements.js";
+export {
+  ACCOUNT_HISTORY_LIMIT,
+  getAccountHistory,
+  grantPaymentRequest,
+  grantPlanManually,
+  revokeManualGrant,
+  type AccountHistoryEntry,
+  type GrantPaymentRequestInput,
+  type GrantPlanManuallyError,
+  type GrantPlanManuallyInput,
+  type ManualGrantResult,
+  type RevokeManualGrantInput,
+} from "./grants.js";
+export { checkBillingTables } from "./health.js";
+export { findAccessReminders, type AccessReminderDue, type FindAccessRemindersOptions } from "./reminders.js";
+export {
+  failRefund,
+  receiveStripeWebhook,
+  recordPayment,
+  refundPayment,
+  STRIPE_PROVIDER,
+  type FailRefundInput,
+  type PaymentOutcome,
+  type ReceiveStripeWebhookInput,
+  type RecordPaymentError,
+  type RecordPaymentInput,
+  type RefundPaymentInput,
+  type StripeWebhookReceipt,
+} from "./payments.js";
+export {
+  getBillingMessages,
+  getBillingModule,
+  getBillingOptions,
+  getBillingRoutes,
+  getEntitlementPolicy,
+  type BillingRoutes,
+} from "./options.js";
+export {
+  findAccountByEmail,
+  findAccountById,
+  getBillingPlans,
+  getPaymentProvider,
+  grantPlan,
+  startPayment,
+  type StartPaymentInput,
+  type StartPaymentResult,
+} from "./plans.js";
+export { parseInvoiceDetails, type InvoiceDetailsError, type InvoiceInput } from "../invoice.js";
+export {
+  billingPrivacyContributor,
+  deleteBillingUserData,
+  exportBillingUserData,
+  type BillingManualGrantData,
+  type BillingPaymentData,
+  type BillingPaymentRequestData,
+  type BillingRefundFailureData,
+  type BillingUserData,
+} from "./privacy.js";
+export {
+  dismissPaymentRequest,
+  expireStaleRequests,
+  listOpenRequests,
+  OPEN_REQUESTS_LIMIT,
+  recordPaymentRequest,
+  type ExpiredRequestsSummary,
+  type OpenPaymentRequest,
+  type RecordPaymentRequestInput,
+} from "./requests.js";
+export { assertAdminRoleDeclared, assertPaymentSetup, PAYMENT_BUCKET } from "./setup.js";

package/src/server/options.ts

@@ -0,0 +1,52 @@
+// The billing options of the running app, read from the configuration in the module context.
+import { getModule, type AnySoftureModule, type SoftureConfig } from "@softure-ai/core";
+import type { EntitlementPolicy } from "../entitlement.js";
+import type { BillingMessages } from "../messages/index.js";
+import type { BillingOptions } from "../options.js";
+
+const MODULE_ID = "billing";
+
+/** The enabled module. Throws when the app did not enable it: calling its functions then is a bug. */
+export function getBillingModule(config: SoftureConfig): AnySoftureModule {
+  const module = getModule(config, MODULE_ID);
+  if (module === undefined) {
+    throw new Error("@softure-ai/billing: the module is not enabled; add billing({ ... }) to modules in softure.config.ts");
+  }
+  return module;
+}
+
+export function getBillingOptions(config: SoftureConfig): BillingOptions {
+  // The module factory parsed these options with billingOptionsSchema.
+  return getBillingModule(config).options as BillingOptions;
+}
+
+/** The module's copy in the app's locale, with the app's overrides applied. */
+export function getBillingMessages(config: SoftureConfig): BillingMessages {
+  // The module factory merged the dictionaries; their shape is the module's own.
+  return getBillingModule(config).messages[config.locale] as BillingMessages;
+}
+
+export interface BillingRoutes {
+  /** The payment page (`PaymentPage`), where the notices and the pricing tiles send an account to pay. */
+  readonly payment: string;
+  /** The admin page (`BillingAdminPage`), refreshed after an admin action and linked from a request to its account. */
+  readonly admin: string;
+}
+
+/** The module's routes with the app's overrides applied. */
+export function getBillingRoutes(config: SoftureConfig): BillingRoutes {
+  const routes = getBillingModule(config).routes;
+  const read = (name: keyof BillingRoutes): string => {
+    const path = routes[name];
+    // The manifest declares every route, so a missing one means a broken module definition.
+    if (path === undefined) throw new Error(`@softure-ai/billing: route "${name}" is missing from the module manifest`);
+    return path;
+  };
+  return { payment: read("payment"), admin: read("admin") };
+}
+
+/** The state machine's policy from the options and the app's time zone. */
+export function getEntitlementPolicy(config: SoftureConfig): EntitlementPolicy {
+  const options = getBillingOptions(config);
+  return { timezone: config.timezone, trialReminderDays: options.trial.reminderDays, paidReminderDays: options.paid.reminderDays };
+}