@rosetears/aili-pi 0.1.0

package/skills/fullstack-dev/references/api-design.md

@@ -0,0 +1,444 @@
+---
+name: fullstack-dev-api-design
+description: "API design patterns and best practices. Use when creating endpoints, choosing methods/status codes, implementing pagination, or writing OpenAPI specs. Prevents common REST/GraphQL/gRPC mistakes."
+license: MIT
+metadata:
+  version: "2.0.0"
+  sources:
+    - Microsoft REST API Guidelines
+    - Google API Design Guide
+    - Zalando RESTful API Guidelines
+    - JSON:API Specification
+    - RFC 9457 (Problem Details for HTTP APIs)
+    - RFC 9110 (HTTP Semantics)
+---
+
+# API Design Guidelines
+
+Framework-agnostic API design guide for backend and full-stack engineers. 50+ rules across 10 categories, prioritized by impact. Covers REST, GraphQL, and gRPC.
+
+## Scope
+
+**USE this skill when:**
+- Designing a new API or adding endpoints
+- Reviewing API pull requests
+- Choosing between REST / GraphQL / gRPC
+- Writing OpenAPI specifications
+- Migrating or versioning an existing API
+
+**NOT for:**
+- Framework-specific implementation details (use your framework's own skill/docs)
+- Frontend data fetching patterns (use React Query / SWR docs)
+- Authentication implementation details (use your auth library's docs)
+- Database schema design (→ `database-schema-design`)
+
+## Context Required
+
+Before applying this skill, gather:
+
+| Required | Optional |
+|----------|----------|
+| Target consumers (browser, mobile, service) | Existing API conventions in the project |
+| Expected request volume (RPS estimate) | Current OpenAPI / Swagger spec |
+| Authentication method (JWT, API key, OAuth) | Rate limiting requirements |
+| Data model / domain entities | Caching strategy |
+
+---
+
+## Quick Start Checklist
+
+New API endpoint? Run through this before writing code:
+
+- [ ] Resource named as **plural noun** (`/orders`, not `/getOrders`)
+- [ ] URL in **kebab-case**, body fields in **camelCase**
+- [ ] Correct **HTTP method** (GET=read, POST=create, PUT=replace, PATCH=partial, DELETE=remove)
+- [ ] Correct **status code** (201 Created, 422 Validation, 404 Not Found…)
+- [ ] Error response follows **RFC 9457** envelope
+- [ ] **Pagination** on all list endpoints (default 20, max 100)
+- [ ] **Authentication** required (Bearer token, not query param)
+- [ ] **Request ID** in response header (`X-Request-Id`)
+- [ ] **Rate limit** headers included
+- [ ] Endpoint documented in **OpenAPI spec**
+
+---
+
+## Quick Navigation
+
+| Need to… | Jump to |
+|----------|---------|
+| Name a resource URL | [1. Resource Modeling](#1-resource-modeling-critical) |
+| Pick HTTP method + status code | [3. HTTP Methods & Status Codes](#3-http-methods--status-codes-critical) |
+| Format error responses | [4. Error Handling](#4-error-handling-high) |
+| Add pagination or filtering | [6. Pagination & Filtering](#6-pagination--filtering-high) |
+| Choose API style (REST vs GraphQL vs gRPC) | [10. API Style Decision](#10-api-style-decision-tree) |
+| Version an existing API | [7. Versioning](#7-versioning-medium-high) |
+| Avoid common mistakes | [Anti-Patterns](#anti-patterns-checklist) |
+
+---
+
+## 1. Resource Modeling (CRITICAL)
+
+### Core Rules
+
+```
+✅ /users                         — plural noun
+✅ /users/{id}/orders              — 1 level nesting
+✅ /reviews?orderId={oid}          — flatten deep nesting with query params
+
+❌ /getUsers                       — verb in URL
+❌ /user                           — singular
+❌ /users/{uid}/orders/{oid}/items/{iid}/reviews  — 3+ levels deep
+```
+
+**Max nesting: 2 levels.** Beyond that, promote to top-level resource with filters.
+
+### Domain Alignment
+
+Resources map to **domain concepts**, not database tables:
+
+```
+✅ /checkout-sessions       (domain aggregate)
+✅ /shipping-labels          (domain concept)
+
+❌ /tbl_order_header          (database table leak)
+❌ /join_user_role            (internal schema leak)
+```
+
+---
+
+## 2. URL & Naming (CRITICAL)
+
+| Context | Convention | Example |
+|---------|-----------|---------|
+| URL path | kebab-case | `/order-items` |
+| JSON body fields | camelCase | `{ "firstName": "Jane" }` |
+| Query params | camelCase or snake_case (be consistent) | `?sortBy=createdAt` |
+| Headers | Train-Case | `X-Request-Id` |
+
+**Python exception:** If your entire stack is Python/snake_case, you MAY use `snake_case` in JSON — but be **consistent across all endpoints**.
+
+```
+✅ GET /users          ❌ GET /users/
+✅ GET /reports/annual  ❌ GET /reports/annual.json
+✅ POST /users          ❌ POST /users/create
+```
+
+---
+
+## 3. HTTP Methods & Status Codes (CRITICAL)
+
+### Method Semantics
+
+| Method | Semantics | Idempotent | Safe | Request Body |
+|--------|-----------|-----------|------|-------------|
+| GET | Read | ✅ | ✅ | ❌ Never |
+| POST | Create / Action | ❌ | ❌ | ✅ Always |
+| PUT | Full replace | ✅ | ❌ | ✅ Always |
+| PATCH | Partial update | ❌* | ❌ | ✅ Always |
+| DELETE | Remove | ✅ | ❌ | ❌ Rarely |
+
+### Status Code Quick Reference
+
+**Success:**
+
+| Code | When | Response Body |
+|------|------|--------------|
+| 200 OK | GET, PUT, PATCH success | Resource / result |
+| 201 Created | POST created resource | Created resource + `Location` header |
+| 202 Accepted | Async operation started | Job ID / status URL |
+| 204 No Content | DELETE success, PUT with no body | None |
+
+**Client Errors:**
+
+| Code | When | Key Distinction |
+|------|------|-----------------|
+| 400 Bad Request | Malformed syntax | Can't even parse |
+| 401 Unauthorized | Missing / invalid auth | "Who are you?" |
+| 403 Forbidden | Authenticated, no permission | "I know you, but no" |
+| 404 Not Found | Resource doesn't exist | Also use to hide 403 |
+| 409 Conflict | Duplicate, version mismatch | State conflict |
+| 422 Unprocessable | Valid syntax, failed validation | Semantic errors |
+| 429 Too Many Requests | Rate limit hit | Include `Retry-After` |
+
+**Server Errors:** 500 (unexpected), 502 (upstream fail), 503 (overloaded), 504 (upstream timeout)
+
+---
+
+## 4. Error Handling (HIGH)
+
+### Standard Error Envelope (RFC 9457)
+
+Every error response uses this format:
+
+```json
+{
+  "type": "https://api.example.com/errors/insufficient-funds",
+  "title": "Insufficient Funds",
+  "status": 422,
+  "detail": "Account balance $10.00 is less than withdrawal $50.00.",
+  "instance": "/transactions/txn_abc123",
+  "request_id": "req_7f3a8b2c",
+  "errors": [
+    { "field": "amount", "message": "Exceeds balance", "code": "INSUFFICIENT_BALANCE" }
+  ]
+}
+```
+
+### Multi-Language Implementation
+
+**TypeScript (Express):**
+```typescript
+class AppError extends Error {
+  constructor(
+    public readonly title: string,
+    public readonly status: number,
+    public readonly detail: string,
+    public readonly code: string,
+  ) { super(detail); }
+}
+
+// Middleware
+app.use((err, req, res, next) => {
+  if (err instanceof AppError) {
+    return res.status(err.status).json({
+      type: `https://api.example.com/errors/${err.code}`,
+      title: err.title, status: err.status,
+      detail: err.detail, request_id: req.id,
+    });
+  }
+  res.status(500).json({ title: 'Internal Error', status: 500, request_id: req.id });
+});
+```
+
+**Python (FastAPI):**
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+class AppError(Exception):
+    def __init__(self, title: str, status: int, detail: str, code: str):
+        self.title, self.status, self.detail, self.code = title, status, detail, code
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(status_code=exc.status, content={
+        "type": f"https://api.example.com/errors/{exc.code}",
+        "title": exc.title, "status": exc.status,
+        "detail": exc.detail, "request_id": request.state.request_id,
+    })
+```
+
+### Iron Rules
+
+```
+✅ Return RFC 9457 error envelope for ALL errors
+✅ Include request_id in every error response
+✅ Return per-field validation errors in `errors` array
+
+❌ Never expose stack traces in production
+❌ Never return 200 for errors
+❌ Never swallow errors silently
+```
+
+---
+
+## 5. Authentication & Authorization (HIGH)
+
+```
+✅ Authorization: Bearer eyJhbGci...      (header)
+❌ GET /users?token=eyJhbGci...            (URL — appears in logs)
+
+✅ 401 → "Who are you?"  (missing/invalid credentials)
+✅ 403 → "You can't do this"  (authenticated, no permission)
+✅ 404 → Hide resource existence  (use instead of 403 when needed)
+```
+
+**Rate Limit Headers (always include):**
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 42
+X-RateLimit-Reset: 1625097600
+Retry-After: 30
+```
+
+---
+
+## 6. Pagination & Filtering (HIGH)
+
+### Cursor vs Offset
+
+| Strategy | When | Pros | Cons |
+|----------|------|------|------|
+| **Cursor** (preferred) | Large/dynamic datasets | Consistent, no skips | Can't jump to page N |
+| **Offset** | Small/stable datasets, admin UIs | Simple, page jumps | Drift on insert/delete |
+
+**Cursor pagination response:**
+```json
+{
+  "data": [...],
+  "pagination": { "next_cursor": "eyJpZCI6MTIwfQ", "has_more": true }
+}
+```
+
+**Offset pagination response:**
+```json
+{
+  "data": [...],
+  "pagination": { "page": 3, "per_page": 20, "total": 256, "total_pages": 13 }
+}
+```
+
+**Always enforce:** Default 20 items, max 100 items.
+
+### Standard Filter Patterns
+
+```
+GET /orders?status=shipped&created_after=2025-01-01&sort=-created_at&fields=id,status
+```
+
+| Pattern | Convention |
+|---------|-----------|
+| Exact match | `?status=shipped` |
+| Range | `?price_gte=10&price_lte=100` |
+| Date range | `?created_after=2025-01-01&created_before=2025-12-31` |
+| Sort | `?sort=field` (asc), `?sort=-field` (desc) |
+| Sparse fields | `?fields=id,name,email` |
+| Search | `?q=search+term` |
+
+---
+
+## 7. Versioning (MEDIUM-HIGH)
+
+| Strategy | Format | Best For |
+|----------|--------|----------|
+| **URL path** (recommended) | `/v1/users` | Public APIs |
+| **Header** | `Api-Version: 2` | Internal APIs |
+| **Query param** | `?version=2` | Legacy (avoid) |
+
+**Non-breaking changes (no version bump):** New optional response fields, new endpoints, new optional params.
+
+**Breaking changes (new version required):** Removing/renaming fields, changing types, stricter validation, removing endpoints.
+
+**Deprecation headers:**
+```
+Sunset: Sat, 01 Mar 2026 00:00:00 GMT
+Deprecation: true
+Link: <https://api.example.com/v2/users>; rel="successor-version"
+```
+
+---
+
+## 8. Request / Response Design (MEDIUM)
+
+### Consistent Envelope
+
+```json
+{
+  "data": { "id": "ord_123", "status": "pending", "total": 99.50 },
+  "meta": { "request_id": "req_abc123", "timestamp": "2025-06-15T10:30:00Z" }
+}
+```
+
+### Key Rules
+
+| Rule | Correct | Wrong |
+|------|---------|-------|
+| Timestamps | `"2025-06-15T10:30:00Z"` (ISO 8601) | `"06/15/2025"` or `1718447400` |
+| Public IDs | UUID `"550e8400-..."` | Auto-increment `42` |
+| Null vs absent (PATCH) | `{ "nickname": null }` = clear field | Absent field = don't change |
+| HATEOAS (public APIs) | `"links": { "cancel": "/orders/123/cancel" }` | No discoverability |
+
+---
+
+## 9. Documentation — OpenAPI (MEDIUM)
+
+**Design-first workflow:**
+
+```
+1. Write OpenAPI 3.1 spec
+2. Review spec with stakeholders
+3. Generate server stubs + client SDKs
+4. Implement handlers
+5. Validate responses against spec in CI
+```
+
+Every endpoint documents: summary, all parameters, request body + examples, all response codes + schemas, auth requirements.
+
+---
+
+## 10. API Style Decision Tree
+
+```
+What kind of API?
+│
+├─ Browser + mobile clients, flexible queries
+│   └─ GraphQL
+│       Rules: DataLoader (no N+1), depth limit ≤7, Relay pagination
+│
+├─ Standard CRUD, public consumers, caching important
+│   └─ REST (this guide)
+│       Rules: Resources, HTTP methods, status codes, OpenAPI
+│
+├─ Service-to-service, high throughput, strong typing
+│   └─ gRPC
+│       Rules: Protobuf schemas, streaming for large data, deadlines
+│
+├─ Full-stack TypeScript, same team owns client + server
+│   └─ tRPC
+│       Rules: Shared types, no code generation needed
+│
+└─ Real-time bidirectional
+    └─ WebSocket / SSE
+        Rules: Heartbeat, reconnection, message ordering
+```
+
+---
+
+## Anti-Patterns Checklist
+
+| # | ❌ Don't | ✅ Do Instead |
+|---|---------|--------------|
+| 1 | Verbs in URLs (`/getUser`) | HTTP methods + noun resources |
+| 2 | Return 200 for errors | Correct 4xx/5xx status codes |
+| 3 | Mix naming styles | One convention per context |
+| 4 | Expose database IDs | UUIDs for public identifiers |
+| 5 | No pagination on lists | Always paginate (default 20) |
+| 6 | Swallow errors silently | Structured RFC 9457 errors |
+| 7 | Token in URL query | Authorization header |
+| 8 | Deep nesting (3+ levels) | Flatten with query params |
+| 9 | Break changes without version | Maintain compatibility or version |
+| 10 | No rate limiting | Implement + communicate via headers |
+| 11 | No request ID | `X-Request-Id` on every response |
+| 12 | Stack traces in production | Safe error message + internal log |
+
+---
+
+## Common Issues
+
+### Issue 1: "Should this be a new resource or a sub-resource?"
+
+**Symptom:** URL path keeps growing (`/users/{id}/orders/{id}/items/{id}/reviews`)
+
+**Rule:** If the child entity makes sense on its own, promote it. If it only exists within the parent context, keep it nested (max 2 levels).
+
+```
+/reviews?orderId=123      ✅  (reviews exist independently)
+/orders/{id}/items         ✅  (items belong to orders, 1 level)
+```
+
+### Issue 2: "PUT or PATCH?"
+
+**Symptom:** Team can't agree on update semantics.
+
+**Rule:**
+- PUT = client sends **complete** resource (missing fields → set to default/null)
+- PATCH = client sends **only changed fields** (missing fields → unchanged)
+- When unsure → **PATCH** (safer, less surprising)
+
+### Issue 3: "400 or 422?"
+
+**Symptom:** Inconsistent validation error codes.
+
+**Rule:**
+- 400 = can't parse request at all (malformed JSON, wrong content-type)
+- 422 = parsed OK, but values fail validation (invalid email, negative quantity)

package/skills/fullstack-dev/references/auth-flow.md

@@ -0,0 +1,165 @@
+# Authentication Flow Patterns
+
+Complete auth flow across frontend and backend. Covers JWT bearer flow, automatic token refresh, Next.js server-side auth, RBAC, and backend middleware order.
+
+---
+
+## JWT Bearer Flow (Most Common)
+
+```
+1. Login
+   Client → POST /api/auth/login { email, password }
+   Server → { accessToken (15min), refreshToken (7d, httpOnly cookie) }
+
+2. Authenticated Requests
+   Client → GET /api/orders  Authorization: Bearer <accessToken>
+   Server → validates JWT → returns data
+
+3. Token Refresh (transparent)
+   Client → 401 received → POST /api/auth/refresh (cookie auto-sent)
+   Server → new accessToken
+   Client → retry original request with new token
+
+4. Logout
+   Client → POST /api/auth/logout
+   Server → invalidate refresh token → clear cookie
+```
+
+---
+
+## Frontend: Automatic Token Refresh
+
+```typescript
+// lib/api-client.ts — add to existing fetch wrapper
+async function apiWithRefresh<T>(path: string, options: RequestInit = {}): Promise<T> {
+  try {
+    return await api<T>(path, options);
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) {
+      // Try refresh
+      const refreshed = await api<{ accessToken: string }>('/api/auth/refresh', {
+        method: 'POST',
+        credentials: 'include',  // send httpOnly cookie
+      });
+      setAuthToken(refreshed.accessToken);
+      // Retry original request
+      return api<T>(path, options);
+    }
+    throw err;
+  }
+}
+```
+
+---
+
+## Next.js: Server-Side Auth (App Router)
+
+```typescript
+// middleware.ts — protect routes server-side
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('session')?.value;
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  return NextResponse.next();
+}
+
+// app/dashboard/page.tsx — server component with auth
+import { cookies } from 'next/headers';
+
+export default async function Dashboard() {
+  const token = (await cookies()).get('session')?.value;
+  const user = await fetch(`${process.env.API_URL}/api/me`, {
+    headers: { Authorization: `Bearer ${token}` },
+  }).then(r => r.json());
+
+  return <DashboardContent user={user} />;
+}
+```
+
+---
+
+## Backend: Standard Middleware Order
+
+```
+Request → 1.RequestID → 2.Logging → 3.CORS → 4.RateLimit → 5.BodyParse
+       → 6.Auth → 7.Authz → 8.Validation → 9.Handler → 10.ErrorHandler → Response
+```
+
+---
+
+## Backend: JWT Rules
+
+```
+✅ Short expiry access token (15min) + refresh token (server-stored)
+✅ Minimal claims: userId, roles (not entire user object)
+✅ Rotate signing keys periodically
+
+❌ Never store tokens in localStorage (XSS risk)
+❌ Never pass tokens in URL query params
+```
+
+---
+
+## Backend: RBAC Pattern
+
+```typescript
+function authorize(...roles: Role[]) {
+  return (req, res, next) => {
+    if (!req.user) throw new UnauthorizedError();
+    if (!roles.some(r => req.user.roles.includes(r))) throw new ForbiddenError();
+    next();
+  };
+}
+router.delete('/users/:id', authenticate, authorize('admin'), deleteUser);
+```
+
+---
+
+## Auth Decision Table
+
+| Method | When | Frontend |
+|--------|------|----------|
+| Session | Same-domain, SSR, Django templates | Django templates / htmx |
+| JWT | Different domain, SPA, mobile | React, Vue, mobile apps |
+| OAuth2 | Third-party login, API consumers | Any |
+
+---
+
+## Iron Rules
+
+```
+✅ Access token: short-lived (15min), in memory
+✅ Refresh token: httpOnly cookie (XSS-safe)
+✅ Automatic transparent refresh on 401
+✅ Redirect to login when refresh fails
+
+❌ Never store tokens in localStorage (XSS risk)
+❌ Never send tokens in URL query params (logged)
+❌ Never trust client-side auth checks alone (server must validate)
+```
+
+---
+
+## Common Issues
+
+### Issue 1: "Auth works on page load but breaks on navigation"
+
+**Cause:** Token stored in component state (lost on unmount).
+
+**Fix:** Store access token in a persistent location:
+- React Context (survives navigation, lost on refresh)
+- Cookie (survives refresh)
+- React Query cache with `staleTime: Infinity` for session
+
+### Issue 2: "CORS error with auth requests"
+
+**Cause:** Missing `credentials: 'include'` on frontend or `credentials: true` on backend CORS config.
+
+**Fix:**
+1. Frontend: `fetch(url, { credentials: 'include' })`
+2. Backend: `cors({ origin: 'https://your-frontend.com', credentials: true })`
+3. Backend: explicit origin (not `*`) when using credentials