@hasna/events 0.1.12 → 0.1.14

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`:
 
@@ -10,6 +10,45 @@ This package is local-first. By default it stores JSON files under `~/.hasna/eve
 
 Override the data directory with `HASNA_EVENTS_DIR`, `HASNA_EVENTS_HOME`, or the CLI `--dir` flag.
 
+## Storage Runtime Contract
+
+The default runtime is local JSON files. It does not use local SQLite, remote
+Postgres, S3, AWS infrastructure, or live cloud mutation:
+
+```ts
+import { getEventsStatus } from "@hasna/events";
+
+const status = await getEventsStatus();
+
+console.log(status.storage);
+// {
+//   mode: "local-files",
+//   localFiles: true,
+//   localSqlite: false,
+//   remote: false,
+//   postgres: false,
+//   s3: false,
+//   aws: false,
+//   idempotency: "best-effort-local",
+//   replayCursors: true
+// }
+```
+
+Cloud-backed stores should implement the same `EventsStore` interface and, for
+durable event-bus use, the optional `appendEventOnce` and `listEventsPage`
+methods. `appendEventOnce` is the storage-layer hook for atomic idempotency by
+`id` or `dedupeKey`, such as a Postgres unique constraint or equivalent
+provider guarantee. `listEventsPage` returns an opaque cursor page for bounded
+replay. The local JSON store implements these hooks for deterministic local
+tests, but its idempotency is best-effort local file behavior, not a
+cross-process database lock.
+
+Remote Postgres/S3/AWS adapters should keep credentials and infrastructure
+provisioning outside this package configuration, report their storage mode in
+`status.storage`, and avoid emitting live external deliveries during store
+tests. Creating buckets, databases, secrets, migrations, or production data
+changes is an explicit deployment/approval step, not part of this local runtime.
+
 ## Install
 
 ```bash
@@ -58,9 +97,94 @@ 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`.
 
+## Typed Event Catalog (Distribution Events)
+
+`@hasna/events/catalog` binds well-known envelope `type` strings to the
+`@hasna/contracts` schema ids their `data` payloads mirror, and provides an
+OPT-IN emit-time validator hook.
+
+Distribution event types (`DISTRIBUTION_EVENT_TYPES`):
+
+| Event type | Contracts schema (`data` mirror) |
+| --- | --- |
+| `release.published` | `hasna.release.v1` |
+| `release.rollout.started` | `hasna.rollout_record.v1` |
+| `release.rollout.completed` | `hasna.rollout_record.v1` |
+| `release.rollout.failed` | `hasna.rollout_record.v1` |
+| `app.installed` | `hasna.rollout_record.v1` |
+| `announcement.sent` | `hasna.announcement.v1` |
+| `feedback.created` | `hasna.feedback.v1` |
+| `feedback.triaged` | `hasna.feedback.v1` |
+
+```ts
+import { EventsClient, EventTypeCatalog, registerDistributionEventTypes } from "@hasna/events";
+
+const catalog = registerDistributionEventTypes(new EventTypeCatalog());
+const client = new EventsClient({ catalog, validateCatalogTypes: true });
+
+// Registered type with an invalid payload throws EventValidationError
+// BEFORE the event is stored or delivered.
+await client.emit({
+  source: "open-publish",
+  type: "release.published",
+  data: { appId: "open-todos" },
+});
+```
+
+Validation is fully backward compatible:
+
+- It is OFF by default (`validateCatalogTypes` defaults to `false`).
+- Unregistered/free-form event types ALWAYS pass, even when validation is on.
+- A per-emit `validate` option overrides the client setting in both directions.
+
+Payload types (`ReleasePublishedData`, `RolloutData`, `AppInstalledData`,
+`AnnouncementSentData`, `FeedbackCreatedData`, `FeedbackTriagedData`) are
+dependency-free structural mirrors of the contracts schemas; this package does
+not depend on `@hasna/contracts` at runtime.
+
+## 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 +193,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 +320,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 +344,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 +361,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}'
@@ -266,24 +390,32 @@ events events emit ticket.created \
 
 events events list --limit 20
 events events replay --type ticket.created
+events events replay --type ticket.created --dry-run --limit 100
+events events replay --type ticket.created --cursor "$NEXT_CURSOR" --limit 100
 events events replay --dry-run
 ```
 
+Replay cursors are opaque and tied to the same filter set (`--id`, `--source`,
+and `--type`) used to produce them. Use the `nextCursor` returned by the
+previous JSON replay response rather than constructing cursor strings in
+callers. A replay without `--limit` or `--cursor` processes all matching events;
+use those flags when callers need bounded page-by-page replay.
+
 Machine-readable status:
 
 ```bash
 events status --json
 ```
 
-The status contract reports event, channel, delivery, file, and transport counts
-only. It does not include event payloads, webhook signing secrets, command
-environment values, or channel targets.
+The status contract reports storage runtime, event, channel, delivery, file, and
+transport metadata only. It does not include event payloads, webhook signing
+secrets, command environment values, or channel targets.
 
 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/catalog.d.ts

@@ -0,0 +1,136 @@
+import type { EventData, EventEnvelope } from "./types.js";
+export interface EventValidationIssue {
+    path: string;
+    message: string;
+}
+export type EventValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: EventValidationIssue[];
+};
+export type EventDataValidator = (data: EventData, event: EventEnvelope) => EventValidationResult;
+export interface EventTypeDefinition {
+    /** Envelope `type` string this definition binds, e.g. `release.published`. */
+    type: string;
+    /** `@hasna/contracts` schema id the payload mirrors, e.g. `hasna.release.v1`. */
+    contractSchemaId?: string;
+    description?: string;
+    validate: EventDataValidator;
+}
+export declare class EventValidationError extends Error {
+    readonly eventType: string;
+    readonly issues: EventValidationIssue[];
+    constructor(eventType: string, issues: EventValidationIssue[]);
+}
+export declare class EventTypeCatalog {
+    private definitions;
+    register(definition: EventTypeDefinition): this;
+    unregister(type: string): boolean;
+    has(type: string): boolean;
+    get(type: string): EventTypeDefinition | undefined;
+    list(): EventTypeDefinition[];
+    /**
+     * Validate an event against its registered definition. Events whose type is
+     * NOT registered always pass: free-form types stay untouched.
+     */
+    validateEvent(event: EventEnvelope): EventValidationResult;
+    /** Like {@link validateEvent} but throws {@link EventValidationError}. */
+    assertEventValid(event: EventEnvelope): void;
+}
+/** Shared default catalog used by `EventsClient` when none is provided. */
+export declare const defaultEventTypeCatalog: EventTypeCatalog;
+export declare const DISTRIBUTION_EVENT_TYPES: {
+    readonly releasePublished: "release.published";
+    readonly rolloutStarted: "release.rollout.started";
+    readonly rolloutCompleted: "release.rollout.completed";
+    readonly rolloutFailed: "release.rollout.failed";
+    readonly appInstalled: "app.installed";
+    readonly announcementSent: "announcement.sent";
+    readonly feedbackCreated: "feedback.created";
+    readonly feedbackTriaged: "feedback.triaged";
+};
+export type DistributionEventType = (typeof DISTRIBUTION_EVENT_TYPES)[keyof typeof DISTRIBUTION_EVENT_TYPES];
+/** Contracts schema id each distribution event payload mirrors. */
+export declare const DISTRIBUTION_EVENT_CONTRACT_SCHEMAS: Record<DistributionEventType, string>;
+export type PublishPath = "skill" | "ci" | "backfilled";
+export type RolloutAction = "install" | "update" | "rollback" | "freeze-blocked";
+/** Payload for `release.published`; mirrors `hasna.release.v1` key fields. */
+export type ReleasePublishedData = {
+    appId: string;
+    package: string;
+    version: string;
+    gitSha?: string;
+    publishedAt?: string;
+    publishPath?: PublishPath;
+    changelogRef?: string;
+    [key: string]: unknown;
+};
+/** Payload for `release.rollout.*`; mirrors `hasna.rollout_record.v1` key fields. */
+export type RolloutData = {
+    appId: string;
+    package: string;
+    version: string;
+    machine: string;
+    action?: RolloutAction;
+    result?: string;
+    error?: string;
+    [key: string]: unknown;
+};
+/** Payload for `app.installed`; mirrors `hasna.rollout_record.v1` (action install). */
+export type AppInstalledData = {
+    appId: string;
+    package: string;
+    version: string;
+    machine: string;
+    [key: string]: unknown;
+};
+/** Payload for `announcement.sent`; mirrors `hasna.announcement.v1` key fields. */
+export type AnnouncementSentData = {
+    campaignId: string;
+    appId?: string;
+    audienceId?: string;
+    releaseId?: string;
+    channels?: string[];
+    [key: string]: unknown;
+};
+/** Payload for `feedback.created`. */
+export type FeedbackCreatedData = {
+    feedbackId: string;
+    appId?: string;
+    source?: string;
+    summary?: string;
+    severity?: string;
+    [key: string]: unknown;
+};
+/** Payload for `feedback.triaged`. */
+export type FeedbackTriagedData = {
+    feedbackId: string;
+    disposition: string;
+    appId?: string;
+    triagedBy?: string;
+    [key: string]: unknown;
+};
+export type DistributionEventDataMap = {
+    "release.published": ReleasePublishedData;
+    "release.rollout.started": RolloutData;
+    "release.rollout.completed": RolloutData;
+    "release.rollout.failed": RolloutData;
+    "app.installed": AppInstalledData;
+    "announcement.sent": AnnouncementSentData;
+    "feedback.created": FeedbackCreatedData;
+    "feedback.triaged": FeedbackTriagedData;
+};
+export declare const validateReleasePublishedData: EventDataValidator;
+export declare const validateRolloutData: EventDataValidator;
+export declare const validateAppInstalledData: EventDataValidator;
+export declare const validateAnnouncementSentData: EventDataValidator;
+export declare const validateFeedbackCreatedData: EventDataValidator;
+export declare const validateFeedbackTriagedData: EventDataValidator;
+/** Fresh definitions for every distribution event type. */
+export declare function createDistributionEventDefinitions(): EventTypeDefinition[];
+/**
+ * Register the distribution event types on a catalog (the shared default
+ * catalog when omitted). Opt-in: nothing is registered until this is called.
+ */
+export declare function registerDistributionEventTypes(catalog?: EventTypeCatalog): EventTypeCatalog;

package/dist/catalog.js

@@ -0,0 +1,191 @@
+// @bun
+// src/catalog.ts
+class EventValidationError extends Error {
+  eventType;
+  issues;
+  constructor(eventType, issues) {
+    const detail = issues.map((issue) => `${issue.path || "<root>"}: ${issue.message}`).join("; ");
+    super(`Event validation failed for type "${eventType}": ${detail}`);
+    this.name = "EventValidationError";
+    this.eventType = eventType;
+    this.issues = issues;
+  }
+}
+
+class EventTypeCatalog {
+  definitions = new Map;
+  register(definition) {
+    this.definitions.set(definition.type, definition);
+    return this;
+  }
+  unregister(type) {
+    return this.definitions.delete(type);
+  }
+  has(type) {
+    return this.definitions.has(type);
+  }
+  get(type) {
+    return this.definitions.get(type);
+  }
+  list() {
+    return [...this.definitions.values()];
+  }
+  validateEvent(event) {
+    const definition = this.definitions.get(event.type);
+    if (!definition)
+      return { ok: true };
+    return definition.validate(event.data, event);
+  }
+  assertEventValid(event) {
+    const result = this.validateEvent(event);
+    if (!result.ok) {
+      throw new EventValidationError(event.type, result.issues);
+    }
+  }
+}
+var defaultEventTypeCatalog = new EventTypeCatalog;
+var DISTRIBUTION_EVENT_TYPES = {
+  releasePublished: "release.published",
+  rolloutStarted: "release.rollout.started",
+  rolloutCompleted: "release.rollout.completed",
+  rolloutFailed: "release.rollout.failed",
+  appInstalled: "app.installed",
+  announcementSent: "announcement.sent",
+  feedbackCreated: "feedback.created",
+  feedbackTriaged: "feedback.triaged"
+};
+var DISTRIBUTION_EVENT_CONTRACT_SCHEMAS = {
+  "release.published": "hasna.release.v1",
+  "release.rollout.started": "hasna.rollout_record.v1",
+  "release.rollout.completed": "hasna.rollout_record.v1",
+  "release.rollout.failed": "hasna.rollout_record.v1",
+  "app.installed": "hasna.rollout_record.v1",
+  "announcement.sent": "hasna.announcement.v1",
+  "feedback.created": "hasna.feedback.v1",
+  "feedback.triaged": "hasna.feedback.v1"
+};
+var PUBLISH_PATHS = ["skill", "ci", "backfilled"];
+var ROLLOUT_ACTIONS = ["install", "update", "rollback", "freeze-blocked"];
+function requireString(data, key, issues) {
+  const value = data[key];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push({ path: key, message: "must be a non-empty string" });
+  }
+}
+function optionalString(data, key, issues) {
+  const value = data[key];
+  if (value !== undefined && (typeof value !== "string" || value.trim().length === 0)) {
+    issues.push({ path: key, message: "must be a non-empty string when present" });
+  }
+}
+function optionalEnum(data, key, allowed, issues) {
+  const value = data[key];
+  if (value !== undefined && (typeof value !== "string" || !allowed.includes(value))) {
+    issues.push({ path: key, message: `must be one of: ${allowed.join(", ")}` });
+  }
+}
+function optionalStringArray(data, key, issues) {
+  const value = data[key];
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+    issues.push({ path: key, message: "must be an array of non-empty strings when present" });
+  }
+}
+function toResult(issues) {
+  return issues.length === 0 ? { ok: true } : { ok: false, issues };
+}
+var validateReleasePublishedData = (data) => {
+  const issues = [];
+  requireString(data, "appId", issues);
+  requireString(data, "package", issues);
+  requireString(data, "version", issues);
+  optionalString(data, "gitSha", issues);
+  optionalString(data, "publishedAt", issues);
+  optionalEnum(data, "publishPath", PUBLISH_PATHS, issues);
+  return toResult(issues);
+};
+var validateRolloutData = (data, event) => {
+  const issues = [];
+  requireString(data, "appId", issues);
+  requireString(data, "package", issues);
+  requireString(data, "version", issues);
+  requireString(data, "machine", issues);
+  optionalEnum(data, "action", ROLLOUT_ACTIONS, issues);
+  if (event.type === "release.rollout.completed" || event.type === "release.rollout.failed") {
+    requireString(data, "result", issues);
+  }
+  return toResult(issues);
+};
+var validateAppInstalledData = (data) => {
+  const issues = [];
+  requireString(data, "appId", issues);
+  requireString(data, "package", issues);
+  requireString(data, "version", issues);
+  requireString(data, "machine", issues);
+  return toResult(issues);
+};
+var validateAnnouncementSentData = (data) => {
+  const issues = [];
+  requireString(data, "campaignId", issues);
+  optionalString(data, "appId", issues);
+  optionalString(data, "audienceId", issues);
+  optionalString(data, "releaseId", issues);
+  optionalStringArray(data, "channels", issues);
+  return toResult(issues);
+};
+var validateFeedbackCreatedData = (data) => {
+  const issues = [];
+  requireString(data, "feedbackId", issues);
+  optionalString(data, "appId", issues);
+  optionalString(data, "source", issues);
+  optionalString(data, "summary", issues);
+  return toResult(issues);
+};
+var validateFeedbackTriagedData = (data) => {
+  const issues = [];
+  requireString(data, "feedbackId", issues);
+  requireString(data, "disposition", issues);
+  optionalString(data, "appId", issues);
+  optionalString(data, "triagedBy", issues);
+  return toResult(issues);
+};
+function createDistributionEventDefinitions() {
+  const bind = (type, validate, description) => ({
+    type,
+    contractSchemaId: DISTRIBUTION_EVENT_CONTRACT_SCHEMAS[type],
+    description,
+    validate
+  });
+  return [
+    bind("release.published", validateReleasePublishedData, "A package version was published"),
+    bind("release.rollout.started", validateRolloutData, "A rollout of a release to a machine started"),
+    bind("release.rollout.completed", validateRolloutData, "A rollout of a release to a machine completed"),
+    bind("release.rollout.failed", validateRolloutData, "A rollout of a release to a machine failed"),
+    bind("app.installed", validateAppInstalledData, "An app was installed on a machine"),
+    bind("announcement.sent", validateAnnouncementSentData, "An announcement campaign was sent"),
+    bind("feedback.created", validateFeedbackCreatedData, "User or agent feedback was captured"),
+    bind("feedback.triaged", validateFeedbackTriagedData, "Captured feedback was triaged")
+  ];
+}
+function registerDistributionEventTypes(catalog = defaultEventTypeCatalog) {
+  for (const definition of createDistributionEventDefinitions()) {
+    catalog.register(definition);
+  }
+  return catalog;
+}
+export {
+  validateRolloutData,
+  validateReleasePublishedData,
+  validateFeedbackTriagedData,
+  validateFeedbackCreatedData,
+  validateAppInstalledData,
+  validateAnnouncementSentData,
+  registerDistributionEventTypes,
+  defaultEventTypeCatalog,
+  createDistributionEventDefinitions,
+  EventValidationError,
+  EventTypeCatalog,
+  DISTRIBUTION_EVENT_TYPES,
+  DISTRIBUTION_EVENT_CONTRACT_SCHEMAS
+};