@hotmeshio/long-tail 0.4.13 → 0.4.14

package/build/api/escalations/helpers.d.ts

@@ -7,4 +7,18 @@ export declare function checkBulkPermission(userId: string, ids: string[]): Prom
     status: 403;
     error: string;
 }>;
+/**
+ * Resolve an optional assignee external_id to an internal userId.
+ * When omitted, returns the caller's userId from auth.
+ */
+export declare function resolveAssignee(assignee: string | undefined, auth: {
+    userId: string;
+}): Promise<{
+    userId: string;
+} | {
+    error: {
+        status: number;
+        error: string;
+    };
+}>;
 export declare function publishBulkClaimEvents(ids: string[], assignedTo: string): void;

package/build/api/escalations/helpers.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getVisibleRoles = getVisibleRoles;
 exports.validateIds = validateIds;
 exports.checkBulkPermission = checkBulkPermission;
+exports.resolveAssignee = resolveAssignee;
 exports.publishBulkClaimEvents = publishBulkClaimEvents;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
@@ -64,6 +65,19 @@ async function checkBulkPermission(userId, ids) {
     }
     return { allowed: true };
 }
+/**
+ * Resolve an optional assignee external_id to an internal userId.
+ * When omitted, returns the caller's userId from auth.
+ */
+async function resolveAssignee(assignee, auth) {
+    if (!assignee)
+        return { userId: auth.userId };
+    const user = await userService.getUserByExternalId(assignee);
+    if (!user) {
+        return { error: { status: 404, error: `User not found for external_id: ${assignee}` } };
+    }
+    return { userId: user.id };
+}
 function publishBulkClaimEvents(ids, assignedTo) {
     for (const id of ids) {
         (0, publish_1.publishEscalationEvent)({

package/build/api/escalations/index.d.ts

@@ -4,3 +4,4 @@ export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './sin
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation } from './resolve';
+export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -24,3 +24,7 @@ Object.defineProperty(exports, "bulkEscalate", { enumerable: true, get: function
 Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function () { return bulk_1.bulkTriage; } });
 var resolve_1 = require("./resolve");
 Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: function () { return resolve_1.resolveEscalation; } });
+var metadata_1 = require("./metadata");
+Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });
+Object.defineProperty(exports, "claimByMetadata", { enumerable: true, get: function () { return metadata_1.claimByMetadata; } });
+Object.defineProperty(exports, "resolveByMetadata", { enumerable: true, get: function () { return metadata_1.resolveByMetadata; } });

package/build/api/escalations/metadata.d.ts

@@ -0,0 +1,56 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Find escalations by a metadata key-value pair.
+ *
+ * Uses JSONB containment (`@>`) backed by a GIN index.
+ * Results are RBAC-scoped to the caller's visible roles.
+ *
+ * @param input.key — metadata field name (e.g. `"orderId"`)
+ * @param input.value — metadata field value (e.g. `"order-123"`)
+ * @param input.status — optional status filter (e.g. `"pending"`)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function findByMetadata(input: {
+    key: string;
+    value: string;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Claim an escalation by metadata key-value pair.
+ *
+ * Finds one available (pending + unassigned/expired) escalation matching
+ * the metadata and claims it atomically. Optionally resolves an assignee
+ * from an external_id.
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.durationMinutes — claim duration (default 30)
+ * @param input.assignee — optional external_id of the user to claim as
+ * @returns `{ status: 200, data: { escalation, isExtension } }`
+ */
+export declare function claimByMetadata(input: {
+    key: string;
+    value: string;
+    durationMinutes?: number;
+    assignee?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve an escalation by metadata key-value pair.
+ *
+ * Finds the pending escalation, auto-claims if unclaimed, then delegates
+ * to the standard resolve logic (supports all 5 resolution paths).
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.resolverPayload — resolution data for the workflow
+ * @param input.assignee — optional external_id of the resolving user
+ * @returns result from the standard resolve endpoint
+ */
+export declare function resolveByMetadata(input: {
+    key: string;
+    value: string;
+    resolverPayload: Record<string, any>;
+    assignee?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -0,0 +1,178 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findByMetadata = findByMetadata;
+exports.claimByMetadata = claimByMetadata;
+exports.resolveByMetadata = resolveByMetadata;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const publish_1 = require("../../lib/events/publish");
+const helpers_1 = require("./helpers");
+/**
+ * Find escalations by a metadata key-value pair.
+ *
+ * Uses JSONB containment (`@>`) backed by a GIN index.
+ * Results are RBAC-scoped to the caller's visible roles.
+ *
+ * @param input.key — metadata field name (e.g. `"orderId"`)
+ * @param input.value — metadata field value (e.g. `"order-123"`)
+ * @param input.status — optional status filter (e.g. `"pending"`)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+async function findByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        const result = await escalationService.findByMetadata(input.key, input.value, input.status, input.limit, input.offset);
+        // RBAC: scope to visible roles
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles) {
+            const roleSet = new Set(visibleRoles);
+            result.escalations = result.escalations.filter(e => roleSet.has(e.role));
+            result.total = result.escalations.length;
+        }
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Claim an escalation by metadata key-value pair.
+ *
+ * Finds one available (pending + unassigned/expired) escalation matching
+ * the metadata and claims it atomically. Optionally resolves an assignee
+ * from an external_id.
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.durationMinutes — claim duration (default 30)
+ * @param input.assignee — optional external_id of the user to claim as
+ * @returns `{ status: 200, data: { escalation, isExtension } }`
+ */
+async function claimByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
+        if ('error' in resolved)
+            return resolved.error;
+        const claimUserId = resolved.userId;
+        // RBAC: find the candidate to check role membership before atomic claim
+        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
+        if (candidates.escalations.length === 0) {
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        }
+        const candidate = candidates.escalations[0];
+        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdmin) {
+            const userHasRole = await userService.hasRole(claimUserId, candidate.role);
+            if (!userHasRole) {
+                return { status: 403, error: `User must have the "${candidate.role}" role to claim this escalation` };
+            }
+        }
+        const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes);
+        if (!result) {
+            return { status: 409, error: 'Escalation not available for claim' };
+        }
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.claimed',
+            source: 'api',
+            workflowId: result.escalation.workflow_id || '',
+            workflowName: result.escalation.workflow_type || '',
+            taskQueue: result.escalation.task_queue || '',
+            escalationId: result.escalation.id,
+            status: 'claimed',
+            data: { assigned_to: claimUserId },
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Resolve an escalation by metadata key-value pair.
+ *
+ * Finds the pending escalation, auto-claims if unclaimed, then delegates
+ * to the standard resolve logic (supports all 5 resolution paths).
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.resolverPayload — resolution data for the workflow
+ * @param input.assignee — optional external_id of the resolving user
+ * @returns result from the standard resolve endpoint
+ */
+async function resolveByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        if (!input.resolverPayload) {
+            return { status: 400, error: 'resolverPayload is required' };
+        }
+        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
+        if (candidates.escalations.length === 0) {
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        }
+        const escalation = candidates.escalations[0];
+        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
+        if ('error' in resolved)
+            return resolved.error;
+        const resolveUserId = resolved.userId;
+        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdmin) {
+            const userHasRole = await userService.hasRole(resolveUserId, escalation.role);
+            if (!userHasRole) {
+                return { status: 403, error: `User must have the "${escalation.role}" role` };
+            }
+        }
+        // Auto-claim if unclaimed or expired
+        const isClaimed = escalation.assigned_to &&
+            escalation.assigned_until &&
+            new Date(escalation.assigned_until) > new Date();
+        if (!isClaimed) {
+            await escalationService.claimEscalation(escalation.id, resolveUserId, 5);
+        }
+        // Delegate to the full resolve logic (handles all 5 resolution paths)
+        const { resolveEscalation } = await Promise.resolve().then(() => __importStar(require('./resolve')));
+        return resolveEscalation({ id: escalation.id, resolverPayload: input.resolverPayload }, auth);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/bin/ltc.js

@@ -134,6 +134,23 @@ escCmd.command('release <id>')
 escCmd.command('resolve <id>')
     .requiredOption('--data <json>', 'Resolver payload (JSON string)')
     .action(wrap(esc.resolveEscalation));
+escCmd.command('find-by-meta <key> <value>')
+    .description('Find escalations by metadata key-value pair')
+    .option('--status <status>', 'Filter by status')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(esc.findByMetadata));
+escCmd.command('claim-by-meta <key> <value>')
+    .description('Claim an escalation by metadata key-value pair')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .option('--assignee <external_id>', 'Claim on behalf of user (external_id)')
+    .action(wrap(esc.claimByMetadata));
+escCmd.command('resolve-by-meta <key> <value>')
+    .description('Resolve an escalation by metadata key-value pair')
+    .option('--data <json>', 'Resolver payload (JSON string)')
+    .option('--assignee <external_id>', 'Resolve on behalf of user (external_id)')
+    .action(wrap(esc.resolveByMetadata));
 // ── Workflows ────────────────────────────────────────────────────────────
 const wfCmd = commander_1.program.command('workflows').alias('wf').description('Manage durable workflows');
 wfCmd.command('list')

package/build/lib/cli/commands/escalations.d.ts

@@ -16,4 +16,13 @@ export declare function releaseEscalation(id: string): Promise<void>;
 export declare function resolveEscalation(id: string, opts: {
     data?: string;
 }): Promise<void>;
+export declare function findByMetadata(key: string, value: string, opts: ListOptions): Promise<void>;
+export declare function claimByMetadata(key: string, value: string, opts: {
+    duration?: string;
+    assignee?: string;
+}): Promise<void>;
+export declare function resolveByMetadata(key: string, value: string, opts: {
+    data?: string;
+    assignee?: string;
+}): Promise<void>;
 export {};

package/build/lib/cli/commands/escalations.js

@@ -8,6 +8,9 @@ exports.getEscalation = getEscalation;
 exports.claimEscalation = claimEscalation;
 exports.releaseEscalation = releaseEscalation;
 exports.resolveEscalation = resolveEscalation;
+exports.findByMetadata = findByMetadata;
+exports.claimByMetadata = claimByMetadata;
+exports.resolveByMetadata = resolveByMetadata;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
@@ -67,3 +70,36 @@ async function resolveEscalation(id, opts) {
     });
     console.log(`\n  ${picocolors_1.default.green('✓')} Resolved ${picocolors_1.default.dim(id)}\n`);
 }
+// --- Metadata candidate key commands ----------------------------------------
+async function findByMetadata(key, value, opts) {
+    const params = new URLSearchParams({ key, value });
+    if (opts.status)
+        params.set('status', opts.status);
+    if (opts.limit)
+        params.set('limit', opts.limit);
+    const data = await (0, client_1.apiFetch)(`/escalations/by-metadata?${params}`);
+    (0, format_1.output)(data, data.escalations || [], COLUMNS, opts);
+}
+async function claimByMetadata(key, value, opts) {
+    const body = { key, value };
+    if (opts.duration)
+        body.durationMinutes = parseInt(opts.duration, 10);
+    if (opts.assignee)
+        body.assignee = opts.assignee;
+    const data = await (0, client_1.apiFetch)('/escalations/claim-by-metadata', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${picocolors_1.default.dim(data.escalation?.id || '')} by ${key}=${value}\n`);
+}
+async function resolveByMetadata(key, value, opts) {
+    const resolverPayload = opts.data ? JSON.parse(opts.data) : {};
+    const body = { key, value, resolverPayload };
+    if (opts.assignee)
+        body.assignee = opts.assignee;
+    await (0, client_1.apiFetch)('/escalations/resolve-by-metadata', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    console.log(`\n  ${picocolors_1.default.green('✓')} Resolved by ${key}=${value}\n`);
+}

package/build/lib/db/schemas/010_metadata_gin.sql

@@ -0,0 +1,5 @@
+-- GIN index for JSONB containment queries on lt_escalations.metadata.
+-- Enables efficient lookups like: WHERE metadata @> '{"orderId":"order-123"}'::jsonb
+-- Uses jsonb_path_ops (smaller, faster for @> queries).
+CREATE INDEX IF NOT EXISTS idx_lt_escalations_metadata
+  ON lt_escalations USING GIN (metadata jsonb_path_ops);

package/build/routes/escalations/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const list_1 = require("./list");
 const bulk_1 = require("./bulk");
+const metadata_1 = require("./metadata");
 const single_1 = require("./single");
 const resolve_1 = require("./resolve");
 const router = (0, express_1.Router)();
@@ -12,6 +13,8 @@ const router = (0, express_1.Router)();
 // POST /release-expired, PATCH /priority, POST /bulk-claim,
 // POST /bulk-assign, PATCH /bulk-escalate, POST /bulk-triage
 (0, bulk_1.registerBulkRoutes)(router);
+// GET /by-metadata, POST /claim-by-metadata, POST /resolve-by-metadata
+(0, metadata_1.registerMetadataRoutes)(router);
 // PATCH /:id/escalate, GET /by-workflow/:workflowId,
 // GET /:id, POST /:id/claim, POST /:id/release
 (0, single_1.registerSingleRoutes)(router);

package/build/routes/escalations/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { Router } from 'express';
+/**
+ * Register metadata-based escalation lookup routes.
+ * Must be registered BEFORE parameterized /:id routes.
+ */
+export declare function registerMetadataRoutes(router: Router): void;

package/build/routes/escalations/metadata.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMetadataRoutes = registerMetadataRoutes;
+const api = __importStar(require("../../api/escalations"));
+/**
+ * Register metadata-based escalation lookup routes.
+ * Must be registered BEFORE parameterized /:id routes.
+ */
+function registerMetadataRoutes(router) {
+    /**
+     * GET /api/escalations/by-metadata
+     * Find escalations by a metadata key-value pair.
+     * Query: key, value, status?, limit?, offset?
+     */
+    router.get('/by-metadata', async (req, res) => {
+        const result = await api.findByMetadata({
+            key: req.query.key,
+            value: req.query.value,
+            status: req.query.status,
+            limit: req.query.limit ? parseInt(req.query.limit, 10) : undefined,
+            offset: req.query.offset ? parseInt(req.query.offset, 10) : undefined,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/claim-by-metadata
+     * Find and claim an escalation by metadata key-value pair.
+     * Body: { key, value, durationMinutes?, assignee? }
+     */
+    router.post('/claim-by-metadata', async (req, res) => {
+        const result = await api.claimByMetadata({
+            key: req.body?.key,
+            value: req.body?.value,
+            durationMinutes: req.body?.durationMinutes,
+            assignee: req.body?.assignee,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/resolve-by-metadata
+     * Find and resolve an escalation by metadata key-value pair.
+     * Body: { key, value, resolverPayload, assignee? }
+     */
+    router.post('/resolve-by-metadata', async (req, res) => {
+        const result = await api.resolveByMetadata({
+            key: req.body?.key,
+            value: req.body?.value,
+            resolverPayload: req.body?.resolverPayload,
+            assignee: req.body?.assignee,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+}

package/build/sdk/index.d.ts

@@ -150,6 +150,25 @@ export declare function createClient(options?: LTClientOptions): {
             ids: string[];
             hint?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        findByMetadata: (input: {
+            key: string;
+            value: string;
+            status?: string;
+            limit?: number;
+            offset?: number;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        claimByMetadata: (input: {
+            key: string;
+            value: string;
+            durationMinutes?: number;
+            assignee?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveByMetadata: (input: {
+            key: string;
+            value: string;
+            resolverPayload: Record<string, any>;
+            assignee?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
     };
     workflows: {
         invoke: (input: {

package/build/sdk/index.js

@@ -130,6 +130,9 @@ function createClient(options = {}) {
             bulkAssign: bindAuth(escalationsApi.bulkAssign, auth),
             bulkEscalate: bindAuth(escalationsApi.bulkEscalate, auth),
             bulkTriage: bindAuth(escalationsApi.bulkTriage, auth),
+            findByMetadata: bindAuth(escalationsApi.findByMetadata, auth),
+            claimByMetadata: bindAuth(escalationsApi.claimByMetadata, auth),
+            resolveByMetadata: bindAuth(escalationsApi.resolveByMetadata, auth),
         },
         // ── Workflows ──────────────────────────────────────────────────────────
         workflows: {

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

@@ -45,3 +45,8 @@ export declare function enrichEscalationRouting(id: string, metadataPatch: Recor
     taskId?: string;
 }): Promise<LTEscalationRecord | null>;
 export declare function getEscalationsByOriginId(originId: string): Promise<LTEscalationRecord[]>;
+export declare function findByMetadata(key: string, value: string, status?: string, limit?: number, offset?: number): Promise<{
+    escalations: LTEscalationRecord[];
+    total: number;
+}>;
+export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number): Promise<ClaimResult | null>;

package/build/services/escalation/crud.js

@@ -14,6 +14,8 @@ exports.getEscalationsByWorkflowId = getEscalationsByWorkflowId;
 exports.updateEscalationMetadata = updateEscalationMetadata;
 exports.enrichEscalationRouting = enrichEscalationRouting;
 exports.getEscalationsByOriginId = getEscalationsByOriginId;
+exports.findByMetadata = findByMetadata;
+exports.claimByMetadata = claimByMetadata;
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
 async function createEscalation(input) {
@@ -148,3 +150,28 @@ async function getEscalationsByOriginId(originId) {
     const { rows } = await pool.query(sql_1.GET_ESCALATIONS_BY_ORIGIN_ID, [originId]);
     return 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 [countResult, dataResult] = await Promise.all([
+        pool.query(sql_1.COUNT_BY_METADATA, [filter, status || null]),
+        pool.query(sql_1.FIND_BY_METADATA, [filter, status || null, limit, offset]),
+    ]);
+    return {
+        escalations: dataResult.rows,
+        total: parseInt(countResult.rows[0].count, 10),
+    };
+}
+async function claimByMetadata(key, value, userId, durationMinutes = 30) {
+    const pool = (0, db_1.getPool)();
+    const filter = JSON.stringify({ [key]: value });
+    const { rows } = await pool.query(sql_1.CLAIM_BY_METADATA, [filter, userId, durationMinutes]);
+    if (rows.length === 0)
+        return null;
+    const row = rows[0];
+    return {
+        escalation: row,
+        isExtension: row.prev_assigned_to === userId,
+    };
+}

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

@@ -19,3 +19,8 @@ export declare const BULK_RESOLVE_FOR_TRIAGE = "UPDATE lt_escalations\nSET statu
 export declare const UPDATE_ESCALATION_METADATA = "UPDATE lt_escalations\nSET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb,\n    updated_at = NOW()\nWHERE id = $1\nRETURNING *";
 export declare const ENRICH_ESCALATION_ROUTING = "UPDATE lt_escalations\nSET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb,\n    workflow_type = COALESCE(workflow_type, $3),\n    workflow_id = COALESCE(workflow_id, $4),\n    task_queue = COALESCE(task_queue, $5),\n    task_id = COALESCE(task_id, $6),\n    updated_at = NOW()\nWHERE id = $1\nRETURNING *";
 export declare const LIST_DISTINCT_TYPES = "SELECT DISTINCT type FROM lt_escalations ORDER BY type";
+/** Find escalations by a single metadata key-value pair. */
+export declare const FIND_BY_METADATA = "SELECT * FROM lt_escalations\nWHERE metadata @> $1::jsonb\n  AND ($2::text IS NULL OR status = $2)\nORDER BY priority ASC, created_at ASC\nLIMIT $3 OFFSET $4";
+export declare const COUNT_BY_METADATA = "SELECT COUNT(*) FROM lt_escalations\nWHERE metadata @> $1::jsonb\n  AND ($2::text IS NULL OR status = $2)";
+/** Atomic claim by metadata: find one available escalation and claim it. */
+export declare const CLAIM_BY_METADATA = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n      assigned_to IS NULL\n      OR assigned_until <= NOW()\n      OR assigned_to = $2\n    )\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT * FROM updated";

package/build/services/escalation/sql.js

@@ -3,7 +3,7 @@
 // Escalation SQL – externalized from crud.ts, bulk.ts, queries.ts
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_DISTINCT_TYPES = exports.ENRICH_ESCALATION_ROUTING = exports.UPDATE_ESCALATION_METADATA = exports.BULK_RESOLVE_FOR_TRIAGE = exports.BULK_ESCALATE_TO_ROLE = exports.BULK_ASSIGN = exports.BULK_CLAIM = exports.GET_ESCALATIONS_BY_ORIGIN_ID = exports.GET_ESCALATIONS_BY_WORKFLOW_ID = exports.GET_ESCALATIONS_BY_TASK_ID = exports.GET_ESCALATION = exports.ESCALATE_TO_ROLE = exports.RELEASE_EXPIRED_CLAIMS = exports.RELEASE_ESCALATION = exports.GET_ESCALATION_ROLES = exports.UPDATE_ESCALATIONS_PRIORITY = exports.RESOLVE_ESCALATION = exports.CLAIM_ESCALATION = exports.CREATE_ESCALATION = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.CLAIM_BY_METADATA = exports.COUNT_BY_METADATA = exports.FIND_BY_METADATA = exports.LIST_DISTINCT_TYPES = exports.ENRICH_ESCALATION_ROUTING = exports.UPDATE_ESCALATION_METADATA = exports.BULK_RESOLVE_FOR_TRIAGE = exports.BULK_ESCALATE_TO_ROLE = exports.BULK_ASSIGN = exports.BULK_CLAIM = exports.GET_ESCALATIONS_BY_ORIGIN_ID = exports.GET_ESCALATIONS_BY_WORKFLOW_ID = exports.GET_ESCALATIONS_BY_TASK_ID = exports.GET_ESCALATION = exports.ESCALATE_TO_ROLE = exports.RELEASE_EXPIRED_CLAIMS = exports.RELEASE_ESCALATION = exports.GET_ESCALATION_ROLES = exports.UPDATE_ESCALATIONS_PRIORITY = exports.RESOLVE_ESCALATION = exports.CLAIM_ESCALATION = exports.CREATE_ESCALATION = exports.ENSURE_ROLE_EXISTS = void 0;
 // --- Role management -------------------------------------------------------
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 // --- Single-record CRUD ---------------------------------------------------
@@ -133,3 +133,41 @@ SET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb,
 WHERE id = $1
 RETURNING *`;
 exports.LIST_DISTINCT_TYPES = 'SELECT DISTINCT type FROM lt_escalations ORDER BY type';
+// --- Metadata candidate key lookups -----------------------------------------
+/** Find escalations by a single metadata key-value pair. */
+exports.FIND_BY_METADATA = `\
+SELECT * FROM lt_escalations
+WHERE metadata @> $1::jsonb
+  AND ($2::text IS NULL OR status = $2)
+ORDER BY priority ASC, created_at ASC
+LIMIT $3 OFFSET $4`;
+exports.COUNT_BY_METADATA = `\
+SELECT COUNT(*) FROM lt_escalations
+WHERE metadata @> $1::jsonb
+  AND ($2::text IS NULL OR status = $2)`;
+/** Atomic claim by metadata: find one available escalation and claim it. */
+exports.CLAIM_BY_METADATA = `\
+WITH target AS (
+  SELECT id, assigned_to
+  FROM lt_escalations
+  WHERE metadata @> $1::jsonb
+    AND status = 'pending'
+    AND (
+      assigned_to IS NULL
+      OR assigned_until <= NOW()
+      OR assigned_to = $2
+    )
+  ORDER BY priority ASC, created_at ASC
+  LIMIT 1
+  FOR UPDATE SKIP LOCKED
+),
+updated AS (
+  UPDATE lt_escalations e
+  SET assigned_to = $2,
+      claimed_at = NOW(),
+      assigned_until = NOW() + INTERVAL '1 minute' * $3
+  FROM target t
+  WHERE e.id = t.id
+  RETURNING e.*, t.assigned_to AS prev_assigned_to
+)
+SELECT * FROM updated`;