@softure-ai/billing 0.1.6 → 0.1.8

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";

package/src/ui/trial-form.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import type { Locale } from "@softure-ai/core";
+import { Button, type ClassNames, createSlotClassGetter, FormError, TextField } from "@softure-ai/ui";
+import { useActionState } from "react";
+import { INITIAL_TRIAL_FORM_STATE, type TrialFormState } from "../contract.js";
+import { EMAIL_FIELD, TRIAL_LAST_DAY_FIELD } from "../fields.js";
+import { getBillingErrorMessage, type BillingMessages } from "../messages/index.js";
+
+// The admin form that extends an account's trial for free: the account's email and the trial's
+// new last day. It submits straight to its server action, which checks the admin role first; after
+// an extension it says until when the trial lasts and stays ready for the next.
+
+export type TrialFormAction = (previous: TrialFormState, formData: FormData) => Promise<TrialFormState>;
+
+export type TrialFormSlot = "root" | "form" | "notice";
+
+export interface TrialFormProps {
+  readonly action: TrialFormAction;
+  readonly messages: BillingMessages;
+  /** Locale of the built-in copy of the ui primitives. */
+  readonly locale?: Locale;
+  readonly classNames?: ClassNames<TrialFormSlot>;
+  readonly unstyled?: boolean;
+}
+
+const DEFAULT_CLASSES: Readonly<Record<TrialFormSlot, string>> = {
+  root: "sft:flex sft:flex-col sft:gap-3 sft:font-sans",
+  form: "sft:flex sft:flex-col sft:gap-3",
+  notice: "sft:m-0 sft:text-sm sft:text-success",
+};
+
+export function TrialForm({ action, messages, locale, classNames, unstyled }: TrialFormProps) {
+  const [state, formAction, isPending] = useActionState(action, INITIAL_TRIAL_FORM_STATE);
+  const slot = createSlotClassGetter({ defaults: DEFAULT_CLASSES, classNames, unstyled });
+  const copy = messages.admin.trial;
+  const error = state.error === undefined ? undefined : getBillingErrorMessage(messages, state.error);
+  const isEmailError = state.error === "billing.account_unknown";
+  const isDayError = state.error === "billing.day_invalid" || state.error === "billing.end_not_in_future" || state.error === "billing.trial_not_extended";
+  const isError = state.status === "error";
+  // A fresh, empty form after each extension; the typed values after an error.
+  const key = `${state.status}:${state.email ?? ""}:${state.lastDay ?? ""}`;
+  return (
+    <div className={slot("root")}>
+      <form action={formAction} className={slot("form")}>
+        <TextField
+          key={`email:${key}`}
+          name={EMAIL_FIELD}
+          type="email"
+          label={copy.email}
+          required
+          defaultValue={isError ? (state.email ?? "") : ""}
+          error={isEmailError ? error : undefined}
+          locale={locale}
+          unstyled={unstyled}
+        />
+        <TextField
+          key={`day:${key}`}
+          name={TRIAL_LAST_DAY_FIELD}
+          type="date"
+          label={copy.lastDay}
+          required
+          defaultValue={isError ? (state.lastDay ?? "") : ""}
+          error={isDayError ? error : undefined}
+          locale={locale}
+          unstyled={unstyled}
+        />
+        <FormError message={isEmailError || isDayError ? undefined : error} unstyled={unstyled} />
+        <Button type="submit" variant="primary" pending={isPending} unstyled={unstyled}>
+          {isPending ? copy.pending : copy.submit}
+        </Button>
+      </form>
+      {state.status === "extended" ? (
+        <p role="status" className={slot("notice")}>
+          {state.notice}
+        </p>
+      ) : null}
+    </div>
+  );
+}