@hotmeshio/hotmesh 0.22.1 → 0.22.2

package/build/index.d.ts

@@ -18,6 +18,7 @@ import * as KeyStore from './modules/key';
 import { ConnectorService as Connector } from './services/connector/factory';
 import { PostgresConnection as ConnectorPostgres } from './services/connector/providers/postgres';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
+import { Escalations } from './services/escalations';
 export { Connector, //factory
-ConnectorNATS, ConnectorPostgres, HotMesh, HotMeshConfig, Virtual, Durable, DBA, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
+ConnectorNATS, ConnectorPostgres, HotMesh, HotMeshConfig, Virtual, Durable, Escalations, DBA, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
 export * as Types from './types';

package/build/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.DBA = exports.Durable = exports.Virtual = exports.HotMesh = exports.ConnectorPostgres = exports.ConnectorNATS = exports.Connector = void 0;
+exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.DBA = exports.Escalations = exports.Durable = exports.Virtual = exports.HotMesh = exports.ConnectorPostgres = exports.ConnectorNATS = exports.Connector = void 0;
 const hotmesh_1 = require("./services/hotmesh");
 Object.defineProperty(exports, "HotMesh", { enumerable: true, get: function () { return hotmesh_1.HotMesh; } });
 const virtual_1 = require("./services/virtual");
@@ -62,4 +62,6 @@ const postgres_1 = require("./services/connector/providers/postgres");
 Object.defineProperty(exports, "ConnectorPostgres", { enumerable: true, get: function () { return postgres_1.PostgresConnection; } });
 const nats_1 = require("./services/connector/providers/nats");
 Object.defineProperty(exports, "ConnectorNATS", { enumerable: true, get: function () { return nats_1.NatsConnection; } });
+const escalations_1 = require("./services/escalations");
+Object.defineProperty(exports, "Escalations", { enumerable: true, get: function () { return escalations_1.Escalations; } });
 exports.Types = __importStar(require("./types"));

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.22.1",
+    "version": "0.22.2",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

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

@@ -1,6 +1,6 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } 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';
+import { EscalationClientService } from '../escalations/client';
 /**
  * Workflow client. Starts workflows, sends signals, and reads results.
  *
@@ -49,6 +49,13 @@ export declare class ClientService {
      * @private
      */
     static instances: Map<string, HotMesh | Promise<HotMesh>>;
+    /**
+     * Escalation queue operations — a thin proxy to `Escalations.Client` that
+     * reuses this Durable.Client's engine pool. Calling
+     * `client.escalations.list(...)` is identical to creating a separate
+     * `new Escalations.Client({ connection })` — just more convenient.
+     */
+    escalations: EscalationClientService;
     /**
      * @private
      */
@@ -97,278 +104,6 @@ export declare class ClientService {
      * @private
      */
     activateWorkflow(hotMesh: HotMesh, appId?: string, version?: string): Promise<void>;
-    /**
-     * 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 }
-     * ```
-     */
-    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: (params?: ListEscalationsParams) => Promise<EscalationEntry[]>;
-        /**
-         * Returns a single escalation row by its UUID primary key.
-         * Returns `null` if not found.
-         */
-        get: (id: string, namespace?: string) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (signalKey: string, namespace?: string) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (params: CreateEscalationParams) => Promise<EscalationEntry>;
-        /**
-         * 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: (params: UpdateEscalationParams) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (params: AppendMilestonesParams) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (params: ClaimEscalationParams) => Promise<ClaimEscalationResult>;
-        /**
-         * 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: (params: ClaimByMetadataParams) => Promise<ClaimByMetadataResult>;
-        /**
-         * 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: (params: ReleaseEscalationParams) => Promise<ReleaseEscalationResult>;
-        /**
-         * 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: (params: EscalateToRoleParams) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (id: string, namespace?: string) => Promise<CancelEscalationResult>;
-        /**
-         * 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: (params: ResolveEscalationParams, namespace?: string) => Promise<ResolveEscalationResult>;
-        /**
-         * 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: (params: ResolveByMetadataParams, namespace?: string) => Promise<ResolveEscalationResult>;
-        /**
-         * 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: (params: MigrateEscalationParams, namespace?: string) => Promise<EscalationEntry | null>;
-        /**
-         * 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: (namespace?: string) => Promise<number>;
-    };
-    /**
-     * 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
-     */
-    private _deliverEscalationSignal;
     /**
      * @private
      */