@hotmeshio/hotmesh 0.22.1 → 0.22.2

package/build/services/escalations/client.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EscalationClientService = void 0;
+const enums_1 = require("../../modules/enums");
+const utils_1 = require("../../modules/utils");
+const hotmesh_1 = require("../hotmesh");
+const types_1 = require("../../types");
+const factory_1 = require("../durable/schemas/factory");
+/**
+ * Standalone client for the `public.hmsh_escalations` signal-pause surface.
+ *
+ * Requires NO dependency on `services/durable/`. Any HotMesh consumer — AI
+ * agent, YAML DAG worker, REST API — can interact with the escalation queue
+ * directly with just a Postgres connection.
+ *
+ * Signal delivery (for `resolve()` / `resolveByMetadata()`) uses HotMesh's
+ * `engine.signal()` internally. The engine is initialised lazily on first use
+ * and cached for the lifetime of the process.
+ *
+ * @example
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Claim the next available approval for the 'manager' role
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager'],
+ * });
+ *
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+class EscalationClientService {
+    constructor(config = {}) {
+        if (config.getHotMeshClient) {
+            // Reuse a caller-supplied engine factory (e.g. Durable.Client) — no extra connections.
+            this._engine = config.getHotMeshClient;
+        }
+        else if (config.connection) {
+            this._connection = config.connection;
+            this._engine = this._makeEngineFactory(config.connection);
+        }
+        else {
+            throw new Error('EscalationClient requires either `connection` or `getHotMeshClient`');
+        }
+    }
+    _makeEngineFactory(connection) {
+        return async (topic, namespace) => {
+            const optionsHash = this._hashConnection(connection);
+            const targetNS = namespace ?? factory_1.APP_ID;
+            const key = `esc:${optionsHash}.${targetNS}`;
+            if (EscalationClientService.instances.has(key)) {
+                return await EscalationClientService.instances.get(key);
+            }
+            const pending = hotmesh_1.HotMesh.init({
+                appId: targetNS,
+                taskQueue: topic ?? undefined,
+                logLevel: enums_1.HMSH_LOGLEVEL,
+                engine: { connection },
+            });
+            EscalationClientService.instances.set(key, pending);
+            return await pending;
+        };
+    }
+    _hashConnection(connection) {
+        if ('options' in connection) {
+            return (0, utils_1.hashOptions)(connection.options);
+        }
+        const parts = [];
+        for (const p in connection) {
+            if (connection[p]?.options) {
+                parts.push((0, utils_1.hashOptions)(connection[p].options));
+            }
+        }
+        return parts.join('');
+    }
+    // ─── Signal delivery ───────────────────────────────────────────────────────
+    async _deliverEscalationSignal(ns, topic, signalPayload) {
+        if (topic) {
+            try {
+                const tc = await this._engine(topic, ns);
+                await tc.engine.signal(topic, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+                return true;
+            }
+            catch { /* topic not currently registered — fall through */ }
+        }
+        let delivered = false;
+        try {
+            const sc = await this._engine(`${ns}.wfs.signal`, ns);
+            await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+            delivered = true;
+        }
+        catch { }
+        try {
+            const wc = await this._engine(`${ns}.wfs.wait`, ns);
+            await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+            delivered = true;
+        }
+        catch { }
+        return delivered;
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Returns all escalation rows matching the given filters. Each row includes
+     * a computed `available` field (true = claimable). Supports `sortBy`,
+     * `sortOrder`, and multi-role `roles[]` filter.
+     */
+    async list(params) {
+        const hm = await this._engine(null, params?.namespace);
+        return hm.engine.store.listEscalations(params ?? {});
+    }
+    /**
+     * Returns the count of escalation rows matching the given filters.
+     * Uses the same filter parameters as `list()`.
+     */
+    async count(params) {
+        const hm = await this._engine(null, params?.namespace);
+        return hm.engine.store.countEscalations(params ?? {});
+    }
+    /** Returns a single escalation row by UUID. Returns `null` if not found. */
+    async get(id, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.getEscalation(id, namespace);
+    }
+    /** Looks up an escalation by `signal_key` — the value passed to `condition()`. */
+    async getBySignalKey(signalKey, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.getEscalationBySignalKey(signalKey, namespace);
+    }
+    /**
+     * Creates a standalone escalation row with `signal_key = null`.
+     * Useful for external task tracking that doesn't need to resume a workflow.
+     */
+    async create(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.createEscalation(params);
+    }
+    /**
+     * Patches an existing escalation row. `metadata` is merged, not replaced.
+     * Signal routing fields can be enriched after creation.
+     */
+    async update(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.updateEscalation(params);
+    }
+    /** Appends milestone entries to the escalation's audit trail. */
+    async appendMilestones(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.appendEscalationMilestones(params);
+    }
+    /**
+     * Atomically claims an escalation by UUID. Implicit model: `status` stays
+     * `'pending'`; claim is expressed via `assigned_to` + `assigned_until`.
+     */
+    async claim(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.claimEscalation(params);
+    }
+    /**
+     * Atomically claims the highest-priority pending escalation whose `metadata`
+     * contains the given key/value. Returns `isExtension: true` when the same
+     * assignee re-claims a row they already hold (extends the expiry).
+     */
+    async claimByMetadata(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.claimEscalationByMetadata(params);
+    }
+    /** Releases a claimed escalation, returning it to available status. */
+    async release(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.releaseEscalation(params);
+    }
+    /**
+     * Reassigns the escalation to a different role, clearing any current claim
+     * and resetting status to `'pending'`.
+     */
+    async escalateToRole(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.escalateEscalationToRole(params);
+    }
+    /**
+     * Cancels a pending escalation without delivering a signal. Terminal rows
+     * return `already-terminal`.
+     */
+    async cancel(id, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.cancelEscalation(id, namespace);
+    }
+    /**
+     * Signal-first resolve: marks the escalation resolved **and** delivers the
+     * signal to the waiting workflow in a single held transaction. If signal
+     * delivery fails, the transaction rolls back — `committed: false`.
+     */
+    async resolve(params, namespace) {
+        const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+        const hm = await this._engine(null, ns);
+        const dbResult = await hm.engine.store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload });
+        if (!dbResult.ok)
+            return dbResult;
+        if (dbResult.signalKey) {
+            await this._deliverEscalationSignal(ns, dbResult.topic, {
+                id: dbResult.signalKey,
+                data: params.resolverPayload ?? {},
+            });
+        }
+        return { ok: true };
+    }
+    /**
+     * Resolves the highest-priority matching escalation by metadata filter,
+     * then delivers its signal.
+     */
+    async resolveByMetadata(params, namespace) {
+        const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+        const hm = await this._engine(null, ns);
+        const dbResult = await hm.engine.store.resolveEscalationByMetadata({ key: params.key, value: params.value, resolverPayload: params.resolverPayload, roles: params.roles });
+        if (!dbResult.ok)
+            return dbResult;
+        if (dbResult.signalKey) {
+            await this._deliverEscalationSignal(ns, dbResult.topic, {
+                id: dbResult.signalKey,
+                data: params.resolverPayload ?? {},
+            });
+        }
+        return { ok: true };
+    }
+    /**
+     * Full-fidelity migration: inserts an escalation row preserving the original
+     * UUID and lifecycle state. Returns `null` on duplicate (idempotent).
+     */
+    async migrate(params, namespace) {
+        const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+        const hm = await this._engine(null, ns);
+        return hm.engine.store.createEscalationForMigration(params);
+    }
+    /**
+     * No-op in the implicit claim model — availability is computed at query time
+     * from `assigned_until`. Kept for API compatibility.
+     */
+    async releaseExpired(namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.releaseExpiredEscalations(namespace);
+    }
+    static async shutdown() {
+        for (const [_, instance] of EscalationClientService.instances) {
+            (await instance).stop();
+        }
+        EscalationClientService.instances.clear();
+    }
+}
+EscalationClientService.instances = new Map();
+exports.EscalationClientService = EscalationClientService;

package/build/services/escalations/index.d.ts

@@ -0,0 +1,66 @@
+import { guid, uuid } from '../../modules/utils';
+import { EscalationClientService } from './client';
+/**
+ * Escalation queue — the canonical signal-pause surface for HotMesh workflows.
+ *
+ * `public.hmsh_escalations` is a global Postgres table written by both the
+ * YAML DAG hook activity and `Durable.workflow.condition()`. Any consumer
+ * can interact with the queue using just a Postgres connection — no Durable
+ * dependency required.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // List all available approvals for the 'manager' role
+ * const pending = await client.list({ role: 'manager', available: true });
+ *
+ * // Claim one atomically
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager', 'senior-manager'],
+ * });
+ *
+ * // Resolve and resume the waiting workflow in one round-trip
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+declare class EscalationsClass {
+    /** @private */
+    constructor();
+    /**
+     * Creates an escalation queue client. Pass a `connection` for standalone
+     * use, or inject a `getHotMeshClient` function to share an existing
+     * engine pool (e.g. from a `Durable.Client`).
+     */
+    static Client: typeof EscalationClientService;
+    /**
+     * Generate a compact HotMesh identifier (not RFC 4122).
+     * Use `Escalations.uuid()` for DB primary keys.
+     */
+    static guid: typeof guid;
+    /**
+     * Generate a standard RFC 4122 v4 UUID — required for the `id` field
+     * when calling `client.migrate()` or any direct UUID column insert.
+     */
+    static uuid: typeof uuid;
+    /**
+     * Gracefully stop all escalation engine instances.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
+     */
+    static shutdown(): Promise<void>;
+}
+export { EscalationsClass as Escalations };
+export { EscalationClientService };

package/build/services/escalations/index.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EscalationClientService = exports.Escalations = void 0;
+const utils_1 = require("../../modules/utils");
+const client_1 = require("./client");
+Object.defineProperty(exports, "EscalationClientService", { enumerable: true, get: function () { return client_1.EscalationClientService; } });
+/**
+ * Escalation queue — the canonical signal-pause surface for HotMesh workflows.
+ *
+ * `public.hmsh_escalations` is a global Postgres table written by both the
+ * YAML DAG hook activity and `Durable.workflow.condition()`. Any consumer
+ * can interact with the queue using just a Postgres connection — no Durable
+ * dependency required.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // List all available approvals for the 'manager' role
+ * const pending = await client.list({ role: 'manager', available: true });
+ *
+ * // Claim one atomically
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager', 'senior-manager'],
+ * });
+ *
+ * // Resolve and resume the waiting workflow in one round-trip
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+class EscalationsClass {
+    /** @private */
+    constructor() { }
+    /**
+     * Gracefully stop all escalation engine instances.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
+     */
+    static async shutdown() {
+        await client_1.EscalationClientService.shutdown();
+    }
+}
+exports.Escalations = EscalationsClass;
+/**
+ * Creates an escalation queue client. Pass a `connection` for standalone
+ * use, or inject a `getHotMeshClient` function to share an existing
+ * engine pool (e.g. from a `Durable.Client`).
+ */
+EscalationsClass.Client = client_1.EscalationClientService;
+/**
+ * Generate a compact HotMesh identifier (not RFC 4122).
+ * Use `Escalations.uuid()` for DB primary keys.
+ */
+EscalationsClass.guid = utils_1.guid;
+/**
+ * Generate a standard RFC 4122 v4 UUID — required for the `id` field
+ * when calling `client.migrate()` or any direct UUID column insert.
+ */
+EscalationsClass.uuid = utils_1.uuid;

package/build/services/store/providers/postgres/postgres.d.ts

@@ -247,16 +247,17 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     getEscalation(id: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     getEscalationBySignalKey(signalKey: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     listEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry[]>;
+    countEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<number>;
     claimEscalation(params: import('../../../../types/hmsh_escalations').ClaimEscalationParams): Promise<import('../../../../types/hmsh_escalations').ClaimEscalationResult>;
     claimEscalationByMetadata(params: import('../../../../types/hmsh_escalations').ClaimByMetadataParams): Promise<import('../../../../types/hmsh_escalations').ClaimByMetadataResult>;
     releaseEscalation(params: import('../../../../types/hmsh_escalations').ReleaseEscalationParams): Promise<import('../../../../types/hmsh_escalations').ReleaseEscalationResult>;
     resolveEscalation(params: import('../../../../types/hmsh_escalations').ResolveEscalationParams): Promise<import('../../../../types/hmsh_escalations').ResolveEscalationResult & {
-        signalKey?: string;
-        topic?: string;
+        signalKey?: string | null;
+        topic?: string | null;
     }>;
     resolveEscalationByMetadata(params: import('../../../../types/hmsh_escalations').ResolveByMetadataParams): Promise<import('../../../../types/hmsh_escalations').ResolveEscalationResult & {
-        signalKey?: string;
-        topic?: string;
+        signalKey?: string | null;
+        topic?: string | null;
     }>;
     /**
      * Queues the escalation UPDATE into an existing transaction without executing it.
@@ -278,6 +279,6 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     escalateEscalationToRole(params: import('../../../../types/hmsh_escalations').EscalateToRoleParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     updateEscalation(params: import('../../../../types/hmsh_escalations').UpdateEscalationParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     appendEscalationMilestones(params: import('../../../../types/hmsh_escalations').AppendMilestonesParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
-    releaseExpiredEscalations(namespace?: string): Promise<number>;
+    releaseExpiredEscalations(_namespace?: string): Promise<number>;
 }
 export { PostgresStoreService };