@hotmeshio/long-tail 0.25.0 → 0.25.2

package/build/api/escalations/batch-flag.d.ts

@@ -0,0 +1,19 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/** True when the row's wait declared `wakeOnFlag` (stored on its envelope at creation). */
+export declare function wakesOnFlag(envelope: unknown): boolean;
+/**
+ * Flag one pending key of a batch escalation (for example, `Missing`). The
+ * key stays pending and still fills. When the row's wait declared
+ * `wakeOnFlag`, the flag ends the wait and the row records its resolver.
+ */
+export declare function flagBatchItem(input: {
+    id: string;
+    itemKey: string;
+    label: string;
+    payload?: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/** Clear one key's flag while the row is pending. */
+export declare function unflagBatchItem(input: {
+    id: string;
+    itemKey: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/batch-flag.js

@@ -0,0 +1,138 @@
+"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.wakesOnFlag = wakesOnFlag;
+exports.flagBatchItem = flagBatchItem;
+exports.unflagBatchItem = unflagBatchItem;
+const escalationService = __importStar(require("../../services/escalation"));
+const escalation_1 = require("../../types/escalation");
+const helpers_1 = require("./helpers");
+const resolve_1 = require("./resolve");
+const LABEL_MAX = 128;
+/** True when the row's wait declared `wakeOnFlag` (stored on its envelope at creation). */
+function wakesOnFlag(envelope) {
+    let parsed = envelope;
+    if (typeof envelope === 'string') {
+        try {
+            parsed = JSON.parse(envelope);
+        }
+        catch {
+            return false;
+        }
+    }
+    return !!parsed && typeof parsed === 'object'
+        && parsed[escalation_1.ESCALATION_BATCH_KEYS.WAKE_ON_FLAG] === true;
+}
+/** Read and write gates shared by flag and unflag: 404 for a row the caller cannot see, 403 for one they cannot act on. */
+async function loadWritable(id, auth) {
+    const row = await escalationService.getEscalation(id);
+    if (!row || (await (0, helpers_1.assertReadAccess)(auth.userId, row)))
+        return { status: 404, error: 'Escalation not found' };
+    const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, row);
+    if (denied)
+        return denied;
+    return { row };
+}
+/**
+ * Flag one pending key of a batch escalation (for example, `Missing`). The
+ * key stays pending and still fills. When the row's wait declared
+ * `wakeOnFlag`, the flag ends the wait and the row records its resolver.
+ */
+async function flagBatchItem(input, auth) {
+    try {
+        const { id, itemKey, label, payload } = input;
+        if (!itemKey || typeof itemKey !== 'string')
+            return { status: 400, error: 'itemKey is required' };
+        if (!label || typeof label !== 'string' || label.length > LABEL_MAX) {
+            return { status: 400, error: `label is required (at most ${LABEL_MAX} characters)` };
+        }
+        if (payload !== undefined && (!payload || typeof payload !== 'object' || Array.isArray(payload))) {
+            return { status: 400, error: 'payload must be an object' };
+        }
+        const gate = await loadWritable(id, auth);
+        if (!('row' in gate))
+            return gate;
+        const wakes = wakesOnFlag(gate.row.envelope);
+        const result = await escalationService.flagBatchItem(id, itemKey, {
+            label,
+            ...(payload ? { payload } : {}),
+            actor: auth.userId,
+            ...(wakes ? { metadata: { resolved_by: auth.userId }, resolvedBy: await (0, resolve_1.resolverIdentity)(auth) } : {}),
+        });
+        return flagResult(result.outcome, itemKey, id, gate.row.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Clear one key's flag while the row is pending. */
+async function unflagBatchItem(input, auth) {
+    try {
+        const { id, itemKey } = input;
+        if (!itemKey || typeof itemKey !== 'string')
+            return { status: 400, error: 'itemKey is required' };
+        const gate = await loadWritable(id, auth);
+        if (!('row' in gate))
+            return gate;
+        const result = await escalationService.unflagBatchItem(id, itemKey);
+        return flagResult(result.outcome, itemKey, id, gate.row.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** Maps the flag outcome vocabulary onto HTTP results. */
+function flagResult(outcome, itemKey, id, workflowId) {
+    const refuse = (status, error) => ({ status, error, data: { error, outcome, itemKey } });
+    switch (outcome) {
+        case 'flagged':
+        case 'unflagged':
+            return { status: 200, data: { outcome, itemKey, escalationId: id } };
+        case 'completed':
+            return { status: 200, data: { outcome, itemKey, escalationId: id, workflowId } };
+        case 'not-found':
+            return refuse(404, 'Escalation not found');
+        case 'not-batch':
+            return refuse(400, 'Escalation is not a batch');
+        case 'unknown-item':
+            return refuse(400, 'itemKey is not in the declared batch');
+        case 'already-filled':
+            return refuse(409, 'This item is already in');
+        case 'not-flagged':
+            return refuse(409, 'This item has no flag');
+        default:
+            return refuse(409, 'Escalation is no longer pending');
+    }
+}

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

@@ -6,6 +6,8 @@ export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
 export { resolveBatchItem, resolveBatchItemBySignalKey, resolveBatchItemByMetadata } from './resolve-batch';
+export { flagBatchItem, unflagBatchItem } from './batch-flag';
+export { runRosterAction, ROSTER_ACTION_OUTCOMES } from './roster-action';
 export { accumulateItem, accumulateItemBySignalKey, accumulateItemByMetadata, removeItem, removeItemBySignalKey, removeItemByMetadata, getEscalationItems, getEscalationItemsBySignalKey, itemsView, } from './accumulate';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';

package/build/api/escalations/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRelatedRows = exports.getRelatedAggregates = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItemsBySignalKey = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItemsBySignalKey = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.ROSTER_ACTION_OUTCOMES = exports.runRosterAction = exports.unflagBatchItem = exports.flagBatchItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.getRelatedRows = exports.getRelatedAggregates = exports.timelineByFacet = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -37,6 +38,12 @@ var resolve_batch_1 = require("./resolve-batch");
 Object.defineProperty(exports, "resolveBatchItem", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItem; } });
 Object.defineProperty(exports, "resolveBatchItemBySignalKey", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemBySignalKey; } });
 Object.defineProperty(exports, "resolveBatchItemByMetadata", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemByMetadata; } });
+var batch_flag_1 = require("./batch-flag");
+Object.defineProperty(exports, "flagBatchItem", { enumerable: true, get: function () { return batch_flag_1.flagBatchItem; } });
+Object.defineProperty(exports, "unflagBatchItem", { enumerable: true, get: function () { return batch_flag_1.unflagBatchItem; } });
+var roster_action_1 = require("./roster-action");
+Object.defineProperty(exports, "runRosterAction", { enumerable: true, get: function () { return roster_action_1.runRosterAction; } });
+Object.defineProperty(exports, "ROSTER_ACTION_OUTCOMES", { enumerable: true, get: function () { return roster_action_1.ROSTER_ACTION_OUTCOMES; } });
 var accumulate_1 = require("./accumulate");
 Object.defineProperty(exports, "accumulateItem", { enumerable: true, get: function () { return accumulate_1.accumulateItem; } });
 Object.defineProperty(exports, "accumulateItemBySignalKey", { enumerable: true, get: function () { return accumulate_1.accumulateItemBySignalKey; } });

package/build/api/escalations/roster-action.d.ts

@@ -0,0 +1,37 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/** Outcomes a roster action answers with besides the act's own result. */
+export declare const ROSTER_ACTION_OUTCOMES: {
+    /** The action is limited to roles the person acting does not hold, and no badge rode the request. */
+    readonly NEEDS_BADGE: "needs_badge";
+    /** A badge rode the request, and its person does not hold the action's roles. */
+    readonly ROLE_REFUSED: "role_refused";
+    /** The badge expired or was spent; scan it again. */
+    readonly NOT_PRIMED: "not_primed";
+};
+export interface RosterActionInput {
+    /** The host row: the escalation whose form declares the roster. */
+    id: string;
+    /** The roster field. */
+    field: string;
+    /** The action's index among the field's actions. */
+    action: number;
+    /** The entry's key. */
+    entry: string;
+    /** A key-in's entered code. */
+    code?: string;
+    /** A badge grant: the act runs as its person. */
+    actingToken?: string;
+}
+/**
+ * Run one action a roster entry offers. The request is a pointer (field,
+ * action index, entry key) and never authority: the action is re-read from
+ * the host row's pinned form schema, the entry must be on the roster the
+ * server computes, the payload is built here from the declaration, and a
+ * role limit is checked against the person acting. The act then runs
+ * through the endpoint it names (resolve, batch fill, flag, unflag) under
+ * that person's own RBAC and `enforce_schema`.
+ *
+ * A badge is read first and spent only once the act is about to run; an
+ * act that does not land returns the use.
+ */
+export declare function runRosterAction(input: RosterActionInput, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/roster-action.js

@@ -0,0 +1,179 @@
+"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.ROSTER_ACTION_OUTCOMES = void 0;
+exports.runRosterAction = runRosterAction;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const roster_1 = require("../../services/escalation/roster");
+const acting_identity_1 = require("../../services/iam/acting-identity");
+const form_validation_1 = require("../../shared/form-validation");
+const batch_flag_1 = require("./batch-flag");
+const helpers_1 = require("./helpers");
+const resolve_1 = require("./resolve");
+const resolve_batch_1 = require("./resolve-batch");
+/** Outcomes a roster action answers with besides the act's own result. */
+exports.ROSTER_ACTION_OUTCOMES = {
+    /** The action is limited to roles the person acting does not hold, and no badge rode the request. */
+    NEEDS_BADGE: 'needs_badge',
+    /** A badge rode the request, and its person does not hold the action's roles. */
+    ROLE_REFUSED: 'role_refused',
+    /** The badge expired or was spent; scan it again. */
+    NOT_PRIMED: 'not_primed',
+};
+/** The roster's context on the server: the host row's own domains. */
+function hostContext(row) {
+    const { escalation, metadata, envelope, payload } = (0, form_validation_1.rosterRowContext)(row);
+    return { escalation, metadata, envelope, payload };
+}
+/**
+ * Run one action a roster entry offers. The request is a pointer (field,
+ * action index, entry key) and never authority: the action is re-read from
+ * the host row's pinned form schema, the entry must be on the roster the
+ * server computes, the payload is built here from the declaration, and a
+ * role limit is checked against the person acting. The act then runs
+ * through the endpoint it names (resolve, batch fill, flag, unflag) under
+ * that person's own RBAC and `enforce_schema`.
+ *
+ * A badge is read first and spent only once the act is about to run; an
+ * act that does not land returns the use.
+ */
+async function runRosterAction(input, auth) {
+    try {
+        if (!input?.id || typeof input.field !== 'string' || !Number.isInteger(input.action)
+            || typeof input.entry !== 'string' || !input.entry) {
+            return { status: 400, error: 'id, field, action and entry are required' };
+        }
+        // 1. The host row and its form, as the page that offered the action read them
+        const detail = await escalationService.getEscalationWithFormSchema(input.id);
+        if (!detail || (await (0, helpers_1.assertReadAccess)(auth.userId, detail.escalation))) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const host = detail.escalation;
+        const embedded = host.metadata?.form_schema;
+        const schema = (embedded && typeof embedded === 'object' ? embedded : detail.form_schema);
+        const fieldSchema = schema?.properties?.[input.field];
+        const def = (0, form_validation_1.readRosterDef)(fieldSchema);
+        const action = (0, form_validation_1.readRosterActions)(fieldSchema)[input.action];
+        if (!def || !action)
+            return { status: 409, error: 'This action is no longer offered' };
+        // 2. The entry, on the roster the server computes
+        const ctx = hostContext(host);
+        const roster = await (0, roster_1.loadRoster)(def, ctx);
+        const entry = roster.entries.find((e) => e.key === input.entry);
+        const kind = (0, form_validation_1.rosterActionKind)(action);
+        const batch = 'batch' in def.expected;
+        if (!entry || (kind === form_validation_1.ROSTER_ACTION_KINDS.RESOLVE ? !entry.row : !batch)) {
+            return { status: 409, error: 'This entry no longer offers that action' };
+        }
+        if (kind === form_validation_1.ROSTER_ACTION_KINDS.FILL && action.fill?.enterCode
+            && !(0, form_validation_1.enteredCodeMatches)(String(input.code ?? ''), entry.key, def.countedBy)) {
+            const error = `That code is not ${(0, form_validation_1.printedKeyCode)(entry.key, def.countedBy)}.`;
+            return { status: 422, error, data: { error, outcome: 'code_mismatch' } };
+        }
+        // 3. The person acting: the badge's person when one rides the request, read without spending it
+        let actor = auth;
+        if (input.actingToken) {
+            const peeked = await (0, acting_identity_1.peekActingAuth)(input.actingToken);
+            if (!peeked.ok)
+                return refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, peeked.error);
+            actor = peeked.auth;
+        }
+        if (!(await holdsRole(action, actor.userId))) {
+            return input.actingToken
+                ? refusal(403, exports.ROSTER_ACTION_OUTCOMES.ROLE_REFUSED, (0, form_validation_1.actionRefusal)(action))
+                : refusal(403, exports.ROSTER_ACTION_OUTCOMES.NEEDS_BADGE, (0, form_validation_1.actionRefusal)(action));
+        }
+        // 4. Spend the badge, run the act, and return the use when it does not land
+        let remaining;
+        if (input.actingToken) {
+            const spent = await (0, acting_identity_1.consumeActingGrant)(input.actingToken);
+            if (!spent.ok)
+                return refusal(401, exports.ROSTER_ACTION_OUTCOMES.NOT_PRIMED, spent.error);
+            remaining = spent.grant.remaining;
+        }
+        const result = await runAct(kind, action, entry, host.id, ctx, input.code, actor);
+        if (input.actingToken && result.status >= 300) {
+            await (0, acting_identity_1.refundActingGrant)(input.actingToken, false);
+            return result;
+        }
+        if (input.actingToken && result.data && typeof result.data === 'object') {
+            result.data = { ...result.data, acting: { remaining } };
+        }
+        return result;
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function holdsRole(action, userId) {
+    if (!action.roles?.length)
+        return true;
+    const [roles, superadmin] = await Promise.all([
+        userService.getUserRoles(userId),
+        userService.isSuperAdmin(userId),
+    ]);
+    return (0, form_validation_1.holdsActionRole)(action, roles.map((r) => r.role), superadmin);
+}
+function runAct(kind, action, entry, hostId, ctx, code, actor) {
+    switch (kind) {
+        case form_validation_1.ROSTER_ACTION_KINDS.RESOLVE:
+            return (0, resolve_1.resolveEscalation)({
+                id: String(entry.row.escalation.id),
+                resolverPayload: (0, form_validation_1.interpolatePayload)(action.resolverPayload, entry.row),
+            }, actor);
+        case form_validation_1.ROSTER_ACTION_KINDS.FILL:
+            return (0, resolve_batch_1.resolveBatchItem)({
+                id: hostId,
+                itemKey: entry.key,
+                resolverPayload: {
+                    ...(0, form_validation_1.interpolatePayload)(action.fill?.payload ?? {}, ctx),
+                    ...(action.fill?.enterCode ? { [form_validation_1.ENTERED_CODE_KEY]: String(code).trim() } : {}),
+                },
+            }, actor);
+        case form_validation_1.ROSTER_ACTION_KINDS.FLAG:
+            return (0, batch_flag_1.flagBatchItem)({
+                id: hostId,
+                itemKey: entry.key,
+                label: action.flag.label,
+                ...(action.flag.payload ? { payload: (0, form_validation_1.interpolatePayload)(action.flag.payload, ctx) } : {}),
+            }, actor);
+        default:
+            return (0, batch_flag_1.unflagBatchItem)({ id: hostId, itemKey: entry.key }, actor);
+    }
+}
+function refusal(status, outcome, error) {
+    return { status, error, data: { error, outcome } };
+}

package/build/api/scan-codes/choice-roles.d.ts

@@ -0,0 +1,3 @@
+import type { ScanChoice } from '../../types';
+/** True when the person may run the choice: it names no roles, or they hold one (superadmin always). */
+export declare function holdsChoiceRole(choice: Pick<ScanChoice, 'roles'>, userId: string): Promise<boolean>;

package/build/api/scan-codes/choice-roles.js

@@ -0,0 +1,48 @@
+"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.holdsChoiceRole = holdsChoiceRole;
+const userService = __importStar(require("../../services/user"));
+const x_lt_actions_1 = require("../../shared/form-validation/x-lt-actions");
+/** True when the person may run the choice: it names no roles, or they hold one (superadmin always). */
+async function holdsChoiceRole(choice, userId) {
+    if (!choice.roles?.length)
+        return true;
+    const [roles, superadmin] = await Promise.all([
+        userService.getUserRoles(userId),
+        userService.isSuperAdmin(userId),
+    ]);
+    return (0, x_lt_actions_1.holdsActionRole)(choice, roles.map((r) => r.role), superadmin);
+}

package/build/api/scan-codes/choice.js

@@ -41,6 +41,8 @@ const identity_1 = require("./identity");
 const grant_1 = require("./grant");
 const helpers_1 = require("../escalations/helpers");
 const context_1 = require("./context");
+const choice_roles_1 = require("./choice-roles");
+const x_lt_actions_1 = require("../../shared/form-validation/x-lt-actions");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
 /**
@@ -85,6 +87,12 @@ async function executeScanChoice(input, auth) {
             effectiveAuth = peeked.auth;
             grant = peeked.grant;
         }
+        // 2b. A choice limited to roles runs only for a person holding one: with
+        // no badge it parks for one, and a badge without the role is refused
+        // without spending it.
+        if (choice.roles?.length && !(await (0, choice_roles_1.holdsChoiceRole)(choice, effectiveAuth.userId))) {
+            return stampPointer(grant ? (0, context_1.refused)((0, x_lt_actions_1.actionRefusal)(choice)) : (0, context_1.notPrimed)({ rule }, (0, x_lt_actions_1.actionRefusal)(choice)), rule, input);
+        }
         // 3. With no live grant, a choice that needs a badge parks for the next
         // badge scan before any row is read, whatever the station may read.
         if (!grant && choice.requireActingIdentity

package/build/api/scan-codes/fill-labels.d.ts

@@ -0,0 +1,15 @@
+import { type LTEscalationRecord, type ScanFillParams, type ScanScheme } from '../../types';
+/** How a batch entry reads: its label from the row's per-key map, or its code. */
+export type EntryLabeler = (key: string, code: string) => string;
+/** The code as the package prints it on a GTIN scheme, as scanned otherwise. */
+export declare function printedCode(code: string, scheme: ScanScheme): string;
+/**
+ * The labeler a fill step declares, or null without `labels`. The map is
+ * read from the batch row (`envelope.<map>` or `metadata.<map>`) and keyed by
+ * batch key. With a `label` template, `{label.<path>}` reads the entry's map
+ * value and `{code}` its printed code; without one, a text value is the
+ * label. An entry the map does not name reads as its code.
+ */
+export declare function entryLabeler(fill: ScanFillParams, row: LTEscalationRecord, scheme: ScanScheme): EntryLabeler | null;
+/** Each open entry's label, in batch order, one per distinct label. */
+export declare function pendingLabels(pending: string[], codeOf: (key: string) => string, label: EntryLabeler): string[];

package/build/api/scan-codes/fill-labels.js

@@ -0,0 +1,99 @@
+"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.printedCode = printedCode;
+exports.entryLabeler = entryLabeler;
+exports.pendingLabels = pendingLabels;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const ctx_path_1 = require("../../shared/form-validation/ctx-path");
+const x_lt_bind_1 = require("../../shared/form-validation/x-lt-bind");
+const types_1 = require("../../types");
+const LABEL_TOKEN = /\{label\.([^}]+)\}/g;
+const CODE_TOKEN = '{code}';
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** A JSON column as an object: the row's envelope arrives as text. */
+function asObject(v) {
+    if (isRecord(v))
+        return v;
+    if (typeof v !== 'string' || !v)
+        return null;
+    try {
+        const parsed = JSON.parse(v);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The code as the package prints it on a GTIN scheme, as scanned otherwise. */
+function printedCode(code, scheme) {
+    return scheme.encoding === types_1.SCAN_ENCODINGS.GTIN ? scanCodeService.displayGtin(code) : code;
+}
+/**
+ * The labeler a fill step declares, or null without `labels`. The map is
+ * read from the batch row (`envelope.<map>` or `metadata.<map>`) and keyed by
+ * batch key. With a `label` template, `{label.<path>}` reads the entry's map
+ * value and `{code}` its printed code; without one, a text value is the
+ * label. An entry the map does not name reads as its code.
+ */
+function entryLabeler(fill, row, scheme) {
+    if (!fill.labels)
+        return null;
+    const map = (0, ctx_path_1.resolveCtxPath)(fill.labels, { envelope: asObject(row.envelope), metadata: asObject(row.metadata) });
+    const labels = isRecord(map) ? map : {};
+    return (key, code) => {
+        const printed = printedCode(code, scheme);
+        const value = labels[key];
+        if (value === undefined || value === null)
+            return printed;
+        if (fill.label) {
+            const text = fill.label
+                .split(CODE_TOKEN).join(printed)
+                .replace(LABEL_TOKEN, (_t, path) => {
+                const v = isRecord(value) ? (0, x_lt_bind_1.getDeep)(value, path) : undefined;
+                return v === undefined || v === null || typeof v === 'object' ? '' : String(v);
+            })
+                .trim();
+            return text || printed;
+        }
+        return typeof value === 'string' && value ? value : printed;
+    };
+}
+/** Each open entry's label, in batch order, one per distinct label. */
+function pendingLabels(pending, codeOf, label) {
+    return [...new Set(pending.map((key) => label(key, codeOf(key))))];
+}

package/build/api/scan-codes/hold.js

@@ -78,6 +78,7 @@ async function heldSubject(step, ctx, row) {
             },
         } : {}),
         ...(claimant ? { claimedBy: claimant } : {}),
+        ...(hold.show ? { show: hold.show } : {}),
     };
 }
 /** The canonical code for the held row, as the station would scan it. */

package/build/api/scan-codes/present.js

@@ -37,6 +37,7 @@ exports.presentStep = presentStep;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const types_1 = require("../../types");
 const identity_1 = require("./identity");
+const choice_roles_1 = require("./choice-roles");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
 const context_1 = require("./context");
@@ -77,9 +78,12 @@ async function presentStep(step, ctx) {
     // configured — presenting a one-button screen would be a pointless tap. An
     // unsatisfied identity requirement still presents (the client's badge
     // stop-over), never a silent or misattributed execution.
+    // A choice limited to roles is withheld from a person without one of them,
+    // so the station asks for a badge of that role.
+    const roleHeld = await Promise.all((step.choices ?? []).map((choice) => (0, choice_roles_1.holdsChoiceRole)(choice, ctx.auth.userId)));
     const only = step.choices?.length === 1 ? step.choices[0] : undefined;
     const autoSelect = step.autoSelectSingle === true && only !== undefined && !only.confirm;
-    if (autoSelect && (!only.requireActingIdentity || satisfied)) {
+    if (autoSelect && (!only.requireActingIdentity || satisfied) && roleHeld[0]) {
         return (0, verbs_1.dispatchChoiceVerb)({ query: step.query, verb: only.verb, params: only.params }, ctx, escalation);
     }
     const choices = (step.choices ?? []).map((choice, index) => ({
@@ -88,8 +92,9 @@ async function presentStep(step, ctx) {
         verb: choice.verb,
         ...(choice.confirm ? { confirm: choice.confirm } : {}),
         ...(choice.requireActingIdentity ? { requireActingIdentity: true } : {}),
+        ...(choice.roles?.length ? { roles: choice.roles } : {}),
         ...(choice.code ? { code: choice.code } : {}),
-        withheld: !!choice.requireActingIdentity && !satisfied,
+        withheld: (!!choice.requireActingIdentity && !satisfied) || !roleHeld[index],
     }));
     return {
         status: 200,