@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/api-contract-guide.md

@@ -0,0 +1,312 @@
+# API Contract Guide
+
+> Define APIs before implementation. Swagger/OpenAPI is MANDATORY.
+
+## API-First Development
+
+### Workflow
+
+```
+1. Write OpenAPI spec
+2. Review with frontend
+3. Generate server stubs (optional)
+4. Implement endpoints
+5. Validate against spec
+6. Deploy with Swagger UI
+```
+
+---
+
+## OpenAPI Specification Template
+
+```yaml
+openapi: 3.0.3
+info:
+  title: API Name
+  description: API description
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8000/api
+    description: Development
+  - url: https://api.example.com
+    description: Production
+
+paths:
+  /users:
+    get:
+      summary: List all users
+      tags: [Users]
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  total:
+                    type: integer
+        401:
+          $ref: '#/components/responses/Unauthorized'
+    
+    post:
+      summary: Create user
+      tags: [Users]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserCreate'
+      responses:
+        201:
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        400:
+          $ref: '#/components/responses/BadRequest'
+        422:
+          $ref: '#/components/responses/ValidationError'
+
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      tags: [Users]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        404:
+          $ref: '#/components/responses/NotFound'
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, name]
+      properties:
+        id:
+          type: integer
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+    
+    UserCreate:
+      type: object
+      required: [email, name, password]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 2
+        password:
+          type: string
+          minLength: 8
+
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: object
+
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    ValidationError:
+      description: Validation failed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearerAuth: []
+```
+
+---
+
+## Framework Integration
+
+### Python FastAPI
+
+```python
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+app = FastAPI(
+    title="My API",
+    description="API description",
+    version="1.0.0",
+    docs_url="/docs",  # Swagger UI
+    redoc_url="/redoc",  # ReDoc
+)
+
+# Custom OpenAPI schema
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+    openapi_schema = get_openapi(
+        title="My API",
+        version="1.0.0",
+        routes=app.routes,
+    )
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+app.openapi = custom_openapi
+```
+
+### Node.js Express
+
+```javascript
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerUi = require('swagger-ui-express');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'My API',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./routes/*.js'],
+};
+
+const specs = swaggerJsdoc(options);
+app.use('/docs', swaggerUi.serve, swaggerUi.setup(specs));
+```
+
+---
+
+## Contract Verification Checklist
+
+### Before Implementation
+
+- [ ] OpenAPI spec written
+- [ ] All endpoints documented
+- [ ] Request/response schemas defined
+- [ ] Error responses documented
+- [ ] Auth requirements specified
+- [ ] Frontend team reviewed and approved
+
+### After Implementation
+
+- [ ] Swagger UI accessible
+- [ ] All endpoints match spec
+- [ ] Response schemas validated
+- [ ] Error codes match documentation
+- [ ] Examples work in Swagger UI
+
+---
+
+## Frontend Mock Generation
+
+From OpenAPI spec, generate mocks:
+
+```typescript
+// Generated from OpenAPI spec
+export interface User {
+  id: number;
+  email: string;
+  name: string;
+  created_at: string;
+}
+
+export interface UserCreate {
+  email: string;
+  name: string;
+  password: string;
+}
+
+// Mock data matching schema
+export const mockUsers: User[] = [
+  {
+    id: 1,
+    email: 'user@example.com',
+    name: 'Test User',
+    created_at: '2024-01-01T00:00:00Z'
+  }
+];
+
+// Mock API matching endpoints
+export const mockApi = {
+  getUsers: async (): Promise<{ data: User[], total: number }> => {
+    return { data: mockUsers, total: mockUsers.length };
+  },
+  
+  createUser: async (data: UserCreate): Promise<User> => {
+    return { ...mockUsers[0], ...data, id: Date.now() };
+  },
+  
+  getUser: async (id: number): Promise<User> => {
+    const user = mockUsers.find(u => u.id === id);
+    if (!user) throw new Error('Not found');
+    return user;
+  }
+};
+```
+

package/.claude/skills/fullstack-developer/references/api-response-patterns.md

@@ -0,0 +1,223 @@
+# API Response Patterns
+
+Best practices for handling API responses, especially distinguishing HTTP status from business status.
+
+## The HTTP vs Business Status Problem
+
+**Common Bug**: Treating HTTP 200 as "success" when the response body contains a business error.
+
+```
+HTTP 200 OK
+{
+  "code": -1,
+  "message": "User not found",
+  "data": null
+}
+```
+
+This is HTTP success but **business failure**. Code that only checks HTTP status will miss this.
+
+## Common Response Patterns
+
+### Pattern A: Numeric Code
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 200 | Success (alternative) |
+| -1, 400, 500, etc. | Error |
+
+### Pattern B: Boolean Success
+
+```json
+{
+  "success": true,
+  "result": { ... }
+}
+```
+
+```json
+{
+  "success": false,
+  "error": "Invalid input"
+}
+```
+
+### Pattern C: String Status
+
+```json
+{
+  "status": "success",
+  "payload": { ... }
+}
+```
+
+```json
+{
+  "status": "error",
+  "message": "Something went wrong"
+}
+```
+
+### Pattern D: Error-First
+
+```json
+{
+  "error": null,
+  "data": { ... }
+}
+```
+
+```json
+{
+  "error": {
+    "code": "INVALID_INPUT",
+    "message": "Email is required"
+  },
+  "data": null
+}
+```
+
+## Response Validation Checklist
+
+### 1. Identify Response Structure
+
+- [ ] What field indicates success/failure? (code, success, status, error)
+- [ ] What are the success values? (0, 200, true, "success", null error)
+- [ ] Where is the error message? (message, msg, error, error.message)
+- [ ] Where is the payload? (data, result, payload, body)
+
+### 2. Define Success Condition
+
+```javascript
+// Bad: Only check HTTP status
+const isSuccess = response.status === 200;
+
+// Good: Check HTTP status AND business status
+const isSuccess = response.status === 200 && 
+  (data.code === 0 || data.code === 200 || data.success === true);
+```
+
+### 3. Extract Error Information
+
+```javascript
+// Handle multiple error message locations
+const errorMessage = 
+  data.message || 
+  data.msg || 
+  data.error?.message || 
+  data.error || 
+  `HTTP ${response.status}`;
+```
+
+### 4. Handle Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Non-JSON response | Fallback to HTTP status text |
+| Empty body | Treat as success if HTTP 2xx |
+| Network timeout | Explicit error with retry option |
+| Partial response | Validate required fields before use |
+
+## Implementation Pattern
+
+### Backend (Python example)
+
+```python
+def check_business_status(response_body: str) -> tuple[bool, str]:
+    """
+    Check business status from response body.
+    Returns (is_success, error_message).
+    """
+    try:
+        data = json.loads(response_body)
+        
+        # Pattern A: Numeric code
+        if "code" in data:
+            success_codes = [0, 200, "0", "200"]
+            if data["code"] not in success_codes:
+                return False, data.get("message") or f"Error code: {data['code']}"
+        
+        # Pattern B: Boolean success
+        if "success" in data:
+            if not data["success"]:
+                return False, data.get("message") or "Operation failed"
+        
+        # Pattern C: String status
+        if "status" in data and isinstance(data["status"], str):
+            if data["status"].lower() in ["error", "fail", "failed"]:
+                return False, data.get("message") or f"Status: {data['status']}"
+        
+        return True, ""
+    except (json.JSONDecodeError, TypeError):
+        return True, ""  # Let HTTP status decide
+```
+
+### Frontend (TypeScript example)
+
+```typescript
+interface ApiResponse<T> {
+  code?: number;
+  success?: boolean;
+  status?: string;
+  message?: string;
+  msg?: string;
+  error?: string | { message: string };
+  data?: T;
+}
+
+function isBusinessSuccess<T>(response: ApiResponse<T>): boolean {
+  // Check code field
+  if (response.code !== undefined) {
+    return [0, 200].includes(response.code);
+  }
+  // Check success field
+  if (response.success !== undefined) {
+    return response.success === true;
+  }
+  // Check status field
+  if (typeof response.status === 'string') {
+    return !['error', 'fail', 'failed'].includes(response.status.toLowerCase());
+  }
+  // No business status field, assume success
+  return true;
+}
+
+function extractErrorMessage<T>(response: ApiResponse<T>): string {
+  return response.message 
+    || response.msg 
+    || (typeof response.error === 'string' ? response.error : response.error?.message)
+    || 'Unknown error';
+}
+```
+
+## Testing Checklist
+
+| Test Case | Input | Expected Behavior |
+|-----------|-------|-------------------|
+| HTTP 200, code 0 | Success response | Treat as success |
+| HTTP 200, code -1 | Business error | Treat as failure, show message |
+| HTTP 200, success false | Business error | Treat as failure |
+| HTTP 500 | Server error | Treat as error |
+| HTTP 200, empty body | Edge case | Treat as success |
+| HTTP 200, non-JSON | Edge case | Fallback to HTTP status |
+| Network timeout | Edge case | Show timeout error |
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Only check HTTP status | Miss business errors | Also check response body |
+| Assume response shape | Crash on unexpected structure | Defensive parsing |
+| Hardcode error field | Miss alternative locations | Check multiple fields |
+| Ignore non-JSON | Crash on HTML error pages | Type check before parse |
+| No timeout handling | Hung requests | Set timeout, show message |
+