@softure-ai/billing 0.1.7 → 0.1.8

package/src/next/actions.ts

@@ -11,14 +11,16 @@ import { errorLogLabel, formatMessage, safeError, type CoreErrorCode, type Err,
 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 { getStartOfDay, parseDay } from "../calendar.js";
+import type { AdminActionErrorCode, AdminActionState, GrantFormState, PaymentFormState, TrialFormState } from "../contract.js";
+import { ACCOUNT_PARAM, EMAIL_FIELD, GRANT_FIELD, INVOICE_FIELDS, PLAN_FIELD, REQUEST_FIELD, TRIAL_LAST_DAY_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 { extendTrialManually } from "../server/trials.js";
 import { formatLastDay } from "../ui/format.js";
 import { getBillingContext } from "./context.js";
 
@@ -107,6 +109,37 @@ export async function grantPlanAction(_previous: GrantFormState, formData: FormD
   return { status: "error", error, ...echo };
 }
 
+/**
+ * Extends the trial of the account with the form's email through the form's last day (the trial
+ * ends at the start of the next day in the app's time zone) and records it in the account's history.
+ * Only for the role of `billing({ adminRole })`, checked from the session before the form is read.
+ * Never writes paid access.
+ */
+export async function extendTrialAction(_previous: TrialFormState, formData: FormData): Promise<TrialFormState> {
+  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 lastDay = readText(formData, TRIAL_LAST_DAY_FIELD).trim();
+  const echo = { email, lastDay };
+
+  const day = parseDay(lastDay);
+  if (day === null) return { status: "error", error: "billing.day_invalid", ...echo };
+  const until = getStartOfDay(day + 1, config.timezone);
+  try {
+    const ctx = await getBillingContext(config);
+    const account = await findAccountByEmail(ctx, email);
+    if (account === null) return { status: "error", error: "billing.account_unknown", ...echo };
+    const result = await extendTrialManually(ctx, { userId: account.id, until, adminId: admin.value.id });
+    if (!result.ok) return { status: "error", error: result.error, ...echo };
+    refreshAdminPage(config);
+    const notice = formatMessage(getBillingMessages(config).admin.trial.extended, { email: account.email, date: formatLastDay(until, config.locale, config.timezone) });
+    return { status: "extended", notice };
+  } catch (error) {
+    return { status: "error", error: reportFailure("extending a trial", error), ...echo };
+  }
+}
+
 interface AdminChange {
   readonly operation: string;
   /** The form field that names the row. */

package/src/next/index.ts

@@ -3,7 +3,15 @@
 // 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 {
+  dismissRequestAction,
+  extendTrialAction,
+  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";

package/src/next/pages.tsx

@@ -23,8 +23,9 @@ import { AccountLookup, GrantHistory, type GrantHistoryRow } from "../ui/grant-h
 import { PaymentForm } from "../ui/payment-form.js";
 import { PaymentRequestList, type PaymentRequestRow } from "../ui/payment-requests.js";
 import { PricingTiles } from "../ui/pricing-tiles.js";
+import { TrialForm } from "../ui/trial-form.js";
 import { CurrentAccessBadge } from "./access.js";
-import { dismissRequestAction, findAccountAction, grantPlanAction, grantRequestAction, revokeGrantAction, startPaymentAction } from "./actions.js";
+import { dismissRequestAction, extendTrialAction, findAccountAction, grantPlanAction, grantRequestAction, revokeGrantAction, startPaymentAction } from "./actions.js";
 import { getBillingContext } from "./context.js";
 import { getCurrentEntitlement } from "./current-entitlement.js";
 import { getPlanPaymentHref } from "./pricing.js";
@@ -33,10 +34,16 @@ type SearchParams = Promise<Record<string, string | string[] | undefined>>;
 
 export interface PaymentPageProps {
   readonly searchParams?: SearchParams;
+  /**
+   * The page's `<h1>`, first in `<main>`: `payment.heading` of the messages by default, this text
+   * instead, or none with `null` (for an app whose frame renders the page heading).
+   */
+  readonly heading?: string | null;
 }
 
 const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:flex sft:w-full sft:flex-col sft:gap-4 sft:sm:max-w-md sft:px-4 sft:py-4";
 const STACK_CLASS = "sft:flex sft:flex-col sft:gap-4";
+const HEADING_CLASS = "sft:m-0 sft:font-heading sft:text-2xl sft:font-bold sft:text-foreground";
 const LEAD_CLASS = "sft:m-0 sft:font-sans sft:text-sm sft:text-muted";
 const NOTICE_CLASS =
   "sft:m-0 sft:rounded-control sft:border sft:border-border-strong sft:bg-surface-raised sft:px-4 sft:py-2.5 sft:font-sans sft:text-sm sft:text-foreground";
@@ -57,7 +64,7 @@ function isCheckoutResult(value: string | undefined): value is CheckoutResult {
  * A hosted checkout comes back with `?checkout=success` or `?checkout=cancelled`, shown as a notice
  * (the access itself changes when the provider's webhook confirms the payment).
  */
-export async function PaymentPage({ searchParams }: PaymentPageProps) {
+export async function PaymentPage({ searchParams, heading }: PaymentPageProps) {
   const config = getSoftureConfig();
   const route = getBillingRoutes(config).payment;
   const planId = await readParam(searchParams, PLAN_FIELD);
@@ -75,6 +82,7 @@ export async function PaymentPage({ searchParams }: PaymentPageProps) {
   const hasLifetime = entitlement?.status === "paid" && entitlement.endsAt === null;
   return (
     <main className={LAYOUT_CLASS}>
+      <PageHeading text={heading === undefined ? copy.heading : heading} />
       <Card title={copy.title} subtitle={copy.lead}>
         <div className={STACK_CLASS}>
           {checkoutNotice === null ? null : (
@@ -128,6 +136,11 @@ export async function PaymentPage({ searchParams }: PaymentPageProps) {
   );
 }
 
+/** The page's `<h1>`, or nothing for `null`. */
+function PageHeading({ text }: { readonly text: string | null }) {
+  return text === null ? null : <h1 className={HEADING_CLASS}>{text}</h1>;
+}
+
 /** The plan's name in the app's locale, or its id when the config no longer has it. */
 function getPlanName(plans: readonly Plan[], planId: string, locale: Locale): string {
   const plan = findPlan(plans, planId);
@@ -138,6 +151,8 @@ interface RowContext {
   readonly config: SoftureConfig;
   readonly messages: BillingMessages;
   readonly plans: readonly Plan[];
+  /** The page's instant, to tell a trial extension still running from an ended one. */
+  readonly now: Date;
 }
 
 function getHistoryHref(config: SoftureConfig, userId: string): string {
@@ -175,8 +190,19 @@ function describeGrant(grant: PaymentGrant | null, { config, messages }: RowCont
 function toHistoryRow(entry: AccountHistoryEntry, context: RowContext): GrantHistoryRow {
   const { config, messages, plans } = context;
   const copy = messages.admin.history;
-  const plan = getPlanName(plans, entry.planId, config.locale);
   const formatDate = (date: Date) => formatDay(date, config.locale, config.timezone);
+  if (entry.source === "trial") {
+    const formatEnd = (end: Date) => formatLastDay(end, config.locale, config.timezone);
+    return {
+      id: entry.id,
+      title: copy.trialExtended,
+      statusText: formatMessage(copy.trialUntil, { date: formatEnd(entry.endsAt) }),
+      isCurrent: entry.endsAt > context.now,
+      details: [formatMessage(copy.extendedOn, { date: formatDate(entry.at) }), formatMessage(copy.trialWasUntil, { date: formatEnd(entry.previousEndsAt) })],
+      revokeLabel: null,
+    };
+  }
+  const plan = getPlanName(plans, entry.planId, config.locale);
   if (entry.source === "manual") {
     const isActive = entry.status === "active";
     return {
@@ -213,21 +239,26 @@ function toHistoryRow(entry: AccountHistoryEntry, context: RowContext): GrantHis
 
 export interface BillingAdminPageProps {
   readonly searchParams?: SearchParams;
+  /**
+   * The page's `<h1>`, first in `<main>`: `admin.heading` of the messages by default, this text
+   * instead, or none with `null` (for an app whose frame renders the page heading).
+   */
+  readonly heading?: string | null;
 }
 
 /**
  * The admin page of manual payments: the open invoice requests (grant or dismiss each), the grant
- * form, and an account's history (`?account=<id>`, reached by the email lookup or a request's
+ * form, the trial form (a free, longer trial), and an account's history (`?account=<id>`, reached by the email lookup or a request's
  * link) with its access and a revoke button on each active manual grant. Anyone without the role
  * of `billing({ adminRole })`, signed in or not, gets Next's "not found".
  */
-export async function BillingAdminPage({ searchParams }: BillingAdminPageProps) {
+export async function BillingAdminPage({ searchParams, heading }: BillingAdminPageProps) {
   const config = getSoftureConfig();
   await requireRole(getBillingOptions(config).adminRole);
   const messages = getBillingMessages(config);
   const plans = getBillingPlans(config);
-  const context: RowContext = { config, messages, plans };
   const ctx = await getBillingContext(config);
+  const context: RowContext = { config, messages, plans, now: ctx.clock.now() };
   const requests = (await listOpenRequests(ctx)).map((request) => toRequestRow(request, context));
   const accountId = await readParam(searchParams, ACCOUNT_PARAM);
   const account = accountId === undefined ? null : await findAccountById(ctx, accountId);
@@ -236,6 +267,7 @@ export async function BillingAdminPage({ searchParams }: BillingAdminPageProps)
   const planOptions = plans.map((plan) => ({ value: plan.id, label: getLocalizedText(plan.name, config.locale) }));
   return (
     <main className={LAYOUT_CLASS}>
+      <PageHeading text={heading === undefined ? messages.admin.heading : heading} />
       <Card title={messages.admin.requests.title} subtitle={messages.admin.requests.lead}>
         <PaymentRequestList requests={requests} grantAction={grantRequestAction} dismissAction={dismissRequestAction} messages={messages} />
       </Card>
@@ -246,6 +278,9 @@ export async function BillingAdminPage({ searchParams }: BillingAdminPageProps)
           <GrantForm action={grantPlanAction} plans={planOptions} messages={messages} locale={config.locale} />
         )}
       </Card>
+      <Card title={messages.admin.trial.title} subtitle={messages.admin.trial.lead}>
+        <TrialForm action={extendTrialAction} messages={messages} locale={config.locale} />
+      </Card>
       <Card title={messages.admin.history.title} subtitle={messages.admin.history.lead}>
         <div className={STACK_CLASS}>
           <AccountLookup action={findAccountAction} messages={messages} locale={config.locale} />

package/src/schema.ts

@@ -1,8 +1,8 @@
 // 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).
+// 0007_record_failed_refunds.sql, 0008_record_request_handover_claims.sql,
+// 0009_record_pending_charge_states.sql and 0010_record_trial_extensions_and_index_foreign_keys.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";
 
@@ -84,3 +84,12 @@ export const manualGrants = billingSchema.table("manual_grants", {
   amount: bigint("amount", { mode: "number" }),
   currency: text("currency"),
 });
+
+export const trialExtensions = billingSchema.table("trial_extensions", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull(),
+  extendedBy: uuid("extended_by"),
+  extendedAt: timestamp("extended_at", { withTimezone: true }).notNull(),
+  previousEndsAt: timestamp("previous_ends_at", { withTimezone: true }).notNull(),
+  endsAt: timestamp("ends_at", { withTimezone: true }).notNull(),
+});

package/src/scripts/entitlement-scripts.ts

@@ -1,7 +1,8 @@
 // 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
+// `importEntitlement`, merged (never shorter) or, with `--exact`, as given for accounts billing has
+// no row of yet; `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";
@@ -17,6 +18,8 @@ import { findAccountByEmail } from "../server/plans.js";
 
 export interface ImportEntitlementsScriptArgs {
   readonly file: string;
+  /** Store each row as given (`importEntitlement`'s `replace` mode) instead of merging it. */
+  readonly exact?: true;
 }
 
 export type PinTrialsScriptArgs = Record<string, never>;
@@ -33,6 +36,7 @@ const MAX_LISTED = 10;
 
 const importArgs = z.strictObject({
   file: z.string().min(1, "--file=<path to a JSON file> is required"),
+  exact: z.literal(true, "--exact takes no value").optional(),
 });
 
 const pinArgs = z.strictObject({});
@@ -128,8 +132,9 @@ export function createImportEntitlementsScript(config: SoftureConfig, options: E
   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? }>"],
+    description:
+      "Records the trial ends, paid periods and lifetime access in a JSON file for the accounts it names by email; never shortens access, except with --exact, which stores each row as given for accounts billing has no row of yet.",
+    usage: ["--file=<path to a JSON array of { email, trialEndsAt?, paidUntil?, isLifetime? }>", "--exact (store each row as given; refused for an account that already has a different row)"],
     args: importArgs,
     run: async (tx, args) => {
       const ctx: BillingContext = { db: tx, clock, config };
@@ -148,13 +153,21 @@ export function createImportEntitlementsScript(config: SoftureConfig, options: E
       if (unknown.length > 0) return refuseOpsScript(`${describeRows(unknown)} name no account; nothing was imported`);
 
       const before = await summarize(ctx, userIds);
+      const mode = args.exact === true ? "replace" : "merge";
+      const existing: number[] = [];
       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 });
+        const imported = await importEntitlement(ctx, { userId, trialEndsAt: row.trialEndsAt, paidUntil: row.paidUntil, isLifetime: row.isLifetime, mode });
+        if (imported.ok) continue;
+        if (imported.error === "billing.entitlement_exists") existing.push(index + 1);
         // 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`);
+        else return refuseOpsScript(`${describeRows([index + 1])} names an account that was deleted meanwhile; nothing was imported`);
+      }
+      // The refusal rolls the whole transaction back: the rows imported before it are undone too.
+      if (existing.length > 0) {
+        return refuseOpsScript(`${describeRows(existing)} name accounts that already have a different entitlement row (--exact imports only accounts billing has no row of yet); nothing was imported`);
       }
       return ok({ before, after: await summarize(ctx, userIds) });
     },

package/src/server/entitlements.ts

@@ -165,21 +165,52 @@ export async function changeEntitlement(
 
 export interface ImportEntitlementInput {
   readonly userId: string;
-  /** The trial end the other system knew; omitted or null keeps the account's own. */
+  /** The trial end the other system knew; omitted or null keeps the account's own (its derived trial in `replace`). */
   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;
+  /**
+   * `merge` (the default) moves each end only later than the account's record. `replace` stores
+   * exactly what the other system knew, a trial shorter than the derived one included, and only for
+   * an account billing has no row of yet (an adoption).
+   */
+  readonly mode?: "merge" | "replace";
+}
+
+export type ImportEntitlementError = "billing.account_unknown" | "billing.entitlement_exists";
+
+/** The record a `replace` import stores: the input, with the derived trial when it names none. */
+function getReplacedRecord(derived: EntitlementRecord, input: ImportEntitlementInput): EntitlementRecord {
+  return { trialEndsAt: input.trialEndsAt ?? derived.trialEndsAt, paidUntil: input.paidUntil ?? null, isLifetime: input.isLifetime ?? false };
+}
+
+function isSameRecord(first: EntitlementRecord, second: EntitlementRecord): boolean {
+  return (
+    first.trialEndsAt.getTime() === second.trialEndsAt.getTime() &&
+    (first.paidUntil?.getTime() ?? null) === (second.paidUntil?.getTime() ?? null) &&
+    first.isLifetime === second.isLifetime
+  );
 }
 
 /**
- * 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.
+ * Records what another system knew about an account (a trial end, a paid period, lifetime access).
+ *
+ * `merge` (the default) goes 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.
+ *
+ * `replace` writes the record as given into the account's first row, so a migration is faithful: a
+ * trial the other system ended early stays ended. An account that already has a row is refused with
+ * `billing.entitlement_exists` and nothing is written, unless the row holds exactly that record (a
+ * repeat, which changes nothing).
+ *
+ * Neither is 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">> {
+export async function importEntitlement(ctx: BillingContext, input: ImportEntitlementInput & { readonly mode?: "merge" }): Promise<Ok<Entitlement> | Err<"billing.account_unknown">>;
+export async function importEntitlement(ctx: BillingContext, input: ImportEntitlementInput): Promise<Ok<Entitlement> | Err<ImportEntitlementError>>;
+export async function importEntitlement(ctx: BillingContext, input: ImportEntitlementInput): Promise<Ok<Entitlement> | Err<ImportEntitlementError>> {
+  if (input.mode === "replace") return replaceEntitlement(ctx, input);
   const changed = await changeEntitlement(ctx, input.userId, {
     type: "import",
     trialEndsAt: input.trialEndsAt ?? null,
@@ -192,6 +223,29 @@ export async function importEntitlement(ctx: BillingContext, input: ImportEntitl
   throw new Error(`@softure-ai/billing: importing an entitlement failed with ${changed.error}`);
 }
 
+/** The `replace` import: the account's first row, as given. */
+async function replaceEntitlement(ctx: BillingContext, input: ImportEntitlementInput): Promise<Ok<Entitlement> | Err<ImportEntitlementError>> {
+  if (!isUserId(input.userId)) return err("billing.account_unknown");
+  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 import, as in `changeEntitlement`.
+    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");
+    const record = getReplacedRecord(getDefaultRecord(ctx, account.createdAt), input);
+    const inserted = await tx
+      .insert(entitlements)
+      .values({ userId: input.userId, ...record, createdAt: now, updatedAt: now })
+      .onConflictDoNothing({ target: entitlements.userId })
+      .returning();
+    if (inserted.length > 0) return ok(resolveEntitlement(record, now, policy));
+    // The row existed, or a concurrent change inserted it (the insert waited for it).
+    const stored = await lockStoredRecord(tx, input.userId);
+    if (stored !== undefined && isSameRecord(stored, record)) return ok(resolveEntitlement(stored, now, policy));
+    return err("billing.entitlement_exists");
+  });
+}
+
 /** How many accounts `pinDerivedTrials` reads and writes at a time. */
 const PIN_BATCH_SIZE = 500;
 

package/src/server/grants.ts

@@ -9,7 +9,7 @@ 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 { entitlements, manualGrants, paymentRequests, payments, trialExtensions } from "../schema.js";
 import { findEntitlementRecord, pinEntitlementRow, type BillingContext } from "./entitlements.js";
 import { getGrantColumns, readGrant } from "./payments.js";
 import { applyPlan, getBillingPlans } from "./plans.js";
@@ -152,7 +152,10 @@ export async function revokeManualGrant(ctx: BillingContext, input: RevokeManual
   });
 }
 
-/** One line of an account's history: a grant typed in by an admin, or a payment a provider reported. */
+/**
+ * One line of an account's history: a grant typed in by an admin, a payment a provider reported, or
+ * a trial an admin extended.
+ */
 export type AccountHistoryEntry =
   | {
       readonly source: "manual";
@@ -181,12 +184,21 @@ export type AccountHistoryEntry =
       readonly refundedAt: Date | null;
       /** The total refunded so far: part of `amount` while the payment is still paid. */
       readonly refundedAmount: number;
+    }
+  | {
+      readonly source: "trial";
+      readonly id: string;
+      /** When it was extended. */
+      readonly at: Date;
+      /** The trial end before and after the extension (first instants no longer covered). */
+      readonly previousEndsAt: Date;
+      readonly endsAt: Date;
     };
 
 /** 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. */
+/** The account's manual grants, provider payments and trial extensions, 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
@@ -201,6 +213,12 @@ export async function getAccountHistory(ctx: Pick<BillingContext, "db">, userId:
     .where(eq(payments.userId, userId))
     .orderBy(desc(payments.paidAt), desc(payments.id))
     .limit(ACCOUNT_HISTORY_LIMIT);
+  const extensionRows = await ctx.db
+    .select()
+    .from(trialExtensions)
+    .where(eq(trialExtensions.userId, userId))
+    .orderBy(desc(trialExtensions.extendedAt), desc(trialExtensions.id))
+    .limit(ACCOUNT_HISTORY_LIMIT);
   const entries: AccountHistoryEntry[] = [];
   for (const row of grantRows) {
     const grant = readGrant(row);
@@ -223,5 +241,8 @@ export async function getAccountHistory(ctx: Pick<BillingContext, "db">, userId:
       refundedAmount: row.refundedAmount,
     });
   }
+  for (const row of extensionRows) {
+    entries.push({ source: "trial", id: row.id, at: row.extendedAt, previousEndsAt: row.previousEndsAt, endsAt: row.endsAt });
+  }
   return entries.sort((first, second) => second.at.getTime() - first.at.getTime());
 }

package/src/server/health.ts

@@ -1,5 +1,5 @@
 // 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,
+// payments, payment requests, manual grants and trial extensions 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";
@@ -14,5 +14,6 @@ export const checkBillingTables: HealthCheck = async (context) => {
   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`);
+  await db.execute(sql`select 1 from billing.trial_extensions limit 0`);
   return ok();
 };

package/src/server/index.ts

@@ -10,6 +10,7 @@ export {
   pinDerivedTrials,
   type BillingContext,
   type EntitlementEventResolver,
+  type ImportEntitlementError,
   type ImportEntitlementInput,
 } from "./entitlements.js";
 export {
@@ -26,6 +27,7 @@ export {
   type RevokeManualGrantInput,
 } from "./grants.js";
 export { checkBillingTables } from "./health.js";
+export { extendTrialManually, type ExtendTrialManuallyInput, type TrialExtensionResult } from "./trials.js";
 export { findAccessReminders, type AccessReminderDue, type FindAccessRemindersOptions } from "./reminders.js";
 export {
   failRefund,
@@ -68,6 +70,7 @@ export {
   type BillingPaymentData,
   type BillingPaymentRequestData,
   type BillingRefundFailureData,
+  type BillingTrialExtensionData,
   type BillingUserData,
 } from "./privacy.js";
 export {

package/src/server/privacy.ts

@@ -1,14 +1,14 @@
 // 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
+// to it by hand, and the trials extended for 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.
+// provider keeps its own records of the payments. Which admin granted or revoked a plan, or
+// extended a trial, 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 { entitlements, manualGrants, paymentRequests, payments, refundFailures, trialExtensions } from "../schema.js";
 import { isUserId } from "./user-id.js";
 
 /** One provider payment, as it appears in an export. */
@@ -69,6 +69,14 @@ export interface BillingManualGrantData {
   readonly currency: string | null;
 }
 
+/** One trial extended by hand, as it appears in an export. */
+export interface BillingTrialExtensionData {
+  readonly extendedAt: Date;
+  /** The trial end before and after the extension (first instants no longer covered). */
+  readonly previousEndsAt: Date;
+  readonly endsAt: Date;
+}
+
 /** What billing holds about one user, as it appears in their export. */
 export interface BillingUserData {
   readonly entitlement: {
@@ -86,9 +94,11 @@ export interface BillingUserData {
   readonly paymentRequests: readonly BillingPaymentRequestData[];
   /** Oldest first. */
   readonly manualGrants: readonly BillingManualGrantData[];
+  /** Oldest first. */
+  readonly trialExtensions: readonly BillingTrialExtensionData[];
 }
 
-const EMPTY_USER_DATA: BillingUserData = { entitlement: null, payments: [], refundFailures: [], paymentRequests: [], manualGrants: [] };
+const EMPTY_USER_DATA: BillingUserData = { entitlement: null, payments: [], refundFailures: [], paymentRequests: [], manualGrants: [], trialExtensions: [] };
 
 export async function exportBillingUserData(context: ModuleContext, userId: string): Promise<Ok<BillingUserData>> {
   if (!isUserId(userId)) return ok(EMPTY_USER_DATA);
@@ -165,7 +175,19 @@ export async function exportBillingUserData(context: ModuleContext, userId: stri
     .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 });
+  const extensionRows = await db
+    .select({ extendedAt: trialExtensions.extendedAt, previousEndsAt: trialExtensions.previousEndsAt, endsAt: trialExtensions.endsAt })
+    .from(trialExtensions)
+    .where(eq(trialExtensions.userId, userId))
+    .orderBy(asc(trialExtensions.extendedAt), asc(trialExtensions.id));
+  return ok({
+    entitlement: row ?? null,
+    payments: paymentRows,
+    refundFailures: failureRows,
+    paymentRequests: requestRows,
+    manualGrants: grantRows,
+    trialExtensions: extensionRows,
+  });
 }
 
 export async function deleteBillingUserData(context: ModuleContext, userId: string): Promise<Ok<undefined>> {
@@ -180,6 +202,7 @@ export async function deleteBillingUserData(context: ModuleContext, userId: stri
   // 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));
+  await db.delete(trialExtensions).where(eq(trialExtensions.userId, userId));
   return ok();
 }
 

package/src/server/trials.ts

@@ -0,0 +1,70 @@
+// Trials an admin extends by hand (the admin page's "Extend a trial" form): the trial end moves
+// later and the change is recorded in `billing.trial_extensions` with the end before and after, so
+// the account's history lists it beside the manual grants. Unlike a granted plan it never writes
+// `paid_until`, so an app that counts paying accounts by it does not count a free extension. Locks
+// follow every change's order (account, then the entitlement row, then the new row).
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { eq } from "drizzle-orm";
+import type { Entitlement, TrialExtensionErrorCode } from "../contract.js";
+import { applyEntitlementEvent, resolveEntitlement } from "../entitlement.js";
+import { entitlements, trialExtensions } from "../schema.js";
+import { findEntitlementRecord, pinEntitlementRow, type BillingContext } from "./entitlements.js";
+import { getEntitlementPolicy } from "./options.js";
+import { lockEntitlementRow } from "./take-back.js";
+import { isUserId } from "./user-id.js";
+
+export interface ExtendTrialManuallyInput {
+  readonly userId: string;
+  /** The trial's new end: the first instant it no longer covers. */
+  readonly until: Date;
+  /** The admin who extends it; null for an extension without one (a script). */
+  readonly adminId: string | null;
+}
+
+export interface TrialExtensionResult {
+  readonly extensionId: string;
+  /** Where the account stands after the extension (paid access still wins over the trial). */
+  readonly entitlement: Entitlement;
+}
+
+/**
+ * Moves the account's trial end to `until` and records it, in one transaction. Refuses an end at
+ * or before now (`billing.end_not_in_future`) and one at or before the current trial end
+ * (`billing.trial_not_extended`); every refusal writes nothing. Database errors propagate.
+ */
+export async function extendTrialManually(ctx: BillingContext, input: ExtendTrialManuallyInput): Promise<Ok<TrialExtensionResult> | Err<TrialExtensionErrorCode>> {
+  if (!isUserId(input.userId)) return err("billing.account_unknown");
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    // A shared lock: the account cannot be deleted before the extension 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 derived trial pinned and locked before the check, so a concurrent change is seen here.
+    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);
+    // The account was locked above and its row pinned.
+    if (record === null) throw new Error("@softure-ai/billing: an account vanished while its trial was being extended");
+
+    const refusal = input.until <= now ? "billing.end_not_in_future" : input.until <= record.trialEndsAt ? "billing.trial_not_extended" : null;
+    if (refusal !== null) {
+      // The pin is this transaction's own row, nobody else has seen it: undo it, so the refusal writes nothing.
+      if (isPinned) await tx.delete(entitlements).where(eq(entitlements.userId, input.userId));
+      return err(refusal);
+    }
+    const next = applyEntitlementEvent(record, { type: "extend_trial", until: input.until }, now);
+    // Both of the event's refusals were checked above.
+    if (!next.ok) throw new Error(`@softure-ai/billing: extending a trial failed with ${next.error}`);
+    await tx
+      .update(entitlements)
+      .set({ trialEndsAt: next.value.trialEndsAt, updatedAt: now })
+      .where(eq(entitlements.userId, input.userId));
+    const [row] = await tx
+      .insert(trialExtensions)
+      .values({ userId: input.userId, extendedBy: input.adminId, extendedAt: now, previousEndsAt: record.trialEndsAt, endsAt: next.value.trialEndsAt })
+      .returning();
+    if (row === undefined) throw new Error("@softure-ai/billing: recording a trial extension returned no row");
+    return ok({ extensionId: row.id, entitlement: resolveEntitlement(next.value, now, getEntitlementPolicy(ctx.config)) });
+  });
+}

package/src/ui/index.ts

@@ -23,3 +23,4 @@ export {
   type PaymentRequestRow,
 } from "./payment-requests.js";
 export { PricingTiles, type PricingTilesProps, type PricingTilesSlot } from "./pricing-tiles.js";
+export { TrialForm, type TrialFormAction, type TrialFormProps, type TrialFormSlot } from "./trial-form.js";