elsabro 2.0.1 → 2.2.0

package/skills/saas-starter.md

@@ -0,0 +1,639 @@
+---
+name: saas-starter
+description: Template SaaS completo con pagos Stripe, subscripciones, dashboard de usuario y panel de admin. Basado en full-stack-app con features adicionales de monetizacion.
+tags: [saas, stripe, subscriptions, payments, dashboard, admin, nextjs, prisma]
+difficulty: advanced
+estimated_time: 60min
+extends: full-stack-app
+---
+
+# Skill: SaaS Starter
+
+<when_to_use>
+Usar cuando el usuario menciona:
+- "crear SaaS"
+- "app con pagos"
+- "subscripciones"
+- "Stripe"
+- "monetizar app"
+- "dashboard con billing"
+</when_to_use>
+
+<pre_requisites>
+## Pre-requisitos
+
+- Todo lo de full-stack-app
+- Cuenta de Stripe (test mode)
+- Stripe CLI instalado
+</pre_requisites>
+
+<additional_structure>
+## Estructura Adicional (sobre full-stack-app)
+
+```
+my-saas/
+├── src/
+│   ├── app/
+│   │   ├── (dashboard)/
+│   │   │   ├── billing/page.tsx       # Gestion de subscripcion
+│   │   │   └── settings/page.tsx      # Configuracion de cuenta
+│   │   ├── (admin)/
+│   │   │   ├── layout.tsx             # Layout admin
+│   │   │   ├── page.tsx               # Dashboard admin
+│   │   │   └── users/page.tsx         # Gestion de usuarios
+│   │   ├── api/
+│   │   │   ├── stripe/
+│   │   │   │   └── webhook/route.ts   # Webhooks de Stripe
+│   │   │   └── admin/
+│   │   │       └── users/route.ts
+│   │   └── pricing/page.tsx           # Pagina de precios
+│   ├── lib/
+│   │   └── stripe.ts                  # Cliente Stripe
+│   └── actions/
+│       └── billing.ts                 # Server Actions para billing
+├── prisma/
+│   └── schema.prisma                  # + Subscription, Price models
+└── stripe/
+    └── fixtures/                      # Productos y precios de prueba
+```
+</additional_structure>
+
+<setup_steps>
+## Pasos de Setup
+
+### Paso 1: Completar full-stack-app primero
+
+Ejecutar todos los pasos de `/elsabro:skill full-stack-app` primero.
+
+### Paso 2: Instalar dependencias de Stripe
+
+```bash
+npm install stripe @stripe/stripe-js
+```
+
+### Paso 3: Configurar variables de Stripe
+
+Agregar a `.env.local`:
+
+```env
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_PRICE_ID_BASIC=price_...
+STRIPE_PRICE_ID_PRO=price_...
+```
+
+### Paso 4: Actualizar schema de Prisma
+
+Agregar a `prisma/schema.prisma`:
+
+```prisma
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String    @unique
+  emailVerified DateTime?
+  password      String?
+  image         String?
+  accounts      Account[]
+  sessions      Session[]
+
+  // Stripe fields
+  stripeCustomerId String?   @unique
+  subscription     Subscription?
+
+  // Admin
+  role          Role      @default(USER)
+
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+
+model Subscription {
+  id                   String   @id @default(cuid())
+  userId               String   @unique
+  user                 User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  stripeSubscriptionId String   @unique
+  stripePriceId        String
+  stripeCurrentPeriodEnd DateTime
+  status               SubscriptionStatus
+
+  createdAt            DateTime @default(now())
+  updatedAt            DateTime @updatedAt
+}
+
+enum SubscriptionStatus {
+  ACTIVE
+  CANCELED
+  PAST_DUE
+  UNPAID
+  TRIALING
+}
+```
+
+### Paso 5: Crear cliente de Stripe
+
+Crear `src/lib/stripe.ts`:
+
+```typescript
+import Stripe from "stripe";
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: "2024-12-18.acacia",
+  typescript: true,
+});
+
+export const PLANS = {
+  basic: {
+    name: "Basic",
+    priceId: process.env.STRIPE_PRICE_ID_BASIC!,
+    price: 9,
+    features: ["5 proyectos", "1GB almacenamiento", "Soporte email"],
+  },
+  pro: {
+    name: "Pro",
+    priceId: process.env.STRIPE_PRICE_ID_PRO!,
+    price: 29,
+    features: ["Proyectos ilimitados", "10GB almacenamiento", "Soporte prioritario", "API access"],
+  },
+};
+
+export async function createCheckoutSession(
+  userId: string,
+  priceId: string,
+  email: string
+) {
+  const session = await stripe.checkout.sessions.create({
+    mode: "subscription",
+    payment_method_types: ["card"],
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${process.env.NEXTAUTH_URL}/dashboard?success=true`,
+    cancel_url: `${process.env.NEXTAUTH_URL}/pricing?canceled=true`,
+    customer_email: email,
+    metadata: { userId },
+  });
+
+  return session;
+}
+
+export async function createBillingPortalSession(customerId: string) {
+  const session = await stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: `${process.env.NEXTAUTH_URL}/dashboard/billing`,
+  });
+
+  return session;
+}
+```
+
+### Paso 6: Crear Server Actions para billing
+
+Crear `src/actions/billing.ts`:
+
+```typescript
+"use server";
+
+import { auth } from "@/lib/auth";
+import { db } from "@/lib/db";
+import { createCheckoutSession, createBillingPortalSession } from "@/lib/stripe";
+import { redirect } from "next/navigation";
+
+export async function subscribe(priceId: string) {
+  const session = await auth();
+
+  if (!session?.user?.id) {
+    redirect("/login");
+  }
+
+  const user = await db.user.findUnique({
+    where: { id: session.user.id },
+    include: { subscription: true },
+  });
+
+  if (!user) {
+    throw new Error("Usuario no encontrado");
+  }
+
+  // Si ya tiene subscripcion activa, redirigir al portal
+  if (user.subscription?.status === "ACTIVE") {
+    const portalSession = await createBillingPortalSession(user.stripeCustomerId!);
+    redirect(portalSession.url);
+  }
+
+  // Crear checkout session
+  const checkoutSession = await createCheckoutSession(
+    user.id,
+    priceId,
+    user.email
+  );
+
+  redirect(checkoutSession.url!);
+}
+
+export async function manageBilling() {
+  const session = await auth();
+
+  if (!session?.user?.id) {
+    redirect("/login");
+  }
+
+  const user = await db.user.findUnique({
+    where: { id: session.user.id },
+  });
+
+  if (!user?.stripeCustomerId) {
+    redirect("/pricing");
+  }
+
+  const portalSession = await createBillingPortalSession(user.stripeCustomerId);
+  redirect(portalSession.url);
+}
+```
+
+### Paso 7: Crear webhook de Stripe
+
+Crear `src/app/api/stripe/webhook/route.ts`:
+
+```typescript
+import { headers } from "next/headers";
+import { NextResponse } from "next/server";
+import { stripe } from "@/lib/stripe";
+import { db } from "@/lib/db";
+import Stripe from "stripe";
+
+export async function POST(request: Request) {
+  const body = await request.text();
+  const signature = headers().get("stripe-signature")!;
+
+  let event: Stripe.Event;
+
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
+  } catch (error) {
+    console.error("Webhook signature verification failed");
+    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
+  }
+
+  switch (event.type) {
+    case "checkout.session.completed": {
+      const session = event.data.object as Stripe.Checkout.Session;
+
+      await db.user.update({
+        where: { id: session.metadata!.userId },
+        data: { stripeCustomerId: session.customer as string },
+      });
+
+      const subscription = await stripe.subscriptions.retrieve(
+        session.subscription as string
+      );
+
+      await db.subscription.create({
+        data: {
+          userId: session.metadata!.userId,
+          stripeSubscriptionId: subscription.id,
+          stripePriceId: subscription.items.data[0].price.id,
+          stripeCurrentPeriodEnd: new Date(subscription.current_period_end * 1000),
+          status: "ACTIVE",
+        },
+      });
+      break;
+    }
+
+    case "customer.subscription.updated": {
+      const subscription = event.data.object as Stripe.Subscription;
+
+      await db.subscription.update({
+        where: { stripeSubscriptionId: subscription.id },
+        data: {
+          stripePriceId: subscription.items.data[0].price.id,
+          stripeCurrentPeriodEnd: new Date(subscription.current_period_end * 1000),
+          status: subscription.status.toUpperCase() as any,
+        },
+      });
+      break;
+    }
+
+    case "customer.subscription.deleted": {
+      const subscription = event.data.object as Stripe.Subscription;
+
+      await db.subscription.update({
+        where: { stripeSubscriptionId: subscription.id },
+        data: { status: "CANCELED" },
+      });
+      break;
+    }
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+### Paso 8: Crear pagina de precios
+
+Crear `src/app/pricing/page.tsx`:
+
+```typescript
+import { auth } from "@/lib/auth";
+import { PLANS } from "@/lib/stripe";
+import { subscribe } from "@/actions/billing";
+import { Button } from "@/components/ui/button";
+
+export default async function PricingPage() {
+  const session = await auth();
+
+  return (
+    <div className="min-h-screen bg-gray-50 py-16">
+      <div className="max-w-5xl mx-auto px-4">
+        <div className="text-center mb-12">
+          <h1 className="text-4xl font-bold mb-4">Planes y Precios</h1>
+          <p className="text-gray-600 text-lg">
+            Elige el plan que mejor se adapte a tus necesidades
+          </p>
+        </div>
+
+        <div className="grid md:grid-cols-2 gap-8">
+          {Object.entries(PLANS).map(([key, plan]) => (
+            <div
+              key={key}
+              className="bg-white rounded-2xl shadow-lg p-8 border-2 border-transparent hover:border-blue-500 transition-colors"
+            >
+              <h2 className="text-2xl font-bold mb-2">{plan.name}</h2>
+              <div className="mb-6">
+                <span className="text-4xl font-bold">${plan.price}</span>
+                <span className="text-gray-600">/mes</span>
+              </div>
+
+              <ul className="space-y-3 mb-8">
+                {plan.features.map((feature) => (
+                  <li key={feature} className="flex items-center gap-2">
+                    <svg className="w-5 h-5 text-green-500" fill="currentColor" viewBox="0 0 20 20">
+                      <path fillRule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clipRule="evenodd"/>
+                    </svg>
+                    {feature}
+                  </li>
+                ))}
+              </ul>
+
+              <form action={subscribe.bind(null, plan.priceId)}>
+                <Button className="w-full" type="submit">
+                  {session ? "Subscribirse" : "Empezar"}
+                </Button>
+              </form>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Paso 9: Crear pagina de billing
+
+Crear `src/app/(dashboard)/billing/page.tsx`:
+
+```typescript
+import { auth } from "@/lib/auth";
+import { db } from "@/lib/db";
+import { redirect } from "next/navigation";
+import { manageBilling } from "@/actions/billing";
+import { Button } from "@/components/ui/button";
+import { PLANS } from "@/lib/stripe";
+
+export default async function BillingPage() {
+  const session = await auth();
+
+  if (!session?.user?.id) {
+    redirect("/login");
+  }
+
+  const user = await db.user.findUnique({
+    where: { id: session.user.id },
+    include: { subscription: true },
+  });
+
+  const currentPlan = user?.subscription
+    ? Object.values(PLANS).find(p => p.priceId === user.subscription?.stripePriceId)
+    : null;
+
+  return (
+    <div className="max-w-2xl mx-auto py-8 px-4">
+      <h1 className="text-2xl font-bold mb-8">Facturacion</h1>
+
+      <div className="bg-white rounded-xl shadow p-6">
+        {user?.subscription ? (
+          <>
+            <div className="mb-6">
+              <h2 className="text-lg font-semibold mb-2">Plan Actual</h2>
+              <p className="text-3xl font-bold text-blue-600">
+                {currentPlan?.name || "Plan"}
+              </p>
+              <p className="text-gray-600">
+                ${currentPlan?.price}/mes
+              </p>
+            </div>
+
+            <div className="mb-6">
+              <h3 className="font-medium mb-2">Estado</h3>
+              <span className={`px-3 py-1 rounded-full text-sm ${
+                user.subscription.status === "ACTIVE"
+                  ? "bg-green-100 text-green-800"
+                  : "bg-yellow-100 text-yellow-800"
+              }`}>
+                {user.subscription.status}
+              </span>
+            </div>
+
+            <div className="mb-6">
+              <h3 className="font-medium mb-2">Proximo cobro</h3>
+              <p className="text-gray-600">
+                {user.subscription.stripeCurrentPeriodEnd.toLocaleDateString()}
+              </p>
+            </div>
+
+            <form action={manageBilling}>
+              <Button type="submit" variant="outline">
+                Gestionar Subscripcion
+              </Button>
+            </form>
+          </>
+        ) : (
+          <div className="text-center py-8">
+            <p className="text-gray-600 mb-4">
+              No tienes una subscripcion activa
+            </p>
+            <a href="/pricing">
+              <Button>Ver Planes</Button>
+            </a>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Paso 10: Crear panel de admin
+
+Crear `src/app/(admin)/layout.tsx`:
+
+```typescript
+import { auth } from "@/lib/auth";
+import { db } from "@/lib/db";
+import { redirect } from "next/navigation";
+
+export default async function AdminLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const session = await auth();
+
+  if (!session?.user?.id) {
+    redirect("/login");
+  }
+
+  const user = await db.user.findUnique({
+    where: { id: session.user.id },
+  });
+
+  if (user?.role !== "ADMIN") {
+    redirect("/dashboard");
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-100">
+      <nav className="bg-gray-900 text-white">
+        <div className="max-w-7xl mx-auto px-4 py-3 flex gap-6">
+          <a href="/admin" className="font-medium hover:text-gray-300">
+            Dashboard
+          </a>
+          <a href="/admin/users" className="font-medium hover:text-gray-300">
+            Usuarios
+          </a>
+          <a href="/dashboard" className="ml-auto text-gray-400 hover:text-white">
+            Volver a la app
+          </a>
+        </div>
+      </nav>
+      <main className="max-w-7xl mx-auto px-4 py-8">{children}</main>
+    </div>
+  );
+}
+```
+
+Crear `src/app/(admin)/page.tsx`:
+
+```typescript
+import { db } from "@/lib/db";
+
+export default async function AdminDashboard() {
+  const [totalUsers, activeSubscriptions, revenue] = await Promise.all([
+    db.user.count(),
+    db.subscription.count({ where: { status: "ACTIVE" } }),
+    db.subscription.findMany({
+      where: { status: "ACTIVE" },
+      select: { stripePriceId: true },
+    }),
+  ]);
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-8">Admin Dashboard</h1>
+
+      <div className="grid md:grid-cols-3 gap-6">
+        <div className="bg-white rounded-xl shadow p-6">
+          <h3 className="text-gray-600 text-sm">Total Usuarios</h3>
+          <p className="text-3xl font-bold">{totalUsers}</p>
+        </div>
+
+        <div className="bg-white rounded-xl shadow p-6">
+          <h3 className="text-gray-600 text-sm">Subscripciones Activas</h3>
+          <p className="text-3xl font-bold">{activeSubscriptions}</p>
+        </div>
+
+        <div className="bg-white rounded-xl shadow p-6">
+          <h3 className="text-gray-600 text-sm">MRR Estimado</h3>
+          <p className="text-3xl font-bold">
+            ${activeSubscriptions * 19}
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Paso 11: Ejecutar migraciones
+
+```bash
+npx prisma migrate dev --name add-stripe-fields
+npx prisma generate
+```
+
+### Paso 12: Configurar Stripe webhook local
+
+```bash
+stripe listen --forward-to localhost:3000/api/stripe/webhook
+```
+</setup_steps>
+
+<verification>
+## Verificacion
+
+### 1. Probar checkout flow
+1. Ir a /pricing
+2. Click en "Subscribirse"
+3. Usar tarjeta de test: 4242 4242 4242 4242
+4. Verificar redireccion a dashboard
+
+### 2. Verificar webhook
+- Revisar logs de `stripe listen`
+- Verificar que subscription se creo en DB
+
+### 3. Probar billing portal
+- Ir a /dashboard/billing
+- Click "Gestionar Subscripcion"
+- Verificar acceso al portal de Stripe
+
+### 4. Probar admin
+- Cambiar role a ADMIN en DB
+- Ir a /admin
+- Verificar metricas
+</verification>
+
+<stripe_test_cards>
+## Tarjetas de Test
+
+| Escenario | Numero |
+|-----------|--------|
+| Exito | 4242 4242 4242 4242 |
+| Requiere auth | 4000 0025 0000 3155 |
+| Declinada | 4000 0000 0000 0002 |
+| Fondos insuficientes | 4000 0000 0000 9995 |
+</stripe_test_cards>
+
+<common_issues>
+## Problemas Comunes
+
+### "Webhook signature verification failed"
+- Verificar STRIPE_WEBHOOK_SECRET
+- Usar el secret de `stripe listen`
+
+### "Customer not found"
+- El checkout debe completarse primero
+- Verificar que el webhook creo el customer
+
+### "Cannot access admin"
+- Verificar que el user tiene role=ADMIN en DB
+</common_issues>