@fjell/registry 4.4.51 → 4.4.53

package/docs/public/configuration.md

@@ -1,759 +0,0 @@
-# Configuration Guide
-
-Complete guide to configuring the Fjell Client API for development and production environments.
-
-## Overview
-
-The Fjell Client API provides extensive configuration options for authentication, error handling, retry logic, monitoring, and performance optimization. This guide covers all available options with practical examples.
-
-## Basic Configuration
-
-### Minimal Setup
-
-```typescript
-import { createPItemApi, createCItemApi } from '@fjell/client-api';
-
-// Minimal configuration for development
-const config = {
-  baseUrl: 'http://localhost:3000/api'
-};
-
-const userApi = createPItemApi<User, 'user'>('user', ['users'], config);
-const taskApi = createCItemApi<Task, 'task', 'user'>('task', ['users', 'tasks'], config);
-```
-
-### Standard Development Configuration
-
-```typescript
-const devConfig = {
-  baseUrl: 'http://localhost:3000/api',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Client-Version': '1.0.0'
-  },
-  timeout: 10000,
-  enableErrorHandling: true,
-  retryConfig: {
-    maxRetries: 2,
-    initialDelayMs: 500,
-    maxDelayMs: 5000
-  }
-};
-```
-
-## Configuration Options
-
-### ClientApiOptions Interface
-
-```typescript
-interface ClientApiOptions {
-  // Required
-  baseUrl: string;                                    // API base URL
-
-  // HTTP Configuration
-  headers?: Record<string, string>;                   // Default headers
-  timeout?: number;                                   // Request timeout (ms)
-
-  // Authentication
-  readAuthenticated?: boolean;                        // Authenticate read operations
-  writeAuthenticated?: boolean;                       // Authenticate write operations
-  getOptions?: RequestOptions;                        // GET request options
-  postOptions?: RequestOptions;                       // POST request options
-  putOptions?: RequestOptions;                        // PUT request options
-  deleteOptions?: RequestOptions;                     // DELETE request options
-
-  // Error Handling
-  enableErrorHandling?: boolean;                      // Enable comprehensive error handling
-  retryConfig?: RetryConfig;                          // Retry behavior configuration
-  errorHandler?: (error: any, context?: Record<string, any>) => void;  // Custom error handler
-
-  // Advanced
-  transformRequest?: (data: any) => any;              // Transform request data
-  transformResponse?: (data: any) => any;             // Transform response data
-}
-```
-
-### RetryConfig Interface
-
-```typescript
-interface RetryConfig {
-  maxRetries: number;                                 // Maximum retry attempts
-  initialDelayMs: number;                             // Initial delay between retries
-  maxDelayMs: number;                                 // Maximum delay between retries
-  backoffMultiplier: number;                          // Exponential backoff multiplier
-  enableJitter: boolean;                              // Add randomness to delays
-
-  // Advanced retry logic
-  shouldRetry?: (error: any, attemptNumber: number) => boolean;  // Custom retry decision
-  onRetry?: (error: any, attemptNumber: number, delay: number) => void;  // Retry callback
-}
-```
-
-## Authentication Configuration
-
-### Basic Authentication
-
-```typescript
-const authConfig = {
-  baseUrl: 'https://api.example.com',
-  headers: {
-    'Authorization': 'Bearer your-api-token',
-    'Content-Type': 'application/json'
-  },
-  readAuthenticated: true,
-  writeAuthenticated: true
-};
-```
-
-### Dynamic Authentication
-
-```typescript
-// Token that updates automatically
-let authToken = 'initial-token';
-
-const dynamicAuthConfig = {
-  baseUrl: 'https://api.example.com',
-  headers: {
-    get 'Authorization'() {
-      return `Bearer ${authToken}`;
-    },
-    'Content-Type': 'application/json'
-  }
-};
-
-// Update token when needed
-function updateAuthToken(newToken: string) {
-  authToken = newToken;
-}
-```
-
-### Per-Operation Authentication
-
-```typescript
-const mixedAuthConfig = {
-  baseUrl: 'https://api.example.com',
-
-  // Default headers (no auth)
-  headers: {
-    'Content-Type': 'application/json'
-  },
-
-  // Authenticate only write operations
-  writeAuthenticated: true,
-
-  // Custom options for different operations
-  postOptions: {
-    headers: {
-      'Authorization': 'Bearer write-token',
-      'X-Write-Permission': 'true'
-    }
-  },
-
-  putOptions: {
-    headers: {
-      'Authorization': 'Bearer write-token',
-      'X-Write-Permission': 'true'
-    }
-  },
-
-  deleteOptions: {
-    headers: {
-      'Authorization': 'Bearer admin-token',
-      'X-Admin-Permission': 'true'
-    }
-  }
-};
-```
-
-## Retry Configuration
-
-### Development Retry Settings
-
-```typescript
-const devRetryConfig = {
-  maxRetries: 2,
-  initialDelayMs: 500,
-  maxDelayMs: 5000,
-  backoffMultiplier: 2,
-  enableJitter: true
-};
-```
-
-### Production Retry Settings
-
-```typescript
-const prodRetryConfig = {
-  maxRetries: 5,
-  initialDelayMs: 1000,
-  maxDelayMs: 30000,
-  backoffMultiplier: 1.5,
-  enableJitter: true,
-
-  // Custom retry logic for production
-  shouldRetry: (error, attemptNumber) => {
-    // Always retry network and server errors
-    if (error.code === 'NETWORK_ERROR' || error.code === 'SERVER_ERROR') {
-      return attemptNumber < 5;
-    }
-
-    // Limited retries for rate limiting
-    if (error.code === 'RATE_LIMIT_ERROR') {
-      return attemptNumber < 3;
-    }
-
-    // No retries for client errors
-    if (error.status >= 400 && error.status < 500) {
-      return false;
-    }
-
-    return error.isRetryable && attemptNumber < 3;
-  },
-
-  // Monitor retry attempts
-  onRetry: (error, attemptNumber, delay) => {
-    console.log(`Retry attempt ${attemptNumber + 1} for ${error.code} (delay: ${delay}ms)`);
-
-    // Send metrics to monitoring service
-    metrics.increment('api.retry', {
-      error_code: error.code,
-      attempt: attemptNumber + 1
-    });
-  }
-};
-```
-
-### Operation-Specific Retry Configuration
-
-```typescript
-// Different retry strategies for different operations
-const adaptiveRetryConfig = {
-  shouldRetry: (error, attemptNumber, context) => {
-    // More aggressive retries for read operations
-    if (context?.operation === 'get' || context?.operation === 'all') {
-      return error.isRetryable && attemptNumber < 5;
-    }
-
-    // Conservative retries for write operations
-    if (context?.operation === 'create' || context?.operation === 'update') {
-      return error.isRetryable && attemptNumber < 2;
-    }
-
-    // No retries for delete operations
-    if (context?.operation === 'remove') {
-      return false;
-    }
-
-    return error.isRetryable && attemptNumber < 3;
-  }
-};
-```
-
-## Error Handling Configuration
-
-### Basic Error Handler
-
-```typescript
-const basicErrorHandler = (error: any, context?: Record<string, any>) => {
-  console.error('API Error:', {
-    message: error.message,
-    code: error.code,
-    operation: context?.operation,
-    url: context?.url
-  });
-};
-
-const config = {
-  baseUrl: 'https://api.example.com',
-  enableErrorHandling: true,
-  errorHandler: basicErrorHandler
-};
-```
-
-### Production Error Handler
-
-```typescript
-const productionErrorHandler = (error: any, context?: Record<string, any>) => {
-  // Structured logging
-  logger.error('API Operation Failed', {
-    error: {
-      message: error.message,
-      code: error.code,
-      stack: error.stack
-    },
-    context: {
-      operation: context?.operation,
-      url: context?.url,
-      method: context?.method,
-      duration: context?.duration,
-      attempts: context?.attempts
-    },
-    timestamp: new Date().toISOString(),
-    requestId: context?.requestId || generateRequestId()
-  });
-
-  // Error tracking service
-  errorTracking.captureException(error, {
-    tags: {
-      service: 'fjell-client-api',
-      operation: context?.operation,
-      environment: process.env.NODE_ENV
-    },
-    extra: context,
-    user: {
-      id: getCurrentUserId()
-    }
-  });
-
-  // Business logic based on error type
-  if (error.code === 'AUTHENTICATION_ERROR') {
-    // Redirect to login
-    authService.redirectToLogin();
-  } else if (error.code === 'RATE_LIMIT_ERROR') {
-    // Implement circuit breaker
-    circuitBreaker.recordFailure();
-  } else if (error.code === 'PAYMENT_ERROR') {
-    // Send business notification
-    notificationService.sendPaymentFailure({
-      userId: context?.userId,
-      orderId: context?.orderId,
-      error: error.message
-    });
-  }
-
-  // Metrics collection
-  metrics.increment('api.errors.total', {
-    error_code: error.code,
-    operation: context?.operation,
-    environment: process.env.NODE_ENV
-  });
-
-  // Alerting for critical errors
-  if (error.code === 'SERVER_ERROR' && context?.attempts >= 3) {
-    alerting.sendAlert({
-      severity: 'high',
-      title: 'API Server Error After Multiple Retries',
-      description: `Operation ${context.operation} failed with ${error.message} after ${context.attempts} attempts`,
-      context
-    });
-  }
-};
-```
-
-## Environment-Specific Configuration
-
-### Development Environment
-
-```typescript
-const developmentConfig = {
-  baseUrl: 'http://localhost:3000/api',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Environment': 'development'
-  },
-  timeout: 10000,
-  enableErrorHandling: true,
-
-  retryConfig: {
-    maxRetries: 2,
-    initialDelayMs: 500,
-    maxDelayMs: 5000,
-    backoffMultiplier: 2,
-    enableJitter: false  // Consistent timing for development
-  },
-
-  errorHandler: (error, context) => {
-    // Detailed logging for development
-    console.group('🚨 API Error Details');
-    console.error('Error:', error);
-    console.log('Context:', context);
-    console.groupEnd();
-  }
-};
-```
-
-### Staging Environment
-
-```typescript
-const stagingConfig = {
-  baseUrl: 'https://api-staging.example.com',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${process.env.STAGING_API_TOKEN}`,
-    'X-Environment': 'staging'
-  },
-  timeout: 15000,
-  enableErrorHandling: true,
-
-  retryConfig: {
-    maxRetries: 3,
-    initialDelayMs: 1000,
-    maxDelayMs: 15000,
-    backoffMultiplier: 2,
-    enableJitter: true
-  },
-
-  errorHandler: (error, context) => {
-    // Same as production but with additional debugging
-    productionErrorHandler(error, context);
-
-    // Extra staging-specific logging
-    if (process.env.STAGING_DEBUG === 'true') {
-      console.log('Staging Debug Info:', {
-        error,
-        context,
-        environment: 'staging'
-      });
-    }
-  }
-};
-```
-
-### Production Environment
-
-```typescript
-const productionConfig = {
-  baseUrl: 'https://api.example.com',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${process.env.PRODUCTION_API_TOKEN}`,
-    'X-Environment': 'production',
-    'X-Service-Version': process.env.SERVICE_VERSION,
-    'X-Request-Source': 'fjell-client-api'
-  },
-  timeout: 30000,
-  enableErrorHandling: true,
-
-  retryConfig: {
-    maxRetries: 5,
-    initialDelayMs: 1000,
-    maxDelayMs: 60000,
-    backoffMultiplier: 1.5,
-    enableJitter: true,
-
-    shouldRetry: (error, attemptNumber) => {
-      // Production-optimized retry logic
-      if (error.code === 'NETWORK_ERROR') return attemptNumber < 5;
-      if (error.code === 'SERVER_ERROR') return attemptNumber < 3;
-      if (error.code === 'RATE_LIMIT_ERROR') return attemptNumber < 3;
-      if (error.code === 'TIMEOUT_ERROR') return attemptNumber < 2;
-      return false;
-    },
-
-    onRetry: (error, attemptNumber, delay) => {
-      // Production retry monitoring
-      metrics.increment('api.retries', {
-        error_code: error.code,
-        attempt: attemptNumber + 1
-      });
-    }
-  },
-
-  errorHandler: productionErrorHandler
-};
-```
-
-## Advanced Configuration Patterns
-
-### Multi-Environment Configuration Factory
-
-```typescript
-interface EnvironmentConfig {
-  api: {
-    baseUrl: string;
-    token: string;
-  };
-  retry: {
-    maxRetries: number;
-    timeout: number;
-  };
-  monitoring: {
-    enabled: boolean;
-    endpoint?: string;
-  };
-}
-
-const environments: Record<string, EnvironmentConfig> = {
-  development: {
-    api: {
-      baseUrl: 'http://localhost:3000/api',
-      token: 'dev-token'
-    },
-    retry: {
-      maxRetries: 2,
-      timeout: 10000
-    },
-    monitoring: {
-      enabled: false
-    }
-  },
-
-  production: {
-    api: {
-      baseUrl: 'https://api.example.com',
-      token: process.env.PROD_API_TOKEN!
-    },
-    retry: {
-      maxRetries: 5,
-      timeout: 30000
-    },
-    monitoring: {
-      enabled: true,
-      endpoint: 'https://monitoring.example.com'
-    }
-  }
-};
-
-function createApiConfig(environment: string): ClientApiOptions {
-  const envConfig = environments[environment];
-  if (!envConfig) {
-    throw new Error(`Unknown environment: ${environment}`);
-  }
-
-  return {
-    baseUrl: envConfig.api.baseUrl,
-    headers: {
-      'Authorization': `Bearer ${envConfig.api.token}`,
-      'Content-Type': 'application/json',
-      'X-Environment': environment
-    },
-    timeout: envConfig.retry.timeout,
-    enableErrorHandling: true,
-
-    retryConfig: {
-      maxRetries: envConfig.retry.maxRetries,
-      initialDelayMs: 1000,
-      maxDelayMs: environment === 'production' ? 60000 : 15000,
-      backoffMultiplier: environment === 'production' ? 1.5 : 2,
-      enableJitter: true
-    },
-
-    errorHandler: envConfig.monitoring.enabled
-      ? productionErrorHandler
-      : developmentErrorHandler
-  };
-}
-
-// Usage
-const config = createApiConfig(process.env.NODE_ENV || 'development');
-const userApi = createPItemApi<User, 'user'>('user', ['users'], config);
-```
-
-### Configuration with Secrets Management
-
-```typescript
-import { getSecret } from './secrets';
-
-async function createSecureApiConfig(): Promise<ClientApiOptions> {
-  const apiToken = await getSecret('API_TOKEN');
-  const encryptionKey = await getSecret('ENCRYPTION_KEY');
-
-  return {
-    baseUrl: process.env.API_BASE_URL!,
-    headers: {
-      'Authorization': `Bearer ${apiToken}`,
-      'Content-Type': 'application/json',
-      'X-Encryption-Key': encryptionKey
-    },
-    timeout: 30000,
-    enableErrorHandling: true,
-
-    // Transform sensitive data
-    transformRequest: (data) => {
-      // Encrypt sensitive fields
-      if (data.password) {
-        data.password = encrypt(data.password, encryptionKey);
-      }
-      return data;
-    },
-
-    transformResponse: (data) => {
-      // Decrypt sensitive fields
-      if (data.encryptedData) {
-        data.decryptedData = decrypt(data.encryptedData, encryptionKey);
-        delete data.encryptedData;
-      }
-      return data;
-    }
-  };
-}
-```
-
-### Configuration Validation
-
-```typescript
-import Joi from 'joi';
-
-const configSchema = Joi.object({
-  baseUrl: Joi.string().uri().required(),
-  timeout: Joi.number().min(1000).max(300000).default(30000),
-  retryConfig: Joi.object({
-    maxRetries: Joi.number().min(0).max(10).required(),
-    initialDelayMs: Joi.number().min(100).max(10000).required(),
-    maxDelayMs: Joi.number().min(1000).max(300000).required(),
-    backoffMultiplier: Joi.number().min(1).max(5).required(),
-    enableJitter: Joi.boolean().required()
-  }).required()
-});
-
-function validateConfig(config: ClientApiOptions): ClientApiOptions {
-  const { error, value } = configSchema.validate(config);
-
-  if (error) {
-    throw new Error(`Invalid configuration: ${error.message}`);
-  }
-
-  return value;
-}
-
-// Usage
-const config = validateConfig({
-  baseUrl: 'https://api.example.com',
-  retryConfig: {
-    maxRetries: 3,
-    initialDelayMs: 1000,
-    maxDelayMs: 30000,
-    backoffMultiplier: 2,
-    enableJitter: true
-  }
-});
-```
-
-## Testing Configuration
-
-### Mock Configuration for Testing
-
-```typescript
-const testConfig: ClientApiOptions = {
-  baseUrl: 'http://mock-api.test',
-  timeout: 5000,
-  enableErrorHandling: false,  // Disable for predictable testing
-
-  retryConfig: {
-    maxRetries: 1,  // Minimal retries for faster tests
-    initialDelayMs: 10,
-    maxDelayMs: 100,
-    backoffMultiplier: 1,
-    enableJitter: false  // Consistent timing for tests
-  },
-
-  errorHandler: (error, context) => {
-    // Capture errors for test assertions
-    testErrorCapture.capture(error, context);
-  }
-};
-```
-
-### Integration Test Configuration
-
-```typescript
-const integrationTestConfig: ClientApiOptions = {
-  baseUrl: process.env.TEST_API_URL || 'http://localhost:3001/api',
-  headers: {
-    'Authorization': `Bearer ${process.env.TEST_API_TOKEN}`,
-    'X-Test-Mode': 'true'
-  },
-  timeout: 10000,
-  enableErrorHandling: true,
-
-  retryConfig: {
-    maxRetries: 2,
-    initialDelayMs: 100,
-    maxDelayMs: 1000,
-    backoffMultiplier: 2,
-    enableJitter: false
-  }
-};
-```
-
-## Configuration Best Practices
-
-### 1. **Environment Variables**
-
-```typescript
-// Use environment variables for sensitive data
-const config = {
-  baseUrl: process.env.API_BASE_URL!,
-  headers: {
-    'Authorization': `Bearer ${process.env.API_TOKEN!}`,
-  },
-  timeout: parseInt(process.env.API_TIMEOUT || '30000'),
-
-  retryConfig: {
-    maxRetries: parseInt(process.env.API_MAX_RETRIES || '3'),
-    initialDelayMs: parseInt(process.env.API_INITIAL_DELAY || '1000')
-  }
-};
-```
-
-### 2. **Configuration Hierarchy**
-
-```typescript
-// Base configuration
-const baseConfig = {
-  headers: {
-    'Content-Type': 'application/json',
-    'User-Agent': 'fjell-client-api/1.0'
-  },
-  timeout: 30000,
-  enableErrorHandling: true
-};
-
-// Environment-specific overrides
-const envConfig = {
-  development: {
-    ...baseConfig,
-    baseUrl: 'http://localhost:3000/api',
-    retryConfig: { maxRetries: 2 }
-  },
-
-  production: {
-    ...baseConfig,
-    baseUrl: 'https://api.example.com',
-    retryConfig: { maxRetries: 5 }
-  }
-};
-```
-
-### 3. **Type Safety**
-
-```typescript
-// Use TypeScript for configuration validation
-interface AppConfig {
-  api: ClientApiOptions;
-  features: {
-    enableRetries: boolean;
-    enableCaching: boolean;
-  };
-}
-
-const appConfig: AppConfig = {
-  api: {
-    baseUrl: process.env.API_BASE_URL!,
-    retryConfig: {
-      maxRetries: 3,
-      initialDelayMs: 1000,
-      maxDelayMs: 30000,
-      backoffMultiplier: 2,
-      enableJitter: true
-    }
-  },
-  features: {
-    enableRetries: true,
-    enableCaching: false
-  }
-};
-```
-
-## Related Documentation
-
-- [Error Handling](./error-handling/README.md) - Configure error handling behavior
-- [Operations](./operations/README.md) - Operation-specific configuration
-- [Examples](../examples-README.md) - Configuration examples and patterns
-
-## Next Steps
-
-1. Choose appropriate configuration for your environment
-2. Set up error handling and monitoring
-3. Configure retry behavior for your use case
-4. Test configuration in staging environment
-5. Monitor and adjust configuration based on production metrics