servcraft 0.1.0 → 0.1.3

package/docs/modules/ANALYTICS.md

@@ -0,0 +1,226 @@
+# Analytics Module
+
+Prometheus-style metrics collection for monitoring and observability.
+
+## Features
+
+- **Counters** - Monotonically increasing values
+- **Gauges** - Values that can go up and down
+- **Histograms** - Distribution of values with buckets
+- **Events** - Track custom application events
+- **Prometheus Export** - Native Prometheus format output
+- **Metric Queries** - Query and aggregate metrics
+
+## Metric Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| Counter | Only increases | Request count, errors |
+| Gauge | Can increase/decrease | Active connections, queue size |
+| Histogram | Value distribution | Response times, payload sizes |
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { AnalyticsService } from 'servcraft/modules/analytics';
+
+const analytics = new AnalyticsService({
+  enabled: true,
+  prefix: 'myapp',
+  defaultLabels: { env: 'production' },
+  flushInterval: 60000,
+});
+```
+
+### Counters
+
+```typescript
+// Simple increment
+analytics.incrementCounter('http_requests_total');
+
+// Increment by value
+analytics.incrementCounter('bytes_received', 1024);
+
+// With labels
+analytics.incrementCounter('http_requests_total', 1, {
+  method: 'GET',
+  path: '/api/users',
+  status: '200',
+});
+```
+
+### Gauges
+
+```typescript
+// Set gauge value
+analytics.setGauge('active_connections', 42);
+
+// With labels
+analytics.setGauge('queue_size', 150, { queue: 'emails' });
+
+// Update periodically
+setInterval(() => {
+  analytics.setGauge('memory_usage_bytes', process.memoryUsage().heapUsed);
+}, 5000);
+```
+
+### Histograms
+
+```typescript
+// Observe value with default buckets
+analytics.observeHistogram('http_request_duration_seconds', 0.125);
+
+// Custom buckets
+analytics.observeHistogram(
+  'http_request_duration_seconds',
+  0.125,
+  [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  { method: 'GET', path: '/api/users' }
+);
+
+// Timing helper
+const start = Date.now();
+// ... do work ...
+const duration = (Date.now() - start) / 1000;
+analytics.observeHistogram('operation_duration_seconds', duration);
+```
+
+### Events
+
+```typescript
+// Track event
+analytics.trackEvent({
+  name: 'user_signup',
+  properties: {
+    source: 'google',
+    plan: 'free',
+  },
+});
+
+// Get recent events
+const events = analytics.getEvents(100);
+```
+
+### Querying Metrics
+
+```typescript
+const result = await analytics.queryMetrics({
+  name: 'myapp_http_requests_total',
+  startTime: new Date('2024-01-01'),
+  endTime: new Date('2024-01-31'),
+  labels: { method: 'GET' },
+  groupBy: ['path'],
+  aggregation: 'sum',
+});
+
+// result: { name, data: [...], aggregated: 12345 }
+```
+
+### Prometheus Export
+
+```typescript
+// Get Prometheus format
+const metrics = analytics.getPrometheusMetrics();
+
+// Example output:
+// myapp_http_requests_total{method="GET",status="200"} 1234
+// myapp_active_connections{} 42
+// myapp_http_request_duration_seconds_bucket{le="0.1"} 500
+// myapp_http_request_duration_seconds_bucket{le="0.5"} 900
+// myapp_http_request_duration_seconds_sum{} 125.5
+// myapp_http_request_duration_seconds_count{} 1000
+```
+
+### Fastify Integration
+
+```typescript
+// Metrics endpoint
+fastify.get('/metrics', async (request, reply) => {
+  reply.type('text/plain').send(analytics.getPrometheusMetrics());
+});
+
+// Request duration middleware
+fastify.addHook('onRequest', async (request) => {
+  request.startTime = Date.now();
+});
+
+fastify.addHook('onResponse', async (request, reply) => {
+  const duration = (Date.now() - request.startTime) / 1000;
+
+  analytics.incrementCounter('http_requests_total', 1, {
+    method: request.method,
+    path: request.routerPath || request.url,
+    status: String(reply.statusCode),
+  });
+
+  analytics.observeHistogram('http_request_duration_seconds', duration, undefined, {
+    method: request.method,
+    path: request.routerPath || request.url,
+  });
+});
+```
+
+## Configuration
+
+```typescript
+interface AnalyticsConfig {
+  enabled?: boolean;          // Enable/disable metrics (default: true)
+  prefix?: string;            // Metric name prefix (default: 'app')
+  defaultLabels?: Record<string, string>; // Labels added to all metrics
+  prometheusEnabled?: boolean; // Enable Prometheus export (default: true)
+  flushInterval?: number;     // Cleanup interval in ms (default: 60000)
+}
+```
+
+## Aggregation Types
+
+| Aggregation | Description |
+|-------------|-------------|
+| `sum` | Sum of all values |
+| `avg` | Average of values |
+| `min` | Minimum value |
+| `max` | Maximum value |
+| `count` | Number of data points |
+
+## Utility Methods
+
+```typescript
+// Get all counters
+const counters = analytics.getCounters();
+
+// Get all gauges
+const gauges = analytics.getGauges();
+
+// Clear all metrics
+analytics.clear();
+```
+
+## Prometheus Configuration
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'myapp'
+    static_configs:
+      - targets: ['localhost:3000']
+    metrics_path: '/metrics'
+    scrape_interval: 15s
+```
+
+## Grafana Dashboard
+
+Common panels:
+- Request rate: `rate(myapp_http_requests_total[5m])`
+- Error rate: `rate(myapp_http_requests_total{status=~"5.."}[5m])`
+- P99 latency: `histogram_quantile(0.99, rate(myapp_http_request_duration_seconds_bucket[5m]))`
+- Active connections: `myapp_active_connections`
+
+## Best Practices
+
+1. **Use Labels Wisely** - Don't create high-cardinality labels
+2. **Consistent Naming** - Follow Prometheus naming conventions
+3. **Default Buckets** - Use appropriate histogram buckets for your use case
+4. **Memory Management** - Configure flush interval to prevent memory growth
+5. **Metric Types** - Use the right metric type for your use case

package/docs/modules/API-VERSIONING.md

@@ -0,0 +1,252 @@
+# API Versioning Module
+
+API versioning support with multiple detection strategies.
+
+## Features
+
+- **Multiple Strategies** - URL path, header, query param, Accept header
+- **Version Detection** - Automatic version detection from requests
+- **Deprecation Warnings** - Warn clients about deprecated versions
+- **Migration Support** - Data migration between versions
+- **Sunset Dates** - Track version end-of-life dates
+
+## Strategies
+
+| Strategy | Example | Best For |
+|----------|---------|----------|
+| URL Path | `/v1/users`, `/v2/users` | RESTful APIs, clear versioning |
+| Header | `X-API-Version: v2` | Clean URLs, flexible |
+| Query | `?version=v2` | Simple implementation |
+| Accept Header | `Accept: application/vnd.api.v2+json` | Content negotiation |
+
+## Usage
+
+### Configuration
+
+```typescript
+import { VersioningService } from 'servcraft/modules/api-versioning';
+
+const versionService = new VersioningService({
+  strategy: 'url',
+  defaultVersion: 'v1',
+  versions: [
+    {
+      version: 'v1',
+      status: 'deprecated',
+      releasedAt: new Date('2023-01-01'),
+      sunsetAt: new Date('2024-06-01'),
+    },
+    {
+      version: 'v2',
+      status: 'active',
+      releasedAt: new Date('2024-01-01'),
+    },
+    {
+      version: 'v3',
+      status: 'active',
+      releasedAt: new Date('2024-06-01'),
+    },
+  ],
+  headerName: 'X-API-Version',
+  queryParam: 'version',
+  strict: true,
+  deprecationWarnings: true,
+});
+```
+
+### Version Detection
+
+```typescript
+// Detect version from request
+const result = versionService.detectVersion({
+  url: '/v2/users',
+  headers: { 'x-api-version': 'v2' },
+  query: { version: 'v2' },
+});
+// {
+//   version: 'v2',
+//   source: 'url',
+//   isValid: true,
+//   warning: undefined
+// }
+
+// Deprecated version warning
+const deprecatedResult = versionService.detectVersion({
+  url: '/v1/users',
+});
+// {
+//   version: 'v1',
+//   source: 'url',
+//   isValid: true,
+//   warning: 'API version v1 is deprecated and will be removed on 2024-06-01'
+// }
+```
+
+### Version Information
+
+```typescript
+// Get version info
+const info = versionService.getVersion('v2');
+// { version: 'v2', status: 'active', releasedAt: Date }
+
+// Get all versions
+const all = versionService.getAllVersions();
+
+// Get active versions
+const active = versionService.getActiveVersions();
+
+// Check if version is valid
+const isValid = versionService.isVersionValid('v3');
+
+// Compare versions
+const comparison = versionService.compareVersions('v1', 'v2');
+// Returns: -1 (v1 < v2)
+```
+
+### Migrations
+
+```typescript
+// Add migration
+versionService.addMigration({
+  from: 'v1',
+  to: 'v2',
+  transform: (data) => ({
+    ...data,
+    // v2 renames 'name' to 'fullName'
+    fullName: data.name,
+    name: undefined,
+    // v2 adds required field
+    version: 2,
+  }),
+});
+
+// Get migration
+const migration = versionService.getMigration('v1', 'v2');
+if (migration) {
+  const v2Data = migration.transform(v1Data);
+}
+```
+
+## Configuration Types
+
+```typescript
+interface VersioningConfig {
+  strategy: 'url' | 'header' | 'query' | 'accept-header';
+  defaultVersion: string;
+  versions: ApiVersion[];
+  headerName?: string;      // default: 'X-API-Version'
+  queryParam?: string;      // default: 'version'
+  strict?: boolean;         // Reject invalid versions
+  deprecationWarnings?: boolean;
+}
+
+interface ApiVersion {
+  version: string;
+  status: 'active' | 'deprecated' | 'sunset';
+  releasedAt: Date;
+  sunsetAt?: Date;
+  changelog?: string;
+}
+
+interface VersionMigration {
+  from: string;
+  to: string;
+  transform: (data: unknown) => unknown;
+}
+```
+
+## Fastify Integration
+
+```typescript
+import { versioningMiddleware } from 'servcraft/modules/api-versioning';
+
+// Register middleware
+fastify.addHook('preHandler', async (request, reply) => {
+  const result = versionService.detectVersion({
+    url: request.url,
+    headers: request.headers,
+    query: request.query,
+  });
+
+  if (!result.isValid && versionService.config.strict) {
+    return reply.status(400).send({
+      error: `Invalid API version: ${result.version}`,
+      supportedVersions: versionService.getActiveVersions().map(v => v.version),
+    });
+  }
+
+  request.apiVersion = result.version;
+
+  // Add deprecation warning header
+  if (result.warning) {
+    reply.header('X-API-Deprecation-Warning', result.warning);
+    reply.header('Sunset', versionService.getVersion(result.version)?.sunsetAt?.toISOString());
+  }
+});
+```
+
+### Versioned Routes
+
+```typescript
+// URL-based versioning
+fastify.get('/v1/users', async (request, reply) => {
+  // v1 response format
+  return users.map(u => ({ name: u.name, email: u.email }));
+});
+
+fastify.get('/v2/users', async (request, reply) => {
+  // v2 response format with pagination
+  return {
+    data: users.map(u => ({ fullName: u.fullName, email: u.email })),
+    meta: { total: users.length },
+  };
+});
+
+// Header-based versioning (single route)
+fastify.get('/users', async (request, reply) => {
+  const version = request.apiVersion;
+
+  if (version === 'v1') {
+    return users.map(u => ({ name: u.name }));
+  }
+
+  // v2 and later
+  return {
+    data: users.map(u => ({ fullName: u.fullName })),
+    meta: { total: users.length },
+  };
+});
+```
+
+## Response Headers
+
+```http
+# Deprecation warning
+X-API-Deprecation-Warning: API version v1 is deprecated and will be removed on 2024-06-01
+Sunset: 2024-06-01T00:00:00.000Z
+
+# Current version
+X-API-Version: v2
+```
+
+## Version Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Version Lifecycle                        │
+├─────────────────────────────────────────────────────────────┤
+│  ACTIVE ──────► DEPRECATED ──────► SUNSET ──────► REMOVED   │
+│                     │                  │                    │
+│                  Warning            Error                   │
+│                  Headers           Response                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Best Practices
+
+1. **Semantic Versioning** - Use v1, v2, v3 for major breaking changes
+2. **Deprecation Period** - Give clients 6+ months notice
+3. **Sunset Headers** - Include Sunset header for deprecated versions
+4. **Documentation** - Document changes between versions
+5. **Default Version** - Don't change default version without notice
+6. **Migration Guides** - Provide clear migration instructions

package/docs/modules/AUDIT.md

@@ -0,0 +1,192 @@
+# Audit Module
+
+Audit logging for tracking user actions and system events.
+
+## Features
+
+- **Automatic Logging** - Track CRUD operations automatically
+- **User Attribution** - Link actions to users
+- **Resource Tracking** - Track changes by resource type
+- **IP & User Agent** - Capture request metadata
+- **Data Retention** - Configurable log retention
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { getAuditService } from 'servcraft/modules/audit';
+
+const auditService = getAuditService();
+```
+
+### Logging Actions
+
+```typescript
+// Generic log entry
+await auditService.log({
+  action: 'create',
+  resource: 'order',
+  resourceId: 'order-123',
+  userId: 'user-456',
+  newValue: { total: 99.99, items: 3 },
+  ipAddress: request.ip,
+  userAgent: request.headers['user-agent'],
+});
+
+// Shortcut methods
+await auditService.logCreate('order', 'order-123', 'user-456', { total: 99.99 });
+
+await auditService.logUpdate('order', 'order-123', 'user-456',
+  { status: 'pending' },  // old value
+  { status: 'shipped' }   // new value
+);
+
+await auditService.logDelete('order', 'order-123', 'user-456', { total: 99.99 });
+```
+
+### Auth Events
+
+```typescript
+// Login event
+await auditService.logLogin('user-123', {
+  ipAddress: '192.168.1.1',
+  userAgent: 'Mozilla/5.0...',
+});
+
+// Logout event
+await auditService.logLogout('user-123');
+
+// Password change
+await auditService.logPasswordChange('user-123', {
+  ipAddress: '192.168.1.1',
+});
+```
+
+### Querying Logs
+
+```typescript
+// Query with filters
+const result = await auditService.query({
+  userId: 'user-123',
+  action: 'update',
+  resource: 'order',
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-01-31'),
+  page: 1,
+  limit: 50,
+});
+// { data: [...], total: 150, page: 1, totalPages: 3 }
+
+// Find by user
+const userLogs = await auditService.findByUser('user-123', 100);
+
+// Find by resource
+const orderLogs = await auditService.findByResource('order', 'order-123', 50);
+```
+
+### Data Retention
+
+```typescript
+// Delete logs older than 90 days
+const deleted = await auditService.cleanupOldLogs(90);
+console.log(`Deleted ${deleted} old audit logs`);
+```
+
+## Types
+
+```typescript
+interface AuditLogEntry {
+  action: string;
+  resource: string;
+  resourceId?: string;
+  userId?: string;
+  oldValue?: Record<string, unknown>;
+  newValue?: Record<string, unknown>;
+  ipAddress?: string;
+  userAgent?: string;
+}
+
+interface AuditLogQuery {
+  userId?: string;
+  action?: string;
+  resource?: string;
+  resourceId?: string;
+  startDate?: Date;
+  endDate?: Date;
+  page?: number;
+  limit?: number;
+}
+
+interface AuditLogRecord extends AuditLogEntry {
+  id: string;
+  timestamp: Date;
+}
+```
+
+## Common Actions
+
+| Action | Description |
+|--------|-------------|
+| `create` | Resource created |
+| `update` | Resource updated |
+| `delete` | Resource deleted |
+| `login` | User logged in |
+| `logout` | User logged out |
+| `password_change` | Password changed |
+| `permission_change` | Permissions modified |
+| `export` | Data exported |
+| `import` | Data imported |
+
+## Middleware Integration
+
+```typescript
+// Fastify hook for automatic audit logging
+fastify.addHook('onResponse', async (request, reply) => {
+  // Only log mutations
+  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(request.method)) {
+    return;
+  }
+
+  const userId = request.user?.id;
+  const resource = request.routerPath.split('/')[2]; // e.g., /api/orders -> orders
+
+  await auditService.log({
+    action: request.method.toLowerCase(),
+    resource,
+    resourceId: request.params?.id,
+    userId,
+    ipAddress: request.ip,
+    userAgent: request.headers['user-agent'],
+  });
+});
+```
+
+## Database Schema
+
+```sql
+CREATE TABLE audit_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  action TEXT NOT NULL,
+  resource TEXT NOT NULL,
+  resource_id TEXT,
+  user_id TEXT,
+  old_value JSONB,
+  new_value JSONB,
+  ip_address TEXT,
+  user_agent TEXT,
+  timestamp TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_audit_user ON audit_logs(user_id);
+CREATE INDEX idx_audit_resource ON audit_logs(resource, resource_id);
+CREATE INDEX idx_audit_timestamp ON audit_logs(timestamp);
+```
+
+## Best Practices
+
+1. **Log Sensitive Actions** - Always log auth, permission, and data changes
+2. **Don't Log Sensitive Data** - Exclude passwords, tokens from logs
+3. **Retention Policy** - Implement data retention per compliance requirements
+4. **Async Logging** - Use async logging to not block requests
+5. **Structured Data** - Use consistent action and resource names