@hasna/events 0.1.9 → 0.1.10

package/README.md

@@ -207,8 +207,11 @@ events webhooks remove ops
 Field filters can match nested `data` or `metadata` values. Plain
 `--data`/`--metadata` values are strings, which keeps ids and slugs such as
 `001` intact. Use `--data-json` or `--metadata-json` for typed JSON predicates.
-Dot paths access nested object keys; dots inside key names are not escaped yet,
-and array traversal is not special-cased. Wildcard behavior stays broad for
+Dot paths access nested object keys; dots inside key names are not escaped yet.
+When the actual event value is an array, string filters match any primitive
+array member, which is useful for tag routing such as `data.tags=auto:route`.
+Use `path!=value` or `path!=json` for negative predicates such as
+`metadata-json 'automation.no_auto!=true'`. Wildcard behavior stays broad for
 legacy source/type/subject filters. For field paths ending in `_path` or `.path`,
 `*` matches one path segment and `**` matches recursively.
 
@@ -218,12 +221,24 @@ events webhooks add loops \
   --transport command \
   --source todos \
   --type task.created \
+  --timeout-ms 15000 \
+  --retry-attempts 3 \
+  --retry-backoff-ms 500 \
   --metadata 'project_path=/home/hasna/workspace/hasna/opensource/*' \
   --metadata-json 'route_enabled=true' \
+  --metadata-json 'automation.no_auto!=true' \
+  --data 'tags=auto:route' \
   --arg events \
   --arg handle \
   --arg todos-task
 
+# Command args that begin with dashes can be passed either form:
+events webhooks add events --id json-route --transport command --arg --json
+events webhooks add events --id json-route --transport command --arg=--json
+
+# For nested CLIs, put child positional args and flags after an explicit delimiter.
+events webhooks add events --id nested-route --transport command -- handle todos-task --json
+
 events webhooks match open-source-task-route \
   --source todos \
   --type task.created \

package/dist/cli/index.js

@@ -48,14 +48,40 @@ function matchRecord(input, matcher) {
     return true;
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
-    if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected, {
-        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
-      });
-    }
-    return actual === expected;
+    return matchField(actual, expected, path);
   });
 }
+function matchField(actual, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !matchPositiveField(actual, expected.not, path);
+  }
+  return matchPositiveField(actual, expected, path);
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }
@@ -640,13 +666,12 @@ function parseFieldMatchers(values, label, typed = false) {
     return;
   const result = {};
   for (const value of values) {
-    const separator = value.indexOf("=");
-    if (separator <= 0)
-      throw new Error(`Invalid ${label} filter, expected path=value: ${value}`);
-    const path = value.slice(0, separator);
+    const parsed = parseMatcherExpression(value, label);
+    const path = parsed.path;
     if (path in result)
       throw new Error(`Duplicate ${label} filter path: ${path}`);
-    result[path] = typed ? parseTypedMatcherValue(value.slice(separator + 1), label) : value.slice(separator + 1);
+    const matcherValue = typed ? parseTypedMatcherValue(parsed.rawValue, label) : parsed.rawValue;
+    result[path] = parsed.negated ? { not: matcherValue } : matcherValue;
   }
   return result;
 }
@@ -688,6 +713,24 @@ function parseTypedMatcherValue(value, label) {
   }
   throw new Error(`${label} filter JSON values must be string, string[], number, boolean, or null`);
 }
+function parseMatcherExpression(value, label) {
+  const negativeSeparator = value.indexOf("!=");
+  if (negativeSeparator > 0) {
+    return {
+      path: value.slice(0, negativeSeparator),
+      rawValue: value.slice(negativeSeparator + 2),
+      negated: true
+    };
+  }
+  const separator = value.indexOf("=");
+  if (separator <= 0)
+    throw new Error(`Invalid ${label} filter, expected path=value or path!=value: ${value}`);
+  return {
+    path: value.slice(0, separator),
+    rawValue: value.slice(separator + 1),
+    negated: false
+  };
+}
 
 // src/cli/index.ts
 function version() {
@@ -704,12 +747,23 @@ function parseGlobalArgs(argv) {
   let dir;
   for (let index = 0;index < argv.length; index += 1) {
     const arg = argv[index];
+    if (arg === "--") {
+      rest.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!arg.startsWith("-")) {
+      rest.push(...argv.slice(index));
+      break;
+    }
     if (arg === "--json" || arg === "-j") {
       json = true;
+    } else if (arg.startsWith("--dir=")) {
+      dir = arg.slice("--dir=".length);
     } else if (arg === "--dir") {
       dir = argv[++index];
     } else {
-      rest.push(arg);
+      rest.push(...argv.slice(index));
+      break;
     }
   }
   return { json, dir, rest };
@@ -827,10 +881,10 @@ Options:
   --source <source>         Event source filter
   --subject <subject>       Event subject filter
   --severity <severity>     Event severity filter
-  --data <path=value>       Event data field filter, repeatable; string values, dot paths, * segment wildcard, ** recursive wildcard
-  --metadata <path=value>   Event metadata field filter, repeatable; string values, dot paths, * segment wildcard, ** recursive wildcard
-  --data-json <path=json>   Event data field filter with typed JSON value
-  --metadata-json <path=json> Event metadata field filter with typed JSON value
+  --data <path=value|path!=value> Event data field filter, repeatable; strings, dot paths, array-member matching, * segment wildcard, ** recursive wildcard
+  --metadata <path=value|path!=value> Event metadata field filter, repeatable; strings, dot paths, array-member matching, * segment wildcard, ** recursive wildcard
+  --data-json <path=json|path!=json> Event data field filter with typed JSON value
+  --metadata-json <path=json|path!=json> Event metadata field filter with typed JSON value
   --honor-filters           On webhooks test, skip delivery when the sample event does not match filters
   --transport <kind>        webhook or command
   --secret <secret>         Webhook signing secret
@@ -838,6 +892,41 @@ Options:
   --redact <path>           Redaction path, repeatable
   --no-deliver              Available on events emit`);
 }
+function printWebhookAddHelp(options = {}) {
+  const name = commandName(options);
+  console.log(`${name} webhooks add
+
+Usage:
+  ${name} [--dir <path>] [--json] webhooks add <url|command> [options]
+  ${name} [--dir <path>] [--json] webhooks add <command> --transport command [options] -- [command-args...]
+
+Options:
+  --id <id>                 Channel id
+  --name <name>             Display name
+  --transport <kind>        webhook or command
+  --type <pattern>          Event type filter, supports wildcards
+  --source <source>         Event source filter
+  --subject <subject>       Event subject filter
+  --severity <severity>     Event severity filter
+  --data <path=value|path!=value> Event data field filter, repeatable
+  --metadata <path=value|path!=value> Event metadata field filter, repeatable
+  --data-json <path=json|path!=json> Event data field filter with typed JSON value
+  --metadata-json <path=json|path!=json> Event metadata field filter with typed JSON value
+  --secret <secret>         Webhook signing secret
+  --header <name=value>     Webhook header, repeatable
+  --arg <arg>               Command argument, repeatable; values may begin with dashes
+  --timeout-ms <ms>         Transport timeout in milliseconds
+  --retry-attempts <n>      Maximum delivery attempts
+  --retry-backoff-ms <ms>   Initial retry backoff in milliseconds
+  --redact <path>           Redaction path, repeatable
+  --disabled                Create channel disabled
+
+Examples:
+  ${name} webhooks add https://example.com/webhooks/hasna --id ops --retry-attempts 3 --retry-backoff-ms 500
+  ${name} webhooks add bun --id command-hook --transport command --arg run --arg ./handler.ts --arg --json
+  ${name} webhooks add bun --id command-hook --transport command --arg=--json
+  ${name} webhooks add bun --id command-hook --transport command -- run ./handler.ts --json`);
+}
 function printEventsHelp(options = {}) {
   const name = commandName(options);
   console.log(`${name} events
@@ -884,6 +973,10 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
       printWebhooksHelp(options);
       return;
     }
+    if (command === "add" && (tail[0] === "--help" || tail[0] === "-h")) {
+      printWebhookAddHelp(options);
+      return;
+    }
     if (tail.includes("--help") || tail.includes("-h")) {
       printWebhooksHelp(options);
       return;
@@ -907,7 +1000,7 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
 }
 async function handleWebhooks(client, command, tail, parsed, options) {
   if (command === "add") {
-    const args = [...tail];
+    const { args, delimiterArgs } = splitDelimiter(tail);
     const transport = takeOption(args, "--transport") ?? "webhook";
     const id = takeOption(args, "--id") ?? crypto.randomUUID();
     const name = takeOption(args, "--name");
@@ -938,7 +1031,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     if (transport === "webhook") {
       channel.webhook = { url: target, secret, headers: parseHeaders(headerValues), timeoutMs };
     } else if (transport === "command") {
-      channel.command = { command: target, args: [...args.slice(1), ...commandArgs], timeoutMs };
+      channel.command = { command: target, args: [...args.slice(1), ...commandArgs, ...delimiterArgs], timeoutMs };
     } else {
       throw new Error(`Transport ${transport} is reserved for future use and cannot be added yet`);
     }
@@ -1011,6 +1104,15 @@ async function handleWebhooks(client, command, tail, parsed, options) {
   }
   throw new Error(`Unknown webhooks command: ${command ?? ""}`);
 }
+function splitDelimiter(values) {
+  const delimiterIndex = values.indexOf("--");
+  if (delimiterIndex === -1)
+    return { args: [...values], delimiterArgs: [] };
+  return {
+    args: values.slice(0, delimiterIndex),
+    delimiterArgs: values.slice(delimiterIndex + 1)
+  };
+}
 async function handleEvents(client, command, tail, parsed, options) {
   if (command === "emit") {
     const args = [...tail];

package/dist/commander.js

@@ -38,14 +38,40 @@ function matchRecord(input, matcher) {
     return true;
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
-    if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected, {
-        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
-      });
-    }
-    return actual === expected;
+    return matchField(actual, expected, path);
   });
 }
+function matchField(actual, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !matchPositiveField(actual, expected.not, path);
+  }
+  return matchPositiveField(actual, expected, path);
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }
@@ -651,13 +677,12 @@ function parseFieldMatchers(values, label, typed = false) {
     return;
   const result = {};
   for (const value of values) {
-    const separator = value.indexOf("=");
-    if (separator <= 0)
-      throw new Error(`Invalid ${label} filter, expected path=value: ${value}`);
-    const path = value.slice(0, separator);
+    const parsed = parseMatcherExpression(value, label);
+    const path = parsed.path;
     if (path in result)
       throw new Error(`Duplicate ${label} filter path: ${path}`);
-    result[path] = typed ? parseTypedMatcherValue(value.slice(separator + 1), label) : value.slice(separator + 1);
+    const matcherValue = typed ? parseTypedMatcherValue(parsed.rawValue, label) : parsed.rawValue;
+    result[path] = parsed.negated ? { not: matcherValue } : matcherValue;
   }
   return result;
 }
@@ -699,6 +724,24 @@ function parseTypedMatcherValue(value, label) {
   }
   throw new Error(`${label} filter JSON values must be string, string[], number, boolean, or null`);
 }
+function parseMatcherExpression(value, label) {
+  const negativeSeparator = value.indexOf("!=");
+  if (negativeSeparator > 0) {
+    return {
+      path: value.slice(0, negativeSeparator),
+      rawValue: value.slice(negativeSeparator + 2),
+      negated: true
+    };
+  }
+  const separator = value.indexOf("=");
+  if (separator <= 0)
+    throw new Error(`Invalid ${label} filter, expected path=value or path!=value: ${value}`);
+  return {
+    path: value.slice(0, separator),
+    rawValue: value.slice(separator + 1),
+    negated: false
+  };
+}
 
 // src/commander.ts
 function parseJsonObject(value, fallback) {
@@ -741,7 +784,7 @@ function wantsJson(actionOptions, command) {
 }
 function registerWebhookCommands(program, options) {
   const webhooks = program.command(options.webhooksCommandName ?? "webhooks").description("Manage Hasna event webhook subscriptions");
-  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--data <path=value...>", "Event data field filter; string values, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--metadata <path=value...>", "Event metadata field filter; string values, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--data-json <path=json...>", "Event data field filter with typed JSON value", collectValues, []).option("--metadata-json <path=json...>", "Event metadata field filter with typed JSON value", collectValues, []).option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
+  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--data <path=value...>", "Event data field filter; string values, path!=value negatives, array-member matching, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--metadata <path=value...>", "Event metadata field filter; string values, path!=value negatives, array-member matching, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--data-json <path=json...>", "Event data field filter with typed JSON value; path!=json negatives supported", collectValues, []).option("--metadata-json <path=json...>", "Event metadata field filter with typed JSON value; path!=json negatives supported", collectValues, []).option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
     const timestamp = new Date().toISOString();
     const channel = {
       id: actionOptions.id,

package/dist/filter-options.d.ts

@@ -1,5 +1,7 @@
-import type { EventFilter, StringMatcher } from "./types.js";
-type MatcherValue = StringMatcher | number | boolean | null;
+import type { EventFilter, FieldMatcherValue } from "./types.js";
+type MatcherValue = FieldMatcherValue | {
+    not: FieldMatcherValue;
+};
 export interface FilterOptionInput {
     source?: string;
     type?: string;

package/dist/filter.js

@@ -38,14 +38,40 @@ function matchRecord(input, matcher) {
     return true;
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
-    if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected, {
-        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
-      });
-    }
-    return actual === expected;
+    return matchField(actual, expected, path);
   });
 }
+function matchField(actual, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !matchPositiveField(actual, expected.not, path);
+  }
+  return matchPositiveField(actual, expected, path);
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }

package/dist/index.js

@@ -38,14 +38,40 @@ function matchRecord(input, matcher) {
     return true;
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
-    if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected, {
-        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
-      });
-    }
-    return actual === expected;
+    return matchField(actual, expected, path);
   });
 }
+function matchField(actual, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !matchPositiveField(actual, expected.not, path);
+  }
+  return matchPositiveField(actual, expected, path);
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }

package/dist/types.d.ts

@@ -27,13 +27,18 @@ export interface EventInput<TData extends EventData = EventData> {
     metadata?: Record<string, unknown>;
 }
 export type StringMatcher = string | string[];
+export type FieldMatcherValue = StringMatcher | number | boolean | null;
+export interface NegativeFieldMatcher {
+    not: FieldMatcherValue;
+}
+export type FieldMatcher = FieldMatcherValue | NegativeFieldMatcher;
 export interface EventFilter {
     source?: StringMatcher;
     type?: StringMatcher;
     subject?: StringMatcher;
     severity?: StringMatcher;
-    data?: Record<string, StringMatcher | number | boolean | null>;
-    metadata?: Record<string, StringMatcher | number | boolean | null>;
+    data?: Record<string, FieldMatcher>;
+    metadata?: Record<string, FieldMatcher>;
 }
 export interface RetryPolicy {
     maxAttempts?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",