@softure-ai/billing 0.1.6 → 0.1.8

package/src/messages/en.ts

@@ -46,6 +46,7 @@ export const en = {
     empty: "No plans are available yet.",
   },
   payment: {
+    heading: "Payment",
     title: "Choose a plan",
     lead: "Pick the plan that suits you. Paid access starts when your current access ends.",
     plansLabel: "Plans",
@@ -67,6 +68,7 @@ export const en = {
     lifetime: "You have lifetime access: there is nothing left to pay for.",
   },
   admin: {
+    heading: "Billing",
     title: "Grant access",
     lead: "Grant a plan to an account once its payment has arrived. A paid period starts when the account's current access ends.",
     email: "Account email",
@@ -76,6 +78,15 @@ export const en = {
     granted: "{email} now has {plan}.",
     grantedUntil: "{email} now has {plan}, with access until {date}.",
     noPlans: "There are no plans to grant: add them to billing({ plans }).",
+    trial: {
+      title: "Extend a trial",
+      lead: "Give an account a longer trial for free, e.g. an invited user. It is not paid access: the account keeps its paid periods, and the trial lasts through the day you choose.",
+      email: "Email of the account to extend",
+      lastDay: "Last day of the trial",
+      submit: "Extend trial",
+      pending: "Extending…",
+      extended: "{email} now has a trial until {date}.",
+    },
     requests: {
       title: "Invoice requests",
       lead: "Requests sent from the payment page. Grant the plan once the invoice is paid, or dismiss the request.",
@@ -119,6 +130,10 @@ export const en = {
       revoke: "Revoke",
       revoking: "Revoking…",
       revokeLabel: "Revoke {plan} granted on {date}",
+      trialExtended: "Trial extended",
+      trialUntil: "Trial until {date}",
+      extendedOn: "Extended on {date}",
+      trialWasUntil: "The trial was until {date}",
     },
   },
   errors: {
@@ -135,6 +150,8 @@ export const en = {
       lifetime_active: "This account already has lifetime access: there is nothing to pay for or grant.",
       request_closed: "This request was granted or dismissed already.",
       grant_revoked: "This grant was revoked already.",
+      trial_not_extended: "The trial already lasts through this day or longer.",
+      day_invalid: "Enter a date, e.g. 2026-11-30.",
     },
     security: {
       rate_limited: "Too many attempts. Try again later.",

package/src/messages/index.ts

@@ -1,4 +1,4 @@
-import type { AdminActionErrorCode, BillingFormErrorCode, GrantFormErrorCode, PaymentFormErrorCode } from "../contract.js";
+import type { AdminActionErrorCode, BillingFormErrorCode, GrantFormErrorCode, PaymentFormErrorCode, TrialFormErrorCode } from "../contract.js";
 import { en } from "./en.js";
 import { pl } from "./pl.js";
 
@@ -8,7 +8,7 @@ export type BillingMessages = typeof en;
 export const billingMessages = { en, pl };
 
 /** The copy for an error code; an unknown code gets the generic failure. */
-export function getBillingErrorMessage(messages: BillingMessages, code: BillingFormErrorCode | PaymentFormErrorCode | GrantFormErrorCode | AdminActionErrorCode): string {
+export function getBillingErrorMessage(messages: BillingMessages, code: BillingFormErrorCode | PaymentFormErrorCode | GrantFormErrorCode | TrialFormErrorCode | AdminActionErrorCode): string {
   const separator = code.lastIndexOf(".");
   const namespace = code.slice(0, separator);
   const name = code.slice(separator + 1);

package/src/messages/pl.ts

@@ -48,6 +48,7 @@ export const pl: typeof en = {
     empty: "Nie ma jeszcze dostępnych planów.",
   },
   payment: {
+    heading: "Płatność",
     title: "Wybierz plan",
     lead: "Wybierz plan dla siebie. Płatny dostęp zaczyna się, gdy skończy się obecny.",
     plansLabel: "Plany",
@@ -69,6 +70,7 @@ export const pl: typeof en = {
     lifetime: "Masz dostęp dożywotni: nie ma już za co płacić.",
   },
   admin: {
+    heading: "Rozliczenia",
     title: "Nadaj dostęp",
     lead: "Nadaj plan kontu, gdy wpłynie płatność. Płatny okres zaczyna się, gdy skończy się obecny dostęp konta.",
     email: "E-mail konta",
@@ -78,6 +80,15 @@ export const pl: typeof en = {
     granted: "{email} ma teraz {plan}.",
     grantedUntil: "{email} ma teraz {plan}, z dostępem do {date}.",
     noPlans: "Nie ma planów do nadania: dodaj je w billing({ plans }).",
+    trial: {
+      title: "Przedłuż okres próbny",
+      lead: "Daj kontu dłuższy okres próbny za darmo, np. zaproszonej osobie. To nie jest płatny dostęp: konto zachowuje opłacone okresy, a okres próbny trwa do końca wybranego dnia.",
+      email: "E-mail konta do przedłużenia",
+      lastDay: "Ostatni dzień okresu próbnego",
+      submit: "Przedłuż okres próbny",
+      pending: "Przedłużanie…",
+      extended: "{email} ma teraz okres próbny do {date}.",
+    },
     requests: {
       title: "Prośby o fakturę",
       lead: "Prośby wysłane ze strony płatności. Nadaj plan, gdy faktura zostanie opłacona, albo odrzuć prośbę.",
@@ -121,6 +132,10 @@ export const pl: typeof en = {
       revoke: "Cofnij",
       revoking: "Cofanie…",
       revokeLabel: "Cofnij {plan} nadany {date}",
+      trialExtended: "Przedłużony okres próbny",
+      trialUntil: "Okres próbny do {date}",
+      extendedOn: "Przedłużono {date}",
+      trialWasUntil: "Wcześniej okres próbny do {date}",
     },
   },
   errors: {
@@ -137,6 +152,8 @@ export const pl: typeof en = {
       lifetime_active: "To konto ma już dostęp dożywotni: nie ma za co płacić ani czego nadawać.",
       request_closed: "Ta prośba została już obsłużona lub odrzucona.",
       grant_revoked: "Ten dostęp został już cofnięty.",
+      trial_not_extended: "Okres próbny trwa już do tego dnia albo dłużej.",
+      day_invalid: "Wpisz datę, np. 2026-11-30.",
     },
     security: {
       rate_limited: "Zbyt wiele prób. Spróbuj później.",

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 {