@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/api/versioning.md

@@ -1,443 +0,0 @@
-# API Versioning Patterns
-
-Patterns for versioning REST APIs.
-
-## URL-Based Versioning
-
-```typescript
-// app/api/v1/users/route.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { prisma } from '@/lib/db'
-
-// V1 API - returns basic user data
-export async function GET() {
-  const users = await prisma.user.findMany({
-    select: {
-      id: true,
-      name: true,
-      email: true
-    }
-  })
-
-  return NextResponse.json(users)
-}
-
-// app/api/v2/users/route.ts
-// V2 API - returns extended user data with different structure
-export async function GET() {
-  const users = await prisma.user.findMany({
-    select: {
-      id: true,
-      name: true,
-      email: true,
-      createdAt: true,
-      profile: {
-        select: {
-          avatar: true,
-          bio: true
-        }
-      }
-    }
-  })
-
-  // V2 uses different response format
-  return NextResponse.json({
-    data: users,
-    meta: {
-      total: users.length,
-      version: 'v2'
-    }
-  })
-}
-```
-
-## Shared Version Logic
-
-```typescript
-// lib/api/versions.ts
-import { NextResponse } from 'next/server'
-
-export type ApiVersion = 'v1' | 'v2' | 'v3'
-
-interface VersionedResponse<T> {
-  v1: (data: T) => object
-  v2: (data: T) => object
-  v3?: (data: T) => object
-}
-
-export function formatResponse<T>(
-  version: ApiVersion,
-  data: T,
-  formatters: VersionedResponse<T>
-) {
-  const formatter = formatters[version]
-  if (!formatter) {
-    throw new Error(`Unsupported API version: ${version}`)
-  }
-  return formatter(data)
-}
-
-// Usage example
-// lib/api/users/formatters.ts
-import { User } from '@prisma/client'
-
-export const userFormatters = {
-  v1: (user: User) => ({
-    id: user.id,
-    name: user.name,
-    email: user.email
-  }),
-
-  v2: (user: User & { profile?: { avatar?: string } }) => ({
-    id: user.id,
-    displayName: user.name, // renamed field
-    email: user.email,
-    avatar: user.profile?.avatar ?? null,
-    createdAt: user.createdAt.toISOString()
-  })
-}
-```
-
-## Header-Based Versioning
-
-```typescript
-// middleware.ts
-import { NextRequest, NextResponse } from 'next/server'
-
-export function middleware(request: NextRequest) {
-  const version = request.headers.get('API-Version') ?? 'v1'
-  const validVersions = ['v1', 'v2', 'v3']
-
-  if (!validVersions.includes(version)) {
-    return NextResponse.json(
-      { error: `Invalid API version: ${version}` },
-      { status: 400 }
-    )
-  }
-
-  // Add version to request headers for route handlers
-  const requestHeaders = new Headers(request.headers)
-  requestHeaders.set('x-api-version', version)
-
-  return NextResponse.next({
-    request: { headers: requestHeaders }
-  })
-}
-
-export const config = {
-  matcher: '/api/:path*'
-}
-
-// app/api/users/route.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { formatResponse } from '@/lib/api/versions'
-import { userFormatters } from '@/lib/api/users/formatters'
-
-export async function GET(request: NextRequest) {
-  const version = request.headers.get('x-api-version') as 'v1' | 'v2'
-
-  const users = await prisma.user.findMany({
-    include: version === 'v2' ? { profile: true } : undefined
-  })
-
-  const formatted = users.map(user =>
-    formatResponse(version, user, userFormatters)
-  )
-
-  const response = NextResponse.json(formatted)
-  response.headers.set('API-Version', version)
-
-  return response
-}
-```
-
-## Content Negotiation Versioning
-
-```typescript
-// lib/api/content-negotiation.ts
-import { NextRequest } from 'next/server'
-
-export function parseAcceptHeader(request: NextRequest): {
-  version: string
-  format: string
-} {
-  const accept = request.headers.get('Accept') ?? 'application/json'
-
-  // Parse: application/vnd.myapi.v2+json
-  const match = accept.match(/application\/vnd\.myapi\.v(\d+)\+(\w+)/)
-
-  if (match) {
-    return {
-      version: `v${match[1]}`,
-      format: match[2]
-    }
-  }
-
-  return { version: 'v1', format: 'json' }
-}
-
-// app/api/users/route.ts
-export async function GET(request: NextRequest) {
-  const { version, format } = parseAcceptHeader(request)
-
-  const users = await prisma.user.findMany()
-
-  const formatted = users.map(user =>
-    formatResponse(version as 'v1' | 'v2', user, userFormatters)
-  )
-
-  const contentType = `application/vnd.myapi.${version}+${format}`
-
-  return new Response(JSON.stringify(formatted), {
-    headers: {
-      'Content-Type': contentType
-    }
-  })
-}
-```
-
-## Version Deprecation
-
-```typescript
-// lib/api/deprecation.ts
-import { NextResponse } from 'next/server'
-
-interface DeprecationInfo {
-  deprecated: boolean
-  sunset?: string // ISO date when version will be removed
-  successor?: string // Recommended version to migrate to
-  message?: string
-}
-
-const versionStatus: Record<string, DeprecationInfo> = {
-  v1: {
-    deprecated: true,
-    sunset: '2024-12-31',
-    successor: 'v2',
-    message: 'Please migrate to v2 API before December 31, 2024'
-  },
-  v2: { deprecated: false },
-  v3: { deprecated: false }
-}
-
-export function addDeprecationHeaders(
-  response: NextResponse,
-  version: string
-): NextResponse {
-  const info = versionStatus[version]
-
-  if (info?.deprecated) {
-    response.headers.set('Deprecation', 'true')
-    if (info.sunset) {
-      response.headers.set('Sunset', info.sunset)
-    }
-    if (info.message) {
-      response.headers.set('X-Deprecation-Notice', info.message)
-    }
-    if (info.successor) {
-      response.headers.set(
-        'Link',
-        `</api/${info.successor}>; rel="successor-version"`
-      )
-    }
-  }
-
-  return response
-}
-
-// Usage in route handler
-export async function GET(request: NextRequest) {
-  const version = request.headers.get('x-api-version') ?? 'v1'
-
-  const data = await fetchData()
-
-  let response = NextResponse.json(data)
-  response = addDeprecationHeaders(response, version)
-
-  return response
-}
-```
-
-## Version-Specific Middleware
-
-```typescript
-// lib/api/version-middleware.ts
-import { NextRequest, NextResponse } from 'next/server'
-
-type Handler = (req: NextRequest) => Promise<NextResponse>
-type VersionedHandlers = Record<string, Handler>
-
-export function createVersionedHandler(handlers: VersionedHandlers) {
-  return async (request: NextRequest) => {
-    const version = request.headers.get('x-api-version') ?? 'v1'
-
-    const handler = handlers[version]
-    if (!handler) {
-      return NextResponse.json(
-        {
-          error: 'Unsupported API version',
-          supportedVersions: Object.keys(handlers)
-        },
-        { status: 400 }
-      )
-    }
-
-    return handler(request)
-  }
-}
-
-// app/api/products/route.ts
-import { createVersionedHandler } from '@/lib/api/version-middleware'
-
-const v1Handler = async (request: NextRequest) => {
-  const products = await prisma.product.findMany()
-  return NextResponse.json(products)
-}
-
-const v2Handler = async (request: NextRequest) => {
-  const products = await prisma.product.findMany({
-    include: { variants: true, reviews: true }
-  })
-  return NextResponse.json({
-    data: products,
-    included: { totalCount: products.length }
-  })
-}
-
-export const GET = createVersionedHandler({
-  v1: v1Handler,
-  v2: v2Handler
-})
-```
-
-## API Documentation per Version
-
-```typescript
-// lib/api/openapi.ts
-import { OpenAPIObject } from 'openapi3-ts/oas31'
-
-export const openApiSpecs: Record<string, OpenAPIObject> = {
-  v1: {
-    openapi: '3.1.0',
-    info: {
-      title: 'My API',
-      version: '1.0.0',
-      description: 'API v1 (deprecated)'
-    },
-    paths: {
-      '/api/v1/users': {
-        get: {
-          summary: 'List users',
-          responses: {
-            '200': {
-              description: 'List of users',
-              content: {
-                'application/json': {
-                  schema: {
-                    type: 'array',
-                    items: { $ref: '#/components/schemas/UserV1' }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    components: {
-      schemas: {
-        UserV1: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-            name: { type: 'string' },
-            email: { type: 'string' }
-          }
-        }
-      }
-    }
-  },
-  v2: {
-    openapi: '3.1.0',
-    info: {
-      title: 'My API',
-      version: '2.0.0',
-      description: 'API v2 (current)'
-    },
-    paths: {
-      '/api/v2/users': {
-        get: {
-          summary: 'List users',
-          responses: {
-            '200': {
-              description: 'List of users with metadata',
-              content: {
-                'application/json': {
-                  schema: { $ref: '#/components/schemas/UsersResponseV2' }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    components: {
-      schemas: {
-        UserV2: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-            displayName: { type: 'string' },
-            email: { type: 'string' },
-            avatar: { type: 'string', nullable: true },
-            createdAt: { type: 'string', format: 'date-time' }
-          }
-        },
-        UsersResponseV2: {
-          type: 'object',
-          properties: {
-            data: {
-              type: 'array',
-              items: { $ref: '#/components/schemas/UserV2' }
-            },
-            meta: {
-              type: 'object',
-              properties: {
-                total: { type: 'number' },
-                version: { type: 'string' }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-
-// app/api/docs/[version]/route.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { openApiSpecs } from '@/lib/api/openapi'
-
-export async function GET(
-  request: NextRequest,
-  { params }: { params: { version: string } }
-) {
-  const spec = openApiSpecs[params.version]
-
-  if (!spec) {
-    return NextResponse.json(
-      { error: 'Version not found' },
-      { status: 404 }
-    )
-  }
-
-  return NextResponse.json(spec)
-}
-```
-
-## When to Use
-
-- Breaking API changes
-- Multiple client versions
-- Gradual API evolution
-- Long-term API support

package/skills/patterns/api/webhooks.md

@@ -1,247 +0,0 @@
-# Webhook Patterns
-
-Patterns for handling incoming webhooks.
-
-## Basic Webhook Handler
-
-```typescript
-// app/api/webhooks/stripe/route.ts
-import { headers } from 'next/headers'
-import Stripe from 'stripe'
-
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
-const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!
-
-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, webhookSecret)
-  } catch (err) {
-    console.error('Webhook signature verification failed')
-    return Response.json({ error: 'Invalid signature' }, { status: 400 })
-  }
-
-  try {
-    await handleEvent(event)
-    return Response.json({ received: true })
-  } catch (err) {
-    console.error('Webhook handler error:', err)
-    return Response.json({ error: 'Handler failed' }, { status: 500 })
-  }
-}
-
-async function handleEvent(event: Stripe.Event) {
-  switch (event.type) {
-    case 'checkout.session.completed':
-      await handleCheckoutComplete(event.data.object)
-      break
-    case 'customer.subscription.updated':
-      await handleSubscriptionUpdate(event.data.object)
-      break
-    case 'invoice.payment_failed':
-      await handlePaymentFailed(event.data.object)
-      break
-    default:
-      console.log(`Unhandled event type: ${event.type}`)
-  }
-}
-```
-
-## Idempotent Webhook Processing
-
-```typescript
-// lib/webhooks.ts
-import { prisma } from '@/lib/db'
-
-export async function processWebhookOnce(
-  eventId: string,
-  handler: () => Promise<void>
-) {
-  // Check if already processed
-  const existing = await prisma.webhookEvent.findUnique({
-    where: { eventId }
-  })
-
-  if (existing?.processedAt) {
-    console.log(`Event ${eventId} already processed`)
-    return { skipped: true }
-  }
-
-  // Create or update event record
-  await prisma.webhookEvent.upsert({
-    where: { eventId },
-    create: { eventId, receivedAt: new Date() },
-    update: {}
-  })
-
-  try {
-    await handler()
-
-    // Mark as processed
-    await prisma.webhookEvent.update({
-      where: { eventId },
-      data: { processedAt: new Date() }
-    })
-
-    return { success: true }
-  } catch (error) {
-    // Record failure
-    await prisma.webhookEvent.update({
-      where: { eventId },
-      data: {
-        error: error instanceof Error ? error.message : 'Unknown error',
-        failedAt: new Date()
-      }
-    })
-
-    throw error
-  }
-}
-
-// Usage
-async function handleEvent(event: Stripe.Event) {
-  await processWebhookOnce(event.id, async () => {
-    // Handle event...
-  })
-}
-```
-
-## Webhook Queue Processing
-
-```typescript
-// lib/webhook-queue.ts
-import { prisma } from '@/lib/db'
-
-export async function queueWebhook(
-  type: string,
-  payload: unknown,
-  eventId: string
-) {
-  await prisma.webhookQueue.create({
-    data: {
-      eventId,
-      type,
-      payload: JSON.stringify(payload),
-      status: 'PENDING'
-    }
-  })
-}
-
-export async function processWebhookQueue() {
-  const pending = await prisma.webhookQueue.findMany({
-    where: { status: 'PENDING' },
-    orderBy: { createdAt: 'asc' },
-    take: 10
-  })
-
-  for (const webhook of pending) {
-    try {
-      await prisma.webhookQueue.update({
-        where: { id: webhook.id },
-        data: { status: 'PROCESSING' }
-      })
-
-      const payload = JSON.parse(webhook.payload)
-      await processWebhookByType(webhook.type, payload)
-
-      await prisma.webhookQueue.update({
-        where: { id: webhook.id },
-        data: { status: 'COMPLETED', processedAt: new Date() }
-      })
-    } catch (error) {
-      await prisma.webhookQueue.update({
-        where: { id: webhook.id },
-        data: {
-          status: 'FAILED',
-          attempts: { increment: 1 },
-          lastError: error instanceof Error ? error.message : 'Unknown'
-        }
-      })
-    }
-  }
-}
-```
-
-## Webhook Retry Logic
-
-```typescript
-// lib/webhook-retry.ts
-const MAX_RETRIES = 3
-const RETRY_DELAYS = [1000, 5000, 30000] // 1s, 5s, 30s
-
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  eventId: string
-): Promise<T> {
-  let lastError: Error
-
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    try {
-      return await fn()
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error('Unknown error')
-
-      if (attempt < MAX_RETRIES) {
-        console.log(`Retry ${attempt + 1}/${MAX_RETRIES} for ${eventId}`)
-        await sleep(RETRY_DELAYS[attempt])
-      }
-    }
-  }
-
-  throw lastError!
-}
-
-function sleep(ms: number) {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-```
-
-## Generic Webhook Verification
-
-```typescript
-// lib/webhooks/verify.ts
-import { createHmac, timingSafeEqual } from 'crypto'
-
-export function verifyWebhookSignature(
-  payload: string,
-  signature: string,
-  secret: string,
-  algorithm = 'sha256'
-): boolean {
-  const expected = createHmac(algorithm, secret)
-    .update(payload)
-    .digest('hex')
-
-  const signatureBuffer = Buffer.from(signature)
-  const expectedBuffer = Buffer.from(expected)
-
-  if (signatureBuffer.length !== expectedBuffer.length) {
-    return false
-  }
-
-  return timingSafeEqual(signatureBuffer, expectedBuffer)
-}
-
-// Usage
-export async function POST(request: Request) {
-  const body = await request.text()
-  const signature = headers().get('x-signature')!
-
-  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET!)) {
-    return Response.json({ error: 'Invalid signature' }, { status: 401 })
-  }
-
-  // Process webhook...
-}
-```
-
-## When to Use
-
-- Payment providers (Stripe, PayPal)
-- Third-party integrations
-- Event-driven architectures
-- Async processing