@hasna/events 0.1.0

package/dist/storage.d.ts

@@ -0,0 +1,44 @@
+import type { ChannelConfig, DeliveryResult, EventEnvelope, StoredEventsData } from "./types.js";
+export declare const HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
+export declare const HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+export declare function getEventsDataDir(override?: string): string;
+export interface EventsStore {
+    dataDir: string;
+    init(): Promise<void>;
+    addChannel(channel: ChannelConfig): Promise<ChannelConfig>;
+    listChannels(): Promise<ChannelConfig[]>;
+    getChannel(id: string): Promise<ChannelConfig | undefined>;
+    removeChannel(id: string): Promise<boolean>;
+    appendEvent(event: EventEnvelope): Promise<EventEnvelope>;
+    listEvents(): Promise<EventEnvelope[]>;
+    findEventByIdentity(identity: {
+        id?: string;
+        dedupeKey?: string;
+    }): Promise<EventEnvelope | undefined>;
+    appendDelivery(result: DeliveryResult): Promise<DeliveryResult>;
+    listDeliveries(): Promise<DeliveryResult[]>;
+}
+export declare class JsonEventsStore implements EventsStore {
+    dataDir: string;
+    private channelsPath;
+    private eventsPath;
+    private deliveriesPath;
+    constructor(dataDir?: string);
+    init(): Promise<void>;
+    addChannel(channel: ChannelConfig): Promise<ChannelConfig>;
+    listChannels(): Promise<ChannelConfig[]>;
+    getChannel(id: string): Promise<ChannelConfig | undefined>;
+    removeChannel(id: string): Promise<boolean>;
+    appendEvent(event: EventEnvelope): Promise<EventEnvelope>;
+    listEvents(): Promise<EventEnvelope[]>;
+    findEventByIdentity(identity: {
+        id?: string;
+        dedupeKey?: string;
+    }): Promise<EventEnvelope | undefined>;
+    appendDelivery(result: DeliveryResult): Promise<DeliveryResult>;
+    listDeliveries(): Promise<DeliveryResult[]>;
+    exportData(): Promise<StoredEventsData>;
+    private ensureArrayFile;
+    private readJson;
+    private writeJson;
+}

package/dist/storage.js

@@ -0,0 +1,120 @@
+// @bun
+// src/storage.ts
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+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";
+function getEventsDataDir(override) {
+  return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
+}
+
+class JsonEventsStore {
+  dataDir;
+  channelsPath;
+  eventsPath;
+  deliveriesPath;
+  constructor(dataDir = getEventsDataDir()) {
+    this.dataDir = dataDir;
+    this.channelsPath = join(dataDir, "channels.json");
+    this.eventsPath = join(dataDir, "events.json");
+    this.deliveriesPath = join(dataDir, "deliveries.json");
+  }
+  async init() {
+    await mkdir(this.dataDir, { recursive: true });
+    await this.ensureArrayFile(this.channelsPath);
+    await this.ensureArrayFile(this.eventsPath);
+    await this.ensureArrayFile(this.deliveriesPath);
+  }
+  async addChannel(channel) {
+    await this.init();
+    const channels = await this.readJson(this.channelsPath, []);
+    const index = channels.findIndex((item) => item.id === channel.id);
+    if (index >= 0) {
+      channels[index] = { ...channel, createdAt: channels[index].createdAt, updatedAt: new Date().toISOString() };
+    } else {
+      channels.push(channel);
+    }
+    await this.writeJson(this.channelsPath, channels);
+    return index >= 0 ? channels[index] : channel;
+  }
+  async listChannels() {
+    await this.init();
+    return this.readJson(this.channelsPath, []);
+  }
+  async getChannel(id) {
+    const channels = await this.listChannels();
+    return channels.find((channel) => channel.id === id);
+  }
+  async removeChannel(id) {
+    await this.init();
+    const channels = await this.readJson(this.channelsPath, []);
+    const next = channels.filter((channel) => channel.id !== id);
+    await this.writeJson(this.channelsPath, next);
+    return next.length !== channels.length;
+  }
+  async appendEvent(event) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    events.push(event);
+    await this.writeJson(this.eventsPath, events);
+    return event;
+  }
+  async listEvents() {
+    await this.init();
+    return this.readJson(this.eventsPath, []);
+  }
+  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);
+  }
+  async appendDelivery(result) {
+    await this.init();
+    const deliveries = await this.readJson(this.deliveriesPath, []);
+    deliveries.push(result);
+    await this.writeJson(this.deliveriesPath, deliveries);
+    return result;
+  }
+  async listDeliveries() {
+    await this.init();
+    return this.readJson(this.deliveriesPath, []);
+  }
+  async exportData() {
+    return {
+      channels: await this.listChannels(),
+      events: await this.listEvents(),
+      deliveries: await this.listDeliveries()
+    };
+  }
+  async ensureArrayFile(path) {
+    if (!existsSync(path)) {
+      await writeFile(path, `[]
+`, "utf-8");
+    }
+  }
+  async readJson(path, fallback) {
+    try {
+      const raw = await readFile(path, "utf-8");
+      if (!raw.trim())
+        return fallback;
+      return JSON.parse(raw);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return fallback;
+      throw error;
+    }
+  }
+  async writeJson(path, value) {
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}
+`, "utf-8");
+    await rename(tempPath, path);
+  }
+}
+export {
+  getEventsDataDir,
+  JsonEventsStore,
+  HASNA_EVENTS_HOME_ENV,
+  HASNA_EVENTS_DIR_ENV
+};

package/dist/transports.d.ts

@@ -0,0 +1,12 @@
+import type { ChannelConfig, DeliveryAttempt, DeliveryResult, EventEnvelope } from "./types.js";
+export interface TransportDispatchOptions {
+    fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+export declare function buildWebhookRequest(event: EventEnvelope, channel: ChannelConfig): {
+    body: string;
+    headers: Record<string, string>;
+};
+export declare function dispatchWebhook(event: EventEnvelope, channel: ChannelConfig, options?: TransportDispatchOptions): Promise<DeliveryAttempt>;
+export declare function dispatchCommand(event: EventEnvelope, channel: ChannelConfig): Promise<DeliveryAttempt>;
+export declare function dispatchChannel(event: EventEnvelope, channel: ChannelConfig, options?: TransportDispatchOptions): Promise<DeliveryAttempt>;
+export declare function createDeliveryResult(event: EventEnvelope, channel: ChannelConfig, attempts: DeliveryAttempt[]): DeliveryResult;

package/dist/transports.js

@@ -0,0 +1,191 @@
+// @bun
+// src/signing.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function buildSignatureBase(timestamp, body) {
+  return `${timestamp}.${body}`;
+}
+function signPayload(secret, timestamp, body) {
+  const digest = createHmac("sha256", secret).update(buildSignatureBase(timestamp, body)).digest("hex");
+  return `sha256=${digest}`;
+}
+function verifyPayloadSignature(secret, timestamp, body, signature) {
+  const expected = signPayload(secret, timestamp, body);
+  const actual = signature.trim();
+  const expectedBuffer = Buffer.from(expected);
+  const actualBuffer = Buffer.from(actual);
+  if (expectedBuffer.length !== actualBuffer.length)
+    return false;
+  return timingSafeEqual(expectedBuffer, actualBuffer);
+}
+function isTimestampWithinTolerance(timestamp, toleranceMs, now = Date.now()) {
+  const parsed = Date.parse(timestamp);
+  if (!Number.isFinite(parsed))
+    return false;
+  const reference = now instanceof Date ? now.getTime() : now;
+  return Math.abs(reference - parsed) <= toleranceMs;
+}
+function verifyWebhookSignature(secret, timestamp, body, signature, options = {}) {
+  if (options.toleranceMs !== undefined && !isTimestampWithinTolerance(timestamp, options.toleranceMs, options.now)) {
+    return false;
+  }
+  return verifyPayloadSignature(secret, timestamp, body, signature);
+}
+
+// src/transports.ts
+import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+function now() {
+  return new Date().toISOString();
+}
+function truncate(value, max = 4096) {
+  return value.length > max ? `${value.slice(0, max)}...` : value;
+}
+function buildWebhookRequest(event, channel) {
+  if (!channel.webhook)
+    throw new Error(`Channel ${channel.id} has no webhook config`);
+  const body = JSON.stringify(event);
+  const timestamp = event.time;
+  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
+  };
+  if (channel.webhook.secret) {
+    headers["X-Hasna-Signature"] = signPayload(channel.webhook.secret, timestamp, body);
+  }
+  return { body, headers };
+}
+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);
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), channel.webhook.timeoutMs ?? 15000);
+  try {
+    const response = await (options.fetchImpl ?? fetch)(channel.webhook.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    const responseBody = truncate(await response.text());
+    return {
+      attempt: 1,
+      status: response.ok ? "success" : "failed",
+      startedAt,
+      completedAt: now(),
+      responseStatus: response.status,
+      responseBody,
+      error: response.ok ? undefined : `Webhook returned HTTP ${response.status}`
+    };
+  } catch (error) {
+    return {
+      attempt: 1,
+      status: "failed",
+      startedAt,
+      completedAt: now(),
+      error: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function dispatchCommand(event, channel) {
+  if (!channel.command)
+    throw new Error(`Channel ${channel.id} has no command config`);
+  const startedAt = now();
+  const eventJson = JSON.stringify(event);
+  const env = {
+    ...process.env,
+    ...channel.command.env,
+    HASNA_CHANNEL_ID: channel.id,
+    HASNA_EVENT_ID: event.id,
+    HASNA_EVENT_TYPE: event.type,
+    HASNA_EVENT_SOURCE: event.source,
+    HASNA_EVENT_SUBJECT: event.subject ?? "",
+    HASNA_EVENT_SEVERITY: event.severity,
+    HASNA_EVENT_TIME: event.time,
+    HASNA_EVENT_DEDUPE_KEY: event.dedupeKey ?? "",
+    HASNA_EVENT_SCHEMA_VERSION: event.schemaVersion,
+    HASNA_EVENT_JSON: eventJson
+  };
+  return new Promise((resolve) => {
+    const child = spawn(channel.command.command, channel.command.args ?? [], {
+      cwd: channel.command.cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    const timeout = setTimeout(() => child.kill("SIGTERM"), channel.command.timeoutMs ?? 15000);
+    child.stdin.end(eventJson);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      clearTimeout(timeout);
+      resolve({
+        attempt: 1,
+        status: "failed",
+        startedAt,
+        completedAt: now(),
+        stdout: truncate(stdout),
+        stderr: truncate(stderr),
+        error: error.message
+      });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timeout);
+      const success = code === 0;
+      resolve({
+        attempt: 1,
+        status: success ? "success" : "failed",
+        startedAt,
+        completedAt: now(),
+        stdout: truncate(stdout),
+        stderr: truncate(stderr),
+        error: success ? undefined : `Command exited with ${signal ? `signal ${signal}` : `code ${code}`}`
+      });
+    });
+  });
+}
+async function dispatchChannel(event, channel, options = {}) {
+  if (channel.transport === "webhook")
+    return dispatchWebhook(event, channel, options);
+  if (channel.transport === "command")
+    return dispatchCommand(event, channel);
+  return {
+    attempt: 1,
+    status: "skipped",
+    startedAt: now(),
+    completedAt: now(),
+    error: `Unsupported transport: ${channel.transport}`
+  };
+}
+function createDeliveryResult(event, channel, attempts) {
+  const status = attempts.some((attempt) => attempt.status === "success") ? "success" : attempts.every((attempt) => attempt.status === "skipped") ? "skipped" : "failed";
+  return {
+    id: randomUUID(),
+    eventId: event.id,
+    channelId: channel.id,
+    transport: channel.transport,
+    status,
+    attempts,
+    createdAt: attempts[0]?.startedAt ?? now(),
+    completedAt: attempts.at(-1)?.completedAt ?? now()
+  };
+}
+export {
+  dispatchWebhook,
+  dispatchCommand,
+  dispatchChannel,
+  createDeliveryResult,
+  buildWebhookRequest
+};

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+export type EventSeverity = "debug" | "info" | "notice" | "warning" | "error" | "critical";
+export type EventData = Record<string, unknown>;
+export interface EventEnvelope<TData extends EventData = EventData> {
+    id: string;
+    source: string;
+    type: string;
+    time: string;
+    subject?: string;
+    severity: EventSeverity;
+    data: TData;
+    message?: string;
+    dedupeKey?: string;
+    schemaVersion: string;
+    metadata: Record<string, unknown>;
+}
+export interface EventInput<TData extends EventData = EventData> {
+    id?: string;
+    source: string;
+    type: string;
+    time?: string | Date;
+    subject?: string;
+    severity?: EventSeverity;
+    data?: TData;
+    message?: string;
+    dedupeKey?: string;
+    schemaVersion?: string;
+    metadata?: Record<string, unknown>;
+}
+export type StringMatcher = string | string[];
+export interface EventFilter {
+    source?: StringMatcher;
+    type?: StringMatcher;
+    subject?: StringMatcher;
+    severity?: StringMatcher;
+    data?: Record<string, StringMatcher | number | boolean | null>;
+    metadata?: Record<string, StringMatcher | number | boolean | null>;
+}
+export interface RetryPolicy {
+    maxAttempts?: number;
+    backoffMs?: number;
+    multiplier?: number;
+}
+export interface RedactionConfig {
+    paths?: string[];
+    replacement?: string;
+}
+export interface WebhookTransportConfig {
+    url: string;
+    secret?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface CommandTransportConfig {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+export type TransportKind = "webhook" | "command" | "email" | "sse" | "mcp-relay";
+export interface ChannelConfig {
+    id: string;
+    name?: string;
+    enabled: boolean;
+    transport: TransportKind;
+    filters?: EventFilter[];
+    webhook?: WebhookTransportConfig;
+    command?: CommandTransportConfig;
+    retry?: RetryPolicy;
+    redact?: RedactionConfig;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DeliveryAttempt {
+    attempt: number;
+    status: "success" | "failed" | "skipped";
+    startedAt: string;
+    completedAt: string;
+    responseStatus?: number;
+    responseBody?: string;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+    nextBackoffMs?: number;
+}
+export interface DeliveryResult {
+    id: string;
+    eventId: string;
+    channelId: string;
+    transport: TransportKind;
+    status: "success" | "failed" | "skipped";
+    attempts: DeliveryAttempt[];
+    createdAt: string;
+    completedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export type EventRedactor = (event: EventEnvelope, channel: ChannelConfig) => EventEnvelope | Promise<EventEnvelope>;
+export interface EmitOptions {
+    deliver?: boolean;
+    dedupe?: boolean;
+}
+export interface ReplayOptions {
+    eventId?: string;
+    source?: string;
+    type?: string;
+    dryRun?: boolean;
+}
+export interface StoredEventsData {
+    channels: ChannelConfig[];
+    events: EventEnvelope[];
+    deliveries: DeliveryResult[];
+}
+export interface EmitResult<TData extends EventData = EventData> {
+    event: EventEnvelope<TData>;
+    deliveries: DeliveryResult[];
+    deduped: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+// @bun

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@hasna/events",
+  "version": "0.1.0",
+  "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "events": "./dist/cli/index.js",
+    "hasna-events": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    },
+    "./signing": {
+      "types": "./dist/signing.d.ts",
+      "import": "./dist/signing.js"
+    },
+    "./filter": {
+      "types": "./dist/filter.d.ts",
+      "import": "./dist/filter.js"
+    },
+    "./transports": {
+      "types": "./dist/transports.d.ts",
+      "import": "./dist/transports.js"
+    },
+    "./commander": {
+      "types": "./dist/commander.d.ts",
+      "import": "./dist/commander.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run test && bun run build"
+  },
+  "keywords": [
+    "events",
+    "webhooks",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/events.git"
+  },
+  "homepage": "https://github.com/hasna/events",
+  "bugs": {
+    "url": "https://github.com/hasna/events/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.3"
+  }
+}