@hotmeshio/hotmesh 0.22.0 → 0.22.2

package/build/services/durable/client.js

@@ -7,6 +7,7 @@ const utils_1 = require("../../modules/utils");
 const hotmesh_1 = require("../hotmesh");
 const key_1 = require("../../modules/key");
 const types_1 = require("../../types");
+const client_1 = require("../escalations/client");
 const search_1 = require("./search");
 const handle_1 = require("./handle");
 const factory_1 = require("./schemas/factory");
@@ -284,342 +285,11 @@ class ClientService {
                 }
             },
         };
-        /**
-         * Escalation queue operations over `public.hmsh_escalations` — a global
-         * table that surfaces workflow signal pauses as role-based, claimable,
-         * searchable queue items.
-         *
-         * When a YAML `hook` activity suspends with an `escalation:` block, or
-         * `Durable.workflow.condition(signalId, config)` fires, **one row is
-         * written atomically** with the workflow checkpoint — no enrichment step,
-         * no secondary round-trip. Every connected app shares the same table;
-         * rows are namespaced by `namespace` + `app_id`.
-         *
-         * **Status lifecycle:**
-         * ```
-         * pending → claimed → resolved
-         *         ↘ cancelled      (any non-terminal state)
-         *         ↗ pending        (via release or releaseExpired)
-         * ```
-         *
-         * **Typical human-in-the-loop flow:**
-         * ```typescript
-         * // 1. Workflow pauses and writes the escalation row automatically
-         * const decision = await Durable.workflow.condition('manager-approval', {
-         *   role: 'manager',
-         *   type: 'order-approval',
-         *   priority: 2,
-         *   metadata: { orderId },
-         * });
-         *
-         * // 2. Dashboard lists pending approvals for this role
-         * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
-         *
-         * // 3. Reviewer claims it (sets assigned_to + expiry)
-         * await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
-         *
-         * // 4. Resolve atomically marks it resolved AND delivers the signal
-         * await client.escalations.resolve({
-         *   id: item.id,
-         *   resolverPayload: { approved: true },
-         * });
-         * // workflow resumes with { approved: true }
-         * ```
-         */
-        this.escalations = {
-            /**
-             * Returns all escalation rows matching the given filters.
-             *
-             * @example
-             * ```typescript
-             * // All pending approvals for the manager role
-             * const items = await client.escalations.list({ role: 'manager', status: 'pending' });
-             *
-             * // By workflow ID
-             * const items = await client.escalations.list({ workflowId: 'order-123' });
-             * ```
-             */
-            list: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params?.namespace);
-                return hotMeshClient.engine.store.listEscalations(params ?? {});
-            },
-            /**
-             * Returns a single escalation row by its UUID primary key.
-             * Returns `null` if not found.
-             */
-            get: async (id, namespace) => {
-                const hotMeshClient = await this.getHotMeshClient(null, namespace);
-                return hotMeshClient.engine.store.getEscalation(id, namespace);
-            },
-            /**
-             * Looks up an escalation row by its `signal_key` — the value that was
-             * passed to `condition()` or stored in the hook activity's collation rule.
-             * This is the same key used to deliver the signal via `hotMesh.signal()`.
-             *
-             * @example
-             * ```typescript
-             * const item = await client.escalations.getBySignalKey('manager-approval');
-             * ```
-             */
-            getBySignalKey: async (signalKey, namespace) => {
-                const hotMeshClient = await this.getHotMeshClient(null, namespace);
-                return hotMeshClient.engine.store.getEscalationBySignalKey(signalKey, namespace);
-            },
-            /**
-             * Creates a standalone escalation row that is **not** backed by a signal.
-             * `signal_key` is `null`. Useful for external task tracking that doesn't
-             * need to resume a workflow (e.g., audit tasks, out-of-band approvals).
-             *
-             * @example
-             * ```typescript
-             * const entry = await client.escalations.create({
-             *   role: 'support',
-             *   type: 'data-correction',
-             *   description: 'Fix the customer address',
-             *   metadata: { customerId: 'cust-42' },
-             * });
-             * ```
-             */
-            create: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.createEscalation(params);
-            },
-            /**
-             * Patches an existing escalation row. All fields are optional — only
-             * provided fields are written. `metadata` is **merged**, not replaced.
-             *
-             * Signal routing fields (`signalKey`, `topic`, `workflowId`, …) can be
-             * enriched after the row is created — useful when the row is created
-             * before the workflow starts and routing context is not yet known.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.update({
-             *   id: item.id,
-             *   description: 'Updated description',
-             *   metadata: { extraKey: 'value' },  // merged into existing metadata
-             * });
-             * ```
-             */
-            update: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.updateEscalation(params);
-            },
-            /**
-             * Appends one or more milestone entries to the escalation's
-             * `milestones` audit trail array. Milestones are append-only; they
-             * record events like state transitions, reviewer notes, or external
-             * system callbacks.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.appendMilestones({
-             *   id: item.id,
-             *   milestones: [{ at: new Date().toISOString(), by: 'alice', note: 'Reviewed' }],
-             * });
-             * ```
-             */
-            appendMilestones: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.appendEscalationMilestones(params);
-            },
-            /**
-             * Atomically claims an escalation row by UUID. Sets `assigned_to`,
-             * `claimed_at`, and `claim_expires_at`. Returns `conflict` if another
-             * actor already holds the claim.
-             *
-             * @example
-             * ```typescript
-             * const result = await client.escalations.claim({
-             *   id: item.id,
-             *   assignee: 'alice@company.com',
-             *   durationMinutes: 30,
-             * });
-             * if (!result.ok) console.warn('Already claimed by someone else');
-             * ```
-             */
-            claim: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.claimEscalation(params);
-            },
-            /**
-             * Atomically claims the highest-priority pending escalation whose
-             * `metadata` contains the given key/value pair. Uses
-             * `FOR UPDATE SKIP LOCKED` so concurrent callers never double-claim.
-             *
-             * Returns `candidatesExist` to distinguish two cases:
-             * - `not-found, candidatesExist: 0` — no rows matched the metadata filter
-             * - `conflict, candidatesExist: N` — matching rows exist but all are claimed
-             *
-             * @example
-             * ```typescript
-             * const result = await client.escalations.claimByMetadata({
-             *   key: 'region',
-             *   value: 'west',
-             *   assignee: 'bob@company.com',
-             *   roles: ['manager'],
-             * });
-             * if (result.ok) console.log('Claimed:', result.entry.id);
-             * ```
-             */
-            claimByMetadata: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.claimEscalationByMetadata(params);
-            },
-            /**
-             * Releases a claimed escalation, returning it to `pending` status and
-             * clearing `assigned_to` and `claim_expires_at`. The row is immediately
-             * available for other actors to claim.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.release({ id: item.id });
-             * ```
-             */
-            release: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.releaseEscalation(params);
-            },
-            /**
-             * Reassigns the escalation to a different role, clearing any current
-             * claim and returning status to `pending`. Use when an escalation must
-             * be handled by a different team or tier.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.escalateToRole({ id: item.id, role: 'senior-manager' });
-             * ```
-             */
-            escalateToRole: async (params) => {
-                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
-                return hotMeshClient.engine.store.escalateEscalationToRole(params);
-            },
-            /**
-             * Terminates the escalation without delivering a signal. Rows in
-             * `pending` or `claimed` state move to `cancelled`. Terminal rows
-             * (`resolved`, `cancelled`) return `already-terminal`.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.cancel(item.id);
-             * ```
-             */
-            cancel: async (id, namespace) => {
-                const hotMeshClient = await this.getHotMeshClient(null, namespace);
-                return hotMeshClient.engine.store.cancelEscalation(id, namespace);
-            },
-            /**
-             * Atomically marks the escalation `resolved` **and** delivers the
-             * signal to the waiting workflow — one round-trip, no separate
-             * `signal()` call required. If `signal_key` is null (standalone
-             * escalation), only the row is updated.
-             *
-             * @example
-             * ```typescript
-             * const result = await client.escalations.resolve({
-             *   id: item.id,
-             *   resolverPayload: { approved: true, note: 'LGTM' },
-             * });
-             * if (!result.ok) console.error(result.reason); // 'not-found' | 'already-resolved' | 'signal-failed'
-             * // workflow resumes with { approved: true, note: 'LGTM' }
-             * ```
-             */
-            resolve: async (params, namespace) => {
-                const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
-                const hotMeshClient = await this.getHotMeshClient(null, ns);
-                const store = hotMeshClient.engine.store;
-                // UUID primary-key lookup — no namespace filter needed; use existing.namespace for the UPDATE.
-                const existing = await store.getEscalation(params.id);
-                if (!existing)
-                    return { ok: false, reason: 'not-found' };
-                if (existing.status === 'resolved')
-                    return { ok: false, reason: 'already-resolved' };
-                if (existing.status === 'cancelled')
-                    return { ok: false, reason: 'already-cancelled' };
-                // Build a single atomic transaction: signal stream INSERTs + escalation UPDATE in one BEGIN/COMMIT.
-                // engine.signal() with a transaction queues an INSERT into the stream table without executing;
-                // queueResolveEscalation() queues the status UPDATE; txn.exec() commits all in one round-trip.
-                const txn = store.transact();
-                if (existing.signal_key && existing.topic) {
-                    const signalPayload = { id: existing.signal_key, data: params.resolverPayload ?? {} };
-                    try {
-                        const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
-                        await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
-                    }
-                    catch { /* no collator hook rule — skip */ }
-                    try {
-                        const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
-                        await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
-                    }
-                    catch { /* no waiter hook rule — skip */ }
-                }
-                store.queueResolveEscalation({ id: params.id, namespace: existing.namespace ?? ns, resolverPayload: params.resolverPayload }, txn);
-                await txn.exec();
-                return { ok: true };
-            },
-            /**
-             * Resolves the highest-priority matching escalation by metadata filter,
-             * then delivers its signal. Identical semantics to `resolve()` but
-             * selects the target row by metadata key/value instead of UUID.
-             *
-             * @example
-             * ```typescript
-             * await client.escalations.resolveByMetadata({
-             *   key: 'orderId',
-             *   value: 'order-123',
-             *   resolverPayload: { approved: true },
-             * });
-             * ```
-             */
-            resolveByMetadata: async (params, namespace) => {
-                const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
-                const hotMeshClient = await this.getHotMeshClient(null, ns);
-                const store = hotMeshClient.engine.store;
-                // Metadata lookup: filter by namespace to scope correctly, but use existing.namespace for the UPDATE.
-                const existing = await store.findEscalationByMetadata(params.key, params.value, params.roles ?? null);
-                if (!existing)
-                    return { ok: false, reason: 'not-found' };
-                if (existing.status === 'resolved')
-                    return { ok: false, reason: 'already-resolved' };
-                if (existing.status === 'cancelled')
-                    return { ok: false, reason: 'already-cancelled' };
-                // Same atomic pattern as resolve(): signal INSERTs + UPDATE in one transaction.
-                const txn = store.transact();
-                if (existing.signal_key && existing.topic) {
-                    const signalPayload = { id: existing.signal_key, data: params.resolverPayload ?? {} };
-                    try {
-                        const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
-                        await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
-                    }
-                    catch { /* no collator hook rule — skip */ }
-                    try {
-                        const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
-                        await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
-                    }
-                    catch { /* no waiter hook rule — skip */ }
-                }
-                store.queueResolveEscalation({ id: existing.id, namespace: existing.namespace ?? ns, resolverPayload: params.resolverPayload }, txn);
-                await txn.exec();
-                return { ok: true };
-            },
-            /**
-             * Releases all claimed escalations whose `claim_expires_at` has lapsed,
-             * returning them to `pending` so they can be claimed again. Returns the
-             * number of rows released. Call periodically from a maintenance job or
-             * cron to prevent stale claims from blocking the queue.
-             *
-             * @example
-             * ```typescript
-             * const released = await client.escalations.releaseExpired();
-             * console.log(`Released ${released} expired claims`);
-             * ```
-             */
-            releaseExpired: async (namespace) => {
-                const hotMeshClient = await this.getHotMeshClient(null, namespace);
-                return hotMeshClient.engine.store.releaseExpiredEscalations(namespace);
-            },
-        };
         this.connection = config.connection;
+        // Inject our getHotMeshClient so the escalation client shares the same engine pool.
+        this.escalations = new client_1.EscalationClientService({
+            getHotMeshClient: this.getHotMeshClient.bind(this),
+        });
     }
     hashOptions() {
         if ('options' in this.connection) {

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

@@ -1,6 +1,6 @@
 import { HotMesh } from '../hotmesh';
 import { ContextType, WorkflowInboundCallsInterceptor, WorkflowOutboundCallsInterceptor, ActivityInboundCallsInterceptor } from '../../types/durable';
-import { guid } from '../../modules/utils';
+import { guid, uuid } from '../../modules/utils';
 import { ClientService } from './client';
 import { ConnectionService } from './connection';
 import { Search } from './search';
@@ -277,6 +277,12 @@ declare class DurableClass {
      * Generate a unique identifier for workflow IDs
      */
     static guid: typeof guid;
+    /**
+     * Generate a standard RFC 4122 v4 UUID — use for DB primary keys and
+     * any context that requires a hyphenated UUID format rather than the
+     * compact HotMesh guid format.
+     */
+    static uuid: typeof uuid;
     /**
      * Provision a scoped Postgres role for a worker. The role can only
      * dequeue, ack, and respond on its assigned stream names via stored

package/build/services/durable/index.js

@@ -310,6 +310,12 @@ DurableClass.interceptorService = new interceptor_1.InterceptorService();
  * Generate a unique identifier for workflow IDs
  */
 DurableClass.guid = utils_1.guid;
+/**
+ * Generate a standard RFC 4122 v4 UUID — use for DB primary keys and
+ * any context that requires a hyphenated UUID format rather than the
+ * compact HotMesh guid format.
+ */
+DurableClass.uuid = utils_1.uuid;
 /**
  * Provision a scoped Postgres role for a worker. The role can only
  * dequeue, ack, and respond on its assigned stream names via stored

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

@@ -0,0 +1,130 @@
+import { HotMesh } from '../hotmesh';
+import { Connection } from '../../types/durable';
+import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams } from '../../types/hmsh_escalations';
+type GetHotMeshFn = (topic: string | null, namespace?: string) => Promise<HotMesh>;
+export interface EscalationClientConfig {
+    /** Postgres connection options — used when creating a standalone EscalationClient. */
+    connection?: Connection;
+    /**
+     * Inject a pre-existing `getHotMeshClient` function (e.g. from Durable.Client).
+     * When provided, the client reuses the caller's engine pool — no second connection.
+     */
+    getHotMeshClient?: GetHotMeshFn;
+}
+/**
+ * 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 } });
+ * }
+ * ```
+ */
+export declare class EscalationClientService {
+    private readonly _engine;
+    private readonly _connection?;
+    static instances: Map<string, HotMesh | Promise<HotMesh>>;
+    constructor(config?: EscalationClientConfig);
+    private _makeEngineFactory;
+    private _hashConnection;
+    private _deliverEscalationSignal;
+    /**
+     * 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.
+     */
+    list(params?: ListEscalationsParams): Promise<EscalationEntry[]>;
+    /**
+     * Returns the count of escalation rows matching the given filters.
+     * Uses the same filter parameters as `list()`.
+     */
+    count(params?: ListEscalationsParams): Promise<number>;
+    /** Returns a single escalation row by UUID. Returns `null` if not found. */
+    get(id: string, namespace?: string): Promise<EscalationEntry | null>;
+    /** Looks up an escalation by `signal_key` — the value passed to `condition()`. */
+    getBySignalKey(signalKey: string, namespace?: string): Promise<EscalationEntry | null>;
+    /**
+     * Creates a standalone escalation row with `signal_key = null`.
+     * Useful for external task tracking that doesn't need to resume a workflow.
+     */
+    create(params: CreateEscalationParams): Promise<EscalationEntry>;
+    /**
+     * Patches an existing escalation row. `metadata` is merged, not replaced.
+     * Signal routing fields can be enriched after creation.
+     */
+    update(params: UpdateEscalationParams): Promise<EscalationEntry | null>;
+    /** Appends milestone entries to the escalation's audit trail. */
+    appendMilestones(params: AppendMilestonesParams): Promise<EscalationEntry | null>;
+    /**
+     * Atomically claims an escalation by UUID. Implicit model: `status` stays
+     * `'pending'`; claim is expressed via `assigned_to` + `assigned_until`.
+     */
+    claim(params: ClaimEscalationParams): Promise<ClaimEscalationResult>;
+    /**
+     * 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).
+     */
+    claimByMetadata(params: ClaimByMetadataParams): Promise<ClaimByMetadataResult>;
+    /** Releases a claimed escalation, returning it to available status. */
+    release(params: ReleaseEscalationParams): Promise<ReleaseEscalationResult>;
+    /**
+     * Reassigns the escalation to a different role, clearing any current claim
+     * and resetting status to `'pending'`.
+     */
+    escalateToRole(params: EscalateToRoleParams): Promise<EscalationEntry | null>;
+    /**
+     * Cancels a pending escalation without delivering a signal. Terminal rows
+     * return `already-terminal`.
+     */
+    cancel(id: string, namespace?: string): Promise<CancelEscalationResult>;
+    /**
+     * 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`.
+     */
+    resolve(params: ResolveEscalationParams, namespace?: string): Promise<ResolveEscalationResult>;
+    /**
+     * Resolves the highest-priority matching escalation by metadata filter,
+     * then delivers its signal.
+     */
+    resolveByMetadata(params: ResolveByMetadataParams, namespace?: string): Promise<ResolveEscalationResult>;
+    /**
+     * Full-fidelity migration: inserts an escalation row preserving the original
+     * UUID and lifecycle state. Returns `null` on duplicate (idempotent).
+     */
+    migrate(params: MigrateEscalationParams, namespace?: string): Promise<EscalationEntry | null>;
+    /**
+     * No-op in the implicit claim model — availability is computed at query time
+     * from `assigned_until`. Kept for API compatibility.
+     */
+    releaseExpired(namespace?: string): Promise<number>;
+    static shutdown(): Promise<void>;
+}
+export {};