@newhomestar/sdk 0.6.7 → 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;
+}