@beignet/cli 0.0.13 → 0.0.15

package/src/make.ts

@@ -172,6 +172,13 @@ type MakeUploadOptions = {
   config?: BeignetConfig;
 };
 
+type MakePaymentsOptions = {
+  cwd?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  config?: BeignetConfig;
+};
+
 type MakeResult = {
   schemaVersion: 1;
   name: string;
@@ -251,6 +258,10 @@ export type MakeScheduleResult = MakeResult;
  * Result returned by `beignet make upload`.
  */
 export type MakeUploadResult = MakeResult;
+/**
+ * Result returned by `beignet make payments`.
+ */
+export type MakePaymentsResult = MakeResult;
 
 type ResourceNames = {
   input: string;
@@ -473,6 +484,90 @@ export async function makeFeature(
   return makeFeatureSlice(options, addons);
 }
 
+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 generatedFiles = paymentsFiles(config, database);
+  const plannedFiles = await planGeneratedFiles(targetDir, generatedFiles, {
+    force: Boolean(options.force),
+  });
+  const billingNames = resourceNames("billing");
+  const plannedBillingUpdates = await updatePaymentsWiring(
+    targetDir,
+    billingNames,
+    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) {
+    updatedFiles.push(...plannedBillingUpdates, ...plannedPaymentsUpdates);
+  } else {
+    for (const file of plannedFiles) {
+      await writePlannedGeneratedFile(targetDir, file);
+    }
+
+    updatedFiles.push(
+      ...(await updatePaymentsWiring(targetDir, billingNames, config, {
+        dryRun: false,
+      })),
+    );
+    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),
+    createdFiles,
+    updatedFiles: uniqueStrings(updatedFiles),
+    skippedFiles,
+  };
+}
+
 async function makeFeatureResource(
   options: MakeResourceOptions,
 ): Promise<MakeResourceResult> {
@@ -1482,6 +1577,17 @@ function notificationPortWirings(command: string): PortProviderWiring[] {
   ];
 }
 
+function paymentsPortWiring(command: string): PortProviderWiring {
+  return {
+    command,
+    portKey: "payments",
+    portType: "PaymentsPort",
+    portTypeModule: "@beignet/core/payments",
+    providerFactory: "createMemoryPaymentsProvider",
+    providerModule: "@beignet/core/payments",
+  };
+}
+
 function providersFilePath(config: ResolvedBeignetConfig): string {
   return `${directoryPath(path.dirname(config.paths.server))}/providers.ts`;
 }
@@ -2310,6 +2416,87 @@ async function updateResourceWiring(
   return [...updated];
 }
 
+async function updatePaymentsWiring(
+  targetDir: string,
+  billingNames: ResourceNames,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<string[]> {
+  const updated = new Set<string>();
+
+  if (await updatePackageJson(targetDir, options)) {
+    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 updateBillingDrizzleSchemaIndex(targetDir, config, options)) {
+    updated.add(drizzleSchemaIndexPath(config));
+  }
+  if (
+    await updateDrizzleRepositories(targetDir, billingNames, config, options)
+  ) {
+    updated.add(drizzleRepositoriesPath(config));
+  }
+  if (await updateDatabaseProviderPick(targetDir, config, 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 updateBillingTransactionPorts(targetDir, config, options)) {
+    updated.add(
+      path.join(infrastructureDir(config), "db/transaction-ports.ts"),
+    );
+  }
+  if (await updateDatabaseResetTables(targetDir, config, 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");
+  }
+
+  const routesFile = await updateServerRoutes(
+    targetDir,
+    billingNames,
+    config,
+    options,
+  );
+  if (routesFile) updated.add(routesFile);
+
+  return [...updated];
+}
+
 async function updatePackageJson(
   targetDir: string,
   options: { dryRun: boolean; webTestingDependency?: boolean },
@@ -2439,6 +2626,59 @@ async function updatePortIndex(
   return true;
 }
 
+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;
+}
+
 async function updateInfrastructurePortStub(
   targetDir: string,
   names: PortNames,
@@ -2620,6 +2860,23 @@ async function updateDrizzleSchemaIndex(
   return true;
 }
 
+async function updateBillingDrizzleSchemaIndex(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const filePath = path.join(targetDir, drizzleSchemaIndexPath(config));
+  if (!(await fileExists(filePath))) return false;
+
+  const original = await readFile(filePath, "utf8");
+  const exportLine = 'export { billingAccounts } from "./billing";';
+  if (original.includes(exportLine)) return false;
+
+  const next = `${original.trimEnd()}\n${exportLine}\n`;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
 async function updateDrizzleRepositories(
   targetDir: string,
   names: ResourceNames,
@@ -2659,6 +2916,138 @@ async function updateDrizzleRepositories(
   return true;
 }
 
+async function updateDatabaseProviderPick(
+  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");
+  const next = appendPickStringLiteralMember(original, "AppPorts", "billing");
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+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\.db\);)/,
+      `$1\n\t\tconst entitlements = createBillingEntitlements(repositories.billing);`,
+    );
+    if (withEntitlementsConst === next) {
+      throw new Error(
+        `Could not find createRepositories(dbPort.db) 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;
+}
+
+async function updateBillingTransactionPorts(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = path.join(infrastructureDir(config), "db/transaction-ports.ts");
+  const filePath = path.join(targetDir, file);
+  if (!(await fileExists(filePath))) return false;
+
+  const original = await readFile(filePath, "utf8");
+  if (/Pick<AppTransactionPorts,\s*["']billing["']>/.test(original)) {
+    return false;
+  }
+
+  const repositoryProperty = /repositories:\s*([^;\n]+);/.exec(original);
+  if (!repositoryProperty) {
+    throw new Error(
+      `Could not find repositories: ... in ${file}. Add billing to the transaction repository dependency manually, or restore the generated transaction ports file before running make payments.`,
+    );
+  }
+
+  const repositoryType = repositoryProperty[1]?.trim();
+  if (!repositoryType) {
+    throw new Error(
+      `Could not update repositories in ${file}. Add billing to the transaction repository dependency manually, or restore the generated transaction ports file before running make payments.`,
+    );
+  }
+
+  const next = original.replace(
+    repositoryProperty[0],
+    `repositories: ${repositoryType} & Pick<AppTransactionPorts, "billing">;`,
+  );
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+async function updateDatabaseResetTables(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = path.join(infrastructureDir(config), "db/reset.ts");
+  const filePath = path.join(targetDir, file);
+  if (!(await fileExists(filePath))) return false;
+
+  const original = await readFile(filePath, "utf8");
+  if (/["']billing_accounts["']/.test(original)) return false;
+
+  const tables = arrayInitializerInfo(original, "tables");
+  if (!tables) return false;
+
+  const nextArray = appendToArrayExpression(tables.text, [
+    '"billing_accounts"',
+  ]);
+  const next = `${original.slice(0, tables.start)}${nextArray}${original.slice(
+    tables.end,
+  )}`;
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
 async function updateInfrastructureDeferredPorts(
   targetDir: string,
   names: ResourceNames,
@@ -2816,6 +3205,137 @@ async function updateSharedErrors(
   return true;
 }
 
+async function updateBillingSharedErrors(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  options: { dryRun: boolean },
+): Promise<boolean> {
+  const file = resourceSharedErrorsPath(config);
+  const filePath = path.join(targetDir, file);
+  if (!(await fileExists(filePath))) return false;
+
+  const original = await readFile(filePath, "utf8");
+  const missingEntries = [
+    {
+      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},`,
+    },
+  ].filter(({ name }) => !new RegExp(`\\b${name}\\b`).test(original));
+
+  if (missingEntries.length === 0) return false;
+
+  const defineErrorsStart = original.indexOf("defineErrors(");
+  if (defineErrorsStart === -1) {
+    throw new Error(
+      `Could not find defineErrors({ in ${file}. Add BillingAccountNotFound and BillingCheckoutUnavailable manually, or restore the generated shared error catalog before running make payments.`,
+    );
+  }
+
+  const openBrace = original.indexOf("{", defineErrorsStart);
+  if (openBrace === -1) {
+    throw new Error(
+      `Could not find defineErrors({ in ${file}. Add BillingAccountNotFound and BillingCheckoutUnavailable manually, or restore the generated shared error catalog before running make payments.`,
+    );
+  }
+
+  const closeBrace = matchingDelimiterIndex(original, openBrace, "{", "}");
+  if (closeBrace === -1) {
+    throw new Error(
+      `Could not update ${file} because the error catalog object is malformed. Add BillingAccountNotFound and BillingCheckoutUnavailable manually, or restore the generated shared error catalog before running make payments.`,
+    );
+  }
+
+  const next = insertBeforeClosingBrace(
+    original,
+    openBrace,
+    closeBrace,
+    missingEntries.map(({ entry }) => entry).join("\n"),
+  );
+
+  if (next === original) return false;
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+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_TEAM_PRICE_ID to your env schema manually, or restore the generated env file before running make payments.`,
+    );
+  }
+  if (/\bBILLING_TEAM_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_TEAM_PRICE_ID: z.string().min(1).default("price_team_example") to the createEnv server block manually, or restore the generated env file before running make payments.`,
+    );
+  }
+
+  const entry = `\n${match[1]}BILLING_TEAM_PRICE_ID: z.string().min(1).default("price_team_example"),`;
+  const next = `${original.slice(0, match.index)}${entry}${original.slice(
+    match.index,
+  )}`;
+
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
+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_TEAM_PRICE_ID=/m.test(original)) return false;
+
+  const match = /\nLOG_LEVEL=/.exec(original);
+  const next = match
+    ? `${original.slice(0, match.index)}\nBILLING_TEAM_PRICE_ID=price_team_example${original.slice(
+        match.index,
+      )}`
+    : `${original.trimEnd()}\nBILLING_TEAM_PRICE_ID=price_team_example\n`;
+
+  if (!options.dryRun) await writeFile(filePath, next);
+  return true;
+}
+
 async function updateServerRoutes(
   targetDir: string,
   names: ResourceNames,
@@ -3169,6 +3689,30 @@ function appendUnionTypeMember(
   )}`;
 }
 
+function appendPickStringLiteralMember(
+  source: string,
+  typeName: string,
+  member: string,
+): string {
+  const match = new RegExp(`Pick<\\s*${typeName}\\s*,([\\s\\S]*?)>`).exec(
+    source,
+  );
+  if (!match) return source;
+
+  const literal = `"${member}"`;
+  if (match[1].includes(literal)) return source;
+
+  const union = match[1];
+  const indent = union.match(/\n([\t ]*)\|/)?.[1] ?? "\t";
+  const nextUnion = union.includes("\n")
+    ? `${union.replace(/\s*$/, "")}\n${indent}| ${literal}\n`
+    : `${union.trimEnd()} | ${literal}`;
+
+  return `${source.slice(0, match.index)}Pick<${typeName},${nextUnion}>${source.slice(
+    match.index + match[0].length,
+  )}`;
+}
+
 function appendTupleTypeMember(
   source: string,
   typeName: string,
@@ -4249,6 +4793,61 @@ function resourceFiles(
   return files;
 }
 
+function paymentsFiles(
+  config: ResolvedBeignetConfig,
+  database: DatabaseName,
+): GeneratedFile[] {
+  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: "app/api/webhooks/payments/route.ts",
+      content: billingWebhookRouteFile(),
+    },
+  ];
+}
+
 function featureUiComponentFiles(
   names: FeatureUiNames,
   config: ResolvedBeignetConfig,
@@ -6889,6 +7488,1230 @@ export const ${names.uploadExportName} = defineUpload<
 `;
 }
 
+function billingSchemasFile(): string {
+  return `import { z } from "zod";
+
+export const billingPlanSchema = z.enum(["team"]);
+
+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>;
+`;
+}
+
+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 = {
+\tteam: {
+\t\tid: "team",
+\t\tlabel: "Team",
+\t\tmode: "subscription",
+\t\tlineItems: [{ priceId: env.BILLING_TEAM_PRICE_ID, quantity: 1 }],
+\t\tentitlements: ["todos.create"],
+\t},
+} as const satisfies Record<BillingPlan, BillingPlanDefinition>;
+
+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);
+}
+`;
+}
+
+function billingEntitlementsFile(): string {
+  return `import {
+\tcreateEntitlements,
+\tdenyEntitlement,
+} from "@beignet/core/entitlements";
+import { billingPlanIncludesEntitlement } from "./pricing";
+import { isBillingAccountActive, type BillingRepository } from "./ports";
+
+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\tif (!isBillingAccountActive(account)) {
+\t\t\t\treturn denyEntitlement({
+\t\t\t\t\treason: "An active billing plan is required for this action.",
+\t\t\t\t\tcode: "BILLING_INACTIVE",
+\t\t\t\t\tdetails: {
+\t\t\t\t\t\tentitlement: input.entitlement,
+\t\t\t\t\t\tstatus: account?.status ?? "inactive",
+\t\t\t\t\t\tsubject: input.subject,
+\t\t\t\t\t},
+\t\t\t\t});
+\t\t\t}
+
+\t\t\tif (!billingPlanIncludesEntitlement(account.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: account.plan,
+\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});
+}
+`;
+}
+
+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";
+}
+`;
+}
+
+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,
+];
+`;
+}
+
+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 {
+\tconst plan = metadataValue(data, "plan");
+\treturn plan === "team" ? plan : "team";
+}
+
+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) {
+\treturn {
+\t\ttenantId,
+\t\tplan: account?.plan ?? "team",
+\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 ?? "team",
+\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}/billing?checkout=success\`,
+\t\t\tcancelUrl: \`\${env.APP_URL}/billing?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}/billing\`,
+\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});
+`;
+}
+
+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],
+});
+`;
+}
+
+function billingTestFile(config: ResolvedBeignetConfig): string {
+  return `import { describe, expect, it } from "bun:test";
+import { createUseCaseTester } from "@beignet/core/application";
+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: "team",
+\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_team_example", quantity: 1 }],
+\t\t\tclientReferenceId: "tenant_example",
+\t\t\tmetadata: {
+\t\t\t\ttenantId: "tenant_example",
+\t\t\t\tplan: "team",
+\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: "team",
+\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: "team",
+\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 billing 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: "team",
+\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"denies billing 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: "team",
+\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: "BILLING_INACTIVE",
+\t\t\t});
+\t\t},
+\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: "team",
+\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\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: "team",
+\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: "team",
+\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});
+});
+`;
+}
+
+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}),
+);
+`;
+}
+
+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};
+}
+`;
+}
+
+function billingWebhookRouteFile(): string {
+  return `import { createPaymentWebhookRoute } from "@beignet/next";
+import { handlePaymentWebhookUseCase } from "@/features/billing/use-cases";
+import { server } from "@/server";
+
+export const runtime = "nodejs";
+
+export const { POST } = createPaymentWebhookRoute({
+\tserver,
+\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},
+});
+`;
+}
+
 function featureUiComponentFile(
   names: FeatureUiNames,
   config: ResolvedBeignetConfig,
@@ -7042,7 +8865,7 @@ import {
 ${mode === "resource" ? `	delete${names.singularPascal}UseCase,\n	get${names.singularPascal}UseCase,\n` : ""}	list${names.pluralPascal}UseCase,
 ${mode === "resource" ? `	update${names.singularPascal}UseCase,\n` : ""}} from "${relativeModule(routeFilePath, useCasesPath)}";
 
-export const ${names.singularCamel}Routes = defineRouteGroup<AppContext>({
+export const ${names.singularCamel}Routes = defineRouteGroup<AppContext>()({
 	name: "${names.pluralKebab}",
 	routes: [
 		{ contract: list${names.pluralPascal}, useCase: list${names.pluralPascal}UseCase },