@ductape/mcp 0.1.39 → 0.1.41

package/dist/index.js

@@ -249,21 +249,46 @@ CONTROLLER DECORATORS:
   @Webhook.Register(...)   — register a webhook consumer URL
   @Webhook.Consumer(...)   — mark inbound handler for forwarded webhook payloads
 
-FOR MESSAGING (events.produce / events.consume):
-
-  Access via ctx.sdk.events — no dedicated NestJS handle, the SDK instance is sufficient:
-
-  await this.ductape.sdk.events.produce({
-    product: 'my-product', env: 'prd',
-    event: 'broker-tag:topic-tag',
-    message: { ... },
-  });
-
-  await this.ductape.sdk.events.consume({
-    product: 'my-product', env: 'prd',
-    event: 'broker-tag:topic-tag',
-    callback: async (message) => { /* handle */ },
-  });
+FOR MESSAGING (events.produce / events.consume / events.dispatch):
+
+  In @ductape/nestjs, inject DuctapeContextService (not raw Ductape):
+    constructor(private readonly ductape: DuctapeContextService) {}
+
+  Produce immediately (method decorator — returns payload as message):
+    @Events.Produce({ event: 'broker-tag:topic-tag' })
+    emitOrderCreated(payload: { orderId: string }) { return payload; }
+
+  Dispatch (scheduled or immediate) — static schedule in decorator:
+    @Events.Dispatch({ broker: 'order-events', event: 'order-events:order-created', schedule: { every: 60000 } })
+    dispatchHeartbeat(payload: { message: { ping: boolean } }) { return payload; }
+
+  Dispatch with dynamic schedule — method returns { message, schedule?, retries? }:
+    @Events.Dispatch({ broker: 'statecraft-events', event: 'statecraft-events:boundary-due' })
+    scheduleBoundary(match: MatchLifecycle) {
+      return {
+        message: buildBoundaryCommand(match),
+        schedule: { start_at: match.nextBoundaryAt },
+        retries: 5,
+      };
+    }
+    // method return takes precedence over decorator schedule; use sdk.events.dispatch() directly
+    // when even the broker/event must vary at call time.
+
+  Consume (method decorator — method is called for each incoming message):
+    @Events.Consumer({ event: 'order-events:order-created' })
+    async onOrderCreated(message: { orderId: string; total: number }) {
+      await this.processOrder(message);
+      // return to ack; throw to nack
+    }
+    // DuctapeEventsConsumerService wires this up automatically at module init.
+    // No manual onModuleInit needed when using the decorator.
+
+  Low-level SDK access (for produce only — not needed for consume with the decorator):
+    await this.ductape.sdk.events.produce({
+      product: 'my-product', env: 'prd',
+      event: 'broker-tag:topic-tag',
+      message: { ... },
+    });
 
 SPECIALIZED MODULES (for injecting handles directly without @InjectContext):
 
@@ -464,18 +489,18 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.fetch    [product_tag, broker_tag]
   messageBrokers.list     [product_tag]
   messageBrokers.delete   [product_tag, broker_tag]
-  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string,
-    description?: string, sample?: object, idempotent?: boolean,
-    queueUrls?: [{ env_slug: string, url: string }]  // SQS only: per-env queue URL per topic
-  }]
-  ← OPTIONAL for most providers: creating a producer automatically creates the topic if it does not exist.
-  ← Only required explicitly for SQS (must supply queueUrls per env) or when you want to set sample/idempotent upfront.
-  ← For Pub/Sub, Kafka, RabbitMQ, Redis, NATS: skip this — let producer creation handle it.
-  ← A broker can have unlimited topics. Add one per logical event type.
-  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, description?: string,
-    sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
-  messageBrokers.topics.fetch  [product_tag, topic_tag]
-  messageBrokers.topics.list   [product_tag, broker_tag]
+  messageBrokers.topics.create  ← FORBIDDEN with publishable key. Use ductape_cli instead:
+    ductape_cli("events topics create -f topic.json")
+    topic.json: { tag, name, broker, description?, sample?, idempotent?, queueUrls?: [{ env_slug, url }] }
+  ← Always required before consuming. For SQS: must include queueUrls per env.
+  ← For Pub/Sub, Kafka, RabbitMQ, Redis, NATS: the first produce call auto-registers the topic,
+     but you should still create it explicitly so consumers can subscribe before any produce occurs.
+  messageBrokers.topics.update  ← FORBIDDEN with publishable key. Use ductape_cli:
+    ductape_cli("events topics update --tag broker:topic -f patch.json")
+  messageBrokers.topics.delete  ← FORBIDDEN with publishable key. Use ductape_cli:
+    ductape_cli("events topics delete --tag broker:topic")
+  messageBrokers.topics.fetch  [product_tag, topic_tag]   ← safe via ductape_execute
+  messageBrokers.topics.list   [product_tag, broker_tag]  ← safe via ductape_execute
   messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]
   messageBrokers.consume  [{ product, env, event: "broker_tag:topic_tag", callback: "function_ref" }]
   messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]
@@ -2422,22 +2447,34 @@ Import (register an EXISTING cloud resource):
   Producing to a topic also calls ensureTopicRegistered in the background — but DO NOT rely on
   auto-registration for consume paths. Always create topics explicitly.
 
-  ductape_execute("messageBrokers.topics.create", [product_tag, {
-    tag: "order-created",             // topic tag (just the topic part, NOT "broker:topic")
-    name: "Order Created",
-    broker: "order-events",           // broker component tag
-    description?: string,
-    sample: { orderId: "string", total: 0 },   // documents expected message shape
-    idempotent?: boolean,             // if true, Ductape deduplicates by idempotency_key
-    // AWS SQS only — must supply per-env queue URL:
-    queueUrls?: [
-      { env_slug: "snd", url: "https://sqs.us-east-1.amazonaws.com/123/queue-snd" },
-      { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123/queue-prd" }
-    ]
-  }])
+  IMPORTANT: messageBrokers.topics.create requires an access key (admin operation).
+  Use ductape_cli — NOT ductape_execute — to create topics.
 
-  List / fetch topics:
-    ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
+  Write a topic.json file, then:
+    ductape_cli("events topics create -f topic.json")
+
+  topic.json schema:
+    {
+      "tag": "order-created",           // topic tag only — NOT "broker:topic"
+      "name": "Order Created",
+      "broker": "order-events",         // broker component tag
+      "description": "...",             // optional
+      "sample": { "orderId": "string", "total": 0 },  // expected message shape
+      "idempotent": false,              // optional — deduplicates by idempotency_key when true
+      // AWS SQS only — per-env queue URL:
+      "queueUrls": [
+        { "env_slug": "snd", "url": "https://sqs.us-east-1.amazonaws.com/123/queue-snd" },
+        { "env_slug": "prd", "url": "https://sqs.us-east-1.amazonaws.com/123/queue-prd" }
+      ]
+    }
+
+  Other topic operations (all require access key via ductape_cli):
+    ductape_cli("events topics list --tag order-events")          → list topics for a broker
+    ductape_cli("events topics get --tag order-events:order-created")
+    ductape_cli("events topics update --tag order-events:order-created -f patch.json")
+    ductape_cli("events topics delete --tag order-events:order-created")
+
+  Read-only fetches (safe with publishable key via ductape_execute):
     ductape_execute("messageBrokers.fetch", [product_tag, "broker-tag"])  → includes topics[]
 
 ━━━ STEP 3: PRODUCE — WRITTEN IN APPLICATION CODE ━━━
@@ -2464,16 +2501,30 @@ Import (register an EXISTING cloud resource):
       idempotencyTtl?: 86400,             // seconds; default 86400 (24h)
     });
 
-  NESTJS — method decorator:
-    import { Messaging } from '@ductape/nestjs';
+  NESTJS — method decorators:
+    import { Events } from '@ductape/nestjs';
     @Injectable() export class OrdersService {
-      @Messaging.Produce({ event: 'order-events:order-created' })
+      // Immediate produce — method returns the message payload:
+      @Events.Produce({ event: 'order-events:order-created' })
       emitOrderCreated(payload: { orderId: string; total: number }) { return payload; }
 
-      // Scheduled dispatch — fire-and-forget with optional schedule:
-      @Messaging.Dispatch({ broker: 'order-events', event: 'order-events:order-created',
-                            schedule?: { start_at?, cron?, every?, limit?, tz? } })
-      scheduleOrderNotification(payload: Record<string, unknown>) { return payload; }
+      // Dispatch with static schedule (known at deploy time):
+      @Events.Dispatch({ broker: 'order-events', event: 'order-events:reminder-due',
+                         schedule: { every: 86400000 } })
+      scheduleReminder(payload: { message: { orderId: string } }) { return payload; }
+
+      // Dispatch with dynamic schedule (known at call time) — method returns { message, schedule?, retries? }:
+      @Events.Dispatch({ broker: 'order-events', event: 'order-events:fulfillment-due' })
+      scheduleFulfillment(order: Order) {
+        return {
+          message: { orderId: order.id, items: order.items },
+          schedule: { start_at: order.expectedAt },
+          retries: 3,
+        };
+      }
+      // Called as: await this.ordersService.scheduleFulfillment(order);
+      // When method return has a 'message' key, schedule/retries from return take precedence over decorator config.
+      // For even more control (dynamic broker/event), use sdk.events.dispatch() directly.
     }
 
   CLIENT-SIDE (browser — publishable key):
@@ -2510,11 +2561,6 @@ Import (register an EXISTING cloud resource):
 
 ━━━ STEP 4: CONSUME — WRITTEN IN APPLICATION CODE ━━━
 
-  Consumers are auto-registered by the SDK on first consume call.
-  Consumer registration options (all optional — used for tracking in Workbench):
-    consumer?: { tag?: string, name?: string, description?: string }
-  If tag is omitted, Ductape generates one: "consumer-<brokerTag>-<topicTag>".
-
   ACK BEHAVIOR (automatic):
     - Callback returns successfully → message is acknowledged (ack)
     - Callback throws → message is tracked as failed; broker nacks/retries per provider behavior
@@ -2533,34 +2579,32 @@ Import (register an EXISTING cloud resource):
     Run multiple instances of your service to scale consumption.
 
   GENERAL BACKEND (TypeScript/Node.js — not NestJS):
-    Start consuming in your module init or service startup:
     await ductape.events.consume({
       product: "my-product",
       env: "prd",
-      event: "order-events:order-created",
+      event: "order-events:order-created",   // ALWAYS "broker-tag:topic-tag"
       callback: async (message) => {
-        // All real processing logic goes here.
         // Throw to nack. Return to ack.
         await processOrder(message as { orderId: string; total: number });
       },
-      consumer?: { tag: "order-processor", name: "Order Processor" },
     });
 
-  NESTJS — use SDK in onModuleInit (no @Messaging.Consume decorator exists yet):
+  NESTJS — use @Events.Consumer decorator (preferred):
+    import { Events } from '@ductape/nestjs';
     @Injectable()
-    export class OrderConsumerService implements OnModuleInit {
-      constructor(private readonly ductape: Ductape) {}
-      async onModuleInit() {
-        await this.ductape.events.consume({
-          product: "my-product",
-          env: process.env.DUCTAPE_ENV || 'prd',
-          event: "order-events:order-created",
-          callback: async (message) => { await this.handle(message); },
-          consumer: { tag: "order-consumer", name: "Order Consumer" },
-        });
+    export class OrderConsumerService {
+      @Events.Consumer({ event: 'order-events:order-created' })
+      async onOrderCreated(message: { orderId: string; total: number }) {
+        await this.processOrder(message);
+        // return to ack; throw to nack
       }
-      private async handle(message: unknown) { /* business logic */ }
+      private async processOrder(msg: { orderId: string; total: number }) { /* ... */ }
     }
+    // DuctapeEventsConsumerService (auto-registered by DuctapeModule) wires this up at startup.
+    // No manual onModuleInit needed.
+
+    // If you need to override product/env for a specific consumer:
+    @Events.Consumer({ event: 'order-events:order-created', product: 'my-product', env: 'prd' })
 
   CLIENT-SIDE: Clients CANNOT consume. Event consumption is always server-side only.
   This is the key distinction between server topics (produce + consume) and client-observable
@@ -3519,11 +3563,11 @@ async function main() {
                 '        "product":"my-product","component":"core-db","env":"prd","resource":"Cluster0","dbName":"myapp_prd"}]\n' +
                 '  - Message broker / event broker import:\n' +
                 '    CLI accepts these aliases for the messageBrokers module: events, event, broker, brokers, message-brokers.\n' +
-                '    List existing brokers: ductape_cli("resources events list <product_tag> --json")\n' +
+                '    List existing brokers: ductape_cli("resources events list --json")\n' +
                 '    GCP Pub/Sub service identifier is "pubsub". AWS SQS is "sqs". Azure Service Bus is "servicebus".\n' +
                 '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
                 '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
-                '    After importing, create producers — topics are auto-created with the producer (except SQS, which needs explicit topics.create with queueUrls first).\n' +
+                '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
                 '  - Listing workspaces, products, secrets\n' +
                 '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
                 '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -260,21 +260,46 @@ CONTROLLER DECORATORS:
   @Webhook.Register(...)   — register a webhook consumer URL
   @Webhook.Consumer(...)   — mark inbound handler for forwarded webhook payloads
 
-FOR MESSAGING (events.produce / events.consume):
+FOR MESSAGING (events.produce / events.consume / events.dispatch):
 
-  Access via ctx.sdk.events — no dedicated NestJS handle, the SDK instance is sufficient:
+  In @ductape/nestjs, inject DuctapeContextService (not raw Ductape):
+    constructor(private readonly ductape: DuctapeContextService) {}
 
-  await this.ductape.sdk.events.produce({
-    product: 'my-product', env: 'prd',
-    event: 'broker-tag:topic-tag',
-    message: { ... },
-  });
+  Produce immediately (method decorator — returns payload as message):
+    @Events.Produce({ event: 'broker-tag:topic-tag' })
+    emitOrderCreated(payload: { orderId: string }) { return payload; }
 
-  await this.ductape.sdk.events.consume({
-    product: 'my-product', env: 'prd',
-    event: 'broker-tag:topic-tag',
-    callback: async (message) => { /* handle */ },
-  });
+  Dispatch (scheduled or immediate) — static schedule in decorator:
+    @Events.Dispatch({ broker: 'order-events', event: 'order-events:order-created', schedule: { every: 60000 } })
+    dispatchHeartbeat(payload: { message: { ping: boolean } }) { return payload; }
+
+  Dispatch with dynamic schedule — method returns { message, schedule?, retries? }:
+    @Events.Dispatch({ broker: 'statecraft-events', event: 'statecraft-events:boundary-due' })
+    scheduleBoundary(match: MatchLifecycle) {
+      return {
+        message: buildBoundaryCommand(match),
+        schedule: { start_at: match.nextBoundaryAt },
+        retries: 5,
+      };
+    }
+    // method return takes precedence over decorator schedule; use sdk.events.dispatch() directly
+    // when even the broker/event must vary at call time.
+
+  Consume (method decorator — method is called for each incoming message):
+    @Events.Consumer({ event: 'order-events:order-created' })
+    async onOrderCreated(message: { orderId: string; total: number }) {
+      await this.processOrder(message);
+      // return to ack; throw to nack
+    }
+    // DuctapeEventsConsumerService wires this up automatically at module init.
+    // No manual onModuleInit needed when using the decorator.
+
+  Low-level SDK access (for produce only — not needed for consume with the decorator):
+    await this.ductape.sdk.events.produce({
+      product: 'my-product', env: 'prd',
+      event: 'broker-tag:topic-tag',
+      message: { ... },
+    });
 
 SPECIALIZED MODULES (for injecting handles directly without @InjectContext):
 
@@ -475,18 +500,18 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.fetch    [product_tag, broker_tag]
   messageBrokers.list     [product_tag]
   messageBrokers.delete   [product_tag, broker_tag]
-  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string,
-    description?: string, sample?: object, idempotent?: boolean,
-    queueUrls?: [{ env_slug: string, url: string }]  // SQS only: per-env queue URL per topic
-  }]
-  ← OPTIONAL for most providers: creating a producer automatically creates the topic if it does not exist.
-  ← Only required explicitly for SQS (must supply queueUrls per env) or when you want to set sample/idempotent upfront.
-  ← For Pub/Sub, Kafka, RabbitMQ, Redis, NATS: skip this — let producer creation handle it.
-  ← A broker can have unlimited topics. Add one per logical event type.
-  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, description?: string,
-    sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
-  messageBrokers.topics.fetch  [product_tag, topic_tag]
-  messageBrokers.topics.list   [product_tag, broker_tag]
+  messageBrokers.topics.create  ← FORBIDDEN with publishable key. Use ductape_cli instead:
+    ductape_cli("events topics create -f topic.json")
+    topic.json: { tag, name, broker, description?, sample?, idempotent?, queueUrls?: [{ env_slug, url }] }
+  ← Always required before consuming. For SQS: must include queueUrls per env.
+  ← For Pub/Sub, Kafka, RabbitMQ, Redis, NATS: the first produce call auto-registers the topic,
+     but you should still create it explicitly so consumers can subscribe before any produce occurs.
+  messageBrokers.topics.update  ← FORBIDDEN with publishable key. Use ductape_cli:
+    ductape_cli("events topics update --tag broker:topic -f patch.json")
+  messageBrokers.topics.delete  ← FORBIDDEN with publishable key. Use ductape_cli:
+    ductape_cli("events topics delete --tag broker:topic")
+  messageBrokers.topics.fetch  [product_tag, topic_tag]   ← safe via ductape_execute
+  messageBrokers.topics.list   [product_tag, broker_tag]  ← safe via ductape_execute
   messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]
   messageBrokers.consume  [{ product, env, event: "broker_tag:topic_tag", callback: "function_ref" }]
   messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]
@@ -2495,22 +2520,34 @@ Import (register an EXISTING cloud resource):
   Producing to a topic also calls ensureTopicRegistered in the background — but DO NOT rely on
   auto-registration for consume paths. Always create topics explicitly.
 
-  ductape_execute("messageBrokers.topics.create", [product_tag, {
-    tag: "order-created",             // topic tag (just the topic part, NOT "broker:topic")
-    name: "Order Created",
-    broker: "order-events",           // broker component tag
-    description?: string,
-    sample: { orderId: "string", total: 0 },   // documents expected message shape
-    idempotent?: boolean,             // if true, Ductape deduplicates by idempotency_key
-    // AWS SQS only — must supply per-env queue URL:
-    queueUrls?: [
-      { env_slug: "snd", url: "https://sqs.us-east-1.amazonaws.com/123/queue-snd" },
-      { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123/queue-prd" }
-    ]
-  }])
+  IMPORTANT: messageBrokers.topics.create requires an access key (admin operation).
+  Use ductape_cli — NOT ductape_execute — to create topics.
 
-  List / fetch topics:
-    ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
+  Write a topic.json file, then:
+    ductape_cli("events topics create -f topic.json")
+
+  topic.json schema:
+    {
+      "tag": "order-created",           // topic tag only — NOT "broker:topic"
+      "name": "Order Created",
+      "broker": "order-events",         // broker component tag
+      "description": "...",             // optional
+      "sample": { "orderId": "string", "total": 0 },  // expected message shape
+      "idempotent": false,              // optional — deduplicates by idempotency_key when true
+      // AWS SQS only — per-env queue URL:
+      "queueUrls": [
+        { "env_slug": "snd", "url": "https://sqs.us-east-1.amazonaws.com/123/queue-snd" },
+        { "env_slug": "prd", "url": "https://sqs.us-east-1.amazonaws.com/123/queue-prd" }
+      ]
+    }
+
+  Other topic operations (all require access key via ductape_cli):
+    ductape_cli("events topics list --tag order-events")          → list topics for a broker
+    ductape_cli("events topics get --tag order-events:order-created")
+    ductape_cli("events topics update --tag order-events:order-created -f patch.json")
+    ductape_cli("events topics delete --tag order-events:order-created")
+
+  Read-only fetches (safe with publishable key via ductape_execute):
     ductape_execute("messageBrokers.fetch", [product_tag, "broker-tag"])  → includes topics[]
 
 ━━━ STEP 3: PRODUCE — WRITTEN IN APPLICATION CODE ━━━
@@ -2537,16 +2574,30 @@ Import (register an EXISTING cloud resource):
       idempotencyTtl?: 86400,             // seconds; default 86400 (24h)
     });
 
-  NESTJS — method decorator:
-    import { Messaging } from '@ductape/nestjs';
+  NESTJS — method decorators:
+    import { Events } from '@ductape/nestjs';
     @Injectable() export class OrdersService {
-      @Messaging.Produce({ event: 'order-events:order-created' })
+      // Immediate produce — method returns the message payload:
+      @Events.Produce({ event: 'order-events:order-created' })
       emitOrderCreated(payload: { orderId: string; total: number }) { return payload; }
 
-      // Scheduled dispatch — fire-and-forget with optional schedule:
-      @Messaging.Dispatch({ broker: 'order-events', event: 'order-events:order-created',
-                            schedule?: { start_at?, cron?, every?, limit?, tz? } })
-      scheduleOrderNotification(payload: Record<string, unknown>) { return payload; }
+      // Dispatch with static schedule (known at deploy time):
+      @Events.Dispatch({ broker: 'order-events', event: 'order-events:reminder-due',
+                         schedule: { every: 86400000 } })
+      scheduleReminder(payload: { message: { orderId: string } }) { return payload; }
+
+      // Dispatch with dynamic schedule (known at call time) — method returns { message, schedule?, retries? }:
+      @Events.Dispatch({ broker: 'order-events', event: 'order-events:fulfillment-due' })
+      scheduleFulfillment(order: Order) {
+        return {
+          message: { orderId: order.id, items: order.items },
+          schedule: { start_at: order.expectedAt },
+          retries: 3,
+        };
+      }
+      // Called as: await this.ordersService.scheduleFulfillment(order);
+      // When method return has a 'message' key, schedule/retries from return take precedence over decorator config.
+      // For even more control (dynamic broker/event), use sdk.events.dispatch() directly.
     }
 
   CLIENT-SIDE (browser — publishable key):
@@ -2583,11 +2634,6 @@ Import (register an EXISTING cloud resource):
 
 ━━━ STEP 4: CONSUME — WRITTEN IN APPLICATION CODE ━━━
 
-  Consumers are auto-registered by the SDK on first consume call.
-  Consumer registration options (all optional — used for tracking in Workbench):
-    consumer?: { tag?: string, name?: string, description?: string }
-  If tag is omitted, Ductape generates one: "consumer-<brokerTag>-<topicTag>".
-
   ACK BEHAVIOR (automatic):
     - Callback returns successfully → message is acknowledged (ack)
     - Callback throws → message is tracked as failed; broker nacks/retries per provider behavior
@@ -2606,34 +2652,32 @@ Import (register an EXISTING cloud resource):
     Run multiple instances of your service to scale consumption.
 
   GENERAL BACKEND (TypeScript/Node.js — not NestJS):
-    Start consuming in your module init or service startup:
     await ductape.events.consume({
       product: "my-product",
       env: "prd",
-      event: "order-events:order-created",
+      event: "order-events:order-created",   // ALWAYS "broker-tag:topic-tag"
       callback: async (message) => {
-        // All real processing logic goes here.
         // Throw to nack. Return to ack.
         await processOrder(message as { orderId: string; total: number });
       },
-      consumer?: { tag: "order-processor", name: "Order Processor" },
     });
 
-  NESTJS — use SDK in onModuleInit (no @Messaging.Consume decorator exists yet):
+  NESTJS — use @Events.Consumer decorator (preferred):
+    import { Events } from '@ductape/nestjs';
     @Injectable()
-    export class OrderConsumerService implements OnModuleInit {
-      constructor(private readonly ductape: Ductape) {}
-      async onModuleInit() {
-        await this.ductape.events.consume({
-          product: "my-product",
-          env: process.env.DUCTAPE_ENV || 'prd',
-          event: "order-events:order-created",
-          callback: async (message) => { await this.handle(message); },
-          consumer: { tag: "order-consumer", name: "Order Consumer" },
-        });
+    export class OrderConsumerService {
+      @Events.Consumer({ event: 'order-events:order-created' })
+      async onOrderCreated(message: { orderId: string; total: number }) {
+        await this.processOrder(message);
+        // return to ack; throw to nack
       }
-      private async handle(message: unknown) { /* business logic */ }
+      private async processOrder(msg: { orderId: string; total: number }) { /* ... */ }
     }
+    // DuctapeEventsConsumerService (auto-registered by DuctapeModule) wires this up at startup.
+    // No manual onModuleInit needed.
+
+    // If you need to override product/env for a specific consumer:
+    @Events.Consumer({ event: 'order-events:order-created', product: 'my-product', env: 'prd' })
 
   CLIENT-SIDE: Clients CANNOT consume. Event consumption is always server-side only.
   This is the key distinction between server topics (produce + consume) and client-observable
@@ -3655,11 +3699,11 @@ async function main() {
           '        "product":"my-product","component":"core-db","env":"prd","resource":"Cluster0","dbName":"myapp_prd"}]\n' +
           '  - Message broker / event broker import:\n' +
           '    CLI accepts these aliases for the messageBrokers module: events, event, broker, brokers, message-brokers.\n' +
-          '    List existing brokers: ductape_cli("resources events list <product_tag> --json")\n' +
+          '    List existing brokers: ductape_cli("resources events list --json")\n' +
           '    GCP Pub/Sub service identifier is "pubsub". AWS SQS is "sqs". Azure Service Bus is "servicebus".\n' +
           '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
           '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
-          '    After importing, create producers — topics are auto-created with the producer (except SQS, which needs explicit topics.create with queueUrls first).\n' +
+          '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
           '  - Listing workspaces, products, secrets\n' +
           '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
           '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +