@hasna/events 0.1.14 → 0.1.16

package/dist/storage.js

@@ -304,17 +304,17 @@ function statusFile(dataDir, fileName, records) {
   return { path, exists: existsSync(path), records };
 }
 export {
-  normalizeEventPageLimit,
-  localJsonRuntime,
-  getEventsStatus,
-  getEventsDataDir,
-  getActiveEventsDirEnv,
-  encodeLocalJsonEventCursor,
-  decodeLocalJsonEventCursor,
-  MAX_EVENT_PAGE_LIMIT,
-  LOCAL_JSON_EVENT_CURSOR_PREFIX,
-  JsonEventsStore,
-  HASNA_EVENTS_HOME_ENV,
+  DEFAULT_EVENT_PAGE_LIMIT,
   HASNA_EVENTS_DIR_ENV,
-  DEFAULT_EVENT_PAGE_LIMIT
+  HASNA_EVENTS_HOME_ENV,
+  JsonEventsStore,
+  LOCAL_JSON_EVENT_CURSOR_PREFIX,
+  MAX_EVENT_PAGE_LIMIT,
+  decodeLocalJsonEventCursor,
+  encodeLocalJsonEventCursor,
+  getActiveEventsDirEnv,
+  getEventsDataDir,
+  getEventsStatus,
+  localJsonRuntime,
+  normalizeEventPageLimit
 };

package/dist/transports.js

@@ -42,21 +42,27 @@ function now() {
 function truncate(value, max = 4096) {
   return value.length > max ? `${value.slice(0, max)}...` : value;
 }
-function buildWebhookRequest(event, channel) {
+function buildWebhookRequest(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
+  for (const name of Object.keys(channel.webhook.headers ?? {})) {
+    if (/^x-hasna-/i.test(name)) {
+      throw new Error(`Webhook header ${name} is reserved for signed delivery metadata`);
+    }
+  }
   const body = JSON.stringify(event);
-  const timestamp = event.time;
+  const timestamp = options.timestamp ?? new Date().toISOString();
   const headers = {
     "Content-Type": "application/json",
     "User-Agent": "@hasna/events",
     "X-Hasna-Event-Id": event.id,
     "X-Hasna-Event-Type": event.type,
-    "X-Hasna-Timestamp": timestamp,
-    ...channel.webhook.headers
+    ...channel.webhook.headers,
+    "X-Hasna-Timestamp": timestamp
   };
-  if (channel.webhook.secret) {
-    headers["X-Hasna-Signature"] = signPayload(channel.webhook.secret, timestamp, body);
+  const secret = options.secret ?? channel.webhook.secret;
+  if (secret) {
+    headers["X-Hasna-Signature"] = signPayload(secret, timestamp, body);
   }
   return { body, headers };
 }
@@ -64,7 +70,21 @@ async function dispatchWebhook(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
   const startedAt = now();
-  const { body, headers } = buildWebhookRequest(event, channel);
+  let secret = channel.webhook.secret;
+  if (channel.webhook.secretRef) {
+    if (!options.secretResolver) {
+      return failedAttempt(startedAt, "Webhook secret reference has no runtime resolver");
+    }
+    try {
+      secret = await options.secretResolver(channel.webhook.secretRef);
+    } catch {
+      return failedAttempt(startedAt, "Webhook secret reference could not be resolved");
+    }
+    if (!secret)
+      return failedAttempt(startedAt, "Webhook secret reference could not be resolved");
+  }
+  const timestamp = (options.now?.() ?? new Date).toISOString();
+  const { body, headers } = buildWebhookRequest(event, channel, { secret, timestamp });
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), channel.webhook.timeoutMs ?? 15000);
   try {
@@ -96,6 +116,15 @@ async function dispatchWebhook(event, channel, options = {}) {
     clearTimeout(timeout);
   }
 }
+function failedAttempt(startedAt, error) {
+  return {
+    attempt: 1,
+    status: "failed",
+    startedAt,
+    completedAt: now(),
+    error
+  };
+}
 async function dispatchCommand(event, channel) {
   if (!channel.command)
     throw new Error(`Channel ${channel.id} has no command config`);
@@ -185,9 +214,9 @@ function createDeliveryResult(event, channel, attempts) {
   };
 }
 export {
-  dispatchWebhook,
-  dispatchCommand,
-  dispatchChannel,
+  buildWebhookRequest,
   createDeliveryResult,
-  buildWebhookRequest
+  dispatchChannel,
+  dispatchCommand,
+  dispatchWebhook
 };

package/fixtures/hasna.app_event.v1.json

@@ -0,0 +1,108 @@
+{
+  "event_id": "evt_fixture_todo_completed_01",
+  "event_type": "todos.task.completed",
+  "schema_version": "hasna.app_event.v1",
+  "source": {
+    "app": "todos",
+    "version": "0.0.0-fixture",
+    "machine": "fixture.local"
+  },
+  "occurred_at": "2026-07-29T12:00:00.000Z",
+  "severity": "notice",
+  "idempotency": {
+    "dedupe_key": "fixture:interop-project:todo-42:completed:v1",
+    "replay_safe": true
+  },
+  "correlation": {
+    "correlation_id": "corr_fixture_interop_project_01",
+    "causation_id": "evt_fixture_todo_created_01"
+  },
+  "subject": {
+    "kind": "task",
+    "id": "todo_fixture_42",
+    "uri": "hasna://todos/tasks/todo_fixture_42"
+  },
+  "actor": {
+    "kind": "service",
+    "id": "todos",
+    "name": "Todos fixture producer"
+  },
+  "project_mappings": {
+    "canonical_id": "project_fixture_interop",
+    "slug": "interop-fixture",
+    "repository": "https://example.invalid/hasna/interop-fixture",
+    "workspace": "workspace_fixture_interop",
+    "external_ids": {
+      "todos": "project_fixture_interop",
+      "conversations": "conversation_fixture_17",
+      "mementos": "memento_fixture_09",
+      "projects": "project_fixture_interop",
+      "codewith": "mailbox_fixture_interop"
+    }
+  },
+  "summary": "Interop fixture task completed successfully.",
+  "data": {
+    "task_status": "completed",
+    "task_title": "Verify app-event interoperability",
+    "conversation_id": "conversation_fixture_17",
+    "memento_id": "memento_fixture_09",
+    "mailbox_topic": "project.activity",
+    "render_hint": {
+      "component": "StatusBadge",
+      "tone": "success"
+    }
+  },
+  "resource_refs": [
+    {
+      "kind": "task",
+      "id": "todo_fixture_42",
+      "uri": "hasna://todos/tasks/todo_fixture_42",
+      "source_package": "@hasna/todos",
+      "external_id": "todo_fixture_42"
+    },
+    {
+      "kind": "conversation",
+      "id": "conversation_fixture_17",
+      "uri": "hasna://conversations/conversation_fixture_17"
+    },
+    {
+      "kind": "memento",
+      "id": "memento_fixture_09",
+      "uri": "hasna://mementos/memento_fixture_09"
+    },
+    {
+      "kind": "render",
+      "id": "project_fixture_interop_status",
+      "uri": "hasna://projects/project_fixture_interop/render/status"
+    }
+  ],
+  "evidence_refs": [
+    {
+      "kind": "test_result",
+      "id": "evidence_fixture_interop_01",
+      "uri": "artifact://interop-fixture/test-report.json",
+      "redaction": "none"
+    }
+  ],
+  "sensitivity": {
+    "classification": "internal",
+    "contains_personal_data": false
+  },
+  "redaction": {
+    "state": "none",
+    "fields": [],
+    "safe_for_logs": true
+  },
+  "delivery": {
+    "intent": "notification",
+    "mode": "at_least_once",
+    "targets": [
+      "todos",
+      "conversations",
+      "mementos",
+      "projects-json-render",
+      "codewith-mailbox"
+    ],
+    "agent_conversation_injection": false
+  }
+}

package/hasna.contract.json

@@ -0,0 +1,70 @@
+{
+  "schema": "hasna.service_contract.v1",
+  "name": "events",
+  "class": "library",
+  "contractVersion": "v1",
+  "kitVersion": "0.8.5",
+  "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps. Library class: SDK exports are the primary surface and the local `events` CLI is the operator seam. The default compatibility store remains user-owned JSON; opt-in durable delivery uses a Node-safe filesystem spool plus a Bun SQLite outbox under the same caller-selected data directory. The package provisions no remote infrastructure.",
+  "bins": [
+    "events"
+  ],
+  "hosting": [
+    "user-hosted"
+  ],
+  "serviceSurfaces": [
+    {
+      "name": "package-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "."
+    },
+    {
+      "name": "durable-spool-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable-spool"
+    },
+    {
+      "name": "durable-delivery-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable"
+    },
+    {
+      "name": "durable-worker-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable-worker"
+    },
+    {
+      "name": "events-cli",
+      "kind": "cli",
+      "status": "supported",
+      "bin": "events",
+      "authMode": "local-only"
+    }
+  ],
+  "metadata": {
+    "release": {
+      "artifactScan": {
+        "script": "artifact-scan"
+      }
+    },
+    "conformance": {
+      "waivedSurfaces": [
+        {
+          "kind": "api",
+          "reason": "Embedded library plus a local CLI; it owns no HTTP service boundary and ships no serve bin."
+        },
+        {
+          "kind": "mcp",
+          "reason": "Embedded library; MCP execution belongs to the applications that consume these envelopes."
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,57 +1,85 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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",
+  "types": "./types/index.d.ts",
   "bin": {
     "events": "dist/cli/index.js",
     "hasna-events": "dist/cli/index.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./types/index.d.ts",
       "import": "./dist/index.js"
     },
     "./storage": {
-      "types": "./dist/storage.d.ts",
+      "types": "./types/storage.d.ts",
       "import": "./dist/storage.js"
     },
+    "./durable": {
+      "types": "./types/durable.d.ts",
+      "import": "./dist/durable.js"
+    },
+    "./durable-spool": {
+      "types": "./types/durable-spool.d.ts",
+      "import": "./dist/durable-spool.js"
+    },
+    "./durable-worker": {
+      "types": "./types/durable-worker.d.ts",
+      "import": "./dist/durable-worker.js"
+    },
     "./signing": {
-      "types": "./dist/signing.d.ts",
+      "types": "./types/signing.d.ts",
       "import": "./dist/signing.js"
     },
     "./filter": {
-      "types": "./dist/filter.d.ts",
+      "types": "./types/filter.d.ts",
       "import": "./dist/filter.js"
     },
     "./transports": {
-      "types": "./dist/transports.d.ts",
+      "types": "./types/transports.d.ts",
       "import": "./dist/transports.js"
     },
     "./catalog": {
-      "types": "./dist/catalog.d.ts",
+      "types": "./types/catalog.d.ts",
       "import": "./dist/catalog.js"
     },
+    "./app-event": {
+      "types": "./types/app-event.d.ts",
+      "import": "./dist/app-event.js"
+    },
+    "./schemas/hasna.app_event.v1.json": "./schemas/hasna.app_event.v1.json",
+    "./fixtures/hasna.app_event.v1.json": "./fixtures/hasna.app_event.v1.json",
     "./commander": {
-      "types": "./dist/commander.d.ts",
+      "types": "./types/commander.d.ts",
       "import": "./dist/commander.js"
     },
     "./cli": {
-      "types": "./dist/cli/index.d.ts",
+      "types": "./types/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     }
   },
   "files": [
     "dist",
+    "types",
+    "schemas",
+    "fixtures",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "hasna.contract.json"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts --outdir dist --target bun && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "bun run build:runtime && bun run build:types",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts src/app-event.ts src/durable.ts src/durable-worker.ts --root src --outdir dist --target bun && bun build src/durable-spool.ts --root src --outdir dist --target node",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "generated-artifacts:check": "bun run build && test -z \"$(git status --porcelain --untracked-files=all -- dist types)\"",
+    "contract:check": "contracts repo-conformance .",
+    "artifact-scan": "bun scripts/artifact-scan.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "prepack": "bun run build && bun run artifact-scan",
     "prepublishOnly": "bun run test && bun run build"
   },
   "keywords": [
@@ -75,7 +103,8 @@
     "url": "https://github.com/hasna/events/issues"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.0.0",
+    "node": ">=20.0.0"
   },
   "author": "Hasna",
   "license": "Apache-2.0",
@@ -83,6 +112,7 @@
     "commander": "^13.1.0"
   },
   "devDependencies": {
+    "@hasna/contracts": "0.8.5",
     "@types/bun": "latest",
     "typescript": "^5.7.3"
   }

package/schemas/hasna.app_event.v1.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.hasna.com/hasna.app_event.v1.json",
+  "title": "hasna.app_event.v1",
+  "description": "Versioned cross-app event profile carried by @hasna/events.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event_id",
+    "event_type",
+    "schema_version",
+    "source",
+    "occurred_at",
+    "severity",
+    "idempotency",
+    "correlation",
+    "subject",
+    "actor",
+    "project_mappings",
+    "summary",
+    "data",
+    "resource_refs",
+    "evidence_refs",
+    "sensitivity",
+    "redaction",
+    "delivery"
+  ],
+  "properties": {
+    "event_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "event_type": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "schema_version": { "const": "hasna.app_event.v1" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["app", "version", "machine"],
+      "properties": {
+        "app": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "machine": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "severity": { "enum": ["debug", "info", "notice", "warning", "error", "critical"] },
+    "idempotency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dedupe_key", "replay_safe"],
+      "properties": {
+        "dedupe_key": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "replay_safe": { "type": "boolean" },
+        "replay_of_event_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["correlation_id"],
+      "properties": {
+        "correlation_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "causation_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "trace_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" }
+      }
+    },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "enum": ["agent", "human", "service", "model", "workflow", "system"] },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "project_mappings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canonical_id", "external_ids"],
+      "properties": {
+        "canonical_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "slug": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "repository": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "workspace": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "external_ids": {
+          "type": "object",
+          "maxProperties": 16,
+          "propertyNames": { "minLength": 1 },
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "data": {
+      "type": "object",
+      "description": "Bounded to 32768 serialized UTF-8 bytes by the runtime validator.",
+      "x-max-utf8-bytes": 32768
+    },
+    "resource_refs": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "$ref": "#/$defs/resource_ref" }
+    },
+    "evidence_refs": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "$ref": "#/$defs/evidence_ref" }
+    },
+    "sensitivity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classification", "contains_personal_data"],
+      "properties": {
+        "classification": { "enum": ["public", "internal", "confidential", "restricted"] },
+        "contains_personal_data": { "type": "boolean" }
+      }
+    },
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "fields", "safe_for_logs"],
+      "properties": {
+        "state": { "enum": ["none", "partial", "full"] },
+        "fields": {
+          "type": "array",
+          "maxItems": 32,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "safe_for_logs": { "type": "boolean" }
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intent", "mode", "targets", "agent_conversation_injection"],
+      "properties": {
+        "intent": { "enum": ["notification", "state_sync", "audit", "command"] },
+        "mode": { "enum": ["at_most_once", "at_least_once"] },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "agent_conversation_injection": {
+          "const": false,
+          "description": "Event text is untrusted data and must not be injected into agent conversations."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "resource_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "source_package": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "uri", "redaction"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" },
+        "redaction": { "enum": ["none", "partial", "full"] }
+      }
+    }
+  }
+}