@newhomestar/sdk 0.7.13 → 0.7.14

package/dist/events.d.ts

@@ -339,6 +339,70 @@ export declare function withInboundEvent(db: any, msg: InboundMessage, handler:
  * process.on('SIGTERM', () => consumer.abort());
  */
 export declare function startInboundConsumer(db: any, options: InboundConsumerOptions): AbortController;
+/** Options for startPollConsumer() — extends InboundConsumerOptions */
+export interface PollConsumerOptions extends InboundConsumerOptions {
+    /**
+     * Messages to request per poll (default: 5).
+     * All messages in the batch are processed sequentially before the next poll.
+     * At-least-once: messages not ACKed within `vt` seconds become visible again.
+     */
+    batch?: number;
+    /**
+     * Milliseconds to sleep between polls when the queue is empty (default: 2000).
+     * Prevents hot-polling against the Events Service.
+     */
+    idleDelayMs?: number;
+}
+/**
+ * Start a worker-pull consumer that polls POST /events/queue/poll, processes
+ * each message via withInboundEvent(), and ACKs on success.
+ *
+ * **This is the recommended pattern for DO App Platform** (and any platform that
+ * doesn't support long-lived SSE connections). Unlike startInboundConsumer (SSE),
+ * each poll is a short HTTP request — no persistent connections, no proxy timeouts.
+ *
+ * ## Loop flow (sequential, never overlaps):
+ *   1. POST /events/queue/poll → up to `batch` messages
+ *   2. For each message (in order):
+ *      a. withInboundEvent(db, msg, handler) → ACID tx + ACK
+ *      b. On failure: NACK → PGMQ re-delivers after VT expires
+ *   3. Sleep `idleDelayMs` if queue was empty, 100ms pause between batches
+ *   4. Repeat — next poll only fires after the current batch is fully processed
+ *
+ * ## ACID / at-least-once guarantee:
+ * Same as startInboundConsumer — withInboundEvent() wraps each message in a
+ * Prisma transaction (inbound_events INSERT + handler). If the handler fails,
+ * no ACK is sent — PGMQ re-delivers after VT. If ACK fails after a successful
+ * transaction, PGMQ re-delivers but the UNIQUE(msg_id) constraint prevents
+ * double-processing (duplicate is ACKed and skipped).
+ *
+ * ## Competing consumers:
+ * Multiple replicas can all call startPollConsumer() on the same queue.
+ * PGMQ's FOR UPDATE SKIP LOCKED ensures each replica gets different messages.
+ *
+ * @param db      - Prisma client (must have `inboundEvent` model)
+ * @param options - Consumer configuration
+ * @returns       - AbortController — call `.abort()` for graceful shutdown
+ *
+ * @example
+ * // Drop-in replacement for startInboundConsumer:
+ * const consumer = startPollConsumer(db, {
+ *   queueName:   'jira_queue',
+ *   batch:       5,      // process up to 5 messages per poll
+ *   vt:          60,     // 60s visibility timeout — must be > max handler time
+ *   idleDelayMs: 2000,   // sleep 2s when queue is empty
+ *   handlers: {
+ *     'nova_ticketing_service.ticket_created': async (tx, event) => {
+ *       await tx.jiraIssue.upsert({ ... });
+ *       return { status: 'processed' };
+ *     },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => consumer.abort());
+ */
+export declare function startPollConsumer(db: any, options: PollConsumerOptions): AbortController;
 /**
  * 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.

package/dist/events.js

@@ -883,6 +883,196 @@ export function startInboundConsumer(db, options) {
     });
     return abort;
 }
+/**
+ * Start a worker-pull consumer that polls POST /events/queue/poll, processes
+ * each message via withInboundEvent(), and ACKs on success.
+ *
+ * **This is the recommended pattern for DO App Platform** (and any platform that
+ * doesn't support long-lived SSE connections). Unlike startInboundConsumer (SSE),
+ * each poll is a short HTTP request — no persistent connections, no proxy timeouts.
+ *
+ * ## Loop flow (sequential, never overlaps):
+ *   1. POST /events/queue/poll → up to `batch` messages
+ *   2. For each message (in order):
+ *      a. withInboundEvent(db, msg, handler) → ACID tx + ACK
+ *      b. On failure: NACK → PGMQ re-delivers after VT expires
+ *   3. Sleep `idleDelayMs` if queue was empty, 100ms pause between batches
+ *   4. Repeat — next poll only fires after the current batch is fully processed
+ *
+ * ## ACID / at-least-once guarantee:
+ * Same as startInboundConsumer — withInboundEvent() wraps each message in a
+ * Prisma transaction (inbound_events INSERT + handler). If the handler fails,
+ * no ACK is sent — PGMQ re-delivers after VT. If ACK fails after a successful
+ * transaction, PGMQ re-delivers but the UNIQUE(msg_id) constraint prevents
+ * double-processing (duplicate is ACKed and skipped).
+ *
+ * ## Competing consumers:
+ * Multiple replicas can all call startPollConsumer() on the same queue.
+ * PGMQ's FOR UPDATE SKIP LOCKED ensures each replica gets different messages.
+ *
+ * @param db      - Prisma client (must have `inboundEvent` model)
+ * @param options - Consumer configuration
+ * @returns       - AbortController — call `.abort()` for graceful shutdown
+ *
+ * @example
+ * // Drop-in replacement for startInboundConsumer:
+ * const consumer = startPollConsumer(db, {
+ *   queueName:   'jira_queue',
+ *   batch:       5,      // process up to 5 messages per poll
+ *   vt:          60,     // 60s visibility timeout — must be > max handler time
+ *   idleDelayMs: 2000,   // sleep 2s when queue is empty
+ *   handlers: {
+ *     'nova_ticketing_service.ticket_created': async (tx, event) => {
+ *       await tx.jiraIssue.upsert({ ... });
+ *       return { status: 'processed' };
+ *     },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => consumer.abort());
+ */
+export function startPollConsumer(db, options) {
+    const { queueName, handlers, defaultHandler, vt = 30, batch = 5, idleDelayMs = 2_000, } = options;
+    const eventsUrl = options.eventsUrl ?? process.env.NOVA_EVENTS_SERVICE_URL;
+    const serviceToken = options.serviceToken ?? process.env.NOVA_SERVICE_TOKEN;
+    if (!eventsUrl || !serviceToken) {
+        console.error('[nova/events] startPollConsumer: NOVA_EVENTS_SERVICE_URL and NOVA_SERVICE_TOKEN ' +
+            'must be set. Poll consumer will NOT start.');
+        return new AbortController();
+    }
+    const abort = new AbortController();
+    /** Derive the event topic from a raw PGMQ message payload */
+    function _deriveEventType(payload) {
+        if (typeof payload.topic === 'string')
+            return payload.topic;
+        if (typeof payload.entity_type === 'string' && typeof payload.action === 'string') {
+            return `${payload.entity_type}.${payload.action}`;
+        }
+        return 'unknown.event';
+    }
+    /** Send a NACK to the events service to release the visibility timeout early */
+    async function _nack(msgId, readCt) {
+        try {
+            await fetch(`${eventsUrl}/events/queue/nack`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${serviceToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ queue: queueName, msg_id: msgId }),
+            });
+        }
+        catch (err) {
+            console.error(`[nova/events] NACK failed for msg_id=${msgId} read_ct=${readCt}:`, String(err).slice(0, 200));
+        }
+    }
+    /** Sleep for ms, returning early if the consumer is aborted */
+    function _sleep(ms) {
+        return new Promise((resolve) => {
+            const t = setTimeout(resolve, ms);
+            abort.signal.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+        });
+    }
+    /** Sequential poll loop — one batch at a time, never overlaps */
+    async function _pollLoop() {
+        const tokenSuffix = serviceToken ? `***${serviceToken.slice(-4)}` : 'MISSING';
+        console.log(`[nova/events] Poll consumer starting — url=${eventsUrl} ` +
+            `token=${tokenSuffix} queue=${queueName} vt=${vt}s batch=${batch} idleDelay=${idleDelayMs}ms`);
+        while (!abort.signal.aborted) {
+            let messages = [];
+            // ── 1. Poll for a batch of messages ────────────────────────────────────
+            try {
+                const res = await fetch(`${eventsUrl}/events/queue/poll`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${serviceToken}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({ queue: queueName, vt, batch }),
+                    signal: abort.signal,
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => '');
+                    console.error(`[nova/events] Poll failed for queue "${queueName}": HTTP ${res.status} — ${text.slice(0, 200)}`);
+                    await _sleep(idleDelayMs);
+                    continue;
+                }
+                const data = await res.json();
+                messages = data.messages ?? [];
+            }
+            catch (err) {
+                if (abort.signal.aborted)
+                    return;
+                const isAbortError = err?.name === 'AbortError' || err?.code === 20;
+                if (isAbortError)
+                    return;
+                console.error(`[nova/events] Poll network error for queue "${queueName}":`, String(err).slice(0, 500));
+                await _sleep(idleDelayMs);
+                continue;
+            }
+            // Queue empty — sleep before polling again
+            if (messages.length === 0) {
+                await _sleep(idleDelayMs);
+                continue;
+            }
+            // ── 2. Process each message sequentially ───────────────────────────────
+            // Processing is intentionally sequential (not concurrent) so that:
+            //   a) Messages for the same entity are handled in order
+            //   b) No poll fires until the current batch is fully processed
+            for (const raw of messages) {
+                if (abort.signal.aborted)
+                    return;
+                // DLQ-routed messages — already moved to DLQ by the server; just log
+                if (raw.event === 'dlq') {
+                    console.warn(`[nova/events] msg_id=${raw.msg_id} moved to DLQ "${raw.dlq_queue}" ` +
+                        `(read_ct=${raw.read_ct}) — skipping processing`);
+                    continue;
+                }
+                const payload = raw.message;
+                const eventType = _deriveEventType(payload);
+                const handler = handlers[eventType] ?? defaultHandler;
+                const msg = {
+                    msg_id: raw.msg_id,
+                    queue: queueName,
+                    payload,
+                    read_ct: raw.read_ct,
+                };
+                if (!handler) {
+                    // No handler registered and no default — ACK to unblock the queue
+                    console.log(`[nova/events] No handler for event type "${eventType}" (msg_id=${raw.msg_id}) — ACK and skip`);
+                    try {
+                        await fetch(`${eventsUrl}/events/queue/ack`, {
+                            method: 'POST',
+                            headers: { 'Authorization': `Bearer ${serviceToken}`, 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ queue: queueName, msg_id: raw.msg_id }),
+                        });
+                    }
+                    catch { /* best-effort */ }
+                    continue;
+                }
+                try {
+                    const outcome = await withInboundEvent(db, msg, handler);
+                    console.log(`[nova/events] msg_id=${raw.msg_id} event="${eventType}" status=${outcome.status} read_ct=${raw.read_ct}`);
+                }
+                catch (err) {
+                    console.error(`[nova/events] Handler failed for msg_id=${raw.msg_id} event="${eventType}" read_ct=${raw.read_ct}:`, err);
+                    // NACK — extends visibility timeout so PGMQ will re-deliver
+                    await _nack(raw.msg_id, raw.read_ct);
+                }
+            }
+            // Short pause between non-empty batches — breathing room for the
+            // Prisma connection pool before the next poll
+            await _sleep(100);
+        }
+        console.log(`[nova/events] Poll consumer for queue "${queueName}" shut down gracefully`);
+    }
+    // Start the poll loop (non-blocking — does not await)
+    _pollLoop().catch((err) => {
+        console.error(`[nova/events] startPollConsumer fatal error for queue "${queueName}":`, err);
+    });
+    return abort;
+}
 // ── NovaEventsClient ───────────────────────────────────────────────────────────
 /**
  * Class-based client when you need more control than the top-level functions.

package/dist/index.d.ts

@@ -293,8 +293,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 { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, startInboundConsumer, startPollConsumer, NovaEventsClient, } from './events.js';
+export type { QueueEventPayload, LogEventPayload, OutboxRelayOptions, ServiceEmitFn, InboundConsumerOptions, PollConsumerOptions, } from './events.js';
 export type { ZodTypeAny as SchemaAny, ZodTypeAny };
 export { parseNovaSpec } from "./parseSpec.js";
 export type { NovaSpec } from "./parseSpec.js";

package/dist/index.js

@@ -865,7 +865,7 @@ export function runDualMode(def, opts = {}) {
 /*──────────────── 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';
+export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, startInboundConsumer, startPollConsumer, NovaEventsClient, } from './events.js';
 // YAML spec parsing utility
 export { parseNovaSpec } from "./parseSpec.js";
 // Integration definition API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.13",
+  "version": "0.7.14",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {