@hasna/events 0.1.12 → 0.1.13

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/events
 
-Shared event envelopes, subscription config, webhook delivery, and command transports for Hasna open-source apps.
+Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps.
 
 This package is local-first. By default it stores JSON files under `~/.hasna/events`:
 
@@ -58,9 +58,49 @@ Envelope fields are:
 
 `source` should be the emitting app or bounded context. `type` should use dot notation such as `ticket.created`, `repo.synced`, or `check.failed`.
 
+## OpenAutomations Trigger Ingress
+
+`@hasna/events` is trigger ingress for OpenAutomations. It records and delivers
+event envelopes, but it does not own durable automation runs, action queues,
+approvals, DLQ state, or replay decisions. `@hasna/automations` consumes the
+same envelope shape and materializes matching events into durable automation
+runs.
+
+For automation-triggered events:
+
+- set `source` to the emitting app or bounded context
+- set `type` with dot notation, such as `ticket.created`
+- set `subject` when the event describes one stable domain object
+- set `dedupeKey` when the producer has a stable business identity
+- keep `id` stable for the specific emitted envelope
+- put only serializable trigger data in `data`
+- keep secrets out of `data` and `metadata`; pass secret references instead
+
+OpenAutomations derives idempotency from `dedupeKey` first and falls back to
+`id` when no dedupe key is present. Replaying events through `events events
+replay` re-delivers envelopes; OpenAutomations is still responsible for deciding
+whether that delivery creates a new run, returns the existing idempotent run, or
+creates an explicit replay request.
+
+## OpenLoops Task Notifications
+
+`@hasna/events` is also notification ingress for OpenLoops task-created routes.
+It delivers `todos` envelopes to configured channels, but it does not import
+OpenLoops, create workflow invocations, own admission queue state, run agents,
+or decide worker retry/backpressure policy. OpenLoops is the consumer that
+handles an envelope, dedupes/upserts a work item, admits it when capacity is
+available, and records workflow run manifests under `.hasna/loops/runs`.
+
+Replay remains delivery-only. Replaying a `todos.task.created` or
+`task.created` envelope sends the event to matching channels again; OpenLoops
+decides whether that replay is ignored as an already-admitted task, resumes
+existing work, or creates an explicit replay work item.
+
 ## Channels And Filters
 
-Channels are reusable subscriptions. They can be enabled or disabled, filtered by source/type/subject/severity, and configured with transport-specific settings.
+Channels are reusable notification routes. They can be enabled or disabled,
+filtered by source/type/subject/severity, and configured with
+transport-specific settings.
 
 ```ts
 await events.addChannel({
@@ -69,7 +109,7 @@ await events.addChannel({
   transport: "webhook",
   filters: [{ type: "ticket.*", severity: ["warning", "error", "critical"] }],
   webhook: {
-    url: "https://example.com/webhooks/hasna",
+    url: "https://example.com/channels/hasna",
     secret: process.env.HASNA_WEBHOOK_SECRET,
   },
   retry: {
@@ -196,16 +236,16 @@ const events = new EventsClient({
 The package exposes `events` and `hasna-events`.
 
 ```bash
-events webhooks add https://example.com/webhooks/hasna \
+events channels add https://example.com/channels/hasna \
   --id ops \
   --type "ticket.*" \
   --secret "$HASNA_WEBHOOK_SECRET" \
   --retry-attempts 3 \
   --retry-backoff-ms 500
 
-events webhooks list
-events webhooks test ops
-events webhooks remove ops
+events channels list
+events channels test ops
+events channels remove ops
 ```
 
 Field filters can match nested `data` or `metadata` values. Plain
@@ -220,7 +260,7 @@ legacy source/type/subject filters. For field paths ending in `_path` or `.path`
 `*` matches one path segment and `**` matches recursively.
 
 ```bash
-events webhooks add loops \
+events channels add loops \
   --id open-source-task-route \
   --transport command \
   --source todos \
@@ -237,18 +277,18 @@ events webhooks add loops \
   --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
+events channels add events --id json-route --transport command --arg --json
+events channels 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 channels add events --id nested-route --transport command -- handle todos-task --json
 
-events webhooks match open-source-task-route \
+events channels match open-source-task-route \
   --source todos \
   --type task.created \
   --metadata '{"project_path":"/home/hasna/workspace/hasna/opensource/open-events","route_enabled":true}'
 
-events webhooks test open-source-task-route --honor-filters \
+events channels test open-source-task-route --honor-filters \
   --source todos \
   --type task.created \
   --metadata '{"project_path":"/tmp/outside","route_enabled":true}'
@@ -283,7 +323,7 @@ Use `--json` for script-friendly output and `--dir <path>` for isolated data.
 
 ## App Integration Pattern
 
-Apps should keep event emission near durable state changes and avoid hardcoding app-specific webhooks. The common pattern is:
+Apps should keep event emission near durable state changes and avoid hardcoding app-specific channels. The common pattern is:
 
 ```ts
 import { EventsClient } from "@hasna/events";

package/dist/cli/index.js

@@ -862,12 +862,12 @@ function printHelp(options = {}) {
   console.log(`${name} ${version()}
 
 Usage:
-  ${name} [--dir <path>] [--json] webhooks add <url|command> [options]
-  ${name} [--dir <path>] [--json] webhooks list
-  ${name} [--dir <path>] [--json] webhooks remove <id>
-  ${name} [--dir <path>] [--json] webhooks test <id>
-  ${name} [--dir <path>] [--json] webhooks match <id>
-  ${name} [--dir <path>] [--json] webhooks status
+  ${name} [--dir <path>] [--json] channels add <url|command> [options]
+  ${name} [--dir <path>] [--json] channels list
+  ${name} [--dir <path>] [--json] channels remove <id>
+  ${name} [--dir <path>] [--json] channels test <id>
+  ${name} [--dir <path>] [--json] channels match <id>
+  ${name} [--dir <path>] [--json] channels status
   ${name} [--dir <path>] [--json] status
   ${name} [--dir <path>] [--json] events emit <type>${options.source ? "" : " --source <source>"} [options]
   ${name} [--dir <path>] [--json] events list [--limit <n>]
@@ -876,17 +876,17 @@ Usage:
 Environment:
   HASNA_EVENTS_DIR or HASNA_EVENTS_HOME overrides the default ${getEventsDataDir()}`);
 }
-function printWebhooksHelp(options = {}) {
+function printChannelsHelp(options = {}) {
   const name = commandName(options);
-  console.log(`${name} webhooks
+  console.log(`${name} channels
 
 Usage:
-  ${name} [--dir <path>] [--json] webhooks add <url|command> [options]
-  ${name} [--dir <path>] [--json] webhooks list
-  ${name} [--dir <path>] [--json] webhooks remove <id>
-  ${name} [--dir <path>] [--json] webhooks test <id>
-  ${name} [--dir <path>] [--json] webhooks match <id>
-  ${name} [--dir <path>] [--json] webhooks status
+  ${name} [--dir <path>] [--json] channels add <url|command> [options]
+  ${name} [--dir <path>] [--json] channels list
+  ${name} [--dir <path>] [--json] channels remove <id>
+  ${name} [--dir <path>] [--json] channels test <id>
+  ${name} [--dir <path>] [--json] channels match <id>
+  ${name} [--dir <path>] [--json] channels status
 
 Options:
   --id <id>                 Channel id for add
@@ -898,20 +898,20 @@ Options:
   --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
+  --honor-filters           On channels test, skip delivery when the sample event does not match filters
   --transport <kind>        webhook or command
   --secret <secret>         Webhook signing secret
   --header <name=value>     Webhook header, repeatable
   --redact <path>           Redaction path, repeatable
   --no-deliver              Available on events emit`);
 }
-function printWebhookAddHelp(options = {}) {
+function printChannelAddHelp(options = {}) {
   const name = commandName(options);
-  console.log(`${name} webhooks add
+  console.log(`${name} channels add
 
 Usage:
-  ${name} [--dir <path>] [--json] webhooks add <url|command> [options]
-  ${name} [--dir <path>] [--json] webhooks add <command> --transport command [options] -- [command-args...]
+  ${name} [--dir <path>] [--json] channels add <url|command> [options]
+  ${name} [--dir <path>] [--json] channels add <command> --transport command [options] -- [command-args...]
 
 Options:
   --id <id>                 Channel id
@@ -935,10 +935,10 @@ Options:
   --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`);
+  ${name} channels add https://example.com/channels/hasna --id ops --retry-attempts 3 --retry-backoff-ms 500
+  ${name} channels add bun --id command-hook --transport command --arg run --arg ./handler.ts --arg --json
+  ${name} channels add bun --id command-hook --transport command --arg=--json
+  ${name} channels add bun --id command-hook --transport command -- run ./handler.ts --json`);
 }
 function printEventsHelp(options = {}) {
   const name = commandName(options);
@@ -957,7 +957,7 @@ Options:
   --dedupe-key <key>        Deduplicate repeated events
   --data <json>             JSON object payload
   --metadata <json>         JSON object metadata
-  --no-deliver              Record without delivering webhooks
+  --no-deliver              Record without delivering channels
   --dry-run                 Preview replay matches without delivery`);
 }
 async function runEventsCli(argv = process.argv.slice(2), options = {}) {
@@ -981,20 +981,20 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
   }
   const store = new JsonEventsStore(parsed.dir);
   const client = new EventsClient({ store });
-  if (group === "webhooks") {
+  if (group === "channels") {
     if (!command || command === "--help" || command === "-h") {
-      printWebhooksHelp(options);
+      printChannelsHelp(options);
       return;
     }
     if (command === "add" && (tail[0] === "--help" || tail[0] === "-h")) {
-      printWebhookAddHelp(options);
+      printChannelAddHelp(options);
       return;
     }
     if (tail.includes("--help") || tail.includes("-h")) {
-      printWebhooksHelp(options);
+      printChannelsHelp(options);
       return;
     }
-    await handleWebhooks(client, command, tail, parsed, options);
+    await handleChannels(client, command, tail, parsed, options);
     return;
   }
   if (group === "events") {
@@ -1011,7 +1011,7 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
   }
   throw new Error(`Unknown command group: ${group}`);
 }
-async function handleWebhooks(client, command, tail, parsed, options) {
+async function handleChannels(client, command, tail, parsed, options) {
   if (command === "add") {
     const { args, delimiterArgs } = splitDelimiter(tail);
     const transport = takeOption(args, "--transport") ?? "webhook";
@@ -1028,7 +1028,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     const filters = parseFilter(args);
     const target = args[0];
     if (!target)
-      throw new Error("webhooks add requires a URL or command target");
+      throw new Error("channels add requires a URL or command target");
     const now2 = new Date().toISOString();
     const channel = {
       id,
@@ -1077,7 +1077,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
   if (command === "remove") {
     const id = tail[0];
     if (!id)
-      throw new Error("webhooks remove requires a channel id");
+      throw new Error("channels remove requires a channel id");
     const removed = await client.removeChannel(id);
     output(parsed, { removed }, () => console.log(removed ? `Removed ${id}` : `Channel not found: ${id}`));
     return;
@@ -1086,7 +1086,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     const args = [...tail];
     const id = args.shift();
     if (!id)
-      throw new Error("webhooks test requires a channel id");
+      throw new Error("channels test requires a channel id");
     const honorFilters = takeFlag(args, "--honor-filters");
     const result = await client.testChannel(id, {
       source: takeOption(args, "--source") ?? options.source ?? "hasna.events",
@@ -1103,7 +1103,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     const args = [...tail];
     const id = args.shift();
     if (!id)
-      throw new Error("webhooks match requires a channel id");
+      throw new Error("channels match requires a channel id");
     const result = await client.matchChannel(id, {
       source: takeOption(args, "--source") ?? options.source ?? "hasna.events",
       type: takeOption(args, "--type") ?? "events.test",
@@ -1115,7 +1115,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     output(parsed, result, () => console.log(`${result.matched ? "matched" : "skipped"}: ${result.channelId}`));
     return;
   }
-  throw new Error(`Unknown webhooks command: ${command ?? ""}`);
+  throw new Error(`Unknown channels command: ${command ?? ""}`);
 }
 function splitDelimiter(values) {
   const delimiterIndex = values.indexOf("--");

package/dist/commander.d.ts

@@ -5,10 +5,10 @@ export interface RegisterEventsCommandsOptions {
     source: string;
     dataDir?: string;
     createClient?: () => EventsClient;
-    webhooksCommandName?: string;
+    channelsCommandName?: string;
     eventsCommandName?: string;
 }
-export declare function registerWebhookCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): CommanderCommandLike;
+export declare function registerChannelCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): CommanderCommandLike;
 export declare function registerEventCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): CommanderCommandLike;
 export declare function registerEventsCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): void;
 export {};

package/dist/commander.js

@@ -795,9 +795,9 @@ function hasJsonOption(options) {
 function wantsJson(actionOptions, command) {
   return hasJsonOption(actionOptions) || hasJsonOption(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, 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) => {
+function registerChannelCommands(program, options) {
+  const channels = program.command(options.channelsCommandName ?? "channels").description("Manage Hasna event channels");
+  channels.command("add").description("Add or replace a channel").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "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,
@@ -820,29 +820,29 @@ function registerWebhookCommands(program, options) {
     const saved = await createClient(options).addChannel(channel);
     print(sanitizeChannelForOutput(saved), wantsJson(actionOptions, command), `Added ${saved.transport} channel ${saved.id}`);
   });
-  webhooks.command("list").description("List configured subscriptions").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
-    const channels = await createClient(options).listChannels();
+  channels.command("list").description("List configured channels").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+    const channels2 = await createClient(options).listChannels();
     if (wantsJson(actionOptions, command)) {
-      console.log(JSON.stringify(sanitizeChannelsForOutput(channels), null, 2));
+      console.log(JSON.stringify(sanitizeChannelsForOutput(channels2), null, 2));
       return;
     }
-    if (!channels.length) {
+    if (!channels2.length) {
       console.log("No channels configured.");
       return;
     }
-    for (const channel of channels) {
+    for (const channel of channels2) {
       console.log(`${channel.id}	${channel.enabled ? "enabled" : "disabled"}	${channel.transport}	${channel.webhook?.url ?? channel.command?.command ?? channel.transport}`);
     }
   });
-  webhooks.command("status").description("Show events webhook storage status").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  channels.command("status").description("Show events channel storage status").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     const status = await getEventsStatus(options.dataDir);
     print(status, wantsJson(actionOptions, command), `events dataDir: ${status.dataDir}`);
   });
-  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  channels.command("remove").description("Remove a channel").argument("<id>", "Channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const removed = await createClient(options).removeChannel(id);
     print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
-  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  channels.command("test").description("Send a test event to one channel").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const result = await createClient(options).testChannel(id, {
       source: actionOptions.source ?? options.source,
       type: actionOptions.type,
@@ -853,7 +853,7 @@ function registerWebhookCommands(program, options) {
     }, { honorFilters: actionOptions.honorFilters });
     print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
   });
-  webhooks.command("match").description("Check whether a sample event matches one subscription without delivering").argument("<id>", "Subscription/channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  channels.command("match").description("Check whether a sample event matches one channel without delivering").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const result = await createClient(options).matchChannel(id, {
       source: actionOptions.source ?? options.source,
       type: actionOptions.type,
@@ -864,7 +864,7 @@ function registerWebhookCommands(program, options) {
     });
     print(result, wantsJson(actionOptions, command), `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
   });
-  return webhooks;
+  return channels;
 }
 function registerEventCommands(program, options) {
   const events = program.command(options.eventsCommandName ?? "events").description("Emit, list, and replay Hasna events");
@@ -912,7 +912,7 @@ function registerEventCommands(program, options) {
   return events;
 }
 function registerEventsCommands(program, options) {
-  registerWebhookCommands(program, options);
+  registerChannelCommands(program, options);
   registerEventCommands(program, options);
 }
 function parseNumber(value) {
@@ -926,7 +926,7 @@ function collectValues(value, previous) {
   return previous;
 }
 export {
-  registerWebhookCommands,
   registerEventsCommands,
-  registerEventCommands
+  registerEventCommands,
+  registerChannelCommands
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.12",
-  "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
+  "version": "0.1.13",
+  "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +52,7 @@
   },
   "keywords": [
     "events",
-    "webhooks",
+    "channels",
     "cli",
     "typescript",
     "bun",