@girardmedia/bootspring 1.1.0

package/skills/patterns/auth/clerk.md

@@ -0,0 +1,132 @@
+# Clerk Authentication Patterns
+
+Battle-tested patterns for Clerk authentication in Next.js.
+
+## Server-Side Auth Check
+
+```typescript
+// lib/auth.ts
+import { auth } from '@clerk/nextjs/server'
+
+export async function requireAuth() {
+  const { userId } = await auth()
+
+  if (!userId) {
+    throw new Error('UNAUTHORIZED')
+  }
+
+  return userId
+}
+
+// Usage in Server Action
+export async function myAction() {
+  const userId = await requireAuth()
+  // Continue with authenticated user
+}
+```
+
+## Protected Layout
+
+```typescript
+// app/(protected)/layout.tsx
+import { auth } from '@clerk/nextjs/server'
+import { redirect } from 'next/navigation'
+
+export default async function ProtectedLayout({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  const { userId } = await auth()
+
+  if (!userId) {
+    redirect('/sign-in')
+  }
+
+  return <>{children}</>
+}
+```
+
+## Get Current User with Metadata
+
+```typescript
+// lib/auth.ts
+import { currentUser } from '@clerk/nextjs/server'
+import { prisma } from '@/lib/db'
+
+export async function getCurrentUser() {
+  const user = await currentUser()
+  if (!user) return null
+
+  // Get or create database user
+  const dbUser = await prisma.user.upsert({
+    where: { clerkId: user.id },
+    update: {
+      email: user.emailAddresses[0]?.emailAddress,
+      name: `${user.firstName} ${user.lastName}`.trim()
+    },
+    create: {
+      clerkId: user.id,
+      email: user.emailAddresses[0]?.emailAddress ?? '',
+      name: `${user.firstName} ${user.lastName}`.trim()
+    }
+  })
+
+  return dbUser
+}
+```
+
+## Client-Side Auth Hook
+
+```typescript
+// hooks/use-user.ts
+'use client'
+import { useUser } from '@clerk/nextjs'
+
+export function useCurrentUser() {
+  const { user, isLoaded, isSignedIn } = useUser()
+
+  return {
+    user: isSignedIn ? user : null,
+    isLoading: !isLoaded,
+    isAuthenticated: isSignedIn
+  }
+}
+```
+
+## Middleware Configuration
+
+```typescript
+// middleware.ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+
+const isProtectedRoute = createRouteMatcher([
+  '/dashboard(.*)',
+  '/settings(.*)',
+  '/api/user(.*)'
+])
+
+const isPublicRoute = createRouteMatcher([
+  '/',
+  '/sign-in(.*)',
+  '/sign-up(.*)',
+  '/api/webhooks(.*)'
+])
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isProtectedRoute(req)) {
+    await auth.protect()
+  }
+})
+
+export const config = {
+  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)']
+}
+```
+
+## When to Use
+
+- Server Components needing user context
+- Server Actions modifying user data
+- API routes requiring authentication
+- Protected page layouts

package/skills/patterns/database/prisma.md

@@ -0,0 +1,180 @@
+# Prisma ORM Patterns
+
+Battle-tested patterns for Prisma with Next.js.
+
+## Client Singleton (Prevents Connection Exhaustion)
+
+```typescript
+// lib/db.ts
+import { PrismaClient } from '@prisma/client'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'error', 'warn']
+    : ['error'],
+})
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+## Common Query Patterns
+
+```typescript
+// Create with relations
+const user = await prisma.user.create({
+  data: {
+    email: 'john@example.com',
+    name: 'John Doe',
+    profile: {
+      create: { bio: 'Hello world' }
+    }
+  },
+  include: { profile: true }
+})
+
+// Read with filters and pagination
+const posts = await prisma.post.findMany({
+  where: {
+    published: true,
+    author: { email: { contains: '@example.com' } }
+  },
+  include: { author: { select: { name: true } } },
+  orderBy: { createdAt: 'desc' },
+  skip: (page - 1) * pageSize,
+  take: pageSize
+})
+
+// Update
+const updated = await prisma.user.update({
+  where: { id: userId },
+  data: { name: 'Updated Name' }
+})
+
+// Upsert (create or update)
+const result = await prisma.user.upsert({
+  where: { email: 'user@example.com' },
+  update: { name: 'Updated' },
+  create: { email: 'user@example.com', name: 'New User' }
+})
+
+// Soft delete pattern
+const deleted = await prisma.user.update({
+  where: { id: userId },
+  data: { deletedAt: new Date() }
+})
+```
+
+## Transactions
+
+```typescript
+// Sequential transaction (atomic)
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: userData }),
+  prisma.post.create({ data: postData })
+])
+
+// Interactive transaction (with logic)
+await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUnique({ where: { id: userId } })
+  if (!user) throw new Error('User not found')
+  if (user.credits < 10) throw new Error('Insufficient credits')
+
+  await tx.user.update({
+    where: { id: userId },
+    data: { credits: { decrement: 10 } }
+  })
+
+  await tx.transaction.create({
+    data: { userId, amount: -10, type: 'PURCHASE' }
+  })
+})
+```
+
+## Server Action Pattern
+
+```typescript
+// actions/user.ts
+'use server'
+import { prisma } from '@/lib/db'
+import { revalidatePath } from 'next/cache'
+import { z } from 'zod'
+
+const UpdateProfileSchema = z.object({
+  name: z.string().min(1).max(100),
+  bio: z.string().max(500).optional()
+})
+
+export async function updateProfile(userId: string, formData: FormData) {
+  const validated = UpdateProfileSchema.parse({
+    name: formData.get('name'),
+    bio: formData.get('bio')
+  })
+
+  await prisma.user.update({
+    where: { id: userId },
+    data: validated
+  })
+
+  revalidatePath('/profile')
+  return { success: true }
+}
+```
+
+## Migration Commands
+
+```bash
+# Development: create and apply migration
+npx prisma migrate dev --name add_posts_table
+
+# Production: apply pending migrations
+npx prisma migrate deploy
+
+# Regenerate client after schema changes
+npx prisma generate
+
+# Visual database browser
+npx prisma studio
+
+# Reset database (WARNING: destroys data)
+npx prisma migrate reset
+```
+
+## Schema Example
+
+```prisma
+// prisma/schema.prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  credits   Int      @default(0)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  deletedAt DateTime?
+
+  posts    Post[]
+  profile  Profile?
+
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id        String   @id @default(cuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now())
+
+  @@index([authorId])
+  @@map("posts")
+}
+```

package/skills/patterns/payments/stripe.md

@@ -0,0 +1,272 @@
+# Stripe Payment Patterns
+
+Battle-tested patterns for Stripe integration in Next.js.
+
+## Stripe Client Setup
+
+```typescript
+// lib/stripe.ts
+import Stripe from 'stripe'
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',
+  typescript: true
+})
+```
+
+## One-Time Payment Checkout
+
+```typescript
+// app/api/checkout/route.ts
+import { stripe } from '@/lib/stripe'
+import { auth } from '@/lib/auth'
+import { NextResponse } from 'next/server'
+
+export async function POST(req: Request) {
+  const { userId } = await auth()
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { priceId, quantity = 1 } = await req.json()
+
+  const session = await stripe.checkout.sessions.create({
+    mode: 'payment',
+    payment_method_types: ['card'],
+    line_items: [{ price: priceId, quantity }],
+    success_url: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
+    metadata: { userId }
+  })
+
+  return NextResponse.json({ url: session.url })
+}
+```
+
+## Subscription Checkout
+
+```typescript
+// app/api/subscribe/route.ts
+import { stripe } from '@/lib/stripe'
+import { auth } from '@/lib/auth'
+import { prisma } from '@/lib/db'
+
+export async function POST(req: Request) {
+  const { userId } = await auth()
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { priceId } = await req.json()
+
+  // Get or create Stripe customer
+  const user = await prisma.user.findUnique({ where: { id: userId } })
+  let customerId = user?.stripeCustomerId
+
+  if (!customerId) {
+    const customer = await stripe.customers.create({
+      email: user?.email,
+      metadata: { userId }
+    })
+    customerId = customer.id
+
+    await prisma.user.update({
+      where: { id: userId },
+      data: { stripeCustomerId: customerId }
+    })
+  }
+
+  const session = await stripe.checkout.sessions.create({
+    mode: 'subscription',
+    customer: customerId,
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?success=true`,
+    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
+    subscription_data: {
+      metadata: { userId }
+    }
+  })
+
+  return NextResponse.json({ url: session.url })
+}
+```
+
+## Webhook Handler
+
+```typescript
+// app/api/webhooks/stripe/route.ts
+import { stripe } from '@/lib/stripe'
+import { prisma } from '@/lib/db'
+import { headers } from 'next/headers'
+import Stripe from 'stripe'
+
+export async function POST(req: Request) {
+  const body = await req.text()
+  const headersList = await headers()
+  const signature = headersList.get('stripe-signature')!
+
+  let event: Stripe.Event
+
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    )
+  } catch (err) {
+    console.error('Webhook signature verification failed')
+    return new Response('Webhook Error', { status: 400 })
+  }
+
+  switch (event.type) {
+    case 'checkout.session.completed': {
+      const session = event.data.object as Stripe.Checkout.Session
+      const userId = session.metadata?.userId
+
+      if (session.mode === 'subscription') {
+        await prisma.user.update({
+          where: { id: userId },
+          data: {
+            subscriptionId: session.subscription as string,
+            subscriptionStatus: 'active'
+          }
+        })
+      } else if (session.mode === 'payment') {
+        // Handle one-time payment (e.g., add credits)
+        await prisma.user.update({
+          where: { id: userId },
+          data: { credits: { increment: 100 } }
+        })
+      }
+      break
+    }
+
+    case 'customer.subscription.updated':
+    case 'customer.subscription.deleted': {
+      const subscription = event.data.object as Stripe.Subscription
+      const userId = subscription.metadata.userId
+
+      await prisma.user.update({
+        where: { id: userId },
+        data: {
+          subscriptionStatus: subscription.status,
+          currentPeriodEnd: new Date(subscription.current_period_end * 1000)
+        }
+      })
+      break
+    }
+
+    case 'invoice.payment_failed': {
+      const invoice = event.data.object as Stripe.Invoice
+      // Send email notification, update status, etc.
+      break
+    }
+  }
+
+  return new Response('OK', { status: 200 })
+}
+```
+
+## Client-Side Checkout Button
+
+```typescript
+// components/checkout-button.tsx
+'use client'
+
+import { useState } from 'react'
+
+export function CheckoutButton({
+  priceId,
+  mode = 'payment'
+}: {
+  priceId: string
+  mode?: 'payment' | 'subscription'
+}) {
+  const [loading, setLoading] = useState(false)
+
+  const handleCheckout = async () => {
+    setLoading(true)
+
+    try {
+      const endpoint = mode === 'subscription' ? '/api/subscribe' : '/api/checkout'
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ priceId })
+      })
+
+      const { url, error } = await res.json()
+
+      if (error) {
+        alert(error)
+        return
+      }
+
+      window.location.href = url
+    } catch (error) {
+      console.error('Checkout error:', error)
+      alert('Something went wrong')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <button
+      onClick={handleCheckout}
+      disabled={loading}
+      className="px-6 py-3 bg-blue-600 text-white rounded-lg disabled:opacity-50"
+    >
+      {loading ? 'Loading...' : mode === 'subscription' ? 'Subscribe' : 'Buy Now'}
+    </button>
+  )
+}
+```
+
+## Customer Portal (Manage Subscription)
+
+```typescript
+// app/api/billing/portal/route.ts
+import { stripe } from '@/lib/stripe'
+import { auth } from '@/lib/auth'
+import { prisma } from '@/lib/db'
+
+export async function POST() {
+  const { userId } = await auth()
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const user = await prisma.user.findUnique({ where: { id: userId } })
+  if (!user?.stripeCustomerId) {
+    return NextResponse.json({ error: 'No billing account' }, { status: 400 })
+  }
+
+  const session = await stripe.billingPortal.sessions.create({
+    customer: user.stripeCustomerId,
+    return_url: `${process.env.NEXT_PUBLIC_URL}/settings/billing`
+  })
+
+  return NextResponse.json({ url: session.url })
+}
+```
+
+## Environment Variables
+
+```bash
+# .env.local
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+```
+
+## Testing Webhooks Locally
+
+```bash
+# Install Stripe CLI
+brew install stripe/stripe-cli/stripe
+
+# Login and forward webhooks
+stripe login
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```