servcraft 0.1.0 → 0.1.1

package/docs/modules/VALIDATION.md

@@ -0,0 +1,294 @@
+# Validation Module
+
+Request validation using Zod schemas with type-safe validation helpers.
+
+## Features
+
+- **Zod Integration** - Full Zod schema support
+- **Type Safety** - Full TypeScript inference
+- **Error Formatting** - Structured error messages
+- **Common Schemas** - Pre-built validation schemas
+- **Request Validation** - Body, query, and params validation
+
+## Usage
+
+### Basic Validation
+
+```typescript
+import { z } from 'zod';
+import { validate, validateBody, validateQuery, validateParams } from 'servcraft/modules/validation';
+
+// Define schema
+const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(50),
+  age: z.number().min(18).optional(),
+});
+
+// Validate data
+const validatedUser = validate(userSchema, requestBody);
+// Returns typed data or throws ValidationError
+```
+
+### Request Validation
+
+```typescript
+// Validate request body
+const createUser = async (request, reply) => {
+  const body = validateBody(userSchema, request.body);
+  // body is typed as { email: string; name: string; age?: number }
+};
+
+// Validate query parameters
+const listUsers = async (request, reply) => {
+  const query = validateQuery(paginationSchema, request.query);
+  // query is typed with pagination fields
+};
+
+// Validate URL parameters
+const getUser = async (request, reply) => {
+  const params = validateParams(idParamSchema, request.params);
+  // params is typed as { id: string }
+};
+```
+
+## Pre-built Schemas
+
+### ID Parameter
+
+```typescript
+import { idParamSchema, IdParam } from 'servcraft/modules/validation';
+
+// Schema: { id: string (UUID) }
+const params = validateParams(idParamSchema, request.params);
+```
+
+### Pagination
+
+```typescript
+import { paginationSchema, PaginationInput } from 'servcraft/modules/validation';
+
+// Schema: { page, limit, sortBy, sortOrder }
+const query = validateQuery(paginationSchema, request.query);
+// Defaults: page=1, limit=20, sortOrder='asc'
+```
+
+### Search
+
+```typescript
+import { searchSchema } from 'servcraft/modules/validation';
+
+// Schema: { q?, search? }
+const query = validateQuery(searchSchema, request.query);
+```
+
+### Email
+
+```typescript
+import { emailSchema } from 'servcraft/modules/validation';
+
+const email = emailSchema.parse('user@example.com');
+// Throws if invalid email
+```
+
+### Password (Strong)
+
+```typescript
+import { passwordSchema } from 'servcraft/modules/validation';
+
+// Requirements:
+// - Minimum 8 characters
+// - At least one uppercase letter
+// - At least one lowercase letter
+// - At least one number
+// - At least one special character
+
+const password = passwordSchema.parse('MyP@ssw0rd!');
+```
+
+### URL
+
+```typescript
+import { urlSchema } from 'servcraft/modules/validation';
+
+const url = urlSchema.parse('https://example.com');
+```
+
+### Phone
+
+```typescript
+import { phoneSchema } from 'servcraft/modules/validation';
+
+// International format: +1234567890
+const phone = phoneSchema.parse('+12025551234');
+```
+
+### Date
+
+```typescript
+import { dateSchema, futureDateSchema, pastDateSchema } from 'servcraft/modules/validation';
+
+// Any valid date
+const date = dateSchema.parse('2024-12-20');
+
+// Must be in the future
+const futureDate = futureDateSchema.parse('2025-01-01');
+
+// Must be in the past
+const pastDate = pastDateSchema.parse('2020-01-01');
+```
+
+## Custom Schemas
+
+```typescript
+import { z } from 'zod';
+
+// User registration schema
+const registerSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain uppercase'),
+  confirmPassword: z.string(),
+  name: z.string().min(2).max(50),
+  acceptTerms: z.literal(true, {
+    errorMap: () => ({ message: 'You must accept the terms' }),
+  }),
+}).refine(data => data.password === data.confirmPassword, {
+  message: 'Passwords do not match',
+  path: ['confirmPassword'],
+});
+
+// Order schema
+const orderSchema = z.object({
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive(),
+  })).min(1, 'Order must have at least one item'),
+  shippingAddress: z.object({
+    street: z.string(),
+    city: z.string(),
+    zipCode: z.string(),
+    country: z.string().length(2),
+  }),
+  notes: z.string().max(500).optional(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { ValidationError } from 'servcraft/utils/errors';
+
+try {
+  const data = validate(schema, input);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // error.errors is structured:
+    // {
+    //   email: ['Invalid email address'],
+    //   password: ['Password must be at least 8 characters'],
+    //   'address.zipCode': ['Invalid zip code']
+    // }
+
+    return reply.status(400).send({
+      success: false,
+      message: 'Validation failed',
+      errors: error.errors,
+    });
+  }
+}
+```
+
+## Fastify Integration
+
+```typescript
+import { z } from 'zod';
+import { validateBody, validateQuery, validateParams } from 'servcraft/modules/validation';
+
+// Route with validation
+fastify.post('/api/users', async (request, reply) => {
+  const body = validateBody(registerSchema, request.body);
+
+  const user = await userService.create(body);
+  return { success: true, data: user };
+});
+
+// With query and params
+fastify.get('/api/users/:id/orders', async (request, reply) => {
+  const params = validateParams(idParamSchema, request.params);
+  const query = validateQuery(paginationSchema, request.query);
+
+  const orders = await orderService.findByUser(params.id, query);
+  return { success: true, data: orders };
+});
+```
+
+## Type Inference
+
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+// Infer type from schema
+type User = z.infer<typeof schema>;
+// { name: string; age: number }
+
+// Use in function
+function createUser(data: z.infer<typeof schema>) {
+  // data is typed
+}
+```
+
+## Common Patterns
+
+### Optional with Default
+
+```typescript
+const schema = z.object({
+  limit: z.number().default(20),
+  active: z.boolean().default(true),
+});
+```
+
+### Transform
+
+```typescript
+const schema = z.object({
+  email: z.string().email().toLowerCase(),
+  tags: z.string().transform(s => s.split(',')),
+});
+```
+
+### Refinement
+
+```typescript
+const schema = z.object({
+  startDate: z.date(),
+  endDate: z.date(),
+}).refine(
+  data => data.endDate > data.startDate,
+  { message: 'End date must be after start date' }
+);
+```
+
+### Union Types
+
+```typescript
+const schema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('email'), email: z.string().email() }),
+  z.object({ type: z.literal('sms'), phone: z.string() }),
+]);
+```
+
+## Best Practices
+
+1. **Reuse Schemas** - Create reusable schemas for common patterns
+2. **Meaningful Errors** - Provide clear error messages
+3. **Type Safety** - Use `z.infer<typeof schema>` for types
+4. **Validation Early** - Validate at the start of handlers
+5. **Sanitize Input** - Use transforms for normalization

package/docs/modules/WEBHOOK.md

@@ -0,0 +1,270 @@
+# Webhook Module
+
+Outbound webhook system with retry logic, signatures, and delivery tracking.
+
+## Features
+
+- **Endpoint Management** - Create, update, delete webhook endpoints
+- **Event Publishing** - Publish events to subscribed endpoints
+- **Automatic Retries** - Exponential backoff with configurable limits
+- **Signature Verification** - HMAC signatures for payload integrity
+- **Delivery Tracking** - Full delivery history with status tracking
+- **Secret Rotation** - Rotate endpoint secrets without downtime
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Webhook Service                          │
+├──────────────────────────────────────────────────────────────┤
+│  Endpoint Mgmt  │  Event Publishing  │  Retry Processor      │
+└────────┬────────┴─────────┬──────────┴──────────┬────────────┘
+         │                  │                     │
+         ▼                  ▼                     ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Prisma Repository                         │
+├──────────────────────────────────────────────────────────────┤
+│    Endpoints    │    Deliveries    │    Statistics           │
+└─────────────────┴──────────────────┴─────────────────────────┘
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { createWebhookService } from 'servcraft/modules/webhook';
+
+const webhookService = createWebhookService({
+  maxRetries: 5,
+  initialRetryDelay: 1000,
+  maxRetryDelay: 60000,
+  backoffMultiplier: 2,
+  timeout: 10000,
+  enableSignature: true,
+  signatureHeader: 'X-Webhook-Signature',
+  timestampHeader: 'X-Webhook-Timestamp',
+});
+```
+
+### Endpoint Management
+
+```typescript
+// Create endpoint
+const endpoint = await webhookService.createEndpoint({
+  url: 'https://example.com/webhooks',
+  events: ['user.created', 'user.updated', 'order.completed'],
+  headers: { 'X-Custom-Header': 'value' },
+  description: 'Main webhook endpoint',
+});
+// endpoint.secret is auto-generated
+
+// List endpoints
+const endpoints = await webhookService.listEndpoints();
+
+// Update endpoint
+await webhookService.updateEndpoint(endpoint.id, {
+  events: ['user.created', 'user.updated'],
+  enabled: true,
+});
+
+// Rotate secret
+const rotated = await webhookService.rotateSecret(endpoint.id);
+// rotated.secret is new secret
+
+// Delete endpoint
+await webhookService.deleteEndpoint(endpoint.id);
+```
+
+### Publishing Events
+
+```typescript
+// Publish to all matching endpoints
+const event = await webhookService.publishEvent('user.created', {
+  userId: 'user-123',
+  email: 'user@example.com',
+  createdAt: new Date().toISOString(),
+});
+
+// Publish to specific endpoints only
+await webhookService.publishEvent('order.completed', payload, ['endpoint-id-1', 'endpoint-id-2']);
+```
+
+### Delivery Management
+
+```typescript
+// Get delivery status
+const delivery = await webhookService.getDelivery(deliveryId);
+// {
+//   id, endpointId, eventType, payload,
+//   status: 'pending' | 'success' | 'retrying' | 'failed',
+//   attempts, deliveredAt, error
+// }
+
+// List deliveries with filters
+const deliveries = await webhookService.listDeliveries({
+  endpointId: 'endpoint-123',
+  status: 'failed',
+  eventType: 'user.created',
+});
+
+// Manual retry
+await webhookService.retryDelivery(deliveryId);
+
+// Get statistics
+const stats = await webhookService.getStats(endpointId);
+// {
+//   totalEvents, successfulDeliveries, failedDeliveries,
+//   pendingDeliveries, successRate
+// }
+```
+
+### Cleanup
+
+```typescript
+// Clean up old deliveries (older than 30 days)
+const deleted = await webhookService.cleanup(30);
+
+// Stop retry processor (on shutdown)
+webhookService.stop();
+```
+
+## Configuration
+
+```typescript
+interface WebhookConfig {
+  maxRetries?: number;        // Max retry attempts (default: 5)
+  initialRetryDelay?: number; // First retry delay ms (default: 1000)
+  maxRetryDelay?: number;     // Max retry delay ms (default: 60000)
+  backoffMultiplier?: number; // Backoff multiplier (default: 2)
+  timeout?: number;           // Request timeout ms (default: 10000)
+  enableSignature?: boolean;  // Enable HMAC signatures (default: true)
+  signatureHeader?: string;   // Signature header name
+  timestampHeader?: string;   // Timestamp header name
+}
+```
+
+## Webhook Payload Format
+
+Delivered webhooks have this structure:
+
+```json
+{
+  "id": "delivery-uuid",
+  "type": "user.created",
+  "created": "2024-01-15T10:30:00.000Z",
+  "data": {
+    "userId": "user-123",
+    "email": "user@example.com"
+  }
+}
+```
+
+## Signature Verification
+
+Webhooks are signed using HMAC-SHA256. Recipients should verify:
+
+```typescript
+// Headers sent with webhook
+// X-Webhook-Signature: t=1705312200,v1=abc123...
+// X-Webhook-Timestamp: 1705312200
+
+// Verification (recipient side)
+import crypto from 'crypto';
+
+function verifyWebhookSignature(
+  payload: string,
+  signature: string,
+  timestamp: string,
+  secret: string
+): boolean {
+  const signedPayload = `${timestamp}.${payload}`;
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Parse signature header: t=timestamp,v1=signature
+  const parts = signature.split(',');
+  const receivedSig = parts.find(p => p.startsWith('v1='))?.slice(3);
+
+  return crypto.timingSafeEqual(
+    Buffer.from(expectedSignature),
+    Buffer.from(receivedSig || '')
+  );
+}
+```
+
+## Retry Strategy
+
+Retries use exponential backoff:
+
+| Attempt | Delay |
+|---------|-------|
+| 1 | Immediate |
+| 2 | 1 second |
+| 3 | 2 seconds |
+| 4 | 4 seconds |
+| 5 | 8 seconds |
+| 6+ | Failed |
+
+## Event Types
+
+Define your event types:
+
+```typescript
+type WebhookEventType =
+  | 'user.created'
+  | 'user.updated'
+  | 'user.deleted'
+  | 'order.created'
+  | 'order.completed'
+  | 'order.cancelled'
+  | 'payment.succeeded'
+  | 'payment.failed'
+  | 'subscription.created'
+  | 'subscription.cancelled';
+```
+
+## Database Schema
+
+```sql
+-- Endpoints
+CREATE TABLE webhook_endpoints (
+  id UUID PRIMARY KEY,
+  url TEXT NOT NULL,
+  secret TEXT NOT NULL,
+  events TEXT[] NOT NULL,
+  headers JSONB,
+  enabled BOOLEAN DEFAULT true,
+  description TEXT,
+  created_at TIMESTAMP,
+  updated_at TIMESTAMP
+);
+
+-- Deliveries
+CREATE TABLE webhook_deliveries (
+  id UUID PRIMARY KEY,
+  endpoint_id UUID REFERENCES webhook_endpoints,
+  event_type TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  status TEXT NOT NULL,
+  attempts INTEGER DEFAULT 0,
+  max_attempts INTEGER DEFAULT 5,
+  delivered_at TIMESTAMP,
+  next_retry_at TIMESTAMP,
+  response_status INTEGER,
+  response_body TEXT,
+  error TEXT,
+  created_at TIMESTAMP
+);
+```
+
+## Best Practices
+
+1. **Idempotency** - Include delivery ID for idempotent processing
+2. **Timeout Handling** - Set reasonable timeouts (10s recommended)
+3. **Signature Verification** - Always verify signatures on receipt
+4. **Event Filtering** - Subscribe only to needed events
+5. **Retry Handling** - Implement idempotent handlers for retries
+6. **Secret Rotation** - Rotate secrets periodically