@flowcore/pathways 0.16.4 → 0.17.0

package/esm/pathways/cluster/postgres-coordinator.js

@@ -0,0 +1,117 @@
+import { PostgresJsAdapter } from "../postgres/index.js";
+/**
+ * PostgreSQL-backed implementation of PathwayCoordinator.
+ * Uses two tables:
+ * - `pathway_leases`: distributed locks for leader election
+ * - `pathway_instances`: instance registration and heartbeating
+ */
+export class PostgresPathwayCoordinator {
+    constructor(adapter, options) {
+        Object.defineProperty(this, "adapter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "initialized", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "leasesTable", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "instancesTable", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.adapter = adapter;
+        this.leasesTable = options?.leasesTable ?? "pathway_leases";
+        this.instancesTable = options?.instancesTable ?? "pathway_instances";
+    }
+    async ensureInitialized() {
+        if (this.initialized)
+            return;
+        await this.adapter.execute(`
+      CREATE TABLE IF NOT EXISTS ${this.leasesTable} (
+        key TEXT PRIMARY KEY,
+        instance_id TEXT NOT NULL,
+        expires_at TIMESTAMPTZ NOT NULL
+      )
+    `);
+        await this.adapter.execute(`
+      CREATE TABLE IF NOT EXISTS ${this.instancesTable} (
+        instance_id TEXT PRIMARY KEY,
+        address TEXT NOT NULL,
+        last_heartbeat TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `);
+        this.initialized = true;
+    }
+    async acquireLease(instanceId, key, ttlMs) {
+        await this.ensureInitialized();
+        const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+        // Try to insert or update if expired
+        const result = await this.adapter.query(`INSERT INTO ${this.leasesTable} (key, instance_id, expires_at)
+       VALUES ($1, $2, $3::timestamptz)
+       ON CONFLICT (key) DO UPDATE
+       SET instance_id = $2, expires_at = $3::timestamptz
+       WHERE ${this.leasesTable}.expires_at < NOW()
+          OR ${this.leasesTable}.instance_id = $2
+       RETURNING TRUE as acquired`, [key, instanceId, expiresAt]);
+        return Array.isArray(result) && result.length > 0;
+    }
+    async renewLease(instanceId, key, ttlMs) {
+        await this.ensureInitialized();
+        const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+        const result = await this.adapter.query(`UPDATE ${this.leasesTable}
+       SET expires_at = $1::timestamptz
+       WHERE key = $2 AND instance_id = $3
+       RETURNING TRUE as renewed`, [expiresAt, key, instanceId]);
+        return Array.isArray(result) && result.length > 0;
+    }
+    async releaseLease(instanceId, key) {
+        await this.ensureInitialized();
+        await this.adapter.execute(`DELETE FROM ${this.leasesTable} WHERE key = $1 AND instance_id = $2`, [key, instanceId]);
+    }
+    async register(instanceId, address) {
+        await this.ensureInitialized();
+        await this.adapter.execute(`INSERT INTO ${this.instancesTable} (instance_id, address, last_heartbeat)
+       VALUES ($1, $2, NOW())
+       ON CONFLICT (instance_id) DO UPDATE
+       SET address = $2, last_heartbeat = NOW()`, [instanceId, address]);
+    }
+    async heartbeat(instanceId) {
+        await this.ensureInitialized();
+        await this.adapter.execute(`UPDATE ${this.instancesTable} SET last_heartbeat = NOW() WHERE instance_id = $1`, [instanceId]);
+    }
+    async unregister(instanceId) {
+        await this.ensureInitialized();
+        await this.adapter.execute(`DELETE FROM ${this.instancesTable} WHERE instance_id = $1`, [instanceId]);
+    }
+    async getInstances(staleThresholdMs) {
+        await this.ensureInitialized();
+        const result = await this.adapter.query(`SELECT instance_id, address FROM ${this.instancesTable}
+       WHERE last_heartbeat > NOW() - INTERVAL '1 millisecond' * $1`, [staleThresholdMs]);
+        if (!Array.isArray(result))
+            return [];
+        return result.map((row) => ({
+            instanceId: row.instance_id,
+            address: row.address,
+        }));
+    }
+}
+/**
+ * Factory function to create a PostgresPathwayCoordinator
+ */
+export async function createPostgresPathwayCoordinator(config, options) {
+    const adapter = new PostgresJsAdapter(config);
+    await adapter.connect();
+    return new PostgresPathwayCoordinator(adapter, options);
+}

package/esm/pathways/cluster/types.d.ts

@@ -0,0 +1,99 @@
+import type { FlowcoreEvent } from "../../contracts/event.js";
+/**
+ * Coordinator interface for distributed cluster coordination
+ * Handles instance registration, heartbeating, and leader election via leases
+ */
+export interface PathwayCoordinator {
+    acquireLease(instanceId: string, key: string, ttlMs: number): Promise<boolean>;
+    renewLease(instanceId: string, key: string, ttlMs: number): Promise<boolean>;
+    releaseLease(instanceId: string, key: string): Promise<void>;
+    register(instanceId: string, address: string): Promise<void>;
+    heartbeat(instanceId: string): Promise<void>;
+    unregister(instanceId: string): Promise<void>;
+    getInstances(staleThresholdMs: number): Promise<Array<{
+        instanceId: string;
+        address: string;
+    }>>;
+}
+/**
+ * Options for starting a cluster
+ */
+export interface PathwayClusterOptions {
+    coordinator: PathwayCoordinator;
+    advertisedAddress: string;
+    port: number;
+    transport?: ClusterTransport;
+    workerConcurrency?: number;
+    leaseTtlMs?: number;
+    leaseRenewIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    staleThresholdMs?: number;
+    deliveryTimeoutMs?: number;
+}
+/**
+ * WebSocket protocol message types for cluster communication
+ */
+export type WsMessage = WsEventsMessage | WsAckMessage | WsFailMessage | WsPingMessage | WsPongMessage;
+export interface WsEventsMessage {
+    type: "events";
+    deliveryId: string;
+    events: FlowcoreEvent[];
+}
+export interface WsAckMessage {
+    type: "ack";
+    deliveryId: string;
+    eventIds: string[];
+}
+export interface WsFailMessage {
+    type: "fail";
+    deliveryId: string;
+    eventIds: string[];
+}
+export interface WsPingMessage {
+    type: "ping";
+}
+export interface WsPongMessage {
+    type: "pong";
+}
+/**
+ * Minimal WebSocket-like interface for cross-platform compatibility
+ */
+export interface ClusterSocket {
+    send(data: string): void;
+    close(): void;
+    readonly readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Transport abstraction for cluster WS server/client.
+ * Implement this interface for different runtimes (Deno, Node.js, etc.)
+ */
+export interface ClusterTransport {
+    /** Start a WS server on the given port. Call onConnection for each new socket. */
+    startServer(port: number, onConnection: (socket: ClusterSocket) => void): Promise<{
+        shutdown(): Promise<void>;
+    }>;
+    /** Connect to a remote WS address and return a socket. */
+    connect(address: string): ClusterSocket;
+}
+/**
+ * Cluster role for this instance
+ */
+export type ClusterRole = "leader" | "worker" | "unknown";
+/**
+ * Pending delivery tracking
+ */
+export interface PendingDelivery {
+    deliveryId: string;
+    events: FlowcoreEvent[];
+    workerAddress: string;
+    sentAt: number;
+    resolve: (eventIds: string[]) => void;
+    reject: (error: Error) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/pathways/cluster/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/pathways/cluster/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE7D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC9E,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5E,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;CAChG;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,kBAAkB,CAAA;IAC/B,iBAAiB,EAAE,MAAM,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,eAAe,GACf,YAAY,GACZ,aAAa,GACb,aAAa,GACb,aAAa,CAAA;AAEjB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,aAAa,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,IAAI,IAAI,CAAA;IACb,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACzC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACrD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAC5C,OAAO,CAAC;QAAE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAA;IAEzC,0DAA0D;IAC1D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACrC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CAC/B"}

package/esm/pathways/cluster/types.js

@@ -0,0 +1 @@
+export {};

package/esm/pathways/index.d.ts

@@ -12,11 +12,15 @@
  * @module
  */
 export * from "./builder.js";
+export * from "./cluster/index.js";
+export { PathwayProvisioner } from "./provisioner.js";
+export type { PathwayProvisionerOptions, ProvisionerRegistration } from "./provisioner.js";
 export * from "./constants.js";
 export * from "./internal-pathway.state.js";
 export * from "./kv/kv-adapter.js";
 export * from "./logger.js";
 export * from "./postgres/index.js";
+export * from "./pump/index.js";
 export * from "./session-pathway.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/pathways/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,YAAY,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAC1F,cAAc,gBAAgB,CAAA;AAC9B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA"}

package/esm/pathways/index.js

@@ -12,10 +12,13 @@
  * @module
  */
 export * from "./builder.js";
+export * from "./cluster/index.js";
+export { PathwayProvisioner } from "./provisioner.js";
 export * from "./constants.js";
 export * from "./internal-pathway.state.js";
 export * from "./kv/kv-adapter.js";
 export * from "./logger.js";
 export * from "./postgres/index.js";
+export * from "./pump/index.js";
 export * from "./session-pathway.js";
 export * from "./types.js";

package/esm/pathways/provisioner.d.ts

@@ -0,0 +1,57 @@
+import { FlowcoreClient } from "@flowcore/sdk";
+import type { Logger } from "./logger.js";
+/**
+ * Registration metadata for a single pathway, used by the provisioner
+ */
+export interface ProvisionerRegistration {
+    flowType: string;
+    eventType: string;
+    flowTypeDescription?: string;
+    eventTypeDescription?: string;
+}
+/**
+ * Options for creating a PathwayProvisioner
+ */
+export interface PathwayProvisionerOptions {
+    tenant: string;
+    dataCore: string;
+    apiKey: string;
+    dataCoreDescription?: string;
+    dataCoreAccessControl: string;
+    dataCoreDeleteProtection: boolean;
+    registrations: ProvisionerRegistration[];
+    logger?: Logger;
+    /** Override FlowcoreClient for testing */
+    clientFactory?: (apiKey: string) => FlowcoreClient;
+}
+/**
+ * Provisions Flowcore infrastructure (data core, flow types, event types).
+ * Creates missing resources when descriptions are provided, updates descriptions
+ * when they differ. Fails if a resource is missing and no description is provided.
+ * Additive only — never deletes.
+ */
+export declare class PathwayProvisioner {
+    private readonly tenant;
+    private readonly dataCore;
+    private readonly apiKey;
+    private readonly dataCoreDescription?;
+    private readonly dataCoreAccessControl;
+    private readonly dataCoreDeleteProtection;
+    private readonly registrations;
+    private readonly logger;
+    private readonly clientFactory;
+    constructor(options: PathwayProvisionerOptions);
+    /**
+     * Run the provisioning flow:
+     * 1. Fetch tenant → tenantId
+     * 2. Fetch or create data core
+     * 3. For each unique flow type: fetch or create
+     * 4. For each event type: fetch or create
+     * 5. Update descriptions where they differ
+     */
+    provision(): Promise<void>;
+    private provisionDataCore;
+    private provisionFlowTypes;
+    private provisionEventTypes;
+}
+//# sourceMappingURL=provisioner.d.ts.map

package/esm/pathways/provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../src/pathways/provisioner.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,cAAc,EAMf,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGzC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,wBAAwB,EAAE,OAAO,CAAA;IACjC,aAAa,EAAE,uBAAuB,EAAE,CAAA;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,CAAA;CACnD;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;gBAEtD,OAAO,EAAE,yBAAyB;IAY9C;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YAuBlB,iBAAiB;YAiDjB,kBAAkB;YAsDlB,mBAAmB;CAuDlC"}

package/esm/pathways/provisioner.js

@@ -0,0 +1,225 @@
+import { DataCoreCreateCommand, DataCoreFetchCommand, DataCoreUpdateCommand, EventTypeCreateCommand, EventTypeListCommand, EventTypeUpdateCommand, FlowcoreClient, FlowTypeCreateCommand, FlowTypeListCommand, FlowTypeUpdateCommand, NotFoundException, TenantFetchCommand, } from "@flowcore/sdk";
+import { NoopLogger } from "./logger.js";
+/**
+ * Provisions Flowcore infrastructure (data core, flow types, event types).
+ * Creates missing resources when descriptions are provided, updates descriptions
+ * when they differ. Fails if a resource is missing and no description is provided.
+ * Additive only — never deletes.
+ */
+export class PathwayProvisioner {
+    constructor(options) {
+        Object.defineProperty(this, "tenant", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCore", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "apiKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCoreDescription", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCoreAccessControl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCoreDeleteProtection", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "registrations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "logger", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "clientFactory", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.tenant = options.tenant;
+        this.dataCore = options.dataCore;
+        this.apiKey = options.apiKey;
+        this.dataCoreDescription = options.dataCoreDescription;
+        this.dataCoreAccessControl = options.dataCoreAccessControl;
+        this.dataCoreDeleteProtection = options.dataCoreDeleteProtection;
+        this.registrations = options.registrations;
+        this.logger = options.logger ?? new NoopLogger();
+        this.clientFactory = options.clientFactory ?? ((apiKey) => new FlowcoreClient({ apiKey }));
+    }
+    /**
+     * Run the provisioning flow:
+     * 1. Fetch tenant → tenantId
+     * 2. Fetch or create data core
+     * 3. For each unique flow type: fetch or create
+     * 4. For each event type: fetch or create
+     * 5. Update descriptions where they differ
+     */
+    async provision() {
+        const client = this.clientFactory(this.apiKey);
+        this.logger.info("Starting provisioning", { tenant: this.tenant, dataCore: this.dataCore });
+        // Step 1: Fetch tenant
+        const tenant = await client.execute(new TenantFetchCommand({ tenant: this.tenant }));
+        const tenantId = tenant.id;
+        this.logger.info("Tenant resolved", { tenantId });
+        // Step 2: Provision data core
+        const dataCoreId = await this.provisionDataCore(client, tenantId);
+        this.logger.info("Data core resolved", { dataCoreId });
+        // Step 3: Provision flow types
+        const flowTypeIds = await this.provisionFlowTypes(client, dataCoreId);
+        this.logger.info("Flow types resolved", { count: flowTypeIds.size });
+        // Step 4: Provision event types
+        await this.provisionEventTypes(client, flowTypeIds);
+        this.logger.info("Provisioning complete");
+    }
+    async provisionDataCore(client, tenantId) {
+        let dataCore = null;
+        try {
+            dataCore = await client.execute(new DataCoreFetchCommand({ tenant: this.tenant, dataCore: this.dataCore }));
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundException)) {
+                throw error;
+            }
+        }
+        if (dataCore) {
+            // Data core exists — update description if provided and changed
+            if (this.dataCoreDescription !== undefined && dataCore.description !== this.dataCoreDescription) {
+                this.logger.info("Updating data core description", {
+                    dataCoreId: dataCore.id,
+                    from: dataCore.description,
+                    to: this.dataCoreDescription,
+                });
+                await client.execute(new DataCoreUpdateCommand({ dataCoreId: dataCore.id, description: this.dataCoreDescription }));
+            }
+            return dataCore.id;
+        }
+        // Data core doesn't exist
+        if (this.dataCoreDescription === undefined) {
+            throw new Error(`Data core "${this.dataCore}" not found on tenant "${this.tenant}". ` +
+                `Provide dataCoreDescription in the PathwaysBuilder constructor to auto-create it.`);
+        }
+        this.logger.info("Creating data core", { name: this.dataCore });
+        const created = await client.execute(new DataCoreCreateCommand({
+            tenantId,
+            name: this.dataCore,
+            description: this.dataCoreDescription,
+            accessControl: this.dataCoreAccessControl,
+            deleteProtection: this.dataCoreDeleteProtection,
+        }));
+        return created.id;
+    }
+    async provisionFlowTypes(client, dataCoreId) {
+        // Collect unique flow types with their descriptions
+        const flowTypes = new Map();
+        for (const reg of this.registrations) {
+            // First registration with a description wins
+            if (!flowTypes.has(reg.flowType)) {
+                flowTypes.set(reg.flowType, reg.flowTypeDescription);
+            }
+            else if (reg.flowTypeDescription !== undefined && flowTypes.get(reg.flowType) === undefined) {
+                flowTypes.set(reg.flowType, reg.flowTypeDescription);
+            }
+        }
+        // Fetch existing flow types
+        const existing = await client.execute(new FlowTypeListCommand({ dataCoreId }));
+        const existingByName = new Map(existing.map((ft) => [ft.name, ft]));
+        const flowTypeIds = new Map();
+        for (const [name, description] of flowTypes) {
+            const existingFt = existingByName.get(name);
+            if (existingFt) {
+                flowTypeIds.set(name, existingFt.id);
+                // Update description if provided and changed
+                if (description !== undefined && existingFt.description !== description) {
+                    this.logger.info("Updating flow type description", {
+                        flowType: name,
+                        from: existingFt.description,
+                        to: description,
+                    });
+                    await client.execute(new FlowTypeUpdateCommand({ flowTypeId: existingFt.id, description }));
+                }
+            }
+            else if (description !== undefined) {
+                // Create flow type
+                this.logger.info("Creating flow type", { name, description });
+                const created = await client.execute(new FlowTypeCreateCommand({ dataCoreId, name, description }));
+                flowTypeIds.set(name, created.id);
+            }
+            else {
+                throw new Error(`Flow type "${name}" not found in data core. ` +
+                    `Provide flowTypeDescription in the register() call to auto-create it.`);
+            }
+        }
+        return flowTypeIds;
+    }
+    async provisionEventTypes(client, flowTypeIds) {
+        // Group registrations by flow type
+        const byFlowType = new Map();
+        for (const reg of this.registrations) {
+            const list = byFlowType.get(reg.flowType) ?? [];
+            list.push(reg);
+            byFlowType.set(reg.flowType, list);
+        }
+        for (const [flowTypeName, regs] of byFlowType) {
+            const flowTypeId = flowTypeIds.get(flowTypeName);
+            if (!flowTypeId)
+                continue;
+            // Fetch existing event types
+            const existing = await client.execute(new EventTypeListCommand({ flowTypeId }));
+            const existingByName = new Map(existing.map((et) => [et.name, et]));
+            for (const reg of regs) {
+                const existingEt = existingByName.get(reg.eventType);
+                if (existingEt) {
+                    // Update description if provided and changed
+                    if (reg.eventTypeDescription !== undefined && existingEt.description !== reg.eventTypeDescription) {
+                        this.logger.info("Updating event type description", {
+                            flowType: flowTypeName,
+                            eventType: reg.eventType,
+                            from: existingEt.description,
+                            to: reg.eventTypeDescription,
+                        });
+                        await client.execute(new EventTypeUpdateCommand({ eventTypeId: existingEt.id, description: reg.eventTypeDescription }));
+                    }
+                }
+                else if (reg.eventTypeDescription !== undefined) {
+                    // Create event type
+                    this.logger.info("Creating event type", {
+                        flowType: flowTypeName,
+                        eventType: reg.eventType,
+                        description: reg.eventTypeDescription,
+                    });
+                    await client.execute(new EventTypeCreateCommand({ flowTypeId, name: reg.eventType, description: reg.eventTypeDescription }));
+                }
+                else {
+                    throw new Error(`Event type "${reg.eventType}" not found in flow type "${flowTypeName}". ` +
+                        `Provide description in the register() call to auto-create it.`);
+                }
+            }
+        }
+    }
+}

package/esm/pathways/pump/index.d.ts

@@ -0,0 +1,4 @@
+export type { PathwayPumpOptions, PostgresPumpStateConfig, PumpNotifierConfig, PumpState, PumpStateManager, PumpStateManagerFactory, } from "./types.js";
+export { PathwayPump } from "./pathway-pump.js";
+export { createPostgresPumpStateManagerFactory } from "./state.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/pathways/pump/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pathways/pump/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAA"}

package/esm/pathways/pump/index.js

@@ -0,0 +1,2 @@
+export { PathwayPump } from "./pathway-pump.js";
+export { createPostgresPumpStateManagerFactory } from "./state.js";

package/esm/pathways/pump/pathway-pump.d.ts

@@ -0,0 +1,54 @@
+import type { FlowcoreEvent } from "../../contracts/event.js";
+import type { Logger } from "../logger.js";
+import type { PathwayPumpOptions } from "./types.js";
+/**
+ * Registered pathway info needed for pump grouping
+ */
+interface PathwayRegistration {
+    flowType: string;
+    eventType: string;
+}
+/**
+ * PathwayPump orchestrates data pump instances for auto-fetching events from Flowcore.
+ *
+ * Groups registered pathways by flowType and creates one FlowcoreDataPump per flowType group.
+ * Events are routed to PathwaysBuilder.process() for handling.
+ */
+export declare class PathwayPump {
+    private readonly stateManagerFactory;
+    private readonly notifier;
+    private readonly bufferSize;
+    private readonly maxRedeliveryCount;
+    private readonly logger;
+    private pumps;
+    private running;
+    private tenant;
+    private dataCore;
+    private apiKey;
+    private baseUrl;
+    private processEvent;
+    constructor(options: PathwayPumpOptions, logger?: Logger);
+    /**
+     * Configure the pump with pathway builder context
+     */
+    configure(config: {
+        tenant: string;
+        dataCore: string;
+        apiKey: string;
+        baseUrl: string;
+        processEvent: (pathway: string, event: FlowcoreEvent) => Promise<void>;
+    }): void;
+    /**
+     * Start pumps for the given pathway registrations.
+     * Groups by flowType and creates one pump per group.
+     */
+    start(pathways: PathwayRegistration[]): Promise<void>;
+    /**
+     * Stop all running pumps
+     */
+    stop(): Promise<void>;
+    get isRunning(): boolean;
+    private buildNotifierOptions;
+}
+export {};
+//# sourceMappingURL=pathway-pump.d.ts.map

package/esm/pathways/pump/pathway-pump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathway-pump.d.ts","sourceRoot":"","sources":["../../../src/pathways/pump/pathway-pump.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,YAAY,CAAA;AAEjG;;GAEG;AACH,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAKD;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyB;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,OAAO,CAAQ;IAGvB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAK;IAGpB,OAAO,CAAC,YAAY,CAA0E;gBAElF,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,MAAM;IAQxD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACvE,GAAG,IAAI;IAQR;;;OAGG;IACG,KAAK,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0E3D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB3B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAGD,OAAO,CAAC,oBAAoB;CAqB7B"}