@tamyla/clodo-framework 4.4.1 → 4.5.0

package/README.md

@@ -23,6 +23,7 @@ A comprehensive framework for building enterprise-grade software architecture on
 - **[Programmatic API](docs/api/PROGRAMMATIC_API.md)** - Complete programmatic usage
 - **[Parameter Reference](docs/api/parameter_reference.md)** - All parameters and validation
 - **[Error Reference](docs/errors.md)** - Error codes and troubleshooting
+- **[Utilities Guide](docs/utilities/README.md)** - Cloudflare API extensions and integrations
 
 ### 📖 **Guides & Migration**
 - **[Getting Started](docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md)** - Step-by-step tutorial
@@ -137,6 +138,16 @@ The Clodo Framework has undergone rigorous validation to ensure it delivers on i
 - **Configuration Override**: Environment-specific settings
 - **Template Enhancement**: Service-specific customizations
 
+### Cloudflare API Utilities (v4.4.0+)
+- **AI Integration**: Workers AI for text generation, analysis, and embeddings
+- **Storage Solutions**: R2 object storage and KV key-value store
+- **Real-time Features**: Queues for messaging, Durable Objects for state
+- **Advanced Analytics**: Custom metrics and performance monitoring
+- **Email Processing**: Inbound/outbound email handling
+- **Vector Databases**: AI-powered semantic search capabilities
+
+> **💡 Utilities are optional extensions** - use them when you need advanced Cloudflare features. See [Utilities Guide](docs/utilities/README.md) for integration examples.
+
 ## 🚀 Three-Tier Service Creation
 
 The Clodo Framework implements a sophisticated three-tier service creation process that transforms your requirements into production-ready Cloudflare services:
@@ -264,30 +275,45 @@ The project is organized for maximum clarity and maintainability:
 
 ```
 clodo-framework/
-├── docs/           # 📖 Public-facing documentation (API reference, guides)
-├── i-docs/         # 📚 Internal documentation (organized by category)
-│   ├── architecture/     # Design docs, audits, specs
-│   ├── development/      # Dev guides, improvements
-│   ├── testing/          # Test plans, validation
-│   ├── deployment/       # Deployment analysis, fixes
-│   ├── roadmap/          # Strategic planning
-│   ├── guides/           # Integration guides
-│   ├── session-reports/  # Development sessions
-│   ├── phases/           # Phase completions
-│   ├── analysis/         # Technical analysis
-│   └── licensing/        # License information
-├── src/            # 💻 Source code
-├── test/           # ✅ Test suites (Latest CI: 115 suites; 2113 tests passed, 4 skipped)
-├── bin/            # 🔧 CLI executables
-├── dist/           # 📦 Built distribution
-└── templates/      # 📋 Service templates
+├── docs/                    # 📖 Public documentation
+│   ├── strategic/          # Business strategy & planning
+│   ├── utilities/          # Utility integration guides
+│   ├── api/                # API reference & guides
+│   ├── integration/        # Integration & migration guides
+│   └── phases/             # Framework development phases
+├── i-docs/                  # 📚 Internal documentation (organized by category)
+│   ├── architecture/       # Design docs, audits, specs
+│   ├── development/        # Dev guides, improvements
+│   ├── testing/            # Test plans, validation
+│   ├── deployment/         # Deployment analysis, fixes
+│   ├── roadmap/            # Strategic planning
+│   ├── guides/             # Integration guides
+│   ├── session-reports/    # Development sessions
+│   ├── phases/             # Phase completions
+│   ├── analysis/           # Technical analysis
+│   └── licensing/          # License information
+├── src/                     # 💻 Source code
+├── test/                    # ✅ Test suites (Latest CI: 115 suites; 2113 tests passed, 4 skipped)
+├── cli/                     # 🔧 CLI tools & commands
+├── examples/                # 📚 Usage examples & demos
+├── config/                  # ⚙️ Configuration files & examples
+├── scripts/                 # 🛠️ Build & utility scripts
+├── templates/               # 📋 Service templates
+├── dist/                    # 📦 Built distribution
+├── lib/                     # 📚 Compiled libraries
+├── .logs/                   # 📝 Log files (hidden)
+├── .tmp/                    # 🗂️ Temporary files (hidden)
+├── backups/                 # 💾 Backup files
+├── deployments/             # 🚀 Deployment artifacts
+├── secrets/                 # 🔐 Secret management
+└── coverage/                # 📊 Test coverage reports
 
 ```
 
 **Quality Metrics:**
 - ✅ **Latest CI (2026-02-04): 115 test suites passed; 4 tests skipped; 2113/2117 tests passed**
 - ✅ **CLI tests:** passing (all CLI-specific tests passed in the latest run)
-- ✅ **Clean architecture** (no temporary or duplicate files)
+- ✅ **Clean architecture** (organized file structure, no clutter in root)
 - ✅ **Configuration-based** (no hard-coded values in source)
 
 ## 📚 Incremental Adoption

package/dist/cli/commands/add.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+/**
+ * clodo add — Incremental enhancement command
+ * 
+ * Adds Cloudflare bindings, middleware, and features to an existing
+ * Clodo-generated Worker project without regenerating from scratch.
+ * 
+ * Usage:
+ *   npx clodo add ai              # Add Workers AI binding
+ *   npx clodo add kv               # Add KV namespace
+ *   npx clodo add kv:users         # Add KV with custom binding name
+ *   npx clodo add d1               # Add D1 database
+ *   npx clodo add r2               # Add R2 storage
+ *   npx clodo add vectorize        # Add Vectorize index
+ *   npx clodo add queues           # Add Queue producer/consumer
+ *   npx clodo add cron             # Add scheduled handler
+ *   npx clodo add auth:bearer      # Add bearer token middleware
+ *   npx clodo add auth:apikey      # Add API key middleware
+ *   npx clodo add email            # Add Email Workers
+ *   npx clodo add hyperdrive       # Add Hyperdrive (Postgres)
+ *   npx clodo add analytics        # Add Analytics Engine
+ *   npx clodo add browser          # Add Browser Rendering
+ * 
+ * @module cli/commands/add
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+/**
+ * TOML snippets for each feature binding
+ */
+const BINDING_TOML = {
+  ai: `
+# ═══ Workers AI ════════════════════════════════════════════════════
+[ai]
+binding = "AI"`,
+  kv: (bindingName = 'KV') => `
+# ═══ KV Namespace ══════════════════════════════════════════════════
+[[kv_namespaces]]
+binding = "${bindingName}"
+id = ""`,
+  d1: (dbName = 'my-db') => `
+# ═══ D1 Database ═══════════════════════════════════════════════════
+[[d1_databases]]
+binding = "DB"
+database_name = "${dbName}"
+database_id = ""`,
+  r2: (bucketName = 'my-storage') => `
+# ═══ R2 Object Storage ═════════════════════════════════════════════
+[[r2_buckets]]
+binding = "R2_STORAGE"
+bucket_name = "${bucketName}"`,
+  vectorize: (indexName = 'my-index') => `
+# ═══ Vectorize ═════════════════════════════════════════════════════
+[[vectorize]]
+binding = "VECTORIZE_INDEX"
+index_name = "${indexName}"`,
+  queues: (queueName = 'my-queue') => `
+# ═══ Queues ════════════════════════════════════════════════════════
+[[queues.producers]]
+binding = "QUEUE"
+queue = "${queueName}"
+
+[[queues.consumers]]
+queue = "${queueName}"
+max_batch_size = 10
+max_batch_timeout = 30
+max_retries = 3`,
+  cron: `
+# ═══ Cron Triggers ═════════════════════════════════════════════════
+[triggers]
+crons = ["*/5 * * * *"]`,
+  email: `
+# ═══ Email Workers ═════════════════════════════════════════════════
+[send_email]
+binding = "EMAIL"`,
+  hyperdrive: `
+# ═══ Hyperdrive ════════════════════════════════════════════════════
+[[hyperdrive]]
+binding = "HYPERDRIVE"
+id = ""`,
+  analytics: (workerName = 'my-worker') => `
+# ═══ Analytics Engine ══════════════════════════════════════════════
+[[analytics_engine_datasets]]
+binding = "ANALYTICS"
+dataset = "${workerName}-analytics"`,
+  browser: `
+# ═══ Browser Rendering ═════════════════════════════════════════════
+[browser]
+binding = "BROWSER"`
+};
+
+/**
+ * Import snippets to add to the worker entry point
+ */
+const IMPORT_SNIPPETS = {
+  ai: {
+    framework: [],
+    utilities: ['runAIModel', 'streamAIResponse'],
+    envBinding: 'AI'
+  },
+  kv: {
+    framework: [],
+    utilities: ['getKV', 'putKV', 'listKV', 'deleteKV'],
+    envBinding: 'KV'
+  },
+  d1: {
+    framework: [],
+    utilities: [],
+    envBinding: 'DB'
+  },
+  r2: {
+    framework: [],
+    utilities: ['putR2Object', 'getR2Object'],
+    envBinding: 'R2_STORAGE'
+  },
+  vectorize: {
+    framework: [],
+    utilities: ['queryVectors', 'upsertVectors'],
+    envBinding: 'VECTORIZE_INDEX'
+  },
+  queues: {
+    framework: [],
+    utilities: [],
+    envBinding: 'QUEUE'
+  },
+  'auth:bearer': {
+    framework: ['createBearerAuth'],
+    utilities: [],
+    envBinding: null
+  },
+  'auth:apikey': {
+    framework: ['createApiKeyAuth'],
+    utilities: [],
+    envBinding: null
+  },
+  email: {
+    framework: [],
+    utilities: ['sendEmail'],
+    envBinding: 'EMAIL'
+  },
+  hyperdrive: {
+    framework: [],
+    utilities: [],
+    envBinding: 'HYPERDRIVE'
+  },
+  analytics: {
+    framework: [],
+    utilities: [],
+    envBinding: 'ANALYTICS'
+  },
+  browser: {
+    framework: [],
+    utilities: [],
+    envBinding: 'BROWSER'
+  }
+};
+
+/**
+ * Parse feature argument (e.g., "kv:users" → { feature: "kv", name: "users" })
+ */
+function parseFeatureArg(arg) {
+  const [feature, name] = arg.split(':');
+  return {
+    feature: feature.toLowerCase(),
+    name
+  };
+}
+
+/**
+ * Add a feature to an existing project
+ */
+export async function addFeature(featureArg, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const {
+    feature,
+    name
+  } = parseFeatureArg(featureArg);
+  const results = {
+    feature,
+    wranglerUpdated: false,
+    envGuardUpdated: false,
+    importsAdded: [],
+    instructions: []
+  };
+
+  // 1. Update wrangler.toml
+  const wranglerPath = join(cwd, 'wrangler.toml');
+  if (existsSync(wranglerPath)) {
+    const wranglerContent = readFileSync(wranglerPath, 'utf8');
+
+    // Check if binding already exists
+    const bindingCheck = {
+      ai: '[ai]',
+      kv: '[[kv_namespaces]]',
+      d1: '[[d1_databases]]',
+      r2: '[[r2_buckets]]',
+      vectorize: '[[vectorize]]',
+      queues: '[[queues.',
+      cron: '[triggers]',
+      email: '[send_email]',
+      hyperdrive: '[[hyperdrive]]',
+      analytics: '[[analytics_engine_datasets]]',
+      browser: '[browser]'
+    };
+    const baseFeature = feature.includes(':') ? feature.split(':')[0] : feature;
+    if (bindingCheck[baseFeature] && wranglerContent.includes(bindingCheck[baseFeature])) {
+      results.instructions.push(`⚠️  ${baseFeature} binding already exists in wrangler.toml`);
+    } else {
+      const tomlSnippet = typeof BINDING_TOML[baseFeature] === 'function' ? BINDING_TOML[baseFeature](name || undefined) : BINDING_TOML[baseFeature];
+      if (tomlSnippet) {
+        writeFileSync(wranglerPath, wranglerContent.trimEnd() + '\n' + tomlSnippet + '\n', 'utf8');
+        results.wranglerUpdated = true;
+        results.instructions.push(`✅ Added ${baseFeature} binding to wrangler.toml`);
+      }
+    }
+  } else {
+    results.instructions.push('⚠️  No wrangler.toml found. Create one first with: npx clodo create');
+  }
+
+  // 2. Show import suggestions
+  const importInfo = IMPORT_SNIPPETS[feature] || IMPORT_SNIPPETS[feature.split(':')[0]];
+  if (importInfo) {
+    if (importInfo.framework.length > 0) {
+      results.importsAdded.push(`import { ${importInfo.framework.join(', ')} } from '@tamyla/clodo-framework';`);
+      results.instructions.push(`📦 Add to your worker: import { ${importInfo.framework.join(', ')} } from '@tamyla/clodo-framework';`);
+    }
+    if (importInfo.utilities.length > 0) {
+      results.importsAdded.push(`import { ${importInfo.utilities.join(', ')} } from '@tamyla/clodo-framework/utilities';`);
+      results.instructions.push(`📦 Add to your worker: import { ${importInfo.utilities.join(', ')} } from '@tamyla/clodo-framework/utilities';`);
+    }
+    if (importInfo.envBinding) {
+      results.instructions.push(`🔧 Add '${importInfo.envBinding}' to your createEnvironmentGuard({ required: [...] })`);
+    }
+  }
+
+  // 3. Feature-specific setup instructions
+  const setupInstructions = {
+    ai: '🚀 Workers AI is ready! Use env.AI.run(model, options) in your handler.',
+    kv: `🚀 Run: wrangler kv namespace create "${name || 'KV'}" to create the namespace, then paste the ID.`,
+    d1: `🚀 Run: wrangler d1 create "${name || 'my-db'}" to create the database.`,
+    r2: `🚀 Run: wrangler r2 bucket create "${name || 'my-storage'}" to create the bucket.`,
+    vectorize: `🚀 Run: wrangler vectorize create "${name || 'my-index'}" --dimensions 768 --metric cosine`,
+    queues: `🚀 Queue "${name || 'my-queue'}" will be auto-created on first deploy.`,
+    cron: '🚀 Cron trigger added. Implement the scheduled() handler in your worker.',
+    'auth:bearer': '🔐 Add createBearerAuth({ token: env.SECRET_KEY }) to your middleware stack.',
+    'auth:apikey': '🔐 Add createApiKeyAuth({ keys: [env.API_KEY] }) to your middleware stack.',
+    email: '🚀 Email binding ready. Use env.EMAIL.send() in your handler.',
+    hyperdrive: '🚀 Run: wrangler hyperdrive create <name> --connection-string "postgres://..."',
+    analytics: '🚀 Analytics Engine ready. Use env.ANALYTICS.writeDataPoint() in your handler.',
+    browser: '🚀 Browser Rendering ready. Use env.BROWSER in your handler.'
+  };
+  if (setupInstructions[feature]) {
+    results.instructions.push(setupInstructions[feature]);
+  }
+  return results;
+}
+
+/**
+ * CLI entry point for `clodo add`
+ */
+export function registerAddCommand(program) {
+  program.command('add <feature>').description('Add a Cloudflare binding or feature to your existing Worker project').option('-d, --dir <path>', 'Project directory', '.').option('--dry-run', 'Show what would change without modifying files').action(async (feature, options) => {
+    console.log(`\n🔧 Adding "${feature}" to your Worker project...\n`);
+    const results = await addFeature(feature, {
+      cwd: resolve(options.dir),
+      dryRun: options.dryRun
+    });
+    for (const instruction of results.instructions) {
+      console.log(`  ${instruction}`);
+    }
+    console.log('');
+  });
+}
+
+/**
+ * List all available features for `clodo add`
+ */
+export function listAvailableFeatures() {
+  return [{
+    name: 'ai',
+    description: 'Workers AI (text generation, embeddings, etc.)'
+  }, {
+    name: 'kv',
+    description: 'KV Namespace (key-value storage)',
+    syntax: 'kv[:binding_name]'
+  }, {
+    name: 'd1',
+    description: 'D1 Database (SQLite)',
+    syntax: 'd1[:db_name]'
+  }, {
+    name: 'r2',
+    description: 'R2 Object Storage',
+    syntax: 'r2[:bucket_name]'
+  }, {
+    name: 'vectorize',
+    description: 'Vectorize (vector database)',
+    syntax: 'vectorize[:index_name]'
+  }, {
+    name: 'queues',
+    description: 'Queues (message queue)',
+    syntax: 'queues[:queue_name]'
+  }, {
+    name: 'cron',
+    description: 'Cron Triggers (scheduled jobs)'
+  }, {
+    name: 'auth:bearer',
+    description: 'Bearer token authentication middleware'
+  }, {
+    name: 'auth:apikey',
+    description: 'API key authentication middleware'
+  }, {
+    name: 'email',
+    description: 'Email Workers (send email)'
+  }, {
+    name: 'hyperdrive',
+    description: 'Hyperdrive (Postgres connection pool)'
+  }, {
+    name: 'analytics',
+    description: 'Analytics Engine (custom metrics)'
+  }, {
+    name: 'browser',
+    description: 'Browser Rendering API'
+  }];
+}

package/dist/config/service-schema-config.js

@@ -2,8 +2,28 @@
 // Allows runtime overrides for enums and features to keep validation flexible and configurable
 
 let config = {
-  serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic'],
-  features: ['d1', 'upstash', 'kv', 'r2', 'pages', 'ws', 'durableObject', 'durableObjects', 'cron', 'metrics']
+  serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic',
+  // New real-world Cloudflare Worker patterns
+  'ai-worker', 'queue-processor', 'cron-worker', 'edge-proxy'],
+  features: [
+  // Storage & Databases
+  'd1', 'kv', 'r2',
+  // AI & ML
+  'ai', 'vectorize',
+  // Messaging & Events
+  'queues', 'cron',
+  // Compute
+  'durableObject', 'durableObjects',
+  // Communication
+  'email', 'ws',
+  // Networking
+  'hyperdrive', 'browser',
+  // Observability
+  'metrics', 'analytics',
+  // Infrastructure
+  'pages',
+  // Legacy (kept for backward compatibility)
+  'upstash']
 };
 export function getConfig() {
   return {
@@ -16,7 +36,80 @@ export function setConfig(updates = {}) {
 }
 export function resetConfig() {
   config = {
-    serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic'],
-    features: ['d1', 'upstash', 'kv', 'r2', 'pages', 'ws', 'durableObject', 'durableObjects', 'cron', 'metrics']
+    serviceTypes: ['api-service', 'data-service', 'worker', 'pages', 'gateway', 'generic', 'ai-worker', 'queue-processor', 'cron-worker', 'edge-proxy'],
+    features: ['d1', 'kv', 'r2', 'ai', 'vectorize', 'queues', 'cron', 'durableObject', 'durableObjects', 'email', 'ws', 'hyperdrive', 'browser', 'metrics', 'analytics', 'pages', 'upstash']
   };
-}
+}
+
+/**
+ * Maps feature names to their wrangler.toml binding configuration.
+ * Used by scaffold generators to produce correct wrangler.toml output.
+ */
+export const FEATURE_BINDING_MAP = {
+  ai: {
+    toml: '[ai]\nbinding = "AI"',
+    envType: 'Ai',
+    binding: 'AI'
+  },
+  vectorize: {
+    toml: '[[vectorize]]\nbinding = "VECTORIZE_INDEX"\nindex_name = "my-index"',
+    envType: 'VectorizeIndex',
+    binding: 'VECTORIZE_INDEX'
+  },
+  kv: {
+    toml: '[[kv_namespaces]]\nbinding = "KV_DATA"\nid = ""',
+    envType: 'KVNamespace',
+    binding: 'KV_DATA'
+  },
+  d1: {
+    toml: '[[d1_databases]]\nbinding = "DB"\ndatabase_name = ""\ndatabase_id = ""',
+    envType: 'D1Database',
+    binding: 'DB'
+  },
+  r2: {
+    toml: '[[r2_buckets]]\nbinding = "R2_STORAGE"\nbucket_name = ""',
+    envType: 'R2Bucket',
+    binding: 'R2_STORAGE'
+  },
+  queues: {
+    toml: '[[queues.producers]]\nbinding = "QUEUE"\nqueue = "my-queue"\n\n[[queues.consumers]]\nqueue = "my-queue"\nmax_batch_size = 10\nmax_batch_timeout = 30',
+    envType: 'Queue',
+    binding: 'QUEUE'
+  },
+  durableObject: {
+    toml: '[[durable_objects.bindings]]\nname = "MY_DURABLE_OBJECT"\nclass_name = "MyDurableObject"',
+    envType: 'DurableObjectNamespace',
+    binding: 'MY_DURABLE_OBJECT'
+  },
+  durableObjects: {
+    toml: '[[durable_objects.bindings]]\nname = "MY_DURABLE_OBJECT"\nclass_name = "MyDurableObject"',
+    envType: 'DurableObjectNamespace',
+    binding: 'MY_DURABLE_OBJECT'
+  },
+  email: {
+    toml: '[send_email]\nname = "EMAIL"\ndestination_address = ""',
+    envType: 'SendEmail',
+    binding: 'EMAIL'
+  },
+  hyperdrive: {
+    toml: '[[hyperdrive]]\nbinding = "HYPERDRIVE"\nid = ""',
+    envType: 'Hyperdrive',
+    binding: 'HYPERDRIVE'
+  },
+  browser: {
+    toml: '[browser]\nbinding = "BROWSER"',
+    envType: 'Fetcher',
+    binding: 'BROWSER'
+  },
+  analytics: {
+    toml: '[[analytics_engine_datasets]]\nbinding = "ANALYTICS"\ndataset = "my-dataset"',
+    envType: 'AnalyticsEngineDataset',
+    binding: 'ANALYTICS'
+  },
+  cron: {
+    // Cron doesn't add bindings, it adds triggers
+    toml: '[triggers]\ncrons = ["*/5 * * * *"]',
+    envType: null,
+    binding: null
+  }
+};

package/dist/index.js

@@ -15,6 +15,18 @@ export { createDomainConfigSchema, validateDomainConfig, createDefaultDomainConf
 export { initializeService } from './worker/integration.js';
 export { autoConfigureFramework } from './version/VersionDetector.js';
 
+// ─── NEW: Middleware Factories & Composition ─────────────────────────
+export { createCorsMiddleware, createErrorHandler, createRateLimitGuard, createLogger, createBearerAuth, createApiKeyAuth, composeMiddleware } from './middleware/factories.js';
+
+// ─── NEW: Environment Guard ──────────────────────────────────────────
+export { EnvironmentGuard, createEnvironmentGuard } from './validation/environmentGuard.js';
+
+// ─── NEW: RequestContext (Hono-style) ────────────────────────────────
+export { RequestContext, createRequestContext } from './routing/RequestContext.js';
+
+// ─── NEW: Feature-to-binding mapping ─────────────────────────────────
+export { FEATURE_BINDING_MAP } from './config/service-schema-config.js';
+
 // Core data and schema components
 export * from './services/GenericDataService.js';
 export * from './schema/SchemaManager.js';
@@ -62,12 +74,19 @@ export { classifyError, getRecoverySuggestions } from './lib/shared/error-handli
 export { FrameworkInfo } from './version/FrameworkInfo.js';
 export { TemplateRuntime } from './utils/TemplateRuntime.js';
 export { HealthChecker } from './monitoring/HealthChecker.js';
-export const FRAMEWORK_VERSION = '1.0.0';
+export const FRAMEWORK_VERSION = '4.4.1';
 export const FRAMEWORK_NAME = 'Clodo Framework';
 
-// Helper for framework initialization
+// ─── Compatibility Constants (for consistent wrangler.toml generation) ──
+export const RECOMMENDED_COMPATIBILITY_DATE = '2024-12-01';
+export const MINIMUM_COMPATIBILITY_DATE = '2023-06-01';
+export const RECOMMENDED_COMPATIBILITY_FLAGS = ['nodejs_compat'];
+
+// Helper for framework initialization (silent by default, verbose with DEBUG)
 export const initializeFramework = (options = {}) => {
-  console.log(`${FRAMEWORK_NAME} v${FRAMEWORK_VERSION} initialized`);
+  if (options.verbose || typeof process !== 'undefined' && process.env?.DEBUG) {
+    console.log(`${FRAMEWORK_NAME} v${FRAMEWORK_VERSION} initialized`);
+  }
   return {
     version: FRAMEWORK_VERSION,
     name: FRAMEWORK_NAME,

package/dist/middleware/Composer.js

@@ -26,7 +26,8 @@ export class MiddlewareComposer {
         // Postprocess in reverse order
         for (const m of chain.slice().reverse()) {
           if (typeof m.postprocess === 'function') {
-            const updated = await m.postprocess(response);
+            // Pass the original request as the second argument so postprocess can access per-request state
+            const updated = await m.postprocess(response, request);
             // Allow middleware to replace response
             if (updated instanceof Response) response = updated;
           }