@hotmeshio/long-tail 0.25.1 → 0.25.3

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

@@ -40,6 +40,7 @@ const resolve_batch_1 = require("../escalations/resolve-batch");
 const escalation_1 = require("../../types/escalation");
 const types_1 = require("../../types");
 const context_1 = require("./context");
+const fill_labels_1 = require("./fill-labels");
 const grant_1 = require("./grant");
 const locate_1 = require("./locate");
 const subject_1 = require("./subject");
@@ -60,6 +61,18 @@ function codeOf(key, separator) {
 function keysFor(keys, target, separator) {
     return keys.filter((k) => codeOf(k, separator) === target);
 }
+/** Labeled pending entries read as one line; labels may carry commas. */
+const LABEL_JOIN = '; ';
+/** The `{fill.pending}` and `{fill.next}` values for the open keys. */
+function pendingCopy(pending, separator, labeler) {
+    const code = (key) => codeOf(key, separator);
+    if (!labeler) {
+        const codes = [...new Set(pending.map(code))];
+        return { pending: codes, ...(codes.length ? { next: codes[0] } : {}) };
+    }
+    const labels = (0, fill_labels_1.pendingLabels)(pending, code, labeler);
+    return { pending: labels.join(LABEL_JOIN), ...(labels.length ? { next: labels[0] } : {}) };
+}
 function progress(batch, filledNow) {
     const remaining = Math.max(0, batch.pending.length - filledNow);
     return { filled: batch.keys.length - remaining, total: batch.keys.length, remaining };
@@ -82,10 +95,12 @@ async function fillStep(step, ctx) {
     if (!batch)
         return (0, context_1.conflict)('the held row is not a batch');
     // 2. Which open slot this scan fills, or why none
+    const labeler = (0, fill_labels_1.entryLabeler)(options, row, ctx.scheme);
+    const open = pendingCopy(batch.pending, separator, labeler);
     const tpl = {
         ...(0, context_1.templateContext)(ctx),
         fill: {
-            pending: [...new Set(batch.pending.map((k) => codeOf(k, separator)))],
+            ...open,
             total: batch.keys.length,
             filled: batch.keys.length - batch.pending.length,
         },
@@ -96,9 +111,10 @@ async function fillStep(step, ctx) {
         const markdown = declared.length
             ? `All ${declared.length} of these are already checked off.`
             : scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_UNEXPECTED, tpl);
-        const expected = ctx.scheme.encoding === types_1.SCAN_ENCODINGS.GTIN
-            ? tpl.fill.pending.map((code) => scanCodeService.displayGtin(code))
-            : tpl.fill.pending;
+        const codes = [...new Set(batch.pending.map((k) => codeOf(k, separator)))];
+        const expected = labeler
+            ? (0, fill_labels_1.pendingLabels)(batch.pending, (k) => codeOf(k, separator), labeler)
+            : codes.map((code) => (0, fill_labels_1.printedCode)(code, ctx.scheme));
         return (0, context_1.refused)(markdown, {
             refusal: { markdown, expected },
             progress: progress(batch, 0),
@@ -125,6 +141,7 @@ async function fillStep(step, ctx) {
             const data = result.data;
             const done = data.outcome === 'completed';
             const filled = progress(batch, batch.pending.length - (done ? 0 : (data.remaining ?? 0)));
+            const next = pendingCopy(batch.pending.filter((k) => k !== itemKey), separator, labeler).next;
             return (0, context_1.withDone)({
                 status: 200,
                 data: {
@@ -134,7 +151,7 @@ async function fillStep(step, ctx) {
                     progress: filled,
                     ...(done ? { clearSubject: true } : {}),
                 },
-            }, step, { ...tpl, fill: { ...tpl.fill, ...filled } });
+            }, step, { ...tpl, fill: { ...tpl.fill, ...filled, next } });
         }
         const outcome = result.data?.outcome;
         if (outcome === 'duplicate-item')

package/build/routes/escalations/resolve.js

@@ -126,6 +126,51 @@ function registerResolveRoutes(router) {
         }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/:id/flag-batch-item
+     * Flag ONE pending key of a batch escalation (e.g. `Missing`). The key stays
+     * pending and still fills; a wait declared with `wakeOnFlag` ends on the flag.
+     * Body: { itemKey: string, label: string, payload?: Record<string, any> }
+     */
+    router.post('/:id/flag-batch-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.flagBatchItem({ id: req.params.id, itemKey: req.body?.itemKey, label: req.body?.label, payload: req.body?.payload }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/unflag-batch-item
+     * Clear ONE key's flag while the batch escalation is pending.
+     * Body: { itemKey: string }
+     */
+    router.post('/:id/unflag-batch-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.unflagBatchItem({ id: req.params.id, itemKey: req.body?.itemKey }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/roster-action
+     * Run one action a roster entry offers on this row's form. The server
+     * re-reads the action from the row's form schema, checks the entry and any
+     * role limit, and runs the act as the person acting: the badged person when
+     * X-LT-Acting-Token rides the request (spent only when the act runs).
+     * Body: { field: string, action: number, entry: string, code?: string }
+     */
+    router.post('/:id/roster-action', async (req, res) => {
+        const token = req.headers[acting_1.ACTING_TOKEN_HEADER];
+        const result = await api.runRosterAction({
+            id: req.params.id,
+            field: req.body?.field,
+            action: req.body?.action,
+            entry: req.body?.entry,
+            code: req.body?.code,
+            actingToken: typeof token === 'string' && token ? token : undefined,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
      * Resolve a pending escalation with a human-provided payload. Routes by

package/build/sdk/index.d.ts

@@ -247,6 +247,17 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             restrictRoles?: string[];
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        flagBatchItem: (input: {
+            id: string;
+            itemKey: string;
+            label: string;
+            payload?: Record<string, any>;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        unflagBatchItem: (input: {
+            id: string;
+            itemKey: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        runRosterAction: (input: import("../api/escalations/roster-action").RosterActionInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         accumulate: (input: {
             id: string;
         } & import("../api/escalations/accumulate").AccumulateItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;

package/build/sdk/index.js

@@ -146,6 +146,9 @@ function createClient(options = {}) {
             resolveBatchItem: bindAuth(escalationsApi.resolveBatchItem, auth),
             resolveBatchItemBySignalKey: bindAuth(escalationsApi.resolveBatchItemBySignalKey, auth),
             resolveBatchItemByMetadata: bindAuth(escalationsApi.resolveBatchItemByMetadata, auth),
+            flagBatchItem: bindAuth(escalationsApi.flagBatchItem, auth),
+            unflagBatchItem: bindAuth(escalationsApi.unflagBatchItem, auth),
+            runRosterAction: bindAuth(escalationsApi.runRosterAction, auth),
             // Open accumulation: add and remove held items, read the ordered collection.
             accumulate: bindAuth(escalationsApi.accumulateItem, auth),
             accumulateBySignalKey: bindAuth(escalationsApi.accumulateItemBySignalKey, auth),

package/build/services/escalation/batch-flag.d.ts

@@ -0,0 +1,25 @@
+import type { FlagBatchItemOutcome, LTEscalationRecord, UnflagBatchItemOutcome } from '../../types';
+export interface FlagBatchItemInput {
+    label: string;
+    payload?: Record<string, any>;
+    actor?: string;
+    metadata?: Record<string, any>;
+    resolvedBy?: {
+        id: string;
+        email?: string;
+    };
+}
+export interface BatchFlagOutcome<O extends string> {
+    outcome: O;
+    /** The post-write row; null on every failure outcome. */
+    escalation: LTEscalationRecord | null;
+}
+/**
+ * Flag one pending key of a batch escalation in a single SDK statement. The
+ * key stays pending. A row whose wait declared `wakeOnFlag` resolves in the
+ * same statement and its workflow wakes; that publishes `escalation.resolved`,
+ * any other flag `escalation.updated`. Failures publish nothing.
+ */
+export declare function flagBatchItem(id: string, itemKey: string, input: FlagBatchItemInput): Promise<BatchFlagOutcome<FlagBatchItemOutcome>>;
+/** Clear one key's flag while the row is pending; publishes `escalation.updated`. */
+export declare function unflagBatchItem(id: string, itemKey: string): Promise<BatchFlagOutcome<UnflagBatchItemOutcome>>;

package/build/services/escalation/batch-flag.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagBatchItem = flagBatchItem;
+exports.unflagBatchItem = unflagBatchItem;
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Flag one pending key of a batch escalation in a single SDK statement. The
+ * key stays pending. A row whose wait declared `wakeOnFlag` resolves in the
+ * same statement and its workflow wakes; that publishes `escalation.resolved`,
+ * any other flag `escalation.updated`. Failures publish nothing.
+ */
+async function flagBatchItem(id, itemKey, input) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.flagBatchItem({ id, itemKey, ...input });
+    if (!result.ok)
+        return { outcome: result.outcome, escalation: null };
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    publishFlagChange(escalation, itemKey, result.outcome === 'completed');
+    return { outcome: result.outcome, escalation };
+}
+/** Clear one key's flag while the row is pending; publishes `escalation.updated`. */
+async function unflagBatchItem(id, itemKey) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.unflagBatchItem({ id, itemKey });
+    if (!result.ok)
+        return { outcome: result.outcome, escalation: null };
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    publishFlagChange(escalation, itemKey, false);
+    return { outcome: result.outcome, escalation };
+}
+function publishFlagChange(escalation, itemKey, completed) {
+    (0, crud_1.publishEscalationChange)({
+        type: completed ? 'escalation.resolved' : 'escalation.updated',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: completed ? 'resolved' : 'pending',
+        data: (0, escalation_wire_1.escalationEventData)(escalation, { item_key: itemKey }),
+    });
+}

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

@@ -2,6 +2,7 @@ export * from './types';
 export * from './crud';
 export { claimAssertedByMetadata } from './claim-asserted';
 export * from './batch';
+export * from './batch-flag';
 export * from './accumulate';
 export * from './bulk';
 export * from './queries';

package/build/services/escalation/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./crud"), exports);
 var claim_asserted_1 = require("./claim-asserted");
 Object.defineProperty(exports, "claimAssertedByMetadata", { enumerable: true, get: function () { return claim_asserted_1.claimAssertedByMetadata; } });
 __exportStar(require("./batch"), exports);
+__exportStar(require("./batch-flag"), exports);
 __exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);
 __exportStar(require("./queries"), exports);

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

@@ -8,6 +8,8 @@
  * Member rows are read with `global: true`: a resolver who cannot see a
  * member must never be told the roster is complete.
  */
-import { type RosterCounts, type ShowIfContext } from '../../shared/form-validation';
+import { type RosterCounts, type RosterDef, type RosterResult, type ShowIfContext } from '../../shared/form-validation';
 /** Each roster field's counts, keyed by field name; empty when the schema declares none. */
 export declare function loadRosterCounts(schema: Record<string, unknown> | null | undefined, ctx: ShowIfContext): Promise<Record<string, RosterCounts>>;
+/** One roster's entries and counts, read the way the widget reads them. */
+export declare function loadRoster(def: RosterDef, ctx: ShowIfContext): Promise<RosterResult>;

package/build/services/escalation/roster.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadRosterCounts = loadRosterCounts;
+exports.loadRoster = loadRoster;
 /**
  * Server-side roster counts: the API-first counterpart of the dashboard's
  * roster widget. For each `x-lt-roster` field of a form schema, the member
@@ -18,10 +19,14 @@ async function loadRosterCounts(schema, ctx) {
     const defs = (0, form_validation_1.readRosterDefs)(schema);
     const counts = {};
     for (const [field, def] of Object.entries(defs)) {
-        counts[field] = (0, form_validation_1.computeRoster)(def, ctx, await readMemberRows(def, ctx)).counts;
+        counts[field] = (await loadRoster(def, ctx)).counts;
     }
     return counts;
 }
+/** One roster's entries and counts, read the way the widget reads them. */
+async function loadRoster(def, ctx) {
+    return (0, form_validation_1.computeRoster)(def, ctx, await readMemberRows(def, ctx));
+}
 async function readMemberRows(def, ctx) {
     const query = (0, form_validation_1.rosterQueryOf)(def);
     const scoped = query ? (0, form_validation_1.resolveRosterQuery)(query, ctx) : null;

package/build/services/scan-code/validate-subject.js

@@ -10,6 +10,10 @@ function isSchemeList(value) {
 function isStringList(value) {
     return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === 'string' && v);
 }
+/** A form field name, as `hold.show` names one. */
+const HOLD_SHOW_FIELD = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** A fill's label map lives on the batch row: `envelope.<path>` or `metadata.<path>`. */
+const FILL_LABELS_PATH = /^(envelope|metadata)\.[A-Za-z0-9_.-]+$/;
 function isPlainObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -165,6 +169,9 @@ function assertValidHold(step, at) {
             throw new Error(`${at}: params.hold.expect.prompt must be markdown`);
         }
     }
+    if (hold.show !== undefined && (typeof hold.show !== 'string' || !HOLD_SHOW_FIELD.test(hold.show))) {
+        throw new Error(`${at}: params.hold.show must name a roster field of the held row's form`);
+    }
 }
 function assertValidFill(step, at) {
     const fill = step.params?.fill;
@@ -180,6 +187,15 @@ function assertValidFill(step, at) {
     if (fill.payload !== undefined && !isPlainObject(fill.payload)) {
         throw new Error(`${at}: params.fill.payload must be an object`);
     }
+    if (fill.labels !== undefined && (typeof fill.labels !== 'string' || !FILL_LABELS_PATH.test(fill.labels))) {
+        throw new Error(`${at}: params.fill.labels must name a map on the row, e.g. "envelope.labels"`);
+    }
+    if (fill.label !== undefined && (typeof fill.label !== 'string' || !fill.label.trim())) {
+        throw new Error(`${at}: params.fill.label must be a non-empty template`);
+    }
+    if (fill.label !== undefined && fill.labels === undefined) {
+        throw new Error(`${at}: params.fill.label requires params.fill.labels`);
+    }
     if (step.confirm)
         throw new Error(`${at}: fill cannot carry confirm`);
 }

package/build/services/scan-code/validate.js

@@ -127,6 +127,13 @@ function assertValidChoices(choices, at) {
             || choice.verb === types_1.SCAN_VERBS.FILL) {
             throw new Error(`${cat}: ${choice.verb} cannot be a choice verb`);
         }
+        if (choice.roles !== undefined && (!Array.isArray(choice.roles) || choice.roles.length === 0
+            || choice.roles.some((r) => typeof r !== 'string' || !r))) {
+            throw new Error(`${cat}: roles must be a non-empty array of role names`);
+        }
+        if (choice.refuse !== undefined && (typeof choice.refuse !== 'string' || !choice.refuse.trim())) {
+            throw new Error(`${cat}: refuse must be non-empty text`);
+        }
         if (choice.confirm && !choice.confirm.prompt) {
             throw new Error(`${cat}: confirm requires a prompt`);
         }

package/build/shared/form-validation/index.d.ts

@@ -24,3 +24,4 @@ export * from './display-only-widgets';
 export * from './x-lt-invoke';
 export * from './x-lt-scan';
 export * from './x-lt-roster';
+export * from './x-lt-actions';

package/build/shared/form-validation/index.js

@@ -40,3 +40,4 @@ __exportStar(require("./display-only-widgets"), exports);
 __exportStar(require("./x-lt-invoke"), exports);
 __exportStar(require("./x-lt-scan"), exports);
 __exportStar(require("./x-lt-roster"), exports);
+__exportStar(require("./x-lt-actions"), exports);

package/build/shared/form-validation/x-lt-actions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * x-lt-actions on a roster field: the acts an entry offers, read the same way
+ * by the dashboard (which shows them) and the API (which runs them). Each
+ * action is exactly one act:
+ *
+ *   { "label": "Missing",      "resolverPayload": { "outcome": "missing" } }  resolve the member row
+ *   { "label": "Key in",       "fill": { "payload": { "source": "key-in" }, "enterCode": true } }
+ *   { "label": "Missing",      "flag": { "label": "Missing" } }               flag the batch key
+ *   { "label": "Found it",     "unflag": true }                               clear the flag
+ *
+ * `when` names the entry states that offer it. `roles` limits who may run it:
+ * the action shows to everyone and runs only for a person holding one of the
+ * roles; `refuse` is what anyone else is told. The server re-reads the action
+ * from the row's form schema and decides; the dashboard only displays.
+ */
+import { type HelpTokenContext } from './x-lt-help';
+import { type RosterEntry, type RosterState } from './x-lt-roster';
+export declare const X_LT_ACTIONS = "x-lt-actions";
+export declare const ROSTER_ACTION_KINDS: {
+    readonly RESOLVE: "resolve";
+    readonly FILL: "fill";
+    readonly FLAG: "flag";
+    readonly UNFLAG: "unflag";
+};
+export type RosterActionKind = (typeof ROSTER_ACTION_KINDS)[keyof typeof ROSTER_ACTION_KINDS];
+/** The separator of counted batch keys when the roster names none. */
+export declare const ROSTER_KEY_SEPARATOR_DEFAULT = "#";
+/** The payload key a key-in records the entered code under. */
+export declare const ENTERED_CODE_KEY = "enteredCode";
+export interface RosterActionDef {
+    label: string;
+    /** The entry states that offer it; the default follows the act. */
+    when?: RosterState | RosterState[];
+    /** A confirmation asked in place before firing; tokens interpolate per entry. */
+    confirm?: string;
+    /** Resolve the entry's member row with this canned payload (a query set). */
+    resolverPayload?: Record<string, unknown>;
+    /** Fill the entry's batch key; `enterCode` asks for the code and checks it against the key. */
+    fill?: {
+        payload?: Record<string, unknown>;
+        enterCode?: boolean;
+    };
+    /** Flag the entry's batch key. */
+    flag?: {
+        label: string;
+        payload?: Record<string, unknown>;
+    };
+    /** Clear the entry's flag. */
+    unflag?: true;
+    /** Runs only for a person holding one of these roles. */
+    roles?: string[];
+    /** What a person without the roles is told. */
+    refuse?: string;
+}
+/** The one act an action declares, or null when it declares none or several. */
+export declare function rosterActionKind(action: RosterActionDef): RosterActionKind | null;
+/** The field's actions with a label and exactly one act, in declared order. */
+export declare function readRosterActions(fieldSchema: Record<string, unknown> | null | undefined): RosterActionDef[];
+/**
+ * True when the entry offers the action: the entry is in one of its states,
+ * and the act fits the entry (a resolve needs a member row; batch acts need
+ * a batch set).
+ */
+export declare function offersAction(action: RosterActionDef, entry: RosterEntry, batch: boolean): boolean;
+/** True when a person holding `roles` may run the action. */
+export declare function holdsActionRole(action: Pick<RosterActionDef, 'roles'>, roles: string[], superadmin?: boolean): boolean;
+/** What a person without the action's roles is told. */
+export declare function actionRefusal(action: Pick<RosterActionDef, 'label' | 'roles' | 'refuse'>): string;
+/** Deep-walk a payload template: string leaves interpolate against the context; other types pass through typed. */
+export declare function interpolatePayload(value: unknown, ctx: HelpTokenContext): unknown;
+/** The code a batch key names, without its ordinal suffix. */
+export declare function batchKeyCode(key: string, separator?: string): string;
+/** The batch key's code as its label prints it: a GTIN in its EAN-13 or EAN-8 form. */
+export declare function printedKeyCode(key: string, separator?: string): string;
+/**
+ * True when an entered code names the batch key's code. GTINs compare in
+ * their 14-digit form, so a UPC-A typed from the label matches its GTIN-14
+ * key; anything else compares as trimmed text.
+ */
+export declare function enteredCodeMatches(entered: string, key: string, separator?: string): boolean;

package/build/shared/form-validation/x-lt-actions.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTERED_CODE_KEY = exports.ROSTER_KEY_SEPARATOR_DEFAULT = exports.ROSTER_ACTION_KINDS = exports.X_LT_ACTIONS = void 0;
+exports.rosterActionKind = rosterActionKind;
+exports.readRosterActions = readRosterActions;
+exports.offersAction = offersAction;
+exports.holdsActionRole = holdsActionRole;
+exports.actionRefusal = actionRefusal;
+exports.interpolatePayload = interpolatePayload;
+exports.batchKeyCode = batchKeyCode;
+exports.printedKeyCode = printedKeyCode;
+exports.enteredCodeMatches = enteredCodeMatches;
+/**
+ * x-lt-actions on a roster field: the acts an entry offers, read the same way
+ * by the dashboard (which shows them) and the API (which runs them). Each
+ * action is exactly one act:
+ *
+ *   { "label": "Missing",      "resolverPayload": { "outcome": "missing" } }  resolve the member row
+ *   { "label": "Key in",       "fill": { "payload": { "source": "key-in" }, "enterCode": true } }
+ *   { "label": "Missing",      "flag": { "label": "Missing" } }               flag the batch key
+ *   { "label": "Found it",     "unflag": true }                               clear the flag
+ *
+ * `when` names the entry states that offer it. `roles` limits who may run it:
+ * the action shows to everyone and runs only for a person holding one of the
+ * roles; `refuse` is what anyone else is told. The server re-reads the action
+ * from the row's form schema and decides; the dashboard only displays.
+ */
+const x_lt_help_1 = require("./x-lt-help");
+const x_lt_roster_1 = require("./x-lt-roster");
+const gtin_1 = require("../scan-code/gtin");
+exports.X_LT_ACTIONS = 'x-lt-actions';
+exports.ROSTER_ACTION_KINDS = {
+    RESOLVE: 'resolve',
+    FILL: 'fill',
+    FLAG: 'flag',
+    UNFLAG: 'unflag',
+};
+/** The separator of counted batch keys when the roster names none. */
+exports.ROSTER_KEY_SEPARATOR_DEFAULT = '#';
+/** The payload key a key-in records the entered code under. */
+exports.ENTERED_CODE_KEY = 'enteredCode';
+const DEFAULT_WHEN = {
+    resolve: [x_lt_roster_1.ROSTER_STATES.WAITING],
+    fill: [x_lt_roster_1.ROSTER_STATES.WAITING, x_lt_roster_1.ROSTER_STATES.FLAGGED],
+    flag: [x_lt_roster_1.ROSTER_STATES.WAITING],
+    unflag: [x_lt_roster_1.ROSTER_STATES.FLAGGED],
+};
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** The one act an action declares, or null when it declares none or several. */
+function rosterActionKind(action) {
+    const kinds = [];
+    if (isRecord(action.resolverPayload))
+        kinds.push(exports.ROSTER_ACTION_KINDS.RESOLVE);
+    if (isRecord(action.fill))
+        kinds.push(exports.ROSTER_ACTION_KINDS.FILL);
+    if (isRecord(action.flag) && typeof action.flag.label === 'string' && action.flag.label) {
+        kinds.push(exports.ROSTER_ACTION_KINDS.FLAG);
+    }
+    if (action.unflag === true)
+        kinds.push(exports.ROSTER_ACTION_KINDS.UNFLAG);
+    return kinds.length === 1 ? kinds[0] : null;
+}
+/** The field's actions with a label and exactly one act, in declared order. */
+function readRosterActions(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_ACTIONS];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((a) => isRecord(a) && typeof a.label === 'string' && !!a.label && rosterActionKind(a) !== null);
+}
+/**
+ * True when the entry offers the action: the entry is in one of its states,
+ * and the act fits the entry (a resolve needs a member row; batch acts need
+ * a batch set).
+ */
+function offersAction(action, entry, batch) {
+    const kind = rosterActionKind(action);
+    if (!kind)
+        return false;
+    if (kind === exports.ROSTER_ACTION_KINDS.RESOLVE ? !entry.row : !batch)
+        return false;
+    const when = action.when === undefined ? DEFAULT_WHEN[kind]
+        : Array.isArray(action.when) ? action.when : [action.when];
+    return when.includes(entry.state);
+}
+/** True when a person holding `roles` may run the action. */
+function holdsActionRole(action, roles, superadmin = false) {
+    const required = Array.isArray(action.roles) ? action.roles.filter((r) => typeof r === 'string' && r) : [];
+    return required.length === 0 || superadmin || required.some((r) => roles.includes(r));
+}
+/** What a person without the action's roles is told. */
+function actionRefusal(action) {
+    if (typeof action.refuse === 'string' && action.refuse.trim())
+        return action.refuse;
+    const roles = (action.roles ?? []).filter(Boolean);
+    return `${action.label} needs ${roles.length > 1 ? 'one of these roles' : 'the role'}: ${roles.join(', ')}.`;
+}
+/** Deep-walk a payload template: string leaves interpolate against the context; other types pass through typed. */
+function interpolatePayload(value, ctx) {
+    if (typeof value === 'string')
+        return (0, x_lt_help_1.interpolateHelp)(value, ctx);
+    if (Array.isArray(value))
+        return value.map((v) => interpolatePayload(v, ctx));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolatePayload(v, ctx)]));
+    }
+    return value;
+}
+/** The code a batch key names, without its ordinal suffix. */
+function batchKeyCode(key, separator = exports.ROSTER_KEY_SEPARATOR_DEFAULT) {
+    const at = key.lastIndexOf(separator);
+    return at > 0 && /^[0-9]+$/.test(key.slice(at + 1)) ? key.slice(0, at) : key;
+}
+/** The batch key's code as its label prints it: a GTIN in its EAN-13 or EAN-8 form. */
+function printedKeyCode(key, separator) {
+    const code = batchKeyCode(key, separator);
+    return (0, gtin_1.isValidGtin)(code) ? (0, gtin_1.displayGtin)((0, gtin_1.normalizeGtin)(code)) : code;
+}
+/**
+ * True when an entered code names the batch key's code. GTINs compare in
+ * their 14-digit form, so a UPC-A typed from the label matches its GTIN-14
+ * key; anything else compares as trimmed text.
+ */
+function enteredCodeMatches(entered, key, separator) {
+    const typed = entered.trim();
+    const code = batchKeyCode(key, separator);
+    if (!typed)
+        return false;
+    if ((0, gtin_1.isValidGtin)(typed) && (0, gtin_1.isValidGtin)(code))
+        return (0, gtin_1.normalizeGtin)(typed) === (0, gtin_1.normalizeGtin)(code);
+    return typed === code;
+}

package/build/shared/form-validation/x-lt-roster.d.ts

@@ -40,6 +40,8 @@ export interface RosterDef {
     key?: string;
     in?: string[];
     flagged?: RosterFlagRule[];
+    /** The separator of counted keys: the nth occurrence of a code ticks `<code><sep>n`. */
+    countedBy?: string;
 }
 /** One member row's token context (the row's own domains). */
 export type RosterRow = HelpTokenContext & {

package/build/shared/form-validation/x-lt-roster.js

@@ -28,9 +28,14 @@ exports.rosterHeadline = rosterHeadline;
  * An entry is `in` when its key is held by the host row (`items`: the
  * accumulated keys, or a batch's filled keys) or appears in a named context
  * value (`resolver.<field>`, a string or an array). It is `flagged` when its
- * member row matches a `flagged` rule, and `waiting` otherwise. In wins over
+ * member row matches a `flagged` rule (or, on a batch set, when its key
+ * carries a flag in `envelope.batch_flags`), and `waiting` otherwise. In wins over
  * flagged, so a member flagged on its own row and then added reads in.
  *
+ * `countedBy` names the separator of counted keys (`<code>#1`, `<code>#2`):
+ * the nth occurrence of a code in a named context value ticks `<code>#n`,
+ * so two scans of one code tick both of its keys.
+ *
  * Isomorphic: the dashboard renders the widget and the form's `roster.*`
  * context from it, and the API layer computes the same counts to evaluate
  * showIf and the roster submit guard at resolve.
@@ -54,6 +59,7 @@ const DEFAULT_KEY = '{{escalation.id}}';
 const MISSING = '—';
 const BATCH_KEYS = 'batch_keys';
 const BATCH_PENDING = 'batch_pending';
+const BATCH_FLAGS = 'batch_flags';
 const ACCUMULATE_KEYS = 'accumulate_keys';
 function isRecord(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
@@ -144,16 +150,34 @@ function heldKeys(ctx) {
     }
     return new Set();
 }
+/** Each value as given, and with `countedBy` its nth occurrence also as `<value><sep>n`. */
+function countedKeys(values, separator) {
+    if (!separator)
+        return values;
+    const seen = new Map();
+    return values.flatMap((v) => {
+        const n = (seen.get(v) ?? 0) + 1;
+        seen.set(v, n);
+        return [v, `${v}${separator}${n}`];
+    });
+}
 function arrivedKeys(def, ctx) {
     const arrived = new Set();
+    const separator = typeof def.countedBy === 'string' && def.countedBy ? def.countedBy : undefined;
     for (const source of def.in ?? [exports.ROSTER_ITEMS_SOURCE]) {
         const keys = source === exports.ROSTER_ITEMS_SOURCE
             ? [...heldKeys(ctx)]
-            : strings((0, ctx_path_1.resolveCtxPath)(source, ctx));
+            : countedKeys(strings((0, ctx_path_1.resolveCtxPath)(source, ctx)), separator);
         keys.forEach((k) => arrived.add(k));
     }
     return arrived;
 }
+/** A batch key's flag label, from `envelope.batch_flags[key].label`. */
+function batchFlagLabel(ctx, key) {
+    const flags = (0, x_lt_bind_1.getDeep)(ctx.envelope, BATCH_FLAGS);
+    const flag = isRecord(flags) ? flags[key] : undefined;
+    return isRecord(flag) && typeof flag.label === 'string' && flag.label ? flag.label : undefined;
+}
 function flagFor(def, row) {
     if (!row)
         return undefined;
@@ -219,10 +243,11 @@ function expectedEntries(def, ctx, rows) {
  */
 function computeRoster(def, ctx, rows = []) {
     const arrived = arrivedKeys(def, ctx);
+    const batch = 'batch' in def.expected;
     const entries = expectedEntries(def, ctx, rows).map((e) => {
         if (arrived.has(e.key))
             return { ...e, state: exports.ROSTER_STATES.IN };
-        const flag = flagFor(def, e.row);
+        const flag = batch ? batchFlagLabel(ctx, e.key) : flagFor(def, e.row);
         return flag ? { ...e, state: exports.ROSTER_STATES.FLAGGED, flag } : { ...e, state: exports.ROSTER_STATES.WAITING };
     });
     const count = (s) => entries.filter((e) => e.state === s).length;