@ductape/mcp 0.1.40 → 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):
 
@@ -2476,16 +2501,30 @@ Import (register an EXISTING cloud resource):
       idempotencyTtl?: 86400,             // seconds; default 86400 (24h)
     });
 
-  NESTJS — method decorator:
+  NESTJS — method decorators:
     import { Events } from '@ductape/nestjs';
     @Injectable() export class OrdersService {
+      // 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:
-      @Events.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):
@@ -2522,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
@@ -2545,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 @Events.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
@@ -3531,7 +3563,7 @@ 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' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.40",
+  "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):
 
@@ -2549,16 +2574,30 @@ Import (register an EXISTING cloud resource):
       idempotencyTtl?: 86400,             // seconds; default 86400 (24h)
     });
 
-  NESTJS — method decorator:
+  NESTJS — method decorators:
     import { Events } from '@ductape/nestjs';
     @Injectable() export class OrdersService {
+      // 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:
-      @Events.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):
@@ -2595,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
@@ -2618,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 @Events.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
@@ -3667,7 +3699,7 @@ 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' +