@hotmeshio/long-tail 0.5.2 → 0.5.4

package/build/services/escalation/crud.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;
+exports.getEscalationBySignalKey = getEscalationBySignalKey;
+exports.resolveEscalationBySignalKey = resolveEscalationBySignalKey;
 exports.updateEscalationsPriority = updateEscalationsPriority;
 exports.getEscalationRoles = getEscalationRoles;
 exports.releaseEscalation = releaseEscalation;
@@ -19,32 +21,37 @@ exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
-const logger_1 = require("../../lib/logger");
+const client_1 = require("./client");
+const map_1 = require("./map");
 const sql_1 = require("./sql");
+// All escalation state lives in `public.hmsh_escalations` (HotMesh 0.22.3),
+// reached through `client.escalations.*`. The function signatures and return
+// shapes below are the frozen public surface — only the storage path changed.
+// Generous upper bound for the "all escalations for X" lookups, which the
+// legacy SQL returned without a LIMIT. Escalations per workflow/origin/task are
+// few; this avoids a silent page cap without an unbounded scan.
+const LOOKUP_LIMIT = 1000;
 async function createEscalation(input) {
-    logger_1.loggerRegistry.info(`[escalation-crud] createEscalation called for wf=${input.workflow_id} type=${input.type} caller=${new Error().stack?.split('\n')[2]?.trim()}`);
-    const pool = (0, db_1.getPool)();
-    // Ensure the role exists in lt_roles (FK constraint)
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [input.role]);
-    const { rows } = await pool.query(sql_1.CREATE_ESCALATION, [
-        input.type,
-        input.subtype,
-        input.description || null,
-        input.priority || 2,
-        input.task_id || null,
-        input.origin_id || null,
-        input.parent_id || null,
-        input.role,
-        input.envelope,
-        input.metadata ? JSON.stringify(input.metadata) : null,
-        input.escalation_payload || null,
-        input.workflow_id || null,
-        input.task_queue || null,
-        input.workflow_type || null,
-        input.trace_id || null,
-        input.span_id || null,
-    ]);
-    const escalation = rows[0];
+    const client = await (0, client_1.escalations)();
+    const entry = await client.create({
+        type: input.type,
+        subtype: input.subtype,
+        description: input.description,
+        priority: input.priority ?? 2,
+        role: input.role,
+        taskId: input.task_id,
+        originId: input.origin_id,
+        parentId: input.parent_id,
+        workflowId: input.workflow_id,
+        taskQueue: input.task_queue,
+        workflowType: input.workflow_type,
+        traceId: input.trace_id,
+        spanId: input.span_id,
+        envelope: (0, map_1.toEnvelopeObject)(input.envelope),
+        metadata: input.metadata,
+        escalationPayload: (0, map_1.toJsonObject)(input.escalation_payload),
+    });
+    const escalation = (0, map_1.toEscalationRecord)(entry);
     (0, publish_1.publishEscalationEvent)({
         type: 'escalation.created',
         source: 'service',
@@ -58,22 +65,16 @@ async function createEscalation(input) {
     return escalation;
 }
 /**
- * Atomic claim operation. Does NOT change status — "claimed" is implicit
- * via assigned_to + assigned_until > NOW().
- *
- * Conditions:
- * - status = 'pending' (not resolved/cancelled)
- * - Either: unassigned, expired claim, or same user (extension)
- *
- * Uses a CTE to capture the previous state so callers can detect extensions.
+ * Atomic claim. Implicit model — status stays 'pending'; "claimed" is
+ * assigned_to + assigned_until > NOW(). `isExtension` is true when the same
+ * user re-claims (extends expiry). Returns null when the row is not claimable.
  */
 async function claimEscalation(id, userId, durationMinutes = 30) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.CLAIM_ESCALATION, [id, userId, durationMinutes]);
-    if (rows.length === 0)
+    const client = await (0, client_1.escalations)();
+    const result = await client.claim({ id, assignee: userId, durationMinutes });
+    if (!result.ok)
         return null;
-    const row = rows[0];
-    const escalation = row;
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
     (0, publish_1.publishEscalationEvent)({
         type: 'escalation.claimed',
         source: 'service',
@@ -84,39 +85,68 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
         status: 'claimed',
         data: { assigned_to: userId },
     });
-    return {
-        escalation,
-        isExtension: row.prev_assigned_to === userId,
-    };
+    return { escalation, isExtension: result.isExtension };
 }
+/**
+ * Mark an escalation resolved. Signal delivery is owned by the resolution
+ * orchestrator (api/escalations/resolve.ts); service-created rows have no
+ * signal_key, so this never delivers a signal itself. Returns null when the
+ * row is missing or already terminal.
+ */
 async function resolveEscalation(id, resolverPayload) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.RESOLVE_ESCALATION, [id, JSON.stringify(resolverPayload)]);
-    const escalation = rows[0] || null;
-    if (escalation) {
-        (0, publish_1.publishEscalationEvent)({
-            type: 'escalation.resolved',
-            source: 'service',
-            workflowId: escalation.workflow_id || '',
-            workflowName: escalation.workflow_type || '',
-            taskQueue: escalation.task_queue || '',
-            escalationId: escalation.id,
-            status: 'resolved',
-            data: {},
-        });
-    }
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolve({ id, resolverPayload });
+    if (!result.ok)
+        return null;
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    (0, publish_1.publishEscalationEvent)({
+        type: 'escalation.resolved',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        status: 'resolved',
+        data: {},
+    });
     return escalation;
 }
 /**
- * Bulk update priority for a set of escalations.
- * Only updates pending escalations.
+ * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
+ * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
+ * Returns null when no row carries that key.
+ */
+async function getEscalationBySignalKey(signalKey) {
+    const client = await (0, client_1.escalations)();
+    const entry = await client.getBySignalKey(signalKey);
+    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
+}
+/**
+ * Resolve an efficient (atomic) escalation by its `signal_key` and resume the
+ * waiting workflow in place. Convenience for webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. Returns null when the key is unknown or already terminal.
+ *
+ * Race-free: `signal_key → id` is an immutable mapping, and the state mutation
+ * is delegated to `resolveEscalation`, whose `client.resolve` uses FOR UPDATE +
+ * `WHERE status = 'pending'` so exactly one concurrent caller commits. No status
+ * pre-check (that would be a TOCTOU window) — the atomic resolve is the arbiter.
+ */
+async function resolveEscalationBySignalKey(signalKey, resolverPayload) {
+    const escalation = await getEscalationBySignalKey(signalKey);
+    if (!escalation)
+        return null;
+    return resolveEscalation(escalation.id, resolverPayload);
+}
+/**
+ * Bulk update priority for a set of escalations. Only pending escalations are
+ * updated.
  */
 async function updateEscalationsPriority(ids, priority) {
     if (ids.length === 0)
         return 0;
-    const pool = (0, db_1.getPool)();
-    const { rowCount } = await pool.query(sql_1.UPDATE_ESCALATIONS_PRIORITY, [priority, ids]);
-    return rowCount ?? 0;
+    const client = await (0, client_1.escalations)();
+    return client.updateManyPriority({ ids, priority });
 }
 /**
  * Get the distinct roles for a set of escalation IDs.
@@ -125,113 +155,145 @@ async function updateEscalationsPriority(ids, priority) {
 async function getEscalationRoles(ids) {
     if (ids.length === 0)
         return [];
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_ESCALATION_ROLES, [ids]);
-    return rows.map((r) => r.role);
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({ ids, limit: LOOKUP_LIMIT });
+    return [...new Set(rows.map(r => r.role).filter((r) => !!r))];
 }
 /**
  * Release a single escalation claim back to the available pool.
  * Only the assigned user (or superadmin via route) may release.
  */
 async function releaseEscalation(id, userId) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.RELEASE_ESCALATION, [id, userId]);
-    const released = rows[0];
-    if (released) {
-        (0, publish_1.publishEscalationEvent)({
-            type: 'escalation.released',
-            source: 'service',
-            workflowId: released.workflow_id || '',
-            workflowName: released.workflow_type || '',
-            taskQueue: released.task_queue || '',
-            escalationId: released.id,
-            status: 'released',
-            data: { released_by: userId },
-        });
-    }
-    return released || null;
+    const client = await (0, client_1.escalations)();
+    const result = await client.release({ id, assignee: userId });
+    if (!result.ok)
+        return null;
+    const released = (0, map_1.toEscalationRecord)(result.entry);
+    (0, publish_1.publishEscalationEvent)({
+        type: 'escalation.released',
+        source: 'service',
+        workflowId: released.workflow_id || '',
+        workflowName: released.workflow_type || '',
+        taskQueue: released.task_queue || '',
+        escalationId: released.id,
+        status: 'released',
+        data: { released_by: userId },
+    });
+    return released;
 }
+/**
+ * Sweep expired claims back to the available pool, returning the count cleared.
+ * Availability is already query-time in the implicit model, but long-tail's
+ * public contract clears `assigned_to` and returns a count, so this runs as a
+ * single direct UPDATE on the shared table (the SDK's releaseExpired is a no-op).
+ */
 async function releaseExpiredClaims() {
+    await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
     const { rowCount } = await pool.query(sql_1.RELEASE_EXPIRED_CLAIMS);
-    return rowCount || 0;
+    return rowCount ?? 0;
 }
 /**
  * Reassign an escalation to a different role.
  * Clears the current assignment so it becomes available to the new role.
  */
 async function escalateToRole(id, targetRole) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.ESCALATE_TO_ROLE, [id, targetRole]);
-    return rows[0] || null;
+    const client = await (0, client_1.escalations)();
+    const entry = await client.escalateToRole({ id, targetRole });
+    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
 }
 async function getEscalation(id) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_ESCALATION, [id]);
-    return rows[0] || null;
+    const client = await (0, client_1.escalations)();
+    const entry = await client.get(id);
+    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
 }
 async function getEscalationsByTaskId(taskId) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_ESCALATIONS_BY_TASK_ID, [taskId]);
-    return rows;
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({
+        taskId,
+        sortBy: 'created_at',
+        sortOrder: 'desc',
+        limit: LOOKUP_LIMIT,
+    });
+    return (0, map_1.toEscalationRecords)(rows);
 }
 async function getEscalationsByWorkflowId(workflowId) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_ESCALATIONS_BY_WORKFLOW_ID, [workflowId]);
-    return rows;
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({
+        workflowId,
+        sortBy: 'created_at',
+        sortOrder: 'desc',
+        limit: LOOKUP_LIMIT,
+    });
+    return (0, map_1.toEscalationRecords)(rows);
 }
 async function updateEscalationMetadata(id, patch) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.UPDATE_ESCALATION_METADATA, [id, JSON.stringify(patch)]);
-    return rows[0] || null;
+    const client = await (0, client_1.escalations)();
+    const entry = await client.update({ id, metadata: patch });
+    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
 }
 async function enrichEscalationRouting(id, metadataPatch, workflowFields) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.ENRICH_ESCALATION_ROUTING, [
+    const client = await (0, client_1.escalations)();
+    const entry = await client.update({
         id,
-        JSON.stringify(metadataPatch),
-        workflowFields.workflowType || null,
-        workflowFields.workflowId || null,
-        workflowFields.taskQueue || null,
-        workflowFields.taskId || null,
-    ]);
-    return rows[0] || null;
+        metadata: metadataPatch,
+        workflowType: workflowFields.workflowType,
+        workflowId: workflowFields.workflowId,
+        taskQueue: workflowFields.taskQueue,
+        taskId: workflowFields.taskId,
+    });
+    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
 }
 async function getEscalationsByOriginId(originId) {
-    const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_ESCALATIONS_BY_ORIGIN_ID, [originId]);
-    return rows;
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({
+        originId,
+        sortBy: 'created_at',
+        sortOrder: 'desc',
+        limit: LOOKUP_LIMIT,
+    });
+    return (0, map_1.toEscalationRecords)(rows);
 }
 // --- Metadata candidate key lookups -----------------------------------------
 async function findByMetadata(key, value, status, limit = 50, offset = 0) {
-    const pool = (0, db_1.getPool)();
-    const filter = JSON.stringify({ [key]: value });
-    const { rows } = await pool.query(sql_1.FIND_BY_METADATA, [filter, status || null, limit, offset]);
-    const total = rows.length > 0 ? parseInt(rows[0]._total, 10) : 0;
-    // Strip the window function column from results
-    const escalations = rows.map(({ _total, ...rest }) => rest);
-    return { escalations, total };
+    const client = await (0, client_1.escalations)();
+    const metadata = { [key]: value };
+    const [rows, total] = await Promise.all([
+        client.list({
+            metadata,
+            status,
+            orderBy: [
+                { column: 'priority', direction: 'asc' },
+                { column: 'created_at', direction: 'asc' },
+            ],
+            limit,
+            offset,
+        }),
+        client.count({ metadata, status }),
+    ]);
+    return { escalations: (0, map_1.toEscalationRecords)(rows), total };
 }
 /**
- * Atomic claim by metadata with inline RBAC.
- * The SQL WHERE clause enforces role membership — if the caller
- * doesn't have an allowed role, zero rows match and the claim
- * never happens. No pre-flight find, no TOCTOU.
+ * Atomic claim by metadata with inline RBAC and optional metadata merge.
+ * The SDK enforces the role filter in SQL — callers without an allowed role
+ * match zero rows. Returns `{ escalation, isExtension, candidatesExist }` or
+ * null when nothing was claimed.
  *
- * @param allowedRoles — roles the caller can claim (null = no filter / global access)
- * @returns `{ escalation, isExtension, candidatesExist }` or null
+ * @param allowedRoles — roles the caller can claim (null = no filter / global)
  */
 async function claimByMetadata(key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
-    const pool = (0, db_1.getPool)();
-    const filter = JSON.stringify({ [key]: value });
-    const metaPatch = metadata ? JSON.stringify(metadata) : null;
-    const roles = allowedRoles ?? null;
-    const { rows } = await pool.query(sql_1.CLAIM_BY_METADATA_GUARDED, [filter, userId, durationMinutes, metaPatch, roles]);
-    if (rows.length === 0)
+    const client = await (0, client_1.escalations)();
+    const result = await client.claimByMetadata({
+        key,
+        value,
+        assignee: userId,
+        durationMinutes,
+        roles: allowedRoles === null ? undefined : allowedRoles,
+        metadata,
+    });
+    if (!result.ok)
         return null;
-    const row = rows[0];
-    const { candidates_exist, prev_assigned_to, _total, ...rest } = row;
-    const escalation = rest;
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
     (0, publish_1.publishEscalationEvent)({
         type: 'escalation.claimed',
         source: 'service',
@@ -244,19 +306,22 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
     });
     return {
         escalation,
-        isExtension: prev_assigned_to === userId,
-        candidatesExist: parseInt(candidates_exist, 10),
+        isExtension: result.isExtension,
+        candidatesExist: result.candidatesExist,
     };
 }
 /**
- * Atomic resolve by metadata with signal guard.
+ * Atomic resolve by metadata with signal guard, in a single CTE.
  *
- * Single query, two outcomes:
- * 1. No signal_id → claim + resolve atomically. Returns { outcome: 'resolved', escalation }.
- * 2. signal_id present → resolve skipped. Returns { outcome: 'signal_required', signalId, escalationId, ... }
- *    so the caller can signal the workflow. conditionLT handles the rest.
+ * Signal-backed rows (those carrying `metadata.signal_id`) are NOT resolved
+ * here — long-tail signals the paused workflow and the workflow interceptor
+ * resolves durably. If the workflow is gone the signal fails and the row stays
+ * pending, which is the contract the route suite pins. This guard is long-tail
+ * business logic over the shared table, so it runs as one atomic statement on
+ * `hmsh_escalations` rather than through the generic SDK resolve.
  */
 async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, allowedRoles) {
+    await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
     const filter = JSON.stringify({ [key]: value });
     const payloadJson = JSON.stringify(resolverPayload);
@@ -267,8 +332,7 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
         return { outcome: 'not_found' };
     const row = rows[0];
     if (row.outcome === 'resolved') {
-        const { target_id, signal_id, target_workflow_id, target_workflow_type, target_task_queue, outcome, ...rest } = row;
-        const escalation = rest;
+        const escalation = (0, map_1.toEscalationRecord)(row);
         (0, publish_1.publishEscalationEvent)({
             type: 'escalation.resolved',
             source: 'service',
@@ -281,7 +345,7 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
         });
         return { outcome: 'resolved', escalation };
     }
-    // Signal-backed escalation — return the signal info for the caller
+    // Signal-backed escalation — return the signal info for the caller to deliver.
     return {
         outcome: 'signal_required',
         signalId: row.signal_id,

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

@@ -2,3 +2,4 @@ export * from './types';
 export * from './crud';
 export * from './bulk';
 export * from './queries';
+export { ensureEscalationCompatView } from './client';

package/build/services/escalation/index.js

@@ -14,7 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureEscalationCompatView = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 __exportStar(require("./bulk"), exports);
 __exportStar(require("./queries"), exports);
+var client_1 = require("./client");
+Object.defineProperty(exports, "ensureEscalationCompatView", { enumerable: true, get: function () { return client_1.ensureEscalationCompatView; } });

package/build/services/escalation/map.d.ts

@@ -0,0 +1,15 @@
+import type { Types } from '@hotmeshio/hotmesh';
+import type { LTEscalationRecord } from '../../types';
+type EscalationEntry = Types.EscalationEntry;
+/** SDK row → long-tail public record. */
+export declare function toEscalationRecord(entry: EscalationEntry): LTEscalationRecord;
+export declare function toEscalationRecords(entries: EscalationEntry[]): LTEscalationRecord[];
+/**
+ * Parse a TEXT/JSON-string field from the public input shape into the JSONB
+ * object the SDK expects. Returns `undefined` (field omitted) for empty/invalid
+ * input so the column stays NULL rather than storing garbage.
+ */
+export declare function toJsonObject(value: string | null | undefined): Record<string, unknown> | undefined;
+/** Parse an envelope string, always yielding an object (defaults to `{}`). */
+export declare function toEnvelopeObject(value: string | null | undefined): Record<string, unknown>;
+export {};

package/build/services/escalation/map.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEscalationRecord = toEscalationRecord;
+exports.toEscalationRecords = toEscalationRecords;
+exports.toJsonObject = toJsonObject;
+exports.toEnvelopeObject = toEnvelopeObject;
+/** Serialize a JSONB object column back to the TEXT form the public shape uses. */
+function toJsonText(value) {
+    return value == null ? null : JSON.stringify(value);
+}
+/** SDK row → long-tail public record. */
+function toEscalationRecord(entry) {
+    return {
+        id: entry.id,
+        type: entry.type ?? '',
+        subtype: entry.subtype ?? '',
+        description: entry.description,
+        status: entry.status,
+        priority: entry.priority,
+        task_id: entry.task_id,
+        origin_id: entry.origin_id,
+        parent_id: entry.parent_id,
+        workflow_id: entry.workflow_id,
+        task_queue: entry.task_queue,
+        workflow_type: entry.workflow_type,
+        signal_key: entry.signal_key,
+        role: entry.role ?? '',
+        assigned_to: entry.assigned_to,
+        assigned_until: entry.assigned_until,
+        resolved_at: entry.resolved_at,
+        claimed_at: entry.claimed_at,
+        envelope: entry.envelope == null ? '{}' : JSON.stringify(entry.envelope),
+        metadata: entry.metadata,
+        escalation_payload: toJsonText(entry.escalation_payload),
+        resolver_payload: toJsonText(entry.resolver_payload),
+        trace_id: entry.trace_id,
+        span_id: entry.span_id,
+        created_at: entry.created_at,
+        updated_at: entry.updated_at,
+    };
+}
+function toEscalationRecords(entries) {
+    return entries.map(toEscalationRecord);
+}
+/**
+ * Parse a TEXT/JSON-string field from the public input shape into the JSONB
+ * object the SDK expects. Returns `undefined` (field omitted) for empty/invalid
+ * input so the column stays NULL rather than storing garbage.
+ */
+function toJsonObject(value) {
+    if (value == null || value === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse an envelope string, always yielding an object (defaults to `{}`). */
+function toEnvelopeObject(value) {
+    return toJsonObject(value) ?? {};
+}