@girardmedia/bootspring 1.2.0 → 2.0.3

package/agents/api-expert/context.md

@@ -1,416 +0,0 @@
-# API Expert Agent
-
-## Role
-Specialized in API design, RESTful patterns, GraphQL, route handler implementation, and API documentation for modern web applications.
-
-## Core Expertise
-
-### RESTful API Design
-
-#### Resource Naming
-```
-# Good: Plural nouns, hierarchical
-GET    /api/users
-GET    /api/users/{id}
-GET    /api/users/{id}/posts
-POST   /api/users
-PATCH  /api/users/{id}
-DELETE /api/users/{id}
-
-# Avoid: Verbs in URLs
-GET    /api/getUsers        ❌
-POST   /api/createUser      ❌
-POST   /api/users/delete/1  ❌
-```
-
-#### HTTP Methods & Status Codes
-```typescript
-// GET: Retrieve resource(s)
-// 200 OK - Success
-// 404 Not Found - Resource doesn't exist
-
-// POST: Create resource
-// 201 Created - Resource created
-// 400 Bad Request - Validation failed
-// 409 Conflict - Duplicate (unique constraint)
-
-// PATCH: Partial update
-// 200 OK - Updated
-// 404 Not Found - Resource doesn't exist
-
-// PUT: Full replacement
-// 200 OK - Replaced
-// 201 Created - Created if didn't exist
-
-// DELETE: Remove resource
-// 204 No Content - Deleted
-// 404 Not Found - Resource doesn't exist
-```
-
-### Route Handler Patterns
-
-```typescript
-// app/api/posts/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { auth } from '@clerk/nextjs/server';
-import { prisma } from '@/lib/prisma';
-import { z } from 'zod';
-
-// Pagination helper
-function parsePagination(searchParams: URLSearchParams) {
-  return {
-    page: Math.max(1, parseInt(searchParams.get('page') ?? '1')),
-    limit: Math.min(100, Math.max(1, parseInt(searchParams.get('limit') ?? '20'))),
-    sort: searchParams.get('sort') ?? 'createdAt',
-    order: (searchParams.get('order') ?? 'desc') as 'asc' | 'desc',
-  };
-}
-
-// GET with filtering, sorting, pagination
-export async function GET(request: NextRequest) {
-  const { searchParams } = new URL(request.url);
-  const { page, limit, sort, order } = parsePagination(searchParams);
-
-  // Filters
-  const status = searchParams.get('status');
-  const authorId = searchParams.get('authorId');
-  const search = searchParams.get('q');
-
-  const where = {
-    ...(status && { status }),
-    ...(authorId && { authorId }),
-    ...(search && {
-      OR: [
-        { title: { contains: search, mode: 'insensitive' } },
-        { content: { contains: search, mode: 'insensitive' } },
-      ],
-    }),
-  };
-
-  const [posts, total] = await Promise.all([
-    prisma.post.findMany({
-      where,
-      skip: (page - 1) * limit,
-      take: limit,
-      orderBy: { [sort]: order },
-      include: {
-        author: { select: { id: true, name: true, avatar: true } },
-        _count: { select: { comments: true, likes: true } },
-      },
-    }),
-    prisma.post.count({ where }),
-  ]);
-
-  return NextResponse.json({
-    data: posts,
-    pagination: {
-      page,
-      limit,
-      total,
-      totalPages: Math.ceil(total / limit),
-      hasNext: page * limit < total,
-      hasPrev: page > 1,
-    },
-  });
-}
-
-// POST with validation
-const CreatePostSchema = z.object({
-  title: z.string().min(1).max(200),
-  content: z.string().min(1),
-  status: z.enum(['draft', 'published']).default('draft'),
-  tags: z.array(z.string()).optional(),
-});
-
-export async function POST(request: NextRequest) {
-  const { userId } = await auth();
-  if (!userId) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-  }
-
-  let body;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
-  }
-
-  const result = CreatePostSchema.safeParse(body);
-  if (!result.success) {
-    return NextResponse.json(
-      { error: 'Validation failed', details: result.error.flatten() },
-      { status: 400 }
-    );
-  }
-
-  const post = await prisma.post.create({
-    data: {
-      ...result.data,
-      authorId: userId,
-    },
-    include: {
-      author: { select: { id: true, name: true } },
-    },
-  });
-
-  return NextResponse.json(post, { status: 201 });
-}
-```
-
-### API Response Formats
-
-```typescript
-// Consistent response envelope
-interface ApiResponse<T> {
-  data: T;
-  meta?: {
-    pagination?: Pagination;
-    [key: string]: unknown;
-  };
-}
-
-interface ApiError {
-  error: string;
-  code?: string;
-  details?: Record<string, string[]>;
-}
-
-// Helper function
-function apiResponse<T>(data: T, meta?: Record<string, unknown>): NextResponse {
-  return NextResponse.json({ data, ...(meta && { meta }) });
-}
-
-function apiError(
-  message: string,
-  status: number,
-  details?: Record<string, unknown>
-): NextResponse {
-  return NextResponse.json(
-    { error: message, ...details },
-    { status }
-  );
-}
-
-// Usage
-return apiResponse(posts, { pagination });
-return apiError('Validation failed', 400, { details: errors });
-```
-
-### API Versioning
-
-```typescript
-// app/api/v1/users/route.ts
-// app/api/v2/users/route.ts
-
-// Or via headers
-export async function GET(request: NextRequest) {
-  const version = request.headers.get('api-version') ?? 'v1';
-
-  if (version === 'v2') {
-    // V2 response format
-    return NextResponse.json({ users: data, meta: {} });
-  }
-
-  // V1 response format (default)
-  return NextResponse.json(data);
-}
-```
-
-### Rate Limiting
-
-```typescript
-// lib/rate-limit.ts
-import { Ratelimit } from '@upstash/ratelimit';
-import { Redis } from '@upstash/redis';
-
-const ratelimit = new Ratelimit({
-  redis: Redis.fromEnv(),
-  limiter: Ratelimit.slidingWindow(100, '1 m'),
-});
-
-export async function rateLimit(identifier: string) {
-  const { success, limit, remaining, reset } = await ratelimit.limit(identifier);
-
-  return {
-    success,
-    headers: {
-      'X-RateLimit-Limit': limit.toString(),
-      'X-RateLimit-Remaining': remaining.toString(),
-      'X-RateLimit-Reset': reset.toString(),
-    },
-  };
-}
-
-// Usage in route
-export async function POST(request: NextRequest) {
-  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous';
-  const { success, headers } = await rateLimit(`api:${ip}`);
-
-  if (!success) {
-    return NextResponse.json(
-      { error: 'Too many requests' },
-      { status: 429, headers }
-    );
-  }
-
-  // Process request...
-  const response = NextResponse.json(data);
-  Object.entries(headers).forEach(([key, value]) => {
-    response.headers.set(key, value);
-  });
-  return response;
-}
-```
-
-### CORS Configuration
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-const allowedOrigins = [
-  'https://yourapp.com',
-  'https://admin.yourapp.com',
-];
-
-export function middleware(request: NextRequest) {
-  const origin = request.headers.get('origin');
-  const isApiRoute = request.nextUrl.pathname.startsWith('/api');
-
-  if (isApiRoute) {
-    // Handle preflight
-    if (request.method === 'OPTIONS') {
-      return new NextResponse(null, {
-        status: 204,
-        headers: {
-          'Access-Control-Allow-Origin': allowedOrigins.includes(origin ?? '') ? origin! : '',
-          'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
-          'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-          'Access-Control-Max-Age': '86400',
-        },
-      });
-    }
-
-    // Add CORS headers to response
-    const response = NextResponse.next();
-    if (origin && allowedOrigins.includes(origin)) {
-      response.headers.set('Access-Control-Allow-Origin', origin);
-    }
-    return response;
-  }
-
-  return NextResponse.next();
-}
-
-export const config = {
-  matcher: '/api/:path*',
-};
-```
-
-### OpenAPI Documentation
-
-```typescript
-// Using next-swagger-doc
-// lib/swagger.ts
-import { createSwaggerSpec } from 'next-swagger-doc';
-
-export const getApiDocs = () => {
-  const spec = createSwaggerSpec({
-    apiFolder: 'app/api',
-    definition: {
-      openapi: '3.0.0',
-      info: {
-        title: 'Your API',
-        version: '1.0.0',
-      },
-      components: {
-        securitySchemes: {
-          bearerAuth: {
-            type: 'http',
-            scheme: 'bearer',
-          },
-        },
-      },
-      security: [{ bearerAuth: [] }],
-    },
-  });
-  return spec;
-};
-
-// JSDoc comments in route handlers
-/**
- * @swagger
- * /api/posts:
- *   get:
- *     summary: List posts
- *     tags: [Posts]
- *     parameters:
- *       - in: query
- *         name: page
- *         schema:
- *           type: integer
- *     responses:
- *       200:
- *         description: List of posts
- */
-export async function GET(request: NextRequest) {
-  // ...
-}
-```
-
-### File Upload API
-
-```typescript
-// app/api/upload/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { put } from '@vercel/blob';
-
-export async function POST(request: NextRequest) {
-  const { userId } = await auth();
-  if (!userId) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-  }
-
-  const formData = await request.formData();
-  const file = formData.get('file') as File;
-
-  if (!file) {
-    return NextResponse.json({ error: 'No file provided' }, { status: 400 });
-  }
-
-  // Validate file
-  const maxSize = 5 * 1024 * 1024; // 5MB
-  if (file.size > maxSize) {
-    return NextResponse.json({ error: 'File too large' }, { status: 400 });
-  }
-
-  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
-  if (!allowedTypes.includes(file.type)) {
-    return NextResponse.json({ error: 'Invalid file type' }, { status: 400 });
-  }
-
-  // Upload to Vercel Blob
-  const blob = await put(file.name, file, {
-    access: 'public',
-  });
-
-  return NextResponse.json({ url: blob.url }, { status: 201 });
-}
-```
-
-## API Checklist
-
-- [ ] RESTful naming conventions
-- [ ] Proper HTTP methods used
-- [ ] Consistent response format
-- [ ] Input validation with Zod
-- [ ] Authentication required
-- [ ] Rate limiting configured
-- [ ] CORS headers set
-- [ ] Error responses standardized
-- [ ] Pagination implemented
-- [ ] API documentation added
-
-## Trigger Keywords
-api, rest, endpoint, route, handler, get, post, patch, delete, request, response, json, cors, rate limit, pagination, filter, sort, openapi, swagger, webhook