@clubedge/create-clubedge-app 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.12.0
+
+- Default to Starter `v0.11.0`, which adds payments (`--payments stripe`): Stripe Checkout, the customer portal, and verified webhooks behind a provider-neutral payments interface. `--payments` needs no CLI code: it comes from the Starter's manifest.
+- Test a payments project in CI and in the release smoke test, and add the payments module in the change-modules job.
+
 ## 0.11.0
 
 - Default to Starter `v0.10.0`, which adds the deploy module (`--deploy docker|fly|railway|render|vercel|netlify`), a migrator in the production image, a manual deploy workflow, and the `/api/ready` readiness endpoint. `--deploy` needs no CLI code: it comes from the Starter's manifest.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.11.0
+create-clubedge-app v0.12.0
         |
         v
-Clubedge Starter v0.10.0
-commit 9d8fec71b3851c2d615735fb37edb6bb0e568761
+Clubedge Starter v0.11.0
+commit b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.11.0` | `clubedge-starter@v0.10.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.12.0` | `clubedge-starter@v0.11.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.10.0` tag is expected to resolve to commit
-`9d8fec71b3851c2d615735fb37edb6bb0e568761`. The CLI verifies this before
+The `v0.11.0` tag is expected to resolve to commit
+`b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.10.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.11.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -85,7 +85,7 @@ Either way, the app lives in `apps/web` and uses the same shared packages, so th
 
 ### Choosing services
 
-Authentication, file storage, caching, email, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
+Authentication, file storage, caching, email, payments, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -93,6 +93,7 @@ Authentication, file storage, caching, email, local infrastructure, and deployme
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
+| `--payments` | `stripe`, `none` (needs an auth module) | `none` |
 | `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
@@ -138,7 +139,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.10.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.11.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -155,7 +156,7 @@ pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add aut
 pnpm dlx @clubedge/create-clubedge-app remove storage
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.10.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.11.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -206,7 +207,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.10.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.11.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.10.0",
-    "starterCommit": "9d8fec71b3851c2d615735fb37edb6bb0e568761"
+    "starterRef": "v0.11.0",
+    "starterCommit": "b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -51,6 +51,15 @@ RESEND_API_KEY=
 EMAIL_FROM=App <no-reply@example.com>
 # clubedge:end
 
+# clubedge:if payments=stripe
+# Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
+# webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+# The Stripe price for each plan in src/config/plans.ts (STRIPE_PRICE_<PLAN>).
+STRIPE_PRICE_PRO=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/README.md

@@ -27,6 +27,7 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
 - Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
 - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
+- Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
 - Zod environment validation, security headers, structured errors, and `/api/health`.
 - Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
 - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release.
@@ -221,6 +222,8 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/email/`: `EmailProvider` interface with console and in-memory providers <!-- clubedge:only email!=none -->
 - `packages/email-smtp/`: SMTP email provider <!-- clubedge:only email=smtp -->
 - `packages/email-resend/`: Resend email provider <!-- clubedge:only email=resend -->
+- `packages/payments/`: `PaymentProvider` interface, billing logic, and the subscription tables <!-- clubedge:only payments!=none -->
+- `packages/payments-stripe/`: Stripe payment provider <!-- clubedge:only payments=stripe -->
 - `packages/ui/`: shared shadcn/ui components, utilities, and global theme styles
 - `.github/`: CI workflow, issue forms, and pull request template
 - `SETUP.md`, `CONTRIBUTING.md`, `SECURITY.md`: setup, contribution, and security guides

package/template/SETUP.md

@@ -45,6 +45,7 @@ The variables are:
 - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
 - `SMTP_URL` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=resend -->
+- `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_PRICE_<PLAN>` (for payments): see [Payments](#payments). <!-- clubedge:only payments=stripe -->
 - `STORAGE_*` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=supabase -->
 
@@ -208,6 +209,33 @@ Set `RESEND_API_KEY` to a [Resend](https://resend.com) API key and `EMAIL_FROM`
 
 Without a provider configured, development prints each email to the server log, so you can open links from the terminal, and production refuses to send. `pnpm check:services` confirms that the provider accepts the settings without sending anything.
 
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+## Payments
+
+The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's own ids. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management. Server code reads a user's plan with `getBilling().subscriptionFor(userId)` and `isEntitled` from `@/server/payments`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if payments=stripe -->
+
+[Stripe](https://stripe.com) runs checkout and billing management. In test mode:
+
+1. Copy the secret key from the dashboard's API keys into `STRIPE_SECRET_KEY`.
+2. Create a recurring price for each plan and put its id in `STRIPE_PRICE_<PLAN>`, such as `STRIPE_PRICE_PRO`.
+3. Forward webhooks to your machine with the [Stripe CLI](https://docs.stripe.com/stripe-cli), and put the signing secret it prints in `STRIPE_WEBHOOK_SECRET`:
+
+```sh
+stripe listen --forward-to localhost:3000/api/webhooks/payments
+```
+
+Turn on the customer portal in the dashboard's billing settings, so "Manage billing" works. In production, add a webhook endpoint for `https://<your-domain>/api/webhooks/payments` with the events `checkout.session.completed` and `customer.subscription.created`, `.updated`, `.deleted`, `.paused`, and `.resumed`, and use its signing secret. Every webhook's signature is verified, each event is applied once, and subscription events read the subscription's current state from Stripe, so retried or out-of-order deliveries are safe.
+
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/web/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same.
+
 <!-- clubedge:end -->
 <!-- clubedge:if storage!=none -->
 
@@ -341,6 +369,7 @@ Production needs these variables:
 - `BETTER_AUTH_SECRET`, at least 32 random characters, different from development. <!-- clubedge:only auth=better-auth -->
 - `SMTP_URL` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=resend -->
+- `STRIPE_SECRET_KEY` (live mode), `STRIPE_WEBHOOK_SECRET` from the production webhook endpoint, and `STRIPE_PRICE_<PLAN>` for each plan. <!-- clubedge:only payments=stripe -->
 - `REDIS_URL`, when you run more than one instance. <!-- clubedge:only cache=redis -->
 - The `STORAGE_*` variables for your S3-compatible bucket. <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET`. <!-- clubedge:only storage=supabase -->

package/template/apps/start/.env.example

@@ -53,6 +53,15 @@ RESEND_API_KEY=
 EMAIL_FROM=App <no-reply@example.com>
 # clubedge:end
 
+# clubedge:if payments=stripe
+# Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
+# webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+# The Stripe price for each plan in src/config/plans.ts (STRIPE_PRICE_<PLAN>).
+STRIPE_PRICE_PRO=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,8 @@
     "@clubedge/email": "workspace:*",
     "@clubedge/email-resend": "workspace:*",
     "@clubedge/email-smtp": "workspace:*",
+    "@clubedge/payments": "workspace:*",
+    "@clubedge/payments-stripe": "workspace:*",
     "@clubedge/storage": "workspace:*",
     "@clubedge/storage-s3": "workspace:*",
     "@clubedge/storage-supabase": "workspace:*",

package/template/apps/start/scripts/check-services.ts

@@ -14,6 +14,9 @@ import { createSmtpEmail } from "@clubedge/email-smtp";
 // clubedge:if email=resend
 import { createResendEmail } from "@clubedge/email-resend";
 // clubedge:end
+// clubedge:if payments=stripe
+import { createStripePayments } from "@clubedge/payments-stripe";
+// clubedge:end
 // clubedge:if storage=s3 && infra=local
 import { createFileSystemStorage } from "@clubedge/storage/file-system";
 // clubedge:end
@@ -100,6 +103,23 @@ async function main() {
       },
     },
     // clubedge:end
+    // clubedge:if payments=stripe
+    {
+      name: "Payments (Stripe)",
+      skip: env.STRIPE_SECRET_KEY ? undefined : "STRIPE_SECRET_KEY is not set",
+      async run() {
+        // A read-only request that checks the key; nothing is charged or created.
+        const stripe = createStripePayments({
+          secretKey: env.STRIPE_SECRET_KEY!,
+          webhookSecret: env.STRIPE_WEBHOOK_SECRET || "unused",
+          prices: {},
+          apiBase: env.STRIPE_API_BASE || undefined,
+        });
+        await stripe.verify();
+        return "secret key accepted";
+      },
+    },
+    // clubedge:end
     // clubedge:if storage=s3 && infra=local
     {
       name: "Local folder storage",

package/template/apps/start/src/components/billing/billing-card.tsx

@@ -0,0 +1,83 @@
+import { CreditCard } from "lucide-react";
+
+import { plans } from "@/config/plans";
+import type { BillingStatus } from "@/server/billing.functions";
+import { Badge } from "@clubedge/ui/components/badge";
+import { Button } from "@clubedge/ui/components/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@clubedge/ui/components/card";
+
+const dateFormat = new Intl.DateTimeFormat("en", { dateStyle: "medium", timeZone: "UTC" });
+
+/** The signed-in user's plan, with checkout or the billing portal. Forms post to /billing/*. */
+export function BillingCard({ billing }: { billing: BillingStatus }) {
+  const { subscription } = billing;
+
+  return (
+    <Card className="gap-0 py-0" id="billing">
+      <CardHeader className="flex-row items-start justify-between gap-3 border-b px-5 py-5 sm:px-6">
+        <div className="grid gap-1">
+          <CardTitle className="text-base">Billing</CardTitle>
+          <CardDescription>Your plan and payment details.</CardDescription>
+        </div>
+        <span className="grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
+          <CreditCard aria-hidden="true" className="size-4" />
+        </span>
+      </CardHeader>
+      <CardContent className="grid gap-4 px-5 py-5 sm:px-6">
+        {!billing.configured ? (
+          <p className="text-sm text-muted-foreground">
+            Payments are not configured yet. Set the Stripe variables in{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
+              apps/web/.env.local
+            </code>
+            .
+          </p>
+        ) : !billing.signedIn ? (
+          <p className="text-sm text-muted-foreground">Sign in to choose a plan.</p>
+        ) : subscription ? (
+          <>
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-medium">{subscription.planName}</span>
+              <Badge variant={subscription.entitled ? "default" : "secondary"}>
+                {subscription.status.replace(/_/g, " ")}
+              </Badge>
+            </div>
+            {subscription.currentPeriodEnd && (
+              <p className="text-sm text-muted-foreground">
+                {subscription.cancelAtPeriodEnd ? "Ends" : "Renews"} on{" "}
+                {dateFormat.format(new Date(subscription.currentPeriodEnd))}.
+              </p>
+            )}
+            <form action="/billing/portal" method="post">
+              <Button type="submit" variant="outline">
+                Manage billing
+              </Button>
+            </form>
+          </>
+        ) : (
+          plans.map((plan) => (
+            <form
+              action="/billing/checkout"
+              className="flex flex-wrap items-center justify-between gap-3"
+              key={plan.id}
+              method="post"
+            >
+              <input name="planId" type="hidden" value={plan.id} />
+              <div className="grid gap-0.5">
+                <span className="font-medium">{plan.name}</span>
+                <span className="text-sm text-muted-foreground">{plan.description}</span>
+              </div>
+              <Button type="submit">Upgrade to {plan.name}</Button>
+            </form>
+          ))
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/template/apps/start/src/config/plans.ts

@@ -0,0 +1,16 @@
+/**
+ * The plans users can subscribe to. Ids are the app's own: each payment provider maps them to
+ * its prices through environment variables, such as STRIPE_PRICE_PRO for the "pro" plan.
+ */
+export const plans = [
+  {
+    id: "pro",
+    name: "Pro",
+    description: "Everything in the free plan, plus the paid features you build.",
+  },
+] as const;
+
+export type PlanId = (typeof plans)[number]["id"];
+
+export const planName = (id: string | null) =>
+  plans.find((plan) => plan.id === id)?.name ?? "Unknown plan";

package/template/apps/start/src/routes/api/webhooks/payments.ts

@@ -0,0 +1,31 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { getBilling, isPaymentsConfigured, WebhookVerificationError } from "@/server/payments";
+
+/**
+ * The payment provider's webhook. The body is read as raw text, because the signature covers
+ * the exact bytes. Each event is applied once; failures answer 500 so the provider retries.
+ */
+export const Route = createFileRoute("/api/webhooks/payments")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        if (!isPaymentsConfigured()) {
+          return Response.json({ error: "Payments are not configured." }, { status: 503 });
+        }
+        try {
+          const result = await getBilling().handleWebhook({
+            body: await request.text(),
+            headers: request.headers,
+          });
+          return Response.json({ received: true, result });
+        } catch (error) {
+          if (error instanceof WebhookVerificationError) {
+            return Response.json({ error: "Invalid signature." }, { status: 400 });
+          }
+          console.error("Payment webhook failed", error);
+          return Response.json({ error: "Webhook failed." }, { status: 500 });
+        }
+      },
+    },
+  },
+});

package/template/apps/start/src/routes/billing/checkout.ts

@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handleCheckout } from "@/server/billing-forms";
+
+export const Route = createFileRoute("/billing/checkout")({
+  server: {
+    handlers: {
+      GET: () => new Response(null, { status: 303, headers: { Location: "/dashboard" } }),
+      POST: ({ request }) => handleCheckout(request),
+    },
+  },
+});

package/template/apps/start/src/routes/billing/portal.ts

@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handlePortal } from "@/server/billing-forms";
+
+export const Route = createFileRoute("/billing/portal")({
+  server: {
+    handlers: {
+      GET: () => new Response(null, { status: 303, headers: { Location: "/dashboard" } }),
+      POST: () => handlePortal(),
+    },
+  },
+});

package/template/apps/start/src/routes/dashboard.tsx

@@ -47,6 +47,10 @@ import {
 import { SidebarInset, SidebarProvider, SidebarTrigger } from "@clubedge/ui/components/sidebar";
 import { siteConfig } from "@/config/site";
 import { getPageUser } from "@/server/auth.functions";
+// clubedge:if payments!=none
+import { BillingCard } from "@/components/billing/billing-card";
+import { getBillingStatus } from "@/server/billing.functions";
+// clubedge:end
 import { AccountButton } from "@/components/dashboard/account-button";
 import { AppSidebar } from "@/components/dashboard/app-sidebar";
 import { ThemeToggle } from "@/components/theme/theme-toggle";
@@ -107,12 +111,18 @@ const setupRows = [
 ];
 
 export const Route = createFileRoute("/dashboard")({
-  loader: () => getPageUser({ data: { pathname: "/dashboard" } }),
+  loader: async () => ({
+    user: await getPageUser({ data: { pathname: "/dashboard" } }),
+    // clubedge:if payments!=none
+    billing: await getBillingStatus(),
+    // clubedge:end
+  }),
   component: DashboardPage,
 });
 
 function DashboardPage() {
-  const user = Route.useLoaderData();
+  const data = Route.useLoaderData();
+  const user = data.user;
 
   return (
     <SidebarProvider defaultOpen>
@@ -243,6 +253,10 @@ function DashboardPage() {
             </Card>
           </section>
 
+          {/* clubedge:if payments!=none */}
+          <BillingCard billing={data.billing} />
+          {/* clubedge:end */}
+
           <section className="grid gap-6 xl:grid-cols-[1.1fr_0.9fr]" id="modules">
             <Card className="gap-0 py-0">
               <CardHeader className="flex-row items-start justify-between gap-3 border-b px-5 py-5 sm:px-6">

package/template/apps/start/src/server/billing-forms.ts

@@ -0,0 +1,50 @@
+import "@tanstack/react-start/server-only";
+import { plans } from "@/config/plans";
+import { getAppUrl } from "@/env/server";
+import { loginUrl } from "@/lib/login-url";
+import { getCurrentUser, isAuthConfigured } from "./auth";
+import { getBilling, isPaymentsConfigured, NoBillingAccountError } from "./payments";
+import { getUserProfileId } from "./users";
+
+// Form endpoints for the billing card. They answer with 303 redirects to the provider's hosted
+// pages, the same way the Next.js server actions do.
+
+function seeOther(location: string): Response {
+  return new Response(null, { status: 303, headers: { Location: location } });
+}
+
+const appUrl = (path: string) => new URL(path, getAppUrl()).toString();
+
+async function signedInProfile() {
+  const user = isAuthConfigured() ? await getCurrentUser() : null;
+  if (!user?.email) return null;
+  return { id: await getUserProfileId({ ...user, email: user.email }), email: user.email };
+}
+
+export async function handleCheckout(request: Request): Promise<Response> {
+  const formData = await request.formData();
+  const plan = plans.find((candidate) => candidate.id === formData.get("planId"));
+  if (!plan || !isPaymentsConfigured()) return seeOther("/dashboard");
+  const user = await signedInProfile();
+  if (!user) return seeOther(loginUrl({ next: "/dashboard" }));
+  const { url } = await getBilling().checkout({
+    user,
+    planId: plan.id,
+    successUrl: appUrl("/dashboard?billing=success"),
+    cancelUrl: appUrl("/dashboard"),
+  });
+  return seeOther(url);
+}
+
+export async function handlePortal(): Promise<Response> {
+  if (!isPaymentsConfigured()) return seeOther("/dashboard");
+  const user = await signedInProfile();
+  if (!user) return seeOther(loginUrl({ next: "/dashboard" }));
+  try {
+    const { url } = await getBilling().portal({ userId: user.id, returnUrl: appUrl("/dashboard") });
+    return seeOther(url);
+  } catch (error) {
+    if (error instanceof NoBillingAccountError) return seeOther("/dashboard");
+    throw error;
+  }
+}

package/template/apps/start/src/server/billing.functions.ts

@@ -0,0 +1,29 @@
+import { createServerFn } from "@tanstack/react-start";
+import { planName } from "@/config/plans";
+import { getCurrentUser, isAuthConfigured } from "./auth";
+import { getBilling, isEntitled, isPaymentsConfigured } from "./payments";
+import { getUserProfileId } from "./users";
+
+/** What the dashboard's billing card shows; serializable, so it can cross to the browser. */
+export const getBillingStatus = createServerFn({ method: "GET" }).handler(async () => {
+  const configured = isPaymentsConfigured();
+  const user = isAuthConfigured() ? await getCurrentUser() : null;
+  if (!configured || !user?.email)
+    return { configured, signedIn: Boolean(user), subscription: null };
+  const subscription = await getBilling().subscriptionFor(
+    await getUserProfileId({ ...user, email: user.email }),
+  );
+  return {
+    configured,
+    signedIn: true,
+    subscription: subscription && {
+      planName: planName(subscription.planId),
+      status: subscription.status,
+      entitled: isEntitled(subscription),
+      currentPeriodEnd: subscription.currentPeriodEnd?.toISOString() ?? null,
+      cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
+    },
+  };
+});
+
+export type BillingStatus = Awaited<ReturnType<typeof getBillingStatus>>;

package/template/apps/start/src/server/payments.ts

@@ -0,0 +1,60 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import { createBilling, type Billing } from "@clubedge/payments";
+import { createStripePayments } from "@clubedge/payments-stripe";
+import { plans } from "@/config/plans";
+import { optional, parseEnv } from "@/env/server";
+import { getDb } from "@/server/db";
+
+export { isEntitled, NoBillingAccountError, WebhookVerificationError } from "@clubedge/payments";
+
+// Stripe behind the provider-neutral PaymentProvider; the rest of the app only uses Billing.
+const paymentsEnvSchema = z.object({
+  STRIPE_SECRET_KEY: optional(z.string()),
+  STRIPE_WEBHOOK_SECRET: optional(z.string()),
+  // For tests and stripe-mock: send API requests to another server.
+  STRIPE_API_BASE: optional(z.url()),
+});
+
+/** Each plan's Stripe price, from STRIPE_PRICE_<PLAN>, such as STRIPE_PRICE_PRO. */
+function prices(): Record<string, string> {
+  return Object.fromEntries(
+    plans.flatMap((plan) => {
+      const price = process.env[`STRIPE_PRICE_${plan.id.toUpperCase().replace(/-/g, "_")}`];
+      return price ? [[plan.id, price]] : [];
+    }),
+  );
+}
+
+function paymentsEnv() {
+  const env = parseEnv(paymentsEnvSchema, "Payments");
+  if (!env.STRIPE_SECRET_KEY || !env.STRIPE_WEBHOOK_SECRET) return null;
+  return { ...env, secretKey: env.STRIPE_SECRET_KEY, webhookSecret: env.STRIPE_WEBHOOK_SECRET };
+}
+
+/** Whether checkout and webhooks can work: the Stripe keys are set. */
+export function isPaymentsConfigured(): boolean {
+  return paymentsEnv() !== null;
+}
+
+let billing: Billing | undefined;
+
+/** One Billing per process. Throws while payments are not configured. */
+export function getBilling(): Billing {
+  if (billing) return billing;
+  const env = paymentsEnv();
+  if (!env)
+    throw new Error(
+      "Payments are not configured: set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.",
+    );
+  billing = createBilling({
+    db: getDb(),
+    provider: createStripePayments({
+      secretKey: env.secretKey,
+      webhookSecret: env.webhookSecret,
+      prices: prices(),
+      apiBase: env.STRIPE_API_BASE,
+    }),
+  });
+  return billing;
+}

package/template/apps/start/src/server/users.ts

@@ -1,6 +1,6 @@
 import "@tanstack/react-start/server-only";
 import type { AuthUser } from "@clubedge/auth";
-import { upsertUserProfile } from "@clubedge/db";
+import { ensureUserId, upsertUserProfile } from "@clubedge/db";
 import { getDb } from "./db";
 
 /**
@@ -15,3 +15,8 @@ export async function ensureUserProfile(user: AuthUser | null): Promise<void> {
     console.error("Could not sync the user profile", error);
   }
 }
+
+/** The app-owned users row id for a signed-in user, creating the row if needed. */
+export async function getUserProfileId(user: AuthUser & { email: string }): Promise<string> {
+  return ensureUserId(getDb(), { authUserId: user.id, email: user.email });
+}

package/template/apps/start/src/start.ts

@@ -12,8 +12,10 @@ const securityHeaders: Record<string, string> = {
 const safeMethods = new Set(["GET", "HEAD", "OPTIONS"]);
 
 // Rejects cross-site form posts and server function calls (Next.js does this for actions).
+// Webhooks are cross-site by design; their handlers verify the sender's signature instead.
 const csrfProtection = createCsrfMiddleware({
-  filter: ({ request }) => !safeMethods.has(request.method),
+  filter: ({ request }) =>
+    !safeMethods.has(request.method) && !new URL(request.url).pathname.startsWith("/api/webhooks/"),
 });
 
 // Refreshed cookies reach both later handlers in this request and the browser response.