@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/integration-testing.md

@@ -0,0 +1,301 @@
+# Frontend-Backend Integration Testing
+
+> Verify the full data flow works end-to-end.
+
+## Integration Test Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    INTEGRATION FLOW                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  User Action → Frontend → API Call → Backend → Database     │
+│       │                                                      │
+│       └───────────────────────────────────────────────────┐  │
+│                                                           │  │
+│  UI Update ← Frontend ← Response ← Backend ← Database     │  │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Contract Verification
+
+### Step 1: Compare API Specs
+
+| Frontend Expects | Backend Provides | Match? |
+|------------------|------------------|--------|
+| `GET /api/users` | `GET /api/users` | ✅ |
+| `{ data: User[] }` | `{ data: User[] }` | ✅ |
+| `User.name` (string) | `User.name` (string) | ✅ |
+| `User.createdAt` | `User.created_at` | ❌ Mismatch! |
+
+### Step 2: Field Mapping
+
+```typescript
+// Common mismatches to check
+const fieldMappingChecks = {
+  // Naming convention differences
+  'created_at': 'createdAt',  // snake_case vs camelCase
+  'user_id': 'userId',
+  
+  // Type differences
+  'id': 'number vs string',
+  'date': 'ISO string vs Date object',
+  'amount': 'number vs string',
+  
+  // Nesting differences
+  'user.profile.name': 'user.name',
+  'data.items': 'items',
+};
+```
+
+### Step 3: Response Transformation
+
+```typescript
+// If backend uses snake_case, frontend uses camelCase
+function transformResponse<T>(data: any): T {
+  if (Array.isArray(data)) {
+    return data.map(transformResponse) as T;
+  }
+  
+  if (data !== null && typeof data === 'object') {
+    return Object.keys(data).reduce((result, key) => {
+      const camelKey = key.replace(/_([a-z])/g, g => g[1].toUpperCase());
+      result[camelKey] = transformResponse(data[key]);
+      return result;
+    }, {} as any);
+  }
+  
+  return data;
+}
+```
+
+---
+
+## Integration Test Checklist
+
+### For Each Endpoint
+
+```markdown
+## Endpoint: [METHOD] [PATH]
+
+### Request
+- [ ] URL is correct
+- [ ] HTTP method is correct
+- [ ] Headers are set (Auth, Content-Type)
+- [ ] Query params serialized correctly
+- [ ] Request body format matches spec
+
+### Response
+- [ ] Status code handled correctly
+- [ ] Response body parsed correctly
+- [ ] All fields mapped correctly
+- [ ] Nested objects work
+- [ ] Arrays work
+- [ ] Null/undefined handled
+
+### Error Handling
+- [ ] 400 Bad Request → validation message
+- [ ] 401 Unauthorized → redirect to login
+- [ ] 403 Forbidden → permission denied UI
+- [ ] 404 Not Found → not found UI
+- [ ] 500 Server Error → generic error UI
+- [ ] Network Error → connectivity message
+
+### Edge Cases
+- [ ] Empty response
+- [ ] Large dataset
+- [ ] Slow response (loading state)
+- [ ] Timeout
+- [ ] Concurrent requests
+```
+
+---
+
+## Test Scenarios
+
+### CRUD Operations
+
+```typescript
+describe('User CRUD Integration', () => {
+  describe('Create User', () => {
+    it('creates user with valid data', async () => {
+      // Arrange
+      const userData = { name: 'Test', email: 'test@example.com' };
+      
+      // Act
+      const result = await api.createUser(userData);
+      
+      // Assert
+      expect(result.id).toBeDefined();
+      expect(result.name).toBe(userData.name);
+      expect(result.email).toBe(userData.email);
+    });
+
+    it('shows validation errors for invalid data', async () => {
+      // Arrange
+      const invalidData = { name: '', email: 'invalid' };
+      
+      // Act & Assert
+      await expect(api.createUser(invalidData)).rejects.toMatchObject({
+        status: 422,
+        errors: expect.objectContaining({
+          name: expect.any(String),
+          email: expect.any(String)
+        })
+      });
+    });
+  });
+
+  describe('Read Users', () => {
+    it('fetches paginated user list', async () => {
+      const result = await api.getUsers({ page: 1, limit: 10 });
+      
+      expect(result.data).toBeInstanceOf(Array);
+      expect(result.total).toBeGreaterThanOrEqual(0);
+      expect(result.data.length).toBeLessThanOrEqual(10);
+    });
+
+    it('fetches single user by ID', async () => {
+      const user = await api.getUser(1);
+      
+      expect(user.id).toBe(1);
+      expect(user.name).toBeDefined();
+    });
+
+    it('returns 404 for non-existent user', async () => {
+      await expect(api.getUser(99999)).rejects.toMatchObject({
+        status: 404
+      });
+    });
+  });
+
+  describe('Update User', () => {
+    it('updates user with valid data', async () => {
+      const updates = { name: 'Updated Name' };
+      const result = await api.updateUser(1, updates);
+      
+      expect(result.name).toBe('Updated Name');
+    });
+  });
+
+  describe('Delete User', () => {
+    it('deletes user successfully', async () => {
+      await expect(api.deleteUser(1)).resolves.not.toThrow();
+    });
+  });
+});
+```
+
+### Authentication Flow
+
+```typescript
+describe('Auth Integration', () => {
+  it('completes login flow', async () => {
+    // 1. Submit login form
+    const response = await api.login({ email: 'user@test.com', password: 'password' });
+    
+    // 2. Token received
+    expect(response.token).toBeDefined();
+    
+    // 3. Token stored
+    expect(localStorage.getItem('token')).toBe(response.token);
+    
+    // 4. Subsequent requests include token
+    const profile = await api.getProfile();
+    expect(profile.email).toBe('user@test.com');
+  });
+
+  it('handles invalid credentials', async () => {
+    await expect(
+      api.login({ email: 'wrong@test.com', password: 'wrong' })
+    ).rejects.toMatchObject({ status: 401 });
+  });
+
+  it('handles expired token', async () => {
+    // Set expired token
+    localStorage.setItem('token', 'expired_token');
+    
+    // Request should fail and redirect to login
+    await expect(api.getProfile()).rejects.toMatchObject({ status: 401 });
+    
+    // Should trigger logout/redirect
+    expect(localStorage.getItem('token')).toBeNull();
+  });
+});
+```
+
+### Data Flow
+
+```typescript
+describe('Data Flow Integration', () => {
+  it('form submission to database to display', async () => {
+    // 1. User fills form
+    const formData = { title: 'New Item', description: 'Test' };
+    
+    // 2. Form submits to API
+    const created = await api.createItem(formData);
+    expect(created.id).toBeDefined();
+    
+    // 3. Data stored in database (backend handles)
+    
+    // 4. Fetch updated list
+    const list = await api.getItems();
+    
+    // 5. New item appears in list
+    expect(list.data.some(item => item.id === created.id)).toBe(true);
+  });
+});
+```
+
+---
+
+## Common Integration Issues
+
+| Issue | Symptom | Solution |
+|-------|---------|----------|
+| CORS error | Network error in browser | Backend: Add CORS headers |
+| 401 on all requests | Always unauthorized | Check auth header format |
+| Field missing | Data not displaying | Check field name mapping |
+| Type error | Crash when using data | Check type transformations |
+| Stale data | Old data after update | Invalidate cache, refetch |
+| Race condition | Inconsistent data | Add loading state, debounce |
+
+---
+
+## Integration Debug Checklist
+
+```markdown
+## When Integration Fails
+
+### 1. Check Network Tab
+- [ ] Request URL correct?
+- [ ] Request method correct?
+- [ ] Request headers correct?
+- [ ] Request body correct?
+- [ ] Response status?
+- [ ] Response body?
+
+### 2. Check Console
+- [ ] Any JavaScript errors?
+- [ ] Any CORS errors?
+- [ ] Any network errors?
+
+### 3. Check Backend Logs
+- [ ] Request received?
+- [ ] Processing error?
+- [ ] Database error?
+
+### 4. Compare Contracts
+- [ ] Field names match?
+- [ ] Data types match?
+- [ ] Required fields present?
+
+### 5. Test in Isolation
+- [ ] API works in Postman/curl?
+- [ ] Frontend works with mock?
+- [ ] Only fails when connected?
+```
+

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

@@ -0,0 +1,307 @@
+# Mock API Patterns
+
+> Frontend should never wait for backend. Use mocks, integrate later.
+
+## Mock Strategy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MOCK → REAL TRANSITION                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Phase 1: Mock Development                                   │
+│  ┌─────────────┐      ┌─────────────┐                       │
+│  │  Frontend   │ ───► │  Mock API   │                       │
+│  └─────────────┘      └─────────────┘                       │
+│                                                              │
+│  Phase 2: Integration                                        │
+│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐  │
+│  │  Frontend   │ ───► │  API Layer  │ ───► │  Real API   │  │
+│  └─────────────┘      └─────────────┘      └─────────────┘  │
+│                              │                               │
+│                              └── Toggle via config           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Mock Implementation Patterns
+
+### Pattern 1: Simple Toggle
+
+```typescript
+// config.ts
+export const USE_MOCK = process.env.NODE_ENV === 'development' && !process.env.REAL_API;
+
+// api/users.ts
+import { mockUsers } from './mocks/users';
+
+export async function getUsers() {
+  if (USE_MOCK) {
+    // Simulate network delay
+    await new Promise(r => setTimeout(r, 300));
+    return { data: mockUsers, total: mockUsers.length };
+  }
+  
+  const response = await fetch('/api/users');
+  return response.json();
+}
+```
+
+### Pattern 2: API Adapter
+
+```typescript
+// api/adapter.ts
+interface ApiAdapter {
+  getUsers(): Promise<User[]>;
+  createUser(data: UserCreate): Promise<User>;
+  getUser(id: number): Promise<User>;
+}
+
+// api/mock-adapter.ts
+export const mockAdapter: ApiAdapter = {
+  async getUsers() {
+    await delay(200);
+    return [...mockUsers];
+  },
+  async createUser(data) {
+    await delay(300);
+    const newUser = { ...data, id: Date.now(), created_at: new Date().toISOString() };
+    mockUsers.push(newUser);
+    return newUser;
+  },
+  async getUser(id) {
+    await delay(100);
+    const user = mockUsers.find(u => u.id === id);
+    if (!user) throw new ApiError(404, 'User not found');
+    return user;
+  }
+};
+
+// api/real-adapter.ts
+export const realAdapter: ApiAdapter = {
+  async getUsers() {
+    return fetchApi('/api/users');
+  },
+  async createUser(data) {
+    return fetchApi('/api/users', { method: 'POST', body: data });
+  },
+  async getUser(id) {
+    return fetchApi(`/api/users/${id}`);
+  }
+};
+
+// api/index.ts
+import { USE_MOCK } from '../config';
+export const api = USE_MOCK ? mockAdapter : realAdapter;
+```
+
+### Pattern 3: MSW (Mock Service Worker)
+
+```typescript
+// mocks/handlers.ts
+import { rest } from 'msw';
+
+export const handlers = [
+  rest.get('/api/users', (req, res, ctx) => {
+    return res(
+      ctx.delay(200),
+      ctx.json({
+        data: mockUsers,
+        total: mockUsers.length
+      })
+    );
+  }),
+
+  rest.post('/api/users', async (req, res, ctx) => {
+    const body = await req.json();
+    const newUser = {
+      id: Date.now(),
+      ...body,
+      created_at: new Date().toISOString()
+    };
+    return res(ctx.status(201), ctx.json(newUser));
+  }),
+
+  rest.get('/api/users/:id', (req, res, ctx) => {
+    const { id } = req.params;
+    const user = mockUsers.find(u => u.id === Number(id));
+    
+    if (!user) {
+      return res(
+        ctx.status(404),
+        ctx.json({ error: 'User not found' })
+      );
+    }
+    
+    return res(ctx.json(user));
+  })
+];
+
+// mocks/browser.ts
+import { setupWorker } from 'msw';
+import { handlers } from './handlers';
+
+export const worker = setupWorker(...handlers);
+
+// main.tsx
+if (process.env.NODE_ENV === 'development') {
+  const { worker } = await import('./mocks/browser');
+  await worker.start();
+}
+```
+
+---
+
+## Mock Data Generation
+
+### Static Mock Data
+
+```typescript
+// mocks/data/users.ts
+import type { User } from '@/types';
+
+export const mockUsers: User[] = [
+  {
+    id: 1,
+    email: 'admin@example.com',
+    name: 'Admin User',
+    role: 'admin',
+    created_at: '2024-01-01T00:00:00Z'
+  },
+  {
+    id: 2,
+    email: 'user@example.com',
+    name: 'Regular User',
+    role: 'user',
+    created_at: '2024-01-15T00:00:00Z'
+  },
+  // Add more as needed
+];
+```
+
+### Dynamic Mock Data (Faker)
+
+```typescript
+import { faker } from '@faker-js/faker';
+
+export function generateMockUser(overrides = {}): User {
+  return {
+    id: faker.number.int({ min: 1, max: 10000 }),
+    email: faker.internet.email(),
+    name: faker.person.fullName(),
+    role: faker.helpers.arrayElement(['admin', 'user', 'guest']),
+    created_at: faker.date.past().toISOString(),
+    ...overrides
+  };
+}
+
+export function generateMockUsers(count: number): User[] {
+  return Array.from({ length: count }, () => generateMockUser());
+}
+```
+
+---
+
+## Error Simulation
+
+```typescript
+// mocks/error-scenarios.ts
+
+export const mockWithErrors = {
+  // Simulate network error
+  async getWithNetworkError() {
+    throw new Error('Network error');
+  },
+
+  // Simulate 500 error
+  async getWithServerError() {
+    return {
+      status: 500,
+      body: { error: 'Internal server error' }
+    };
+  },
+
+  // Simulate timeout
+  async getWithTimeout() {
+    await new Promise(r => setTimeout(r, 30000));
+  },
+
+  // Simulate validation error
+  async createWithValidationError() {
+    return {
+      status: 422,
+      body: {
+        errors: {
+          email: 'Email is invalid',
+          password: 'Password too short'
+        }
+      }
+    };
+  },
+
+  // Simulate auth error
+  async getWithAuthError() {
+    return {
+      status: 401,
+      body: { error: 'Unauthorized' }
+    };
+  }
+};
+```
+
+---
+
+## Mock Configuration
+
+```typescript
+// config/mock.ts
+
+export const mockConfig = {
+  // Enable/disable mocks
+  enabled: process.env.VITE_USE_MOCK === 'true',
+  
+  // Simulate network delay (ms)
+  delay: {
+    min: 100,
+    max: 500
+  },
+  
+  // Simulate random failures (for testing error handling)
+  failureRate: 0, // 0-1, set to 0.1 for 10% failures
+  
+  // Log mock calls
+  logging: true
+};
+
+export function delay(ms?: number) {
+  const time = ms ?? Math.random() * (mockConfig.delay.max - mockConfig.delay.min) + mockConfig.delay.min;
+  return new Promise(r => setTimeout(r, time));
+}
+
+export function shouldFail() {
+  return Math.random() < mockConfig.failureRate;
+}
+```
+
+---
+
+## Transition Checklist
+
+### Before Switching to Real API
+
+- [ ] Mock covers all endpoints
+- [ ] Mock handles all error cases
+- [ ] UI works with mock data
+- [ ] Loading states implemented
+- [ ] Error states implemented
+
+### After Switching to Real API
+
+- [ ] Environment config set correctly
+- [ ] All endpoints work
+- [ ] Auth tokens handled
+- [ ] Data format matches
+- [ ] Error responses handled
+- [ ] Remove unused mock code (or keep for testing)
+