@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-payments/SKILL.md

@@ -0,0 +1,243 @@
+# Skill: Configure Payments
+
+Set up Stripe payments including checkout, subscriptions, and webhooks in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add payments, billing, subscriptions, Stripe, or checkout.
+
+## Prerequisites
+
+- A Stripe account at [stripe.com](https://stripe.com)
+- `appConfig.features.billing` set to `true`
+- `appConfig.services.payments.provider` set to `'stripe'`
+
+## Step 1: Install Stripe SDK
+
+```bash
+yarn add stripe
+```
+
+## Step 2: Environment Variables
+
+```bash
+STRIPE_SECRET_KEY="sk_test_..."
+STRIPE_WEBHOOK_SECRET="whsec_..."
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
+```
+
+## Step 3: Create the Stripe Service
+
+```typescript
+// src/features/billing/server/stripe.ts
+import 'server-only';
+
+import Stripe from 'stripe';
+
+let _stripe: Stripe | null = null;
+
+export function getStripe(): Stripe {
+  if (_stripe) return _stripe;
+
+  const secretKey = process.env.STRIPE_SECRET_KEY;
+  if (!secretKey) {
+    throw new Error(
+      'STRIPE_SECRET_KEY is not set.\n'
+      + '  → Get your key from https://dashboard.stripe.com/apikeys\n'
+      + '  → Add it to your .env file',
+    );
+  }
+
+  _stripe = new Stripe(secretKey, { apiVersion: '2024-12-18.acacia' });
+  return _stripe;
+}
+```
+
+## Step 4: Prisma Schema for Subscriptions
+
+```prisma
+// prisma/schema/billing.prisma
+model Subscription {
+  id                 String   @id @default(cuid())
+  userId             String   @unique
+  stripeCustomerId   String   @unique
+  stripeSubscriptionId String? @unique
+  stripePriceId      String?
+  status             String   @default("inactive")
+  currentPeriodEnd   DateTime?
+  cancelAtPeriodEnd  Boolean  @default(false)
+  createdAt          DateTime @default(now())
+  updatedAt          DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([stripeCustomerId])
+  @@index([status])
+}
+```
+
+## Step 5: Checkout API Route
+
+```typescript
+// src/app/api/protected/billing/checkout/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { getStripe } from '@/features/billing/server';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const checkoutSchema = z.object({
+  priceId: z.string().min(1),
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const { priceId } = checkoutSchema.parse(await request.json());
+    const stripe = getStripe();
+    const userId = request.session.userId;
+
+    // Find or create Stripe customer
+    let subscription = await prisma.subscription.findUnique({ where: { userId } });
+
+    if (!subscription) {
+      const customer = await stripe.customers.create({
+        email: request.session.email,
+        metadata: { userId },
+      });
+
+      subscription = await prisma.subscription.create({
+        data: { userId, stripeCustomerId: customer.id },
+      });
+    }
+
+    // Create checkout session
+    const session = await stripe.checkout.sessions.create({
+      customer: subscription.stripeCustomerId,
+      mode: 'subscription',
+      payment_method_types: ['card'],
+      line_items: [{ price: priceId, quantity: 1 }],
+      success_url: `${process.env.APP_URL || 'http://localhost:3000'}/billing?success=true`,
+      cancel_url: `${process.env.APP_URL || 'http://localhost:3000'}/billing?canceled=true`,
+      metadata: { userId },
+    });
+
+    return NextResponse.json({ url: session.url });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/billing/checkout' });
+  }
+});
+```
+
+## Step 6: Customer Portal Route
+
+```typescript
+// src/app/api/protected/billing/portal/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { prisma } from '@/lib/prisma';
+import { getStripe } from '@/features/billing/server';
+import { NextResponse } from 'next/server';
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const stripe = getStripe();
+    const subscription = await prisma.subscription.findUnique({
+      where: { userId: request.session.userId },
+    });
+
+    if (!subscription) {
+      return NextResponse.json({ error: 'No subscription found' }, { status: 404 });
+    }
+
+    const session = await stripe.billingPortal.sessions.create({
+      customer: subscription.stripeCustomerId,
+      return_url: `${process.env.APP_URL || 'http://localhost:3000'}/billing`,
+    });
+
+    return NextResponse.json({ url: session.url });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/billing/portal' });
+  }
+});
+```
+
+## Step 7: Stripe Webhook
+
+See the `add-webhook` skill for the full pattern. Key events to handle:
+
+```typescript
+switch (event.type) {
+  case 'checkout.session.completed': {
+    const session = event.data.object;
+    await prisma.subscription.update({
+      where: { stripeCustomerId: session.customer as string },
+      data: {
+        stripeSubscriptionId: session.subscription as string,
+        status: 'active',
+      },
+    });
+    break;
+  }
+  case 'customer.subscription.updated': {
+    const sub = event.data.object;
+    await prisma.subscription.update({
+      where: { stripeSubscriptionId: sub.id },
+      data: {
+        status: sub.status,
+        stripePriceId: sub.items.data[0]?.price.id,
+        currentPeriodEnd: new Date(sub.current_period_end * 1000),
+        cancelAtPeriodEnd: sub.cancel_at_period_end,
+      },
+    });
+    break;
+  }
+  case 'customer.subscription.deleted': {
+    const sub = event.data.object;
+    await prisma.subscription.update({
+      where: { stripeSubscriptionId: sub.id },
+      data: { status: 'canceled' },
+    });
+    break;
+  }
+}
+```
+
+## Step 8: Subscription Check Helper
+
+```typescript
+// src/features/billing/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+
+export async function getUserSubscription(userId: string) {
+  return prisma.subscription.findUnique({ where: { userId } });
+}
+
+export async function isSubscribed(userId: string): Promise<boolean> {
+  const sub = await getUserSubscription(userId);
+  return sub?.status === 'active' || sub?.status === 'trialing';
+}
+```
+
+## Local Development
+
+Test webhooks locally with Stripe CLI:
+
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+
+This prints a webhook signing secret -- use it as `STRIPE_WEBHOOK_SECRET`.
+
+## Checklist
+
+- [ ] Stripe SDK installed
+- [ ] Environment variables set (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`)
+- [ ] Lazy Stripe client created (`src/features/billing/server/stripe.ts`)
+- [ ] Subscription model in Prisma schema
+- [ ] Checkout session API route
+- [ ] Customer portal API route
+- [ ] Webhook handler for subscription events
+- [ ] Subscription check helper functions
+- [ ] Webhook excluded from CSRF in middleware
+- [ ] Feature flag checked (`appConfig.features.billing`)