autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/rest-api.md

@@ -0,0 +1,490 @@
+# REST API Skill
+
+## RESTful Route Design
+\`\`\`
+# Resources use nouns (plural)
+GET    /api/users          # List users
+GET    /api/users/:id      # Get single user
+POST   /api/users          # Create user
+PUT    /api/users/:id      # Replace user (full update)
+PATCH  /api/users/:id      # Partial update
+DELETE /api/users/:id      # Delete user
+
+# Nested resources
+GET    /api/users/:id/posts        # User's posts
+POST   /api/users/:id/posts        # Create post for user
+GET    /api/posts/:id/comments     # Post's comments
+
+# Actions (when CRUD doesn't fit)
+POST   /api/users/:id/verify       # Verify user
+POST   /api/posts/:id/publish      # Publish post
+POST   /api/auth/login             # Login
+POST   /api/auth/logout            # Logout
+
+# Filtering, sorting, pagination
+GET /api/users?status=active&role=admin
+GET /api/users?sort=created_at&order=desc
+GET /api/users?page=2&limit=20
+GET /api/users?cursor=abc123&limit=20
+GET /api/posts?search=typescript&tags=react,node
+\`\`\`
+
+## Express.js Implementation
+\`\`\`typescript
+// routes/users.ts
+import { Router } from 'express';
+import { z } from 'zod';
+import { prisma } from '../lib/prisma';
+import { authenticate } from '../middleware/auth';
+import { validate } from '../middleware/validate';
+import { ApiError } from '../lib/errors';
+
+const router = Router();
+
+// Validation schemas
+const createUserSchema = z.object({
+  body: z.object({
+    email: z.string().email(),
+    name: z.string().min(2).max(100),
+    password: z.string().min(8),
+  }),
+});
+
+const updateUserSchema = z.object({
+  body: z.object({
+    name: z.string().min(2).max(100).optional(),
+    bio: z.string().max(500).optional(),
+  }),
+  params: z.object({
+    id: z.string().uuid(),
+  }),
+});
+
+const listUsersSchema = z.object({
+  query: z.object({
+    page: z.coerce.number().min(1).default(1),
+    limit: z.coerce.number().min(1).max(100).default(20),
+    status: z.enum(['active', 'inactive']).optional(),
+    search: z.string().optional(),
+  }),
+});
+
+// List users with pagination
+router.get('/', validate(listUsersSchema), async (req, res) => {
+  const { page, limit, status, search } = req.query;
+
+  const where = {
+    ...(status && { status }),
+    ...(search && {
+      OR: [
+        { name: { contains: search, mode: 'insensitive' } },
+        { email: { contains: search, mode: 'insensitive' } },
+      ],
+    }),
+  };
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      where,
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { createdAt: 'desc' },
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        createdAt: true,
+      },
+    }),
+    prisma.user.count({ where }),
+  ]);
+
+  res.json({
+    data: users,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  });
+});
+
+// Get single user
+router.get('/:id', async (req, res) => {
+  const user = await prisma.user.findUnique({
+    where: { id: req.params.id },
+    select: {
+      id: true,
+      name: true,
+      email: true,
+      bio: true,
+      createdAt: true,
+    },
+  });
+
+  if (!user) {
+    throw new ApiError(404, 'USER_NOT_FOUND', 'User not found');
+  }
+
+  res.json({ data: user });
+});
+
+// Create user
+router.post('/', validate(createUserSchema), async (req, res) => {
+  const { email, name, password } = req.body;
+
+  const existing = await prisma.user.findUnique({ where: { email } });
+  if (existing) {
+    throw new ApiError(409, 'EMAIL_EXISTS', 'Email already registered');
+  }
+
+  const hashedPassword = await bcrypt.hash(password, 12);
+  const user = await prisma.user.create({
+    data: { email, name, password: hashedPassword },
+    select: { id: true, email: true, name: true },
+  });
+
+  res.status(201).json({ data: user });
+});
+
+// Update user (partial)
+router.patch('/:id', authenticate, validate(updateUserSchema), async (req, res) => {
+  if (req.user.id !== req.params.id && req.user.role !== 'admin') {
+    throw new ApiError(403, 'FORBIDDEN', 'Not authorized');
+  }
+
+  const user = await prisma.user.update({
+    where: { id: req.params.id },
+    data: req.body,
+    select: { id: true, name: true, bio: true },
+  });
+
+  res.json({ data: user });
+});
+
+// Delete user
+router.delete('/:id', authenticate, async (req, res) => {
+  if (req.user.id !== req.params.id && req.user.role !== 'admin') {
+    throw new ApiError(403, 'FORBIDDEN', 'Not authorized');
+  }
+
+  await prisma.user.delete({ where: { id: req.params.id } });
+  res.status(204).send();
+});
+
+export default router;
+\`\`\`
+
+## Next.js App Router API
+\`\`\`typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import { prisma } from '@/lib/prisma';
+import { getSession } from '@/lib/auth';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+});
+
+// GET /api/users
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const page = Number(searchParams.get('page')) || 1;
+  const limit = Math.min(Number(searchParams.get('limit')) || 20, 100);
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+    }),
+    prisma.user.count(),
+  ]);
+
+  return NextResponse.json({
+    data: users,
+    meta: { page, limit, total },
+  });
+}
+
+// POST /api/users
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const validated = createUserSchema.parse(body);
+
+    const user = await prisma.user.create({
+      data: validated,
+    });
+
+    return NextResponse.json({ data: user }, { status: 201 });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        {
+          error: {
+            code: 'VALIDATION_ERROR',
+            message: 'Invalid input',
+            details: error.errors,
+          },
+        },
+        { status: 400 }
+      );
+    }
+    throw error;
+  }
+}
+
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  const user = await prisma.user.findUnique({
+    where: { id: params.id },
+  });
+
+  if (!user) {
+    return NextResponse.json(
+      { error: { code: 'NOT_FOUND', message: 'User not found' } },
+      { status: 404 }
+    );
+  }
+
+  return NextResponse.json({ data: user });
+}
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  const session = await getSession();
+  if (!session) {
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Not authenticated' } },
+      { status: 401 }
+    );
+  }
+
+  const body = await request.json();
+  const user = await prisma.user.update({
+    where: { id: params.id },
+    data: body,
+  });
+
+  return NextResponse.json({ data: user });
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  await prisma.user.delete({ where: { id: params.id } });
+  return new NextResponse(null, { status: 204 });
+}
+\`\`\`
+
+## Middleware
+\`\`\`typescript
+// middleware/auth.ts
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { ApiError } from '../lib/errors';
+
+export async function authenticate(
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    throw new ApiError(401, 'UNAUTHORIZED', 'Missing authentication token');
+  }
+
+  const token = authHeader.split(' ')[1];
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
+    req.user = decoded as User;
+    next();
+  } catch {
+    throw new ApiError(401, 'INVALID_TOKEN', 'Invalid or expired token');
+  }
+}
+
+// middleware/validate.ts
+import { Request, Response, NextFunction } from 'express';
+import { AnyZodObject, ZodError } from 'zod';
+
+export function validate(schema: AnyZodObject) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await schema.parseAsync({
+        body: req.body,
+        query: req.query,
+        params: req.params,
+      });
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        res.status(400).json({
+          error: {
+            code: 'VALIDATION_ERROR',
+            message: 'Invalid request data',
+            details: error.errors.map((e) => ({
+              field: e.path.join('.'),
+              message: e.message,
+            })),
+          },
+        });
+      } else {
+        next(error);
+      }
+    }
+  };
+}
+
+// middleware/rateLimit.ts
+import rateLimit from 'express-rate-limit';
+
+export const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  message: {
+    error: {
+      code: 'TOO_MANY_REQUESTS',
+      message: 'Too many requests, please try again later',
+    },
+  },
+});
+\`\`\`
+
+## Error Handling
+\`\`\`typescript
+// lib/errors.ts
+export class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+// middleware/errorHandler.ts
+import { Request, Response, NextFunction } from 'express';
+import { ApiError } from '../lib/errors';
+
+export function errorHandler(
+  error: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  console.error(error);
+
+  if (error instanceof ApiError) {
+    return res.status(error.statusCode).json({
+      error: {
+        code: error.code,
+        message: error.message,
+        ...(error.details && { details: error.details }),
+      },
+    });
+  }
+
+  // Default to 500
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  });
+}
+\`\`\`
+
+## HTTP Status Codes
+\`\`\`
+# Success
+200 OK              - GET, PUT, PATCH success
+201 Created         - POST success (include Location header)
+204 No Content      - DELETE success
+
+# Client Errors
+400 Bad Request     - Validation error, malformed request
+401 Unauthorized    - Missing/invalid authentication
+403 Forbidden       - Authenticated but not authorized
+404 Not Found       - Resource doesn't exist
+409 Conflict        - Duplicate resource, state conflict
+422 Unprocessable   - Valid JSON but semantic errors
+429 Too Many Reqs   - Rate limited
+
+# Server Errors
+500 Internal Error  - Unexpected server error
+502 Bad Gateway     - Upstream service error
+503 Unavailable     - Temporarily unavailable
+\`\`\`
+
+## Response Formats
+\`\`\`json
+// Success with data
+{
+  "data": { "id": "1", "name": "John" }
+}
+
+// Success with list and pagination
+{
+  "data": [{ "id": "1" }, { "id": "2" }],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+
+// Cursor pagination
+{
+  "data": [...],
+  "meta": {
+    "nextCursor": "abc123",
+    "hasMore": true
+  }
+}
+
+// Error
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ]
+  }
+}
+\`\`\`
+
+## ❌ DON'T
+- Use verbs in URLs (/api/getUsers)
+- Return 200 for errors
+- Expose internal error details
+- Skip input validation
+- Ignore authentication/authorization
+- Use inconsistent response formats
+
+## ✅ DO
+- Use plural nouns for resources
+- Return appropriate status codes
+- Validate all inputs with schema
+- Use consistent error format
+- Implement pagination for lists
+- Add rate limiting
+- Include CORS headers
+- Version your API (/api/v1/...)
+- Document with OpenAPI/Swagger