@hotmeshio/long-tail 0.5.12 → 0.6.0

package/README.md

@@ -302,6 +302,7 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](https
 | [Compiler](https://github.com/hotmeshio/long-tail/blob/main/docs/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
 | [CLI](https://github.com/hotmeshio/long-tail/blob/main/docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
 | [Escalation Strategies](https://github.com/hotmeshio/long-tail/blob/main/docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
+| [Faceted Routing](https://github.com/hotmeshio/long-tail/blob/main/docs/faceted-routing.md) | Query and atomically claim the queue by facets; dispatcher pattern |
 | [SDK](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
 | [Architecture](https://github.com/hotmeshio/long-tail/blob/main/docs/architecture.md) | Project structure, conventions, discovery |
 | [Cloud](https://github.com/hotmeshio/long-tail/blob/main/docs/cloud.md) | AWS ECS, GCP Cloud Run, Docker |

package/build/api/escalations/bulk.js

@@ -236,7 +236,15 @@ async function startTriageWorkflow(escalation, hint, userId, client) {
         }
         catch { }
     }
-    const triageWorkflowId = `triage-${escalation.id}-${Date.now()}`;
+    // Deterministic id: an escalation is terminal-once, so `triage-<id>` is unique for
+    // its lifetime. A retry re-targets the same triage job (HotMesh upserts jobs by
+    // (workflowId, app_id)) instead of spawning a duplicate. NOTE: the bulk flow
+    // resolves the set FIRST (bulkResolveForTriage) then starts triage per row, so a
+    // crash between the set-resolve and a given start leaves that escalation
+    // resolved-but-not-triaged — a retry's resolveMany returns only freshly-resolved
+    // rows and will not re-drive it. Closing that gap needs a durable orchestrator
+    // (resolve+triage in one workflow); tracked as a follow-up, not fixed here.
+    const triageWorkflowId = `triage-${escalation.id}`;
     const triageEnvelope = {
         data: {
             escalationId: escalation.id,

package/build/api/escalations/cancel.js

@@ -37,7 +37,6 @@ exports.cancelSingleEscalation = cancelSingleEscalation;
 exports.bulkCancel = bulkCancel;
 const escalationService = __importStar(require("../../services/escalation"));
 const helpers_1 = require("./helpers");
-const userService = __importStar(require("../../services/user"));
 /**
  * Cancel a single escalation. The caller must hold global escalation access
  * or the escalation's role.
@@ -52,12 +51,11 @@ async function cancelSingleEscalation(input, auth) {
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
-        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
-        if (!hasGlobal) {
-            const hasRole = await userService.hasRole(auth.userId, escalation.role);
-            if (!hasRole)
-                return { status: 403, error: 'Forbidden' };
-        }
+        // Cancel ("delete") is a write verb: write_all may cancel any item in the role,
+        // write_self may cancel an item assigned to them, read-only members may not.
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return denied;
         const cancelled = await escalationService.cancelEscalation(id);
         if (!cancelled) {
             return { status: 409, error: 'Escalation is not cancellable (already terminal)' };

package/build/api/escalations/claim.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.claimEscalation = claimEscalation;
 exports.releaseEscalation = releaseEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
-const userService = __importStar(require("../../services/user"));
 const helpers_1 = require("./helpers");
 /**
  * Claim a pending escalation for the authenticated user.
@@ -57,20 +56,16 @@ async function claimEscalation(input, auth) {
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
-        // Happy path: try claim assuming user has the role
-        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
-        if (!hasGlobal) {
-            const userHasRole = await userService.hasRole(auth.userId, escalation.role);
-            if (!userHasRole) {
-                // Unhappy path: provision role if flag present, then retry
-                const provisioned = await (0, helpers_1.ensureRoleMembership)(auth.userId, escalation.role, auth.userId, provisionIfAbsent);
-                if (!provisioned) {
-                    return {
-                        status: 403,
-                        error: `You must have the "${escalation.role}" role to claim this escalation`,
-                    };
-                }
-            }
+        // Write-scope gate: write_all may claim any item in the role; write_self may
+        // only (re)claim an item already assigned to them (extension); read-only and
+        // non-members are denied. Global access bypasses.
+        const writeDenied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (writeDenied) {
+            // Unhappy path: a global caller may JIT-provision their own role membership
+            // (ensureRoleMembership requires global authority, so this no-ops otherwise).
+            const provisioned = await (0, helpers_1.ensureRoleMembership)(auth.userId, escalation.role, auth.userId, provisionIfAbsent);
+            if (!provisioned)
+                return writeDenied;
         }
         const result = await escalationService.claimEscalation(id, auth.userId, durationMinutes);
         if (!result) {
@@ -94,6 +89,14 @@ async function claimEscalation(input, auth) {
  */
 async function releaseEscalation(input, auth) {
     try {
+        const escalation = await escalationService.getEscalation(input.id);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        // Releasing returns the item to the pool — a queue-management verb. A
+        // self-scope owner cannot release (it would forfeit access to their own item).
+        const manageDenied = await (0, helpers_1.assertQueueManageAccess)(auth.userId, escalation.role);
+        if (manageDenied)
+            return manageDenied;
         const result = await escalationService.releaseEscalation(input.id, auth.userId);
         if (!result) {
             return { status: 409, error: 'Escalation not found or not claimed by you' };

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

@@ -26,4 +26,10 @@ export declare function createEscalation(input: {
     envelope?: string;
     metadata?: Record<string, any>;
     escalation_payload?: string;
+    origin_id?: string;
+    parent_id?: string;
+    task_id?: string;
+    workflow_id?: string;
+    task_queue?: string;
+    workflow_type?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/create.js

@@ -35,7 +35,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
-const userService = __importStar(require("../../services/user"));
 const helpers_1 = require("./helpers");
 // ── Create ────────────────────────────────────────────────────────────────
 /**
@@ -65,13 +64,11 @@ async function createEscalation(input, auth) {
         if (!role || typeof role !== 'string') {
             return { status: 400, error: 'role is required' };
         }
-        // RBAC: caller must hold the target role or be superadmin
-        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
-        if (!hasGlobal) {
-            const userHasRole = await userService.hasRole(auth.userId, role);
-            if (!userHasRole) {
-                return { status: 403, error: `You must hold the "${role}" role or be a superadmin to create escalations for it` };
-            }
+        // RBAC: creating an escalation injects work into a role's queue — a write_all
+        // (or global) action. read-only and self-scope members may not create.
+        const denied = await (0, helpers_1.assertQueueManageAccess)(auth.userId, role);
+        if (denied) {
+            return { status: 403, error: `You must have write access to the "${role}" role or be a superadmin to create escalations for it` };
         }
         const escalation = await escalationService.createEscalation({
             type,
@@ -82,6 +79,12 @@ async function createEscalation(input, auth) {
             envelope: input.envelope ?? '{}',
             metadata: input.metadata,
             escalation_payload: input.escalation_payload,
+            origin_id: input.origin_id,
+            parent_id: input.parent_id,
+            task_id: input.task_id,
+            workflow_id: input.workflow_id,
+            task_queue: input.task_queue,
+            workflow_type: input.workflow_type,
         });
         // Event published by service layer (services/escalation/crud.ts)
         return { status: 201, data: escalation };

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

@@ -0,0 +1,18 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import type { FacetQuery } from '../../types/facets';
+/** Item-level faceted search over a pond, scoped to the caller's role. */
+export declare function searchByFacets(query: FacetQuery, auth: LTApiAuth): Promise<LTApiResult>;
+/** Batch-claim complete origin groups in priority order, assigned to the calling operator. */
+export declare function claimGroups(input: {
+    query: FacetQuery;
+    limit?: number;
+    durationMinutes?: number;
+    sizeFacet?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/** Batch-claim individual rows (FOR UPDATE SKIP LOCKED), assigned to the calling operator. */
+export declare function claimByFacets(input: {
+    query: FacetQuery;
+    limit?: number;
+    durationMinutes?: number;
+    allOrNone?: boolean;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/facets.js

@@ -0,0 +1,115 @@
+"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.searchByFacets = searchByFacets;
+exports.claimGroups = claimGroups;
+exports.claimByFacets = claimByFacets;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+// ── Faceted escalation surface (public) ──────────────────────────────────────
+//
+// The faceted-routing read/claim primitives, exposed on the public API so example
+// workflows (and dependent projects) reach the pond the same way the dashboard,
+// MCP, and CLI do — through api/, which calls services/. Faceted routing is the
+// whole-pond dispatcher pattern: searching surfaces OTHER operators' items and
+// claiming takes ownership of unassigned work. So the gate is the broad scope, not
+// mere membership — read_all to search the pond, write_all to claim from it. A
+// global principal (superadmin / admin) passes unfiltered. Self-scope members work
+// only their own assigned items, through the by-id paths — not the pond surface.
+async function callerMaySearchPond(userId, role) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return true;
+    const scope = await userService.getRoleScope(userId, role);
+    return scope?.read === 'all';
+}
+async function callerMayClaimPond(userId, role) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return true;
+    const scope = await userService.getRoleScope(userId, role);
+    return scope?.write === 'all';
+}
+/** Item-level faceted search over a pond, scoped to the caller's role. */
+async function searchByFacets(query, auth) {
+    try {
+        if (!query?.role)
+            return { status: 400, error: 'role is required' };
+        if (!(await callerMaySearchPond(auth.userId, query.role))) {
+            return { status: 403, error: `You must hold the "${query.role}" role with full (read_all) scope or be a superadmin` };
+        }
+        const result = await escalationService.searchByFacets(query);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Batch-claim complete origin groups in priority order, assigned to the calling operator. */
+async function claimGroups(input, auth) {
+    try {
+        if (!input.query?.role)
+            return { status: 400, error: 'role is required' };
+        if (!(await callerMayClaimPond(auth.userId, input.query.role))) {
+            return { status: 403, error: `You must hold the "${input.query.role}" role with claim (write_all) scope or be a superadmin` };
+        }
+        const groups = await escalationService.claimGroups(input.query, auth.userId, {
+            limit: input.limit,
+            durationMinutes: input.durationMinutes,
+            sizeFacet: input.sizeFacet,
+        });
+        return { status: 200, data: { groups } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Batch-claim individual rows (FOR UPDATE SKIP LOCKED), assigned to the calling operator. */
+async function claimByFacets(input, auth) {
+    try {
+        if (!input.query?.role)
+            return { status: 400, error: 'role is required' };
+        if (!(await callerMayClaimPond(auth.userId, input.query.role))) {
+            return { status: 403, error: `You must hold the "${input.query.role}" role with claim (write_all) scope or be a superadmin` };
+        }
+        const claimed = await escalationService.claimByFacets(input.query, auth.userId, {
+            limit: input.limit,
+            durationMinutes: input.durationMinutes,
+            allOrNone: input.allOrNone,
+        });
+        return { status: 200, data: { claimed } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -1,6 +1,73 @@
 export { hasGlobalEscalationAccess } from '../../services/user';
-export declare function getVisibleRoles(userId: string): Promise<string[] | undefined>;
+/**
+ * Read-scope partition for escalation search/list/stats. Splits the user's roles
+ * into the breadth at which they may SEARCH:
+ * - `global`   → sees every role's queue (superadmin, admin/admin); no role filter
+ * - `allRoles` → roles where read_scope='all' (whole queue visible)
+ * - `selfRoles`→ roles where read_scope='self' (only items assigned to them)
+ *
+ * The caller feeds allRoles + selfRoles + the user's id into the scoped search
+ * predicate. `effectiveScope` folds admin/superadmin memberships to read='all'.
+ */
+export interface EscalationReadScope {
+    global: boolean;
+    allRoles: string[];
+    selfRoles: string[];
+}
+export declare function getEscalationReadScope(userId: string): Promise<EscalationReadScope>;
 export declare function validateIds(ids: unknown): ids is string[];
+/**
+ * Write-scope partition for metadata-driven resolve. Splits the user's roles by
+ * the breadth at which they may ACT (claim/ack/delete):
+ * - `global`   → may act on any role's queue; no filter
+ * - `allRoles` → write_scope='all' (act on any item in the role)
+ * - `selfRoles`→ write_scope='self' (act only on items assigned to them)
+ * write_scope='none' roles are excluded — read-only memberships cannot act.
+ */
+export interface EscalationWriteScope {
+    global: boolean;
+    allRoles: string[];
+    selfRoles: string[];
+}
+export declare function getEscalationWriteScope(userId: string): Promise<EscalationWriteScope>;
+/**
+ * Authorize a READ of one escalation (get single). Global access sees all;
+ * otherwise the user must hold the role with read_scope='all', OR read_scope='self'
+ * with the escalation assigned to them. Returns an error result, or null if allowed.
+ */
+export declare function assertReadAccess(userId: string, escalation: {
+    role: string;
+    assigned_to?: string | null;
+}): Promise<{
+    status: number;
+    error: string;
+} | null>;
+/**
+ * Authorize a WRITE on one escalation (claim/ack/delete by id). Global access may
+ * act on all; otherwise write_scope='all' may act on any item in the role, and
+ * write_scope='self' may act only on items assigned to the user. read-only
+ * ('none') and non-members are denied. Returns an error result, or null if allowed.
+ *
+ * This is an authorization gate over durable ownership (a self-scope user cannot
+ * reassign items to themselves), so the subsequent atomic mutation is the single
+ * source of truth — no claim race is introduced here.
+ */
+export declare function assertWriteAccess(userId: string, escalation: {
+    role: string;
+    assigned_to?: string | null;
+}): Promise<{
+    status: number;
+    error: string;
+} | null>;
+/**
+ * Require write_scope='all' (or global) for a queue-management verb — release and
+ * escalate move an item out of the user's hands, so self-scope owners (who only
+ * fill in their own item) and read-only members may not perform them.
+ */
+export declare function assertQueueManageAccess(userId: string, role: string): Promise<{
+    status: number;
+    error: string;
+} | null>;
 export declare function checkBulkPermission(userId: string, ids: string[]): Promise<{
     allowed: true;
 } | {
@@ -19,6 +86,8 @@ export interface ProvisionIfAbsent {
     roles?: Array<{
         role: string;
         type?: string;
+        read_scope?: string;
+        write_scope?: string;
     }>;
 }
 /**

package/build/api/escalations/helpers.js

@@ -34,8 +34,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasGlobalEscalationAccess = void 0;
-exports.getVisibleRoles = getVisibleRoles;
+exports.getEscalationReadScope = getEscalationReadScope;
 exports.validateIds = validateIds;
+exports.getEscalationWriteScope = getEscalationWriteScope;
+exports.assertReadAccess = assertReadAccess;
+exports.assertWriteAccess = assertWriteAccess;
+exports.assertQueueManageAccess = assertQueueManageAccess;
 exports.checkBulkPermission = checkBulkPermission;
 exports.resolveAssignee = resolveAssignee;
 exports.ensureRoleMembership = ensureRoleMembership;
@@ -47,15 +51,98 @@ const publish_1 = require("../../lib/events/publish");
 // Re-export from service layer for use by escalation API modules
 var user_1 = require("../../services/user");
 Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return user_1.hasGlobalEscalationAccess; } });
-async function getVisibleRoles(userId) {
-    if (await userService.hasGlobalEscalationAccess(userId))
-        return undefined;
+async function getEscalationReadScope(userId) {
+    if (await userService.hasGlobalEscalationAccess(userId)) {
+        return { global: true, allRoles: [], selfRoles: [] };
+    }
     const userRoles = await userService.getUserRoles(userId);
-    return userRoles.map((r) => r.role);
+    const allRoles = [];
+    const selfRoles = [];
+    for (const r of userRoles) {
+        const eff = userService.effectiveScope(r.type, r.read_scope, r.write_scope);
+        if (eff.read === 'all')
+            allRoles.push(r.role);
+        else
+            selfRoles.push(r.role);
+    }
+    return { global: false, allRoles, selfRoles };
 }
 function validateIds(ids) {
     return Array.isArray(ids) && ids.length > 0;
 }
+async function getEscalationWriteScope(userId) {
+    if (await userService.hasGlobalEscalationAccess(userId)) {
+        return { global: true, allRoles: [], selfRoles: [] };
+    }
+    const userRoles = await userService.getUserRoles(userId);
+    const allRoles = [];
+    const selfRoles = [];
+    for (const r of userRoles) {
+        const eff = userService.effectiveScope(r.type, r.read_scope, r.write_scope);
+        if (eff.write === 'all')
+            allRoles.push(r.role);
+        else if (eff.write === 'self')
+            selfRoles.push(r.role);
+    }
+    return { global: false, allRoles, selfRoles };
+}
+/**
+ * Authorize a READ of one escalation (get single). Global access sees all;
+ * otherwise the user must hold the role with read_scope='all', OR read_scope='self'
+ * with the escalation assigned to them. Returns an error result, or null if allowed.
+ */
+async function assertReadAccess(userId, escalation) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return null;
+    const scope = await userService.getRoleScope(userId, escalation.role);
+    if (!scope)
+        return { status: 403, error: 'Not authorized to view this escalation' };
+    if (scope.read === 'all')
+        return null;
+    if (escalation.assigned_to && escalation.assigned_to === userId)
+        return null;
+    return { status: 403, error: 'Not authorized to view this escalation' };
+}
+/**
+ * Authorize a WRITE on one escalation (claim/ack/delete by id). Global access may
+ * act on all; otherwise write_scope='all' may act on any item in the role, and
+ * write_scope='self' may act only on items assigned to the user. read-only
+ * ('none') and non-members are denied. Returns an error result, or null if allowed.
+ *
+ * This is an authorization gate over durable ownership (a self-scope user cannot
+ * reassign items to themselves), so the subsequent atomic mutation is the single
+ * source of truth — no claim race is introduced here.
+ */
+async function assertWriteAccess(userId, escalation) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return null;
+    const scope = await userService.getRoleScope(userId, escalation.role);
+    const write = scope ? scope.write : 'none';
+    if (write === 'all')
+        return null;
+    if (write === 'self') {
+        if (escalation.assigned_to && escalation.assigned_to === userId)
+            return null;
+        return {
+            status: 403,
+            error: `You may only act on escalations assigned to you in the "${escalation.role}" role`,
+        };
+    }
+    return { status: 403, error: `You do not have write access to the "${escalation.role}" role` };
+}
+/**
+ * Require write_scope='all' (or global) for a queue-management verb — release and
+ * escalate move an item out of the user's hands, so self-scope owners (who only
+ * fill in their own item) and read-only members may not perform them.
+ */
+async function assertQueueManageAccess(userId, role) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return null;
+    const scope = await userService.getRoleScope(userId, role);
+    if (scope && scope.write === 'all')
+        return null;
+    return { status: 403, error: `You do not have permission to manage the "${role}" queue` };
+}
 async function checkBulkPermission(userId, ids) {
     if (await userService.hasGlobalEscalationAccess(userId))
         return { allowed: true };
@@ -92,7 +179,9 @@ async function resolveAssignee(assignee, auth, provisionIfAbsent) {
     if (!hasAuthority) {
         return { error: { status: 403, error: 'Only superadmin or admin can provision users on claim' } };
     }
-    // Provision the user
+    // Provision the user. The onboarding/customer flow declares the work-surface
+    // scope (e.g. read_self + write_self) so the provisioned user sees and acts on
+    // only their own pre-claimed item.
     const created = await userService.createUser({
         external_id: assignee,
         display_name: provisionIfAbsent.displayName || assignee,
@@ -100,6 +189,8 @@ async function resolveAssignee(assignee, auth, provisionIfAbsent) {
         roles: (provisionIfAbsent.roles || []).map((r) => ({
             role: r.role,
             type: (r.type || 'member'),
+            read_scope: r.read_scope,
+            write_scope: r.write_scope,
         })),
     });
     return { userId: created.id };
@@ -121,7 +212,10 @@ async function ensureRoleMembership(userId, requiredRole, callerUserId, provisio
         return false;
     // Add the role — idempotent (ON CONFLICT DO NOTHING)
     try {
-        await userService.addUserRole(userId, requiredRole, (declaredRole.type || 'member'));
+        await userService.addUserRole(userId, requiredRole, (declaredRole.type || 'member'), {
+            read_scope: declaredRole.read_scope,
+            write_scope: declaredRole.write_scope,
+        });
     }
     catch { /* already has it */ }
     return true;

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

@@ -1,8 +1,9 @@
 export { createEscalation } from './create';
-export { listEscalations, listAvailableEscalations, listDistinctTypes, getEscalationStats } from './list';
+export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacetKeys, getEscalationStats } from './list';
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
-export { resolveEscalation, resolveBySignalKey } from './resolve';
+export { resolveEscalation, resolveBySignalKey, resolveByIds } from './resolve';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
+export { searchByFacets, claimGroups, claimByFacets } from './facets';

package/build/api/escalations/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveBySignalKey = 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.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveByIds = exports.resolveBySignalKey = 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.listFacetKeys = 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");
 Object.defineProperty(exports, "listEscalations", { enumerable: true, get: function () { return list_1.listEscalations; } });
 Object.defineProperty(exports, "listAvailableEscalations", { enumerable: true, get: function () { return list_1.listAvailableEscalations; } });
 Object.defineProperty(exports, "listDistinctTypes", { enumerable: true, get: function () { return list_1.listDistinctTypes; } });
+Object.defineProperty(exports, "listFacetKeys", { enumerable: true, get: function () { return list_1.listFacetKeys; } });
 Object.defineProperty(exports, "getEscalationStats", { enumerable: true, get: function () { return list_1.getEscalationStats; } });
 var single_1 = require("./single");
 Object.defineProperty(exports, "getEscalation", { enumerable: true, get: function () { return single_1.getEscalation; } });
@@ -25,6 +26,7 @@ Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function (
 var resolve_1 = require("./resolve");
 Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: function () { return resolve_1.resolveEscalation; } });
 Object.defineProperty(exports, "resolveBySignalKey", { enumerable: true, get: function () { return resolve_1.resolveBySignalKey; } });
+Object.defineProperty(exports, "resolveByIds", { enumerable: true, get: function () { return resolve_1.resolveByIds; } });
 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; } });
@@ -32,3 +34,7 @@ Object.defineProperty(exports, "resolveByMetadata", { enumerable: true, get: fun
 var cancel_1 = require("./cancel");
 Object.defineProperty(exports, "cancelSingleEscalation", { enumerable: true, get: function () { return cancel_1.cancelSingleEscalation; } });
 Object.defineProperty(exports, "bulkCancel", { enumerable: true, get: function () { return cancel_1.bulkCancel; } });
+var facets_1 = require("./facets");
+Object.defineProperty(exports, "searchByFacets", { enumerable: true, get: function () { return facets_1.searchByFacets; } });
+Object.defineProperty(exports, "claimGroups", { enumerable: true, get: function () { return facets_1.claimGroups; } });
+Object.defineProperty(exports, "claimByFacets", { enumerable: true, get: function () { return facets_1.claimByFacets; } });

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

@@ -1,4 +1,15 @@
 import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+import type { FacetRange, FacetOrder } from '../../types';
+/** Faceted-query elements a human caller may add to the scoped list/available query. */
+export interface FacetInput {
+    roles?: string[];
+    facets?: Record<string, any>;
+    block?: Record<string, any>[];
+    range?: FacetRange[];
+    exists?: string[];
+    available?: boolean;
+    orderBy?: FacetOrder[];
+}
 /**
  * List escalations with optional filters.
  *
@@ -31,7 +42,7 @@ export declare function listEscalations(input: {
     sort_by?: string;
     order?: string;
     search?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
+} & FacetInput, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * List escalations available for claim (pending and not actively claimed).
  *
@@ -59,7 +70,15 @@ export declare function listAvailableEscalations(input: {
     sort_by?: string;
     order?: string;
     search?: string;
-}, auth: LTApiAuth): Promise<LTApiResult>;
+} & FacetInput, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List the distinct top-level metadata facet KEYS visible to the caller. Powers the
+ * faceted-query UI's key autocomplete — only keys that actually exist in the caller's
+ * (role-scoped) escalations are offered, never description-only text.
+ *
+ * @returns `{ status: 200, data: { keys: string[] } }`
+ */
+export declare function listFacetKeys(_input: unknown, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * List all distinct escalation type values.
  *