@hasna/events 0.1.14 → 0.1.16

package/types/app-event.d.ts

@@ -0,0 +1,130 @@
+import type { EventData, EventEnvelope, EventInput, EventSeverity } from "./types.js";
+/** Stable wire-profile identifier for cross-app events. */
+export declare const APP_EVENT_V1_SCHEMA_VERSION: "hasna.app_event.v1";
+export declare const APP_EVENT_V1_METADATA_KEY: "app_event";
+export declare const APP_EVENT_V1_MAX_SUMMARY_LENGTH = 512;
+export declare const APP_EVENT_V1_MAX_DATA_BYTES: number;
+export declare const APP_EVENT_V1_MAX_REFS = 32;
+export declare const APP_EVENT_V1_MAX_TARGETS = 16;
+export type AppEventActorKind = "agent" | "human" | "service" | "model" | "workflow" | "system";
+export type AppEventSensitivity = "public" | "internal" | "confidential" | "restricted";
+export type AppEventRedactionState = "none" | "partial" | "full";
+export type AppEventDeliveryIntent = "notification" | "state_sync" | "audit" | "command";
+export type AppEventDeliveryMode = "at_most_once" | "at_least_once";
+export interface AppEventSource {
+    app: string;
+    version: string;
+    machine: string;
+}
+export interface AppEventIdempotency {
+    dedupe_key: string;
+    replay_safe: boolean;
+    replay_of_event_id?: string;
+}
+export interface AppEventCorrelation {
+    correlation_id: string;
+    causation_id?: string;
+    trace_id?: string;
+}
+export interface AppEventSubject {
+    kind: string;
+    id: string;
+    uri?: string;
+}
+export interface AppEventActor {
+    kind: AppEventActorKind;
+    id: string;
+    name?: string;
+}
+export interface AppEventProjectMappings {
+    canonical_id: string;
+    slug?: string;
+    repository?: string;
+    workspace?: string;
+    external_ids: Record<string, string>;
+}
+/** Dependency-free structural mirror of a hasna.resource_ref pointer. */
+export interface AppEventResourceRef {
+    kind: string;
+    id: string;
+    uri?: string;
+    source_package?: string;
+    external_id?: string;
+}
+/** Dependency-free structural mirror of a hasna.evidence_ref pointer. */
+export interface AppEventEvidenceRef {
+    kind: string;
+    id: string;
+    uri: string;
+    sha256?: string;
+    redaction: AppEventRedactionState;
+}
+export interface AppEventSensitivityPolicy {
+    classification: AppEventSensitivity;
+    contains_personal_data: boolean;
+}
+export interface AppEventRedaction {
+    state: AppEventRedactionState;
+    fields: string[];
+    safe_for_logs: boolean;
+}
+export interface AppEventDelivery {
+    intent: AppEventDeliveryIntent;
+    mode: AppEventDeliveryMode;
+    targets: string[];
+    /** Untrusted event text is data, never an instruction to an agent. */
+    agent_conversation_injection: false;
+}
+/**
+ * Cross-app wire profile carried by the existing @hasna/events envelope.
+ * Use {@link appEventV1ToEventInput}; this profile does not define another bus.
+ */
+export interface AppEventV1<TData extends EventData = EventData> {
+    event_id: string;
+    event_type: string;
+    schema_version: typeof APP_EVENT_V1_SCHEMA_VERSION;
+    source: AppEventSource;
+    occurred_at: string;
+    severity: EventSeverity;
+    idempotency: AppEventIdempotency;
+    correlation: AppEventCorrelation;
+    subject: AppEventSubject;
+    actor: AppEventActor;
+    project_mappings: AppEventProjectMappings;
+    summary: string;
+    data: TData;
+    resource_refs: AppEventResourceRef[];
+    evidence_refs: AppEventEvidenceRef[];
+    sensitivity: AppEventSensitivityPolicy;
+    redaction: AppEventRedaction;
+    delivery: AppEventDelivery;
+}
+export interface AppEventValidationIssue {
+    path: string;
+    message: string;
+}
+export type AppEventValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: AppEventValidationIssue[];
+};
+export declare class AppEventValidationError extends Error {
+    readonly issues: AppEventValidationIssue[];
+    constructor(issues: AppEventValidationIssue[]);
+}
+export declare class AppEventReplaySafetyError extends Error {
+    readonly eventId: string;
+    constructor(eventId: string);
+}
+export declare function validateAppEventV1(value: unknown): AppEventValidationResult;
+export declare function assertAppEventV1<TData extends EventData = EventData>(value: unknown): asserts value is AppEventV1<TData>;
+export declare function assertAppEventV1ReplaySafe(event: AppEventV1): void;
+export declare function appEventV1ReplayIdentity(event: AppEventV1): {
+    eventId: string;
+    dedupeKey: string;
+};
+/** Map the profile onto the existing @hasna/events envelope without another transport or store. */
+export declare function appEventV1ToEventInput<TData extends EventData>(event: AppEventV1<TData>): EventInput<TData>;
+/** Reconstruct a profile from an @hasna/events envelope produced by the adapter. */
+export declare function appEventV1FromEventEnvelope<TData extends EventData = EventData>(envelope: EventEnvelope<TData>): AppEventV1<TData>;

package/types/durable-spool.d.ts

@@ -0,0 +1,30 @@
+import type { EventEnvelope, EventInput } from "./types.js";
+export interface DurableEventSpoolOptions {
+    dataDir: string;
+}
+export interface DurableSpoolEnqueueResult<TData extends Record<string, unknown> = Record<string, unknown>> {
+    event: EventEnvelope<TData>;
+    stored: boolean;
+    deduped: boolean;
+}
+export interface DurableSpoolRecoveryOptions {
+    olderThanMs?: number;
+}
+export interface DurableSpoolRecoveryResult {
+    recovered: number;
+    deduped: number;
+    cleaned: number;
+}
+export declare class DurableEventSpool {
+    readonly dataDir: string;
+    readonly inboxDir: string;
+    constructor(options: DurableEventSpoolOptions);
+    enqueue<TData extends Record<string, unknown>>(input: EventInput<TData>): Promise<DurableSpoolEnqueueResult<TData>>;
+    recover(options?: DurableSpoolRecoveryOptions): Promise<DurableSpoolRecoveryResult>;
+    close(): Promise<void>;
+    private pathFor;
+    private assertSameIdentity;
+    private ensureInbox;
+    private syncInbox;
+    private syncDirectory;
+}

package/types/durable-worker.d.ts

@@ -0,0 +1,27 @@
+import { DurableEventsBroker, type DurableDrainResult, type DurableSpoolImportResult } from "./durable.js";
+export interface DurableWorkerOptions {
+    broker: DurableEventsBroker;
+    signal: AbortSignal;
+    workerId?: string;
+    limit?: number;
+    leaseMs?: number;
+    debounceMs?: number;
+    reconcileMs?: number;
+    watchRestartMs?: number;
+    onCycle?: (cycle: DurableWorkerCycle) => void | Promise<void>;
+}
+export interface DurableWorkerCycle {
+    imported: DurableSpoolImportResult;
+    drained: DurableDrainResult;
+}
+export interface DurableWorkerResult {
+    workerId: string;
+    cycles: number;
+    imported: number;
+    deduped: number;
+    delivered: number;
+    retried: number;
+    dead: number;
+    lost: number;
+}
+export declare function runDurableWorker(options: DurableWorkerOptions): Promise<DurableWorkerResult>;

package/types/durable.d.ts

@@ -0,0 +1,112 @@
+import { type TransportDispatchOptions } from "./transports.js";
+import type { ChannelConfig, DeliveryResult, EventEnvelope, EventInput } from "./types.js";
+export interface DurableEventsBrokerOptions extends TransportDispatchOptions {
+    dataDir: string;
+    databaseName?: string;
+    now?: () => Date;
+}
+export interface DurableEnqueueOptions {
+    dedupe?: boolean;
+}
+export interface DurableEnqueueResult<TData extends Record<string, unknown> = Record<string, unknown>> {
+    event: EventEnvelope<TData>;
+    deduped: boolean;
+    queued: number;
+}
+export interface DurableDrainOptions {
+    workerId?: string;
+    limit?: number;
+    leaseMs?: number;
+}
+export interface DurableDrainResult {
+    workerId: string;
+    claimed: number;
+    delivered: number;
+    retried: number;
+    dead: number;
+    lost: number;
+    deliveries: DeliveryResult[];
+}
+export interface DurableSpoolImportOptions {
+    limit?: number;
+}
+export interface DurableSpoolImportResult {
+    scanned: number;
+    imported: number;
+    deduped: number;
+    queued: number;
+}
+export interface DurableRetryDeadOptions {
+    eventId?: string;
+    channelId?: string;
+    limit?: number;
+}
+export interface DurableRetryDeadResult {
+    matched: number;
+    requeued: number;
+}
+export type DurableOutboxStatus = "pending" | "leased" | "delivered" | "dead";
+export interface DurableEventsStatus {
+    service: "events";
+    storage: "local-sqlite";
+    schemaVersion: number;
+    databasePath: string;
+    counts: {
+        channels: number;
+        enabledChannels: number;
+        events: number;
+        pending: number;
+        leased: number;
+        delivered: number;
+        dead: number;
+    };
+    safety: {
+        statusOmitsEventPayloads: true;
+        databasePersistsEventEnvelopes: true;
+        includesResolvedSecrets: false;
+        inlineWebhookSecretsAllowed: false;
+    };
+}
+export interface DurableDeliveryJob {
+    id: string;
+    event: EventEnvelope;
+    channel: ChannelConfig;
+    attempt: number;
+    workerId: string;
+}
+export interface DurableSettleResult {
+    status: "delivered" | "retry" | "dead" | "lost";
+    delivery?: DeliveryResult;
+}
+export declare function defaultWebhookSecretResolver(reference: string): string | undefined;
+export declare class DurableEventsBroker {
+    readonly dataDir: string;
+    readonly databasePath: string;
+    private readonly db;
+    private readonly now;
+    private readonly transportOptions;
+    constructor(options: DurableEventsBrokerOptions);
+    close(): void;
+    addChannel(input: Omit<ChannelConfig, "createdAt" | "updatedAt"> & Partial<Pick<ChannelConfig, "createdAt" | "updatedAt">>): ChannelConfig;
+    listChannels(): ChannelConfig[];
+    enqueue<TData extends Record<string, unknown>>(input: EventInput<TData>, options?: DurableEnqueueOptions): DurableEnqueueResult<TData>;
+    drain(options?: DurableDrainOptions): Promise<DurableDrainResult>;
+    importSpool(options?: DurableSpoolImportOptions): DurableSpoolImportResult;
+    retryDead(options?: DurableRetryDeadOptions): DurableRetryDeadResult;
+    status(): DurableEventsStatus;
+    nextWakeAt(): number | undefined;
+    private claim;
+    private settle;
+    private completeOutbox;
+    private findEvent;
+    private queueMatchingChannels;
+    private count;
+    private immediate;
+    private ensureSchema;
+    private createSchemaV1;
+    private assertSchemaV1;
+    private readSchemaVersion;
+    private applicationSchemaObjects;
+    private assertEmptyApplicationSchema;
+    private secureDatabaseFiles;
+}

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

@@ -8,6 +8,8 @@ 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;
@@ -58,7 +60,5 @@ export declare class EventsClient {
     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}/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;
 }