@hotmeshio/hotmesh 0.22.1 → 0.22.3

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,351 +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;
-                // store.resolveEscalation() uses FOR UPDATE inside its CTE, serializing concurrent
-                // callers at the DB level. The second caller blocks on the row lock, reads
-                // 'already-resolved' after the first commits, and returns — no signal is queued.
-                // This eliminates the double-signal race that the previous KVTransaction approach
-                // had: two concurrent callers could both pass the unlocked getEscalation() read,
-                // both queue signal INSERTs, and both commit them — even though only one UPDATE won.
-                const dbResult = await store.resolveEscalation({
-                    id: params.id,
-                    resolverPayload: params.resolverPayload,
-                    // namespace intentionally omitted — UUID lookup; passing ns would miss rows
-                    // stored under namespace 'hmsh' (the engine default) when ns = APP_ID = 'durable'.
-                });
-                if (!dbResult.ok)
-                    return dbResult;
-                if (dbResult.signalKey) {
-                    const signalPayload = { id: dbResult.signalKey, data: params.resolverPayload ?? {} };
-                    const delivered = await this._deliverEscalationSignal(ns, dbResult.topic, signalPayload);
-                    if (!delivered)
-                        return { ok: false, reason: 'signal-failed' };
-                }
-                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;
-                // Same FOR UPDATE CTE serialization as resolve(). Metadata filter selects
-                // the highest-priority matching row; the lock prevents concurrent callers
-                // from both resolving it.
-                const dbResult = await store.resolveEscalationByMetadata({
-                    key: params.key,
-                    value: params.value,
-                    resolverPayload: params.resolverPayload,
-                    roles: params.roles,
-                });
-                if (!dbResult.ok)
-                    return dbResult;
-                if (dbResult.signalKey) {
-                    const signalPayload = { id: dbResult.signalKey, data: params.resolverPayload ?? {} };
-                    const delivered = await this._deliverEscalationSignal(ns, dbResult.topic, signalPayload);
-                    if (!delivered)
-                        return { ok: false, reason: 'signal-failed' };
-                }
-                return { ok: true };
-            },
-            /**
-             * Full-fidelity migration: inserts an escalation row preserving the original
-             * UUID and all lifecycle state. Returns the inserted row, or `null` if the
-             * UUID already exists (idempotent — safe to call multiple times with the same
-             * `params.id`). Use this to migrate rows from a legacy escalation table to
-             * `hmsh_escalations` without losing original IDs or state.
-             *
-             * @example
-             * ```typescript
-             * const entry = await client.escalations.migrate({
-             *   id: 'original-uuid',
-             *   status: 'resolved',
-             *   resolvedAt: new Date('2025-01-01'),
-             *   type: 'order-approval',
-             *   role: 'approver',
-             * });
-             * // null on subsequent calls with the same id — idempotent
-             * ```
-             */
-            migrate: async (params, namespace) => {
-                const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
-                const hotMeshClient = await this.getHotMeshClient(null, ns);
-                return hotMeshClient.engine.store.createEscalationForMigration(params);
-            },
-            /**
-             * 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) {
@@ -703,46 +364,6 @@ class ClientService {
             }
         }
     }
-    /**
-     * Delivers a signal to the registered escalation topic.
-     *
-     * When the topic is known (stored at condition() time), we deliver only to that
-     * topic. This avoids writing a stale pending entry to the alternate stream, which
-     * would interfere with concurrent consumers in other workflows or tests.
-     *
-     * When topic is null (legacy/standalone rows with no registered topic), we try
-     * both wfs.signal and wfs.wait unconditionally — engine.signal() on the wrong
-     * topic stores pending without throwing, so a sequential fallback would skip
-     * the second topic and leave single-condition workflows permanently suspended.
-     *
-     * @private
-     */
-    async _deliverEscalationSignal(ns, topic, signalPayload) {
-        if (topic) {
-            // Registered topic known — deliver precisely, no stream pollution.
-            try {
-                const tc = await this.getHotMeshClient(topic, ns);
-                await tc.engine.signal(topic, signalPayload, types_1.StreamStatus.SUCCESS, 200);
-                return true;
-            }
-            catch { /* topic not currently registered — fall through */ }
-        }
-        // Topic unknown or primary delivery failed — try both topics unconditionally.
-        let delivered = false;
-        try {
-            const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
-            await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
-            delivered = true;
-        }
-        catch { /* no collator hook rule for this workflow */ }
-        try {
-            const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
-            await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
-            delivered = true;
-        }
-        catch { /* no waiter hook rule for this workflow */ }
-        return delivered;
-    }
     /**
      * @private
      */

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

@@ -0,0 +1,168 @@
+import { HotMesh } from '../hotmesh';
+import { Connection } from '../../types/durable';
+import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, StatsEscalationsParams, EscalationStats, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, ClaimManyParams, EscalateManyToRoleParams, UpdateManyPriorityParams, ResolveManyParams } from '../../types/hmsh_escalations';
+export 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 extra connections.
+     */
+    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;
+    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`, `orderBy[]`, 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`.
+     * Returns `isExtension: true` when the same assignee re-claims a row they already hold.
+     */
+    claim(params: ClaimEscalationParams): Promise<ClaimEscalationResult>;
+    /**
+     * Atomically claims the highest-priority pending escalation whose `metadata`
+     * contains the given key/value. Optionally merges `metadata` into the claimed row
+     * in the same atomic UPDATE. 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>;
+    /**
+     * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
+     * with FOR UPDATE + WHERE guard: only one concurrent caller can commit the
+     * status change; the committed resolved row with its `signal_key` is the
+     * durable proof. Signal delivery is best-effort post-commit — the resolved
+     * row is the recovery record for any missed delivery. Returns the updated
+     * row as `entry` on success.
+     */
+    resolve(params: ResolveEscalationParams, namespace?: string): Promise<ResolveEscalationResult>;
+    /**
+     * Resolves the highest-priority matching escalation by metadata filter,
+     * then delivers its signal. Same transaction + WHERE guard semantics as `resolve()`.
+     */
+    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>;
+    /**
+     * Bulk-claims up to `ids.length` pending escalations in one statement.
+     * Returns `{ claimed, skipped }` — skipped rows are either already claimed
+     * by another assignee or non-existent. Implicit-claim semantics apply.
+     */
+    claimMany(params: ClaimManyParams): Promise<{
+        claimed: number;
+        skipped: number;
+    }>;
+    /**
+     * Bulk-reassigns pending escalations to a new role, clearing any current claim.
+     * Returns the count of rows updated.
+     */
+    escalateManyToRole(params: EscalateManyToRoleParams): Promise<number>;
+    /**
+     * Bulk-updates priority for pending escalations. Returns the count of rows updated.
+     */
+    updateManyPriority(params: UpdateManyPriorityParams): Promise<number>;
+    /**
+     * Bulk-resolves pending escalations by id-set. No signal delivery — intended
+     * for redirect-to-triage flows where no workflow is waiting. Returns the
+     * resolved rows.
+     */
+    resolveMany(params: ResolveManyParams): Promise<EscalationEntry[]>;
+    /**
+     * Returns dashboard-ready escalation counts. `period` controls the window
+     * used for `created` and `resolved` counts (default `'24h'`). When `roles`
+     * is an empty array, all counts are zero (RBAC guard).
+     */
+    stats(params?: StatsEscalationsParams): Promise<EscalationStats>;
+    /**
+     * Returns the sorted list of distinct `type` values in the escalations table.
+     * Useful for populating filter dropdowns.
+     */
+    listDistinctTypes(namespace?: string): Promise<string[]>;
+    static shutdown(): Promise<void>;
+}