@hotmeshio/hotmesh 0.21.1 → 0.22.1

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

@@ -1,5 +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';
 /**
  * Workflow client. Starts workflows, sends signals, and reads results.
  *
@@ -82,73 +83,6 @@ export declare class ClientService {
      * is accessed by calling workflow.start().
      */
     workflow: ClientWorkflow;
-    /**
-     * Signal queue API for managing paused-workflow task records.
-     * Operations: list, get, claim, claimByMetadata, release, resolve,
-     * resolveByMetadata, releaseExpired.
-     *
-     * Requires a Postgres store provider. Methods are no-ops (return null/false)
-     * when called against a non-Postgres store.
-     *
-     * @example
-     * ```typescript
-     * // Claim a pending task by metadata key
-     * const task = await client.signalQueue.claimByMetadata({
-     *   key: 'orderId', value: 'RX-123',
-     *   assignee: 'pharmacist-jane',
-     *   durationMinutes: 30,
-     * });
-     *
-     * if (task) {
-     *   await client.signalQueue.resolve({
-     *     id: task.id,
-     *     resolverPayload: { approved: true },
-     *   });
-     *   // → paused workflow resumes with { approved: true }
-     * }
-     * ```
-     */
-    signalQueue: {
-        list: (params?: {
-            namespace?: string;
-            taskQueue?: string;
-            status?: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
-            role?: string;
-            limit?: number;
-            offset?: number;
-        }) => Promise<any>;
-        get: (id: string, namespace?: string) => Promise<any>;
-        getBySignalKey: (signalKey: string, namespace?: string) => Promise<any>;
-        claim: (params: {
-            id: string;
-            namespace?: string;
-            assignee?: string;
-            durationMinutes?: number;
-        }) => Promise<import('../../types/signal').ClaimSignalResult>;
-        claimByMetadata: (params: {
-            key: string;
-            value: unknown;
-            namespace?: string;
-            assignee?: string;
-            durationMinutes?: number;
-        }) => Promise<import('../../types/signal').ClaimSignalResult>;
-        release: (params: {
-            id: string;
-            namespace?: string;
-        }) => Promise<import('../../types/signal').ReleaseSignalResult>;
-        resolve: (params: {
-            id: string;
-            namespace?: string;
-            resolverPayload?: Record<string, unknown>;
-        }) => Promise<import('../../types/signal').ResolveSignalResult>;
-        resolveByMetadata: (params: {
-            key: string;
-            value: unknown;
-            namespace?: string;
-            resolverPayload?: Record<string, unknown>;
-        }) => Promise<import('../../types/signal').ResolveSignalResult>;
-        releaseExpired: (namespace?: string) => Promise<number>;
-    };
     /**
      * Any router can be used to deploy and activate the HotMesh
      * distributed executable to the active quorum EXCEPT for
@@ -163,6 +97,278 @@ 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
      */