@newhomestar/sdk 0.6.8 → 0.6.9

package/dist/events.d.ts

@@ -0,0 +1,226 @@
+/** Full request body for POST /events/queue */
+export interface QueueEventPayload {
+    entity_type: string;
+    action: string;
+    /** Auto-stamped from NOVA_SERVICE_SLUG if not provided */
+    source_service?: string;
+    /** ISO 8601 — when the event actually happened (defaults to now()) */
+    occurred_at?: string;
+    /** UUID linking a chain of related events across services */
+    correlation_id?: string;
+    /** The event_id that directly caused this event */
+    causation_id?: string;
+    /**
+     * Deduplication key from the outbox row.
+     * Auto-set by withEventOutbox(). Prevents double-posting on retries.
+     */
+    idempotency_key?: string;
+    /** Payload schema version (default: 1) */
+    event_version?: number;
+    entity_id?: string;
+    integration_id?: string;
+    diff?: {
+        before: Record<string, unknown>;
+        after: Record<string, unknown>;
+        changed_fields: string[];
+    };
+    attributes?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    performed_by_id?: string;
+    affected_user_id?: string;
+}
+/** Request body for POST /events (audit-only, no fan-out) */
+export interface LogEventPayload extends QueueEventPayload {
+}
+/** Options for startOutboxRelay() */
+export interface OutboxRelayOptions {
+    /** How often to poll for undelivered outbox rows (default: 60_000ms) */
+    intervalMs?: number;
+    /** Rows with attempts >= maxAttempts are left for manual reconciliation (default: 5) */
+    maxAttempts?: number;
+    /** Events service URL — defaults to NOVA_EVENTS_SERVICE_URL env var */
+    eventsUrl?: string;
+    /** Service JWT — defaults to NOVA_SERVICE_TOKEN env var */
+    serviceToken?: string;
+}
+/**
+ * Returns `true` when a request originated from an integration sync or worker,
+ * indicated by the `x-source: integration_sync` header.
+ *
+ * **Producer side** — pass `req` to `withServiceEventOutbox()` and this check is
+ * done for you automatically. Use this helper directly only when you need
+ * conditional logic beyond event emission (e.g. skipping a side-effect).
+ *
+ * **Consumer side** — integration workers MUST check this before writing back to
+ * the source system to avoid infinite sync loops:
+ *
+ * @example
+ * // In a worker handler — don't write back to BambooHR if BambooHR caused the event
+ * if (isIntegrationSync(event)) return { status: 'skipped' };
+ * await ctx.fetch(`https://api.bamboohr.com/...`, { method: 'PUT', ... });
+ *
+ * @example
+ * // In a Next.js route handler (producer side) — pass req instead of calling this
+ * const employee = await withServiceEventOutbox(db, req, async (tx, emit) => { ... });
+ */
+export declare function isIntegrationSync(reqOrEvent: Request | Record<string, any>): boolean;
+/** Emit function passed to the withServiceEventOutbox callback */
+export type ServiceEmitFn = (topic: string, payload: Record<string, unknown>, idempotencyKey?: string) => void;
+/**
+ * Run a Prisma transaction that atomically writes business data + outbox rows,
+ * then immediately relays events to the Nova Events Service.
+ *
+ * This is the **preferred** high-level API for emitting events from service
+ * route handlers. It is source-aware: if the incoming request carries
+ * `x-source: integration_sync` or `x-integration-id: <slug>`, those values are
+ * automatically stamped on every event's `metadata` field. This lets downstream
+ * consumers self-filter to prevent sync loops without suppressing events for
+ * other subscribers.
+ *
+ * Events **always fan out** to all subscriber queues — no events are silently
+ * dropped. An integration worker that receives an event it caused should check
+ * `isIntegrationSync(event)` and skip processing if true.
+ *
+ * @param db               - Prisma client instance (must have `eventOutbox` model)
+ * @param reqOrCallback    - Either the inbound `Request` (for source tagging) OR
+ *                           the callback directly (if source context is not needed)
+ * @param maybeCallback    - The callback when `req` is provided as the second arg
+ *
+ * @example
+ * // Route handler — source metadata auto-stamped from request headers
+ * export async function POST(req: Request) {
+ *   const employee = await withServiceEventOutbox(db, req, async (tx, emit) => {
+ *     const row = await tx.hrisEmployee.create({ data });
+ *     emit('employee.created', { id: row.id, firstName: row.firstName });
+ *     return row;
+ *   });
+ *   return NextResponse.json(employee);
+ * }
+ *
+ * @example
+ * // Without a request (background job, scheduled task)
+ * const result = await withServiceEventOutbox(db, async (tx, emit) => {
+ *   const row = await tx.hrisEmployee.update({ where: { id }, data });
+ *   emit('employee.updated', { id, ...changes });
+ *   return row;
+ * });
+ */
+export declare function withServiceEventOutbox<R>(db: any, reqOrCallback: Request | ((tx: any, emit: ServiceEmitFn) => Promise<R>), maybeCallback?: (tx: any, emit: ServiceEmitFn) => Promise<R>): Promise<R>;
+/**
+ * Run a Prisma transaction that atomically writes business data + an outbox row,
+ * then immediately relays the event to the Nova Events Service.
+ *
+ * If the relay fails (network error or non-2xx), the outbox row is preserved and
+ * startOutboxRelay() will retry it with exponential backoff.
+ *
+ * @param db       - Prisma client instance (must have `eventOutbox` model)
+ * @param callback - Receives the transaction `tx`; must return `{ events, result }`
+ *
+ * @example
+ * const employee = await withEventOutbox(db, async (tx) => {
+ *   const row = await tx.hrisEmployee.update({ where: { id }, data: updates });
+ *   return {
+ *     events: [{
+ *       entity_type: 'employee',
+ *       action:      'updated',
+ *       entity_id:   id,
+ *       diff:        { before: old, after: mapRow(row), changed_fields },
+ *     }],
+ *     result: row,
+ *   };
+ * });
+ */
+export declare function withEventOutbox<R>(db: any, callback: (tx: any) => Promise<{
+    events: QueueEventPayload[];
+    result: R;
+}>): Promise<R>;
+/**
+ * POST /events — Record an event in the audit log WITHOUT queue fan-out.
+ *
+ * Use for:
+ *   • Inbound sync audits (metadata.source = "integration_sync")
+ *   • Read events ("employee.viewed")
+ *   • System events that don't need integration write-back
+ *
+ * For events that need downstream processing, use queueEvent() or withEventOutbox().
+ */
+export declare function logEvent(payload: LogEventPayload): Promise<{
+    event_id: string;
+    status: string;
+}>;
+/**
+ * POST /events/queue — Log an event AND fan-out to all active subscriber queues.
+ *
+ * Use when there is NO database transaction context (e.g. a scheduled job,
+ * a webhook handler that doesn't update its own DB first).
+ *
+ * When you have a DB transaction, prefer withEventOutbox() for atomicity.
+ *
+ * @throws if the events service returns non-2xx (no retry logic)
+ */
+export declare function queueEvent(payload: QueueEventPayload): Promise<{
+    event_id: string;
+    subscriber_count: number;
+    status: string;
+}>;
+/**
+ * Start a background interval that retries undelivered outbox rows.
+ *
+ * Call ONCE at service startup (e.g. in layout.tsx or the service entry point).
+ * Returns the interval handle so you can clear it in tests or graceful shutdown.
+ *
+ * Retry schedule (exponential backoff): 2^attempts * 5s
+ *   attempt 0 → 5s,  attempt 1 → 10s,  attempt 2 → 20s,
+ *   attempt 3 → 40s, attempt 4 → 80s
+ *
+ * Rows with attempts >= maxAttempts (default 5) are skipped and left for
+ * a manual reconciler — they won't be retried automatically.
+ *
+ * @param db      - Prisma client instance (must have `eventOutbox` model)
+ * @param options - Relay configuration
+ *
+ * @example
+ * // src/app/layout.tsx
+ * import { startOutboxRelay } from '@newhomestar/sdk/events';
+ * import { db } from '@/lib/db';
+ *
+ * startOutboxRelay(db);
+ */
+export declare function startOutboxRelay(db: any, options?: OutboxRelayOptions): ReturnType<typeof setInterval>;
+/**
+ * Class-based client when you need more control than the top-level functions.
+ * Useful when you want to pass configuration explicitly rather than relying on env vars.
+ *
+ * @example
+ * const client = new NovaEventsClient({ serviceSlug: 'my-service' });
+ * await client.queueEvent({ entity_type: 'employee', action: 'updated', ... });
+ * client.startOutboxRelay(db);
+ */
+export declare class NovaEventsClient {
+    private readonly eventsUrl;
+    private readonly serviceToken;
+    private readonly serviceSlug?;
+    constructor(options?: {
+        eventsUrl?: string;
+        serviceToken?: string;
+        serviceSlug?: string;
+    });
+    /** POST /events — audit log only */
+    logEvent(payload: LogEventPayload): Promise<{
+        event_id: string;
+        status: string;
+    }>;
+    /** POST /events/queue — log + fan-out to all subscriber queues */
+    queueEvent(payload: QueueEventPayload): Promise<{
+        event_id: string;
+        subscriber_count: number;
+        status: string;
+    }>;
+    /** Transactional outbox helper (use in services with a Prisma DB) */
+    withOutbox<R>(db: any, callback: (tx: any) => Promise<{
+        events: QueueEventPayload[];
+        result: R;
+    }>): Promise<R>;
+    /** Start the background outbox retry relay */
+    startOutboxRelay(db: any, options?: Omit<OutboxRelayOptions, 'eventsUrl' | 'serviceToken'>): NodeJS.Timeout;
+}

package/dist/events.js

@@ -0,0 +1,503 @@
+// @newhomestar/sdk/events — Transactional outbox + HTTP event client
+// =====================================================================
+// Producer-side helpers for emitting platform events safely.
+//
+// The central problem: a service can write to its DB successfully and
+// then fail to call POST /events/queue, leaving state changed but the
+// event missing. The transactional outbox solves this by writing data
+// + outbox row in ONE atomic transaction — they succeed or fail together.
+//
+// ─── Usage ───────────────────────────────────────────────────────────
+//
+//  Producer service (e.g. HRIS):
+//
+//  import { withEventOutbox, startOutboxRelay } from '@newhomestar/sdk/events';
+//
+//  // In a route handler — atomically writes data + emits event:
+//  const employee = await withEventOutbox(db, async (tx) => {
+//    const row = await tx.hrisEmployee.update({ where: { id }, data });
+//    return {
+//      events: [{ entity_type: 'employee', action: 'updated', entity_id: id, ... }],
+//      result: row,
+//    };
+//  });
+//
+//  // In layout.tsx — starts the retry loop for any failed relays:
+//  startOutboxRelay(db);
+//
+// ─── Required env vars ───────────────────────────────────────────────
+//  NOVA_EVENTS_SERVICE_URL  — URL of the nova-events-service
+//  NOVA_SERVICE_TOKEN       — JWT with scope to POST /events/queue
+//  NOVA_SERVICE_SLUG        — Stamped as source_service on every event
+// =====================================================================
+import dotenv from 'dotenv';
+// Load .env.local in dev if NOVA_EVENTS_SERVICE_URL not already set
+if (!process.env.NOVA_EVENTS_SERVICE_URL) {
+    dotenv.config({ path: '.env.local', override: false });
+}
+// ── Internal helpers ───────────────────────────────────────────────────────────
+function _getEnvOrThrow(key, context) {
+    const val = process.env[key];
+    if (!val)
+        throw new Error(`[${context}] ${key} env var is required but not set`);
+    return val;
+}
+/**
+ * Relay a single outbox row to the events service and update the outbox.
+ * Used by both withEventOutbox (immediate relay) and startOutboxRelay (retry loop).
+ */
+async function _relayRow(db, row, eventsUrl, serviceToken) {
+    let lastError = null;
+    try {
+        const body = {
+            ...row.payload,
+            idempotency_key: row.idempotencyKey,
+        };
+        const res = await fetch(`${eventsUrl}/events/queue`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${serviceToken}`,
+                'Content-Type': 'application/json',
+                'Idempotency-Key': row.idempotencyKey,
+            },
+            body: JSON.stringify(body),
+        });
+        if (res.ok) {
+            await db.eventOutbox.update({
+                where: { id: row.id },
+                data: { delivered: true, deliveredAt: new Date() },
+            });
+            return;
+        }
+        // Non-2xx: treat as transient failure, update error fields
+        const text = await res.text().catch(() => `HTTP ${res.status}`);
+        lastError = `HTTP ${res.status}: ${text}`.slice(0, 500);
+    }
+    catch (err) {
+        lastError = String(err).slice(0, 500);
+    }
+    // Relay failed — record the attempt
+    await db.eventOutbox.update({
+        where: { id: row.id },
+        data: {
+            attempts: { increment: 1 },
+            lastAttemptAt: new Date(),
+            lastError,
+        },
+    }).catch((updateErr) => {
+        console.error('[nova/events] Failed to update outbox row after relay failure:', updateErr);
+    });
+}
+// ── isIntegrationSync ─────────────────────────────────────────────────────────
+/**
+ * Returns `true` when a request originated from an integration sync or worker,
+ * indicated by the `x-source: integration_sync` header.
+ *
+ * **Producer side** — pass `req` to `withServiceEventOutbox()` and this check is
+ * done for you automatically. Use this helper directly only when you need
+ * conditional logic beyond event emission (e.g. skipping a side-effect).
+ *
+ * **Consumer side** — integration workers MUST check this before writing back to
+ * the source system to avoid infinite sync loops:
+ *
+ * @example
+ * // In a worker handler — don't write back to BambooHR if BambooHR caused the event
+ * if (isIntegrationSync(event)) return { status: 'skipped' };
+ * await ctx.fetch(`https://api.bamboohr.com/...`, { method: 'PUT', ... });
+ *
+ * @example
+ * // In a Next.js route handler (producer side) — pass req instead of calling this
+ * const employee = await withServiceEventOutbox(db, req, async (tx, emit) => { ... });
+ */
+export function isIntegrationSync(reqOrEvent) {
+    // Next.js / fetch Request object
+    if (typeof reqOrEvent.headers?.get === 'function') {
+        return reqOrEvent.headers.get('x-source') === 'integration_sync';
+    }
+    // Plain event/message object (consumer side: check metadata stamped at emit time)
+    const meta = reqOrEvent?.metadata;
+    return meta?.source === 'integration_sync';
+}
+/**
+ * Run a Prisma transaction that atomically writes business data + outbox rows,
+ * then immediately relays events to the Nova Events Service.
+ *
+ * This is the **preferred** high-level API for emitting events from service
+ * route handlers. It is source-aware: if the incoming request carries
+ * `x-source: integration_sync` or `x-integration-id: <slug>`, those values are
+ * automatically stamped on every event's `metadata` field. This lets downstream
+ * consumers self-filter to prevent sync loops without suppressing events for
+ * other subscribers.
+ *
+ * Events **always fan out** to all subscriber queues — no events are silently
+ * dropped. An integration worker that receives an event it caused should check
+ * `isIntegrationSync(event)` and skip processing if true.
+ *
+ * @param db               - Prisma client instance (must have `eventOutbox` model)
+ * @param reqOrCallback    - Either the inbound `Request` (for source tagging) OR
+ *                           the callback directly (if source context is not needed)
+ * @param maybeCallback    - The callback when `req` is provided as the second arg
+ *
+ * @example
+ * // Route handler — source metadata auto-stamped from request headers
+ * export async function POST(req: Request) {
+ *   const employee = await withServiceEventOutbox(db, req, async (tx, emit) => {
+ *     const row = await tx.hrisEmployee.create({ data });
+ *     emit('employee.created', { id: row.id, firstName: row.firstName });
+ *     return row;
+ *   });
+ *   return NextResponse.json(employee);
+ * }
+ *
+ * @example
+ * // Without a request (background job, scheduled task)
+ * const result = await withServiceEventOutbox(db, async (tx, emit) => {
+ *   const row = await tx.hrisEmployee.update({ where: { id }, data });
+ *   emit('employee.updated', { id, ...changes });
+ *   return row;
+ * });
+ */
+export async function withServiceEventOutbox(db, reqOrCallback, maybeCallback) {
+    // ── Resolve overloads ────────────────────────────────────────────────────
+    const req = typeof reqOrCallback !== 'function' ? reqOrCallback : undefined;
+    const callback = (typeof reqOrCallback === 'function' ? reqOrCallback : maybeCallback);
+    const eventsUrl = process.env.NOVA_EVENTS_SERVICE_URL;
+    const serviceToken = process.env.NOVA_SERVICE_TOKEN;
+    const serviceSlug = process.env.NOVA_SERVICE_SLUG;
+    if (!eventsUrl || !serviceToken) {
+        throw new Error('[withServiceEventOutbox] NOVA_EVENTS_SERVICE_URL and NOVA_SERVICE_TOKEN must be set. ' +
+            'Add them to your .env.local or deployment environment.');
+    }
+    // ── Extract source metadata from request headers ─────────────────────────
+    // x-source:         set by integration sync handlers (value: "integration_sync")
+    // x-integration-id: set by integration workers to identify the source system
+    const xSource = req?.headers?.get('x-source') ?? 'user';
+    const integrationId = req?.headers?.get('x-integration-id') ?? undefined;
+    const stagedEmits = [];
+    const outboxRows = [];
+    // ── Atomic: callback + outbox INSERTs in one transaction ─────────────────
+    const result = await db.$transaction(async (tx) => {
+        // The emit fn is synchronous — events are staged and written after callback returns
+        const emit = (topic, payload, idempotencyKey) => {
+            stagedEmits.push({ topic, payload, idempotencyKey });
+        };
+        const callbackResult = await callback(tx, emit);
+        // Write one outbox row per staged emit
+        for (const staged of stagedEmits) {
+            // ── Derive entity_type + action from topic string ──────────────────
+            // Supports dot notation   ("employee.created"  → entity_type=employee, action=created)
+            //           dotted path   ("hris.employee.created" → entity_type=hris.employee, action=created)
+            //           UPPER_SNAKE   ("EMPLOYEE_CREATED"  → entity_type=employee, action=created)
+            //           bare string   ("employee"          → entity_type=employee, action=event)
+            let entity_type;
+            let action;
+            if (staged.topic.includes('.')) {
+                const lastDot = staged.topic.lastIndexOf('.');
+                entity_type = staged.topic.slice(0, lastDot);
+                action = staged.topic.slice(lastDot + 1);
+            }
+            else if (staged.topic.includes('_')) {
+                const firstUnderscore = staged.topic.indexOf('_');
+                entity_type = staged.topic.slice(0, firstUnderscore).toLowerCase();
+                action = staged.topic.slice(firstUnderscore + 1).toLowerCase().replace(/_/g, '.');
+            }
+            else {
+                entity_type = staged.topic.toLowerCase();
+                action = 'event';
+            }
+            const fullPayload = {
+                entity_type,
+                action,
+                source_service: serviceSlug ?? undefined,
+                attributes: staged.payload,
+                metadata: {
+                    source: xSource,
+                    ...(integrationId ? { integration_id: integrationId } : {}),
+                },
+            };
+            const row = await tx.eventOutbox.create({
+                data: {
+                    eventType: staged.topic,
+                    payload: fullPayload,
+                    ...(staged.idempotencyKey
+                        ? { idempotencyKey: staged.idempotencyKey }
+                        : {}),
+                },
+                select: { id: true, idempotencyKey: true },
+            });
+            outboxRows.push({
+                id: row.id,
+                idempotencyKey: row.idempotencyKey,
+                payload: fullPayload,
+            });
+        }
+        return callbackResult;
+    });
+    // ── Immediate relay: best-effort POST after commit ────────────────────────
+    await Promise.allSettled(outboxRows.map(row => _relayRow(db, row, eventsUrl, serviceToken)));
+    return result;
+}
+// ── withEventOutbox ────────────────────────────────────────────────────────────
+/**
+ * Run a Prisma transaction that atomically writes business data + an outbox row,
+ * then immediately relays the event to the Nova Events Service.
+ *
+ * If the relay fails (network error or non-2xx), the outbox row is preserved and
+ * startOutboxRelay() will retry it with exponential backoff.
+ *
+ * @param db       - Prisma client instance (must have `eventOutbox` model)
+ * @param callback - Receives the transaction `tx`; must return `{ events, result }`
+ *
+ * @example
+ * const employee = await withEventOutbox(db, async (tx) => {
+ *   const row = await tx.hrisEmployee.update({ where: { id }, data: updates });
+ *   return {
+ *     events: [{
+ *       entity_type: 'employee',
+ *       action:      'updated',
+ *       entity_id:   id,
+ *       diff:        { before: old, after: mapRow(row), changed_fields },
+ *     }],
+ *     result: row,
+ *   };
+ * });
+ */
+export async function withEventOutbox(db, callback) {
+    const eventsUrl = process.env.NOVA_EVENTS_SERVICE_URL;
+    const serviceToken = process.env.NOVA_SERVICE_TOKEN;
+    const serviceSlug = process.env.NOVA_SERVICE_SLUG;
+    if (!eventsUrl || !serviceToken) {
+        throw new Error('[withEventOutbox] NOVA_EVENTS_SERVICE_URL and NOVA_SERVICE_TOKEN must be set. ' +
+            'Add them to your .env.local or deployment environment.');
+    }
+    // Rows inserted in the transaction — relayed after commit
+    const outboxRows = [];
+    // ── Atomic: business write + outbox INSERT in one transaction ──────────────
+    const result = await db.$transaction(async (tx) => {
+        const { events, result: callbackResult } = await callback(tx);
+        for (const event of events) {
+            const fullPayload = {
+                ...event,
+                source_service: event.source_service ?? serviceSlug ?? undefined,
+            };
+            const row = await tx.eventOutbox.create({
+                data: {
+                    eventType: `${event.entity_type}.${event.action}`,
+                    payload: fullPayload,
+                },
+                select: { id: true, idempotencyKey: true },
+            });
+            outboxRows.push({
+                id: row.id,
+                idempotencyKey: row.idempotencyKey,
+                payload: fullPayload,
+            });
+        }
+        return callbackResult;
+    });
+    // ── Immediate relay: best-effort POST after commit ─────────────────────────
+    // Failures are recorded in the outbox and retried by startOutboxRelay().
+    // We fire all relays concurrently (most calls have a single event anyway).
+    await Promise.allSettled(outboxRows.map(row => _relayRow(db, row, eventsUrl, serviceToken)));
+    return result;
+}
+// ── logEvent ───────────────────────────────────────────────────────────────────
+/**
+ * POST /events — Record an event in the audit log WITHOUT queue fan-out.
+ *
+ * Use for:
+ *   • Inbound sync audits (metadata.source = "integration_sync")
+ *   • Read events ("employee.viewed")
+ *   • System events that don't need integration write-back
+ *
+ * For events that need downstream processing, use queueEvent() or withEventOutbox().
+ */
+export async function logEvent(payload) {
+    const eventsUrl = _getEnvOrThrow('NOVA_EVENTS_SERVICE_URL', 'logEvent');
+    const serviceToken = _getEnvOrThrow('NOVA_SERVICE_TOKEN', 'logEvent');
+    const serviceSlug = process.env.NOVA_SERVICE_SLUG;
+    const res = await fetch(`${eventsUrl}/events`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${serviceToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            ...payload,
+            source_service: payload.source_service ?? serviceSlug,
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`[logEvent] HTTP ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ── queueEvent ─────────────────────────────────────────────────────────────────
+/**
+ * POST /events/queue — Log an event AND fan-out to all active subscriber queues.
+ *
+ * Use when there is NO database transaction context (e.g. a scheduled job,
+ * a webhook handler that doesn't update its own DB first).
+ *
+ * When you have a DB transaction, prefer withEventOutbox() for atomicity.
+ *
+ * @throws if the events service returns non-2xx (no retry logic)
+ */
+export async function queueEvent(payload) {
+    const eventsUrl = _getEnvOrThrow('NOVA_EVENTS_SERVICE_URL', 'queueEvent');
+    const serviceToken = _getEnvOrThrow('NOVA_SERVICE_TOKEN', 'queueEvent');
+    const serviceSlug = process.env.NOVA_SERVICE_SLUG;
+    const res = await fetch(`${eventsUrl}/events/queue`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${serviceToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            ...payload,
+            source_service: payload.source_service ?? serviceSlug,
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`[queueEvent] HTTP ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ── startOutboxRelay ───────────────────────────────────────────────────────────
+/**
+ * Start a background interval that retries undelivered outbox rows.
+ *
+ * Call ONCE at service startup (e.g. in layout.tsx or the service entry point).
+ * Returns the interval handle so you can clear it in tests or graceful shutdown.
+ *
+ * Retry schedule (exponential backoff): 2^attempts * 5s
+ *   attempt 0 → 5s,  attempt 1 → 10s,  attempt 2 → 20s,
+ *   attempt 3 → 40s, attempt 4 → 80s
+ *
+ * Rows with attempts >= maxAttempts (default 5) are skipped and left for
+ * a manual reconciler — they won't be retried automatically.
+ *
+ * @param db      - Prisma client instance (must have `eventOutbox` model)
+ * @param options - Relay configuration
+ *
+ * @example
+ * // src/app/layout.tsx
+ * import { startOutboxRelay } from '@newhomestar/sdk/events';
+ * import { db } from '@/lib/db';
+ *
+ * startOutboxRelay(db);
+ */
+export function startOutboxRelay(db, options = {}) {
+    const { intervalMs = 60_000, maxAttempts = 5, eventsUrl = process.env.NOVA_EVENTS_SERVICE_URL, serviceToken = process.env.NOVA_SERVICE_TOKEN, } = options;
+    if (!eventsUrl || !serviceToken) {
+        console.warn('[nova/events] startOutboxRelay: NOVA_EVENTS_SERVICE_URL or NOVA_SERVICE_TOKEN not set — ' +
+            'outbox relay is DISABLED. Set these env vars to enable automatic retry.');
+        // Return a no-op interval that never fires
+        return setInterval(() => { }, 2_147_483_647);
+    }
+    console.log(`[nova/events] Outbox relay started (interval: ${intervalMs}ms, maxAttempts: ${maxAttempts})`);
+    const handle = setInterval(async () => {
+        try {
+            const now = new Date();
+            // Find undelivered rows where the backoff window has elapsed.
+            // The query fetches rows where last_attempt_at is old enough for the
+            // minimum backoff (5s for attempt 0). The per-row check below applies
+            // the precise 2^attempts * 5 calculation to skip rows still in cooldown.
+            const undelivered = await db.eventOutbox.findMany({
+                where: {
+                    delivered: false,
+                    attempts: { lt: maxAttempts },
+                    OR: [
+                        { lastAttemptAt: null },
+                        { lastAttemptAt: { lt: new Date(now.getTime() - 5_000) } },
+                    ],
+                },
+                orderBy: [{ attempts: 'asc' }, { createdAt: 'asc' }],
+                take: 50,
+            });
+            for (const row of undelivered) {
+                // Precise per-row backoff gate: skip if cooldown hasn't elapsed
+                if (row.lastAttemptAt != null) {
+                    const backoffMs = Math.pow(2, row.attempts) * 5_000;
+                    if (now.getTime() - row.lastAttemptAt.getTime() < backoffMs) {
+                        continue;
+                    }
+                }
+                await _relayRow(db, row, eventsUrl, serviceToken);
+            }
+            // Cleanup: delete delivered rows older than 7 days (keep audit trail brief)
+            await db.eventOutbox.deleteMany({
+                where: {
+                    delivered: true,
+                    deliveredAt: { lt: new Date(now.getTime() - 7 * 24 * 60 * 60 * 1_000) },
+                },
+            });
+        }
+        catch (err) {
+            console.error('[nova/events] Outbox relay cycle error:', err);
+        }
+    }, intervalMs);
+    return handle;
+}
+// ── NovaEventsClient ───────────────────────────────────────────────────────────
+/**
+ * Class-based client when you need more control than the top-level functions.
+ * Useful when you want to pass configuration explicitly rather than relying on env vars.
+ *
+ * @example
+ * const client = new NovaEventsClient({ serviceSlug: 'my-service' });
+ * await client.queueEvent({ entity_type: 'employee', action: 'updated', ... });
+ * client.startOutboxRelay(db);
+ */
+export class NovaEventsClient {
+    eventsUrl;
+    serviceToken;
+    serviceSlug;
+    constructor(options) {
+        this.eventsUrl = options?.eventsUrl ?? process.env.NOVA_EVENTS_SERVICE_URL ?? '';
+        this.serviceToken = options?.serviceToken ?? process.env.NOVA_SERVICE_TOKEN ?? '';
+        this.serviceSlug = options?.serviceSlug ?? process.env.NOVA_SERVICE_SLUG;
+    }
+    /** POST /events — audit log only */
+    async logEvent(payload) {
+        return logEvent({ ...payload, source_service: payload.source_service ?? this.serviceSlug });
+    }
+    /** POST /events/queue — log + fan-out to all subscriber queues */
+    async queueEvent(payload) {
+        return queueEvent({ ...payload, source_service: payload.source_service ?? this.serviceSlug });
+    }
+    /** Transactional outbox helper (use in services with a Prisma DB) */
+    async withOutbox(db, callback) {
+        // Temporarily override env for the helpers
+        const original = {
+            eventsUrl: process.env.NOVA_EVENTS_SERVICE_URL,
+            serviceToken: process.env.NOVA_SERVICE_TOKEN,
+            serviceSlug: process.env.NOVA_SERVICE_SLUG,
+        };
+        process.env.NOVA_EVENTS_SERVICE_URL = this.eventsUrl;
+        process.env.NOVA_SERVICE_TOKEN = this.serviceToken;
+        if (this.serviceSlug)
+            process.env.NOVA_SERVICE_SLUG = this.serviceSlug;
+        try {
+            return await withEventOutbox(db, callback);
+        }
+        finally {
+            if (original.eventsUrl !== undefined)
+                process.env.NOVA_EVENTS_SERVICE_URL = original.eventsUrl;
+            if (original.serviceToken !== undefined)
+                process.env.NOVA_SERVICE_TOKEN = original.serviceToken;
+            if (original.serviceSlug !== undefined)
+                process.env.NOVA_SERVICE_SLUG = original.serviceSlug;
+        }
+    }
+    /** Start the background outbox retry relay */
+    startOutboxRelay(db, options) {
+        return startOutboxRelay(db, {
+            ...options,
+            eventsUrl: this.eventsUrl,
+            serviceToken: this.serviceToken,
+        });
+    }
+}

package/dist/index.d.ts

@@ -75,6 +75,20 @@ export interface JWTPayload {
 export interface ActionCtx {
     jobId: string;
     progress: (percent: number, meta?: unknown) => void;
+    /**
+     * Number of times this message has been delivered/retried.
+     * Populated in SSE worker mode; undefined in HTTP server mode.
+     * Use for alerting when read_ct is high (approaching DLQ threshold).
+     */
+    read_ct?: number;
+    /**
+     * Extend the message visibility lease for long-running handlers.
+     * Call periodically to prevent the message from re-appearing in the queue
+     * before processing is complete. SSE worker mode only.
+     *
+     * @param extend_by - Seconds to extend the lease (default: 30)
+     */
+    heartbeat?: (extend_by?: number) => Promise<void>;
     /** Raw HTTP headers from the inbound request (HTTP mode only) */
     headers?: Record<string, string | string[] | undefined>;
     /** Bearer token extracted from the Authorization header (HTTP mode only) */
@@ -231,6 +245,8 @@ export declare function runHttpServer<T extends WorkerDef>(def: T, opts?: HttpSe
 export declare function runDualMode<T extends WorkerDef>(def: T, opts?: {
     port?: number;
 }): void;
+export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, NovaEventsClient, } from './events.js';
+export type { QueueEventPayload, LogEventPayload, OutboxRelayOptions, ServiceEmitFn, } from './events.js';
 export type { ZodTypeAny as SchemaAny, ZodTypeAny };
 export { parseNovaSpec } from "./parseSpec.js";
 export type { NovaSpec } from "./parseSpec.js";
@@ -268,5 +284,25 @@ export type StreamCapability = {
     consumerGroup?: string;
 };
 export type Capability = WebhookCapability | ScheduledCapability | QueueCapability | StreamCapability;
+/**
+ * Event trigger — subscribes the worker to one or more Nova event topics.
+ * Topics are matched against `message.topic` / `message.event_type` in SSE frames.
+ */
+export type EventTrigger = {
+    type: 'event';
+    /** Nova event topic strings (e.g. "hris.employee.created") */
+    events: string[];
+};
+/**
+ * Schedule trigger — runs the worker on a cron schedule.
+ */
+export type ScheduleTrigger = {
+    type: 'schedule';
+    cron: string;
+    timezone?: string;
+    description?: string;
+};
+/** Union of all trigger variants */
+export type Trigger = EventTrigger | ScheduleTrigger;
 export { createPlatformClient, resolveCredentials, resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch, emitPlatformEvent, IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
 export type { ResolvedCredentials, IntegrationConfig, AuthMode, } from "./credentials.js";

package/dist/index.js

@@ -141,7 +141,46 @@ function buildTopicActionMap(def) {
     }
     return topicMap;
 }
+/**
+ * Build a topic → actionDef map from the new `triggers` API (and legacy `capabilities`).
+ * Used by runWorkerSSE() to route incoming SSE messages to the correct handler.
+ */
+function buildTriggerMap(def) {
+    const map = new Map();
+    for (const [, actionDef] of Object.entries(def.actions)) {
+        // New: triggers API (preferred)
+        const triggers = actionDef.triggers;
+        if (triggers) {
+            for (const trigger of triggers) {
+                if (trigger.type === 'event' && Array.isArray(trigger.events)) {
+                    for (const topic of trigger.events) {
+                        map.set(topic, actionDef);
+                    }
+                }
+            }
+        }
+        // Legacy: capabilities API (backward compat)
+        if (actionDef.capabilities) {
+            for (const cap of actionDef.capabilities) {
+                if (cap.type === 'queue' && cap.topics) {
+                    for (const topic of cap.topics) {
+                        if (!map.has(topic))
+                            map.set(topic, actionDef); // triggers take precedence
+                    }
+                }
+            }
+        }
+    }
+    return map;
+}
 export async function runWorker(def) {
+    // ── SSE mode (preferred): NOVA_EVENTS_SERVICE_URL + NOVA_SERVICE_TOKEN ─────
+    // When these env vars are set the worker connects via SSE to the events service.
+    // No Supabase connection is required on the worker side.
+    if (process.env.NOVA_EVENTS_SERVICE_URL) {
+        return runWorkerSSE(def);
+    }
+    // ── Legacy mode: RUNTIME_SUPABASE_* + pgmq_public RPC ────────────────────
     if (!runtime)
         throw new Error("RUNTIME_SUPABASE_* env vars not configured");
     // Build topic-to-action mapping for capability-based routing
@@ -277,6 +316,177 @@ async function nack(id, q) {
     await runtime.schema("pgmq_public").rpc("nack", { queue_name: q, message_id: id });
 }
 function delay(ms) { return new Promise(r => setTimeout(r, ms)); }
+/*──────────────── SSE Worker Mode ───────────────*/
+const _EVENTS_BASE = () => (process.env.NOVA_EVENTS_SERVICE_URL ?? '').replace(/\/$/, '');
+const _EVENTS_TOKEN = () => process.env.NOVA_SERVICE_TOKEN ?? '';
+async function _ackSSE(queue, msgId) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/ack`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId }),
+    });
+    if (!res.ok)
+        console.error(`[nova] ack failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function _nackSSE(queue, msgId, readCt) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/nack`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId, read_ct: readCt }),
+    });
+    if (!res.ok)
+        console.error(`[nova] nack failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function _heartbeatSSE(queue, msgId, extendBy = 30) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/heartbeat`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId, extend_by: extendBy }),
+    });
+    if (!res.ok)
+        console.error(`[nova] heartbeat failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function runWorkerSSE(def) {
+    const baseUrl = _EVENTS_BASE();
+    const token = _EVENTS_TOKEN();
+    if (!baseUrl)
+        throw new Error('[nova] NOVA_EVENTS_SERVICE_URL is required for SSE worker mode');
+    if (!token)
+        throw new Error('[nova] NOVA_SERVICE_TOKEN is required for SSE worker mode');
+    // ── Ensure the worker's queue exists before connecting ──────────────────
+    const ensureRes = await fetch(`${baseUrl}/events/queue/ensure`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ queue: def.queue }),
+    });
+    if (!ensureRes.ok) {
+        throw new Error(`[nova] Failed to ensure queue '${def.queue}': ${await ensureRes.text()}`);
+    }
+    console.log(`[nova] ✅ Queue '${def.queue}' ready`);
+    const triggerMap = buildTriggerMap(def);
+    console.log(`[nova] SSE worker '${def.name}' → ${baseUrl}/events/queue/stream?queue=${def.queue}`);
+    console.log(`[nova] Trigger map:`, Object.fromEntries(triggerMap));
+    let reconnectDelay = 1_000; // start 1 s, double up to 30 s
+    // ── Outer reconnect loop ─────────────────────────────────────────────────
+    while (true) {
+        try {
+            const streamRes = await fetch(`${baseUrl}/events/queue/stream?queue=${encodeURIComponent(def.queue)}`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!streamRes.ok || !streamRes.body) {
+                const errText = await streamRes.text().catch(() => '');
+                console.error(`[nova] SSE HTTP ${streamRes.status}: ${errText}`);
+                await delay(reconnectDelay);
+                reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+                continue;
+            }
+            // Successful connection — reset backoff
+            reconnectDelay = 1_000;
+            console.log(`[nova] 📡 SSE stream connected`);
+            // ── Stream reader ──────────────────────────────────────────────────
+            const reader = streamRes.body.getReader();
+            const decoder = new TextDecoder();
+            let buf = '';
+            let currentEvent = null;
+            let currentData = null;
+            readLoop: while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    console.warn(`[nova] SSE stream closed — will reconnect`);
+                    break readLoop;
+                }
+                buf += decoder.decode(value, { stream: true });
+                const lines = buf.split('\n');
+                buf = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (line.startsWith('event:')) {
+                        currentEvent = line.slice(6).trim();
+                    }
+                    else if (line.startsWith('data:')) {
+                        currentData = line.slice(5).trim();
+                    }
+                    else if (line === '') {
+                        // ── End of SSE frame ────────────────────────────────────────
+                        if (currentData) {
+                            try {
+                                const frame = JSON.parse(currentData);
+                                // Server-side DLQ event — already moved; just log
+                                if (currentEvent === 'dlq') {
+                                    console.warn(`[nova] ⚠️  Message ${frame.msg_id} moved to DLQ (read_ct=${frame.read_ct})`);
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                // Keepalive heartbeat — ignore
+                                if (frame.type === 'keepalive') {
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                // ── Normal message ─────────────────────────────────────
+                                const { msg_id, read_ct, message } = frame;
+                                const topic = message?.topic ?? message?.event_type ?? message?.type ?? '';
+                                const actionDef = triggerMap.get(topic);
+                                if (!actionDef) {
+                                    console.error(`[nova] ❌ No handler for topic '${topic}' — nacking (available: ${[...triggerMap.keys()].join(', ')})`);
+                                    await _nackSSE(def.queue, msg_id, read_ct ?? 0);
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                console.log(`[nova] 🚀 topic='${topic}' msg_id=${msg_id} read_ct=${read_ct}`);
+                                // ── Invoke handler ─────────────────────────────────────
+                                try {
+                                    const rawPayload = message?.payload ?? message;
+                                    const parsedInput = actionDef.input.parse(rawPayload);
+                                    const credCtx = buildCredentialCtx(def.name);
+                                    const ctx = {
+                                        jobId: `sse-${msg_id}`,
+                                        read_ct: read_ct ?? 0,
+                                        progress: (percent, meta) => {
+                                            console.log(`[nova] progress ${percent}%`, meta ?? '');
+                                        },
+                                        heartbeat: (extendBy = 30) => _heartbeatSSE(def.queue, msg_id, extendBy),
+                                        ...credCtx,
+                                    };
+                                    const result = await actionDef.handler(parsedInput, ctx);
+                                    actionDef.output.parse(result);
+                                    await _ackSSE(def.queue, msg_id);
+                                    console.log(`[nova] ✅ ack msg_id=${msg_id}`);
+                                }
+                                catch (handlerErr) {
+                                    console.error(`[nova] ❌ handler error msg_id=${msg_id}:`, handlerErr);
+                                    await _nackSSE(def.queue, msg_id, read_ct ?? 0);
+                                }
+                            }
+                            catch (parseErr) {
+                                console.error(`[nova] Failed to parse SSE frame:`, parseErr);
+                            }
+                        }
+                        currentEvent = null;
+                        currentData = null;
+                    }
+                }
+            }
+        }
+        catch (connErr) {
+            console.error(`[nova] SSE connection error:`, connErr);
+        }
+        console.log(`[nova] Reconnecting in ${reconnectDelay}ms…`);
+        await delay(reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+    }
+}
 /*──────────────── NEW: OpenAPI Spec Generation ───────────────*/
 export async function generateOpenAPISpec(def) {
     // This would use oRPC's built-in OpenAPI generation
@@ -610,6 +820,10 @@ export function runDualMode(def, opts = {}) {
         console.log(`💡 Worker running in HTTP-only mode. Set RUNTIME_SUPABASE_URL and RUNTIME_SUPABASE_SERVICE_ROLE_KEY to enable event processing`);
     }
 }
+/*──────────────── Event Outbox (re-exports for convenience) ───────────────*/
+// Full API is also available via '@newhomestar/sdk/events' subpath.
+// These re-exports allow import { withServiceEventOutbox } from '@newhomestar/sdk'.
+export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, NovaEventsClient, } from './events.js';
 // YAML spec parsing utility
 export { parseNovaSpec } from "./parseSpec.js";
 // Integration definition API

package/dist/integrationSpec.d.ts

@@ -90,7 +90,7 @@ export declare const IntegrationSpecSchema: z.ZodObject<{
                 streamName: z.ZodString;
                 eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 consumerGroup: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>]>>>;
+            }, z.core.$strip>], "type">>>;
         }, z.core.$strip>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"webhook">;
@@ -122,7 +122,7 @@ export declare const IntegrationSpecSchema: z.ZodObject<{
             streamName: z.ZodString;
             eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             consumerGroup: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>>>;
+        }, z.core.$strip>], "type">>>;
         schemas: z.ZodOptional<z.ZodArray<z.ZodObject<{
             slug: z.ZodString;
             name: z.ZodString;

package/dist/parseSpec.d.ts

@@ -73,7 +73,7 @@ export declare const NovaSpecSchema: z.ZodObject<{
                 streamName: z.ZodString;
                 eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 consumerGroup: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>]>>>;
+            }, z.core.$strip>], "type">>>;
         }, z.core.$strip>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"webhook">;
@@ -105,7 +105,7 @@ export declare const NovaSpecSchema: z.ZodObject<{
             streamName: z.ZodString;
             eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             consumerGroup: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>>>;
+        }, z.core.$strip>], "type">>>;
     }, z.core.$strip>;
     build: z.ZodOptional<z.ZodObject<{
         dockerfile: z.ZodString;

package/dist/workerSchema.d.ts

@@ -83,6 +83,15 @@ export declare const WorkerDefSchema: z.ZodObject<{
             resourceIdKey: z.ZodOptional<z.ZodString>;
             policy: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        triggers: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"event">;
+            events: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"schedule">;
+            cron: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"webhook">;
             eventTypes: z.ZodArray<z.ZodString>;

package/dist/workerSchema.js

@@ -61,7 +61,24 @@ export const WorkerDefSchema = z.object({
             resourceIdKey: z.string().optional(),
             policy: z.string().optional(),
         }).optional(),
-        // NEW: Capabilities array for event subscriptions and external triggers
+        // NEW: Trigger-based routing (preferred over capabilities for SSE-based workers)
+        // Use triggers to declaratively map event topics and cron schedules to this action.
+        // `nova workers push` / `nova integrations push` reads these to register
+        // event_subscriptions and ensure PGMQ queues exist.
+        triggers: z.array(z.union([
+            z.object({
+                type: z.literal('event'),
+                events: z.array(z.string()), // e.g. ['employee.updated', 'employee.created']
+            }),
+            z.object({
+                type: z.literal('schedule'),
+                cron: z.string(), // standard 5-field cron e.g. '0 8 * * *'
+                timezone: z.string().optional(),
+                description: z.string().optional(),
+            }),
+        ])).optional(),
+        // LEGACY: Capabilities array — still supported for backward compatibility.
+        // New code should use `triggers` instead.
         capabilities: z.array(z.union([
             z.object({
                 type: z.literal('webhook'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {
@@ -23,6 +23,10 @@
     "./next": {
       "import": "./dist/next.js",
       "types": "./dist/next.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
     }
   },
   "files": [
@@ -40,11 +44,14 @@
     "dotenv": "^16.4.3",
     "express": "^4.18.2",
     "express-oauth2-jwt-bearer": "^1.7.4",
-    "yaml": "^2.7.1",
-    "zod": "^4.0.5"
+    "yaml": "^2.7.1"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.17",
-    "typescript": "^5.4.4"
+    "typescript": "^5.4.4",
+    "zod": "^4.3.0"
   }
 }