@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/price.ts

@@ -0,0 +1,50 @@
+// Prices of plans as the app shows them: the amount counts the currency's minor unit as billing
+// pins it (`src/currency-digits.ts`, ISO 4217), and the locale's `Intl` only supplies the notation,
+// so "PLN 29.00" in en and its Polish notation (a decimal comma, the currency sign after) come from
+// one config, and no runtime's CLDR can change the amount.
+import type { Locale } from "@softure-ai/core";
+import type { PlanPrice } from "./contract.js";
+import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
+
+const formatters = new Map<string, Intl.NumberFormat>();
+
+/** The pinned digits, or undefined for a code billing does not accept. */
+function findMinorUnitDigits(currency: string): number | undefined {
+  return Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
+}
+
+function getFormatter(locale: Locale, currency: string, digits: number | undefined): Intl.NumberFormat {
+  const key = `${locale}:${currency}`;
+  let format = formatters.get(key);
+  if (format === undefined) {
+    format = new Intl.NumberFormat(
+      locale,
+      digits === undefined ? { style: "currency", currency } : { style: "currency", currency, minimumFractionDigits: digits, maximumFractionDigits: digits },
+    );
+    formatters.set(key, format);
+  }
+  return format;
+}
+
+/** Whether billing accepts `currency`: an upper-case ISO 4217 code in its pinned table. */
+export function isSupportedCurrency(currency: string): boolean {
+  return findMinorUnitDigits(currency) !== undefined;
+}
+
+/** Digits of the currency's minor unit: 2 for PLN, EUR and HUF, 0 for JPY, 3 for KWD. */
+export function getMinorUnitDigits(currency: string): number {
+  const digits = findMinorUnitDigits(currency);
+  // A config with this code is refused when it loads, so reaching here is a bug.
+  if (digits === undefined) throw new Error(`getMinorUnitDigits: billing does not know the currency "${currency}"`);
+  return digits;
+}
+
+/**
+ * The price in the locale's notation, e.g. "PLN 29.00" in en. A stored price in a code billing no
+ * longer accepts is shown with `Intl`'s own digits, so a history page never breaks on it.
+ */
+export function formatPrice(price: PlanPrice, locale: Locale): string {
+  const digits = findMinorUnitDigits(price.currency);
+  const format = getFormatter(locale, price.currency, digits);
+  return format.format(price.amount / 10 ** (digits ?? format.resolvedOptions().maximumFractionDigits ?? 2));
+}

package/src/refund.ts

@@ -0,0 +1,135 @@
+// Refunds, pure: what one payment of a plan added to an account (stored with the payment) and the
+// change a refund of it makes. A full refund takes back the part of the payment's period not used
+// yet. Access ahead of now is one unbroken run (every grant starts where running access ends), so
+// taking back those days moves the dated end back by as many local days; a period already used up
+// takes nothing back, and a lapse between payments never lets an old refund eat a new period.
+// A partial refund takes back the same share of those days as the share of the money not refunded
+// before that it returns, rounded down: the refund that completes the amount has a share of one, so
+// partial refunds that add up to the whole payment take back what one full refund would. A refund
+// that fails later gives back the failed money's share of the days refunds took.
+import { getDayNumber, getStartOfDay } from "./calendar.js";
+import type { EntitlementEvent, EntitlementRecord, PaymentGrant } from "./contract.js";
+
+/** The later of two instants. */
+function getLater(first: Date, second: Date): Date {
+  return first > second ? first : second;
+}
+
+/** Where a grant added to `record` at `now` starts: the latest of the trial's end, dated paid access and `now`. */
+export function getGrantStart(record: EntitlementRecord, now: Date): Date {
+  return [record.trialEndsAt, ...(record.paidUntil === null ? [] : [record.paidUntil])].reduce(getLater, now);
+}
+
+/**
+ * What a plan's event added to `record`: the period from where access ended (the trial, dated paid
+ * access or `now`, as `getPlanGrant` starts it) to the event's end, or lifetime access. Null for an
+ * event that is not a plan grant.
+ */
+export function getPaymentGrant(record: EntitlementRecord, event: EntitlementEvent, now: Date): PaymentGrant | null {
+  switch (event.type) {
+    case "grant_lifetime":
+      return { kind: "lifetime" };
+    case "grant": {
+      const from = getGrantStart(record, now);
+      return from < event.until ? { kind: "period", from, until: event.until } : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * `instant` moved back by `days` local days in `timezone`, at the same local time of day (the first
+ * instant of the day when that time does not exist there).
+ */
+export function moveBackByDays(instant: Date, days: number, timezone: string): Date {
+  const day = getDayNumber(instant, timezone);
+  const timeOfDay = instant.getTime() - getStartOfDay(day, timezone).getTime();
+  return new Date(getStartOfDay(day - days, timezone).getTime() + timeOfDay);
+}
+
+/**
+ * The local days of a period not used yet at `now`, `[max(from, now), until)`, today included; 0
+ * once the period has ended. A refund moves dated access, and every period stacked after this one,
+ * back by this many days.
+ */
+export function getUnusedDays(grant: Extract<PaymentGrant, { kind: "period" }>, now: Date, timezone: string): number {
+  if (grant.until <= now) return 0;
+  return Math.max(0, getDayNumber(grant.until, timezone) - getDayNumber(getLater(grant.from, now), timezone));
+}
+
+/** The part of a payment a refund returns: `refunded` newly refunded out of the `outstanding` amount not refunded before. */
+export interface RefundShare {
+  readonly refunded: number;
+  readonly outstanding: number;
+}
+
+export interface RefundTiming {
+  readonly now: Date;
+  readonly timezone: string;
+  /** The part of the payment refunded; omitted for a full refund. */
+  readonly share?: RefundShare;
+}
+
+/** Whether `share` returns everything not refunded before (or is absent: a full refund). */
+export function isFullShare(share: RefundShare | undefined): boolean {
+  return share === undefined || share.refunded >= share.outstanding;
+}
+
+/**
+ * The local days a refund takes back from a period: all its unused days (`getUnusedDays`) for a
+ * full share, else that share of them rounded down, so the account keeps any part of a day.
+ */
+export function getTakenBackDays(grant: Extract<PaymentGrant, { kind: "period" }>, timing: RefundTiming): number {
+  const unusedDays = getUnusedDays(grant, timing.now, timing.timezone);
+  const { share } = timing;
+  if (share === undefined || isFullShare(share)) return unusedDays;
+  if (share.refunded <= 0) return 0;
+  // Integers: at most 10^8 minor units times a period's days stays a safe integer.
+  return Math.floor((unusedDays * share.refunded) / share.outstanding);
+}
+
+/**
+ * The change a refund of a payment that granted `grant` makes to `record`: a period moves dated
+ * paid access back by the days it takes back (`getTakenBackDays`), and a full refund of a lifetime
+ * ends lifetime access. Null when nothing is taken back (the period is used up, the share rounds to
+ * no day, a partial refund of a lifetime, or dated access is already gone).
+ */
+export function getRefundEvent(record: EntitlementRecord, grant: PaymentGrant, timing: RefundTiming): EntitlementEvent | null {
+  if (grant.kind === "lifetime") return isFullShare(timing.share) ? { type: "end_lifetime" } : null;
+  const days = getTakenBackDays(grant, timing);
+  if (record.paidUntil === null || days === 0) return null;
+  return { type: "shorten", until: moveBackByDays(record.paidUntil, days, timing.timezone) };
+}
+
+/** `instant` moved forward by `days` local days in `timezone`, as `moveBackByDays` moves it back. */
+export function moveForwardByDays(instant: Date, days: number, timezone: string): Date {
+  return moveBackByDays(instant, -days, timezone);
+}
+
+export interface RestoredDaysInput {
+  /** The local days refunds took from the payment's period so far. */
+  readonly takenBackDays: number;
+  /** The payment's refunded total before the failure. */
+  readonly refundedAmount: number;
+  /** The part of that total the failure gives back (at most `refundedAmount`). */
+  readonly restoredAmount: number;
+  /** The app's `partialRefunds` policy. */
+  readonly policy: "pro_rata" | "keep_access";
+}
+
+/**
+ * The local days a failed refund gives back. Under `pro_rata` the share of the days refunds took
+ * that the failed money is of the money refunded, rounded down, and every day once nothing stays
+ * refunded, so failures that undo every refund give back exactly what was taken. Under
+ * `keep_access` only the refund that completed the payment took days, so any failure gives them
+ * all back: the payment is no longer refunded in full.
+ */
+export function getRestoredDays({ takenBackDays, refundedAmount, restoredAmount, policy }: RestoredDaysInput): number {
+  if (takenBackDays <= 0 || restoredAmount <= 0 || refundedAmount <= 0) return 0;
+  const remaining = refundedAmount - restoredAmount;
+  if (remaining <= 0) return takenBackDays;
+  if (policy === "keep_access") return takenBackDays;
+  // Integers: at most 10^8 minor units times a period's days stays a safe integer.
+  return Math.floor((takenBackDays * restoredAmount) / refundedAmount);
+}

package/src/reminder.ts

@@ -0,0 +1,52 @@
+// Which reminder mail an account is due, as a pure rule: the four states the in-app notice shows
+// (trial or paid access ending, trial or paid access ended), decided from the account's record by
+// the state machine. An ended mail is due only for a few days after the end, so turning reminders
+// on never mails every account that lapsed long ago.
+import { getDayNumber } from "./calendar.js";
+import type { EntitlementRecord } from "./contract.js";
+import { resolveEntitlement, type EntitlementPolicy } from "./entitlement.js";
+
+export const ACCESS_REMINDER_KINDS = ["trial-ending", "paid-ending", "trial-ended", "paid-ended"] as const;
+export type AccessReminderKind = (typeof ACCESS_REMINDER_KINDS)[number];
+
+/** The longest catch-up window for ended mails, in days. */
+export const MAX_CATCH_UP_DAYS = 365;
+/** Days after the day access ended during which its ended mail is still due. */
+export const DEFAULT_CATCH_UP_DAYS = 3;
+
+export interface AccessReminder {
+  readonly kind: AccessReminderKind;
+  /** The first instant without the access the mail is about. */
+  readonly endsAt: Date;
+}
+
+export interface AccessReminderInput {
+  readonly record: EntitlementRecord;
+  /** `auth.users.created_at`: a trial that ended by then was never a trial. */
+  readonly accountCreatedAt: Date;
+  readonly now: Date;
+  readonly policy: EntitlementPolicy;
+  /** An ended mail is due from the day access ended through this many local days after it. */
+  readonly catchUpDays: number;
+}
+
+/** The reminder `input.record` is due at `input.now`, or null (lifetime, outside every window). */
+export function getAccessReminder(input: AccessReminderInput): AccessReminder | null {
+  const { record, accountCreatedAt, now, policy, catchUpDays } = input;
+  const entitlement = resolveEntitlement(record, now, policy);
+  if (entitlement.status !== "read_only") {
+    if (!entitlement.isEnding || entitlement.endsAt === null) return null;
+    return { kind: entitlement.status === "trial" ? "trial-ending" : "paid-ending", endsAt: entitlement.endsAt };
+  }
+  if (getDayNumber(now, policy.timezone) - getDayNumber(entitlement.since, policy.timezone) > catchUpDays) return null;
+  if (entitlement.reason === "paid_ended") return { kind: "paid-ended", endsAt: entitlement.since };
+  return entitlement.since > accountCreatedAt ? { kind: "trial-ended", endsAt: entitlement.since } : null;
+}
+
+/**
+ * The delivery scope of a reminder in `mailing.deliveries`: one mail per account, kind and end, so
+ * a new end (an extended trial, a renewal, a refund) is a new window and the same end never mails twice.
+ */
+export function getAccessReminderScope(kind: AccessReminderKind, userId: string, endsAt: Date): string {
+  return `billing.${kind}:${userId}:${String(endsAt.getTime())}`;
+}

package/src/schema.ts

@@ -0,0 +1,86 @@
+// Drizzle view of the module's tables (migrations/0001_create_entitlements.sql,
+// 0002_create_payments.sql, 0003_record_payment_grants.sql, 0004_create_requests_and_grants.sql,
+// 0005_record_refunded_amounts.sql, 0006_record_request_handover_and_prices.sql,
+// 0007_record_failed_refunds.sql, 0008_record_request_handover_claims.sql and
+// 0009_record_pending_charge_states.sql).
+// The migrations are the source of truth; this file only types the queries.
+import { bigint, boolean, integer, pgSchema, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const billingSchema = pgSchema("billing");
+
+export const entitlements = billingSchema.table("entitlements", {
+  userId: uuid("user_id").primaryKey(),
+  trialEndsAt: timestamp("trial_ends_at", { withTimezone: true }).notNull(),
+  paidUntil: timestamp("paid_until", { withTimezone: true }),
+  isLifetime: boolean("is_lifetime").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
+});
+
+export const payments = billingSchema.table("payments", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull(),
+  provider: text("provider").notNull(),
+  checkoutId: text("checkout_id").notNull(),
+  paymentId: text("payment_id"),
+  planId: text("plan_id").notNull(),
+  amount: bigint("amount", { mode: "number" }).notNull(),
+  currency: text("currency").notNull(),
+  status: text("status", { enum: ["paid", "refunded"] }).notNull(),
+  paidAt: timestamp("paid_at", { withTimezone: true }).notNull(),
+  refundedAt: timestamp("refunded_at", { withTimezone: true }),
+  grantKind: text("grant_kind", { enum: ["period", "lifetime"] }),
+  grantedFrom: timestamp("granted_from", { withTimezone: true }),
+  grantedUntil: timestamp("granted_until", { withTimezone: true }),
+  refundedAmount: bigint("refunded_amount", { mode: "number" }).notNull().default(0),
+  takenBackDays: integer("taken_back_days").notNull().default(0),
+  refundsSeenAt: timestamp("refunds_seen_at", { withTimezone: true }),
+  pendingRefundedAmount: bigint("pending_refunded_amount", { mode: "number" }),
+  pendingRefundsSeenAt: timestamp("pending_refunds_seen_at", { withTimezone: true }),
+});
+
+export const refundFailures = billingSchema.table(
+  "refund_failures",
+  {
+    paymentId: uuid("payment_id").notNull(),
+    refundId: text("refund_id").notNull(),
+    amount: bigint("amount", { mode: "number" }).notNull(),
+    refundCreatedAt: timestamp("refund_created_at", { withTimezone: true }).notNull(),
+    failedAt: timestamp("failed_at", { withTimezone: true }).notNull(),
+    recordedAt: timestamp("recorded_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.paymentId, table.refundId] })],
+);
+
+export const paymentRequests = billingSchema.table("payment_requests", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull(),
+  planId: text("plan_id").notNull(),
+  invoiceName: text("invoice_name"),
+  invoiceTaxId: text("invoice_tax_id"),
+  invoiceAddress: text("invoice_address"),
+  status: text("status", { enum: ["open", "granted", "dismissed", "expired"] }).notNull(),
+  requestedAt: timestamp("requested_at", { withTimezone: true }).notNull(),
+  closedAt: timestamp("closed_at", { withTimezone: true }),
+  handedOverAt: timestamp("handed_over_at", { withTimezone: true }),
+  handoverClaimedAt: timestamp("handover_claimed_at", { withTimezone: true }),
+  amount: bigint("amount", { mode: "number" }),
+  currency: text("currency"),
+});
+
+export const manualGrants = billingSchema.table("manual_grants", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull(),
+  planId: text("plan_id").notNull(),
+  requestId: uuid("request_id"),
+  grantedBy: uuid("granted_by"),
+  grantedAt: timestamp("granted_at", { withTimezone: true }).notNull(),
+  grantKind: text("grant_kind", { enum: ["period", "lifetime"] }).notNull(),
+  grantedFrom: timestamp("granted_from", { withTimezone: true }),
+  grantedUntil: timestamp("granted_until", { withTimezone: true }),
+  status: text("status", { enum: ["active", "revoked"] }).notNull(),
+  revokedAt: timestamp("revoked_at", { withTimezone: true }),
+  revokedBy: uuid("revoked_by"),
+  amount: bigint("amount", { mode: "number" }),
+  currency: text("currency"),
+});

package/src/scripts/entitlement-scripts.ts

@@ -0,0 +1,188 @@
+// The operator's tools for turning billing on for accounts that already exist: safe ops scripts
+// (`@softure-ai/ops/scripts`), dry run by default, `--commit` writes. `import-entitlements` records
+// what another system knew (trial ends, paid periods, lifetime access) from a JSON file through
+// `importEntitlement`; `pin-trials` writes every derived trial into a row before a config change
+// would move it (`pinDerivedTrials`). Reports and refusals carry counts and row numbers, never an
+// email.
+import { readFile } from "node:fs/promises";
+import { users } from "@softure-ai/auth";
+import { ok, systemClock, type Clock, type SoftureConfig } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { defineOpsScript, refuseOpsScript, type OpsScript } from "@softure-ai/ops/scripts";
+import { count, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+import { entitlements } from "../schema.js";
+import { getEntitlement, importEntitlement, pinDerivedTrials, type BillingContext } from "../server/entitlements.js";
+import { findAccountByEmail } from "../server/plans.js";
+
+export interface ImportEntitlementsScriptArgs {
+  readonly file: string;
+}
+
+export type PinTrialsScriptArgs = Record<string, never>;
+
+export interface EntitlementScriptOptions {
+  /** The time stored as the rows' `created_at` / `updated_at`; the system clock by default. */
+  readonly clock?: Clock;
+}
+
+/** The most rows one import file holds; split a larger one. */
+export const MAX_IMPORT_ROWS = 50_000;
+/** The most problems a refusal lists. */
+const MAX_LISTED = 10;
+
+const importArgs = z.strictObject({
+  file: z.string().min(1, "--file=<path to a JSON file> is required"),
+});
+
+const pinArgs = z.strictObject({});
+
+const instant = z.iso
+  .datetime({ offset: true, message: "must be an ISO 8601 date-time with an offset, e.g. 2026-11-01T00:00:00+01:00" })
+  .transform((text) => new Date(text));
+
+const importRow = z
+  .strictObject({
+    email: z.string().trim().min(1, "is required").max(320),
+    trialEndsAt: instant.nullable().optional(),
+    paidUntil: instant.nullable().optional(),
+    isLifetime: z.boolean().optional(),
+  })
+  .refine((row) => (row.trialEndsAt ?? row.paidUntil ?? row.isLifetime) != null, "needs trialEndsAt, paidUntil or isLifetime");
+
+const importFile = z.array(importRow).min(1, "holds no rows").max(MAX_IMPORT_ROWS, `holds more than ${String(MAX_IMPORT_ROWS)} rows; split it`);
+
+type ImportRow = z.output<typeof importRow>;
+
+/** Where the imported accounts stand: how many are in each state. */
+interface ImportSummary {
+  readonly accounts: number;
+  readonly trial: number;
+  readonly paid: number;
+  readonly lifetime: number;
+  readonly readOnly: number;
+}
+
+/** "rows 3, 7 and 12" style, at most `MAX_LISTED` of them. */
+function describeRows(rows: readonly number[]): string {
+  const listed = rows.slice(0, MAX_LISTED).map(String);
+  const more = rows.length > MAX_LISTED ? ` and ${String(rows.length - MAX_LISTED)} more` : "";
+  return `${rows.length === 1 ? "row" : "rows"} ${listed.join(", ")}${more}`;
+}
+
+/** The file's rows, or why they cannot be imported. Row numbers count from 1. */
+async function readImportFile(path: string): Promise<{ readonly ok: true; readonly rows: readonly ImportRow[] } | { readonly ok: false; readonly reason: string }> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error ? String(error.code) : "unknown error";
+    return { ok: false, reason: `cannot read the file "${path}" (${code})` };
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: `the file "${path}" is not valid JSON` };
+  }
+  const parsed = importFile.safeParse(json);
+  if (!parsed.success) {
+    const problems = parsed.error.issues.slice(0, MAX_LISTED).map((issue) => {
+      const [index, ...field] = issue.path;
+      if (typeof index !== "number") return `the file ${issue.message}`;
+      return `row ${String(index + 1)}${field.length > 0 ? ` ${field.join(".")}` : ""}: ${issue.message}`;
+    });
+    return { ok: false, reason: `the file must be a JSON array of { email, trialEndsAt?, paidUntil?, isLifetime? }: ${problems.join("; ")}` };
+  }
+  return { ok: true, rows: parsed.data };
+}
+
+/** Row numbers of emails seen earlier in the file (compared as auth stores emails). */
+function findRepeatedRows(rows: readonly ImportRow[]): number[] {
+  const seen = new Set<string>();
+  const repeated: number[] = [];
+  rows.forEach((row, index) => {
+    const key = row.email.toLowerCase();
+    if (seen.has(key)) repeated.push(index + 1);
+    seen.add(key);
+  });
+  return repeated;
+}
+
+async function summarize(ctx: BillingContext, userIds: readonly string[]): Promise<ImportSummary> {
+  const summary = { accounts: userIds.length, trial: 0, paid: 0, lifetime: 0, readOnly: 0 };
+  for (const userId of userIds) {
+    const entitlement = await getEntitlement(ctx, userId);
+    // The accounts were found under the script's transaction; one erased meanwhile counts as none.
+    if (entitlement === null) continue;
+    if (entitlement.status === "read_only") summary.readOnly += 1;
+    else if (entitlement.status === "trial") summary.trial += 1;
+    else if (entitlement.endsAt === null) summary.lifetime += 1;
+    else summary.paid += 1;
+  }
+  return summary;
+}
+
+/** `import-entitlements --file=…`: records trial ends, paid periods and lifetime access from a JSON file. */
+export function createImportEntitlementsScript(config: SoftureConfig, options: EntitlementScriptOptions = {}): OpsScript<ImportEntitlementsScriptArgs> {
+  const clock = options.clock ?? systemClock;
+  return defineOpsScript({
+    name: "import-entitlements",
+    description: "Records the trial ends, paid periods and lifetime access in a JSON file for the accounts it names by email; never shortens access.",
+    usage: ["--file=<path to a JSON array of { email, trialEndsAt?, paidUntil?, isLifetime? }>"],
+    args: importArgs,
+    run: async (tx, args) => {
+      const ctx: BillingContext = { db: tx, clock, config };
+      const file = await readImportFile(args.file);
+      if (!file.ok) return refuseOpsScript(file.reason);
+      const repeated = findRepeatedRows(file.rows);
+      if (repeated.length > 0) return refuseOpsScript(`${describeRows(repeated)} repeat an email named earlier in the file`);
+
+      const userIds: string[] = [];
+      const unknown: number[] = [];
+      for (const [index, row] of file.rows.entries()) {
+        const account = await findAccountByEmail(ctx, row.email);
+        if (account === null) unknown.push(index + 1);
+        else userIds.push(account.id);
+      }
+      if (unknown.length > 0) return refuseOpsScript(`${describeRows(unknown)} name no account; nothing was imported`);
+
+      const before = await summarize(ctx, userIds);
+      for (const [index, row] of file.rows.entries()) {
+        const userId = userIds[index];
+        // One id per row: every row found an account above.
+        if (userId === undefined) throw new Error(`import-entitlements: row ${String(index + 1)} lost its account`);
+        const imported = await importEntitlement(ctx, { userId, trialEndsAt: row.trialEndsAt, paidUntil: row.paidUntil, isLifetime: row.isLifetime });
+        // Erased between the lookup and the change's lock.
+        if (!imported.ok) return refuseOpsScript(`${describeRows([index + 1])} names an account that was deleted meanwhile; nothing was imported`);
+      }
+      return ok({ before, after: await summarize(ctx, userIds) });
+    },
+  });
+}
+
+async function countAccountsWithoutRow(db: Queryable): Promise<number> {
+  const [row] = await db
+    .select({ total: count() })
+    .from(users)
+    .leftJoin(entitlements, eq(entitlements.userId, users.id))
+    .where(isNull(entitlements.userId));
+  return row?.total ?? 0;
+}
+
+/** `pin-trials`: writes every derived trial into a row, so a config change moves none of them. */
+export function createPinTrialsScript(config: SoftureConfig, options: EntitlementScriptOptions = {}): OpsScript<PinTrialsScriptArgs> {
+  const clock = options.clock ?? systemClock;
+  return defineOpsScript({
+    name: "pin-trials",
+    description: "Writes the trial every account without an entitlement row is on into a row, before trial.days, trial.startsAt or the time zone changes.",
+    usage: [],
+    args: pinArgs,
+    run: async (tx) => {
+      const ctx: BillingContext = { db: tx, clock, config };
+      const before = { accountsWithoutRow: await countAccountsWithoutRow(tx) };
+      const pinned = await pinDerivedTrials(ctx);
+      return ok({ before, after: { accountsWithoutRow: await countAccountsWithoutRow(tx), pinned } });
+    },
+  });
+}

package/src/scripts/index.ts

@@ -0,0 +1,11 @@
+// `@softure-ai/billing/scripts`: ops scripts that grant a plan, revoke a manual grant, import
+// entitlements and pin derived trials (see the README, "Scripts" and "Existing accounts").
+export {
+  createImportEntitlementsScript,
+  createPinTrialsScript,
+  MAX_IMPORT_ROWS,
+  type EntitlementScriptOptions,
+  type ImportEntitlementsScriptArgs,
+  type PinTrialsScriptArgs,
+} from "./entitlement-scripts.js";
+export { createGrantPlanScript, createRevokeGrantScript, type GrantPlanScriptArgs, type PlanScriptOptions, type RevokeGrantScriptArgs } from "./plan-scripts.js";

package/src/scripts/plan-scripts.ts

@@ -0,0 +1,143 @@
+// The operator's way to grant a plan and revoke a manual grant without the admin page: safe ops
+// scripts (`@softure-ai/ops/scripts`), dry run by default, `--commit` writes. They write through
+// `grantPlanManually` and `revokeManualGrant`, so a script's grant is in the account's history like
+// the admin page's, and either side can revoke the other's. Reports carry the user id, the
+// entitlement and the active manual grants (with the ids `revoke-grant` takes), never the email.
+import { ok, systemClock, type Clock, type SoftureConfig } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { defineOpsScript, refuseOpsScript, type OpsScript } from "@softure-ai/ops/scripts";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+import type { Entitlement, PaymentGrant } from "../contract.js";
+import { findPlan } from "../plans.js";
+import { manualGrants } from "../schema.js";
+import { getEntitlement, type BillingContext } from "../server/entitlements.js";
+import { getAccountHistory, grantPlanManually, revokeManualGrant } from "../server/grants.js";
+import { findAccountByEmail, getBillingPlans } from "../server/plans.js";
+import { isUuid } from "../server/user-id.js";
+
+export interface GrantPlanScriptArgs {
+  readonly email: string;
+  readonly plan: string;
+}
+
+export interface RevokeGrantScriptArgs {
+  readonly email: string;
+  readonly grant: string;
+}
+
+export interface PlanScriptOptions {
+  /** The time stored as `granted_at` / `revoked_at`; the system clock by default. */
+  readonly clock?: Clock;
+}
+
+const EMAIL = z.string().min(1, "--email=<account email> is required");
+
+const grantPlanArgs = z.strictObject({
+  email: EMAIL,
+  plan: z.string().min(1, "--plan=<plan id> is required"),
+});
+
+const revokeGrantArgs = z.strictObject({
+  email: EMAIL,
+  grant: z.string().min(1, "--grant=<manual grant id> is required"),
+});
+
+const NO_ACCOUNT = "no account has this email";
+
+/** An active manual grant as the report lists it. */
+interface ActiveGrant {
+  readonly id: string;
+  readonly planId: string;
+  readonly grantedAt: Date;
+  readonly grant: PaymentGrant;
+}
+
+interface AccountState {
+  readonly userId: string;
+  readonly access: Entitlement | null;
+  /** Newest first, as the admin page's history lists them. */
+  readonly grants: readonly ActiveGrant[];
+}
+
+async function describeAccount(ctx: BillingContext, userId: string): Promise<AccountState> {
+  const history = await getAccountHistory(ctx, userId);
+  const grants = history.flatMap((entry) =>
+    entry.source === "manual" && entry.status === "active" ? [{ id: entry.id, planId: entry.planId, grantedAt: entry.at, grant: entry.grant }] : [],
+  );
+  return { userId, access: await getEntitlement(ctx, userId), grants };
+}
+
+function describeDeclared(config: SoftureConfig): string {
+  return getBillingPlans(config)
+    .map((plan) => plan.id)
+    .join(", ");
+}
+
+/** Whether `grantId` is an active manual grant of the account (its own select: the history is capped). */
+async function hasActiveGrant(db: Queryable, userId: string, grantId: string): Promise<boolean> {
+  if (!isUuid(grantId)) return false;
+  const [row] = await db
+    .select({ id: manualGrants.id })
+    .from(manualGrants)
+    .where(and(eq(manualGrants.id, grantId), eq(manualGrants.userId, userId), eq(manualGrants.status, "active")));
+  return row !== undefined;
+}
+
+/** `grant-plan --email=… --plan=…`: grants one payment of a declared plan by hand and records it. */
+export function createGrantPlanScript(config: SoftureConfig, options: PlanScriptOptions = {}): OpsScript<GrantPlanScriptArgs> {
+  const clock = options.clock ?? systemClock;
+  return defineOpsScript({
+    name: "grant-plan",
+    description: "Grants one payment of a plan to the account with the given email, recorded in its billing history.",
+    usage: ["--email=<account email>", "--plan=<plan id from billing({ plans })>"],
+    args: grantPlanArgs,
+    run: async (tx, args) => {
+      const ctx: BillingContext = { db: tx, clock, config };
+      if (findPlan(getBillingPlans(config), args.plan) === undefined) {
+        return refuseOpsScript(`plan "${args.plan}" is not declared (declared: ${describeDeclared(config)})`);
+      }
+      const account = await findAccountByEmail(ctx, args.email);
+      if (account === null) return refuseOpsScript(NO_ACCOUNT);
+      const before = await describeAccount(ctx, account.id);
+      const granted = await grantPlanManually(ctx, { userId: account.id, planId: args.plan, adminId: null });
+      if (!granted.ok) {
+        switch (granted.error) {
+          case "billing.lifetime_active":
+            return refuseOpsScript("the account has lifetime access already");
+          case "billing.account_unknown":
+            // Deleted between the lookup and the grant's lock.
+            return refuseOpsScript(NO_ACCOUNT);
+          case "billing.plan_unknown":
+          case "billing.request_closed":
+            // The plan was checked above and no request is given.
+            throw new Error(`grant-plan: granting plan "${args.plan}" failed with ${granted.error}`);
+        }
+      }
+      return ok({ before, after: await describeAccount(ctx, account.id) });
+    },
+  });
+}
+
+/** `revoke-grant --email=… --grant=…`: revokes one active manual grant and takes back what it added. */
+export function createRevokeGrantScript(config: SoftureConfig, options: PlanScriptOptions = {}): OpsScript<RevokeGrantScriptArgs> {
+  const clock = options.clock ?? systemClock;
+  return defineOpsScript({
+    name: "revoke-grant",
+    description: "Revokes a manual plan grant of the account with the given email and takes back what it added.",
+    usage: ["--email=<account email>", "--grant=<manual grant id, listed by a dry run of either script>"],
+    args: revokeGrantArgs,
+    run: async (tx, args) => {
+      const ctx: BillingContext = { db: tx, clock, config };
+      const account = await findAccountByEmail(ctx, args.email);
+      if (account === null) return refuseOpsScript(NO_ACCOUNT);
+      const before = await describeAccount(ctx, account.id);
+      const noGrant = `the account has no active manual grant "${args.grant}"`;
+      if (!(await hasActiveGrant(tx, account.id, args.grant))) return refuseOpsScript(noGrant);
+      const revoked = await revokeManualGrant(ctx, { grantId: args.grant, adminId: null });
+      // Revoked by the admin page between the check and the revoke's lock.
+      if (!revoked.ok) return refuseOpsScript(noGrant);
+      return ok({ before, after: await describeAccount(ctx, account.id) });
+    },
+  });
+}