@hasna/events 0.1.13 → 0.1.15

package/{dist → types}/index.d.ts

@@ -1,15 +1,31 @@
-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 * from "./app-event.js";
+export { redactPaths, redactSensitiveKeys } from "./redaction.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,24 +42,23 @@ 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;
 }
-export declare function redactPaths<T extends EventEnvelope>(event: T, paths: string[], replacement?: string): T;
 export declare function sanitizeChannelForOutput(channel: ChannelConfig): ChannelConfig;
 export declare function sanitizeChannelsForOutput(channels: ChannelConfig[]): ChannelConfig[];
-export declare function redactSensitiveKeys<T extends EventEnvelope>(event: T, replacement?: string): T;

package/types/redaction.d.ts

@@ -0,0 +1,4 @@
+import type { EventEnvelope } from "./types.js";
+export declare function redactPaths<T extends EventEnvelope>(event: T, paths: string[], replacement?: string): T;
+export declare function redactSensitiveKeys<T extends EventEnvelope>(event: T, replacement?: string): T;
+export declare function shouldRedactKey(key: string): boolean;

package/{dist → types}/storage.d.ts

@@ -1,17 +1,23 @@
-import type { ChannelConfig, DeliveryResult, EventEnvelope, EventsStatus, StoredEventsData } from "./types.js";
+import type { ChannelConfig, DeliveryResult, EventAppendOptions, EventAppendResult, EventEnvelope, EventPage, EventPageOptions, EventsStatus, EventsStoreRuntime, 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 const LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
+export declare const DEFAULT_EVENT_PAGE_LIMIT = 100;
+export declare const MAX_EVENT_PAGE_LIMIT = 1000;
 export declare function getEventsDataDir(override?: string): string;
 export declare function getActiveEventsDirEnv(): EventsStatus["env"]["active"];
 export interface EventsStore {
     dataDir: string;
+    runtime?: EventsStoreRuntime;
     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[]>;
+    appendEventOnce?(event: EventEnvelope, options?: EventAppendOptions): Promise<EventAppendResult>;
+    listEvents(options?: EventPageOptions): Promise<EventEnvelope[]>;
+    listEventsPage?(options?: EventPageOptions): Promise<EventPage>;
     findEventByIdentity(identity: {
         id?: string;
         dedupeKey?: string;
@@ -21,6 +27,7 @@ export interface EventsStore {
 }
 export declare class JsonEventsStore implements EventsStore {
     dataDir: string;
+    runtime: EventsStoreRuntime;
     private channelsPath;
     private eventsPath;
     private deliveriesPath;
@@ -31,7 +38,9 @@ export declare class JsonEventsStore implements EventsStore {
     getChannel(id: string): Promise<ChannelConfig | undefined>;
     removeChannel(id: string): Promise<boolean>;
     appendEvent(event: EventEnvelope): Promise<EventEnvelope>;
-    listEvents(): Promise<EventEnvelope[]>;
+    appendEventOnce(event: EventEnvelope, options?: EventAppendOptions): Promise<EventAppendResult>;
+    listEvents(options?: EventPageOptions): Promise<EventEnvelope[]>;
+    listEventsPage(options?: EventPageOptions): Promise<EventPage>;
     findEventByIdentity(identity: {
         id?: string;
         dedupeKey?: string;
@@ -43,4 +52,8 @@ export declare class JsonEventsStore implements EventsStore {
     private readJson;
     private writeJson;
 }
+export declare function localJsonRuntime(dataDir?: string): EventsStoreRuntime;
+export declare function encodeLocalJsonEventCursor(offset: number, options?: EventPageOptions): string;
+export declare function decodeLocalJsonEventCursor(cursor: string | undefined, options?: EventPageOptions): number;
+export declare function normalizeEventPageLimit(limit: number | undefined): number;
 export declare function getEventsStatus(dataDir?: string): Promise<EventsStatus>;

package/{dist → types}/transports.d.ts

@@ -1,8 +1,15 @@
 import type { ChannelConfig, DeliveryAttempt, DeliveryResult, EventEnvelope } from "./types.js";
 export interface TransportDispatchOptions {
     fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    secretResolver?: WebhookSecretResolver;
+    now?: () => Date;
 }
-export declare function buildWebhookRequest(event: EventEnvelope, channel: ChannelConfig): {
+export type WebhookSecretResolver = (reference: string) => string | undefined | Promise<string | undefined>;
+export interface BuildWebhookRequestOptions {
+    secret?: string;
+    timestamp?: string;
+}
+export declare function buildWebhookRequest(event: EventEnvelope, channel: ChannelConfig, options?: BuildWebhookRequestOptions): {
     body: string;
     headers: Record<string, string>;
 };

package/{dist → types}/types.d.ts

@@ -51,7 +51,16 @@ export interface RedactionConfig {
 }
 export interface WebhookTransportConfig {
     url: string;
+    /**
+     * Legacy inline HMAC secret. Durable stores should reject this field so
+     * credential material is never persisted with channel configuration.
+     */
     secret?: string;
+    /**
+     * Runtime-only HMAC secret reference, for example
+     * `env:HASNA_NOTES_WEBHOOK_SECRET`.
+     */
+    secretRef?: string;
     headers?: Record<string, string>;
     timeoutMs?: number;
 }
@@ -105,13 +114,50 @@ export interface EmitOptions {
     deliver?: boolean;
     dedupe?: boolean;
     redactSensitiveData?: boolean;
-}
-export interface ReplayOptions {
+    /**
+     * Per-emit override for the opt-in catalog validator hook. When true the
+     * event is validated against the client's `EventTypeCatalog` before it is
+     * stored or delivered (types not registered in the catalog always pass);
+     * when false validation is skipped even if the client enabled
+     * `validateCatalogTypes`. Defaults to the client-level setting (off).
+     */
+    validate?: boolean;
+}
+export interface EventPageOptions {
     eventId?: string;
     source?: string;
     type?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface EventPage {
+    events: EventEnvelope[];
+    cursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export interface EventAppendOptions {
+    dedupe?: boolean;
+}
+export interface EventAppendResult<TData extends EventData = EventData> {
+    event: EventEnvelope<TData>;
+    stored: boolean;
+    deduped: boolean;
+    identity: {
+        id: string;
+        dedupeKey?: string;
+    };
+}
+export interface ReplayOptions extends EventPageOptions {
     dryRun?: boolean;
 }
+export interface ReplayResult {
+    events: EventEnvelope[];
+    deliveries: DeliveryResult[];
+    cursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+}
 export interface StoredEventsData {
     channels: ChannelConfig[];
     events: EventEnvelope[];
@@ -122,10 +168,26 @@ export interface EmitResult<TData extends EventData = EventData> {
     deliveries: DeliveryResult[];
     deduped: boolean;
 }
+export type EventsStorageMode = "local-files" | "local-sqlite" | "remote-postgres" | "remote-s3" | "remote-aws" | "custom";
+export interface EventsStoreRuntime {
+    mode: EventsStorageMode;
+    name: string;
+    remote: boolean;
+    localFiles: boolean;
+    localSqlite: boolean;
+    postgres: boolean;
+    s3: boolean;
+    aws: boolean;
+    durable: boolean;
+    idempotency: "best-effort-local" | "atomic-store" | "consumer-owned";
+    replayCursors: boolean;
+    description: string;
+}
 export interface EventsStatus {
     service: "events";
     schemaVersion: "1.0";
     dataDir: string;
+    storage: EventsStoreRuntime;
     env: {
         primary: "HASNA_EVENTS_DIR";
         fallback: "HASNA_EVENTS_HOME";