@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/api/rate-limiting.md

@@ -1,231 +0,0 @@
-# Rate Limiting Patterns
-
-Patterns for implementing API rate limiting.
-
-## In-Memory Rate Limiter
-
-```typescript
-// lib/rate-limit.ts
-const rateLimitMap = new Map<string, { count: number; resetTime: number }>()
-
-export function rateLimit(
-  key: string,
-  limit: number,
-  windowMs: number
-): { success: boolean; remaining: number; resetIn: number } {
-  const now = Date.now()
-  const record = rateLimitMap.get(key)
-
-  if (!record || now > record.resetTime) {
-    rateLimitMap.set(key, { count: 1, resetTime: now + windowMs })
-    return { success: true, remaining: limit - 1, resetIn: windowMs }
-  }
-
-  if (record.count >= limit) {
-    return {
-      success: false,
-      remaining: 0,
-      resetIn: record.resetTime - now
-    }
-  }
-
-  record.count++
-  return {
-    success: true,
-    remaining: limit - record.count,
-    resetIn: record.resetTime - now
-  }
-}
-```
-
-## Redis Rate Limiter
-
-```typescript
-// lib/rate-limit-redis.ts
-import { Redis } from '@upstash/redis'
-
-const redis = new Redis({
-  url: process.env.UPSTASH_REDIS_URL!,
-  token: process.env.UPSTASH_REDIS_TOKEN!
-})
-
-export async function rateLimitRedis(
-  key: string,
-  limit: number,
-  windowSeconds: number
-) {
-  const current = await redis.incr(key)
-
-  if (current === 1) {
-    await redis.expire(key, windowSeconds)
-  }
-
-  const ttl = await redis.ttl(key)
-
-  return {
-    success: current <= limit,
-    remaining: Math.max(0, limit - current),
-    resetIn: ttl > 0 ? ttl * 1000 : windowSeconds * 1000
-  }
-}
-```
-
-## Sliding Window Rate Limiter
-
-```typescript
-// lib/rate-limit-sliding.ts
-import { Redis } from '@upstash/redis'
-
-const redis = new Redis({
-  url: process.env.UPSTASH_REDIS_URL!,
-  token: process.env.UPSTASH_REDIS_TOKEN!
-})
-
-export async function slidingWindowRateLimit(
-  key: string,
-  limit: number,
-  windowMs: number
-) {
-  const now = Date.now()
-  const windowStart = now - windowMs
-
-  // Remove old entries and add new one
-  const pipeline = redis.pipeline()
-  pipeline.zremrangebyscore(key, 0, windowStart)
-  pipeline.zadd(key, { score: now, member: `${now}-${Math.random()}` })
-  pipeline.zcard(key)
-  pipeline.expire(key, Math.ceil(windowMs / 1000))
-
-  const results = await pipeline.exec()
-  const count = results[2] as number
-
-  return {
-    success: count <= limit,
-    remaining: Math.max(0, limit - count),
-    resetIn: windowMs
-  }
-}
-```
-
-## Rate Limit Middleware
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server'
-import type { NextRequest } from 'next/server'
-import { rateLimitRedis } from '@/lib/rate-limit-redis'
-
-const RATE_LIMITS = {
-  '/api/': { limit: 100, window: 60 },           // 100 req/min
-  '/api/auth/': { limit: 10, window: 60 },       // 10 req/min
-  '/api/ai/': { limit: 20, window: 60 }          // 20 req/min
-}
-
-export async function middleware(request: NextRequest) {
-  const ip = request.ip ?? request.headers.get('x-forwarded-for') ?? 'unknown'
-  const path = request.nextUrl.pathname
-
-  // Find matching rate limit
-  let config = { limit: 100, window: 60 }
-  for (const [prefix, limits] of Object.entries(RATE_LIMITS)) {
-    if (path.startsWith(prefix)) {
-      config = limits
-      break
-    }
-  }
-
-  const key = `rate-limit:${ip}:${path}`
-  const result = await rateLimitRedis(key, config.limit, config.window)
-
-  if (!result.success) {
-    return NextResponse.json(
-      { error: 'Too many requests' },
-      {
-        status: 429,
-        headers: {
-          'X-RateLimit-Limit': config.limit.toString(),
-          'X-RateLimit-Remaining': '0',
-          'X-RateLimit-Reset': Math.ceil(Date.now() / 1000 + result.resetIn / 1000).toString(),
-          'Retry-After': Math.ceil(result.resetIn / 1000).toString()
-        }
-      }
-    )
-  }
-
-  const response = NextResponse.next()
-  response.headers.set('X-RateLimit-Limit', config.limit.toString())
-  response.headers.set('X-RateLimit-Remaining', result.remaining.toString())
-
-  return response
-}
-
-export const config = {
-  matcher: '/api/:path*'
-}
-```
-
-## Per-User Rate Limiting
-
-```typescript
-// lib/rate-limit-user.ts
-import { auth } from '@/auth'
-
-export async function userRateLimit(baseLimit: number) {
-  const session = await auth()
-  const userId = session?.user?.id
-
-  // Higher limits for authenticated users
-  const limit = userId ? baseLimit * 2 : baseLimit
-
-  // Use user ID or IP as key
-  const key = userId ?? (await getClientIP())
-
-  return rateLimitRedis(`user:${key}`, limit, 60)
-}
-```
-
-## Token Bucket Algorithm
-
-```typescript
-// lib/token-bucket.ts
-interface Bucket {
-  tokens: number
-  lastRefill: number
-}
-
-const buckets = new Map<string, Bucket>()
-
-export function tokenBucket(
-  key: string,
-  maxTokens: number,
-  refillRate: number // tokens per second
-): boolean {
-  const now = Date.now()
-  let bucket = buckets.get(key)
-
-  if (!bucket) {
-    bucket = { tokens: maxTokens, lastRefill: now }
-    buckets.set(key, bucket)
-  }
-
-  // Refill tokens
-  const timePassed = (now - bucket.lastRefill) / 1000
-  bucket.tokens = Math.min(maxTokens, bucket.tokens + timePassed * refillRate)
-  bucket.lastRefill = now
-
-  // Try to consume a token
-  if (bucket.tokens >= 1) {
-    bucket.tokens -= 1
-    return true
-  }
-
-  return false
-}
-```
-
-## When to Use
-
-- API protection
-- DDoS mitigation
-- Fair usage enforcement
-- Cost control

package/skills/patterns/api/route-handler.md

@@ -1,217 +0,0 @@
-# Next.js Route Handler Patterns
-
-Battle-tested patterns for API routes in Next.js App Router.
-
-## Basic CRUD Route Handler
-
-```typescript
-// app/api/posts/route.ts
-import { prisma } from '@/lib/db'
-import { auth } from '@/lib/auth'
-import { NextRequest, NextResponse } from 'next/server'
-import { z } from 'zod'
-
-const CreatePostSchema = z.object({
-  title: z.string().min(1).max(200),
-  content: z.string().optional(),
-  published: z.boolean().default(false)
-})
-
-// GET /api/posts
-export async function GET(request: NextRequest) {
-  const searchParams = request.nextUrl.searchParams
-  const page = parseInt(searchParams.get('page') ?? '1')
-  const limit = parseInt(searchParams.get('limit') ?? '10')
-
-  const posts = await prisma.post.findMany({
-    where: { published: true },
-    orderBy: { createdAt: 'desc' },
-    skip: (page - 1) * limit,
-    take: limit,
-    include: { author: { select: { name: true } } }
-  })
-
-  return NextResponse.json({ posts, page, limit })
-}
-
-// POST /api/posts
-export async function POST(request: NextRequest) {
-  try {
-    const { userId } = await auth()
-    if (!userId) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-    }
-
-    const body = await request.json()
-    const validated = CreatePostSchema.parse(body)
-
-    const post = await prisma.post.create({
-      data: { ...validated, authorId: userId }
-    })
-
-    return NextResponse.json(post, { status: 201 })
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return NextResponse.json({ error: error.errors }, { status: 400 })
-    }
-    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
-  }
-}
-```
-
-## Dynamic Route Handler
-
-```typescript
-// app/api/posts/[id]/route.ts
-import { prisma } from '@/lib/db'
-import { auth } from '@/lib/auth'
-import { NextRequest, NextResponse } from 'next/server'
-
-type Params = { params: Promise<{ id: string }> }
-
-// GET /api/posts/:id
-export async function GET(request: NextRequest, { params }: Params) {
-  const { id } = await params
-
-  const post = await prisma.post.findUnique({
-    where: { id },
-    include: { author: { select: { name: true, email: true } } }
-  })
-
-  if (!post) {
-    return NextResponse.json({ error: 'Not found' }, { status: 404 })
-  }
-
-  return NextResponse.json(post)
-}
-
-// PATCH /api/posts/:id
-export async function PATCH(request: NextRequest, { params }: Params) {
-  const { userId } = await auth()
-  if (!userId) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
-
-  const { id } = await params
-  const body = await request.json()
-
-  const post = await prisma.post.findUnique({ where: { id } })
-  if (!post) {
-    return NextResponse.json({ error: 'Not found' }, { status: 404 })
-  }
-  if (post.authorId !== userId) {
-    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
-  }
-
-  const updated = await prisma.post.update({
-    where: { id },
-    data: body
-  })
-
-  return NextResponse.json(updated)
-}
-
-// DELETE /api/posts/:id
-export async function DELETE(request: NextRequest, { params }: Params) {
-  const { userId } = await auth()
-  if (!userId) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
-
-  const { id } = await params
-
-  const post = await prisma.post.findUnique({ where: { id } })
-  if (!post || post.authorId !== userId) {
-    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
-  }
-
-  await prisma.post.delete({ where: { id } })
-
-  return new NextResponse(null, { status: 204 })
-}
-```
-
-## Error Handling Wrapper
-
-```typescript
-// lib/api-utils.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { ZodError } from 'zod'
-
-type Handler = (req: NextRequest, context?: any) => Promise<NextResponse>
-
-export function withErrorHandling(handler: Handler): Handler {
-  return async (req, context) => {
-    try {
-      return await handler(req, context)
-    } catch (error) {
-      console.error('API Error:', error)
-
-      if (error instanceof ZodError) {
-        return NextResponse.json(
-          { error: 'Validation failed', details: error.errors },
-          { status: 400 }
-        )
-      }
-
-      if (error instanceof Error) {
-        if (error.message === 'UNAUTHORIZED') {
-          return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-        }
-        if (error.message === 'NOT_FOUND') {
-          return NextResponse.json({ error: 'Not found' }, { status: 404 })
-        }
-      }
-
-      return NextResponse.json(
-        { error: 'Internal server error' },
-        { status: 500 }
-      )
-    }
-  }
-}
-```
-
-## Rate Limiting Pattern
-
-```typescript
-// lib/rate-limit.ts
-import { NextRequest, NextResponse } from 'next/server'
-
-const rateLimit = new Map<string, { count: number; resetTime: number }>()
-
-export function checkRateLimit(
-  identifier: string,
-  limit: number = 10,
-  windowMs: number = 60000
-): boolean {
-  const now = Date.now()
-  const record = rateLimit.get(identifier)
-
-  if (!record || now > record.resetTime) {
-    rateLimit.set(identifier, { count: 1, resetTime: now + windowMs })
-    return true
-  }
-
-  if (record.count >= limit) {
-    return false
-  }
-
-  record.count++
-  return true
-}
-
-// Usage in route
-export async function POST(request: NextRequest) {
-  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'
-
-  if (!checkRateLimit(ip, 10, 60000)) {
-    return NextResponse.json(
-      { error: 'Too many requests' },
-      { status: 429 }
-    )
-  }
-
-  // Continue with handler...
-}
-```

package/skills/patterns/api/server-action.md

@@ -1,249 +0,0 @@
-# Next.js Server Action Patterns
-
-Battle-tested patterns for Server Actions in Next.js App Router.
-
-## Basic Server Action
-
-```typescript
-// actions/posts.ts
-'use server'
-
-import { prisma } from '@/lib/db'
-import { auth } from '@/lib/auth'
-import { revalidatePath } from 'next/cache'
-import { redirect } from 'next/navigation'
-import { z } from 'zod'
-
-const CreatePostSchema = z.object({
-  title: z.string().min(1, 'Title is required').max(200),
-  content: z.string().optional()
-})
-
-export async function createPost(formData: FormData) {
-  const { userId } = await auth()
-  if (!userId) throw new Error('UNAUTHORIZED')
-
-  const validated = CreatePostSchema.parse({
-    title: formData.get('title'),
-    content: formData.get('content')
-  })
-
-  const post = await prisma.post.create({
-    data: { ...validated, authorId: userId }
-  })
-
-  revalidatePath('/posts')
-  redirect(`/posts/${post.id}`)
-}
-```
-
-## Server Action with Return Value
-
-```typescript
-// actions/posts.ts
-'use server'
-
-type ActionResult<T> =
-  | { success: true; data: T }
-  | { success: false; error: string }
-
-export async function updatePost(
-  postId: string,
-  formData: FormData
-): Promise<ActionResult<{ id: string }>> {
-  try {
-    const { userId } = await auth()
-    if (!userId) {
-      return { success: false, error: 'Not authenticated' }
-    }
-
-    const post = await prisma.post.findUnique({ where: { id: postId } })
-    if (!post || post.authorId !== userId) {
-      return { success: false, error: 'Not authorized' }
-    }
-
-    const title = formData.get('title') as string
-    if (!title || title.length < 1) {
-      return { success: false, error: 'Title is required' }
-    }
-
-    const updated = await prisma.post.update({
-      where: { id: postId },
-      data: { title }
-    })
-
-    revalidatePath(`/posts/${postId}`)
-    return { success: true, data: { id: updated.id } }
-  } catch (error) {
-    console.error('Update post error:', error)
-    return { success: false, error: 'Failed to update post' }
-  }
-}
-```
-
-## Using with useActionState (React 19)
-
-```typescript
-// components/create-post-form.tsx
-'use client'
-
-import { useActionState } from 'react'
-import { createPost } from '@/actions/posts'
-
-const initialState = { error: null as string | null }
-
-export function CreatePostForm() {
-  const [state, formAction, isPending] = useActionState(
-    async (prevState: typeof initialState, formData: FormData) => {
-      const result = await createPost(formData)
-      if (!result.success) {
-        return { error: result.error }
-      }
-      return { error: null }
-    },
-    initialState
-  )
-
-  return (
-    <form action={formAction}>
-      {state.error && (
-        <div className="text-red-500 mb-4">{state.error}</div>
-      )}
-
-      <input
-        name="title"
-        placeholder="Post title"
-        required
-        disabled={isPending}
-        className="w-full p-2 border rounded"
-      />
-
-      <textarea
-        name="content"
-        placeholder="Content (optional)"
-        disabled={isPending}
-        className="w-full p-2 border rounded mt-2"
-      />
-
-      <button
-        type="submit"
-        disabled={isPending}
-        className="mt-4 px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
-      >
-        {isPending ? 'Creating...' : 'Create Post'}
-      </button>
-    </form>
-  )
-}
-```
-
-## Delete Action with Confirmation
-
-```typescript
-// actions/posts.ts
-'use server'
-
-export async function deletePost(postId: string): Promise<ActionResult<null>> {
-  const { userId } = await auth()
-  if (!userId) {
-    return { success: false, error: 'Not authenticated' }
-  }
-
-  const post = await prisma.post.findUnique({ where: { id: postId } })
-  if (!post || post.authorId !== userId) {
-    return { success: false, error: 'Not authorized' }
-  }
-
-  await prisma.post.delete({ where: { id: postId } })
-
-  revalidatePath('/posts')
-  return { success: true, data: null }
-}
-
-// components/delete-button.tsx
-'use client'
-
-import { deletePost } from '@/actions/posts'
-import { useTransition } from 'react'
-import { useRouter } from 'next/navigation'
-
-export function DeleteButton({ postId }: { postId: string }) {
-  const [isPending, startTransition] = useTransition()
-  const router = useRouter()
-
-  const handleDelete = () => {
-    if (!confirm('Are you sure you want to delete this post?')) return
-
-    startTransition(async () => {
-      const result = await deletePost(postId)
-      if (result.success) {
-        router.push('/posts')
-      } else {
-        alert(result.error)
-      }
-    })
-  }
-
-  return (
-    <button
-      onClick={handleDelete}
-      disabled={isPending}
-      className="text-red-500 disabled:opacity-50"
-    >
-      {isPending ? 'Deleting...' : 'Delete'}
-    </button>
-  )
-}
-```
-
-## Optimistic Updates
-
-```typescript
-// components/like-button.tsx
-'use client'
-
-import { useOptimistic, useTransition } from 'react'
-import { toggleLike } from '@/actions/posts'
-
-export function LikeButton({ postId, initialLiked, initialCount }: {
-  postId: string
-  initialLiked: boolean
-  initialCount: number
-}) {
-  const [isPending, startTransition] = useTransition()
-  const [optimistic, setOptimistic] = useOptimistic(
-    { liked: initialLiked, count: initialCount },
-    (state, newLiked: boolean) => ({
-      liked: newLiked,
-      count: newLiked ? state.count + 1 : state.count - 1
-    })
-  )
-
-  const handleClick = () => {
-    startTransition(async () => {
-      setOptimistic(!optimistic.liked)
-      await toggleLike(postId)
-    })
-  }
-
-  return (
-    <button onClick={handleClick} disabled={isPending}>
-      {optimistic.liked ? '❤️' : '🤍'} {optimistic.count}
-    </button>
-  )
-}
-```
-
-## When to Use Server Actions vs Route Handlers
-
-**Use Server Actions for:**
-- Form submissions
-- Mutations from client components
-- Actions that need revalidation
-- Progressive enhancement (works without JS)
-
-**Use Route Handlers for:**
-- Webhooks from external services
-- Public APIs consumed by other apps
-- Long-running operations
-- File uploads/downloads