@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/api/middleware.md

@@ -1,279 +0,0 @@
-# API Middleware Patterns
-
-Patterns for Next.js API middleware.
-
-## Authentication Middleware
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server'
-import type { NextRequest } from 'next/server'
-import { getToken } from 'next-auth/jwt'
-
-const protectedPaths = ['/api/users', '/api/teams', '/api/billing']
-const publicPaths = ['/api/auth', '/api/health', '/api/webhooks']
-
-export async function middleware(request: NextRequest) {
-  const path = request.nextUrl.pathname
-
-  // Skip public paths
-  if (publicPaths.some(p => path.startsWith(p))) {
-    return NextResponse.next()
-  }
-
-  // Check auth for protected paths
-  if (protectedPaths.some(p => path.startsWith(p))) {
-    const token = await getToken({ req: request })
-
-    if (!token) {
-      return NextResponse.json(
-        { error: { message: 'Unauthorized', code: 'UNAUTHORIZED' } },
-        { status: 401 }
-      )
-    }
-
-    // Add user info to headers for route handlers
-    const requestHeaders = new Headers(request.headers)
-    requestHeaders.set('x-user-id', token.sub!)
-    requestHeaders.set('x-user-role', token.role as string)
-
-    return NextResponse.next({
-      request: { headers: requestHeaders }
-    })
-  }
-
-  return NextResponse.next()
-}
-
-export const config = {
-  matcher: '/api/:path*'
-}
-```
-
-## CORS Middleware
-
-```typescript
-// middleware.ts
-const allowedOrigins = [
-  'https://app.example.com',
-  'https://admin.example.com'
-]
-
-function corsMiddleware(request: NextRequest) {
-  const origin = request.headers.get('origin')
-  const isAllowed = origin && allowedOrigins.includes(origin)
-
-  // Handle preflight
-  if (request.method === 'OPTIONS') {
-    return new NextResponse(null, {
-      status: 204,
-      headers: {
-        'Access-Control-Allow-Origin': isAllowed ? origin : '',
-        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-        'Access-Control-Max-Age': '86400'
-      }
-    })
-  }
-
-  const response = NextResponse.next()
-
-  if (isAllowed) {
-    response.headers.set('Access-Control-Allow-Origin', origin)
-  }
-
-  return response
-}
-```
-
-## Request Logging Middleware
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server'
-import type { NextRequest } from 'next/server'
-
-export async function middleware(request: NextRequest) {
-  const requestId = crypto.randomUUID()
-  const start = Date.now()
-
-  // Add request ID to headers
-  const requestHeaders = new Headers(request.headers)
-  requestHeaders.set('x-request-id', requestId)
-
-  const response = NextResponse.next({
-    request: { headers: requestHeaders }
-  })
-
-  // Log request
-  const duration = Date.now() - start
-  console.log(JSON.stringify({
-    requestId,
-    method: request.method,
-    path: request.nextUrl.pathname,
-    duration,
-    timestamp: new Date().toISOString()
-  }))
-
-  response.headers.set('x-request-id', requestId)
-  return response
-}
-```
-
-## Composed Middleware
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server'
-import type { NextRequest, NextMiddleware } from 'next/server'
-
-type MiddlewareFunction = (
-  request: NextRequest
-) => Promise<NextResponse | null> | NextResponse | null
-
-// Compose multiple middlewares
-function composeMiddleware(...middlewares: MiddlewareFunction[]) {
-  return async (request: NextRequest) => {
-    for (const middleware of middlewares) {
-      const result = await middleware(request)
-      // If middleware returns a response, stop chain
-      if (result) return result
-    }
-    return NextResponse.next()
-  }
-}
-
-// Individual middlewares
-async function authMiddleware(request: NextRequest) {
-  if (request.nextUrl.pathname.startsWith('/api/protected')) {
-    const token = await getToken({ req: request })
-    if (!token) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-    }
-  }
-  return null // Continue to next middleware
-}
-
-function loggingMiddleware(request: NextRequest) {
-  console.log(`${request.method} ${request.nextUrl.pathname}`)
-  return null
-}
-
-async function rateLimitMiddleware(request: NextRequest) {
-  const ip = request.ip ?? 'unknown'
-  const result = await checkRateLimit(ip)
-  if (!result.success) {
-    return NextResponse.json({ error: 'Rate limited' }, { status: 429 })
-  }
-  return null
-}
-
-// Export composed middleware
-export const middleware = composeMiddleware(
-  loggingMiddleware,
-  rateLimitMiddleware,
-  authMiddleware
-)
-
-export const config = {
-  matcher: '/api/:path*'
-}
-```
-
-## API Key Middleware
-
-```typescript
-// lib/api-key.ts
-import { prisma } from '@/lib/db'
-import { headers } from 'next/headers'
-
-export async function validateApiKey() {
-  const headersList = headers()
-  const apiKey = headersList.get('x-api-key')
-
-  if (!apiKey) {
-    return null
-  }
-
-  const key = await prisma.apiKey.findUnique({
-    where: { key: apiKey },
-    include: { user: true }
-  })
-
-  if (!key || key.revokedAt) {
-    return null
-  }
-
-  // Update last used
-  await prisma.apiKey.update({
-    where: { id: key.id },
-    data: { lastUsedAt: new Date() }
-  })
-
-  return key.user
-}
-
-// Usage in route handler
-export async function GET(request: Request) {
-  const user = await validateApiKey()
-
-  if (!user) {
-    return Response.json(
-      { error: 'Invalid API key' },
-      { status: 401 }
-    )
-  }
-
-  // Continue with authenticated user...
-}
-```
-
-## Request Validation Middleware
-
-```typescript
-// lib/validate-request.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { z } from 'zod'
-
-export function withValidation<T extends z.ZodSchema>(
-  schema: T,
-  handler: (
-    request: NextRequest,
-    data: z.infer<T>
-  ) => Promise<NextResponse>
-) {
-  return async (request: NextRequest) => {
-    try {
-      const body = await request.json()
-      const data = schema.parse(body)
-      return handler(request, data)
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        return NextResponse.json(
-          { error: { message: 'Validation failed', details: error.errors } },
-          { status: 400 }
-        )
-      }
-      throw error
-    }
-  }
-}
-
-// Usage
-const CreateUserSchema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1)
-})
-
-export const POST = withValidation(CreateUserSchema, async (request, data) => {
-  const user = await createUser(data)
-  return NextResponse.json({ data: user }, { status: 201 })
-})
-```
-
-## When to Use
-
-- Authentication/authorization
-- Request logging
-- Rate limiting
-- CORS handling

package/skills/patterns/api/openapi.md

@@ -1,285 +0,0 @@
-# OpenAPI Documentation Patterns
-
-Patterns for API documentation with OpenAPI/Swagger.
-
-## OpenAPI Spec Definition
-
-```typescript
-// lib/openapi.ts
-import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi'
-import { z } from 'zod'
-
-export const registry = new OpenAPIRegistry()
-
-// Define schemas
-export const UserSchema = registry.register(
-  'User',
-  z.object({
-    id: z.string().openapi({ example: 'usr_123' }),
-    email: z.string().email().openapi({ example: 'user@example.com' }),
-    name: z.string().openapi({ example: 'John Doe' }),
-    role: z.enum(['USER', 'ADMIN']).openapi({ example: 'USER' }),
-    createdAt: z.string().datetime().openapi({ example: '2024-01-01T00:00:00Z' })
-  })
-)
-
-export const ErrorSchema = registry.register(
-  'Error',
-  z.object({
-    error: z.object({
-      message: z.string(),
-      code: z.string()
-    })
-  })
-)
-
-// Register endpoints
-registry.registerPath({
-  method: 'get',
-  path: '/api/users/{id}',
-  tags: ['Users'],
-  summary: 'Get user by ID',
-  request: {
-    params: z.object({
-      id: z.string().openapi({ description: 'User ID' })
-    })
-  },
-  responses: {
-    200: {
-      description: 'User found',
-      content: {
-        'application/json': {
-          schema: z.object({ data: UserSchema })
-        }
-      }
-    },
-    404: {
-      description: 'User not found',
-      content: {
-        'application/json': {
-          schema: ErrorSchema
-        }
-      }
-    }
-  }
-})
-
-// Generate spec
-export function generateOpenAPISpec() {
-  const generator = new OpenApiGeneratorV3(registry.definitions)
-
-  return generator.generateDocument({
-    openapi: '3.0.0',
-    info: {
-      title: 'My API',
-      version: '1.0.0',
-      description: 'API documentation'
-    },
-    servers: [
-      { url: 'https://api.example.com', description: 'Production' },
-      { url: 'http://localhost:3000', description: 'Development' }
-    ]
-  })
-}
-```
-
-## API Route for Spec
-
-```typescript
-// app/api/openapi/route.ts
-import { generateOpenAPISpec } from '@/lib/openapi'
-
-export async function GET() {
-  const spec = generateOpenAPISpec()
-  return Response.json(spec)
-}
-```
-
-## Swagger UI Page
-
-```tsx
-// app/docs/page.tsx
-'use client'
-
-import SwaggerUI from 'swagger-ui-react'
-import 'swagger-ui-react/swagger-ui.css'
-
-export default function DocsPage() {
-  return (
-    <div className="min-h-screen">
-      <SwaggerUI url="/api/openapi" />
-    </div>
-  )
-}
-```
-
-## Schema with Descriptions
-
-```typescript
-// lib/schemas/user.ts
-import { z } from 'zod'
-import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi'
-
-extendZodWithOpenApi(z)
-
-export const CreateUserSchema = z.object({
-  email: z
-    .string()
-    .email()
-    .openapi({
-      description: 'User email address',
-      example: 'user@example.com'
-    }),
-  name: z
-    .string()
-    .min(1)
-    .max(100)
-    .openapi({
-      description: 'User display name',
-      example: 'John Doe'
-    }),
-  password: z
-    .string()
-    .min(8)
-    .openapi({
-      description: 'Password (min 8 characters)',
-      example: 'securepassword123'
-    })
-}).openapi('CreateUserInput')
-
-export const UserResponseSchema = z.object({
-  id: z.string(),
-  email: z.string().email(),
-  name: z.string(),
-  emailVerified: z.boolean(),
-  createdAt: z.string().datetime()
-}).openapi('UserResponse')
-```
-
-## Register Multiple Endpoints
-
-```typescript
-// lib/openapi/users.ts
-import { registry } from '../openapi'
-import { CreateUserSchema, UserResponseSchema } from '../schemas/user'
-
-// List users
-registry.registerPath({
-  method: 'get',
-  path: '/api/users',
-  tags: ['Users'],
-  summary: 'List all users',
-  request: {
-    query: z.object({
-      page: z.string().optional().openapi({ example: '1' }),
-      limit: z.string().optional().openapi({ example: '10' })
-    })
-  },
-  responses: {
-    200: {
-      description: 'List of users',
-      content: {
-        'application/json': {
-          schema: z.object({
-            data: z.array(UserResponseSchema),
-            pagination: z.object({
-              page: z.number(),
-              limit: z.number(),
-              total: z.number()
-            })
-          })
-        }
-      }
-    }
-  }
-})
-
-// Create user
-registry.registerPath({
-  method: 'post',
-  path: '/api/users',
-  tags: ['Users'],
-  summary: 'Create a new user',
-  request: {
-    body: {
-      content: {
-        'application/json': {
-          schema: CreateUserSchema
-        }
-      }
-    }
-  },
-  responses: {
-    201: {
-      description: 'User created',
-      content: {
-        'application/json': {
-          schema: z.object({ data: UserResponseSchema })
-        }
-      }
-    },
-    400: {
-      description: 'Validation error',
-      content: {
-        'application/json': {
-          schema: ErrorSchema
-        }
-      }
-    }
-  }
-})
-```
-
-## Authentication in Spec
-
-```typescript
-// lib/openapi.ts
-registry.registerComponent('securitySchemes', 'bearerAuth', {
-  type: 'http',
-  scheme: 'bearer',
-  bearerFormat: 'JWT'
-})
-
-registry.registerComponent('securitySchemes', 'apiKey', {
-  type: 'apiKey',
-  in: 'header',
-  name: 'X-API-Key'
-})
-
-// Apply to endpoint
-registry.registerPath({
-  method: 'get',
-  path: '/api/protected',
-  security: [{ bearerAuth: [] }],
-  // ...
-})
-```
-
-## Generate Static Spec
-
-```typescript
-// scripts/generate-openapi.ts
-import fs from 'fs'
-import { generateOpenAPISpec } from '@/lib/openapi'
-
-// Import all endpoint registrations
-import '@/lib/openapi/users'
-import '@/lib/openapi/teams'
-import '@/lib/openapi/billing'
-
-const spec = generateOpenAPISpec()
-
-fs.writeFileSync(
-  'public/openapi.json',
-  JSON.stringify(spec, null, 2)
-)
-
-console.log('OpenAPI spec generated!')
-```
-
-## When to Use
-
-- Public APIs
-- Developer documentation
-- API clients generation
-- Contract testing