raffel 0.1.2 → 0.2.2

package/dist/mcp/docs/interceptors.js

@@ -1,7 +1,7 @@
 /**
  * Raffel MCP - Interceptor Documentation
  *
- * All built-in interceptors with options, examples, and use cases.
+ * Built-in interceptors with options, examples, and use cases.
  */
 export const interceptors = [
     // === Auth ===
@@ -11,30 +11,22 @@ export const interceptors = [
         category: 'auth',
         options: [
             {
-                name: 'strategy',
-                type: 'AuthStrategy',
+                name: 'strategies',
+                type: 'AuthStrategy[]',
                 required: true,
-                description: 'Authentication strategy (bearer, apiKey, static)',
+                description: 'Authentication strategies to try in order',
             },
             {
-                name: 'extractFrom',
-                type: "'header' | 'query' | 'cookie'",
+                name: 'publicProcedures',
+                type: 'string[]',
                 required: false,
-                default: "'header'",
-                description: 'Where to extract the credential from',
+                description: 'Procedures that skip authentication',
             },
             {
-                name: 'headerName',
-                type: 'string',
-                required: false,
-                default: "'Authorization'",
-                description: 'Header name for credential extraction',
-            },
-            {
-                name: 'onUnauthenticated',
-                type: '(ctx) => void',
+                name: 'onError',
+                type: '(error, envelope) => void',
                 required: false,
-                description: 'Callback when authentication fails',
+                description: 'Hook for strategy errors (non-fatal)',
             },
         ],
         examples: [
@@ -44,47 +36,18 @@ export const interceptors = [
 
 const server = createServer()
   .use(createAuthMiddleware({
-    strategy: createBearerStrategy({
-      validate: async (token) => {
-        const user = await verifyJwt(token)
-        return user ? { authenticated: true, principal: user } : { authenticated: false }
+    strategies: [createBearerStrategy({
+      verify: async (token) => {
+        const payload = await verifyJwt(token)
+        return payload ? { authenticated: true, principal: payload.sub, claims: payload } : null
       }
-    })
+    })]
   }))
   .procedure('users.me')
-    .handler(async (input, ctx) => {
-      // ctx.auth.principal contains the authenticated user
-      return ctx.auth.principal
+    .handler(async (_input, ctx) => {
+      return { userId: ctx.auth?.principal }
     })`,
             },
-            {
-                title: 'API Key Authentication',
-                code: `import { createServer, createAuthMiddleware, createApiKeyStrategy } from 'raffel'
-
-const server = createServer()
-  .use(createAuthMiddleware({
-    strategy: createApiKeyStrategy({
-      validate: async (key) => {
-        const app = await db.apiKeys.findByKey(key)
-        return app ? { authenticated: true, principal: app } : { authenticated: false }
-      },
-      extractFrom: 'header',
-      headerName: 'X-API-Key'
-    })
-  }))`,
-            },
-            {
-                title: 'Static API Key (Development)',
-                code: `import { createServer, createAuthMiddleware, createStaticApiKeyStrategy } from 'raffel'
-
-const server = createServer()
-  .use(createAuthMiddleware({
-    strategy: createStaticApiKeyStrategy({
-      keys: ['dev-key-123', 'test-key-456'],
-      principal: { role: 'admin' }
-    })
-  }))`,
-            },
         ],
     },
     {
@@ -99,24 +62,24 @@ const server = createServer()
                 description: 'Array of authorization rules to evaluate',
             },
             {
-                name: 'defaultDeny',
+                name: 'defaultAllow',
                 type: 'boolean',
                 required: false,
-                default: 'true',
-                description: 'Deny access if no rule matches',
+                default: 'false',
+                description: 'Allow access if no rule matches',
             },
         ],
         examples: [
             {
                 title: 'Role-Based Access Control',
-                code: `import { createServer, createAuthzMiddleware, hasRole, hasAnyRole } from 'raffel'
+                code: `import { createServer, createAuthzMiddleware, hasRole, hasAnyRole, requireAuth } from 'raffel'
 
 const server = createServer()
   .use(createAuthzMiddleware({
     rules: [
       { pattern: 'admin.*', check: hasRole('admin') },
       { pattern: 'users.delete', check: hasAnyRole(['admin', 'moderator']) },
-      { pattern: 'users.*', check: requireAuth() },
+      { pattern: 'users.*', check: requireAuth },
     ]
   }))`,
             },
@@ -142,11 +105,23 @@ const server = createServer()
                 default: '100',
                 description: 'Maximum requests per window',
             },
+            {
+                name: 'maxUniqueKeys',
+                type: 'number',
+                required: false,
+                description: 'Maximum unique keys to track',
+            },
+            {
+                name: 'skipSuccessfulRequests',
+                type: 'boolean',
+                required: false,
+                description: 'If true, successful requests are not counted',
+            },
             {
                 name: 'keyGenerator',
                 type: '(envelope, ctx) => string',
                 required: false,
-                description: 'Function to generate rate limit key (default: user or IP)',
+                description: 'Function to generate rate limit key (default: user or metadata)',
             },
             {
                 name: 'rules',
@@ -156,9 +131,8 @@ const server = createServer()
             },
             {
                 name: 'driver',
-                type: 'string | RateLimitDriver',
+                type: 'RateLimitDriverConfig | RateLimitDriver',
                 required: false,
-                default: 'memory',
                 description: 'Storage driver (memory, filesystem, redis, or custom)',
             },
         ],
@@ -170,27 +144,14 @@ const server = createServer()
 const server = createServer()
   .use(createRateLimitInterceptor({
     windowMs: 60 * 1000, // 1 minute
-    maxRequests: 100,    // 100 requests per minute
-  }))`,
-            },
-            {
-                title: 'Per-Procedure Rules',
-                code: `import { createServer, createRateLimitInterceptor } from 'raffel'
-
-const server = createServer()
-  .use(createRateLimitInterceptor({
     maxRequests: 100,
-    rules: [
-      { id: 'auth', pattern: 'auth.*', maxRequests: 5, windowMs: 60000 },
-      { id: 'reports', pattern: 'reports.*', maxRequests: 10, windowMs: 3600000 },
-    ]
   }))`,
             },
         ],
     },
     {
-        name: 'retry',
-        description: 'Automatic retry with exponential backoff for transient failures. Use for downstream service calls.',
+        name: 'createRetryInterceptor',
+        description: 'Automatic retry with backoff for transient failures. Use for downstream service calls.',
         category: 'resilience',
         options: [
             {
@@ -201,50 +162,55 @@ const server = createServer()
                 description: 'Maximum retry attempts',
             },
             {
-                name: 'initialDelay',
+                name: 'initialDelayMs',
                 type: 'number',
                 required: false,
-                default: '1000',
+                default: '100',
                 description: 'Initial delay in ms before first retry',
             },
             {
-                name: 'maxDelay',
+                name: 'maxDelayMs',
                 type: 'number',
                 required: false,
-                default: '30000',
+                default: '10000',
                 description: 'Maximum delay between retries',
             },
             {
-                name: 'backoffMultiplier',
-                type: 'number',
+                name: 'backoffStrategy',
+                type: "'linear' | 'exponential' | 'decorrelated'",
                 required: false,
-                default: '2',
-                description: 'Multiplier for exponential backoff',
+                default: "'exponential'",
+                description: 'Backoff strategy',
             },
             {
-                name: 'retryOn',
-                type: '(error) => boolean',
+                name: 'retryableCodes',
+                type: 'string[]',
                 required: false,
-                description: 'Predicate to decide if error is retryable',
+                description: 'Error codes that should trigger retry',
+            },
+            {
+                name: 'shouldRetry',
+                type: '(error, attempt) => boolean',
+                required: false,
+                description: 'Custom retry predicate',
             },
         ],
         examples: [
             {
-                title: 'Retry with Exponential Backoff',
-                code: `import { createServer, forPattern, retry } from 'raffel'
+                title: 'Retry External Calls',
+                code: `import { createServer, forPattern, createRetryInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('external.*', retry({
+  .use(forPattern('external.*', createRetryInterceptor({
     maxAttempts: 3,
-    initialDelay: 1000,
-    backoffMultiplier: 2,
-    retryOn: (err) => err.code === 'ECONNREFUSED' || err.status >= 500
+    initialDelayMs: 200,
+    retryableCodes: ['UNAVAILABLE', 'DEADLINE_EXCEEDED'],
   })))`,
             },
         ],
     },
     {
-        name: 'circuitBreaker',
+        name: 'createCircuitBreakerInterceptor',
         description: 'Circuit breaker pattern to prevent cascading failures. Opens circuit after threshold failures.',
         category: 'resilience',
         options: [
@@ -259,19 +225,32 @@ const server = createServer()
                 name: 'successThreshold',
                 type: 'number',
                 required: false,
-                default: '2',
+                default: '3',
                 description: 'Successes before circuit closes',
             },
             {
-                name: 'timeout',
+                name: 'resetTimeoutMs',
                 type: 'number',
                 required: false,
                 default: '30000',
-                description: 'Time in ms before attempting to close',
+                description: 'Time in ms before attempting recovery',
+            },
+            {
+                name: 'windowMs',
+                type: 'number',
+                required: false,
+                default: '60000',
+                description: 'Failure counting window in ms',
+            },
+            {
+                name: 'failureCodes',
+                type: 'string[]',
+                required: false,
+                description: 'Error codes that count as failures',
             },
             {
                 name: 'onStateChange',
-                type: '(state) => void',
+                type: '(state, procedure) => void',
                 required: false,
                 description: 'Callback when circuit state changes',
             },
@@ -279,70 +258,64 @@ const server = createServer()
         examples: [
             {
                 title: 'Circuit Breaker for External Service',
-                code: `import { createServer, forPattern, circuitBreaker } from 'raffel'
+                code: `import { createServer, forPattern, createCircuitBreakerInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('payments.*', circuitBreaker({
-    failureThreshold: 5,   // Open after 5 failures
-    successThreshold: 2,   // Close after 2 successes in half-open
-    timeout: 30000,        // Try half-open after 30s
-    onStateChange: (state) => {
-      console.log(\`Circuit breaker state: \${state}\`)
-      if (state === 'open') alertOps('Payment service circuit open!')
-    }
+  .use(forPattern('payments.*', createCircuitBreakerInterceptor({
+    failureThreshold: 5,
+    resetTimeoutMs: 30000,
   })))`,
             },
         ],
     },
     {
-        name: 'timeout',
-        description: 'Enforces deadline on handler execution. Rejects with DEADLINE_EXCEEDED if exceeded.',
+        name: 'createTimeoutInterceptor',
+        description: 'Enforces deadline on handler execution (DEADLINE_EXCEEDED on timeout).',
         category: 'resilience',
         options: [
             {
-                name: 'ms',
+                name: 'defaultMs',
                 type: 'number',
-                required: true,
-                description: 'Timeout in milliseconds',
+                required: false,
+                default: '30000',
+                description: 'Default timeout in ms',
+            },
+            {
+                name: 'procedures',
+                type: 'Record<string, number>',
+                required: false,
+                description: 'Per-procedure timeouts',
             },
             {
-                name: 'onTimeout',
-                type: '(ctx) => void',
+                name: 'patterns',
+                type: 'Record<string, number>',
                 required: false,
-                description: 'Callback when timeout occurs',
+                description: 'Pattern-based timeouts',
             },
         ],
         examples: [
             {
                 title: 'Global Timeout',
-                code: `import { createServer, timeout } from 'raffel'
-
-const server = createServer()
-  .use(timeout({ ms: 30000 })) // 30 second timeout for all procedures`,
-            },
-            {
-                title: 'Per-Procedure Timeout',
-                code: `import { createServer, forPattern, timeout } from 'raffel'
+                code: `import { createServer, createTimeoutInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('reports.*', timeout({ ms: 120000 }))) // 2 min for reports
-  .use(timeout({ ms: 10000 })) // 10s default`,
+  .use(createTimeoutInterceptor({ defaultMs: 30000 }))`,
             },
         ],
     },
     {
-        name: 'bulkhead',
+        name: 'createBulkheadInterceptor',
         description: 'Limits concurrent executions to isolate failures. Prevents one slow procedure from consuming all resources.',
         category: 'resilience',
         options: [
             {
-                name: 'maxConcurrent',
+                name: 'concurrency',
                 type: 'number',
                 required: true,
                 description: 'Maximum concurrent executions',
             },
             {
-                name: 'maxQueue',
+                name: 'maxQueueSize',
                 type: 'number',
                 required: false,
                 default: '0',
@@ -352,36 +325,49 @@ const server = createServer()
                 name: 'queueTimeout',
                 type: 'number',
                 required: false,
+                default: '0',
                 description: 'Max time to wait in queue (ms)',
             },
+            {
+                name: 'onReject',
+                type: '(procedure) => void',
+                required: false,
+                description: 'Callback when a request is rejected',
+            },
         ],
         examples: [
             {
                 title: 'Limit Concurrent Database Queries',
-                code: `import { createServer, forPattern, bulkhead } from 'raffel'
+                code: `import { createServer, forPattern, createBulkheadInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('db.*', bulkhead({
-    maxConcurrent: 10, // Max 10 concurrent DB queries
-    maxQueue: 50,      // Queue up to 50 more
-    queueTimeout: 5000 // Wait max 5s in queue
+  .use(forPattern('db.*', createBulkheadInterceptor({
+    concurrency: 10,
+    maxQueueSize: 50,
+    queueTimeout: 5000,
   })))`,
             },
         ],
     },
     {
-        name: 'fallback',
+        name: 'createFallbackInterceptor',
         description: 'Provides fallback response when handler fails. Useful for graceful degradation.',
         category: 'resilience',
         options: [
             {
-                name: 'fallback',
-                type: '(error, ctx) => unknown',
-                required: true,
-                description: 'Function returning fallback value',
+                name: 'response',
+                type: 'unknown',
+                required: false,
+                description: 'Static fallback response',
+            },
+            {
+                name: 'handler',
+                type: '(ctx, error) => unknown',
+                required: false,
+                description: 'Dynamic fallback handler',
             },
             {
-                name: 'shouldFallback',
+                name: 'when',
                 type: '(error) => boolean',
                 required: false,
                 description: 'Predicate to decide if fallback should be used',
@@ -390,15 +376,14 @@ const server = createServer()
         examples: [
             {
                 title: 'Fallback to Cached Data',
-                code: `import { createServer, forPattern, fallback } from 'raffel'
+                code: `import { createServer, forPattern, createFallbackInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('prices.*', fallback({
-    fallback: async (error, ctx) => {
-      // Return cached data on failure
-      return await cache.get(\`prices:\${ctx.procedure}\`) || { prices: [], stale: true }
+  .use(forPattern('prices.*', createFallbackInterceptor({
+    handler: async (_ctx, error) => {
+      return await cache.get('prices') || { prices: [], stale: true, reason: error.message }
     },
-    shouldFallback: (err) => err.code === 'SERVICE_UNAVAILABLE'
+    when: (err) => (err as any).code === 'UNAVAILABLE',
   })))`,
             },
         ],
@@ -406,7 +391,7 @@ const server = createServer()
     // === Observability ===
     {
         name: 'createMetricsInterceptor',
-        description: 'Auto-instruments all procedures with Prometheus-compatible metrics (latency, count, errors).',
+        description: 'Auto-instruments procedures with metrics (latency, count, errors).',
         category: 'observability',
         options: [
             {
@@ -415,18 +400,6 @@ const server = createServer()
                 required: true,
                 description: 'Metric registry for storing metrics',
             },
-            {
-                name: 'buckets',
-                type: 'number[]',
-                required: false,
-                description: 'Histogram buckets for latency',
-            },
-            {
-                name: 'labels',
-                type: '(ctx) => Record<string, string>',
-                required: false,
-                description: 'Additional labels to add to metrics',
-            },
         ],
         examples: [
             {
@@ -435,15 +408,7 @@ const server = createServer()
 
 const metrics = createMetricRegistry()
 const server = createServer()
-  .use(createMetricsInterceptor({ registry: metrics }))
-
-// Metrics automatically collected:
-// - raffel_procedure_duration_seconds (histogram)
-// - raffel_procedure_total (counter)
-// - raffel_procedure_errors_total (counter)
-
-server.procedure('metrics.export')
-  .handler(async () => exportPrometheus(metrics))`,
+  .use(createMetricsInterceptor(metrics))`,
             },
         ],
     },
@@ -458,18 +423,6 @@ server.procedure('metrics.export')
                 required: true,
                 description: 'Tracer instance for creating spans',
             },
-            {
-                name: 'spanName',
-                type: '(ctx) => string',
-                required: false,
-                description: 'Custom span name generator',
-            },
-            {
-                name: 'attributes',
-                type: '(ctx) => SpanAttributes',
-                required: false,
-                description: 'Additional span attributes',
-            },
         ],
         examples: [
             {
@@ -483,22 +436,22 @@ server.procedure('metrics.export')
 
 const tracer = createTracer({
   serviceName: 'my-api',
-  exporter: createJaegerExporter({ endpoint: 'http://localhost:14268/api/traces' })
+  exporters: [createJaegerExporter({ serviceName: 'my-api' })],
 })
 
 const server = createServer()
-  .use(createTracingInterceptor({ tracer }))`,
+  .use(createTracingInterceptor(tracer))`,
             },
         ],
     },
     {
-        name: 'logging',
+        name: 'createLoggingInterceptor',
         description: 'Structured logging for request/response with configurable levels and formats.',
         category: 'observability',
         options: [
             {
                 name: 'level',
-                type: "'debug' | 'info' | 'warn' | 'error'",
+                type: "'trace' | 'debug' | 'info' | 'warn' | 'error'",
                 required: false,
                 default: "'info'",
                 description: 'Log level',
@@ -507,35 +460,47 @@ const server = createServer()
                 name: 'format',
                 type: "'json' | 'pretty'",
                 required: false,
-                default: "'json'",
+                default: "'pretty'",
                 description: 'Log output format',
             },
             {
-                name: 'includeInput',
+                name: 'includePayload',
+                type: 'boolean',
+                required: false,
+                default: 'false',
+                description: 'Include request payload in logs',
+            },
+            {
+                name: 'includeResponse',
                 type: 'boolean',
                 required: false,
                 default: 'false',
-                description: 'Include request input in logs (careful with PII)',
+                description: 'Include response payload in logs',
             },
             {
-                name: 'includeOutput',
+                name: 'includeMetadata',
                 type: 'boolean',
                 required: false,
                 default: 'false',
-                description: 'Include response output in logs',
+                description: 'Include metadata (headers) in logs',
+            },
+            {
+                name: 'excludeProcedures',
+                type: 'string[]',
+                required: false,
+                description: 'Procedure patterns to exclude',
             },
         ],
         examples: [
             {
                 title: 'Production Logging',
-                code: `import { createServer, logging, forPattern, except } from 'raffel'
+                code: `import { createServer, createLoggingInterceptor, except } from 'raffel'
 
 const server = createServer()
-  .use(except('health.*', logging({
+  .use(except(['health.*'], createLoggingInterceptor({
     level: 'info',
     format: 'json',
-    includeInput: false,  // Don't log PII
-    includeOutput: false
+    includeMetadata: false,
   })))`,
             },
         ],
@@ -543,155 +508,118 @@ const server = createServer()
     // === Validation ===
     {
         name: 'createValidationInterceptor',
-        description: 'Validates input/output against registered schemas. Supports Zod, Yup, Joi, Ajv, fastest-validator.',
+        description: 'Validates input/output against a schema for a specific handler.',
         category: 'validation',
         options: [
             {
-                name: 'validateInput',
-                type: 'boolean',
-                required: false,
-                default: 'true',
-                description: 'Validate request input',
-            },
-            {
-                name: 'validateOutput',
-                type: 'boolean',
-                required: false,
-                default: 'false',
-                description: 'Validate response output',
-            },
-            {
-                name: 'onError',
-                type: '(errors) => void',
-                required: false,
-                description: 'Callback on validation error',
+                name: 'schema',
+                type: 'HandlerSchema',
+                required: true,
+                description: 'Schema with input/output validators',
             },
         ],
         examples: [
             {
                 title: 'Zod Validation',
-                code: `import { createServer, createValidationInterceptor, registerValidator, createZodAdapter } from 'raffel'
+                code: `import { createServer, createValidationInterceptor } from 'raffel'
 import { z } from 'zod'
 
-registerValidator(createZodAdapter(z))
+const schema = {
+  input: z.object({ email: z.string().email() }),
+  output: z.object({ id: z.string(), email: z.string() }),
+}
 
 const server = createServer()
-  .use(createValidationInterceptor({ validateInput: true, validateOutput: true }))
   .procedure('users.create')
-    .input(z.object({
-      email: z.string().email(),
-      name: z.string().min(2).max(100),
-      age: z.number().min(18).optional()
-    }))
-    .output(z.object({
-      id: z.string(),
-      email: z.string(),
-      name: z.string()
-    }))
-    .handler(async (input, ctx) => {
-      // Input is already validated and typed!
-      return await db.users.create(input)
-    })`,
+    .use(createValidationInterceptor(schema))
+    .handler(async (input) => createUser(input))`,
             },
         ],
     },
     // === Caching ===
     {
-        name: 'cache',
-        description: 'Response caching with pluggable drivers (memory, file, Redis, S3DB). Supports TTL and invalidation.',
+        name: 'createCacheInterceptor',
+        description: 'Response caching with pluggable drivers. Supports TTL, stale-while-revalidate, and invalidation.',
         category: 'caching',
         options: [
+            {
+                name: 'ttlMs',
+                type: 'number',
+                required: false,
+                default: '60000',
+                description: 'Time-to-live in milliseconds',
+            },
             {
                 name: 'driver',
                 type: 'CacheDriver',
-                required: true,
-                description: 'Cache driver instance',
+                required: false,
+                description: 'Cache driver instance (memory, redis, file, s3db)',
             },
             {
-                name: 'ttl',
-                type: 'number',
+                name: 'procedures',
+                type: 'string[]',
                 required: false,
-                default: '60000',
-                description: 'Time-to-live in milliseconds',
+                description: 'Procedures to include (glob patterns supported)',
             },
             {
-                name: 'keyGenerator',
-                type: '(ctx, input) => string',
+                name: 'excludeProcedures',
+                type: 'string[]',
                 required: false,
-                description: 'Custom cache key generator',
+                description: 'Procedures to exclude',
             },
             {
-                name: 'shouldCache',
-                type: '(ctx, result) => boolean',
+                name: 'keyGenerator',
+                type: '(envelope) => string',
                 required: false,
-                description: 'Predicate to decide if response should be cached',
+                description: 'Custom cache key generator',
             },
         ],
         examples: [
             {
-                title: 'In-Memory Caching',
-                code: `import { createServer, forPattern, cache, createCacheMemoryDriver } from 'raffel'
+                title: 'Redis Cache',
+                code: `import { createServer } from 'raffel'
+import { createCacheInterceptor } from 'raffel/middleware'
+import { createDriver } from 'raffel/cache'
 
-const memoryCache = createCacheMemoryDriver({
-  maxSize: 1000,
-  evictionPolicy: 'lru'
-})
+const redisDriver = await createDriver('redis', { client: redis })
+const cache = createCacheInterceptor({ ttlMs: 60000, driver: redisDriver })
 
-const server = createServer()
-  .use(forPattern('products.list', cache({
-    driver: memoryCache,
-    ttl: 5 * 60 * 1000, // 5 minutes
-    keyGenerator: (ctx, input) => \`products:\${JSON.stringify(input)}\`
-  })))`,
-            },
-            {
-                title: 'Redis Distributed Cache',
-                code: `import { createServer, forPattern, cache, createCacheRedisDriver } from 'raffel'
-import Redis from 'ioredis'
-
-const redisCache = createCacheRedisDriver({
-  client: new Redis(process.env.REDIS_URL),
-  prefix: 'cache:'
-})
-
-const server = createServer()
-  .use(forPattern('*', cache({
-    driver: redisCache,
-    ttl: 60000,
-    shouldCache: (ctx, result) => !ctx.auth // Don't cache authenticated responses
-  })))`,
+const server = createServer().use(cache)`,
             },
         ],
     },
     {
-        name: 'dedup',
+        name: 'createDedupInterceptor',
         description: 'Request deduplication to prevent duplicate processing of identical concurrent requests.',
         category: 'caching',
         options: [
             {
-                name: 'windowMs',
+                name: 'ttlMs',
                 type: 'number',
                 required: false,
-                default: '1000',
-                description: 'Deduplication window in milliseconds',
+                default: '30000',
+                description: 'TTL for pending requests',
             },
             {
                 name: 'keyGenerator',
-                type: '(ctx, input) => string',
+                type: '(envelope, ctx) => string',
                 required: false,
                 description: 'Custom dedup key generator',
             },
+            {
+                name: 'procedures',
+                type: 'string[]',
+                required: false,
+                description: 'Procedures to deduplicate (glob patterns)',
+            },
         ],
         examples: [
             {
                 title: 'Prevent Double Submit',
-                code: `import { createServer, forPattern, dedup } from 'raffel'
+                code: `import { createServer, forPattern, createDedupInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(forPattern('orders.create', dedup({
-    windowMs: 5000, // 5 second window
-    keyGenerator: (ctx, input) => \`order:\${ctx.auth.principal.id}:\${input.idempotencyKey}\`
-  })))`,
+  .use(forPattern('orders.create', createDedupInterceptor()))`,
             },
         ],
     },
@@ -711,16 +639,14 @@ const server = createServer()
         examples: [
             {
                 title: 'Compose Production Stack',
-                code: `import { createServer, compose, timeout, logging, cache } from 'raffel'
+                code: `import { createServer, compose, createTimeoutInterceptor, createLoggingInterceptor } from 'raffel'
 
 const productionStack = compose(
-  timeout({ ms: 30000 }),
-  logging({ level: 'info', format: 'json' }),
-  cache({ driver: memoryCache, ttl: 60000 })
+  createTimeoutInterceptor({ defaultMs: 30000 }),
+  createLoggingInterceptor({ level: 'info', format: 'json' })
 )
 
-const server = createServer()
-  .use(productionStack)`,
+const server = createServer().use(productionStack)`,
             },
         ],
     },
@@ -731,7 +657,7 @@ const server = createServer()
         options: [
             {
                 name: 'predicate',
-                type: '(ctx) => boolean',
+                type: '(envelope, ctx) => boolean',
                 required: true,
                 description: 'Condition to evaluate',
             },
@@ -744,13 +670,13 @@ const server = createServer()
         ],
         examples: [
             {
-                title: 'Environment-Based Middleware',
-                code: `import { createServer, when, logging } from 'raffel'
+                title: 'Environment-Based Logging',
+                code: `import { createServer, when, createLoggingInterceptor } from 'raffel'
 
 const server = createServer()
   .use(when(
     () => process.env.NODE_ENV === 'development',
-    logging({ level: 'debug', format: 'pretty', includeInput: true })
+    createLoggingInterceptor({ level: 'debug', format: 'pretty' })
   ))`,
             },
         ],
@@ -762,9 +688,9 @@ const server = createServer()
         options: [
             {
                 name: 'pattern',
-                type: 'string | string[]',
+                type: 'string',
                 required: true,
-                description: 'Glob pattern(s) to match (e.g., "users.*", "admin.**")',
+                description: 'Glob pattern to match (e.g., "users.*", "admin.**")',
             },
             {
                 name: 'interceptor',
@@ -787,14 +713,14 @@ const server = createServer()
     },
     {
         name: 'except',
-        description: 'Applies interceptor to all procedures except those matching patterns.',
+        description: 'Applies interceptor to all procedures except those matching names.',
         category: 'composition',
         options: [
             {
-                name: 'pattern',
-                type: 'string | string[]',
+                name: 'procedures',
+                type: 'string[]',
                 required: true,
-                description: 'Pattern(s) to exclude',
+                description: 'Procedures to exclude',
             },
             {
                 name: 'interceptor',
@@ -806,10 +732,10 @@ const server = createServer()
         examples: [
             {
                 title: 'Exclude Health Checks from Logging',
-                code: `import { createServer, except, logging } from 'raffel'
+                code: `import { createServer, except, createLoggingInterceptor } from 'raffel'
 
 const server = createServer()
-  .use(except('health.*', logging({ level: 'info' })))`,
+  .use(except(['health.check'], createLoggingInterceptor({ level: 'info' })))`,
             },
         ],
     },
@@ -820,7 +746,7 @@ const server = createServer()
         options: [
             {
                 name: 'predicate',
-                type: '(ctx) => boolean',
+                type: '(envelope, ctx) => boolean',
                 required: true,
                 description: 'Condition to branch on',
             },
@@ -840,13 +766,13 @@ const server = createServer()
         examples: [
             {
                 title: 'Different Caching by Auth Status',
-                code: `import { createServer, branch, cache } from 'raffel'
+                code: `import { createServer, branch, createCacheInterceptor } from 'raffel'
 
 const server = createServer()
   .use(branch(
-    (ctx) => !ctx.auth?.authenticated,
-    cache({ driver: publicCache, ttl: 300000 }),  // 5 min for public
-    cache({ driver: privateCache, ttl: 60000 })   // 1 min for authenticated
+    (_env, ctx) => !ctx.auth?.authenticated,
+    createCacheInterceptor({ ttlMs: 300000 }),  // 5 min for public
+    createCacheInterceptor({ ttlMs: 60000 })    // 1 min for authenticated
   ))`,
             },
         ],