@hasna/events 0.1.4 → 0.1.6

package/dist/cli/index.d.ts

@@ -1,2 +1,6 @@
 #!/usr/bin/env bun
-export {};
+export interface RunEventsCliOptions {
+    programName?: string;
+    source?: string;
+}
+export declare function runEventsCli(argv?: string[], options?: RunEventsCliOptions): Promise<void>;

package/dist/cli/index.js

@@ -631,29 +631,34 @@ function output(parsed, value, human) {
   }
   human();
 }
-function printHelp() {
-  console.log(`events ${version()}
+function commandName(options) {
+  return options.programName ?? "events";
+}
+function printHelp(options = {}) {
+  const name = commandName(options);
+  console.log(`${name} ${version()}
 
 Usage:
-  events [--dir <path>] [--json] webhooks add <url|command> [options]
-  events [--dir <path>] [--json] webhooks list
-  events [--dir <path>] [--json] webhooks remove <id>
-  events [--dir <path>] [--json] webhooks test <id>
-  events [--dir <path>] [--json] events emit <type> --source <source> [options]
-  events [--dir <path>] [--json] events list [--limit <n>]
-  events [--dir <path>] [--json] events replay [--id <event-id>] [--dry-run]
+  ${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] events emit <type>${options.source ? "" : " --source <source>"} [options]
+  ${name} [--dir <path>] [--json] events list [--limit <n>]
+  ${name} [--dir <path>] [--json] events replay [--id <event-id>] [--dry-run]
 
 Environment:
   HASNA_EVENTS_DIR or HASNA_EVENTS_HOME overrides the default ${getEventsDataDir()}`);
 }
-function printWebhooksHelp() {
-  console.log(`events webhooks
+function printWebhooksHelp(options = {}) {
+  const name = commandName(options);
+  console.log(`${name} webhooks
 
 Usage:
-  events [--dir <path>] [--json] webhooks add <url|command> [options]
-  events [--dir <path>] [--json] webhooks list
-  events [--dir <path>] [--json] webhooks remove <id>
-  events [--dir <path>] [--json] webhooks test <id>
+  ${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>
 
 Options:
   --id <id>                 Channel id for add
@@ -667,16 +672,17 @@ Options:
   --redact <path>           Redaction path, repeatable
   --no-deliver              Available on events emit`);
 }
-function printEventsHelp() {
-  console.log(`events events
+function printEventsHelp(options = {}) {
+  const name = commandName(options);
+  console.log(`${name} events
 
 Usage:
-  events [--dir <path>] [--json] events emit <type> --source <source> [options]
-  events [--dir <path>] [--json] events list [--limit <n>]
-  events [--dir <path>] [--json] events replay [--id <event-id>] [--dry-run]
+  ${name} [--dir <path>] [--json] events emit <type>${options.source ? "" : " --source <source>"} [options]
+  ${name} [--dir <path>] [--json] events list [--limit <n>]
+  ${name} [--dir <path>] [--json] events replay [--id <event-id>] [--dry-run]
 
 Options:
-  --source <source>         Event source
+  --source <source>         Event source${options.source ? ` (default: ${options.source})` : ""}
   --subject <subject>       Event subject
   --severity <severity>     Event severity
   --message <message>       Human-readable event message
@@ -686,11 +692,11 @@ Options:
   --no-deliver              Record without delivering webhooks
   --dry-run                 Preview replay matches without delivery`);
 }
-async function main(argv = process.argv.slice(2)) {
+async function runEventsCli(argv = process.argv.slice(2), options = {}) {
   const parsed = parseGlobalArgs(argv);
   const [group, command, ...tail] = parsed.rest;
   if (!group || group === "--help" || group === "-h") {
-    printHelp();
+    printHelp(options);
     return;
   }
   if (group === "--version" || group === "-v") {
@@ -701,23 +707,23 @@ async function main(argv = process.argv.slice(2)) {
   const client = new EventsClient({ store });
   if (group === "webhooks") {
     if (!command || command === "--help" || command === "-h") {
-      printWebhooksHelp();
+      printWebhooksHelp(options);
       return;
     }
-    await handleWebhooks(client, command, tail, parsed);
+    await handleWebhooks(client, command, tail, parsed, options);
     return;
   }
   if (group === "events") {
     if (!command || command === "--help" || command === "-h") {
-      printEventsHelp();
+      printEventsHelp(options);
       return;
     }
-    await handleEvents(client, command, tail, parsed);
+    await handleEvents(client, command, tail, parsed, options);
     return;
   }
   throw new Error(`Unknown command group: ${group}`);
 }
-async function handleWebhooks(client, command, tail, parsed) {
+async function handleWebhooks(client, command, tail, parsed, options) {
   if (command === "add") {
     const args = [...tail];
     const transport = takeOption(args, "--transport") ?? "webhook";
@@ -785,7 +791,7 @@ async function handleWebhooks(client, command, tail, parsed) {
     if (!id)
       throw new Error("webhooks test requires a channel id");
     const result = await client.testChannel(id, {
-      source: takeOption(args, "--source") ?? "hasna.events",
+      source: takeOption(args, "--source") ?? options.source ?? "hasna.events",
       type: takeOption(args, "--type") ?? "events.test",
       subject: takeOption(args, "--subject") ?? id,
       data: parseJsonOption(takeOption(args, "--data"), { test: true })
@@ -795,13 +801,13 @@ async function handleWebhooks(client, command, tail, parsed) {
   }
   throw new Error(`Unknown webhooks command: ${command ?? ""}`);
 }
-async function handleEvents(client, command, tail, parsed) {
+async function handleEvents(client, command, tail, parsed, options) {
   if (command === "emit") {
     const args = [...tail];
     const type = args.shift();
     if (!type)
       throw new Error("events emit requires an event type");
-    const source = takeOption(args, "--source");
+    const source = takeOption(args, "--source") ?? options.source;
     if (!source)
       throw new Error("events emit requires --source");
     const noDeliver = takeFlag(args, "--no-deliver");
@@ -870,13 +876,18 @@ function severityOption(value) {
     throw new Error(`Invalid severity: ${value}`);
   return value;
 }
-main().catch((error) => {
-  const parsed = parseGlobalArgs(process.argv.slice(2));
-  const message = error instanceof Error ? error.message : String(error);
-  if (parsed.json) {
-    console.log(JSON.stringify({ error: message }, null, 2));
-  } else {
-    console.error(message);
-  }
-  process.exit(1);
-});
+if (import.meta.main) {
+  runEventsCli().catch((error) => {
+    const parsed = parseGlobalArgs(process.argv.slice(2));
+    const message = error instanceof Error ? error.message : String(error);
+    if (parsed.json) {
+      console.log(JSON.stringify({ error: message }, null, 2));
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  });
+}
+export {
+  runEventsCli
+};

package/dist/commander.js

@@ -594,9 +594,15 @@ function print(value, json, text) {
   else
     console.log(text);
 }
+function hasJsonOption(options) {
+  return Boolean(options?.json || options?.opts?.().json || options?.optsWithGlobals?.().json || options?.parent?.opts?.().json || options?.parent?.optsWithGlobals?.().json);
+}
+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("--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) => {
+  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("--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,
@@ -617,11 +623,11 @@ function registerWebhookCommands(program, options) {
       throw new Error(`Transport ${actionOptions.transport} is reserved for future use and cannot be added yet`);
     }
     const saved = await createClient(options).addChannel(channel);
-    print(sanitizeChannelForOutput(saved), Boolean(actionOptions.json), `Added ${saved.transport} channel ${saved.id}`);
+    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) => {
+  webhooks.command("list").description("List configured subscriptions").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     const channels = await createClient(options).listChannels();
-    if (actionOptions.json) {
+    if (wantsJson(actionOptions, command)) {
       console.log(JSON.stringify(sanitizeChannelsForOutput(channels), null, 2));
       return;
     }
@@ -633,11 +639,11 @@ function registerWebhookCommands(program, options) {
       console.log(`${channel.id}	${channel.enabled ? "enabled" : "disabled"}	${channel.transport}	${channel.webhook?.url ?? channel.command?.command ?? channel.transport}`);
     }
   });
-  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions) => {
+  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const removed = await createClient(options).removeChannel(id);
-    print({ removed }, Boolean(actionOptions.json), removed ? `Removed ${id}` : `Channel not found: ${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("--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("-j, --json", "Print JSON output", false).action(async (id, actionOptions) => {
+  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").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("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const result = await createClient(options).testChannel(id, {
       source: options.source,
       type: actionOptions.type,
@@ -645,13 +651,13 @@ function registerWebhookCommands(program, options) {
       message: actionOptions.message,
       data: parseJsonObject(actionOptions.data, { test: true })
     });
-    print(result, Boolean(actionOptions.json), `${result.status}: ${result.channelId}`);
+    print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
   });
   return webhooks;
 }
 function registerEventCommands(program, options) {
   const events = program.command(options.eventsCommandName ?? "events").description("Emit, list, and replay Hasna events");
-  events.command("emit").description("Emit an event from this app").argument("<type>", "Event type").option("--source <source>", "Event source override").option("--subject <subject>", "Event subject").option("--severity <severity>", "Event severity", "info").option("--message <message>", "Event message").option("--dedupe-key <key>", "Dedupe key").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--no-deliver", "Record without delivering").option("--no-dedupe", "Allow duplicate id/dedupeKey events").option("-j, --json", "Print JSON output", false).action(async (type, actionOptions) => {
+  events.command("emit").description("Emit an event from this app").argument("<type>", "Event type").option("--source <source>", "Event source override").option("--subject <subject>", "Event subject").option("--severity <severity>", "Event severity", "info").option("--message <message>", "Event message").option("--dedupe-key <key>", "Dedupe key").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--no-deliver", "Record without delivering").option("--no-dedupe", "Allow duplicate id/dedupeKey events").option("-j, --json", "Print JSON output", false).action(async (type, actionOptions, command) => {
     const result = await createClient(options).emit({
       source: actionOptions.source ?? options.source,
       type,
@@ -662,9 +668,9 @@ function registerEventCommands(program, options) {
       data: parseJsonObject(actionOptions.data, {}),
       metadata: parseJsonObject(actionOptions.metadata, {})
     }, { deliver: actionOptions.deliver, dedupe: actionOptions.dedupe });
-    print(result, Boolean(actionOptions.json), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
+    print(result, wantsJson(actionOptions, command), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
   });
-  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions) => {
+  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     let rows = await createClient(options).listEvents();
     if (actionOptions.source)
       rows = rows.filter((event) => event.source === actionOptions.source);
@@ -672,7 +678,7 @@ function registerEventCommands(program, options) {
       rows = rows.filter((event) => event.type === actionOptions.type);
     if (actionOptions.limit)
       rows = rows.slice(-actionOptions.limit);
-    if (actionOptions.json) {
+    if (wantsJson(actionOptions, command)) {
       console.log(JSON.stringify(rows, null, 2));
       return;
     }
@@ -683,14 +689,14 @@ function registerEventCommands(program, options) {
     for (const event of rows)
       console.log(`${event.time}	${event.id}	${event.source}	${event.type}	${event.severity}`);
   });
-  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions) => {
+  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     const result = await createClient(options).replay({
       eventId: actionOptions.id,
       source: actionOptions.source,
       type: actionOptions.type,
       dryRun: actionOptions.dryRun
     });
-    print(result, Boolean(actionOptions.json), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
+    print(result, wantsJson(actionOptions, command), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
   });
   return events;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,10 @@
     "./commander": {
       "types": "./dist/commander.d.ts",
       "import": "./dist/commander.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
     }
   },
   "files": [