@sguild/dispatcher 2.0.0 → 2.0.1

package/dist/events.d.ts

@@ -0,0 +1,63 @@
+import type { Prisma } from "@prisma/client";
+export type DispatcherEventWindow = "30m" | "6h" | "24h" | "7d";
+export type DispatcherDeliveryState = "published" | "delivered" | "resolved" | "dead-lettered";
+export type DispatcherEventCursor = {
+    inserted_at: string;
+    seq: string;
+    producer: string;
+};
+export type DispatcherEventSummary = {
+    producer: string;
+    event_id: string;
+    seq: string;
+    event_type: string;
+    schema_version: number;
+    tenant_id: string;
+    subject: string | null;
+    actor: string;
+    occurred_at: string;
+    inserted_at: string;
+    correlation_id: string | null;
+    causation_id: string | null;
+    delivery_state: DispatcherDeliveryState;
+    dedup_consumers: string[];
+    active_dead_letter_count: number;
+    resolved_dead_letter_count: number;
+};
+export type DispatcherDeadLetterEvidence = {
+    dead_letter_id: string;
+    consumer: string;
+    attempt_count: number;
+    last_error: string;
+    created_at: string;
+    resolved_at: string | null;
+};
+export type DispatcherEventDetail = DispatcherEventSummary & {
+    payload: Prisma.JsonValue;
+    metadata: Prisma.JsonValue | null;
+    dead_letters: DispatcherDeadLetterEvidence[];
+};
+export type ListDispatcherEventsFilter = {
+    window?: DispatcherEventWindow;
+    producer?: string;
+    eventType?: string;
+    tenantId?: string;
+    subject?: string;
+    q?: string;
+    limit?: number;
+    cursor?: string;
+    now?: Date;
+};
+export type ListDispatcherEventsResult = {
+    events: DispatcherEventSummary[];
+    next_cursor: string | null;
+    has_more: boolean;
+};
+export type GetDispatcherEventOptions = {
+    producer?: string;
+};
+export declare const DISPATCHER_EVENT_WINDOWS: DispatcherEventWindow[];
+export declare function knownEventTypes(): string[];
+export declare function parseDispatcherEventWindow(value: string | null | undefined): DispatcherEventWindow;
+export declare function listDispatcherEvents(filter?: ListDispatcherEventsFilter): Promise<ListDispatcherEventsResult>;
+export declare function getDispatcherEvent(eventId: string, options?: GetDispatcherEventOptions): Promise<DispatcherEventDetail | null>;

package/dist/events.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPATCHER_EVENT_WINDOWS = void 0;
+exports.knownEventTypes = knownEventTypes;
+exports.parseDispatcherEventWindow = parseDispatcherEventWindow;
+exports.listDispatcherEvents = listDispatcherEvents;
+exports.getDispatcherEvent = getDispatcherEvent;
+const producer_db_1 = require("./producer-db");
+const registry_1 = require("./registry");
+const dlq_1 = require("./dlq");
+exports.DISPATCHER_EVENT_WINDOWS = [
+    "30m",
+    "6h",
+    "24h",
+    "7d",
+];
+const WINDOW_MS = {
+    "30m": 30 * 60 * 1000,
+    "6h": 6 * 60 * 60 * 1000,
+    "24h": 24 * 60 * 60 * 1000,
+    "7d": 7 * 24 * 60 * 60 * 1000,
+};
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 500;
+function knownEventTypes() {
+    return Object.keys((0, registry_1.loadRegistry)().events).sort();
+}
+function parseDispatcherEventWindow(value) {
+    if (!value)
+        return "30m";
+    if (exports.DISPATCHER_EVENT_WINDOWS.includes(value)) {
+        return value;
+    }
+    throw new Error(`Unsupported dispatcher event window '${value}'`);
+}
+async function listDispatcherEvents(filter = {}) {
+    const window = filter.window ?? "30m";
+    const now = filter.now ?? new Date();
+    const since = new Date(now.getTime() - WINDOW_MS[window]);
+    const limit = normalizeLimit(filter.limit);
+    const producers = filter.producer ? [filter.producer] : knownEventProducers();
+    const aggregateRead = !filter.producer;
+    const cursor = decodeCursor(filter.cursor);
+    const merged = [];
+    for (const producer of producers) {
+        const db = (0, producer_db_1.getProducerDb)(producer);
+        if (!db) {
+            if (filter.producer)
+                throw new dlq_1.ProducerDbNotConfiguredError(producer);
+            continue;
+        }
+        const tablePrefix = db.schema ? `"${db.schema}".` : "";
+        const whereClauses = ["inserted_at >= $1"];
+        const params = [since];
+        if (filter.eventType?.trim()) {
+            params.push(filter.eventType.trim());
+            whereClauses.push(`event_type = $${params.length}`);
+        }
+        if (filter.tenantId?.trim()) {
+            params.push(filter.tenantId.trim());
+            whereClauses.push(`tenant_id = $${params.length}`);
+        }
+        if (filter.subject?.trim()) {
+            params.push(filter.subject.trim());
+            whereClauses.push(`subject = $${params.length}`);
+        }
+        if (filter.q?.trim()) {
+            params.push(`%${filter.q.trim()}%`);
+            const qParam = `$${params.length}`;
+            whereClauses.push(`(id ILIKE ${qParam} OR event_type ILIKE ${qParam} OR producer ILIKE ${qParam} OR tenant_id ILIKE ${qParam} OR subject ILIKE ${qParam} OR actor ILIKE ${qParam} OR correlation_id ILIKE ${qParam} OR causation_id ILIKE ${qParam})`);
+        }
+        if (cursor) {
+            params.push(cursor.inserted_at, cursor.seq, producer, cursor.producer);
+            const insertedParam = `$${params.length - 3}`;
+            const seqParam = `$${params.length - 2}`;
+            const producerParam = `$${params.length - 1}`;
+            const cursorProducerParam = `$${params.length}`;
+            whereClauses.push(`(inserted_at < ${insertedParam} OR (inserted_at = ${insertedParam} AND (seq < ${seqParam}::bigint OR (seq = ${seqParam}::bigint AND ${producerParam} > ${cursorProducerParam}))))`);
+        }
+        params.push(limit + 1);
+        const sql = `SELECT id, seq, event_type, schema_version, tenant_id,
+                        producer, subject, actor, occurred_at, inserted_at,
+                        correlation_id, causation_id
+                 FROM ${tablePrefix}dispatcher_event
+                 WHERE ${whereClauses.join(" AND ")}
+                 ORDER BY inserted_at DESC, seq DESC
+                 LIMIT $${params.length}`;
+        let rows;
+        try {
+            const result = await db.pool.query(sql, params);
+            rows = result.rows;
+        }
+        catch (e) {
+            if (!aggregateRead)
+                throw e;
+            console.warn(`[dispatcher.events] producer ${producer} excluded from aggregate read: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        const evidence = await deliveryEvidenceForEvents(producer, tablePrefix, rows.map((row) => String(row.id)));
+        for (const row of rows) {
+            merged.push(toEventSummary(producer, row, evidence.get(String(row.id))));
+        }
+    }
+    merged.sort(compareEventsDesc);
+    const page = merged.slice(0, limit);
+    const hasMore = merged.length > limit;
+    const last = page[page.length - 1];
+    return {
+        events: page,
+        next_cursor: hasMore && last ? encodeCursor(last) : null,
+        has_more: hasMore,
+    };
+}
+async function getDispatcherEvent(eventId, options = {}) {
+    if (!eventId)
+        return null;
+    const producers = options.producer ? [options.producer] : knownEventProducers();
+    const aggregateRead = !options.producer;
+    for (const producer of producers) {
+        const db = (0, producer_db_1.getProducerDb)(producer);
+        if (!db) {
+            if (options.producer)
+                throw new dlq_1.ProducerDbNotConfiguredError(producer);
+            continue;
+        }
+        const tablePrefix = db.schema ? `"${db.schema}".` : "";
+        const sql = `SELECT id, seq, event_type, schema_version, tenant_id,
+                        producer, subject, actor, occurred_at, inserted_at,
+                        payload, metadata, correlation_id, causation_id
+                 FROM ${tablePrefix}dispatcher_event
+                 WHERE id = $1
+                 LIMIT 1`;
+        let rows;
+        try {
+            const result = await db.pool.query(sql, [eventId]);
+            rows = result.rows;
+        }
+        catch (e) {
+            if (!aggregateRead)
+                throw e;
+            console.warn(`[dispatcher.events] producer ${producer} excluded from aggregate detail read: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        const row = rows[0];
+        if (!row)
+            continue;
+        const evidence = await deliveryEvidenceForEvents(producer, tablePrefix, [eventId]);
+        const summary = toEventSummary(producer, row, evidence.get(eventId));
+        const deadLetters = await deadLettersForEvent(producer, tablePrefix, eventId);
+        return {
+            ...summary,
+            payload: row.payload ?? null,
+            metadata: row.metadata ?? null,
+            dead_letters: deadLetters,
+        };
+    }
+    return null;
+}
+function knownEventProducers() {
+    const manifest = (0, registry_1.loadRegistry)();
+    const set = new Set();
+    for (const entry of Object.values(manifest.events)) {
+        set.add(entry.producer);
+    }
+    return Array.from(set);
+}
+async function deliveryEvidenceForEvents(producer, tablePrefix, eventIds) {
+    const map = new Map();
+    if (eventIds.length === 0)
+        return map;
+    const db = (0, producer_db_1.getProducerDb)(producer);
+    if (!db)
+        return map;
+    const dedupResult = await db.pool.query(`SELECT event_id, array_agg(consumer ORDER BY consumer) AS consumers
+     FROM ${tablePrefix}dispatcher_dedup
+     WHERE event_id = ANY($1::text[])
+     GROUP BY event_id`, [eventIds]);
+    for (const row of dedupResult.rows) {
+        map.set(row.event_id, {
+            dedup_consumers: row.consumers ?? [],
+            active_dead_letter_count: 0,
+            resolved_dead_letter_count: 0,
+        });
+    }
+    const dlqResult = await db.pool.query(`SELECT event_id,
+            COUNT(*) FILTER (WHERE resolved_at IS NULL) AS active_count,
+            COUNT(*) FILTER (WHERE resolved_at IS NOT NULL) AS resolved_count
+     FROM ${tablePrefix}dispatcher_dead_letter
+     WHERE event_id = ANY($1::text[])
+     GROUP BY event_id`, [eventIds]);
+    for (const row of dlqResult.rows) {
+        const current = map.get(row.event_id) ?? {
+            dedup_consumers: [],
+            active_dead_letter_count: 0,
+            resolved_dead_letter_count: 0,
+        };
+        current.active_dead_letter_count = Number(row.active_count);
+        current.resolved_dead_letter_count = Number(row.resolved_count);
+        map.set(row.event_id, current);
+    }
+    return map;
+}
+async function deadLettersForEvent(producer, tablePrefix, eventId) {
+    const db = (0, producer_db_1.getProducerDb)(producer);
+    if (!db)
+        return [];
+    const result = await db.pool.query(`SELECT id, consumer, attempt_count, last_error, created_at, resolved_at
+     FROM ${tablePrefix}dispatcher_dead_letter
+     WHERE event_id = $1
+     ORDER BY created_at DESC`, [eventId]);
+    return result.rows.map((row) => ({
+        dead_letter_id: row.id,
+        consumer: row.consumer,
+        attempt_count: Number(row.attempt_count),
+        last_error: row.last_error,
+        created_at: toIso(row.created_at),
+        resolved_at: row.resolved_at ? toIso(row.resolved_at) : null,
+    }));
+}
+function toEventSummary(fallbackProducer, row, evidence) {
+    const dedupConsumers = evidence?.dedup_consumers ?? [];
+    const activeDeadLetterCount = evidence?.active_dead_letter_count ?? 0;
+    const resolvedDeadLetterCount = evidence?.resolved_dead_letter_count ?? 0;
+    return {
+        producer: row.producer || fallbackProducer,
+        event_id: row.id,
+        seq: String(row.seq),
+        event_type: row.event_type,
+        schema_version: Number(row.schema_version),
+        tenant_id: row.tenant_id,
+        subject: row.subject ?? null,
+        actor: row.actor,
+        occurred_at: toIso(row.occurred_at),
+        inserted_at: toIso(row.inserted_at),
+        correlation_id: row.correlation_id ?? null,
+        causation_id: row.causation_id ?? null,
+        delivery_state: deliveryState(dedupConsumers, activeDeadLetterCount, resolvedDeadLetterCount),
+        dedup_consumers: dedupConsumers,
+        active_dead_letter_count: activeDeadLetterCount,
+        resolved_dead_letter_count: resolvedDeadLetterCount,
+    };
+}
+function deliveryState(dedupConsumers, activeDeadLetterCount, resolvedDeadLetterCount) {
+    if (activeDeadLetterCount > 0)
+        return "dead-lettered";
+    if (resolvedDeadLetterCount > 0)
+        return "resolved";
+    if (dedupConsumers.length > 0)
+        return "delivered";
+    return "published";
+}
+function compareEventsDesc(a, b) {
+    const inserted = b.inserted_at.localeCompare(a.inserted_at);
+    if (inserted !== 0)
+        return inserted;
+    const seq = BigInt(b.seq) > BigInt(a.seq) ? 1 : BigInt(b.seq) < BigInt(a.seq) ? -1 : 0;
+    if (seq !== 0)
+        return seq;
+    return a.producer.localeCompare(b.producer);
+}
+function normalizeLimit(limit) {
+    if (limit === undefined)
+        return DEFAULT_LIST_LIMIT;
+    return Math.min(limit, MAX_LIST_LIMIT);
+}
+function encodeCursor(event) {
+    const cursor = {
+        inserted_at: event.inserted_at,
+        seq: event.seq,
+        producer: event.producer,
+    };
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeCursor(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        if (!parsed.inserted_at || !parsed.seq || !parsed.producer)
+            return null;
+        return {
+            inserted_at: parsed.inserted_at,
+            seq: parsed.seq,
+            producer: parsed.producer,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export type { ConsumerLoopOptions } from "./postgres-consumer";
 export { EnvelopeValidationError, PayloadValidationError, PayloadSchemaUnavailableError, } from "./validator";
 export { DeadLetterAlreadyResolvedError, DeadLetterNotFoundError, ProducerDbNotConfiguredError, ReplayConsumerUnknownError, ReplayDeliveryFailedError, getDeadLetter, knownProducers, listDeadLetters, replayDeadLetter, resolveDeadLetter, } from "./dlq";
 export type { DeadLetter, GetDeadLetterOptions, ListDeadLettersFilter, ReplayDeadLetterInput, ReplayDeadLetterOutcome, ResolveDeadLetterInput, } from "./dlq";
+export { DISPATCHER_EVENT_WINDOWS, getDispatcherEvent, knownEventTypes, listDispatcherEvents, parseDispatcherEventWindow, } from "./events";
+export type { DispatcherDeadLetterEvidence, DispatcherDeliveryState, DispatcherEventDetail, DispatcherEventSummary, DispatcherEventWindow, GetDispatcherEventOptions, ListDispatcherEventsFilter, ListDispatcherEventsResult, } from "./events";
 export { configureDispatcherObservability, resetDispatcherObservabilityForTests, } from "./observability";
 export type { DispatcherHistogramName, DispatcherMetricLabels, DispatcherMetricName, DispatcherObservabilityHooks, } from "./observability";
 export type { ActorRef, CanonicalEntityId, EventEmit, EventEnvelope, LiveProducerDomain, ProducerDomain, PublishResult, SubscribeHandler, } from "./types";

package/dist/index.js

@@ -19,7 +19,7 @@
  * (Slice 3b) and the per-consumer DLQ read API (Slice 5) remain.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebhookDispatchError = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.SIGNATURE_HEADER = exports.EVENT_TYPE_HEADER = exports.EVENT_ID_HEADER = exports.verifyInboxRequest = exports.tryInsertOrDetectConflict = exports.loadRegistry = exports.getEventTypeRegistration = exports.getActiveSchemaVersion = exports.resetDispatcherObservabilityForTests = exports.configureDispatcherObservability = exports.resolveDeadLetter = exports.replayDeadLetter = exports.listDeadLetters = exports.knownProducers = exports.getDeadLetter = exports.ReplayDeliveryFailedError = exports.ReplayConsumerUnknownError = exports.ProducerDbNotConfiguredError = exports.DeadLetterNotFoundError = exports.DeadLetterAlreadyResolvedError = exports.PayloadSchemaUnavailableError = exports.PayloadValidationError = exports.EnvelopeValidationError = exports.configureDispatcher = exports.UnregisteredSchemaVersionError = exports.UnregisteredEventTypeError = exports.DispatcherNotImplementedError = exports.dispatcher = void 0;
+exports.WebhookDispatchError = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.SIGNATURE_HEADER = exports.EVENT_TYPE_HEADER = exports.EVENT_ID_HEADER = exports.verifyInboxRequest = exports.tryInsertOrDetectConflict = exports.loadRegistry = exports.getEventTypeRegistration = exports.getActiveSchemaVersion = exports.resetDispatcherObservabilityForTests = exports.configureDispatcherObservability = exports.parseDispatcherEventWindow = exports.listDispatcherEvents = exports.knownEventTypes = exports.getDispatcherEvent = exports.DISPATCHER_EVENT_WINDOWS = exports.resolveDeadLetter = exports.replayDeadLetter = exports.listDeadLetters = exports.knownProducers = exports.getDeadLetter = exports.ReplayDeliveryFailedError = exports.ReplayConsumerUnknownError = exports.ProducerDbNotConfiguredError = exports.DeadLetterNotFoundError = exports.DeadLetterAlreadyResolvedError = exports.PayloadSchemaUnavailableError = exports.PayloadValidationError = exports.EnvelopeValidationError = exports.configureDispatcher = exports.UnregisteredSchemaVersionError = exports.UnregisteredEventTypeError = exports.DispatcherNotImplementedError = exports.dispatcher = void 0;
 var dispatcher_1 = require("./dispatcher");
 Object.defineProperty(exports, "dispatcher", { enumerable: true, get: function () { return dispatcher_1.dispatcher; } });
 var dispatcher_2 = require("./dispatcher");
@@ -43,6 +43,12 @@ Object.defineProperty(exports, "knownProducers", { enumerable: true, get: functi
 Object.defineProperty(exports, "listDeadLetters", { enumerable: true, get: function () { return dlq_1.listDeadLetters; } });
 Object.defineProperty(exports, "replayDeadLetter", { enumerable: true, get: function () { return dlq_1.replayDeadLetter; } });
 Object.defineProperty(exports, "resolveDeadLetter", { enumerable: true, get: function () { return dlq_1.resolveDeadLetter; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "DISPATCHER_EVENT_WINDOWS", { enumerable: true, get: function () { return events_1.DISPATCHER_EVENT_WINDOWS; } });
+Object.defineProperty(exports, "getDispatcherEvent", { enumerable: true, get: function () { return events_1.getDispatcherEvent; } });
+Object.defineProperty(exports, "knownEventTypes", { enumerable: true, get: function () { return events_1.knownEventTypes; } });
+Object.defineProperty(exports, "listDispatcherEvents", { enumerable: true, get: function () { return events_1.listDispatcherEvents; } });
+Object.defineProperty(exports, "parseDispatcherEventWindow", { enumerable: true, get: function () { return events_1.parseDispatcherEventWindow; } });
 var observability_1 = require("./observability");
 Object.defineProperty(exports, "configureDispatcherObservability", { enumerable: true, get: function () { return observability_1.configureDispatcherObservability; } });
 Object.defineProperty(exports, "resetDispatcherObservabilityForTests", { enumerable: true, get: function () { return observability_1.resetDispatcherObservabilityForTests; } });

package/dist/postgres-consumer.js

@@ -257,7 +257,8 @@ class ConsumerLoop {
         try {
             await client.query("BEGIN");
             await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_dedup (consumer, event_id)
-         VALUES ($1, $2)`, [this.options.consumer, eventId]);
+         VALUES ($1, $2)
+         ON CONFLICT (consumer, event_id) DO NOTHING`, [this.options.consumer, eventId]);
             await client.query(`INSERT INTO ${this.tablePrefix}dispatcher_cursor (consumer, event_type, last_seq, updated_at)
          VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
          ON CONFLICT (consumer, event_type)

package/dist/validator.js

@@ -132,6 +132,7 @@ function validatePayload(eventType, schemaVersion, payload) {
 function __resetValidatorCachesForTests() {
     cachedEnvelopeValidator = null;
     payloadValidatorCache.clear();
+    ajv.removeSchema();
 }
 // =============================================================================
 // Internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sguild/dispatcher",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Cross-domain event dispatcher SDK for Sguild domains, per the Sguild Event Envelope contract and ADR-0009. Producer-side transactional emit, consumer-side polling worker with dedup/retry/dead-letter, envelope and payload validation against the bundled contracts tree.",
   "license": "UNLICENSED",
   "repository": {