@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/server/privacy.ts

@@ -0,0 +1,189 @@
+// The billing part of a GDPR export and deletion (`@softure-ai/privacy`): the account's entitlement
+// row, its provider payments and their failed refunds, its invoice requests and the plans granted
+// to it by hand. An account
+// without an entitlement row has no stored entitlement (its trial is derived from the account). The
+// provider keeps its own records of the payments. Which admin granted or revoked a plan is the
+// admin's data, not the account's, and is left out of the export.
+import { users } from "@softure-ai/auth";
+import { ok, type ModuleContext, type Ok, type PrivacyContributor } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { asc, eq } from "drizzle-orm";
+import { entitlements, manualGrants, paymentRequests, payments, refundFailures } from "../schema.js";
+import { isUserId } from "./user-id.js";
+
+/** One provider payment, as it appears in an export. */
+export interface BillingPaymentData {
+  readonly provider: string;
+  readonly checkoutId: string;
+  readonly paymentId: string | null;
+  readonly planId: string;
+  readonly amount: number;
+  readonly currency: string;
+  readonly status: "paid" | "refunded";
+  readonly paidAt: Date;
+  readonly refundedAt: Date | null;
+  /** The total refunded so far, in the currency's minor unit. */
+  readonly refundedAmount: number;
+  /** What the payment granted: `period` (from, until) or `lifetime`; null when recorded before grants were. */
+  readonly grantKind: "period" | "lifetime" | null;
+  readonly grantedFrom: Date | null;
+  readonly grantedUntil: Date | null;
+}
+
+/** One provider refund that failed, as it appears in an export. */
+export interface BillingRefundFailureData {
+  /** The provider's payment id of the refunded payment (`BillingPaymentData.paymentId`). */
+  readonly paymentId: string | null;
+  readonly refundId: string;
+  /** What the refund was for, in the currency's minor unit. */
+  readonly amount: number;
+  readonly refundCreatedAt: Date;
+  readonly failedAt: Date;
+}
+
+/** One invoice request, as it appears in an export; the details are gone once it was closed. */
+export interface BillingPaymentRequestData {
+  readonly planId: string;
+  readonly invoiceName: string | null;
+  readonly invoiceTaxId: string | null;
+  readonly invoiceAddress: string | null;
+  /** The plan's price the request quoted, in the currency's minor unit; null before prices were recorded. */
+  readonly amount: number | null;
+  readonly currency: string | null;
+  readonly status: "open" | "granted" | "dismissed" | "expired";
+  readonly requestedAt: Date;
+  readonly closedAt: Date | null;
+}
+
+/** One plan granted by hand, as it appears in an export. */
+export interface BillingManualGrantData {
+  readonly planId: string;
+  readonly grantedAt: Date;
+  readonly grantKind: "period" | "lifetime";
+  readonly grantedFrom: Date | null;
+  readonly grantedUntil: Date | null;
+  readonly status: "active" | "revoked";
+  readonly revokedAt: Date | null;
+  /** What it was granted for, in the currency's minor unit; null before prices were recorded. */
+  readonly amount: number | null;
+  readonly currency: string | null;
+}
+
+/** What billing holds about one user, as it appears in their export. */
+export interface BillingUserData {
+  readonly entitlement: {
+    readonly trialEndsAt: Date;
+    readonly paidUntil: Date | null;
+    readonly isLifetime: boolean;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+  } | null;
+  /** Oldest first. */
+  readonly payments: readonly BillingPaymentData[];
+  /** Oldest first. */
+  readonly refundFailures: readonly BillingRefundFailureData[];
+  /** Oldest first. */
+  readonly paymentRequests: readonly BillingPaymentRequestData[];
+  /** Oldest first. */
+  readonly manualGrants: readonly BillingManualGrantData[];
+}
+
+const EMPTY_USER_DATA: BillingUserData = { entitlement: null, payments: [], refundFailures: [], paymentRequests: [], manualGrants: [] };
+
+export async function exportBillingUserData(context: ModuleContext, userId: string): Promise<Ok<BillingUserData>> {
+  if (!isUserId(userId)) return ok(EMPTY_USER_DATA);
+  // Core types `db` as unknown; privacy passes the @softure-ai/db handle or its transaction.
+  const db = context.db as Queryable;
+  const [row] = await db
+    .select({
+      trialEndsAt: entitlements.trialEndsAt,
+      paidUntil: entitlements.paidUntil,
+      isLifetime: entitlements.isLifetime,
+      createdAt: entitlements.createdAt,
+      updatedAt: entitlements.updatedAt,
+    })
+    .from(entitlements)
+    .where(eq(entitlements.userId, userId));
+  const paymentRows = await db
+    .select({
+      provider: payments.provider,
+      checkoutId: payments.checkoutId,
+      paymentId: payments.paymentId,
+      planId: payments.planId,
+      amount: payments.amount,
+      currency: payments.currency,
+      status: payments.status,
+      paidAt: payments.paidAt,
+      refundedAt: payments.refundedAt,
+      refundedAmount: payments.refundedAmount,
+      grantKind: payments.grantKind,
+      grantedFrom: payments.grantedFrom,
+      grantedUntil: payments.grantedUntil,
+    })
+    .from(payments)
+    .where(eq(payments.userId, userId))
+    .orderBy(asc(payments.paidAt), asc(payments.id));
+  const failureRows = await db
+    .select({
+      paymentId: payments.paymentId,
+      refundId: refundFailures.refundId,
+      amount: refundFailures.amount,
+      refundCreatedAt: refundFailures.refundCreatedAt,
+      failedAt: refundFailures.failedAt,
+    })
+    .from(refundFailures)
+    .innerJoin(payments, eq(payments.id, refundFailures.paymentId))
+    .where(eq(payments.userId, userId))
+    .orderBy(asc(refundFailures.failedAt), asc(refundFailures.refundId));
+  const requestRows = await db
+    .select({
+      planId: paymentRequests.planId,
+      invoiceName: paymentRequests.invoiceName,
+      invoiceTaxId: paymentRequests.invoiceTaxId,
+      invoiceAddress: paymentRequests.invoiceAddress,
+      amount: paymentRequests.amount,
+      currency: paymentRequests.currency,
+      status: paymentRequests.status,
+      requestedAt: paymentRequests.requestedAt,
+      closedAt: paymentRequests.closedAt,
+    })
+    .from(paymentRequests)
+    .where(eq(paymentRequests.userId, userId))
+    .orderBy(asc(paymentRequests.requestedAt), asc(paymentRequests.id));
+  const grantRows = await db
+    .select({
+      planId: manualGrants.planId,
+      grantedAt: manualGrants.grantedAt,
+      grantKind: manualGrants.grantKind,
+      grantedFrom: manualGrants.grantedFrom,
+      grantedUntil: manualGrants.grantedUntil,
+      status: manualGrants.status,
+      revokedAt: manualGrants.revokedAt,
+      amount: manualGrants.amount,
+      currency: manualGrants.currency,
+    })
+    .from(manualGrants)
+    .where(eq(manualGrants.userId, userId))
+    .orderBy(asc(manualGrants.grantedAt), asc(manualGrants.id));
+  return ok({ entitlement: row ?? null, payments: paymentRows, refundFailures: failureRows, paymentRequests: requestRows, manualGrants: grantRows });
+}
+
+export async function deleteBillingUserData(context: ModuleContext, userId: string): Promise<Ok<undefined>> {
+  if (!isUserId(userId)) return ok();
+  const db = context.db as Queryable;
+  // Lock the account first, in the order `changeEntitlement` takes its locks (account, then
+  // entitlement): a change running at the same time then waits instead of deadlocking the erase.
+  await db.select({ id: users.id }).from(users).where(eq(users.id, userId)).for("update");
+  await db.delete(entitlements).where(eq(entitlements.userId, userId));
+  // Their failed refunds go with them (ON DELETE CASCADE).
+  await db.delete(payments).where(eq(payments.userId, userId));
+  // Grants first: they reference the requests they answered.
+  await db.delete(manualGrants).where(eq(manualGrants.userId, userId));
+  await db.delete(paymentRequests).where(eq(paymentRequests.userId, userId));
+  return ok();
+}
+
+export const billingPrivacyContributor: PrivacyContributor = {
+  exportUserData: exportBillingUserData,
+  deleteUserData: deleteBillingUserData,
+};

package/src/server/reminders.ts

@@ -0,0 +1,113 @@
+// The accounts due a reminder mail now. Two bounded range queries find the candidates: stored rows
+// whose trial or dated paid access ends inside the widest window, and accounts without a row whose
+// derived trial does (its end day is the creation day plus `trial.days`, so the window is a range
+// on `auth.users.created_at`, indexed by auth, plus every account under `trial.startsAt` when the
+// floor's trial ends in it). The pure rule then decides each candidate exactly,
+// so the ranges only need to be wide enough, never exact.
+import { users } from "@softure-ai/auth";
+import { and, asc, eq, gte, isNull, lt, or, type SQL } from "drizzle-orm";
+import { getDayNumber, getStartOfDay } from "../calendar.js";
+import type { EntitlementRecord } from "../contract.js";
+import { DEFAULT_CATCH_UP_DAYS, getAccessReminder, MAX_CATCH_UP_DAYS, type AccessReminderKind } from "../reminder.js";
+import { entitlements } from "../schema.js";
+import { getDefaultRecord, getTrialFloorDay, type BillingContext } from "./entitlements.js";
+import { getBillingOptions, getEntitlementPolicy } from "./options.js";
+
+export interface FindAccessRemindersOptions {
+  /** An ended mail is due from the day access ended through this many local days after it. Default 3. */
+  readonly catchUpDays?: number;
+}
+
+export interface AccessReminderDue {
+  readonly userId: string;
+  readonly email: string;
+  readonly kind: AccessReminderKind;
+  /** The first instant without the access the mail is about. */
+  readonly endsAt: Date;
+}
+
+interface Candidate {
+  readonly userId: string;
+  readonly email: string;
+  readonly createdAt: Date;
+  readonly record: EntitlementRecord;
+}
+
+/**
+ * Every account due a reminder at the clock's now, ordered by end, then account. Reads only.
+ * Throws for a `catchUpDays` that is not an integer from 0 to 365 (a caller bug); database errors
+ * propagate.
+ */
+export async function findAccessReminders(ctx: BillingContext, options: FindAccessRemindersOptions = {}): Promise<AccessReminderDue[]> {
+  const catchUpDays = options.catchUpDays ?? DEFAULT_CATCH_UP_DAYS;
+  if (!Number.isInteger(catchUpDays) || catchUpDays < 0 || catchUpDays > MAX_CATCH_UP_DAYS) {
+    throw new Error(`@softure-ai/billing: catchUpDays must be an integer from 0 to ${String(MAX_CATCH_UP_DAYS)}, got ${String(catchUpDays)}`);
+  }
+  const now = ctx.clock.now();
+  const policy = getEntitlementPolicy(ctx.config);
+  const candidates = [...(await findStoredCandidates(ctx, now, catchUpDays)), ...(await findDerivedCandidates(ctx, now, catchUpDays))];
+
+  const due: AccessReminderDue[] = [];
+  for (const candidate of candidates) {
+    const reminder = getAccessReminder({ record: candidate.record, accountCreatedAt: candidate.createdAt, now, policy, catchUpDays });
+    if (reminder !== null) due.push({ userId: candidate.userId, email: candidate.email, ...reminder });
+  }
+  return due.sort((first, second) => first.endsAt.getTime() - second.endsAt.getTime() || first.userId.localeCompare(second.userId));
+}
+
+/** Stored rows without lifetime whose trial or paid end lies from the catch-up start to past the widest reminder window. */
+async function findStoredCandidates(ctx: BillingContext, now: Date, catchUpDays: number): Promise<Candidate[]> {
+  const { timezone } = ctx.config;
+  const { trial, paid } = getBillingOptions(ctx.config);
+  const today = getDayNumber(now, timezone);
+  const from = getStartOfDay(today - catchUpDays, timezone);
+  const to = getStartOfDay(today + Math.max(trial.reminderDays, paid.reminderDays) + 1, timezone);
+  const rows = await ctx.db
+    .select({
+      userId: users.id,
+      email: users.email,
+      createdAt: users.createdAt,
+      trialEndsAt: entitlements.trialEndsAt,
+      paidUntil: entitlements.paidUntil,
+      isLifetime: entitlements.isLifetime,
+    })
+    .from(entitlements)
+    .innerJoin(users, eq(users.id, entitlements.userId))
+    .where(
+      and(
+        eq(entitlements.isLifetime, false),
+        or(and(gte(entitlements.trialEndsAt, from), lt(entitlements.trialEndsAt, to)), and(gte(entitlements.paidUntil, from), lt(entitlements.paidUntil, to))),
+      ),
+    )
+    .orderBy(asc(users.id));
+  return rows.map(({ trialEndsAt, paidUntil, isLifetime, ...account }) => ({ ...account, record: { trialEndsAt, paidUntil, isLifetime } }));
+}
+
+/**
+ * Accounts without a row whose derived trial ends in the same span: a trial ends at the start of
+ * the creation day plus `trial.days`, so the span moves back by `trial.days` onto `created_at`.
+ * Under `trial.startsAt` every account created before the floor day shares one trial end; when that
+ * end lies in the span, they are all candidates.
+ */
+async function findDerivedCandidates(ctx: BillingContext, now: Date, catchUpDays: number): Promise<Candidate[]> {
+  const { timezone } = ctx.config;
+  const { trial } = getBillingOptions(ctx.config);
+  const today = getDayNumber(now, timezone);
+  const from = getStartOfDay(today - catchUpDays - trial.days, timezone);
+  const to = getStartOfDay(today + trial.reminderDays + 1 - trial.days, timezone);
+  let createdInSpan: SQL | undefined = and(gte(users.createdAt, from), lt(users.createdAt, to));
+  const floorDay = getTrialFloorDay(ctx);
+  if (floorDay !== null) {
+    const floorEndDay = floorDay + trial.days;
+    if (floorEndDay >= today - catchUpDays && floorEndDay <= today + trial.reminderDays) {
+      createdInSpan = or(createdInSpan, lt(users.createdAt, getStartOfDay(floorDay, timezone)));
+    }
+  }
+  const rows = await ctx.db
+    .select({ userId: users.id, email: users.email, createdAt: users.createdAt })
+    .from(users)
+    .leftJoin(entitlements, eq(entitlements.userId, users.id))
+    .where(and(isNull(entitlements.userId), createdInSpan))
+    .orderBy(asc(users.id));
+  return rows.map((account) => ({ ...account, record: getDefaultRecord(ctx, account.createdAt) }));
+}

package/src/server/requests.ts

@@ -0,0 +1,201 @@
+// Invoice requests in billing: stored before a provider hands a request over (the manual adapter),
+// listed in the admin page until the admin grants or dismisses them or they expire. One open
+// request per account and plan: asking again refreshes its details and price. The hand-over is
+// claimed on the row (`handover_claimed_at`) and recorded once it answered (`handed_over_at`), so
+// an open request reaches the owner once; a failed hand-over is released for the next ask, and a
+// claim left without an answer (the process stopped) is taken over after a minute. Closing a request clears its invoice details, which are
+// personal data the app no longer needs (the migration's CHECK holds closed rows empty).
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { and, asc, eq, isNull, lt, lte, or, sql } from "drizzle-orm";
+import type { PlanPrice } from "../contract.js";
+import type { InvoiceDetails } from "../payment.js";
+import { paymentRequests } from "../schema.js";
+import type { BillingContext } from "./entitlements.js";
+import { getBillingOptions } from "./options.js";
+import { isUuid } from "./user-id.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** How long a hand-over claim blocks other asks: a provider's mail call takes seconds. */
+const HANDOVER_CLAIM_TIMEOUT_MS = 60 * 1000;
+
+/** How many open requests the admin page lists by default. */
+export const OPEN_REQUESTS_LIMIT = 50;
+
+export interface RecordPaymentRequestInput {
+  readonly userId: string;
+  readonly planId: string;
+  /** Null when the provider collects its own details. */
+  readonly invoice: InvoiceDetails | null;
+  /** The plan's price now: what the request quotes. */
+  readonly price: PlanPrice;
+}
+
+/** An open request, as the admin page lists it. */
+export interface OpenPaymentRequest {
+  readonly id: string;
+  readonly userId: string;
+  readonly email: string;
+  readonly planId: string;
+  readonly invoice: InvoiceDetails | null;
+  /** The plan's price when it was asked for; null for a request stored before prices were. */
+  readonly price: PlanPrice | null;
+  readonly requestedAt: Date;
+}
+
+/** The columns that close a request: its status, when, and no invoice details any more. */
+export function getClosedRequestColumns(status: "granted" | "dismissed" | "expired", now: Date) {
+  return { status, closedAt: now, invoiceName: null, invoiceTaxId: null, invoiceAddress: null };
+}
+
+/**
+ * Stores a request before it is handed over to the owner, or refreshes the account's open request
+ * for the same plan (its details, price and time; its hand-over and claim stay). Returns the
+ * request's id. Database errors propagate.
+ */
+export async function recordPaymentRequest(ctx: Pick<BillingContext, "db" | "clock">, input: RecordPaymentRequestInput): Promise<string> {
+  const now = ctx.clock.now();
+  const details = {
+    invoiceName: input.invoice?.name ?? null,
+    invoiceTaxId: input.invoice?.taxId ?? null,
+    invoiceAddress: input.invoice?.address ?? null,
+    amount: input.price.amount,
+    currency: input.price.currency,
+  };
+  const [row] = await ctx.db
+    .insert(paymentRequests)
+    .values({ userId: input.userId, planId: input.planId, ...details, status: "open", requestedAt: now })
+    .onConflictDoUpdate({
+      target: [paymentRequests.userId, paymentRequests.planId],
+      targetWhere: sql`status = 'open'`,
+      set: { ...details, requestedAt: now },
+    })
+    .returning();
+  // An insert or an update of the conflicting row always returns it.
+  if (row === undefined) throw new Error("@softure-ai/billing: storing a payment request returned no row");
+  return row.id;
+}
+
+/**
+ * Claims the hand-over of an open request that was not handed over yet: the time it was claimed,
+ * or null when it was handed over already, is being handed over (a claim younger than
+ * `HANDOVER_CLAIM_TIMEOUT_MS`), or is no longer open. An older claim was left without an answer and
+ * is taken over. A conditional update, so two asks at once hand it over once. Database errors
+ * propagate.
+ */
+export async function claimHandOver(ctx: Pick<BillingContext, "db" | "clock">, requestId: string): Promise<Date | null> {
+  const now = ctx.clock.now();
+  const staleBefore = new Date(now.getTime() - HANDOVER_CLAIM_TIMEOUT_MS);
+  const [claimed] = await ctx.db
+    .update(paymentRequests)
+    .set({ handoverClaimedAt: now })
+    .where(
+      and(
+        eq(paymentRequests.id, requestId),
+        eq(paymentRequests.status, "open"),
+        isNull(paymentRequests.handedOverAt),
+        or(isNull(paymentRequests.handoverClaimedAt), lte(paymentRequests.handoverClaimedAt, staleBefore)),
+      ),
+    )
+    .returning();
+  return claimed === undefined ? null : now;
+}
+
+/**
+ * Records a hand-over that answered: the request is never handed over again, whichever ask holds
+ * the claim now. The first record wins. Database errors propagate.
+ */
+export async function confirmHandOver(ctx: Pick<BillingContext, "db" | "clock">, requestId: string): Promise<void> {
+  await ctx.db
+    .update(paymentRequests)
+    .set({ handedOverAt: ctx.clock.now(), handoverClaimedAt: null })
+    .where(and(eq(paymentRequests.id, requestId), isNull(paymentRequests.handedOverAt)));
+}
+
+/**
+ * Gives back a claim whose hand-over failed, so the next ask tries again. Only the claim made at
+ * `claimedAt` is cleared, never a later one. Database errors propagate.
+ */
+export async function releaseHandOver(ctx: Pick<BillingContext, "db">, requestId: string, claimedAt: Date): Promise<void> {
+  await ctx.db
+    .update(paymentRequests)
+    .set({ handoverClaimedAt: null })
+    .where(and(eq(paymentRequests.id, requestId), eq(paymentRequests.handoverClaimedAt, claimedAt)));
+}
+
+/** The open requests, oldest first, with each account's email. */
+export async function listOpenRequests(ctx: Pick<BillingContext, "db">, limit: number = OPEN_REQUESTS_LIMIT): Promise<readonly OpenPaymentRequest[]> {
+  const rows = await ctx.db
+    .select({
+      id: paymentRequests.id,
+      userId: paymentRequests.userId,
+      email: users.email,
+      planId: paymentRequests.planId,
+      invoiceName: paymentRequests.invoiceName,
+      invoiceTaxId: paymentRequests.invoiceTaxId,
+      invoiceAddress: paymentRequests.invoiceAddress,
+      amount: paymentRequests.amount,
+      currency: paymentRequests.currency,
+      requestedAt: paymentRequests.requestedAt,
+    })
+    .from(paymentRequests)
+    .innerJoin(users, eq(users.id, paymentRequests.userId))
+    .where(eq(paymentRequests.status, "open"))
+    .orderBy(asc(paymentRequests.requestedAt), asc(paymentRequests.id))
+    .limit(limit);
+  return rows.map(({ invoiceName, invoiceTaxId, invoiceAddress, amount, currency, ...row }) => ({
+    ...row,
+    invoice: invoiceName === null || invoiceAddress === null ? null : { name: invoiceName, taxId: invoiceTaxId, address: invoiceAddress },
+    price: readPrice(amount, currency),
+  }));
+}
+
+/** The open request with this id (its account and plan), or undefined. */
+export async function findOpenRequest(db: Queryable, requestId: string): Promise<{ readonly userId: string; readonly planId: string } | undefined> {
+  if (!isUuid(requestId)) return undefined;
+  const [row] = await db
+    .select({ userId: paymentRequests.userId, planId: paymentRequests.planId })
+    .from(paymentRequests)
+    .where(and(eq(paymentRequests.id, requestId), eq(paymentRequests.status, "open")));
+  return row;
+}
+
+/** Closes an open request without a grant and clears its details; `billing.request_closed` when it is not open. */
+export async function dismissPaymentRequest(ctx: Pick<BillingContext, "db" | "clock">, requestId: string): Promise<Ok<undefined> | Err<"billing.request_closed">> {
+  if (!isUuid(requestId)) return err("billing.request_closed");
+  const [closed] = await ctx.db
+    .update(paymentRequests)
+    .set(getClosedRequestColumns("dismissed", ctx.clock.now()))
+    .where(and(eq(paymentRequests.id, requestId), eq(paymentRequests.status, "open")))
+    .returning();
+  return closed === undefined ? err("billing.request_closed") : ok();
+}
+
+export interface ExpiredRequestsSummary {
+  /** Open requests closed as `expired` by this run. */
+  readonly expired: number;
+}
+
+/**
+ * Closes the open requests nobody asked again for in `requests.expireAfterDays` days as `expired`
+ * and clears their invoice details: personal data kept no longer than the request waits. Run it
+ * daily (a scheduler); a repeated run closes nothing new. Database errors propagate.
+ */
+export async function expireStaleRequests(ctx: BillingContext): Promise<ExpiredRequestsSummary> {
+  const now = ctx.clock.now();
+  const { expireAfterDays } = getBillingOptions(ctx.config).requests;
+  const cutoff = new Date(now.getTime() - expireAfterDays * DAY_MS);
+  const expired = await ctx.db
+    .update(paymentRequests)
+    .set(getClosedRequestColumns("expired", now))
+    .where(and(eq(paymentRequests.status, "open"), lt(paymentRequests.requestedAt, cutoff)))
+    .returning();
+  return { expired: expired.length };
+}
+
+/** A stored price, or null when the row has none (a CHECK stores both or neither). */
+export function readPrice(amount: number | null, currency: string | null): PlanPrice | null {
+  return amount === null || currency === null ? null : { amount, currency };
+}

package/src/server/setup.ts

@@ -0,0 +1,37 @@
+// What billing needs from the app's other modules, checked once per config so a setup mistake fails
+// with one clear error instead of on each request: the rate limit bucket in `security({ buckets })`
+// (before the first payment), and an `adminRole` that `auth({ roles })` declares (at the first
+// billing request and in the readiness probe).
+import { getDeclaredRoles, isDeclaredRole } from "@softure-ai/auth/server";
+import { getModule, type SoftureConfig } from "@softure-ai/core";
+import { getBillingOptions } from "./options.js";
+
+export const PAYMENT_BUCKET = "billing-payment";
+
+const checkedPaymentConfigs = new WeakSet<SoftureConfig>();
+const checkedRoleConfigs = new WeakSet<SoftureConfig>();
+
+export function assertPaymentSetup(config: SoftureConfig): void {
+  if (checkedPaymentConfigs.has(config)) return;
+  const security = getModule(config, "security")?.options as { buckets?: Readonly<Record<string, unknown>> } | undefined;
+  if (!Object.hasOwn(security?.buckets ?? {}, PAYMENT_BUCKET)) {
+    throw new Error(`@softure-ai/billing: security({ buckets }) lacks "${PAYMENT_BUCKET}"; spread BILLING_RATE_LIMIT_BUCKETS into it`);
+  }
+  checkedPaymentConfigs.add(config);
+}
+
+/**
+ * Throws when `billing({ adminRole })` is not a role of `auth({ roles })`: a misspelt role would
+ * otherwise surface only when an admin opens the admin page.
+ */
+export function assertAdminRoleDeclared(config: SoftureConfig): void {
+  if (checkedRoleConfigs.has(config)) return;
+  const { adminRole } = getBillingOptions(config);
+  if (!isDeclaredRole(config, adminRole)) {
+    const declared = [...getDeclaredRoles(config)].join(", ");
+    throw new Error(
+      `@softure-ai/billing: billing({ adminRole }) is "${adminRole}", which auth({ roles }) does not declare (declared: ${declared}); declare it there or fix the name`,
+    );
+  }
+  checkedRoleConfigs.add(config);
+}