@hasna/events 0.1.13 → 0.1.14

package/dist/commander.js

@@ -98,11 +98,15 @@ function channelMatchesEvent(channel, event) {
 
 // src/storage.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { Buffer as Buffer2 } 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");
 }
@@ -116,11 +120,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");
@@ -168,13 +174,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();
@@ -225,6 +276,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}${Buffer2.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(Buffer2.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();
@@ -241,6 +369,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,
@@ -457,6 +586,182 @@ function createDeliveryResult(event, channel, attempts) {
     completedAt: attempts.at(-1)?.completedAt ?? now()
   };
 }
+
+// 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;
+}
 // src/index.ts
 import { randomUUID as randomUUID2 } from "crypto";
 function createEvent(input) {
@@ -479,10 +784,14 @@ class EventsClient {
   store;
   redactors;
   transportOptions;
+  catalog;
+  validateCatalogTypes;
   constructor(options = {}) {
     this.store = options.store ?? new JsonEventsStore(options.dataDir);
     this.redactors = options.redactors ?? [];
     this.transportOptions = { fetchImpl: options.fetchImpl };
+    this.catalog = options.catalog ?? defaultEventTypeCatalog;
+    this.validateCatalogTypes = options.validateCatalogTypes ?? false;
   }
   async addChannel(input) {
     const timestamp = new Date().toISOString();
@@ -500,18 +809,40 @@ class EventsClient {
   }
   async emit(input, options = {}) {
     const event = options.redactSensitiveData === false ? createEvent(input) : redactSensitiveKeys(createEvent(input));
-    if (options.dedupe !== false) {
-      const existing = await this.store.findEventByIdentity({ id: input.id, dedupeKey: event.dedupeKey });
-      if (existing) {
-        return { event: existing, deliveries: [], deduped: true };
-      }
+    if (options.validate ?? this.validateCatalogTypes) {
+      this.catalog.assertEventValid(event);
     }
-    await this.store.appendEvent(event);
-    const deliveries = options.deliver === false ? [] : await this.deliver(event);
-    return { event, deliveries, deduped: false };
+    const append = await this.appendEvent(event, { dedupe: options.dedupe !== false });
+    if (append.deduped) {
+      return { event: append.event, deliveries: [], deduped: true };
+    }
+    const deliveries = options.deliver === false ? [] : await this.deliver(append.event);
+    return { event: append.event, deliveries, deduped: false };
   }
-  async listEvents() {
-    return this.store.listEvents();
+  async listEvents(options = {}) {
+    if (Object.keys(options).length === 0)
+      return this.store.listEvents();
+    return queryClientEvents(await this.store.listEvents(), options);
+  }
+  async listEventsPage(options = {}) {
+    if (this.store.listEventsPage)
+      return this.store.listEventsPage(options);
+    const events = queryClientEvents(await this.store.listEvents(), {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = events.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < events.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async listDeliveries() {
     return this.store.listDeliveries();
@@ -579,22 +910,37 @@ class EventsClient {
     return result;
   }
   async replay(options = {}) {
-    const events = (await this.store.listEvents()).filter((event) => {
-      if (options.eventId && event.id !== options.eventId)
-        return false;
-      if (options.source && event.source !== options.source)
-        return false;
-      if (options.type && event.type !== options.type)
-        return false;
-      return true;
-    });
+    const page = options.cursor || options.limit !== undefined ? await this.listEventsPage(options) : { events: await this.listEvents(options), hasMore: false };
     if (options.dryRun)
-      return { events, deliveries: [] };
+      return { events: page.events, deliveries: [], cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
     const deliveries = [];
-    for (const event of events) {
+    for (const event of page.events) {
       deliveries.push(...await this.deliver(event));
     }
-    return { events, deliveries };
+    return { events: page.events, deliveries, cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
+  }
+  async appendEvent(event, options) {
+    if (this.store.appendEventOnce) {
+      return this.store.appendEventOnce(event, { dedupe: options.dedupe });
+    }
+    if (options.dedupe) {
+      const existing = await this.store.findEventByIdentity({ id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    const stored = await this.store.appendEvent(event);
+    return {
+      event: stored,
+      stored: true,
+      deduped: false,
+      identity: { id: stored.id, dedupeKey: stored.dedupeKey }
+    };
   }
   async applyRedaction(event, channel) {
     let next = redactPaths(event, channel.redact?.paths ?? [], channel.redact?.replacement ?? "[REDACTED]");
@@ -671,6 +1017,20 @@ function setPath(input, path, replacement) {
   if (last && last in cursor)
     cursor[last] = replacement;
 }
+function queryClientEvents(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)
+    rows = rows.slice(decodeLocalJsonEventCursor(options.cursor, options));
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
 function normalizeTime(value) {
   if (!value)
     return new Date().toISOString();
@@ -757,6 +1117,7 @@ function parseMatcherExpression(value, label) {
 }
 
 // src/commander.ts
+var DEFAULT_EVENT_LIST_LIMIT = 100;
 function parseJsonObject(value, fallback) {
   if (!value)
     return fallback;
@@ -789,6 +1150,14 @@ function print(value, json, text) {
   else
     console.log(text);
 }
+function fail(error, json) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (json)
+    console.log(JSON.stringify({ error: message }, null, 2));
+  else
+    console.error(message);
+  process.exitCode = 1;
+}
 function hasJsonOption(options) {
   return Boolean(options?.json || options?.opts?.().json || options?.optsWithGlobals?.().json || options?.parent?.opts?.().json || options?.parent?.optsWithGlobals?.().json);
 }
@@ -843,26 +1212,36 @@ function registerChannelCommands(program, options) {
     print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
   channels.command("test").description("Send a test event to one channel").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").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("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
-    const result = await createClient(options).testChannel(id, {
-      source: actionOptions.source ?? options.source,
-      type: actionOptions.type,
-      subject: actionOptions.subject ?? id,
-      message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true }),
-      metadata: parseJsonObject(actionOptions.metadata, {})
-    }, { honorFilters: actionOptions.honorFilters });
-    print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).testChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      }, { honorFilters: actionOptions.honorFilters });
+      print(result, json, `${result.status}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
   });
   channels.command("match").description("Check whether a sample event matches one channel without delivering").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
-    const result = await createClient(options).matchChannel(id, {
-      source: actionOptions.source ?? options.source,
-      type: actionOptions.type,
-      subject: actionOptions.subject ?? id,
-      message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true }),
-      metadata: parseJsonObject(actionOptions.metadata, {})
-    });
-    print(result, wantsJson(actionOptions, command), `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).matchChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      });
+      print(result, json, `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
   });
   return channels;
 }
@@ -881,7 +1260,8 @@ function registerEventCommands(program, options) {
     }, { deliver: actionOptions.deliver, dedupe: actionOptions.dedupe });
     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, command) => {
+  const defaultListLimit = options.defaultEventListLimit ?? DEFAULT_EVENT_LIST_LIMIT;
+  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", `Limit to the most recent <n> events (default ${defaultListLimit}; use 0 for all)`, parseNumber, defaultListLimit).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);
@@ -900,14 +1280,16 @@ 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, command) => {
+  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("--cursor <cursor>", "Opaque replay cursor from a previous page").option("--limit <n>", "Maximum events to replay", parseNumber).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,
+      cursor: actionOptions.cursor,
+      limit: actionOptions.limit,
       dryRun: actionOptions.dryRun
     });
-    print(result, wantsJson(actionOptions, command), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
+    print(result, wantsJson(actionOptions, command), replaySummary(result.events.length, result.deliveries.length, result.nextCursor));
   });
   return events;
 }
@@ -925,8 +1307,13 @@ function collectValues(value, previous) {
   previous.push(value);
   return previous;
 }
+function replaySummary(events, deliveries, nextCursor) {
+  const suffix = nextCursor ? `, next cursor: ${nextCursor}` : "";
+  return `Replayed ${events} event(s), ${deliveries} delivery result(s)${suffix}`;
+}
 export {
   registerEventsCommands,
   registerEventCommands,
-  registerChannelCommands
+  registerChannelCommands,
+  DEFAULT_EVENT_LIST_LIMIT
 };

package/dist/index.d.ts

@@ -1,15 +1,29 @@
-import type { ChannelConfig, DeliveryResult, EmitOptions, EmitResult, EventEnvelope, EventFilter, EventInput, EventRedactor, ReplayOptions } from "./types.js";
+import type { ChannelConfig, DeliveryResult, EmitOptions, EmitResult, EventEnvelope, EventFilter, EventPage, EventPageOptions, EventInput, EventRedactor, ReplayOptions, ReplayResult } from "./types.js";
 import { type EventsStore } from "./storage.js";
 import { type TransportDispatchOptions } from "./transports.js";
+import { type EventTypeCatalog } from "./catalog.js";
 export * from "./types.js";
 export * from "./storage.js";
 export * from "./filter.js";
 export * from "./signing.js";
 export * from "./transports.js";
+export * from "./catalog.js";
 export interface EventsClientOptions extends TransportDispatchOptions {
     store?: EventsStore;
     dataDir?: string;
     redactors?: EventRedactor[];
+    /**
+     * Event type catalog used by the opt-in emit-time validator hook. Defaults
+     * to the shared `defaultEventTypeCatalog`.
+     */
+    catalog?: EventTypeCatalog;
+    /**
+     * Opt-in: when true, emitted events whose `type` is registered in the
+     * catalog are validated and rejected (with `EventValidationError`) before
+     * they are stored or delivered. Unregistered/free-form types always pass.
+     * Defaults to false, so existing emitters are untouched.
+     */
+    validateCatalogTypes?: boolean;
 }
 export interface ChannelMatchResult {
     channelId: string;
@@ -26,20 +40,21 @@ export declare class EventsClient {
     private store;
     private redactors;
     private transportOptions;
+    private catalog;
+    private validateCatalogTypes;
     constructor(options?: EventsClientOptions);
     addChannel(input: Omit<ChannelConfig, "createdAt" | "updatedAt"> & Partial<Pick<ChannelConfig, "createdAt" | "updatedAt">>): Promise<ChannelConfig>;
     listChannels(): Promise<ChannelConfig[]>;
     removeChannel(id: string): Promise<boolean>;
     emit<TData extends Record<string, unknown>>(input: EventInput<TData>, options?: EmitOptions): Promise<EmitResult<TData>>;
-    listEvents(): Promise<EventEnvelope[]>;
+    listEvents(options?: EventPageOptions): Promise<EventEnvelope[]>;
+    listEventsPage(options?: EventPageOptions): Promise<EventPage>;
     listDeliveries(): Promise<DeliveryResult[]>;
     deliver(event: EventEnvelope): Promise<DeliveryResult[]>;
     matchChannel(id: string, input?: Partial<EventInput>): Promise<ChannelMatchResult>;
     testChannel(id: string, input?: Partial<EventInput>, options?: TestChannelOptions): Promise<DeliveryResult>;
-    replay(options?: ReplayOptions): Promise<{
-        events: EventEnvelope[];
-        deliveries: DeliveryResult[];
-    }>;
+    replay(options?: ReplayOptions): Promise<ReplayResult>;
+    private appendEvent;
     private applyRedaction;
     private deliverWithRetry;
 }