servcraft 0.1.0 → 0.1.3

package/src/modules/validation/validator.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import type { ZodError, ZodTypeAny } from 'zod';
+import type { ZodSchema, ZodError } from 'zod';
 import { ValidationError } from '../../utils/errors.js';
 
-export function validateBody<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+export function validateBody<T>(schema: ZodSchema<T>, data: unknown): T {
   const result = schema.safeParse(data);
 
   if (!result.success) {
@@ -12,7 +12,7 @@ export function validateBody<T extends ZodTypeAny>(schema: T, data: unknown): z.
   return result.data;
 }
 
-export function validateQuery<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+export function validateQuery<T extends z.ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
   const result = schema.safeParse(data);
 
   if (!result.success) {
@@ -22,7 +22,7 @@ export function validateQuery<T extends ZodTypeAny>(schema: T, data: unknown): z
   return result.data;
 }
 
-export function validateParams<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+export function validateParams<T>(schema: ZodSchema<T>, data: unknown): T {
   const result = schema.safeParse(data);
 
   if (!result.success) {
@@ -32,7 +32,7 @@ export function validateParams<T extends ZodTypeAny>(schema: T, data: unknown):
   return result.data;
 }
 
-export function validate<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+export function validate<T>(schema: ZodSchema<T>, data: unknown): T {
   return validateBody(schema, data);
 }
 
@@ -83,21 +83,16 @@ export const passwordSchema = z
 export const urlSchema = z.string().url('Invalid URL format');
 
 // Phone validation (basic international format)
-export const phoneSchema = z.string().regex(
-  /^\+?[1-9]\d{1,14}$/,
-  'Invalid phone number format'
-);
+export const phoneSchema = z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number format');
 
 // Date validation
 export const dateSchema = z.coerce.date();
-export const futureDateSchema = z.coerce.date().refine(
-  (date) => date > new Date(),
-  'Date must be in the future'
-);
-export const pastDateSchema = z.coerce.date().refine(
-  (date) => date < new Date(),
-  'Date must be in the past'
-);
+export const futureDateSchema = z.coerce
+  .date()
+  .refine((date) => date > new Date(), 'Date must be in the future');
+export const pastDateSchema = z.coerce
+  .date()
+  .refine((date) => date < new Date(), 'Date must be in the past');
 
 // Type exports
 export type IdParam = z.infer<typeof idParamSchema>;

package/src/modules/webhook/index.ts

@@ -0,0 +1,91 @@
+/**
+ * Webhook Module
+ *
+ * Provides outgoing webhook functionality with:
+ * - HMAC signature verification
+ * - Automatic retry with exponential backoff
+ * - Delivery tracking and monitoring
+ * - Multiple retry strategies
+ * - Event publishing and subscription
+ *
+ * @example
+ * ```typescript
+ * import { WebhookService, createWebhookRoutes } from './modules/webhook';
+ *
+ * // Create service
+ * const webhookService = new WebhookService({
+ *   maxRetries: 5,
+ *   timeout: 10000,
+ *   enableSignature: true
+ * });
+ *
+ * // Create endpoint
+ * const endpoint = await webhookService.createEndpoint({
+ *   url: 'https://example.com/webhook',
+ *   events: ['user.created', 'order.completed'],
+ *   description: 'Production webhook'
+ * });
+ *
+ * // Publish event
+ * await webhookService.publishEvent('user.created', {
+ *   userId: '123',
+ *   email: 'user@example.com',
+ *   name: 'John Doe'
+ * });
+ *
+ * // Add routes to your app
+ * app.use('/api/webhooks', authMiddleware, createWebhookRoutes(webhookService));
+ * ```
+ *
+ * ## Signature Verification
+ *
+ * Webhooks are signed with HMAC-SHA256. Recipients should verify:
+ *
+ * ```typescript
+ * import { verifyWebhookSignature } from './modules/webhook';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'];
+ *   const secret = 'your-webhook-secret';
+ *
+ *   if (!verifyWebhookSignature(req.body, signature, secret)) {
+ *     return res.status(401).json({ error: 'Invalid signature' });
+ *   }
+ *
+ *   // Process webhook
+ *   res.json({ received: true });
+ * });
+ * ```
+ */
+
+// Types
+export * from './types.js';
+
+// Service
+export { WebhookService } from './webhook.service.js';
+
+// Routes
+export { createWebhookRoutes } from './webhook.routes.js';
+
+// Signature utilities
+export {
+  generateSignature,
+  verifySignature,
+  verifyWebhookSignature,
+  parseSignatureHeader,
+  formatSignatureHeader,
+  generateWebhookSecret,
+} from './signature.js';
+
+// Retry strategies
+export {
+  ExponentialBackoffStrategy,
+  LinearBackoffStrategy,
+  FixedDelayStrategy,
+  CustomDelayStrategy,
+  createDefaultRetryStrategy,
+  calculateNextRetryTime,
+  shouldRetryDelivery,
+  getExponentialBackoff,
+  parseRetryAfter,
+} from './retry.js';

package/src/modules/webhook/retry.ts

@@ -0,0 +1,196 @@
+import type { WebhookRetryStrategy } from './types.js';
+
+/**
+ * Exponential backoff retry strategy
+ */
+export class ExponentialBackoffStrategy implements WebhookRetryStrategy {
+  constructor(
+    private initialDelay: number = 1000, // 1 second
+    private maxDelay: number = 60000, // 1 minute
+    private multiplier: number = 2,
+    private maxRetries: number = 5
+  ) {}
+
+  getNextRetryDelay(attempt: number): number {
+    if (attempt >= this.maxRetries) {
+      return -1; // No more retries
+    }
+
+    // Calculate exponential backoff: initialDelay * (multiplier ^ attempt)
+    const delay = this.initialDelay * Math.pow(this.multiplier, attempt);
+
+    // Add jitter (±25% randomization) to prevent thundering herd
+    const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+
+    // Cap at maxDelay
+    return Math.min(delay + jitter, this.maxDelay);
+  }
+
+  shouldRetry(attempt: number, error?: Error): boolean {
+    // Don't retry if max attempts reached
+    if (attempt >= this.maxRetries) {
+      return false;
+    }
+
+    // Don't retry client errors (4xx), except specific cases
+    if (error && 'statusCode' in error) {
+      const statusCode = (error as { statusCode: number }).statusCode;
+
+      // Retry on server errors (5xx) and specific client errors
+      if (statusCode >= 500) {
+        return true;
+      }
+
+      // Retry on specific client errors
+      if (statusCode === 408 || statusCode === 429) {
+        return true; // Request Timeout or Too Many Requests
+      }
+
+      // Don't retry other client errors
+      if (statusCode >= 400 && statusCode < 500) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Linear backoff retry strategy
+ */
+export class LinearBackoffStrategy implements WebhookRetryStrategy {
+  constructor(
+    private delay: number = 5000, // 5 seconds
+    private maxRetries: number = 3
+  ) {}
+
+  getNextRetryDelay(attempt: number): number {
+    if (attempt >= this.maxRetries) {
+      return -1;
+    }
+
+    // Linear increase: delay * (attempt + 1)
+    return this.delay * (attempt + 1);
+  }
+
+  shouldRetry(attempt: number): boolean {
+    return attempt < this.maxRetries;
+  }
+}
+
+/**
+ * Fixed delay retry strategy
+ */
+export class FixedDelayStrategy implements WebhookRetryStrategy {
+  constructor(
+    private delay: number = 10000, // 10 seconds
+    private maxRetries: number = 3
+  ) {}
+
+  getNextRetryDelay(attempt: number): number {
+    if (attempt >= this.maxRetries) {
+      return -1;
+    }
+
+    return this.delay;
+  }
+
+  shouldRetry(attempt: number): boolean {
+    return attempt < this.maxRetries;
+  }
+}
+
+/**
+ * Custom retry delays strategy
+ */
+export class CustomDelayStrategy implements WebhookRetryStrategy {
+  constructor(private delays: number[]) {}
+
+  getNextRetryDelay(attempt: number): number {
+    if (attempt >= this.delays.length) {
+      return -1;
+    }
+
+    return this.delays[attempt] ?? -1;
+  }
+
+  shouldRetry(attempt: number): boolean {
+    return attempt < this.delays.length;
+  }
+}
+
+/**
+ * Retry utility functions
+ */
+
+/**
+ * Calculate next retry time
+ */
+export function calculateNextRetryTime(
+  attempt: number,
+  strategy: WebhookRetryStrategy
+): Date | null {
+  const delay = strategy.getNextRetryDelay(attempt);
+
+  if (delay < 0) {
+    return null;
+  }
+
+  return new Date(Date.now() + delay);
+}
+
+/**
+ * Check if delivery should be retried
+ */
+export function shouldRetryDelivery(
+  attempts: number,
+  strategy: WebhookRetryStrategy,
+  error?: Error
+): boolean {
+  return strategy.shouldRetry(attempts, error);
+}
+
+/**
+ * Get retry delay with exponential backoff
+ */
+export function getExponentialBackoff(
+  attempt: number,
+  initialDelay = 1000,
+  maxDelay = 60000,
+  multiplier = 2
+): number {
+  const delay = initialDelay * Math.pow(multiplier, attempt);
+  const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+  return Math.min(delay + jitter, maxDelay);
+}
+
+/**
+ * Create default retry strategy
+ */
+export function createDefaultRetryStrategy(): WebhookRetryStrategy {
+  return new ExponentialBackoffStrategy(1000, 60000, 2, 5);
+}
+
+/**
+ * Parse retry-after header
+ */
+export function parseRetryAfter(retryAfter: string | number): number {
+  if (typeof retryAfter === 'number') {
+    return retryAfter * 1000; // seconds to milliseconds
+  }
+
+  // Try parsing as number (seconds)
+  const seconds = parseInt(retryAfter, 10);
+  if (!isNaN(seconds)) {
+    return seconds * 1000;
+  }
+
+  // Try parsing as HTTP date
+  const date = new Date(retryAfter);
+  if (!isNaN(date.getTime())) {
+    return Math.max(0, date.getTime() - Date.now());
+  }
+
+  return 0;
+}

package/src/modules/webhook/signature.ts

@@ -0,0 +1,135 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+import type { WebhookSignature } from './types.js';
+
+/**
+ * Generate HMAC signature for webhook payload
+ */
+export function generateSignature(
+  payload: string | Record<string, unknown>,
+  secret: string,
+  timestamp?: number
+): WebhookSignature {
+  const ts = timestamp || Date.now();
+  const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload);
+
+  // Format: timestamp.payload
+  const signedPayload = `${ts}.${payloadString}`;
+
+  // Generate HMAC SHA256 signature
+  const signature = createHmac('sha256', secret).update(signedPayload).digest('hex');
+
+  return {
+    signature,
+    timestamp: ts,
+    version: 'v1',
+  };
+}
+
+/**
+ * Verify webhook signature
+ */
+export function verifySignature(
+  payload: string | Record<string, unknown>,
+  signature: string,
+  secret: string,
+  timestamp: number,
+  options: {
+    toleranceSeconds?: number;
+  } = {}
+): boolean {
+  const { toleranceSeconds = 300 } = options; // 5 minutes default tolerance
+
+  // Check timestamp tolerance
+  const now = Date.now();
+  const timeDiff = Math.abs(now - timestamp);
+
+  if (timeDiff > toleranceSeconds * 1000) {
+    return false;
+  }
+
+  // Generate expected signature
+  const expected = generateSignature(payload, secret, timestamp);
+
+  // Timing-safe comparison
+  try {
+    const receivedBuffer = Buffer.from(signature, 'hex');
+    const expectedBuffer = Buffer.from(expected.signature, 'hex');
+
+    if (receivedBuffer.length !== expectedBuffer.length) {
+      return false;
+    }
+
+    return timingSafeEqual(receivedBuffer, expectedBuffer);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse signature header
+ * Format: "t=<timestamp>,v1=<signature>"
+ */
+export function parseSignatureHeader(header: string): {
+  timestamp: number;
+  signature: string;
+} | null {
+  try {
+    const parts = header.split(',');
+    const result: { timestamp?: number; signature?: string } = {};
+
+    for (const part of parts) {
+      const [key, value] = part.split('=');
+      if (key === 't' && value) {
+        result.timestamp = parseInt(value, 10);
+      } else if (key === 'v1' && value) {
+        result.signature = value;
+      }
+    }
+
+    if (result.timestamp && result.signature) {
+      return {
+        timestamp: result.timestamp,
+        signature: result.signature,
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format signature for header
+ * Format: "t=<timestamp>,v1=<signature>"
+ */
+export function formatSignatureHeader(sig: WebhookSignature): string {
+  return `t=${sig.timestamp},v1=${sig.signature}`;
+}
+
+/**
+ * Generate webhook secret
+ */
+export function generateWebhookSecret(): string {
+  return createHmac('sha256', Date.now().toString()).update(Math.random().toString()).digest('hex');
+}
+
+/**
+ * Verify webhook signature from headers
+ */
+export function verifyWebhookSignature(
+  payload: string | Record<string, unknown>,
+  signatureHeader: string,
+  secret: string,
+  options: {
+    toleranceSeconds?: number;
+  } = {}
+): boolean {
+  const parsed = parseSignatureHeader(signatureHeader);
+
+  if (!parsed) {
+    return false;
+  }
+
+  return verifySignature(payload, parsed.signature, secret, parsed.timestamp, options);
+}

package/src/modules/webhook/types.ts

@@ -0,0 +1,181 @@
+export type WebhookEventType =
+  | 'user.created'
+  | 'user.updated'
+  | 'user.deleted'
+  | 'payment.succeeded'
+  | 'payment.failed'
+  | 'order.created'
+  | 'order.completed'
+  | 'order.cancelled'
+  | string; // Allow custom event types
+
+export type WebhookStatus = 'pending' | 'delivered' | 'failed' | 'disabled';
+
+export type WebhookDeliveryStatus = 'pending' | 'success' | 'failed' | 'retrying';
+
+export interface WebhookEndpoint {
+  /** Unique identifier */
+  id: string;
+  /** Endpoint URL */
+  url: string;
+  /** Secret for HMAC signature */
+  secret: string;
+  /** Events to listen for */
+  events: WebhookEventType[];
+  /** Whether the endpoint is active */
+  enabled: boolean;
+  /** Optional description */
+  description?: string;
+  /** Custom headers to send */
+  headers?: Record<string, string>;
+  /** Metadata */
+  metadata?: Record<string, unknown>;
+  /** Creation date */
+  createdAt: Date;
+  /** Last update date */
+  updatedAt: Date;
+}
+
+export interface WebhookEvent {
+  /** Unique identifier */
+  id: string;
+  /** Event type */
+  type: WebhookEventType;
+  /** Event payload */
+  payload: Record<string, unknown>;
+  /** When the event occurred */
+  occurredAt: Date;
+  /** Endpoints that should receive this event */
+  endpoints?: string[];
+}
+
+export interface WebhookDelivery {
+  /** Unique identifier */
+  id: string;
+  /** Webhook endpoint ID */
+  endpointId: string;
+  /** Event ID */
+  eventId: string;
+  /** Event type */
+  eventType: WebhookEventType;
+  /** Delivery status */
+  status: WebhookDeliveryStatus;
+  /** Number of attempts */
+  attempts: number;
+  /** Maximum attempts */
+  maxAttempts: number;
+  /** Next retry time */
+  nextRetryAt?: Date;
+  /** HTTP response status */
+  responseStatus?: number;
+  /** Response body */
+  responseBody?: string;
+  /** Error message if failed */
+  error?: string;
+  /** Request payload */
+  payload: Record<string, unknown>;
+  /** Creation date */
+  createdAt: Date;
+  /** Last attempt date */
+  lastAttemptAt?: Date;
+  /** Delivery completion date */
+  deliveredAt?: Date;
+}
+
+export interface WebhookConfig {
+  /** Default maximum retry attempts */
+  maxRetries?: number;
+  /** Initial retry delay in ms */
+  initialRetryDelay?: number;
+  /** Maximum retry delay in ms */
+  maxRetryDelay?: number;
+  /** Backoff multiplier */
+  backoffMultiplier?: number;
+  /** Request timeout in ms */
+  timeout?: number;
+  /** Enable signature verification */
+  enableSignature?: boolean;
+  /** Signature header name */
+  signatureHeader?: string;
+  /** Timestamp header name */
+  timestampHeader?: string;
+}
+
+export interface WebhookSignature {
+  /** Signature value */
+  signature: string;
+  /** Timestamp */
+  timestamp: number;
+  /** Version */
+  version: string;
+}
+
+export interface WebhookDeliveryAttempt {
+  /** Attempt number */
+  attempt: number;
+  /** HTTP status code */
+  statusCode?: number;
+  /** Response body */
+  responseBody?: string;
+  /** Error message */
+  error?: string;
+  /** Attempt timestamp */
+  timestamp: Date;
+  /** Duration in ms */
+  duration?: number;
+}
+
+export interface WebhookStats {
+  /** Total events sent */
+  totalEvents: number;
+  /** Successful deliveries */
+  successfulDeliveries: number;
+  /** Failed deliveries */
+  failedDeliveries: number;
+  /** Pending deliveries */
+  pendingDeliveries: number;
+  /** Average delivery time in ms */
+  averageDeliveryTime: number;
+  /** Success rate (0-100) */
+  successRate: number;
+}
+
+export interface WebhookFilter {
+  /** Filter by endpoint ID */
+  endpointId?: string;
+  /** Filter by event type */
+  eventType?: WebhookEventType;
+  /** Filter by status */
+  status?: WebhookDeliveryStatus;
+  /** Filter by date range */
+  startDate?: Date;
+  endDate?: Date;
+  /** Limit results */
+  limit?: number;
+  /** Offset for pagination */
+  offset?: number;
+}
+
+export interface CreateWebhookEndpointData {
+  url: string;
+  events: WebhookEventType[];
+  description?: string;
+  headers?: Record<string, string>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdateWebhookEndpointData {
+  url?: string;
+  events?: WebhookEventType[];
+  enabled?: boolean;
+  description?: string;
+  headers?: Record<string, string>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WebhookRetryStrategy {
+  /** Calculate next retry delay */
+  getNextRetryDelay(attempt: number): number;
+  /** Check if should retry */
+  shouldRetry(attempt: number, error?: Error): boolean;
+}