@beignet/cli 0.0.26 → 0.0.28

package/src/make/payments.ts

@@ -0,0 +1,2182 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  type BeignetConfig,
+  loadBeignetConfig,
+  type ResolvedBeignetConfig,
+  resolveConfig,
+} from "../config.js";
+import { appendToNamedArray, insertAfterImports } from "../registry-edits.js";
+import {
+  addNamedTypeImport,
+  aliasModule,
+  appendDeferredPortKey,
+  appendPickStringLiteralMember,
+  appendSharedErrorEntries,
+  assertStandardApp,
+  type DatabaseName,
+  detectResourceDatabase,
+  detectResourcePersistence,
+  detectUiShell,
+  drizzleDialects,
+  drizzleRepositoriesPath,
+  drizzleSchemaIndexPath,
+  fileExists,
+  type GeneratedFile,
+  infrastructureDir,
+  insertTypeProperty,
+  type MakeResult,
+  paymentsPortWiring,
+  planGeneratedFiles,
+  type ResourceNames,
+  readOptionalFile,
+  relativeModule,
+  resourceNames,
+  resourceSharedErrorsPath,
+  seedEntrypointPath,
+  seedNames,
+  uniqueStrings,
+  updateDatabaseProviderPick,
+  updateDatabaseResetTables,
+  updateDrizzleRepositories,
+  updateDrizzleSchemaIndexExports,
+  updateInfrastructureDeferredPorts,
+  updatePackageJson,
+  updatePackageScripts,
+  updatePortsIndex,
+  updateSeedEntrypoint,
+  updateServerRoutes,
+  updateTransactionPortsPick,
+  wirePortProviders,
+  writePlannedGeneratedFile,
+} from "./shared.js";
+
+export type MakePaymentsOptions = {
+  cwd?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  config?: BeignetConfig;
+};
+
+/**
+ * Result returned by `beignet make payments`.
+ */
+export type MakePaymentsResult = MakeResult;
+
+export async function makePayments(
+  options: MakePaymentsOptions,
+): Promise<MakePaymentsResult> {
+  const targetDir = path.resolve(options.cwd ?? process.cwd());
+  const config = options.config
+    ? resolveConfig(options.config)
+    : await loadBeignetConfig(targetDir);
+
+  await assertStandardApp(targetDir, config);
+
+  const persistence = await detectResourcePersistence(targetDir, config);
+  if (persistence !== "drizzle") {
+    throw new Error(
+      "beignet make payments expects a Drizzle-backed Beignet app because billing state must be durable. Add a database provider first, then run make payments again.",
+    );
+  }
+
+  const database = await detectResourceDatabase(targetDir, config);
+  const ui = await detectUiShell(targetDir, config);
+  const generatedFiles = paymentsFiles(config, database, { ui });
+  const plannedFiles = await planGeneratedFiles(targetDir, generatedFiles, {
+    force: Boolean(options.force),
+  });
+  const billingNames = resourceNames("billing");
+  const billingSeedNames = seedNames("billing/demo-billing-account");
+  const plannedBillingUpdates = await updatePaymentsWiring(
+    targetDir,
+    billingNames,
+    config,
+    { dryRun: true, ui },
+  );
+  const plannedSeedEntrypoint = await updateSeedEntrypoint(
+    targetDir,
+    billingSeedNames,
+    config,
+    { dryRun: true },
+  );
+  const plannedPaymentsUpdates = (
+    await wirePortProviders(
+      targetDir,
+      config,
+      [paymentsPortWiring("make payments")],
+      { dryRun: true },
+    )
+  ).updatedFiles;
+
+  const createdFiles = plannedFiles
+    .filter((file) => file.result === "created")
+    .map((file) => file.path);
+  const updatedFiles = plannedFiles
+    .filter((file) => file.result === "updated")
+    .map((file) => file.path);
+  const skippedFiles = plannedFiles
+    .filter((file) => file.result === "skipped")
+    .map((file) => file.path);
+
+  if (options.dryRun) {
+    if (plannedSeedEntrypoint === "created") {
+      createdFiles.push(seedEntrypointPath(config));
+    }
+    if (plannedSeedEntrypoint === "updated") {
+      updatedFiles.push(seedEntrypointPath(config));
+    }
+    if (plannedSeedEntrypoint === "skipped") {
+      skippedFiles.push(seedEntrypointPath(config));
+    }
+    updatedFiles.push(...plannedBillingUpdates, ...plannedPaymentsUpdates);
+  } else {
+    for (const file of plannedFiles) {
+      await writePlannedGeneratedFile(targetDir, file);
+    }
+
+    const seedEntrypointResult = await updateSeedEntrypoint(
+      targetDir,
+      billingSeedNames,
+      config,
+      { dryRun: false },
+    );
+    if (seedEntrypointResult === "created") {
+      createdFiles.push(seedEntrypointPath(config));
+    }
+    if (seedEntrypointResult === "updated") {
+      updatedFiles.push(seedEntrypointPath(config));
+    }
+    if (seedEntrypointResult === "skipped") {
+      skippedFiles.push(seedEntrypointPath(config));
+    }
+
+    updatedFiles.push(
+      ...(await updatePaymentsWiring(targetDir, billingNames, config, {
+        dryRun: false,
+        ui,
+      })),
+    );
+    updatedFiles.push(
+      ...(
+        await wirePortProviders(
+          targetDir,
+          config,
+          [paymentsPortWiring("make payments")],
+          { dryRun: false },
+        )
+      ).updatedFiles,
+    );
+  }
+
+  return {
+    schemaVersion: 1,
+    name: "payments",
+    targetDir,
+    dryRun: Boolean(options.dryRun),
+    files: [
+      ...generatedFiles.map((file) => file.path),
+      seedEntrypointPath(config),
+    ],
+    createdFiles,
+    updatedFiles: uniqueStrings(updatedFiles),
+    skippedFiles,
+  };
+}
+
+/**
+ * Post-generate guidance for `beignet make payments`, shared with the CLI
+ * command so the printed steps track what was actually emitted.
+ */
+export function makePaymentsNextStepLines(
+  result: Pick<MakePaymentsResult, "files">,
+): string[] {
+  const hasPlanUi = result.files.includes("app/(app)/settings/plan/page.tsx");
+
+  return [
+    "The free plan works out of the box; billing accounts without an active subscription resolve to it automatically.",
+    "Set BILLING_PRO_PRICE_ID in .env.local to the provider price ID for your pro plan.",
+    "Run beignet db generate and beignet db migrate so billing_accounts exists before handling webhooks.",
+    'Gate paid actions once usage passes FREE_PLAN_LIMITS: await requireEntitlement(ctx, { entitlement: "todos.create", subject: { type: "tenant", id: tenantId } });',
+    ...(hasPlanUi
+      ? [
+          "Users manage their plan at /settings/plan; run bun run db:seed to create the demo billing account.",
+        ]
+      : ["Run bun run db:seed to create the demo billing account."]),
+    "Use createMemoryPaymentsProvider() for local development, then swap server/providers.ts to stripePaymentsProvider when STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are configured.",
+    "Billing accounts fall back to the user id today; after beignet make tenancy they become workspace-scoped automatically.",
+    "Run your app's test, lint, and typecheck commands, then beignet lint and beignet doctor.",
+  ];
+}
+
+export async function updatePaymentsWiring(
+  targetDir: string,
+  billingNames: ResourceNames,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean; ui?: boolean },
+): Promise<string[]> {
+  const updated = new Set<string>();
+
+  if (await updatePackageJson(targetDir, { dryRun: options.dryRun })) {
+    updated.add("package.json");
+  }
+  if (
+    await updatePackageScripts(
+      targetDir,
+      { "db:seed": `bun ${seedEntrypointPath(config)}` },
+      { dryRun: options.dryRun },
+    )
+  ) {
+    updated.add("package.json");
+  }
+  if (
+    await updatePortsIndex(targetDir, billingNames, config, {
+      ...options,
+      generationOptions: {
+        auth: false,
+        tenant: false,
+        events: false,
+        softDelete: false,
+      },
+    })
+  ) {
+    updated.add(config.paths.ports);
+  }
+  if (await updatePaymentsEntitlementsPort(targetDir, config, options)) {
+    updated.add(config.paths.ports);
+    updated.add(config.paths.infrastructurePorts);
+  }
+  if (
+    await updateInfrastructureDeferredPorts(
+      targetDir,
+      billingNames,
+      config,
+      options,
+    )
+  ) {
+    updated.add(config.paths.infrastructurePorts);
+  }
+  if (
+    await updateDrizzleSchemaIndexExports(
+      targetDir,
+      config,
+      { exports: ["billingAccounts"], module: "./billing" },
+      options,
+    )
+  ) {
+    updated.add(drizzleSchemaIndexPath(config));
+  }
+  if (
+    await updateDrizzleRepositories(targetDir, billingNames, config, options)
+  ) {
+    updated.add(drizzleRepositoriesPath(config));
+  }
+  if (
+    await updateDatabaseProviderPick(targetDir, config, ["billing"], options)
+  ) {
+    updated.add(path.join(infrastructureDir(config), "db/provider.ts"));
+  }
+  if (await updateDatabaseProviderEntitlements(targetDir, config, options)) {
+    updated.add(path.join(infrastructureDir(config), "db/provider.ts"));
+  }
+  if (
+    await updateTransactionPortsPick(
+      targetDir,
+      config,
+      ["billing"],
+      "make payments",
+      options,
+    )
+  ) {
+    updated.add(
+      path.join(infrastructureDir(config), "db/transaction-ports.ts"),
+    );
+  }
+  if (
+    await updateDatabaseResetTables(
+      targetDir,
+      config,
+      ["billing_accounts"],
+      options,
+    )
+  ) {
+    updated.add(path.join(infrastructureDir(config), "db/reset.ts"));
+  }
+  if (await updateBillingSharedErrors(targetDir, config, options)) {
+    updated.add(resourceSharedErrorsPath(config));
+  }
+  if (await updateBillingEnv(targetDir, options)) {
+    updated.add("lib/env.ts");
+  }
+  if (await updateBillingEnvExample(targetDir, options)) {
+    updated.add(".env.example");
+  }
+  if (options.ui && (await updateBillingSettingsNav(targetDir, options))) {
+    updated.add("components/settings-nav.tsx");
+  }
+
+  const routesFile = await updateServerRoutes(
+    targetDir,
+    billingNames,
+    config,
+    options,
+  );
+  if (routesFile) updated.add(routesFile);
+
+  return [...updated];
+}
+
+export async function updatePaymentsEntitlementsPort(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  let changed = false;
+  const portsFilePath = path.join(targetDir, config.paths.ports);
+  const portsOriginal = await readFile(portsFilePath, "utf8");
+  let portsNext = addNamedTypeImport(
+    portsOriginal,
+    "EntitlementsPort",
+    "@beignet/core/entitlements",
+  );
+  if (!/\bentitlements\s*:/.test(portsNext)) {
+    portsNext = insertTypeProperty(
+      portsNext,
+      "AppPorts",
+      "entitlements: EntitlementsPort;",
+      `Could not find AppPorts in ${config.paths.ports}. Add entitlements: EntitlementsPort; manually, or restore the generated ports file before running make payments.`,
+    );
+  }
+  if (portsNext !== portsOriginal) {
+    changed = true;
+    if (!options.dryRun) await writeFile(portsFilePath, portsNext);
+  }
+
+  const infrastructureFilePath = path.join(
+    targetDir,
+    config.paths.infrastructurePorts,
+  );
+  const infrastructureOriginal = await readFile(infrastructureFilePath, "utf8");
+  const infrastructureNext = appendDeferredPortKey(
+    infrastructureOriginal,
+    "entitlements",
+  );
+  if (
+    infrastructureNext === infrastructureOriginal &&
+    !/["']entitlements["']/.test(infrastructureOriginal)
+  ) {
+    throw new Error(
+      `Could not find the deferred port list in ${config.paths.infrastructurePorts}. Add "entitlements" manually, or restore the generated infrastructure ports file before running make payments.`,
+    );
+  }
+  if (infrastructureNext !== infrastructureOriginal) {
+    changed = true;
+    if (!options.dryRun) {
+      await writeFile(infrastructureFilePath, infrastructureNext);
+    }
+  }
+
+  return changed;
+}
+
+export async function updateDatabaseProviderEntitlements(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = path.join(infrastructureDir(config), "db/provider.ts");
+  const filePath = path.join(targetDir, file);
+  if (!(await fileExists(filePath))) return false;
+
+  const original = await readFile(filePath, "utf8");
+  let next = original;
+  const importLine =
+    'import { createBillingEntitlements } from "@/features/billing/entitlements";';
+  if (!next.includes(importLine)) {
+    next = insertAfterImports(next, importLine);
+  }
+
+  next = appendPickStringLiteralMember(next, "AppPorts", "entitlements");
+
+  if (!/\bconst\s+entitlements\s*=/.test(next)) {
+    const withEntitlementsConst = next.replace(
+      /(\n\s*const repositories = createRepositories\(dbPort\.(?:drizzle|db)\);)/,
+      `$1\n\t\tconst entitlements = createBillingEntitlements(repositories.billing);`,
+    );
+    if (withEntitlementsConst === next) {
+      throw new Error(
+        `Could not find createRepositories(dbPort.drizzle) in ${file}. Add const entitlements = createBillingEntitlements(repositories.billing) manually, or restore the generated database provider before running make payments.`,
+      );
+    }
+    next = withEntitlementsConst;
+  }
+
+  if (!/\bentitlements\s*,/.test(next)) {
+    const withEntitlementsPort = next.replace(
+      /(\n\s*\.\.\.repositories,\n)/,
+      `$1\t\t\tentitlements,\n`,
+    );
+    if (withEntitlementsPort === next) {
+      throw new Error(
+        `Could not find the repository spread in ${file}. Add entitlements to providedPorts manually, or restore the generated database provider before running make payments.`,
+      );
+    }
+    next = withEntitlementsPort;
+  }
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+export async function updateBillingSharedErrors(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  return appendSharedErrorEntries(
+    targetDir,
+    config,
+    [
+      {
+        name: "BillingAccountNotFound",
+        entry: `BillingAccountNotFound: {
+\t\tcode: "BILLING_ACCOUNT_NOT_FOUND",
+\t\tstatus: 404,
+\t\tmessage: "Billing account not found",
+\t},`,
+      },
+      {
+        name: "IdempotencyConflict",
+        entry: `IdempotencyConflict: {
+\t\tcode: "IDEMPOTENCY_CONFLICT",
+\t\tstatus: 409,
+\t\tmessage: "Idempotency key was already used with a different request",
+\t},`,
+      },
+      {
+        name: "IdempotencyInProgress",
+        entry: `IdempotencyInProgress: {
+\t\tcode: "IDEMPOTENCY_IN_PROGRESS",
+\t\tstatus: 409,
+\t\tmessage: "Idempotency key is already being processed",
+\t},`,
+      },
+      {
+        name: "BillingCheckoutUnavailable",
+        entry: `BillingCheckoutUnavailable: {
+\t\tcode: "BILLING_CHECKOUT_UNAVAILABLE",
+\t\tstatus: 502,
+\t\tmessage: "Billing checkout is unavailable",
+\t},`,
+      },
+    ],
+    "make payments",
+    options,
+  );
+}
+
+export async function updateBillingEnv(
+  targetDir: string,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = "lib/env.ts";
+  const filePath = path.join(targetDir, file);
+  const original = await readOptionalFile(filePath);
+  if (original === undefined) {
+    throw new Error(
+      `Could not find ${file}. Add BILLING_PRO_PRICE_ID to your env schema manually, or restore the generated env file before running make payments.`,
+    );
+  }
+  if (/\bBILLING_PRO_PRICE_ID\b/.test(original)) return false;
+
+  const match = /\n([\t ]*)LOG_LEVEL:/.exec(original);
+  if (!match) {
+    throw new Error(
+      `Could not find LOG_LEVEL in ${file}. Add BILLING_PRO_PRICE_ID: z.string().min(1).default("price_pro_example") to the createEnv server block manually, or restore the generated env file before running make payments.`,
+    );
+  }
+
+  const entry = `\n${match[1]}BILLING_PRO_PRICE_ID: z.string().min(1).default("price_pro_example"),`;
+  const next = `${original.slice(0, match.index)}${entry}${original.slice(
+    match.index,
+  )}`;
+
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+export async function updateBillingEnvExample(
+  targetDir: string,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = ".env.example";
+  const filePath = path.join(targetDir, file);
+  const original = await readOptionalFile(filePath);
+  if (original === undefined) return false;
+  if (/^BILLING_PRO_PRICE_ID=/m.test(original)) return false;
+
+  const match = /\nLOG_LEVEL=/.exec(original);
+  const next = match
+    ? `${original.slice(0, match.index)}\nBILLING_PRO_PRICE_ID=price_pro_example${original.slice(
+        match.index,
+      )}`
+    : `${original.trimEnd()}\nBILLING_PRO_PRICE_ID=price_pro_example\n`;
+
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+export async function updateBillingSettingsNav(
+  targetDir: string,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = "components/settings-nav.tsx";
+  const filePath = path.join(targetDir, file);
+  const original = await readOptionalFile(filePath);
+  if (original === undefined) return false;
+  if (original.includes('"/settings/plan"')) return false;
+
+  const appended = appendToNamedArray(
+    original,
+    "settingsLinks",
+    '{ href: "/settings/plan", label: "Plan" }',
+  );
+  if (appended.kind === "missing") {
+    throw new Error(
+      `Could not find const settingsLinks = [ in ${file}. Add { href: "/settings/plan", label: "Plan" } to the settings navigation manually, or restore the generated settings nav before running make payments.`,
+    );
+  }
+  if (appended.kind === "unchanged") return false;
+
+  if (!options.dryRun) await writeFile(filePath, appended.source);
+  return true;
+}
+
+export function paymentsFiles(
+  config: ResolvedBeignetConfig,
+  database: DatabaseName,
+  options: { ui: boolean } = { ui: false },
+): GeneratedFile[] {
+  const uiFiles: GeneratedFile[] = options.ui
+    ? [
+        {
+          path: path.join(config.paths.features, "billing/client/queries.ts"),
+          content: billingClientQueriesFile(),
+        },
+        {
+          path: path.join(
+            config.paths.features,
+            "billing/components/plan-card.tsx",
+          ),
+          content: billingPlanCardFile(),
+        },
+        {
+          path: path.join(
+            config.paths.features,
+            "billing/components/billing-actions.tsx",
+          ),
+          content: billingActionsFile(),
+        },
+        {
+          path: path.join(config.paths.features, "billing/components/index.ts"),
+          content: billingComponentsIndexFile(),
+        },
+        {
+          path: "app/(app)/settings/plan/page.tsx",
+          content: billingPlanPageFile(),
+        },
+      ]
+    : [];
+
+  return [
+    {
+      path: path.join(config.paths.features, "billing/schemas.ts"),
+      content: billingSchemasFile(),
+    },
+    {
+      path: path.join(config.paths.features, "billing/pricing.ts"),
+      content: billingPricingFile(),
+    },
+    {
+      path: path.join(config.paths.features, "billing/entitlements.ts"),
+      content: billingEntitlementsFile(),
+    },
+    {
+      path: path.join(config.paths.features, "billing/ports.ts"),
+      content: billingPortsFile(),
+    },
+    {
+      path: path.join(config.paths.features, "billing/contracts.ts"),
+      content: billingContractsFile(),
+    },
+    {
+      path: path.join(config.paths.features, "billing/use-cases/index.ts"),
+      content: billingUseCasesFile(config),
+    },
+    {
+      path: path.join(config.paths.features, "billing/routes.ts"),
+      content: billingRoutesFile(config),
+    },
+    {
+      path: path.join(config.paths.features, "billing/tests/billing.test.ts"),
+      content: billingTestFile(config),
+    },
+    {
+      path: path.join(
+        infrastructureDir(config),
+        "billing/drizzle-billing-repository.ts",
+      ),
+      content: billingDrizzleRepositoryFile(config, database),
+    },
+    {
+      path: path.join(infrastructureDir(config), "db/schema/billing.ts"),
+      content: billingDrizzleSchemaFile(database),
+    },
+    {
+      path: path.join(config.paths.features, "billing/seeds/index.ts"),
+      content: billingSeedsFile(config),
+    },
+    {
+      path: "app/api/webhooks/payments/route.ts",
+      content: billingWebhookRouteFile(),
+    },
+    ...uiFiles,
+  ];
+}
+
+export function billingSchemasFile(): string {
+  return `import { z } from "zod";
+
+export const billingPlanSchema = z.enum(["free", "pro"]);
+
+export const billingStatusSchema = z.enum([
+\t"inactive",
+\t"trialing",
+\t"active",
+\t"past_due",
+\t"canceled",
+]);
+
+export const createCheckoutSessionInputSchema = z.object({
+\tplan: billingPlanSchema,
+});
+
+export const createCheckoutSessionOutputSchema = z.object({
+\tsessionId: z.string(),
+\turl: z.string().url(),
+});
+
+export const createBillingPortalSessionOutputSchema = z.object({
+\turl: z.string().url(),
+});
+
+export const billingStatusOutputSchema = z.object({
+\ttenantId: z.string(),
+\tplan: billingPlanSchema,
+\tstatus: billingStatusSchema,
+\tactive: z.boolean(),
+\tprovider: z.string().optional(),
+\tcustomerId: z.string().optional(),
+\tsubscriptionId: z.string().optional(),
+\tcurrentPeriodEnd: z.string().optional(),
+\tcancelAtPeriodEnd: z.boolean().optional(),
+\tcheckoutSessionId: z.string().optional(),
+\tlastEventId: z.string().optional(),
+\tupdatedAt: z.string().optional(),
+});
+
+export type BillingPlan = z.infer<typeof billingPlanSchema>;
+export type BillingStatus = z.infer<typeof billingStatusSchema>;
+export type BillingStatusOutput = z.infer<typeof billingStatusOutputSchema>;
+`;
+}
+
+export function billingPricingFile(): string {
+  return `import type {
+\tPaymentCheckoutLineItem,
+\tPaymentCheckoutMode,
+} from "@beignet/core/payments";
+import { env } from "@/lib/env";
+import type { BillingPlan } from "./schemas";
+
+export type BillingEntitlement = "todos.create";
+
+export type BillingPlanDefinition = {
+\tid: BillingPlan;
+\tlabel: string;
+\tmode: PaymentCheckoutMode;
+\tlineItems: readonly PaymentCheckoutLineItem[];
+\tentitlements: readonly BillingEntitlement[];
+};
+
+export const billingPlans = {
+\tfree: {
+\t\tid: "free",
+\t\tlabel: "Free",
+\t\tmode: "subscription",
+\t\tlineItems: [],
+\t\tentitlements: [],
+\t},
+\tpro: {
+\t\tid: "pro",
+\t\tlabel: "Pro",
+\t\tmode: "subscription",
+\t\tlineItems: [{ priceId: env.BILLING_PRO_PRICE_ID, quantity: 1 }],
+\t\tentitlements: ["todos.create"],
+\t},
+} as const satisfies Record<BillingPlan, BillingPlanDefinition>;
+
+/**
+ * Free-plan quotas. Call \`requireEntitlement\` only once usage reaches these
+ * limits, so the free plan stays a fully working tier.
+ */
+export const FREE_PLAN_LIMITS = {
+\ttodos: 100,
+} as const;
+
+export function getBillingPlan(plan: BillingPlan): BillingPlanDefinition {
+\treturn billingPlans[plan];
+}
+
+export function billingPlanIncludesEntitlement(
+\tplan: BillingPlan,
+\tentitlement: string,
+): entitlement is BillingEntitlement {
+\treturn getBillingPlan(plan).entitlements.includes(
+\t\tentitlement as BillingEntitlement,
+\t);
+}
+`;
+}
+
+export function billingEntitlementsFile(): string {
+  return `import {
+\tcreateEntitlements,
+\tdenyEntitlement,
+} from "@beignet/core/entitlements";
+import { isBillingAccountActive, type BillingRepository } from "./ports";
+import { billingPlanIncludesEntitlement } from "./pricing";
+import type { BillingPlan } from "./schemas";
+
+/**
+ * Billing-backed entitlements.
+ *
+ * The free plan is a valid tier: a missing billing account or an inactive
+ * subscription resolves to the free plan rather than denying everything.
+ * Only entitlements outside the resolved plan are denied.
+ */
+export function createBillingEntitlements(billing: BillingRepository) {
+\treturn createEntitlements({
+\t\tasync inspect(input) {
+\t\t\tif (input.subject.type !== "tenant") {
+\t\t\t\treturn denyEntitlement({
+\t\t\t\t\treason: "Billing entitlements require a tenant subject.",
+\t\t\t\t\tcode: "ENTITLEMENT_SUBJECT_UNSUPPORTED",
+\t\t\t\t\tdetails: { subject: input.subject },
+\t\t\t\t});
+\t\t\t}
+
+\t\t\tconst account = await billing.findByTenantId(input.subject.id);
+\t\t\tconst plan: BillingPlan = isBillingAccountActive(account)
+\t\t\t\t? account.plan
+\t\t\t\t: "free";
+
+\t\t\tif (!billingPlanIncludesEntitlement(plan, input.entitlement)) {
+\t\t\t\treturn denyEntitlement({
+\t\t\t\t\treason:
+\t\t\t\t\t\t"The current billing plan does not include this entitlement.",
+\t\t\t\t\tcode: "ENTITLEMENT_NOT_INCLUDED",
+\t\t\t\t\tdetails: {
+\t\t\t\t\t\tentitlement: input.entitlement,
+\t\t\t\t\t\tplan,
+\t\t\t\t\t\tsubject: input.subject,
+\t\t\t\t\t},
+\t\t\t\t});
+\t\t\t}
+
+\t\t\treturn true;
+\t\t},
+\t});
+}
+`;
+}
+
+export function billingPortsFile(): string {
+  return `import type { BillingPlan, BillingStatus } from "./schemas";
+
+export type BillingAccount = {
+\ttenantId: string;
+\tplan: BillingPlan;
+\tstatus: BillingStatus;
+\tprovider: string;
+\tcustomerId?: string;
+\tsubscriptionId?: string;
+\tcurrentPeriodEnd?: string;
+\tcancelAtPeriodEnd?: boolean;
+\tcheckoutSessionId?: string;
+\tlastEventId?: string;
+\tupdatedAt: string;
+};
+
+export type SaveBillingAccountInput = BillingAccount;
+
+export interface BillingRepository {
+\tfindByTenantId(tenantId: string): Promise<BillingAccount | null>;
+\tfindByCustomerId(
+\t\tcustomerId: string,
+\t\tprovider: string,
+\t): Promise<BillingAccount | null>;
+\tsave(input: SaveBillingAccountInput): Promise<BillingAccount>;
+}
+
+export function isBillingAccountActive(
+\taccount: BillingAccount | null,
+): account is BillingAccount & { status: "active" | "trialing" } {
+\treturn account?.status === "active" || account?.status === "trialing";
+}
+`;
+}
+
+export function billingContractsFile(): string {
+  return `import { defineContractGroup } from "@beignet/core/contracts";
+import { z } from "zod";
+import {
+\tbillingStatusOutputSchema,
+\tcreateBillingPortalSessionOutputSchema,
+\tcreateCheckoutSessionInputSchema,
+\tcreateCheckoutSessionOutputSchema,
+} from "@/features/billing/schemas";
+import { errors } from "@/features/shared/errors";
+
+const billing = defineContractGroup()
+\t.namespace("billing")
+\t.prefix("/api/billing");
+const checkoutHeadersSchema = z.object({
+\t"idempotency-key": z.string().min(1),
+});
+const checkoutBilling = billing.headers(checkoutHeadersSchema);
+
+export const getBillingStatus = billing
+\t.get("/")
+\t.query(z.object({}))
+\t.meta({ auth: "required" })
+\t.errors({ Unauthorized: errors.Unauthorized })
+\t.responses({
+\t\t200: billingStatusOutputSchema,
+\t})
+\t.openapi({ summary: "Get billing status", tags: ["billing"] });
+
+export const createCheckoutSession = checkoutBilling
+\t.post("/checkout")
+\t.body(createCheckoutSessionInputSchema)
+\t.meta({
+\t\tauth: "required",
+\t\tidempotency: {
+\t\t\trequired: true,
+\t\t\theader: "idempotency-key",
+\t\t\tscope: "actor-tenant",
+\t\t\tttlSec: 86_400,
+\t\t},
+\t})
+\t.errors({
+\t\tUnauthorized: errors.Unauthorized,
+\t\tIdempotencyConflict: errors.IdempotencyConflict,
+\t\tIdempotencyInProgress: errors.IdempotencyInProgress,
+\t\tBillingCheckoutUnavailable: errors.BillingCheckoutUnavailable,
+\t})
+\t.responses({
+\t\t201: createCheckoutSessionOutputSchema,
+\t})
+\t.openapi({ summary: "Create a checkout session", tags: ["billing"] });
+
+export const createBillingPortalSession = billing
+\t.post("/portal")
+\t.body(z.object({}))
+\t.meta({ auth: "required" })
+\t.errors({
+\t\tUnauthorized: errors.Unauthorized,
+\t\tBillingAccountNotFound: errors.BillingAccountNotFound,
+\t})
+\t.responses({
+\t\t200: createBillingPortalSessionOutputSchema,
+\t})
+\t.openapi({ summary: "Create a billing portal session", tags: ["billing"] });
+
+export const billingContracts = [
+\tgetBillingStatus,
+\tcreateCheckoutSession,
+\tcreateBillingPortalSession,
+];
+`;
+}
+
+export function billingUseCasesFile(config: ResolvedBeignetConfig): string {
+  return `import {
+\tcreateIdempotencyFingerprint,
+\trunIdempotently,
+} from "@beignet/core/idempotency";
+import type { PaymentWebhookEvent } from "@beignet/core/payments";
+import { requireUser } from "@beignet/core/ports";
+import { z } from "zod";
+import type { AppContext } from "${aliasModule(config.paths.appContext)}";
+import { appError } from "@/features/shared/errors";
+import { env } from "@/lib/env";
+import { useCase } from "@/lib/use-case";
+import { getBillingPlan } from "../pricing";
+import type { BillingAccount } from "../ports";
+import { isBillingAccountActive } from "../ports";
+import {
+\ttype BillingPlan,
+\ttype BillingStatus,
+\tbillingStatusOutputSchema,
+\tcreateBillingPortalSessionOutputSchema,
+\tcreateCheckoutSessionInputSchema,
+\tcreateCheckoutSessionOutputSchema,
+} from "../schemas";
+
+type ProviderPayload = Record<string, unknown>;
+
+const paymentWebhookEventSchema = z.custom<PaymentWebhookEvent>(
+\t(value): value is PaymentWebhookEvent =>
+\t\ttypeof value === "object" &&
+\t\tvalue !== null &&
+\t\ttypeof (value as PaymentWebhookEvent).id === "string" &&
+\t\ttypeof (value as PaymentWebhookEvent).type === "string" &&
+\t\ttypeof (value as PaymentWebhookEvent).provider === "string",
+);
+const paymentWebhookOutputSchema = z.object({
+\treceived: z.boolean(),
+\taccountUpdated: z.boolean(),
+});
+
+function nowIso(): string {
+\treturn new Date().toISOString();
+}
+
+function record(value: unknown): ProviderPayload {
+\treturn value && typeof value === "object" && !Array.isArray(value)
+\t\t? (value as ProviderPayload)
+\t\t: {};
+}
+
+function stringValue(value: unknown): string | undefined {
+\treturn typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function providerId(value: unknown): string | undefined {
+\tif (typeof value === "string") return stringValue(value);
+\tconst payload = record(value);
+\treturn stringValue(payload.id);
+}
+
+function metadataValue(data: ProviderPayload, key: string): string | undefined {
+\treturn stringValue(record(data.metadata)[key]);
+}
+
+function tenantIdFromPayload(data: ProviderPayload): string | undefined {
+\treturn (
+\t\tstringValue(data.client_reference_id) ??
+\t\tmetadataValue(data, "tenantId") ??
+\t\tmetadataValue(data, "tenant_id")
+\t);
+}
+
+function planFromPayload(data: ProviderPayload): BillingPlan {
+\t// Checkout and subscription webhooks are always about a paid plan, so an
+\t// event without plan metadata resolves to pro rather than free.
+\tconst plan = metadataValue(data, "plan");
+\treturn plan === "free" ? "free" : "pro";
+}
+
+function statusFromPayload(
+\tdata: ProviderPayload,
+\tfallback: BillingStatus,
+): BillingStatus {
+\tconst status = stringValue(data.status);
+\tswitch (status) {
+\t\tcase "active":
+\t\tcase "trialing":
+\t\tcase "past_due":
+\t\tcase "canceled":
+\t\tcase "inactive":
+\t\t\treturn status;
+\t\tcase "unpaid":
+\t\t\treturn "past_due";
+\t\tcase "incomplete":
+\t\t\treturn "inactive";
+\t\tcase "incomplete_expired":
+\t\t\treturn "canceled";
+\t\tcase "paused":
+\t\t\treturn "inactive";
+\t\tdefault:
+\t\t\treturn fallback;
+\t}
+}
+
+function periodEndFromPayload(data: ProviderPayload): string | undefined {
+\tconst value = data.current_period_end;
+\treturn typeof value === "number"
+\t\t? new Date(value * 1000).toISOString()
+\t\t: stringValue(value);
+}
+
+function cancelAtPeriodEndFromPayload(
+\tdata: ProviderPayload,
+): boolean | undefined {
+\treturn typeof data.cancel_at_period_end === "boolean"
+\t\t? data.cancel_at_period_end
+\t\t: undefined;
+}
+
+function billingTenantId(ctx: AppContext): string {
+\tconst user = requireUser(ctx);
+\treturn ctx.tenant?.id ?? user.id;
+}
+
+function billingStatusOutput(tenantId: string, account: BillingAccount | null) {
+\t// A missing account or an inactive subscription resolves to the free plan;
+\t// the free plan is the default tier, not a locked state.
+\tconst plan: BillingPlan = isBillingAccountActive(account)
+\t\t? account.plan
+\t\t: "free";
+
+\treturn {
+\t\ttenantId,
+\t\tplan,
+\t\tstatus: account?.status ?? "inactive",
+\t\tactive: isBillingAccountActive(account),
+\t\t...(account?.provider ? { provider: account.provider } : {}),
+\t\t...(account?.customerId ? { customerId: account.customerId } : {}),
+\t\t...(account?.subscriptionId
+\t\t\t? { subscriptionId: account.subscriptionId }
+\t\t\t: {}),
+\t\t...(account?.currentPeriodEnd
+\t\t\t? { currentPeriodEnd: account.currentPeriodEnd }
+\t\t\t: {}),
+\t\t...(account?.cancelAtPeriodEnd !== undefined
+\t\t\t? { cancelAtPeriodEnd: account.cancelAtPeriodEnd }
+\t\t\t: {}),
+\t\t...(account?.checkoutSessionId
+\t\t\t? { checkoutSessionId: account.checkoutSessionId }
+\t\t\t: {}),
+\t\t...(account?.lastEventId ? { lastEventId: account.lastEventId } : {}),
+\t\t...(account?.updatedAt ? { updatedAt: account.updatedAt } : {}),
+\t};
+}
+
+async function saveBillingAccount(args: {
+\texisting: BillingAccount | null;
+\ttenantId: string;
+\tprovider: string;
+\tplan?: BillingPlan;
+\tstatus?: BillingStatus;
+\tcustomerId?: string;
+\tsubscriptionId?: string;
+\tcurrentPeriodEnd?: string;
+\tcancelAtPeriodEnd?: boolean;
+\tcheckoutSessionId?: string;
+\tlastEventId?: string;
+\tsave: (account: BillingAccount) => Promise<BillingAccount>;
+}) {
+\treturn args.save({
+\t\ttenantId: args.tenantId,
+\t\tprovider: args.provider,
+\t\tplan: args.plan ?? args.existing?.plan ?? "free",
+\t\tstatus: args.status ?? args.existing?.status ?? "inactive",
+\t\tcustomerId: args.customerId ?? args.existing?.customerId,
+\t\tsubscriptionId: args.subscriptionId ?? args.existing?.subscriptionId,
+\t\tcurrentPeriodEnd:
+\t\t\targs.currentPeriodEnd ?? args.existing?.currentPeriodEnd,
+\t\tcancelAtPeriodEnd:
+\t\t\targs.cancelAtPeriodEnd ?? args.existing?.cancelAtPeriodEnd,
+\t\tcheckoutSessionId:
+\t\t\targs.checkoutSessionId ?? args.existing?.checkoutSessionId,
+\t\tlastEventId: args.lastEventId ?? args.existing?.lastEventId,
+\t\tupdatedAt: nowIso(),
+\t});
+}
+
+async function applyCheckoutCompleted(
+\tevent: PaymentWebhookEvent,
+\tsave: (account: BillingAccount) => Promise<BillingAccount>,
+\tfindByTenantId: (tenantId: string) => Promise<BillingAccount | null>,
+) {
+\tconst data = record(event.data);
+\tconst tenantId = tenantIdFromPayload(data);
+\tif (!tenantId) return null;
+
+\tconst existing = await findByTenantId(tenantId);
+\treturn saveBillingAccount({
+\t\texisting,
+\t\ttenantId,
+\t\tprovider: event.provider,
+\t\tplan: planFromPayload(data),
+\t\tstatus: "active",
+\t\tcustomerId: providerId(data.customer),
+\t\tsubscriptionId: providerId(data.subscription),
+\t\tcheckoutSessionId: stringValue(data.id),
+\t\tlastEventId: event.id,
+\t\tsave,
+\t});
+}
+
+async function applySubscriptionEvent(
+\tevent: PaymentWebhookEvent,
+\tsave: (account: BillingAccount) => Promise<BillingAccount>,
+\tfindByCustomerId: (
+\t\tcustomerId: string,
+\t\tprovider: string,
+\t) => Promise<BillingAccount | null>,
+\tfindByTenantId: (tenantId: string) => Promise<BillingAccount | null>,
+) {
+\tconst data = record(event.data);
+\tconst customerId = providerId(data.customer);
+\tconst explicitTenantId = tenantIdFromPayload(data);
+\tconst existing = explicitTenantId
+\t\t? await findByTenantId(explicitTenantId)
+\t\t: customerId
+\t\t\t? await findByCustomerId(customerId, event.provider)
+\t\t\t: null;
+\tconst tenantId = explicitTenantId ?? existing?.tenantId;
+\tif (!tenantId) return null;
+
+\treturn saveBillingAccount({
+\t\texisting,
+\t\ttenantId,
+\t\tprovider: event.provider,
+\t\tplan: planFromPayload(data),
+\t\tstatus:
+\t\t\tevent.type === "customer.subscription.deleted"
+\t\t\t\t? "canceled"
+\t\t\t\t: statusFromPayload(data, existing?.status ?? "active"),
+\t\tcustomerId,
+\t\tsubscriptionId: providerId(data.id) ?? existing?.subscriptionId,
+\t\tcurrentPeriodEnd: periodEndFromPayload(data),
+\t\tcancelAtPeriodEnd:
+\t\t\tevent.type === "customer.subscription.deleted"
+\t\t\t\t? false
+\t\t\t\t: cancelAtPeriodEndFromPayload(data),
+\t\tlastEventId: event.id,
+\t\tsave,
+\t});
+}
+
+async function applyInvoiceSucceeded(
+\tevent: PaymentWebhookEvent,
+\tsave: (account: BillingAccount) => Promise<BillingAccount>,
+\tfindByCustomerId: (
+\t\tcustomerId: string,
+\t\tprovider: string,
+\t) => Promise<BillingAccount | null>,
+) {
+\tconst data = record(event.data);
+\tconst customerId = providerId(data.customer);
+\tif (!customerId) return null;
+
+\tconst existing = await findByCustomerId(customerId, event.provider);
+\tif (!existing) return null;
+\tif (existing.status === "canceled") return null;
+
+\treturn saveBillingAccount({
+\t\texisting,
+\t\ttenantId: existing.tenantId,
+\t\tprovider: event.provider,
+\t\tstatus: "active",
+\t\tcustomerId,
+\t\tsubscriptionId: providerId(data.subscription),
+\t\tcancelAtPeriodEnd: cancelAtPeriodEndFromPayload(data),
+\t\tlastEventId: event.id,
+\t\tsave,
+\t});
+}
+
+async function applyInvoiceFailed(
+\tevent: PaymentWebhookEvent,
+\tsave: (account: BillingAccount) => Promise<BillingAccount>,
+\tfindByCustomerId: (
+\t\tcustomerId: string,
+\t\tprovider: string,
+\t) => Promise<BillingAccount | null>,
+) {
+\tconst data = record(event.data);
+\tconst customerId = providerId(data.customer);
+\tif (!customerId) return null;
+
+\tconst existing = await findByCustomerId(customerId, event.provider);
+\tif (!existing) return null;
+\tif (existing.status === "canceled") return null;
+
+\treturn saveBillingAccount({
+\t\texisting,
+\t\ttenantId: existing.tenantId,
+\t\tprovider: event.provider,
+\t\tstatus: "past_due",
+\t\tcustomerId,
+\t\tsubscriptionId: providerId(data.subscription),
+\t\tlastEventId: event.id,
+\t\tsave,
+\t});
+}
+
+export const getBillingStatusUseCase = useCase
+\t.query("billing.getStatus")
+\t.input(z.object({}))
+\t.output(billingStatusOutputSchema)
+\t.run(async ({ ctx }) => {
+\t\tconst tenantId = billingTenantId(ctx);
+\t\tconst account = await ctx.ports.billing.findByTenantId(tenantId);
+\t\treturn billingStatusOutput(tenantId, account);
+\t});
+
+export const createCheckoutSessionUseCase = useCase
+\t.command("billing.createCheckoutSession")
+\t.input(createCheckoutSessionInputSchema)
+\t.output(createCheckoutSessionOutputSchema)
+\t.run(async ({ ctx, input }) => {
+\t\tconst tenantId = billingTenantId(ctx);
+\t\tconst account = await ctx.ports.billing.findByTenantId(tenantId);
+\t\tconst plan = getBillingPlan(input.plan);
+\t\tconst session = await ctx.ports.payments.createCheckoutSession({
+\t\t\tmode: plan.mode,
+\t\t\tlineItems: plan.lineItems,
+\t\t\tsuccessUrl: \`\${env.APP_URL}/settings/plan?checkout=success\`,
+\t\t\tcancelUrl: \`\${env.APP_URL}/settings/plan?checkout=cancelled\`,
+\t\t\tcustomerId: account?.customerId,
+\t\t\tclientReferenceId: tenantId,
+\t\t\tmetadata: {
+\t\t\t\ttenantId,
+\t\t\t\tplan: input.plan,
+\t\t\t},
+\t\t});
+
+\t\tif (!session.url) {
+\t\t\tthrow appError("BillingCheckoutUnavailable", {
+\t\t\t\tdetails: { provider: session.provider, sessionId: session.id },
+\t\t\t});
+\t\t}
+
+\t\tawait ctx.ports.billing.save({
+\t\t\ttenantId,
+\t\t\tprovider: session.provider,
+\t\t\tplan: input.plan,
+\t\t\tstatus: account?.status ?? "inactive",
+\t\t\tcustomerId: session.customerId ?? account?.customerId,
+\t\t\tsubscriptionId: account?.subscriptionId,
+\t\t\tcurrentPeriodEnd: account?.currentPeriodEnd,
+\t\t\tcancelAtPeriodEnd: account?.cancelAtPeriodEnd,
+\t\t\tcheckoutSessionId: session.id,
+\t\t\tlastEventId: account?.lastEventId,
+\t\t\tupdatedAt: nowIso(),
+\t\t});
+
+\t\treturn {
+\t\t\tsessionId: session.id,
+\t\t\turl: session.url,
+\t\t};
+\t});
+
+export const createBillingPortalSessionUseCase = useCase
+\t.command("billing.createPortalSession")
+\t.input(z.object({}))
+\t.output(createBillingPortalSessionOutputSchema)
+\t.run(async ({ ctx }) => {
+\t\tconst tenantId = billingTenantId(ctx);
+\t\tconst account = await ctx.ports.billing.findByTenantId(tenantId);
+
+\t\tif (!account?.customerId) {
+\t\t\tthrow appError("BillingAccountNotFound", {
+\t\t\t\tdetails: { tenantId },
+\t\t\t});
+\t\t}
+
+\t\tconst session = await ctx.ports.payments.createBillingPortalSession({
+\t\t\tcustomerId: account.customerId,
+\t\t\treturnUrl: \`\${env.APP_URL}/settings/plan\`,
+\t\t});
+
+\t\treturn { url: session.url };
+\t});
+
+export const handlePaymentWebhookUseCase = useCase
+\t.command("billing.handlePaymentWebhook")
+\t.input(paymentWebhookEventSchema)
+\t.output(paymentWebhookOutputSchema)
+\t.run(async ({ ctx, input }) => {
+\t\tconst fingerprint = await createIdempotencyFingerprint({
+\t\t\ttype: input.type,
+\t\t\tdata: input.data,
+\t\t});
+
+\t\treturn runIdempotently(ctx.ports.idempotency, {
+\t\t\tnamespace: "webhooks.payments",
+\t\t\tkey: input.id,
+\t\t\tscope: { provider: input.provider },
+\t\t\tfingerprint,
+\t\t\tttlSec: 60 * 60 * 24 * 30,
+\t\t\trun: () =>
+\t\t\t\tctx.ports.uow.transaction(async (tx) => {
+\t\t\t\t\tlet account: BillingAccount | null = null;
+
+\t\t\t\t\tif (input.type === "checkout.session.completed") {
+\t\t\t\t\t\taccount = await applyCheckoutCompleted(
+\t\t\t\t\t\t\tinput,
+\t\t\t\t\t\t\ttx.billing.save,
+\t\t\t\t\t\t\ttx.billing.findByTenantId,
+\t\t\t\t\t\t);
+\t\t\t\t\t} else if (input.type.startsWith("customer.subscription.")) {
+\t\t\t\t\t\taccount = await applySubscriptionEvent(
+\t\t\t\t\t\t\tinput,
+\t\t\t\t\t\t\ttx.billing.save,
+\t\t\t\t\t\t\ttx.billing.findByCustomerId,
+\t\t\t\t\t\t\ttx.billing.findByTenantId,
+\t\t\t\t\t\t);
+\t\t\t\t\t} else if (input.type === "invoice.payment_succeeded") {
+\t\t\t\t\t\taccount = await applyInvoiceSucceeded(
+\t\t\t\t\t\t\tinput,
+\t\t\t\t\t\t\ttx.billing.save,
+\t\t\t\t\t\t\ttx.billing.findByCustomerId,
+\t\t\t\t\t\t);
+\t\t\t\t\t} else if (input.type === "invoice.payment_failed") {
+\t\t\t\t\t\taccount = await applyInvoiceFailed(
+\t\t\t\t\t\t\tinput,
+\t\t\t\t\t\t\ttx.billing.save,
+\t\t\t\t\t\t\ttx.billing.findByCustomerId,
+\t\t\t\t\t\t);
+\t\t\t\t\t}
+
+\t\t\t\t\treturn {
+\t\t\t\t\t\treceived: true,
+\t\t\t\t\t\taccountUpdated: Boolean(account),
+\t\t\t\t\t};
+\t\t\t\t}),
+\t\t});
+\t});
+`;
+}
+
+export function billingRoutesFile(config: ResolvedBeignetConfig): string {
+  const routeFilePath = path.join(config.paths.features, "billing/routes.ts");
+
+  return `import { defineRouteGroup } from "@beignet/next";
+import type { AppContext } from "${relativeModule(routeFilePath, config.paths.appContext)}";
+import * as billingContracts from "@/features/billing/contracts";
+import * as billingUseCases from "@/features/billing/use-cases";
+
+export const billingRoutes = defineRouteGroup<AppContext>()({
+\tname: "billing",
+\troutes: [
+\t\t{
+\t\t\tcontract: billingContracts.getBillingStatus,
+\t\t\tuseCase: billingUseCases.getBillingStatusUseCase,
+\t\t},
+\t\t{
+\t\t\tcontract: billingContracts.createCheckoutSession,
+\t\t\tuseCase: billingUseCases.createCheckoutSessionUseCase,
+\t\t},
+\t\t{
+\t\t\tcontract: billingContracts.createBillingPortalSession,
+\t\t\tuseCase: billingUseCases.createBillingPortalSessionUseCase,
+\t\t},
+\t],
+});
+`;
+}
+
+export function billingTestFile(config: ResolvedBeignetConfig): string {
+  return `import { describe, expect, it } from "bun:test";
+import { createUseCaseTester } from "@beignet/core/application";
+import { requireEntitlement } from "@beignet/core/entitlements";
+import { createAnonymousActor } from "@beignet/core/ports";
+import { createTestUserActor } from "@beignet/core/ports/testing";
+import {
+\tcreateTestContextFactory,
+\tcreateTestPorts,
+} from "@beignet/core/testing";
+import type { AppContext } from "${aliasModule(config.paths.appContext)}";
+import { appPorts } from "@/infra/app-ports";
+import type { AppTransactionPorts } from "@/ports";
+import { createBillingEntitlements } from "../entitlements";
+import type { BillingAccount, BillingRepository } from "../ports";
+import {
+\tcreateBillingPortalSessionUseCase,
+\tcreateCheckoutSessionUseCase,
+\tgetBillingStatusUseCase,
+\thandlePaymentWebhookUseCase,
+} from "../use-cases";
+
+function createMemoryBillingRepository(): BillingRepository {
+\tconst accounts = new Map<string, BillingAccount>();
+
+\treturn {
+\t\tasync findByTenantId(tenantId) {
+\t\t\treturn accounts.get(tenantId) ?? null;
+\t\t},
+
+\t\tasync findByCustomerId(customerId, provider) {
+\t\t\treturn (
+\t\t\t\t[...accounts.values()].find(
+\t\t\t\t\t(account) =>
+\t\t\t\t\t\taccount.customerId === customerId &&
+\t\t\t\t\t\taccount.provider === provider,
+\t\t\t\t) ?? null
+\t\t\t);
+\t\t},
+
+\t\tasync save(input) {
+\t\t\taccounts.set(input.tenantId, { ...input });
+\t\t\treturn input;
+\t\t},
+\t};
+}
+
+function createHarness(options: { actor?: AppContext["actor"] } = {}) {
+\tconst billing = createMemoryBillingRepository();
+\tconst actor = options.actor ?? createTestUserActor("user_test");
+\tconst fixture = createTestPorts<AppContext["ports"], AppTransactionPorts>({
+\t\tbase: appPorts,
+\t\toverrides: {
+\t\t\tbilling,
+\t\t\tentitlements: createBillingEntitlements(billing),
+\t\t\tgate: appPorts.gate,
+\t\t},
+\t});
+\tconst createContext = createTestContextFactory<
+\t\tAppContext,
+\t\tAppContext["ports"]
+\t>({
+\t\tports: fixture.ports,
+\t\tactor,
+\t\tauth:
+\t\t\tactor.type === "user" && actor.id
+\t\t\t\t? { user: { id: actor.id }, session: { id: "session_test" } }
+\t\t\t\t: null,
+\t\trequestId: "test-request",
+\t\ttraceId: "test-trace",
+\t\ttenant: { id: "tenant_example" },
+\t});
+
+\treturn {
+\t\tbilling,
+\t\tentitlements: fixture.ports.entitlements,
+\t\tpayments: fixture.payments,
+\t\ttester: createUseCaseTester<AppContext>(createContext),
+\t};
+}
+
+describe("billing use cases", () => {
+\tit("requires an authenticated user to read billing status", async () => {
+\t\tconst harness = createHarness({ actor: createAnonymousActor() });
+
+\t\tawait expect(
+\t\t\tharness.tester.run(getBillingStatusUseCase, {}),
+\t\t).rejects.toMatchObject({
+\t\t\tcode: "UNAUTHORIZED",
+\t\t});
+\t});
+
+\tit("creates checkout sessions through the payments port and records billing state", async () => {
+\t\tconst harness = createHarness();
+
+\t\tconst checkout = await harness.tester.run(createCheckoutSessionUseCase, {
+\t\t\tplan: "pro",
+\t\t});
+
+\t\texpect(checkout.sessionId).toMatch(/^checkout_/);
+\t\texpect(checkout.url).toContain("/checkout/");
+\t\texpect(harness.payments.checkoutSessions).toHaveLength(1);
+\t\texpect(harness.payments.checkoutSessions[0]?.input).toMatchObject({
+\t\t\tmode: "subscription",
+\t\t\tlineItems: [{ priceId: "price_pro_example", quantity: 1 }],
+\t\t\tclientReferenceId: "tenant_example",
+\t\t\tmetadata: {
+\t\t\t\ttenantId: "tenant_example",
+\t\t\t\tplan: "pro",
+\t\t\t},
+\t\t});
+\t\texpect(
+\t\t\tharness.payments.checkoutSessions[0]?.input.idempotencyKey,
+\t\t).toBe(undefined);
+\t\tawait expect(
+\t\t\tharness.billing.findByTenantId("tenant_example"),
+\t\t).resolves.toMatchObject({
+\t\t\tcheckoutSessionId: checkout.sessionId,
+\t\t\tplan: "pro",
+\t\t\tstatus: "inactive",
+\t\t});
+\t});
+
+\tit("creates billing portal sessions for tenants with provider customers", async () => {
+\t\tconst harness = createHarness();
+\t\tawait harness.billing.save({
+\t\t\ttenantId: "tenant_example",
+\t\t\tprovider: "memory",
+\t\t\tplan: "pro",
+\t\t\tstatus: "active",
+\t\t\tcustomerId: "cus_123",
+\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t});
+
+\t\tconst portal = await harness.tester.run(
+\t\t\tcreateBillingPortalSessionUseCase,
+\t\t\t{},
+\t\t);
+
+\t\texpect(portal.url).toContain("/portal/");
+\t\texpect(harness.payments.billingPortalSessions).toHaveLength(1);
+\t\texpect(harness.payments.billingPortalSessions[0]?.input.customerId).toBe(
+\t\t\t"cus_123",
+\t\t);
+\t});
+
+\tit.each(["active", "trialing"] as const)(
+\t\t"grants pro entitlements for %s accounts",
+\t\tasync (status) => {
+\t\t\tconst harness = createHarness();
+\t\t\tawait harness.billing.save({
+\t\t\t\ttenantId: "tenant_example",
+\t\t\t\tprovider: "stripe",
+\t\t\t\tplan: "pro",
+\t\t\t\tstatus,
+\t\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t\t});
+
+\t\t\tawait expect(
+\t\t\t\tharness.entitlements.can({
+\t\t\t\t\tentitlement: "todos.create",
+\t\t\t\t\tsubject: { type: "tenant", id: "tenant_example" },
+\t\t\t\t}),
+\t\t\t).resolves.toBe(true);
+\t\t},
+\t);
+
+\tit.each(["inactive", "past_due", "canceled"] as const)(
+\t\t"resolves %s accounts to the free plan and denies pro entitlements",
+\t\tasync (status) => {
+\t\t\tconst harness = createHarness();
+\t\t\tawait harness.billing.save({
+\t\t\t\ttenantId: "tenant_example",
+\t\t\t\tprovider: "stripe",
+\t\t\t\tplan: "pro",
+\t\t\t\tstatus,
+\t\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t\t});
+
+\t\t\tawait expect(
+\t\t\t\tharness.entitlements.inspect({
+\t\t\t\t\tentitlement: "todos.create",
+\t\t\t\t\tsubject: { type: "tenant", id: "tenant_example" },
+\t\t\t\t}),
+\t\t\t).resolves.toMatchObject({
+\t\t\t\tallowed: false,
+\t\t\t\tcode: "ENTITLEMENT_NOT_INCLUDED",
+\t\t\t\tdetails: { plan: "free" },
+\t\t\t});
+\t\t},
+\t);
+
+\tit("gates paid actions with requireEntitlement once the free limit is reached", async () => {
+\t\tconst harness = createHarness();
+\t\tconst ctx = { ports: { entitlements: harness.entitlements } };
+\t\tconst subject = { type: "tenant", id: "tenant_example" } as const;
+
+\t\t// In a use case, count usage first and only gate past the free limit:
+\t\t//
+\t\t//   if (todoCount >= FREE_PLAN_LIMITS.todos) {
+\t\t//     await requireEntitlement(ctx, {
+\t\t//       entitlement: "todos.create",
+\t\t//       subject: { type: "tenant", id: tenantId },
+\t\t//     });
+\t\t//   }
+\t\t//
+\t\t// Without an active subscription the account resolves to the free plan,
+\t\t// so the pro entitlement is denied with a 403.
+\t\tawait expect(
+\t\t\trequireEntitlement(ctx, { entitlement: "todos.create", subject }),
+\t\t).rejects.toMatchObject({
+\t\t\tcode: "ENTITLEMENT_NOT_INCLUDED",
+\t\t\tstatus: 403,
+\t\t});
+
+\t\tawait harness.billing.save({
+\t\t\ttenantId: "tenant_example",
+\t\t\tprovider: "stripe",
+\t\t\tplan: "pro",
+\t\t\tstatus: "active",
+\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t});
+
+\t\tawait expect(
+\t\t\trequireEntitlement(ctx, { entitlement: "todos.create", subject }),
+\t\t).resolves.toMatchObject({ allowed: true });
+\t});
+
+\tit("handles checkout and subscription webhooks idempotently", async () => {
+\t\tconst harness = createHarness();
+\t\tconst checkoutEvent = {
+\t\t\tid: "evt_checkout_completed",
+\t\t\ttype: "checkout.session.completed",
+\t\t\tprovider: "stripe",
+\t\t\tdata: {
+\t\t\t\tid: "cs_123",
+\t\t\t\tclient_reference_id: "tenant_example",
+\t\t\t\tcustomer: "cus_123",
+\t\t\t\tsubscription: "sub_123",
+\t\t\t\tmetadata: {
+\t\t\t\t\ttenantId: "tenant_example",
+\t\t\t\t\tplan: "pro",
+\t\t\t\t},
+\t\t\t},
+\t\t};
+\t\tconst subscriptionEvent = {
+\t\t\tid: "evt_subscription_updated",
+\t\t\ttype: "customer.subscription.updated",
+\t\t\tprovider: "stripe",
+\t\t\tdata: {
+\t\t\t\tid: "sub_123",
+\t\t\t\tcustomer: "cus_123",
+\t\t\t\tstatus: "active",
+\t\t\t\tcurrent_period_end: 1_799_798_400,
+\t\t\t\tcancel_at_period_end: true,
+\t\t\t},
+\t\t};
+
+\t\tawait expect(
+\t\t\tharness.tester.run(handlePaymentWebhookUseCase, checkoutEvent),
+\t\t).resolves.toEqual({ received: true, accountUpdated: true });
+\t\tawait expect(
+\t\t\tharness.tester.run(handlePaymentWebhookUseCase, checkoutEvent),
+\t\t).resolves.toEqual({ received: true, accountUpdated: true });
+\t\tawait expect(
+\t\t\tharness.tester.run(handlePaymentWebhookUseCase, subscriptionEvent),
+\t\t).resolves.toEqual({ received: true, accountUpdated: true });
+\t\tawait expect(
+\t\t\tharness.tester.run(getBillingStatusUseCase, {}),
+\t\t).resolves.toMatchObject({
+\t\t\ttenantId: "tenant_example",
+\t\t\tplan: "pro",
+\t\t\tactive: true,
+\t\t\tstatus: "active",
+\t\t\tcustomerId: "cus_123",
+\t\t\tsubscriptionId: "sub_123",
+\t\t\tcurrentPeriodEnd: "2027-01-13T00:00:00.000Z",
+\t\t\tcancelAtPeriodEnd: true,
+\t\t\tcheckoutSessionId: "cs_123",
+\t\t\tlastEventId: "evt_subscription_updated",
+\t\t});
+\t});
+
+\tit("marks active subscriptions as past due when invoice payment fails", async () => {
+\t\tconst harness = createHarness();
+\t\tawait harness.billing.save({
+\t\t\ttenantId: "tenant_example",
+\t\t\tprovider: "stripe",
+\t\t\tplan: "pro",
+\t\t\tstatus: "active",
+\t\t\tcustomerId: "cus_123",
+\t\t\tsubscriptionId: "sub_123",
+\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t});
+
+\t\tawait expect(
+\t\t\tharness.tester.run(handlePaymentWebhookUseCase, {
+\t\t\t\tid: "evt_invoice_failed",
+\t\t\t\ttype: "invoice.payment_failed",
+\t\t\t\tprovider: "stripe",
+\t\t\t\tdata: {
+\t\t\t\t\tcustomer: "cus_123",
+\t\t\t\t\tsubscription: "sub_123",
+\t\t\t\t},
+\t\t\t}),
+\t\t).resolves.toEqual({ received: true, accountUpdated: true });
+\t\tawait expect(
+\t\t\tharness.billing.findByTenantId("tenant_example"),
+\t\t).resolves.toMatchObject({
+\t\t\tstatus: "past_due",
+\t\t\tlastEventId: "evt_invoice_failed",
+\t\t});
+\t});
+
+\tit("preserves pending cancellation when an invoice succeeds", async () => {
+\t\tconst harness = createHarness();
+\t\tawait harness.billing.save({
+\t\t\ttenantId: "tenant_example",
+\t\t\tprovider: "stripe",
+\t\t\tplan: "pro",
+\t\t\tstatus: "active",
+\t\t\tcustomerId: "cus_123",
+\t\t\tsubscriptionId: "sub_123",
+\t\t\tcancelAtPeriodEnd: true,
+\t\t\tupdatedAt: new Date(0).toISOString(),
+\t\t});
+
+\t\tawait expect(
+\t\t\tharness.tester.run(handlePaymentWebhookUseCase, {
+\t\t\t\tid: "evt_invoice_succeeded",
+\t\t\t\ttype: "invoice.payment_succeeded",
+\t\t\t\tprovider: "stripe",
+\t\t\t\tdata: {
+\t\t\t\t\tcustomer: "cus_123",
+\t\t\t\t\tsubscription: "sub_123",
+\t\t\t\t},
+\t\t\t}),
+\t\t).resolves.toEqual({ received: true, accountUpdated: true });
+\t\tawait expect(
+\t\t\tharness.billing.findByTenantId("tenant_example"),
+\t\t).resolves.toMatchObject({
+\t\t\tstatus: "active",
+\t\t\tcancelAtPeriodEnd: true,
+\t\t\tlastEventId: "evt_invoice_succeeded",
+\t\t});
+\t});
+});
+`;
+}
+
+export function billingDrizzleSchemaFile(database: DatabaseName): string {
+  const dialect = drizzleDialects[database];
+  const idColumn =
+    database === "mysql"
+      ? (columnName: string) => `varchar("${columnName}", { length: 255 })`
+      : (columnName: string) => `text("${columnName}")`;
+  const imports =
+    database === "mysql"
+      ? "mysqlTable, uniqueIndex, varchar"
+      : `${dialect.tableFunction}, text, uniqueIndex`;
+
+  return `import type { BillingPlan, BillingStatus } from "@/features/billing/schemas";
+import { ${imports} } from "${dialect.columnModule}";
+
+export const billingAccounts = ${dialect.tableFunction}(
+\t"billing_accounts",
+\t{
+\t\ttenantId: ${idColumn("tenant_id")}.primaryKey(),
+\t\tplan: ${idColumn("plan")}.$type<BillingPlan>().notNull(),
+\t\tstatus: ${idColumn("status")}.$type<BillingStatus>().notNull(),
+\t\tprovider: ${idColumn("provider")}.notNull(),
+\t\tcustomerId: ${idColumn("customer_id")},
+\t\tsubscriptionId: ${idColumn("subscription_id")},
+\t\tcurrentPeriodEnd: ${idColumn("current_period_end")},
+\t\tcancelAtPeriodEnd: ${idColumn("cancel_at_period_end")}.$type<"true" | "false">(),
+\t\tcheckoutSessionId: ${idColumn("checkout_session_id")},
+\t\tlastEventId: ${idColumn("last_event_id")},
+\t\tupdatedAt: ${idColumn("updated_at")}.notNull(),
+\t},
+\t(table) => ({
+\t\tproviderCustomerUnique: uniqueIndex(
+\t\t\t"billing_accounts_provider_customer_unique",
+\t\t).on(table.provider, table.customerId),
+\t\tproviderSubscriptionUnique: uniqueIndex(
+\t\t\t"billing_accounts_provider_subscription_unique",
+\t\t).on(table.provider, table.subscriptionId),
+\t}),
+);
+`;
+}
+
+export function billingDrizzleRepositoryFile(
+  config: ResolvedBeignetConfig,
+  database: DatabaseName,
+): string {
+  const dialect = drizzleDialects[database];
+  const billingPortPath = path.join(config.paths.features, "billing/ports.ts");
+  const upsert =
+    database === "mysql"
+      ? `\t\t\tconst row = toRow(input);
+\t\t\tawait db
+\t\t\t\t.insert(schema.billingAccounts)
+\t\t\t\t.values(row)
+\t\t\t\t.onDuplicateKeyUpdate({ set: row });
+
+\t\t\tconst [saved] = await db
+\t\t\t\t.select()
+\t\t\t\t.from(schema.billingAccounts)
+\t\t\t\t.where(eq(schema.billingAccounts.tenantId, input.tenantId))
+\t\t\t\t.limit(1);
+
+\t\t\tif (!saved) {
+\t\t\t\tthrow new Error("Billing account save did not return a row.");
+\t\t\t}
+
+\t\t\treturn toBillingAccount(saved);`
+      : `\t\t\tconst [row] = await db
+\t\t\t\t.insert(schema.billingAccounts)
+\t\t\t\t.values(toRow(input))
+\t\t\t\t.onConflictDoUpdate({
+\t\t\t\t\ttarget: schema.billingAccounts.tenantId,
+\t\t\t\t\tset: toRow(input),
+\t\t\t\t})
+\t\t\t\t.returning();
+
+\t\t\tif (!row) {
+\t\t\t\tthrow new Error("Billing account save did not return a row.");
+\t\t\t}
+
+\t\t\treturn toBillingAccount(row);`;
+
+  return `import type { ${dialect.dbTypeName} } from "@beignet/provider-db-drizzle/${dialect.subpath}";
+import { and, eq } from "drizzle-orm";
+import type {
+\tBillingAccount,
+\tBillingRepository,
+\tSaveBillingAccountInput,
+} from "${aliasModule(billingPortPath)}";
+import * as schema from "@/infra/db/schema";
+
+type BillingAccountRow = typeof schema.billingAccounts.$inferSelect;
+
+function toBillingAccount(row: BillingAccountRow): BillingAccount {
+\treturn {
+\t\ttenantId: row.tenantId,
+\t\tplan: row.plan,
+\t\tstatus: row.status,
+\t\tprovider: row.provider,
+\t\t...(row.customerId ? { customerId: row.customerId } : {}),
+\t\t...(row.subscriptionId ? { subscriptionId: row.subscriptionId } : {}),
+\t\t...(row.currentPeriodEnd ? { currentPeriodEnd: row.currentPeriodEnd } : {}),
+\t\t...(row.cancelAtPeriodEnd
+\t\t\t? { cancelAtPeriodEnd: row.cancelAtPeriodEnd === "true" }
+\t\t\t: {}),
+\t\t...(row.checkoutSessionId
+\t\t\t? { checkoutSessionId: row.checkoutSessionId }
+\t\t\t: {}),
+\t\t...(row.lastEventId ? { lastEventId: row.lastEventId } : {}),
+\t\tupdatedAt: row.updatedAt,
+\t};
+}
+
+function toRow(input: SaveBillingAccountInput) {
+\treturn {
+\t\ttenantId: input.tenantId,
+\t\tplan: input.plan,
+\t\tstatus: input.status,
+\t\tprovider: input.provider,
+\t\tcustomerId: input.customerId ?? null,
+\t\tsubscriptionId: input.subscriptionId ?? null,
+\t\tcurrentPeriodEnd: input.currentPeriodEnd ?? null,
+\t\tcancelAtPeriodEnd:
+\t\t\tinput.cancelAtPeriodEnd === undefined
+\t\t\t\t? null
+\t\t\t\t: input.cancelAtPeriodEnd
+\t\t\t\t\t? ("true" as const)
+\t\t\t\t\t: ("false" as const),
+\t\tcheckoutSessionId: input.checkoutSessionId ?? null,
+\t\tlastEventId: input.lastEventId ?? null,
+\t\tupdatedAt: input.updatedAt,
+\t};
+}
+
+export function createDrizzleBillingRepository(
+\tdb: ${dialect.dbTypeName}<typeof schema>,
+): BillingRepository {
+\treturn {
+\t\tasync findByTenantId(tenantId) {
+\t\t\tconst [row] = await db
+\t\t\t\t.select()
+\t\t\t\t.from(schema.billingAccounts)
+\t\t\t\t.where(eq(schema.billingAccounts.tenantId, tenantId))
+\t\t\t\t.limit(1);
+
+\t\t\treturn row ? toBillingAccount(row) : null;
+\t\t},
+
+\t\tasync findByCustomerId(customerId, provider) {
+\t\t\tconst rows = await db
+\t\t\t\t.select()
+\t\t\t\t.from(schema.billingAccounts)
+\t\t\t\t.where(
+\t\t\t\t\tand(
+\t\t\t\t\t\teq(schema.billingAccounts.customerId, customerId),
+\t\t\t\t\t\teq(schema.billingAccounts.provider, provider),
+\t\t\t\t\t),
+\t\t\t\t)
+\t\t\t\t.limit(2);
+
+\t\t\tif (rows.length > 1) {
+\t\t\t\tthrow new Error(
+\t\t\t\t\t\`Multiple billing accounts found for provider "\${provider}" customer "\${customerId}".\`,
+\t\t\t\t);
+\t\t\t}
+
+\t\t\treturn rows[0] ? toBillingAccount(rows[0]) : null;
+\t\t},
+
+\t\tasync save(input) {
+${upsert}
+\t\t},
+\t};
+}
+`;
+}
+
+export function billingSeedsFile(config: ResolvedBeignetConfig): string {
+  return `import { defineSeed } from "@beignet/core/testing";
+import type { AppContext } from "${aliasModule(config.paths.appContext)}";
+
+/**
+ * Demo billing account on the free plan. Billing accounts are keyed by
+ * tenant id, which falls back to the user id until tenancy is added, so the
+ * demo account uses a stable placeholder id.
+ */
+export const demoBillingAccountSeed = defineSeed(
+\t"billing.demo-billing-account",
+\t{
+\t\tdescription: "Creates a demo billing account on the free plan.",
+\t\trun: async (ctx: AppContext) => {
+\t\t\tawait ctx.ports.billing.save({
+\t\t\t\ttenantId: "demo-user",
+\t\t\t\tplan: "free",
+\t\t\t\tstatus: "inactive",
+\t\t\t\tprovider: "memory",
+\t\t\t\tupdatedAt: new Date().toISOString(),
+\t\t\t});
+\t\t},
+\t},
+);
+
+export const billingSeeds = [demoBillingAccountSeed] as const;
+`;
+}
+
+export function billingClientQueriesFile(): string {
+  return `import type { QueryClient } from "@tanstack/react-query";
+import { rq } from "@/client";
+import {
+\tcreateBillingPortalSession,
+\tcreateCheckoutSession,
+\tgetBillingStatus,
+} from "@/features/billing/contracts";
+
+export function getBillingStatusQueryOptions() {
+\treturn rq(getBillingStatus).queryOptions({ query: {} });
+}
+
+export function createCheckoutSessionMutationOptions() {
+\treturn rq(createCheckoutSession).mutationOptions();
+}
+
+export function createBillingPortalSessionMutationOptions() {
+\treturn rq(createBillingPortalSession).mutationOptions();
+}
+
+export function invalidateBillingStatus(queryClient: QueryClient) {
+\treturn rq(getBillingStatus).invalidate(queryClient);
+}
+`;
+}
+
+export function billingPlanCardFile(): string {
+  return `import { SparklesIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import type { BillingStatusOutput } from "@/features/billing/schemas";
+import { cn } from "@/lib/utils";
+
+/**
+ * Current plan overview. Actions (upgrade / portal) render through
+ * \`actions\`.
+ */
+export function PlanCard({
+\tbilling,
+\tactions,
+}: {
+\tbilling: BillingStatusOutput;
+\tactions?: ReactNode;
+}) {
+\tconst isPro = billing.plan === "pro";
+
+\treturn (
+\t\t<Card>
+\t\t\t<CardHeader>
+\t\t\t\t<CardTitle className="flex items-center gap-2">
+\t\t\t\t\t{isPro ? <SparklesIcon className="size-4 text-primary" /> : null}
+\t\t\t\t\t{isPro ? "Pro" : "Free"} plan
+\t\t\t\t\t<span
+\t\t\t\t\t\tclassName={cn(
+\t\t\t\t\t\t\t"rounded-full border px-2 py-0.5 text-xs font-medium",
+\t\t\t\t\t\t\tbilling.active
+\t\t\t\t\t\t\t\t? "border-primary/40 text-primary"
+\t\t\t\t\t\t\t\t: "text-muted-foreground",
+\t\t\t\t\t\t)}
+\t\t\t\t\t>
+\t\t\t\t\t\t{billing.status}
+\t\t\t\t\t</span>
+\t\t\t\t</CardTitle>
+\t\t\t</CardHeader>
+\t\t\t<CardContent className="flex flex-col gap-4">
+\t\t\t\t<p className="text-sm text-muted-foreground">
+\t\t\t\t\t{isPro
+\t\t\t\t\t\t? "Pro removes the free-plan limits."
+\t\t\t\t\t\t: "The free plan is fully functional up to the free-plan limits. Upgrade to Pro to remove them."}
+\t\t\t\t</p>
+\t\t\t\t{actions}
+\t\t\t</CardContent>
+\t\t</Card>
+\t);
+}
+`;
+}
+
+export function billingActionsFile(): string {
+  return `"use client";
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { CreditCardIcon, ExternalLinkIcon, Loader2Icon } from "lucide-react";
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+\tcreateBillingPortalSessionMutationOptions,
+\tcreateCheckoutSessionMutationOptions,
+\tinvalidateBillingStatus,
+} from "@/features/billing/client/queries";
+import type { BillingPlan } from "@/features/billing/schemas";
+
+/**
+ * Upgrade and billing-portal actions. Checkout is idempotent: each attempt
+ * sends a fresh \`idempotency-key\`, and retries of the same attempt replay
+ * it.
+ */
+export function BillingActions({
+\tplan,
+\thasCustomer,
+}: {
+\tplan: BillingPlan;
+\thasCustomer: boolean;
+}) {
+\tconst queryClient = useQueryClient();
+\tconst [error, setError] = useState<string | null>(null);
+\tconst [idempotencyKey, setIdempotencyKey] = useState(() =>
+\t\tcrypto.randomUUID(),
+\t);
+
+\tconst checkout = useMutation({
+\t\t...createCheckoutSessionMutationOptions(),
+\t\tonSuccess(data) {
+\t\t\tvoid invalidateBillingStatus(queryClient);
+\t\t\twindow.location.assign(data.url);
+\t\t},
+\t\tonError() {
+\t\t\tsetError("Could not start checkout. Try again.");
+\t\t\tsetIdempotencyKey(crypto.randomUUID());
+\t\t},
+\t});
+\tconst portal = useMutation({
+\t\t...createBillingPortalSessionMutationOptions(),
+\t\tonSuccess(data) {
+\t\t\twindow.location.assign(data.url);
+\t\t},
+\t\tonError() {
+\t\t\tsetError("Could not open the billing portal.");
+\t\t},
+\t});
+\tconst busy = checkout.isPending || portal.isPending;
+
+\treturn (
+\t\t<div className="flex flex-col gap-3">
+\t\t\t<div className="flex flex-wrap gap-2">
+\t\t\t\t{plan === "free" ? (
+\t\t\t\t\t<Button
+\t\t\t\t\t\ttype="button"
+\t\t\t\t\t\tdisabled={busy}
+\t\t\t\t\t\tonClick={() => {
+\t\t\t\t\t\t\tsetError(null);
+\t\t\t\t\t\t\tcheckout.mutate({
+\t\t\t\t\t\t\t\tbody: { plan: "pro" },
+\t\t\t\t\t\t\t\theaders: { "idempotency-key": idempotencyKey },
+\t\t\t\t\t\t\t});
+\t\t\t\t\t\t}}
+\t\t\t\t\t>
+\t\t\t\t\t\t{checkout.isPending ? (
+\t\t\t\t\t\t\t<Loader2Icon className="size-4 animate-spin" />
+\t\t\t\t\t\t) : (
+\t\t\t\t\t\t\t<CreditCardIcon className="size-4" />
+\t\t\t\t\t\t)}
+\t\t\t\t\t\tUpgrade to Pro
+\t\t\t\t\t</Button>
+\t\t\t\t) : null}
+\t\t\t\t<Button
+\t\t\t\t\ttype="button"
+\t\t\t\t\tvariant="secondary"
+\t\t\t\t\tdisabled={busy || !hasCustomer}
+\t\t\t\t\tonClick={() => {
+\t\t\t\t\t\tsetError(null);
+\t\t\t\t\t\tportal.mutate({ body: {} });
+\t\t\t\t\t}}
+\t\t\t\t>
+\t\t\t\t\t{portal.isPending ? (
+\t\t\t\t\t\t<Loader2Icon className="size-4 animate-spin" />
+\t\t\t\t\t) : (
+\t\t\t\t\t\t<ExternalLinkIcon className="size-4" />
+\t\t\t\t\t)}
+\t\t\t\t\tBilling portal
+\t\t\t\t</Button>
+\t\t\t</div>
+\t\t\t{error ? <p className="text-sm text-destructive">{error}</p> : null}
+\t\t</div>
+\t);
+}
+`;
+}
+
+export function billingComponentsIndexFile(): string {
+  return `export { BillingActions } from "./billing-actions";
+export { PlanCard } from "./plan-card";
+`;
+}
+
+export function billingPlanPageFile(): string {
+  return `"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { getBillingStatusQueryOptions } from "@/features/billing/client/queries";
+import { BillingActions, PlanCard } from "@/features/billing/components";
+
+export default function SettingsPlanPage() {
+\tconst billingQuery = useQuery(getBillingStatusQueryOptions());
+
+\tif (billingQuery.isPending) {
+\t\treturn <p className="text-sm text-muted-foreground">Loading plan...</p>;
+\t}
+
+\tif (billingQuery.isError) {
+\t\treturn (
+\t\t\t<p className="text-sm text-destructive">Could not load your plan.</p>
+\t\t);
+\t}
+
+\treturn (
+\t\t<PlanCard
+\t\t\tbilling={billingQuery.data}
+\t\t\tactions={
+\t\t\t\t<BillingActions
+\t\t\t\t\tplan={billingQuery.data.plan}
+\t\t\t\t\thasCustomer={Boolean(billingQuery.data.customerId)}
+\t\t\t\t/>
+\t\t\t}
+\t\t/>
+\t);
+}
+`;
+}
+
+export function billingWebhookRouteFile(): string {
+  return `import { createPaymentWebhookRoute } from "@beignet/next";
+import { handlePaymentWebhookUseCase } from "@/features/billing/use-cases";
+import { getServer } from "@/server";
+
+export const runtime = "nodejs";
+
+export const { POST } = createPaymentWebhookRoute({
+\tserver: getServer,
+\thandle: async ({ ctx, event }) => {
+\t\tawait handlePaymentWebhookUseCase.run({ ctx, input: event });
+\t\treturn {
+\t\t\tstatus: 200,
+\t\t\tbody: {
+\t\t\t\treceived: true,
+\t\t\t},
+\t\t};
+\t},
+});
+`;
+}