@open-rlb/nestjs-amqp 2.1.1 → 2.2.0

package/schematics/add-route/schema.ts

@@ -0,0 +1,43 @@
+/** HTTP verb for the route. Mirrors PathDefinition['method']. */
+export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/** Where the gateway reads the RPC payload from. Mirrors BrokerHttpDataSource. */
+export type RouteDataSource = 'body' | 'query' | 'params' | 'body-query' | 'query-body';
+/** rpc = wait for the reply; event = fire-and-forget (confirm only). */
+export type RouteMode = 'rpc' | 'event';
+
+export interface AddRouteOptions {
+  /** Route name (the key). Prompted when omitted. */
+  name?: string;
+  /** HTTP method. Default: GET. */
+  method?: RouteMethod;
+  /** URL path (e.g. /orders/:id). Prompted when omitted. */
+  path?: string;
+  /** Where to read the payload from. Default: query for GET, body otherwise. */
+  dataSource?: RouteDataSource;
+  /** Broker topic the request forwards to. Prompted when omitted. */
+  topic?: string;
+  /** Broker action invoked on that topic. Prompted when omitted. */
+  action?: string;
+  /** rpc (wait reply) | event (fire-and-forget). Default: rpc. */
+  mode?: RouteMode;
+  /** RPC reply timeout in ms. */
+  timeout?: number;
+  /** Auth-provider name that must verify the caller. */
+  auth?: string;
+  /** Allow anonymous callers even when `auth` is set. */
+  allowAnonymous?: boolean;
+  /** Actions the caller must hold (OR-semantics) — gated via the ACL. Requires `auth`. */
+  actions?: string | string[];
+  /** HTTP status returned on success. */
+  successStatusCode?: number;
+  /** Return the reply as a raw binary buffer. */
+  binary?: boolean;
+  /** Respond with this redirect status instead of a body. */
+  redirect?: number;
+  /** Forward the raw (unparsed) request body — needs rawBody:true at bootstrap. */
+  parseRaw?: boolean;
+  /** Update the entry when it already exists (default: leave it untouched). */
+  overwrite?: boolean;
+  /** Path to config.yaml (default: auto-detected, typically config/config.yaml). */
+  config?: string;
+}

package/schematics/add-topic/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { AddTopicOptions } from './schema';
+export declare function main(options: AddTopicOptions): Rule;

package/schematics/add-topic/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const broker_yaml_util_1 = require("../utils/broker-yaml.util");
+const schematic_prompt_util_1 = require("../utils/schematic-prompt.util");
+const yaml_config_util_1 = require("../utils/yaml-config.util");
+const MODES = ['rpc', 'handle', 'broadcast', 'event'];
+function main(options) {
+    return async (tree, context) => {
+        const flagsProvided = options.name !== undefined;
+        const prompts = (0, schematic_prompt_util_1.loadPrompts)(context, flagsProvided);
+        const name = options.name || (await (0, schematic_prompt_util_1.askText)(prompts, 'Topic name?', ''));
+        if (!name) {
+            context.logger.error('[rlb-amqp] add-topic: a name is required.');
+            return tree;
+        }
+        const mode = options.mode || (await (0, schematic_prompt_util_1.askSelect)(prompts, 'Topic mode?', MODES, 'rpc'));
+        const exchange = options.exchange || (await (0, schematic_prompt_util_1.askText)(prompts, 'Exchange?', 'rlb'));
+        const createDeps = options.createDeps ?? true;
+        const configPath = (0, yaml_config_util_1.findConfigYaml)(tree, options.config);
+        const { doc, existed } = (0, yaml_config_util_1.readConfigDoc)(tree, configPath);
+        if (!existed)
+            context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+        const consumesQueue = mode === 'rpc' || mode === 'handle';
+        let queue = options.queue;
+        if (consumesQueue && !queue) {
+            queue = await (0, schematic_prompt_util_1.askText)(prompts, `Queue for '${name}'?`, name);
+        }
+        if (createDeps && !(0, broker_yaml_util_1.exchangeExists)(doc, exchange)) {
+            const exOutcome = (0, broker_yaml_util_1.ensureExchange)(doc, { name: exchange });
+            (0, schematic_prompt_util_1.logOutcome)(context, `exchange '${exchange}'`, exOutcome);
+        }
+        const routingKey = (0, broker_yaml_util_1.routingKeyRequired)(doc, exchange) ? options.routingKey || name : options.routingKey;
+        if (createDeps && queue && !(0, broker_yaml_util_1.queueExists)(doc, queue)) {
+            const qOutcome = (0, broker_yaml_util_1.ensureQueue)(doc, {
+                name: queue,
+                exchange,
+                routingKey: (0, broker_yaml_util_1.routingKeyRequired)(doc, exchange) ? routingKey || queue : options.routingKey,
+            });
+            (0, schematic_prompt_util_1.logOutcome)(context, `queue '${queue}'`, qOutcome);
+        }
+        const hasRetry = options.retryMaxAttempts !== undefined ||
+            options.retryDelayMs !== undefined ||
+            options.retryOnExhausted !== undefined;
+        const retry = hasRetry
+            ? {
+                maxAttempts: options.retryMaxAttempts,
+                delayMs: options.retryDelayMs,
+                onExhausted: options.retryOnExhausted,
+            }
+            : undefined;
+        const outcome = (0, broker_yaml_util_1.ensureTopic)(doc, {
+            name,
+            mode,
+            queue,
+            exchange,
+            routingKey,
+            errorBehavior: options.errorBehavior,
+            retry,
+            mandatory: options.mandatory,
+            persistent: options.persistent,
+            toObservable: options.toObservable,
+        }, { overwrite: options.overwrite });
+        (0, schematic_prompt_util_1.logOutcome)(context, `topic '${name}'`, outcome);
+        (0, yaml_config_util_1.writeConfigDoc)(tree, configPath, doc);
+        return tree;
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/add-topic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-topic/index.ts"],"names":[],"mappings":"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"}

package/schematics/add-topic/index.spec.ts

@@ -0,0 +1,100 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { parseDocument } from 'yaml';
+import { main } from './index';
+import { AddTopicOptions } from './schema';
+
+/**
+ * Invoke the factory Rule directly against a Tree (NOT SchematicTestRunner — it eagerly loads `ora`,
+ * an ESM-only module jest cannot transform here). Passing `name` makes `flagsProvided` true, so no
+ * interactive prompt is attempted.
+ */
+const ctx = { logger: { info() {}, warn() {}, error() {} } } as unknown as SchematicContext;
+
+async function run(options: AddTopicOptions, tree: Tree): Promise<Tree> {
+  const rule = main(options) as Rule;
+  const result = await (rule as (t: Tree, c: SchematicContext) => Promise<Tree>)(tree, ctx);
+  return result || tree;
+}
+
+function read(tree: Tree, path = 'config/config.yaml'): string {
+  return tree.read(path)!.toString('utf-8');
+}
+function doc(tree: Tree) {
+  return parseDocument(read(tree));
+}
+function seedConfig(): Tree {
+  const tree = Tree.empty();
+  tree.create(
+    'config/config.yaml',
+    ['# my config', 'broker:', '  exchanges:', '    - name: rlb', '      type: direct', 'topics: []', ''].join('\n'),
+  );
+  return tree;
+}
+
+describe('add-topic schematic', () => {
+  it('appends a new topic, preserving comments', async () => {
+    const tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q' }, seedConfig());
+    const topics = doc(tree).getIn(['topics']) as any;
+    expect(topics.items.map((i: any) => String(i.get('name')))).toEqual(['get-user']);
+    expect(String(topics.items[0].get('mode'))).toBe('rpc');
+    expect(read(tree)).toContain('# my config');
+  });
+
+  it('is idempotent: re-adding the same topic leaves a single entry', async () => {
+    let tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q' }, seedConfig());
+    tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q' }, tree);
+    const topics = doc(tree).getIn(['topics']) as any;
+    const names = topics.items.map((i: any) => String(i.get('name')));
+    expect(names.filter((n: string) => n === 'get-user')).toHaveLength(1);
+  });
+
+  it('creates the consuming queue for rpc mode', async () => {
+    const tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q' }, seedConfig());
+    const queues = doc(tree).getIn(['broker', 'queues']) as any;
+    const queue = queues.items.find((i: any) => String(i.get('name')) === 'get-user-q');
+    expect(queue).toBeDefined();
+    expect(String(queue.get('exchange'))).toBe('rlb');
+    const topic = (doc(tree).getIn(['topics']) as any).items[0];
+    expect(String(topic.get('queue'))).toBe('get-user-q');
+  });
+
+  it('does not require a queue for broadcast mode but binds the exchange', async () => {
+    const tree = await run({ name: 'announce', mode: 'broadcast', exchange: 'events' }, seedConfig());
+    const topic = (doc(tree).getIn(['topics']) as any).items[0];
+    expect(String(topic.get('mode'))).toBe('broadcast');
+    expect(String(topic.get('exchange'))).toBe('events');
+    expect(topic.get('queue')).toBeUndefined();
+    const exchanges = doc(tree).getIn(['broker', 'exchanges']) as any;
+    expect(exchanges.items.map((i: any) => String(i.get('name')))).toContain('events');
+  });
+
+  it('builds a retry object only when a retry flag is provided', async () => {
+    const tree = await run(
+      { name: 'flaky', mode: 'handle', queue: 'flaky-q', retryMaxAttempts: 5, retryDelayMs: 1000, retryOnExhausted: 'drop' },
+      seedConfig(),
+    );
+    const topic = (doc(tree).getIn(['topics']) as any).items[0];
+    const retry = topic.get('retry') as any;
+    expect(Number(retry.get('maxAttempts'))).toBe(5);
+    expect(Number(retry.get('delayMs'))).toBe(1000);
+    expect(String(retry.get('onExhausted'))).toBe('drop');
+    expect(retry.get('deadLetter')).toBeUndefined();
+  });
+
+  it('omits retry entirely when no retry flag is given', async () => {
+    const tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q' }, seedConfig());
+    const topic = (doc(tree).getIn(['topics']) as any).items[0];
+    expect(topic.get('retry')).toBeUndefined();
+  });
+
+  it('defaults routingKey to the topic name for topic exchanges', async () => {
+    const seed = Tree.empty();
+    seed.create(
+      'config/config.yaml',
+      ['broker:', '  exchanges:', '    - name: rlb', '      type: topic', 'topics: []', ''].join('\n'),
+    );
+    const tree = await run({ name: 'get-user', mode: 'rpc', queue: 'get-user-q', exchange: 'rlb' }, seed);
+    const topic = (doc(tree).getIn(['topics']) as any).items[0];
+    expect(String(topic.get('routingKey'))).toBe('get-user');
+  });
+});

package/schematics/add-topic/index.ts

@@ -0,0 +1,104 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import {
+  ensureExchange,
+  ensureQueue,
+  ensureTopic,
+  exchangeExists,
+  queueExists,
+  RetrySpec,
+  routingKeyRequired,
+  TopicMode,
+} from '../utils/broker-yaml.util';
+import { askConfirm, askSelect, askText, loadPrompts, logOutcome } from '../utils/schematic-prompt.util';
+import { findConfigYaml, readConfigDoc, writeConfigDoc } from '../utils/yaml-config.util';
+import { AddTopicOptions } from './schema';
+
+const MODES: readonly TopicMode[] = ['rpc', 'handle', 'broadcast', 'event'];
+
+/**
+ * `add-topic <name>` — idempotent upsert of a `topics[]` entry, comment-preserving.
+ * rpc/handle modes consume a queue, so we create the queue (and its exchange) via the ensureQueue/
+ * ensureExchange DATA helpers — never sibling schematics — to avoid prompt ping-pong. Any retry* flag
+ * builds a `retry` object; the dead-letter exchange itself is owned by the enable-retry schematic, so
+ * we deliberately never emit `retry.deadLetter` here.
+ */
+export function main(options: AddTopicOptions): Rule {
+  return async (tree: Tree, context: SchematicContext) => {
+    const flagsProvided = options.name !== undefined;
+    const prompts = loadPrompts(context, flagsProvided);
+
+    const name = options.name || (await askText(prompts, 'Topic name?', ''));
+    if (!name) {
+      context.logger.error('[rlb-amqp] add-topic: a name is required.');
+      return tree;
+    }
+
+    const mode = (options.mode as TopicMode) || (await askSelect(prompts, 'Topic mode?', MODES, 'rpc'));
+    const exchange = options.exchange || (await askText(prompts, 'Exchange?', 'rlb'));
+    const createDeps = options.createDeps ?? true;
+
+    const configPath = findConfigYaml(tree, options.config);
+    const { doc, existed } = readConfigDoc(tree, configPath);
+    if (!existed) context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+
+    // rpc/handle require a consuming queue; broadcast/event route via exchange(+routingKey).
+    const consumesQueue = mode === 'rpc' || mode === 'handle';
+    let queue = options.queue;
+    if (consumesQueue && !queue) {
+      queue = await askText(prompts, `Queue for '${name}'?`, name);
+    }
+
+    // Ensure the exchange first so a created queue never dangles.
+    if (createDeps && !exchangeExists(doc, exchange)) {
+      const exOutcome = ensureExchange(doc, { name: exchange });
+      logOutcome(context, `exchange '${exchange}'`, exOutcome);
+    }
+
+    // Topic exchanges MUST carry a routingKey; default it to the topic name when unspecified.
+    const routingKey = routingKeyRequired(doc, exchange) ? options.routingKey || name : options.routingKey;
+
+    if (createDeps && queue && !queueExists(doc, queue)) {
+      const qOutcome = ensureQueue(doc, {
+        name: queue,
+        exchange,
+        // Match the topic's routingKey when the exchange is topic-typed (helper defaults to queue name otherwise).
+        routingKey: routingKeyRequired(doc, exchange) ? routingKey || queue : options.routingKey,
+      });
+      logOutcome(context, `queue '${queue}'`, qOutcome);
+    }
+
+    // Only build a retry object when the caller supplied at least one retry field.
+    const hasRetry =
+      options.retryMaxAttempts !== undefined ||
+      options.retryDelayMs !== undefined ||
+      options.retryOnExhausted !== undefined;
+    const retry: RetrySpec | undefined = hasRetry
+      ? {
+          maxAttempts: options.retryMaxAttempts,
+          delayMs: options.retryDelayMs,
+          onExhausted: options.retryOnExhausted,
+        }
+      : undefined;
+
+    const outcome = ensureTopic(
+      doc,
+      {
+        name,
+        mode,
+        queue,
+        exchange,
+        routingKey,
+        errorBehavior: options.errorBehavior,
+        retry,
+        mandatory: options.mandatory,
+        persistent: options.persistent,
+        toObservable: options.toObservable,
+      },
+      { overwrite: options.overwrite },
+    );
+    logOutcome(context, `topic '${name}'`, outcome);
+
+    writeConfigDoc(tree, configPath, doc);
+    return tree;
+  };
+}

package/schematics/add-topic/schema.d.ts

@@ -0,0 +1,18 @@
+import { TopicMode } from '../utils/broker-yaml.util';
+export interface AddTopicOptions {
+    name?: string;
+    mode?: TopicMode;
+    queue?: string;
+    exchange?: string;
+    routingKey?: string;
+    errorBehavior?: 'ack' | 'nack' | 'requeue';
+    retryMaxAttempts?: number;
+    retryDelayMs?: number;
+    retryOnExhausted?: 'dead-letter' | 'drop';
+    mandatory?: boolean;
+    persistent?: boolean;
+    toObservable?: boolean;
+    createDeps?: boolean;
+    overwrite?: boolean;
+    config?: string;
+}

package/schematics/add-topic/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/schematics/add-topic/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-topic/schema.ts"],"names":[],"mappings":""}

package/schematics/add-topic/schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "SchematicsRlbAmqpAddTopic",
+  "title": "Add a broker topic to config.yaml",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Topic name (the key).",
+      "x-prompt": "Topic name?",
+      "$default": { "$source": "argv", "index": 0 }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["rpc", "handle", "broadcast", "event"],
+      "default": "rpc",
+      "description": "Topic mode."
+    },
+    "queue": {
+      "type": "string",
+      "description": "Queue the topic consumes (required for rpc/handle)."
+    },
+    "exchange": {
+      "type": "string",
+      "default": "rlb",
+      "description": "Exchange the topic uses."
+    },
+    "routingKey": {
+      "type": "string",
+      "description": "routingKey (required — and defaulted — when the exchange is a topic)."
+    },
+    "errorBehavior": {
+      "type": "string",
+      "enum": ["ack", "nack", "requeue"],
+      "description": "errorBehavior."
+    },
+    "retryMaxAttempts": { "type": "number", "description": "retry.maxAttempts." },
+    "retryDelayMs": { "type": "number", "description": "retry.delayMs." },
+    "retryOnExhausted": {
+      "type": "string",
+      "enum": ["dead-letter", "drop"],
+      "description": "retry.onExhausted."
+    },
+    "mandatory": { "type": "boolean", "description": "options.mandatory." },
+    "persistent": { "type": "boolean", "description": "options.persistent." },
+    "toObservable": { "type": "boolean", "description": "toObservable." },
+    "createDeps": {
+      "type": "boolean",
+      "default": true,
+      "description": "Create the queue/exchange dependencies when missing."
+    },
+    "overwrite": {
+      "type": "boolean",
+      "default": false,
+      "description": "Update the entry if it already exists (default: leave it untouched)."
+    },
+    "config": {
+      "type": "string",
+      "description": "Path to config.yaml (default: auto-detected)."
+    }
+  },
+  "required": []
+}

package/schematics/add-topic/schema.ts

@@ -0,0 +1,34 @@
+import { TopicMode } from '../utils/broker-yaml.util';
+
+export interface AddTopicOptions {
+  /** Topic name (the key). Prompted when omitted. */
+  name?: string;
+  /** rpc | handle | broadcast | event. Default: rpc. */
+  mode?: TopicMode;
+  /** Queue the topic consumes (required for rpc/handle). */
+  queue?: string;
+  /** Exchange the topic uses. Default: 'rlb'. */
+  exchange?: string;
+  /** routingKey (required — and defaulted — when the exchange is a topic). */
+  routingKey?: string;
+  /** errorBehavior: ack | nack | requeue. */
+  errorBehavior?: 'ack' | 'nack' | 'requeue';
+  /** retry.maxAttempts. */
+  retryMaxAttempts?: number;
+  /** retry.delayMs. */
+  retryDelayMs?: number;
+  /** retry.onExhausted: dead-letter | drop. */
+  retryOnExhausted?: 'dead-letter' | 'drop';
+  /** options.mandatory. */
+  mandatory?: boolean;
+  /** options.persistent. */
+  persistent?: boolean;
+  /** toObservable. */
+  toObservable?: boolean;
+  /** Create the queue/exchange dependencies when missing. Default: true. */
+  createDeps?: boolean;
+  /** Update the entry when it already exists (default: leave it untouched). */
+  overwrite?: boolean;
+  /** Path to config.yaml (default: auto-detected, typically config/config.yaml). */
+  config?: string;
+}

package/schematics/add-ws-event/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { AddWsEventOptions } from './schema';
+export declare function main(options: AddWsEventOptions): Rule;

package/schematics/add-ws-event/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const schematic_prompt_util_1 = require("../utils/schematic-prompt.util");
+const yaml_config_util_1 = require("../utils/yaml-config.util");
+const TYPES = ['ws', 'http'];
+function main(options) {
+    return async (tree, context) => {
+        const flagsProvided = options.name !== undefined;
+        const prompts = (0, schematic_prompt_util_1.loadPrompts)(context, flagsProvided);
+        const name = options.name || (await (0, schematic_prompt_util_1.askText)(prompts, 'Event name?', ''));
+        if (!name) {
+            context.logger.error('[rlb-amqp] add-ws-event: a name is required.');
+            return tree;
+        }
+        const type = options.type || (await (0, schematic_prompt_util_1.askSelect)(prompts, 'Event type?', TYPES, 'ws'));
+        const configPath = (0, yaml_config_util_1.findConfigYaml)(tree, options.config);
+        const { doc, existed } = (0, yaml_config_util_1.readConfigDoc)(tree, configPath);
+        if (!existed)
+            context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+        const item = type === 'http'
+            ? {
+                name,
+                type,
+                url: options.url,
+                method: options.httpMethod,
+                timeout: options.timeout,
+            }
+            : {
+                name,
+                type,
+                exchange: options.exchange,
+                routingKey: options.routingKey,
+                auth: options.auth,
+                requireAuth: options.requireAuth,
+                actions: options.actions,
+                scopeClaim: options.scopeClaim,
+                payloadKey: options.payloadKey,
+            };
+        if (options.scopeClaim && !options.payloadKey) {
+            context.logger.warn('[rlb-amqp] add-ws-event: scopeClaim without payloadKey denies every message (per-user isolation needs both).');
+        }
+        const hasActions = options.actions !== undefined && (!Array.isArray(options.actions) || options.actions.length > 0);
+        if (hasActions && !options.auth) {
+            context.logger.warn('[rlb-amqp] add-ws-event: actions require auth.');
+        }
+        const outcome = (0, yaml_config_util_1.upsertSeqItemByKey)(doc, ['gateway', 'events'], 'name', item, { overwrite: options.overwrite });
+        (0, schematic_prompt_util_1.logOutcome)(context, `ws-event '${name}'`, outcome);
+        (0, yaml_config_util_1.writeConfigDoc)(tree, configPath, doc);
+        return tree;
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/add-ws-event/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/add-ws-event/index.ts"],"names":[],"mappings":"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"}

package/schematics/add-ws-event/index.spec.ts

@@ -0,0 +1,85 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { parseDocument } from 'yaml';
+import { main } from './index';
+import { AddWsEventOptions } from './schema';
+
+/**
+ * Schematics are tested by invoking the factory Rule directly against a Tree, NOT via
+ * SchematicTestRunner (its testing entrypoint eagerly loads `ora`, an ESM-only module jest cannot
+ * transform here). Passing `name` makes `flagsProvided` true, so no interactive prompt is attempted.
+ */
+function makeCtx(warnings: string[] = []): SchematicContext {
+  return { logger: { info() {}, warn: (m: string) => warnings.push(m), error() {} } } as unknown as SchematicContext;
+}
+
+async function run(options: AddWsEventOptions, tree: Tree, ctx = makeCtx()): Promise<Tree> {
+  const rule = main(options) as Rule;
+  const result = await (rule as (t: Tree, c: SchematicContext) => Promise<Tree>)(tree, ctx);
+  return result || tree;
+}
+
+function read(tree: Tree, path = 'config/config.yaml'): string {
+  return tree.read(path)!.toString('utf-8');
+}
+function doc(tree: Tree) {
+  return parseDocument(read(tree));
+}
+function seedConfig(): Tree {
+  const tree = Tree.empty();
+  tree.create('config/config.yaml', ['# my config', 'gateway:', '  events: []', ''].join('\n'));
+  return tree;
+}
+
+describe('add-ws-event schematic', () => {
+  it('appends a ws event with exchange/routingKey/scoping, preserving comments', async () => {
+    const tree = await run(
+      {
+        name: 'order-updates',
+        type: 'ws',
+        exchange: 'rlb',
+        routingKey: 'order.updated',
+        auth: 'keycloak',
+        scopeClaim: 'sub',
+        payloadKey: 'userId',
+      },
+      seedConfig(),
+    );
+    const events = doc(tree).getIn(['gateway', 'events']) as any;
+    expect(events.items.map((i: any) => String(i.get('name')))).toEqual(['order-updates']);
+    const ev = events.items[0];
+    expect(String(ev.get('type'))).toBe('ws');
+    expect(String(ev.get('exchange'))).toBe('rlb');
+    expect(String(ev.get('scopeClaim'))).toBe('sub');
+    expect(read(tree)).toContain('# my config');
+  });
+
+  it('maps httpMethod onto `method` for http events (no ws-only fields leak)', async () => {
+    const tree = await run(
+      { name: 'webhook', type: 'http', url: 'https://hooks/x', httpMethod: 'POST', timeout: 5000, exchange: 'ignored' },
+      seedConfig(),
+    );
+    const ev = (doc(tree).getIn(['gateway', 'events']) as any).items[0];
+    expect(String(ev.get('method'))).toBe('POST');
+    expect(String(ev.get('url'))).toBe('https://hooks/x');
+    // ws-only field must not appear on an http event.
+    expect(ev.get('exchange')).toBeUndefined();
+  });
+
+  it('warns when scopeClaim is set without payloadKey (denies every message)', async () => {
+    const warnings: string[] = [];
+    await run(
+      { name: 'leaky', type: 'ws', exchange: 'rlb', routingKey: 'x', auth: 'kc', scopeClaim: 'sub' },
+      seedConfig(),
+      makeCtx(warnings),
+    );
+    expect(warnings.some((w) => w.includes('scopeClaim without payloadKey'))).toBe(true);
+  });
+
+  it('is idempotent and creates config.yaml when missing', async () => {
+    let tree = await run({ name: 'e1', type: 'ws', exchange: 'rlb', routingKey: 'k' }, Tree.empty());
+    expect(tree.exists('config/config.yaml')).toBe(true);
+    tree = await run({ name: 'e1', type: 'ws', exchange: 'rlb', routingKey: 'k' }, tree);
+    const names = (doc(tree).getIn(['gateway', 'events']) as any).items.map((i: any) => String(i.get('name')));
+    expect(names.filter((n: string) => n === 'e1')).toHaveLength(1);
+  });
+});