@hotmeshio/hotmesh 0.22.1 → 0.22.3

package/build/types/hmsh_escalations.d.ts

@@ -34,7 +34,8 @@ export interface EscalationEntry {
     entity: string | null;
     description: string | null;
     role: string | null;
-    status: 'pending' | 'claimed' | 'resolved' | 'cancelled' | 'expired';
+    /** Lifecycle status. Claims are implicit: status='pending' + assigned_to IS NOT NULL + assigned_until > NOW(). */
+    status: 'pending' | 'resolved' | 'cancelled' | 'expired';
     priority: number;
     assigned_to: string | null;
     assigned_until: Date | null;
@@ -53,8 +54,12 @@ export interface EscalationEntry {
     trace_id: string | null;
     span_id: string | null;
     expires_at: Date | null;
+    /** Nullable passthrough column — populated when downstream needs task-level context. */
+    task_id: string | null;
     created_at: Date;
     updated_at: Date;
+    /** Computed by list(): true when the row is claimable (no active assignee or expired claim). */
+    available?: boolean;
 }
 /**
  * Result of `claim()` — identifies whether failure was due to the row not
@@ -65,20 +70,21 @@ export interface EscalationEntry {
 export type ClaimEscalationResult = {
     ok: true;
     entry: EscalationEntry;
+    isExtension: boolean;
 } | {
     ok: false;
     reason: 'not-found' | 'conflict';
 };
 /**
- * Result of `claimByMetadata()`. Includes `candidatesExist` — the total
- * count of rows matching the metadata filter regardless of claimability — so
- * callers can distinguish "nothing matching at all" from "found candidates but
- * all are locked or in-progress".
+ * Result of `claimByMetadata()`. Includes `candidatesExist` and `isExtension`:
+ * - `candidatesExist` — total count of rows matching the filter regardless of claimability
+ * - `isExtension` — true when the same assignee re-claims a row they already hold (extends the expiry)
  */
 export type ClaimByMetadataResult = {
     ok: true;
     entry: EscalationEntry;
     candidatesExist: number;
+    isExtension: boolean;
 } | {
     ok: false;
     reason: 'not-found' | 'conflict';
@@ -86,12 +92,14 @@ export type ClaimByMetadataResult = {
 };
 export type ResolveEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
-    reason: 'not-found' | 'already-resolved' | 'already-cancelled' | 'signal-failed';
+    reason: 'not-found' | 'already-resolved' | 'already-cancelled';
 };
 export type ReleaseEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
     reason: 'not-found' | 'wrong-assignee';
@@ -105,6 +113,8 @@ export type CancelEscalationResult = {
 export interface ListEscalationsParams {
     namespace?: string;
     role?: string;
+    /** Filter by one or more roles (OR semantics; takes precedence over `role` when both set). */
+    roles?: string[];
     type?: string;
     subtype?: string;
     entity?: string;
@@ -112,9 +122,53 @@ export interface ListEscalationsParams {
     assignedTo?: string;
     workflowId?: string;
     originId?: string;
+    /** When true, returns only rows without an active claim. When false, returns only actively claimed rows. */
+    available?: boolean;
+    /** Exact priority match. */
+    priority?: number;
+    /** JSONB containment filter — rows whose `metadata` contains all provided keys/values. */
+    metadata?: Record<string, unknown>;
+    /** Filter by a set of UUIDs. */
+    ids?: string[];
+    /** Filter by `task_id` column. */
+    taskId?: string;
+    sortBy?: 'created_at' | 'priority' | 'updated_at';
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * Multi-column sort. When provided, supersedes `sortBy`/`sortOrder`.
+     * Columns are applied left to right.
+     */
+    orderBy?: Array<{
+        column: 'priority' | 'created_at' | 'updated_at' | 'resolved_at' | 'role' | 'type';
+        direction: 'asc' | 'desc';
+    }>;
     limit?: number;
     offset?: number;
 }
+export interface StatsEscalationsParams {
+    namespace?: string;
+    /** RBAC scope — when an empty array is provided, all counts are zero. */
+    roles?: string[];
+    /** Counting window for created/resolved. Default: '24h'. */
+    period?: '1h' | '24h' | '7d' | '30d';
+}
+export interface EscalationStats {
+    pending: number;
+    claimed: number;
+    created: number;
+    resolved: number;
+    by_role: Array<{
+        role: string;
+        pending: number;
+        claimed: number;
+    }>;
+    by_type: Array<{
+        type: string;
+        pending: number;
+        claimed: number;
+        resolved: number;
+    }>;
+}
 export interface CreateEscalationParams {
     namespace?: string;
     appId?: string;
@@ -135,6 +189,7 @@ export interface CreateEscalationParams {
     createdBy?: string;
     traceId?: string;
     spanId?: string;
+    taskId?: string;
     escalationPayload?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     envelope?: Record<string, unknown>;
@@ -152,6 +207,7 @@ export interface UpdateEscalationParams {
     description?: string;
     priority?: number;
     role?: string;
+    taskId?: string;
     /** Merged into existing metadata (keys overwritten, others preserved) */
     metadata?: Record<string, unknown>;
     /** Replaces existing envelope */
@@ -186,6 +242,8 @@ export interface ClaimByMetadataParams {
     assignee?: string;
     durationMinutes?: number;
     roles?: string[];
+    /** Merged (not replaced) into the claimed row's metadata in the same atomic UPDATE. */
+    metadata?: Record<string, unknown>;
 }
 export interface ReleaseEscalationParams {
     id: string;
@@ -210,6 +268,27 @@ export interface EscalateToRoleParams {
     targetRole: string;
     namespace?: string;
 }
+export interface ClaimManyParams {
+    ids: string[];
+    namespace?: string;
+    assignee: string;
+    durationMinutes?: number;
+}
+export interface EscalateManyToRoleParams {
+    ids: string[];
+    namespace?: string;
+    targetRole: string;
+}
+export interface UpdateManyPriorityParams {
+    ids: string[];
+    namespace?: string;
+    priority: number;
+}
+export interface ResolveManyParams {
+    ids: string[];
+    namespace?: string;
+    resolverPayload?: Record<string, unknown>;
+}
 /**
  * Full-fidelity migration params. Extends `CreateEscalationParams` with:
  * - `id` (required) — preserves the original UUID; no auto-generation

package/index.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 {
   //Provider Connectors
@@ -30,6 +31,7 @@ export {
   HotMeshConfig,
   Virtual,
   Durable,
+  Escalations,
   DBA,
 
   //Durable Submodules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -86,9 +86,9 @@
     "test:trigger": "vitest run tests/unit/services/activities/trigger.test.ts",
     "test:virtual": "vitest run tests/virtual",
     "test:unit": "vitest run tests/unit",
-
     "prove": "docker compose exec hotmesh npx vitest run tests/durable 2>&1 | tee /tmp/hmsh-durable.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-durable.txt | tail -5",
     "prove:escalations": "docker compose exec hotmesh npx vitest run tests/durable/escalations/postgres.test.ts 2>&1 | tee /tmp/hmsh-escalations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-escalations.txt | tail -5",
+    "prove:migrations": "docker compose exec hotmesh npx vitest run tests/durable/migrations/postgres.test.ts 2>&1 | tee /tmp/hmsh-migrations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-migrations.txt | tail -5",
     "prove:functional": "docker compose exec hotmesh npx vitest run tests/functional 2>&1 | tee /tmp/hmsh-functional.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-functional.txt | tail -5",
     "prove:all": "docker compose exec hotmesh npx vitest run tests/ 2>&1 | tee /tmp/hmsh-all.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-all.txt | tail -5",
     "prove:file": "f() { docker compose exec hotmesh npx vitest run \"$@\" 2>&1 | tee /tmp/hmsh-file.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-file.txt | tail -5; }; f"