create-crm-starter 0.1.0

package/template/extras/service-plans/_shared/src/lib/service-plans/types.ts

@@ -0,0 +1,57 @@
+export const BILLING_INTERVALS = ['monthly', 'quarterly', 'annual'] as const;
+export type BillingInterval = (typeof BILLING_INTERVALS)[number];
+
+export const BILLING_INTERVAL_LABEL: Record<BillingInterval, string> = {
+  monthly: 'Monthly',
+  quarterly: 'Quarterly',
+  annual: 'Annual',
+};
+
+export const SUBSCRIPTION_STATUSES = ['active', 'paused', 'cancelled'] as const;
+export type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+
+export const SUBSCRIPTION_STATUS_LABEL: Record<SubscriptionStatus, string> = {
+  active: 'Active',
+  paused: 'Paused',
+  cancelled: 'Cancelled',
+};
+
+export const SUBSCRIPTION_STATUS_VARIANT: Record<
+  SubscriptionStatus,
+  'default' | 'secondary' | 'destructive' | 'outline'
+> = {
+  active: 'default',
+  paused: 'secondary',
+  cancelled: 'destructive',
+};
+
+/**
+ * A plan template (silver/gold/platinum etc.) — defined once per business
+ * and assigned to customers as subscriptions.
+ */
+export interface ServicePlan {
+  id: string;
+  name: string;
+  description?: string;
+  /** Price billed per `billingInterval`, in cents. */
+  price: number;
+  billingInterval: BillingInterval;
+  /** How many service visits the customer receives per year. */
+  visitsPerYear: number;
+  perks?: string;
+  /** Computed: estimated annual revenue per subscriber based on interval. */
+  arrPerSubscriber: number;
+  activeSubscribers: number;
+  monthlyRecurringRevenue: number;
+}
+
+export interface ServicePlanSubscription {
+  id: string;
+  customerId: string;
+  customerName: string;
+  planId: string;
+  planName: string;
+  status: SubscriptionStatus;
+  startedAt: string;
+  renewsAt?: string;
+}

package/template/extras/service-plans/drizzle/src/app/(dashboard)/service-plans/new/page.tsx

@@ -0,0 +1,10 @@
+import { NewServicePlanForm } from '@/components/service-plans/new-plan-form';
+
+export default function NewServicePlanPage() {
+  return (
+    <div className="mx-auto max-w-2xl space-y-6">
+      <h1 className="text-3xl font-bold tracking-tight">New service plan</h1>
+      <NewServicePlanForm />
+    </div>
+  );
+}

package/template/extras/service-plans/drizzle/src/app/api/stripe/webhook/route.ts

@@ -0,0 +1,143 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import type Stripe from 'stripe';
+import { eq } from 'drizzle-orm';
+import { stripe } from '@/lib/stripe';
+import { recordInvoicePayment } from '@/lib/invoices/actions';
+import { db } from '@/db/client';
+import { servicePlanSubscriptions } from '@/db/schema';
+
+/**
+ * Stripe webhook with both invoice reconciliation AND service-plan
+ * subscription handling. service-plans module ships this as a wholesale
+ * override of the estimates-invoices version (which itself overrode the
+ * payments-stripe baseline). resolveInstallers order: payments-stripe →
+ * estimates-invoices → service-plans (last-wins).
+ *
+ * Set STRIPE_WEBHOOK_SECRET in .env.local. For local dev:
+ *   stripe listen --forward-to localhost:3000/api/stripe/webhook
+ */
+export async function POST(req: NextRequest) {
+  const secret = process.env.STRIPE_WEBHOOK_SECRET;
+  if (!secret) {
+    return NextResponse.json({ error: 'STRIPE_WEBHOOK_SECRET not set' }, { status: 500 });
+  }
+  const signature = req.headers.get('stripe-signature');
+  if (!signature) {
+    return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
+  }
+  const body = await req.text();
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, secret);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Signature verification failed';
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+
+  switch (event.type) {
+    case 'checkout.session.completed': {
+      const session = event.data.object as Stripe.Checkout.Session;
+
+      // Service-plan subscription Checkout → create the row in our DB.
+      if (session.mode === 'subscription' && session.metadata?.kind === 'service-plan-subscription') {
+        const customerId = session.metadata.customerId;
+        const planId = session.metadata.planId;
+        const stripeSubscriptionId =
+          typeof session.subscription === 'string' ? session.subscription : session.subscription?.id;
+        const stripeCustomerId =
+          typeof session.customer === 'string' ? session.customer : session.customer?.id;
+        if (!customerId || !planId || !stripeSubscriptionId) {
+          console.error('[stripe] subscription session missing metadata', session.id);
+          return NextResponse.json({ error: 'missing metadata' }, { status: 400 });
+        }
+        try {
+          // Idempotency: if we've already recorded this Stripe subscription,
+          // skip the insert.
+          const existing = await db
+            .select({ id: servicePlanSubscriptions.id })
+            .from(servicePlanSubscriptions)
+            .where(eq(servicePlanSubscriptions.stripeSubscriptionId, stripeSubscriptionId))
+            .limit(1);
+          if (existing.length === 0) {
+            // Renewal date = +1 of the billing interval. For simplicity we
+            // default to +1 year; Stripe's customer.subscription.updated
+            // event below will refine it from current_period_end.
+            const renewsAt = new Date();
+            renewsAt.setFullYear(renewsAt.getFullYear() + 1);
+            await db.insert(servicePlanSubscriptions).values({
+              customerId,
+              planId,
+              status: 'active',
+              stripeSubscriptionId,
+              stripeCustomerId: stripeCustomerId ?? null,
+              renewsAt,
+            });
+            console.log(`[stripe] subscribed customer ${customerId} to plan ${planId}`);
+          }
+        } catch (err) {
+          console.error('[stripe] subscription insert failed:', err);
+          return NextResponse.json({ error: 'subscription insert failed' }, { status: 500 });
+        }
+        break;
+      }
+
+      // Otherwise: invoice payment (handled by estimates-invoices logic).
+      const invoiceId = session.metadata?.invoiceId;
+      const amount = session.amount_total;
+      const paymentIntentId =
+        typeof session.payment_intent === 'string' ? session.payment_intent : null;
+      if (invoiceId && amount && amount > 0) {
+        try {
+          await recordInvoicePayment({
+            invoiceId,
+            amount,
+            method: 'stripe',
+            stripeSessionId: session.id,
+            stripePaymentIntentId: paymentIntentId ?? undefined,
+            note: 'Stripe Checkout',
+          });
+          console.log(`[stripe] reconciled invoice ${invoiceId} +${amount}¢`);
+        } catch (err) {
+          console.error(`[stripe] failed to record payment for invoice ${invoiceId}:`, err);
+          return NextResponse.json({ error: 'payment recording failed' }, { status: 500 });
+        }
+      } else {
+        console.log(
+          '[stripe] checkout.session.completed (no invoiceId metadata)',
+          session.id,
+          session.metadata,
+        );
+      }
+      break;
+    }
+    case 'customer.subscription.updated': {
+      const sub = event.data.object as Stripe.Subscription;
+      const renewsAt = sub.current_period_end ? new Date(sub.current_period_end * 1000) : null;
+      const status =
+        sub.status === 'active' || sub.status === 'trialing' ? 'active' :
+        sub.status === 'paused' ? 'paused' : 'cancelled';
+      await db
+        .update(servicePlanSubscriptions)
+        .set({ renewsAt, status, updatedAt: new Date() })
+        .where(eq(servicePlanSubscriptions.stripeSubscriptionId, sub.id));
+      break;
+    }
+    case 'customer.subscription.deleted': {
+      const sub = event.data.object as Stripe.Subscription;
+      await db
+        .update(servicePlanSubscriptions)
+        .set({ status: 'cancelled', cancelledAt: new Date(), updatedAt: new Date() })
+        .where(eq(servicePlanSubscriptions.stripeSubscriptionId, sub.id));
+      break;
+    }
+    case 'payment_intent.succeeded':
+    case 'payment_intent.payment_failed':
+    case 'invoice.paid':
+      break;
+    default:
+      break;
+  }
+
+  return NextResponse.json({ received: true });
+}

package/template/extras/service-plans/drizzle/src/components/service-plans/new-plan-form.tsx

@@ -0,0 +1,126 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { createServicePlan } from '@/lib/service-plans/actions';
+import {
+  BILLING_INTERVALS,
+  BILLING_INTERVAL_LABEL,
+  type BillingInterval,
+} from '@/lib/service-plans/types';
+
+export function NewServicePlanForm() {
+  const [pending, start] = useTransition();
+  const [error, setError] = useState<string | null>(null);
+
+  const [name, setName] = useState('');
+  const [description, setDescription] = useState('');
+  const [price, setPrice] = useState(2499);
+  const [billingInterval, setBillingInterval] = useState<BillingInterval>('monthly');
+  const [visitsPerYear, setVisitsPerYear] = useState(2);
+  const [perks, setPerks] = useState('');
+
+  function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    if (!name.trim()) { setError('Name is required.'); return; }
+    start(async () => {
+      try {
+        await createServicePlan({
+          name,
+          description: description || undefined,
+          price,
+          billingInterval,
+          visitsPerYear,
+          perks: perks || undefined,
+        });
+      } catch (err) {
+        setError((err as Error).message);
+      }
+    });
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>Plan basics</CardTitle>
+          <CardDescription>Name and what the customer gets.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="name">Name *</Label>
+            <Input id="name" required value={name} onChange={(e) => setName(e.target.value)} placeholder="e.g. Gold Plan" />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="description">Description</Label>
+            <Input id="description" value={description} onChange={(e) => setDescription(e.target.value)} placeholder="One-line summary of the plan" />
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Pricing & cadence</CardTitle>
+          <CardDescription>Prices in cents. e.g. 2499 = $24.99</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="price">Price (¢)</Label>
+              <Input id="price" type="number" min={0} value={price} onChange={(e) => setPrice(Number(e.target.value) || 0)} />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="billingInterval">Billing interval</Label>
+              <select
+                id="billingInterval"
+                value={billingInterval}
+                onChange={(e) => setBillingInterval(e.target.value as BillingInterval)}
+                className="border-input bg-background h-10 w-full rounded-md border px-3 text-sm"
+              >
+                {BILLING_INTERVALS.map((i) => (
+                  <option key={i} value={i}>{BILLING_INTERVAL_LABEL[i]}</option>
+                ))}
+              </select>
+            </div>
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="visitsPerYear">Visits per year</Label>
+            <Input id="visitsPerYear" type="number" min={0} value={visitsPerYear} onChange={(e) => setVisitsPerYear(Number(e.target.value) || 0)} />
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Perks</CardTitle>
+          <CardDescription>Separated by · (the · character renders as a bulleted list)</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <textarea
+            value={perks}
+            onChange={(e) => setPerks(e.target.value)}
+            rows={3}
+            placeholder="Annual tune-up · 15% off repairs · Priority booking"
+            className="border-input bg-background focus-visible:ring-ring flex w-full rounded-md border px-3 py-2 text-sm focus-visible:outline-none focus-visible:ring-2"
+          />
+        </CardContent>
+      </Card>
+
+      {error && <p className="text-destructive text-sm">{error}</p>}
+
+      <div className="flex justify-end gap-3">
+        <Button type="button" variant="outline" asChild>
+          <Link href="/service-plans">Cancel</Link>
+        </Button>
+        <Button type="submit" disabled={pending}>
+          {pending ? 'Creating…' : 'Create plan'}
+        </Button>
+      </div>
+    </form>
+  );
+}

package/template/extras/service-plans/drizzle/src/components/service-plans/subscribe-customer-form.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Label } from '@/components/ui/label';
+import { subscribeCustomerWithStripeCheckout, subscribeCustomerToPlan } from '@/lib/service-plans/actions';
+
+interface Props {
+  planId: string;
+  customers: { id: string; name: string }[];
+}
+
+export function SubscribeCustomerForm({ planId, customers }: Props) {
+  const [customerId, setCustomerId] = useState(customers[0]?.id ?? '');
+  const [pending, start] = useTransition();
+  const [error, setError] = useState<string | null>(null);
+  const [info, setInfo] = useState<string | null>(null);
+
+  function handleStripe() {
+    setError(null);
+    setInfo(null);
+    if (!customerId) { setError('Pick a customer.'); return; }
+    start(async () => {
+      try {
+        // Redirects to Stripe Checkout on success — no return.
+        await subscribeCustomerWithStripeCheckout(customerId, planId);
+      } catch (err) {
+        setError((err as Error).message);
+      }
+    });
+  }
+
+  function handleManual() {
+    setError(null);
+    setInfo(null);
+    if (!customerId) { setError('Pick a customer.'); return; }
+    if (!confirm('Subscribe without billing — record this subscription as paid offline?')) return;
+    start(async () => {
+      try {
+        await subscribeCustomerToPlan(customerId, planId);
+        setInfo('Subscription recorded.');
+      } catch (err) {
+        setError((err as Error).message);
+      }
+    });
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Subscribe a customer</CardTitle>
+        <CardDescription>
+          Bill via Stripe Checkout (recurring) — or record an offline subscription if the customer pays you directly.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <Label htmlFor="customer">Customer</Label>
+          {customers.length === 0 ? (
+            <p className="text-muted-foreground text-sm">No customers yet.</p>
+          ) : (
+            <select
+              id="customer"
+              value={customerId}
+              onChange={(e) => setCustomerId(e.target.value)}
+              className="border-input bg-background h-10 w-full rounded-md border px-3 text-sm"
+            >
+              {customers.map((c) => (
+                <option key={c.id} value={c.id}>{c.name}</option>
+              ))}
+            </select>
+          )}
+        </div>
+        {error && <p className="text-destructive text-sm">{error}</p>}
+        {info && <p className="text-emerald-600 text-sm">✓ {info}</p>}
+        <div className="flex flex-wrap items-center gap-3">
+          <Button onClick={handleStripe} disabled={pending || customers.length === 0}>
+            {pending ? 'Opening checkout…' : 'Subscribe via Stripe Checkout'}
+          </Button>
+          <Button onClick={handleManual} variant="outline" disabled={pending || customers.length === 0}>
+            Record offline subscription
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/template/extras/service-plans/drizzle/src/components/service-plans/subscribe-customer-section.tsx

@@ -0,0 +1,12 @@
+import { asc } from 'drizzle-orm';
+import { db } from '@/db/client';
+import { customers } from '@/db/schema';
+import { SubscribeCustomerForm } from './subscribe-customer-form';
+
+export async function SubscribeCustomerSection({ planId }: { planId: string }) {
+  const rows = await db
+    .select({ id: customers.id, name: customers.name })
+    .from(customers)
+    .orderBy(asc(customers.name));
+  return <SubscribeCustomerForm planId={planId} customers={rows} />;
+}

package/template/extras/service-plans/drizzle/src/db/schema/service-plans.ts

@@ -0,0 +1,46 @@
+import { integer, pgEnum, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { customers } from './customers';
+
+export const billingInterval = pgEnum('billing_interval', ['monthly', 'quarterly', 'annual']);
+export const subscriptionStatus = pgEnum('subscription_status', ['active', 'paused', 'cancelled']);
+
+export const servicePlans = pgTable('service_plans', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  description: text('description'),
+  /** Price billed per `billing_interval`, in cents. */
+  price: integer('price').notNull().default(0),
+  billingInterval: billingInterval('billing_interval').notNull().default('monthly'),
+  visitsPerYear: integer('visits_per_year').notNull().default(1),
+  perks: text('perks'),
+  /** Stripe Product ID — set on first Subscribe-customer call via
+   *  ensureStripePriceForPlan. Null until then. */
+  stripeProductId: text('stripe_product_id'),
+  /** Stripe Price ID — recurring price tied to billing_interval. */
+  stripePriceId: text('stripe_price_id'),
+  archivedAt: timestamp('archived_at'),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+});
+
+export const servicePlanSubscriptions = pgTable('service_plan_subscriptions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  customerId: uuid('customer_id').notNull().references(() => customers.id, { onDelete: 'cascade' }),
+  planId: uuid('plan_id').notNull().references(() => servicePlans.id, { onDelete: 'restrict' }),
+  status: subscriptionStatus('status').notNull().default('active'),
+  startedAt: timestamp('started_at').notNull().defaultNow(),
+  renewsAt: timestamp('renews_at'),
+  cancelledAt: timestamp('cancelled_at'),
+  notes: text('notes'),
+  /** Stripe Customer ID — created on first subscription via Checkout. */
+  stripeCustomerId: text('stripe_customer_id'),
+  /** Stripe Subscription ID — set by the webhook on checkout completion. */
+  stripeSubscriptionId: text('stripe_subscription_id').unique(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+});
+
+export type ServicePlanRow = typeof servicePlans.$inferSelect;
+export type NewServicePlanRow = typeof servicePlans.$inferInsert;
+export type SubscriptionRow = typeof servicePlanSubscriptions.$inferSelect;
+export type NewSubscriptionRow = typeof servicePlanSubscriptions.$inferInsert;

package/template/extras/service-plans/drizzle/src/lib/service-plans/actions.ts

@@ -0,0 +1,196 @@
+'use server';
+
+import { and, eq } from 'drizzle-orm';
+import { headers } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { revalidatePath } from 'next/cache';
+import { db } from '@/db/client';
+import { customers, servicePlans, servicePlanSubscriptions } from '@/db/schema';
+import { isStripeConfigured, stripe } from '@/lib/stripe';
+import type { BillingInterval, SubscriptionStatus } from './types';
+
+export interface CreateServicePlanInput {
+  name: string;
+  description?: string;
+  price: number; // cents
+  billingInterval: BillingInterval;
+  visitsPerYear: number;
+  perks?: string;
+}
+
+export async function createServicePlan(input: CreateServicePlanInput): Promise<void> {
+  if (!input.name.trim()) throw new Error('Name is required');
+  if (input.price < 0) throw new Error('Price must be ≥ 0');
+
+  const [row] = await db
+    .insert(servicePlans)
+    .values({
+      name: input.name.trim(),
+      description: input.description?.trim() || null,
+      price: input.price,
+      billingInterval: input.billingInterval,
+      visitsPerYear: input.visitsPerYear,
+      perks: input.perks?.trim() || null,
+    })
+    .returning({ id: servicePlans.id });
+
+  revalidatePath('/service-plans');
+  redirect(`/service-plans/${row.id}`);
+}
+
+/**
+ * Manual subscription — no Stripe billing. Used for cash/check plans or
+ * when the office records a subscription that was sold offline.
+ */
+export async function subscribeCustomerToPlan(
+  customerId: string,
+  planId: string,
+): Promise<string> {
+  if (!customerId || !planId) throw new Error('Customer and plan are required');
+  const renewsAt = new Date();
+  renewsAt.setFullYear(renewsAt.getFullYear() + 1);
+  const [row] = await db
+    .insert(servicePlanSubscriptions)
+    .values({
+      customerId,
+      planId,
+      status: 'active',
+      renewsAt,
+    })
+    .returning({ id: servicePlanSubscriptions.id });
+  revalidatePath('/service-plans');
+  revalidatePath(`/service-plans/${planId}`);
+  revalidatePath(`/customers/${customerId}`);
+  return row.id;
+}
+
+export async function setSubscriptionStatus(
+  subscriptionId: string,
+  status: SubscriptionStatus,
+): Promise<void> {
+  await db
+    .update(servicePlanSubscriptions)
+    .set({
+      status,
+      cancelledAt: status === 'cancelled' ? new Date() : null,
+      updatedAt: new Date(),
+    })
+    .where(eq(servicePlanSubscriptions.id, subscriptionId));
+  revalidatePath('/service-plans');
+}
+
+/**
+ * Idempotently ensures the given service plan has a Stripe Product + Price
+ * (recurring). Returns the price ID. Stripe Prices are immutable — if a
+ * plan's price/interval is edited later, this will create a NEW Price
+ * rather than mutate the old one (and you should update plan.stripePriceId).
+ */
+async function ensureStripePriceForPlan(planId: string): Promise<string> {
+  if (!isStripeConfigured) {
+    throw new Error('Stripe not configured. Set STRIPE_SECRET_KEY in .env.local.');
+  }
+  const [plan] = await db.select().from(servicePlans).where(eq(servicePlans.id, planId)).limit(1);
+  if (!plan) throw new Error('Plan not found');
+  if (plan.stripePriceId) return plan.stripePriceId;
+
+  const product = plan.stripeProductId
+    ? await stripe.products.retrieve(plan.stripeProductId)
+    : await stripe.products.create({
+        name: plan.name,
+        description: plan.description ?? undefined,
+        metadata: { fielderlyPlanId: plan.id },
+      });
+
+  const intervalMap: Record<BillingInterval, 'month' | 'year'> = {
+    monthly: 'month',
+    quarterly: 'month', // Stripe doesn't have 'quarter' — use month × 3
+    annual: 'year',
+  };
+  const intervalCount = plan.billingInterval === 'quarterly' ? 3 : 1;
+
+  const price = await stripe.prices.create({
+    product: product.id,
+    currency: 'usd',
+    unit_amount: plan.price,
+    recurring: {
+      interval: intervalMap[plan.billingInterval as BillingInterval],
+      interval_count: intervalCount,
+    },
+    metadata: { fielderlyPlanId: plan.id },
+  });
+
+  await db
+    .update(servicePlans)
+    .set({ stripeProductId: product.id, stripePriceId: price.id, updatedAt: new Date() })
+    .where(eq(servicePlans.id, plan.id));
+
+  return price.id;
+}
+
+/**
+ * Server action — initiates a Stripe Checkout session in subscription
+ * mode for the given customer + plan. On successful payment the webhook
+ * inserts the servicePlanSubscriptions row with the resulting Stripe
+ * subscription ID and customer ID.
+ */
+export async function subscribeCustomerWithStripeCheckout(
+  customerId: string,
+  planId: string,
+): Promise<void> {
+  if (!customerId || !planId) throw new Error('Customer and plan required');
+  if (!isStripeConfigured) {
+    throw new Error('Stripe not configured. Set STRIPE_SECRET_KEY in .env.local.');
+  }
+
+  // Make sure we haven't already subscribed this customer to this plan.
+  const existing = await db
+    .select({ id: servicePlanSubscriptions.id })
+    .from(servicePlanSubscriptions)
+    .where(
+      and(
+        eq(servicePlanSubscriptions.customerId, customerId),
+        eq(servicePlanSubscriptions.planId, planId),
+        eq(servicePlanSubscriptions.status, 'active'),
+      ),
+    )
+    .limit(1);
+  if (existing.length > 0) {
+    throw new Error('Customer is already actively subscribed to this plan.');
+  }
+
+  const priceId = await ensureStripePriceForPlan(planId);
+  const [customer] = await db
+    .select({ id: customers.id, name: customers.name, emails: customers.emails })
+    .from(customers)
+    .where(eq(customers.id, customerId))
+    .limit(1);
+  if (!customer) throw new Error('Customer not found');
+  const email = Array.isArray(customer.emails) ? customer.emails[0] : undefined;
+
+  const h = await headers();
+  const host = h.get('host') ?? 'localhost:3000';
+  const proto = h.get('x-forwarded-proto') ?? (host.startsWith('localhost') ? 'http' : 'https');
+  const origin = `${proto}://${host}`;
+
+  const session = await stripe.checkout.sessions.create({
+    mode: 'subscription',
+    customer_email: email,
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${origin}/service-plans/${planId}?subscribed=true`,
+    cancel_url: `${origin}/service-plans/${planId}?cancelled=true`,
+    metadata: {
+      planId,
+      customerId,
+      kind: 'service-plan-subscription',
+    },
+    subscription_data: {
+      metadata: {
+        planId,
+        customerId,
+      },
+    },
+  });
+
+  if (!session.url) throw new Error('Stripe did not return a checkout URL');
+  redirect(session.url);
+}