@hasna/events 0.1.13 → 0.1.15

package/dist/storage.js

@@ -1,11 +1,15 @@
 // @bun
 // src/storage.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { Buffer } from "buffer";
 import { existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+var LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
+var DEFAULT_EVENT_PAGE_LIMIT = 100;
+var MAX_EVENT_PAGE_LIMIT = 1000;
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
@@ -19,11 +23,13 @@ function getActiveEventsDirEnv() {
 
 class JsonEventsStore {
   dataDir;
+  runtime;
   channelsPath;
   eventsPath;
   deliveriesPath;
   constructor(dataDir = getEventsDataDir()) {
     this.dataDir = dataDir;
+    this.runtime = localJsonRuntime(dataDir);
     this.channelsPath = join(dataDir, "channels.json");
     this.eventsPath = join(dataDir, "events.json");
     this.deliveriesPath = join(dataDir, "deliveries.json");
@@ -71,13 +77,58 @@ class JsonEventsStore {
     await this.writeJson(this.eventsPath, events);
     return event;
   }
-  async listEvents() {
+  async appendEventOnce(event, options = {}) {
     await this.init();
-    return this.readJson(this.eventsPath, []);
+    const events = await this.readJson(this.eventsPath, []);
+    const dedupe = options.dedupe !== false;
+    if (dedupe) {
+      const existing = findEventByIdentity(events, { id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    events.push(event);
+    await this.writeJson(this.eventsPath, events);
+    return {
+      event,
+      stored: true,
+      deduped: false,
+      identity: { id: event.id, dedupeKey: event.dedupeKey }
+    };
+  }
+  async listEvents(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    return queryEvents(events, options);
+  }
+  async listEventsPage(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    const queried = queryEvents(events, {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = queried.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < queried.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async findEventByIdentity(identity) {
     const events = await this.listEvents();
-    return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+    return findEventByIdentity(events, identity);
   }
   async appendDelivery(result) {
     await this.init();
@@ -128,6 +179,83 @@ class JsonEventsStore {
     });
   }
 }
+function localJsonRuntime(dataDir = getEventsDataDir()) {
+  return {
+    mode: "local-files",
+    name: "json-events-store",
+    remote: false,
+    localFiles: true,
+    localSqlite: false,
+    postgres: false,
+    s3: false,
+    aws: false,
+    durable: true,
+    idempotency: "best-effort-local",
+    replayCursors: true,
+    description: `Local JSON files in ${dataDir}; no SQLite, Postgres, S3, or AWS runtime is configured by this store.`
+  };
+}
+function encodeLocalJsonEventCursor(offset, options = {}) {
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid event cursor offset: ${offset}`);
+  const payload = {
+    offset,
+    eventId: options.eventId,
+    source: options.source,
+    type: options.type
+  };
+  return `${LOCAL_JSON_EVENT_CURSOR_PREFIX}${Buffer.from(JSON.stringify(payload), "utf-8").toString("base64url")}`;
+}
+function decodeLocalJsonEventCursor(cursor, options = {}) {
+  if (!cursor)
+    return 0;
+  if (!cursor.startsWith(LOCAL_JSON_EVENT_CURSOR_PREFIX))
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  const rawPayload = cursor.slice(LOCAL_JSON_EVENT_CURSOR_PREFIX.length);
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(rawPayload, "base64url").toString("utf-8"));
+  } catch {
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  }
+  const offset = payload.offset;
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  assertCursorFilter("eventId", payload.eventId, options.eventId);
+  assertCursorFilter("source", payload.source, options.source);
+  assertCursorFilter("type", payload.type, options.type);
+  return offset;
+}
+function normalizeEventPageLimit(limit) {
+  if (limit === undefined)
+    return DEFAULT_EVENT_PAGE_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1)
+    throw new Error(`Event page limit must be a positive integer, got ${limit}`);
+  return Math.min(limit, MAX_EVENT_PAGE_LIMIT);
+}
+function queryEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor) {
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    rows = rows.slice(offset);
+  }
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
+function assertCursorFilter(name, cursorValue, optionValue) {
+  if (cursorValue !== optionValue)
+    throw new Error(`Local JSON event cursor ${name} filter mismatch`);
+}
+function findEventByIdentity(events, identity) {
+  return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+}
 async function getEventsStatus(dataDir) {
   const store = new JsonEventsStore(dataDir);
   await store.init();
@@ -144,6 +272,7 @@ async function getEventsStatus(dataDir) {
     service: "events",
     schemaVersion: "1.0",
     dataDir: store.dataDir,
+    storage: store.runtime,
     env: {
       primary: HASNA_EVENTS_DIR_ENV,
       fallback: HASNA_EVENTS_HOME_ENV,
@@ -175,10 +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,
-  HASNA_EVENTS_DIR_ENV
+  HASNA_EVENTS_DIR_ENV,
+  DEFAULT_EVENT_PAGE_LIMIT
 };

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`);

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": "open-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": "open-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,53 +1,85 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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": "./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 --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": [
@@ -71,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",
@@ -79,6 +112,7 @@
     "commander": "^13.1.0"
   },
   "devDependencies": {
+    "@hasna/contracts": "0.8.5",
     "@types/bun": "latest",
     "typescript": "^5.7.3"
   }