@girardmedia/bootspring 1.1.0

package/agents/api-expert/context.md

@@ -0,0 +1,416 @@
+# 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