@dbs-portal/tool-mock/docs/API.md

API mocking toolkit using MSW for DBS Portal development workflows

# API Reference - @dbs-portal/tool-mock

Complete API reference for the DBS Portal MSW mocking toolkit.

## Core Setup

### setupMocks(options?)

Sets up MSW based on the current environment with automatic detection.

```typescript
import { setupMocks } from '@dbs-portal/tool-mock'

await setupMocks({
  config: {
    enabled: true,
    mode: 'development',
    logging: true,
    delay: [100, 300],
  },
  handlers: [/* custom handlers */],
  start: true, // Start immediately
})
```

**Parameters:**
- `options.config` - Mock configuration overrides
- `options.handlers` - Additional request handlers
- `options.start` - Whether to start MSW immediately (default: true)

### teardownMocks()

Cleanly shuts down MSW and cleans up resources.

```typescript
import { teardownMocks } from '@dbs-portal/tool-mock'

await teardownMocks()
```

### autoSetupMocks(handlers?)

Convenience function that automatically sets up MSW based on environment variables.

```typescript
import { autoSetupMocks } from '@dbs-portal/tool-mock'

await autoSetupMocks([
  // Optional custom handlers
])
```

## Configuration

### MockConfig Interface

```typescript
interface MockConfig {
  enabled: boolean
  mode: 'development' | 'testing' | 'storybook' | 'disabled'
  baseUrl?: string
  delay?: number | [number, number]
  logging?: boolean
  handlers?: RequestHandler[]
  errorSimulation?: ErrorSimulationConfig
}
```

### updateMockConfig(config)

Updates the global mock configuration.

```typescript
import { updateMockConfig } from '@dbs-portal/tool-mock'

updateMockConfig({
  delay: [200, 500],
  logging: false,
  errorSimulation: {
    networkErrorRate: 0.01,
    serverErrorRate: 0.005,
  },
})
```

### getMockConfig()

Returns the current mock configuration.

```typescript
import { getMockConfig } from '@dbs-portal/tool-mock'

const config = getMockConfig()
console.log('Current delay:', config.delay)
```

## Handler Factories

### createCrudHandlers(options)

Creates a complete set of CRUD handlers for a resource.

```typescript
import { createCrudHandlers } from '@dbs-portal/tool-mock'

const userHandlers = createCrudHandlers({
  basePath: '/api/users',
  dataFactory: (overrides = {}) => ({
    id: generateId(),
    email: 'user@example.com',
    firstName: 'John',
    lastName: 'Doe',
    createdAt: new Date().toISOString(),
    ...overrides,
  }),
  initialData: [
    { id: '1', email: 'admin@example.com', firstName: 'Admin', lastName: 'User' },
  ],
  pagination: {
    defaultPageSize: 10,
    maxPageSize: 100,
  },
  validate: (data) => {
    const errors = []
    if (!data.email) errors.push('Email is required')
    if (!data.firstName) errors.push('First name is required')
    return errors.length > 0 ? errors : null
  },
})
```

**Generated Endpoints:**
- `GET /api/users` - List with pagination and filtering
- `GET /api/users/:id` - Get single item
- `POST /api/users` - Create new item
- `PUT /api/users/:id` - Update existing item
- `PATCH /api/users/:id` - Partial update
- `DELETE /api/users/:id` - Delete item

### createAuthHandlers(basePath)

Creates authentication-related handlers.

```typescript
import { createAuthHandlers } from '@dbs-portal/tool-mock'

const authHandlers = createAuthHandlers('/api/auth', {
  users: [
    {
      id: '1',
      email: 'admin@example.com',
      password: 'password',
      roles: ['admin'],
      permissions: ['users:read', 'users:write'],
    },
  ],
  tokenExpiry: '1h',
  refreshTokenExpiry: '7d',
})
```

**Generated Endpoints:**
- `POST /api/auth/login` - User authentication
- `POST /api/auth/logout` - User logout
- `POST /api/auth/refresh` - Token refresh
- `GET /api/auth/me` - Current user info
- `POST /api/auth/register` - User registration (optional)

### createHandler(method, path, options)

Creates a single custom handler with built-in utilities.

```typescript
import { createHandler } from '@dbs-portal/tool-mock'

const customHandler = createHandler('GET', '/api/custom', {
  response: (request) => ({
    success: true,
    data: { message: 'Custom response' },
    timestamp: new Date().toISOString(),
  }),
  delay: [100, 200],
  status: 200,
  headers: { 'X-Custom-Header': 'value' },
})
```

## Data Factories

### createDataFactory(template)

Creates a reusable data factory function.

```typescript
import { createDataFactory, generateId } from '@dbs-portal/tool-mock'

const userFactory = createDataFactory((overrides = {}) => ({
  id: generateId(),
  email: `user${Math.random()}@example.com`,
  firstName: 'John',
  lastName: 'Doe',
  isActive: true,
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
  ...overrides,
}))

// Usage
const user1 = userFactory()
const user2 = userFactory({ firstName: 'Jane', email: 'jane@example.com' })
```

### createListFactory(itemFactory, count?)

Creates a factory for generating lists of items.

```typescript
import { createListFactory } from '@dbs-portal/tool-mock'

const userListFactory = createListFactory(userFactory, 10)

// Generate 10 users
const users = userListFactory()

// Generate 5 users with overrides
const customUsers = userListFactory(5, { isActive: false })
```

### Built-in Generators

```typescript
import {
  generateId,
  generateEmail,
  generateName,
  generateDate,
  generateBoolean,
  generateNumber,
  generateString,
} from '@dbs-portal/tool-mock'

const mockData = {
  id: generateId(), // UUID v4
  email: generateEmail(), // random@example.com
  name: generateName(), // Random first/last name
  birthDate: generateDate('1980-01-01', '2000-12-31'),
  isActive: generateBoolean(0.8), // 80% chance of true
  score: generateNumber(0, 100),
  description: generateString(50, 200), // Random string 50-200 chars
}
```

## Response Building

### mockResponseBuilder()

Fluent API for building complex mock responses.

```typescript
import { mockResponseBuilder } from '@dbs-portal/tool-mock'

const response = mockResponseBuilder()
  .data({ users: userListFactory(5) })
  .status(200)
  .headers({ 'X-Total-Count': '5' })
  .delay([100, 300])
  .build()
```

### Pagination Helpers

```typescript
import { createPaginatedResponse } from '@dbs-portal/tool-mock'

const paginatedUsers = createPaginatedResponse({
  items: userListFactory(50),
  page: 1,
  pageSize: 10,
  total: 50,
})
```

### Error Responses

```typescript
import { createErrorResponse } from '@dbs-portal/tool-mock'

const errorResponse = createErrorResponse({
  code: 'VALIDATION_ERROR',
  message: 'Invalid input data',
  details: {
    email: ['Email is required'],
    firstName: ['First name must be at least 2 characters'],
  },
  status: 400,
})
```

## Integration Utilities

### createMockAwareApiClient(config)

Creates an API client with MSW integration.

```typescript
import { createMockAwareApiClient } from '@dbs-portal/tool-mock'

const apiClient = await createMockAwareApiClient({
  baseURL: '/api',
  enableMocking: true,
  mockConfig: {
    mode: 'development',
    logging: true,
    delay: 200,
  },
  mockHandlers: [
    ...userHandlers,
    ...authHandlers,
  ],
})

// Check if mocking is active
if (apiClient.isMocking()) {
  console.log('Using mocked responses')
}
```

### withMockAuth(handlers, authConfig?)

Wraps handlers with authentication requirements.

```typescript
import { withMockAuth } from '@dbs-portal/tool-mock'

const protectedHandlers = withMockAuth(userHandlers, {
  requireAuth: true,
  requiredRoles: ['admin'],
  requiredPermissions: ['users:read'],
})
```

## Testing Utilities

### setupMSWTesting(handlers)

Sets up MSW for testing environments.

```typescript
import { setupMSWTesting } from '@dbs-portal/tool-mock'

const msw = setupMSWTesting([
  ...userHandlers,
  ...authHandlers,
])

// In test files
beforeAll(() => msw.listen())
afterEach(() => msw.resetHandlers())
afterAll(() => msw.close())
```

### mockApiCall(endpoint, response)

Utility for mocking individual API calls in tests.

```typescript
import { mockApiCall } from '@dbs-portal/tool-mock'

test('should handle user creation', async () => {
  mockApiCall('POST', '/api/users', {
    success: true,
    data: userFactory({ id: 'new-user' }),
  })

  // Test implementation
})
```

## Environment Detection

### isMockingEnabled()

Checks if mocking is enabled in the current environment.

```typescript
import { isMockingEnabled } from '@dbs-portal/tool-mock'

if (isMockingEnabled()) {
  console.log('Mocking is active')
}
```

### getMockingMode()

Returns the current mocking mode.

```typescript
import { getMockingMode } from '@dbs-portal/tool-mock'

const mode = getMockingMode() // 'development' | 'testing' | 'storybook' | 'disabled'
```

### getEnvironmentInfo()

Returns detailed environment information.

```typescript
import { getEnvironmentInfo } from '@dbs-portal/tool-mock'

const envInfo = getEnvironmentInfo()
console.log('Environment:', envInfo.environment) // 'browser' | 'node'
console.log('Should mock:', envInfo.shouldMock)
console.log('Mode:', envInfo.mode)
```