@hotmeshio/long-tail 0.30.4 → 0.31.0

package/build/api/labels/templates.js

@@ -0,0 +1,98 @@
+"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.listLabelTemplates = listLabelTemplates;
+exports.getLabelTemplate = getLabelTemplate;
+exports.upsertLabelTemplate = upsertLabelTemplate;
+exports.deleteLabelTemplate = deleteLabelTemplate;
+exports.listLabelMedia = listLabelMedia;
+exports.listLabelTransports = listLabelTransports;
+const labels = __importStar(require("../../services/labels"));
+const transports_1 = require("../../lib/labels/transports");
+const errors_1 = require("./errors");
+/**
+ * List label templates, optionally for one scan scheme.
+ *
+ * @param input.scheme — scheme version to filter by
+ * @returns `{ status: 200, data: { templates } }`
+ */
+async function listLabelTemplates(input = {}) {
+    try {
+        return { status: 200, data: { templates: await labels.listLabelTemplates(input.scheme) } };
+    }
+    catch (err) {
+        return (0, errors_1.labelFailure)(err);
+    }
+}
+/** One label template by name; 404 when absent. */
+async function getLabelTemplate(input) {
+    try {
+        const template = await labels.getLabelTemplate(input.name);
+        return template ? { status: 200, data: template } : { status: 404, error: 'Label template not found' };
+    }
+    catch (err) {
+        return (0, errors_1.labelFailure)(err);
+    }
+}
+/**
+ * Create or replace a label template. With `expected_revision`, the write
+ * lands only on that revision (409 otherwise).
+ */
+async function upsertLabelTemplate(input) {
+    try {
+        const { expected_revision, ...template } = input;
+        return { status: 200, data: await labels.upsertLabelTemplate(template, expected_revision) };
+    }
+    catch (err) {
+        return (0, errors_1.labelFailure)(err);
+    }
+}
+async function deleteLabelTemplate(input) {
+    try {
+        const deleted = await labels.deleteLabelTemplate(input.name);
+        return deleted ? { status: 200, data: { deleted: true } } : { status: 404, error: 'Label template not found' };
+    }
+    catch (err) {
+        return (0, errors_1.labelFailure)(err);
+    }
+}
+/** Media presets and the deployment's default. */
+async function listLabelMedia() {
+    return { status: 200, data: { media: labels.labelMediaPresets(), defaultMedia: labels.defaultLabelMediaId() } };
+}
+/** Registered printer transports by name. */
+async function listLabelTransports() {
+    return { status: 200, data: { transports: transports_1.labelTransportRegistry.list() } };
+}

package/build/api/scan-codes/context.d.ts

@@ -1,5 +1,5 @@
 import * as scanCodeService from '../../services/scan-code';
-import { type LTEscalationRecord, type ParsedScanCode, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
+import { type LTEscalationRecord, type ParsedScanCode, type ScanDoneCopy, type ScanExecuteResponse, type ScanRule, type ScanScheme, type ScanStep } from '../../types';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /** The held subject, re-derived from the client's pointer on this request. */
 export interface HeldSubject {
@@ -42,6 +42,10 @@ export interface StepContext {
     subject?: HeldSubject;
     /** The station sent a subject pointer that no longer checks out. */
     subjectStale?: boolean;
+    /** The scanned code's own pending row, read once a step's copy or Open asks for it; null when none. */
+    located?: LTEscalationRecord | null;
+    /** The located row's role title. */
+    locatedTitle?: string | null;
 }
 export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<string, any>;
 /**
@@ -51,6 +55,8 @@ export declare function targetFilter(step: ScanStep, ctx: StepContext): Record<s
  */
 export declare function targetValue(ctx: Pick<StepContext, 'scheme' | 'parsed'>): string | string[];
 export declare function templateContext(ctx: StepContext): scanCodeService.ScanTemplateContext;
+/** The `{located.x}` bag: the row's metadata plus its id, role and role title. */
+export declare function locatedBag(row: LTEscalationRecord, title?: string | null): Record<string, unknown>;
 /** The `{subject.x}` bag: the held row's metadata plus its id. */
 export declare function subjectBag(row: LTEscalationRecord): Record<string, unknown>;
 /**
@@ -85,6 +91,8 @@ export declare function templated<T>(step: ScanStep, ctx: StepContext, render: (
  * batch); an unreadable token renders empty rather than failing the act.
  */
 export declare function withDone(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'done'>, tpl: scanCodeService.ScanTemplateContext): LTApiResult<ScanExecuteResponse>;
+/** A done copy rendered for the station: the markdown, its pause, and the line under it. */
+export declare function renderDone(done: ScanDoneCopy, tpl: scanCodeService.ScanTemplateContext): ScanDoneCopy;
 /**
  * Attach the step's `follow` to a write that completed the held subject: the
  * code the station replays and the target it waits for, so the subject's

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.targetFilter = targetFilter;
 exports.targetValue = targetValue;
 exports.templateContext = templateContext;
+exports.locatedBag = locatedBag;
 exports.subjectBag = subjectBag;
 exports.liveClaimMetadata = liveClaimMetadata;
 exports.stepTemplate = stepTemplate;
@@ -48,6 +49,7 @@ exports.notPrimed = notPrimed;
 exports.refused = refused;
 exports.templated = templated;
 exports.withDone = withDone;
+exports.renderDone = renderDone;
 exports.withFollow = withFollow;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
@@ -70,8 +72,13 @@ function templateContext(ctx) {
         scannedAt: ctx.scannedAt,
         code: ctx.parsed.raw ?? ctx.parsed.target,
         ...(ctx.subject ? { subject: subjectBag(ctx.subject.row) } : {}),
+        ...(ctx.located ? { located: locatedBag(ctx.located, ctx.locatedTitle) } : {}),
     };
 }
+/** The `{located.x}` bag: the row's metadata plus its id, role and role title. */
+function locatedBag(row, title) {
+    return { ...(row.metadata ?? {}), id: row.id, role: row.role, roleTitle: title || row.role };
+}
 /** The `{subject.x}` bag: the held row's metadata plus its id. */
 function subjectBag(row) {
     return { ...(row.metadata ?? {}), id: row.id };
@@ -168,7 +175,15 @@ function withDone(result, step, tpl) {
     const data = result.data;
     if (!step.done || !data || data.outcome !== types_1.SCAN_OUTCOMES.EXECUTED || data.already || data.done)
         return result;
-    return { ...result, data: { ...data, done: { markdown: scanCodeService.renderScanCopy(step.done.markdown, tpl) } } };
+    return { ...result, data: { ...data, done: renderDone(step.done, tpl) } };
+}
+/** A done copy rendered for the station: the markdown, its pause, and the line under it. */
+function renderDone(done, tpl) {
+    return {
+        markdown: scanCodeService.renderScanCopy(done.markdown, tpl),
+        ...(done.afterSeconds !== undefined ? { afterSeconds: done.afterSeconds } : {}),
+        ...(done.nextPrompt ? { nextPrompt: scanCodeService.renderScanCopy(done.nextPrompt, tpl) } : {}),
+    };
 }
 /**
  * Attach the step's `follow` to a write that completed the held subject: the

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

@@ -39,7 +39,9 @@ const identity_1 = require("./identity");
 const context_1 = require("./context");
 const grant_1 = require("./grant");
 const hold_1 = require("./hold");
+const located_1 = require("./located");
 const locate_1 = require("./locate");
+const open_1 = require("./open");
 const present_1 = require("./present");
 const subject_1 = require("./subject");
 const verb_fill_1 = require("./verb-fill");
@@ -116,7 +118,8 @@ async function executeScanCode(input, auth) {
             const stepResult = await executeStep(rule.steps[i], ctx);
             if (stepResult) {
                 const step = rule.steps[i];
-                result = decorate((0, context_1.withFollow)((0, context_1.withDone)(stepResult, step, (0, context_1.templateContext)(ctx)), step, ctx), ctx, i);
+                const answered = (0, context_1.withFollow)((0, context_1.withDone)(stepResult, step, (0, context_1.templateContext)(ctx)), step, ctx);
+                result = decorate(await (0, open_1.withOpen)(answered, step, ctx), ctx, i);
             }
         }
         // 4. Nothing matched: a stale subject, or the fallback screen
@@ -177,6 +180,8 @@ function subjectGateOpen(step, ctx) {
 async function executeStep(step, ctx) {
     if (!subjectGateOpen(step, ctx))
         return null;
+    if ((0, located_1.readsLocated)(step))
+        await (0, located_1.loadLocated)(ctx);
     // The identity pre-condition: the effective actor must be a real acting
     // identity — a badge grant, or an authenticated user whose own write scope
     // covers the step. A write-incapable shared account can never self-satisfy,

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

@@ -3,6 +3,14 @@ import { type LTEscalationRecord, type ScanFillParams, type ScanScheme } from '.
 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;
+/** A per-key map the batch row carries (`envelope.<map>` or `metadata.<map>`); empty when absent. */
+export declare function rowMap(path: string, row: LTEscalationRecord): Record<string, unknown>;
+/**
+ * The open keys in the order a fill tries them. With `prefer`, the keys whose
+ * mapped value equals (or, for a list, contains) the held subject's target
+ * come first; the rest keep the row's order.
+ */
+export declare function preferredKeys(keys: string[], fill: ScanFillParams, row: LTEscalationRecord, heldTarget: string | undefined): 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

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

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printedCode = printedCode;
+exports.rowMap = rowMap;
+exports.preferredKeys = preferredKeys;
 exports.entryLabeler = entryLabeler;
 exports.pendingLabels = pendingLabels;
 const scanCodeService = __importStar(require("../../services/scan-code"));
@@ -63,6 +65,26 @@ function asObject(v) {
 function printedCode(code, scheme) {
     return scheme.encoding === types_1.SCAN_ENCODINGS.GTIN ? scanCodeService.displayGtin(code) : code;
 }
+/** A per-key map the batch row carries (`envelope.<map>` or `metadata.<map>`); empty when absent. */
+function rowMap(path, row) {
+    const map = (0, ctx_path_1.resolveCtxPath)(path, { envelope: asObject(row.envelope), metadata: asObject(row.metadata) });
+    return isRecord(map) ? map : {};
+}
+/**
+ * The open keys in the order a fill tries them. With `prefer`, the keys whose
+ * mapped value equals (or, for a list, contains) the held subject's target
+ * come first; the rest keep the row's order.
+ */
+function preferredKeys(keys, fill, row, heldTarget) {
+    if (!fill.prefer || heldTarget === undefined)
+        return keys;
+    const owners = rowMap(fill.prefer, row);
+    const owns = (key) => {
+        const value = owners[key];
+        return (Array.isArray(value) ? value : [value]).some((v) => v !== null && v !== undefined && String(v) === heldTarget);
+    };
+    return [...keys.filter(owns), ...keys.filter((key) => !owns(key))];
+}
 /**
  * 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
@@ -73,8 +95,7 @@ function printedCode(code, scheme) {
 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 : {};
+    const labels = rowMap(fill.labels, row);
     return (key, code) => {
         const printed = printedCode(code, scheme);
         const value = labels[key];

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

@@ -79,6 +79,8 @@ async function heldSubject(step, ctx, row) {
         } : {}),
         ...(claimant ? { claimedBy: claimant } : {}),
         ...(hold.show ? { show: hold.show } : {}),
+        ...(hold.release ? { release: hold.release } : {}),
+        ...(hold.whenAllIn ? { whenAllIn: (0, context_1.renderDone)(hold.whenAllIn, tpl) } : {}),
     };
 }
 /** The canonical code for the held row, as the station would scan it. */

package/build/api/scan-codes/located.d.ts

@@ -0,0 +1,10 @@
+import type { ScanStep } from '../../types';
+import { type StepContext } from './context';
+/** True when the step's copy or Open reads the scanned code's own pending row. */
+export declare function readsLocated(step: ScanStep): boolean;
+/**
+ * The scanned code's own pending row, read once per request: the newest
+ * pending row whose scheme facet holds the scanned target, in any role the
+ * actor may read, other than the held subject. Sets null when there is none.
+ */
+export declare function loadLocated(ctx: StepContext): Promise<void>;

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

@@ -0,0 +1,74 @@
+"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.readsLocated = readsLocated;
+exports.loadLocated = loadLocated;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const role_1 = require("../../services/role");
+const helpers_1 = require("../escalations/helpers");
+const metadata_1 = require("../escalations/metadata");
+const context_1 = require("./context");
+/** True when the step's copy or Open reads the scanned code's own pending row. */
+function readsLocated(step) {
+    return step.open?.target === 'located'
+        || scanCodeService.mentionsLocatedToken(step.refuse)
+        || scanCodeService.mentionsLocatedToken(step.done);
+}
+/**
+ * The scanned code's own pending row, read once per request: the newest
+ * pending row whose scheme facet holds the scanned target, in any role the
+ * actor may read, other than the held subject. Sets null when there is none.
+ */
+async function loadLocated(ctx) {
+    if (ctx.located !== undefined)
+        return;
+    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
+    const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global);
+    if (roles !== null && roles.length === 0) {
+        ctx.located = null;
+        return;
+    }
+    const found = await escalationService.searchByFacets({
+        roles: roles ?? undefined,
+        facets: { [ctx.scheme.target_facet]: (0, context_1.targetValue)(ctx) },
+        status: 'pending',
+        orderBy: [{ field: 'created_at', direction: 'desc' }],
+        limit: 2,
+    }, { total: false });
+    const row = found.escalations.find((r) => r.id !== ctx.subject?.row.id) ?? null;
+    ctx.located = row;
+    ctx.locatedTitle = row ? await (0, role_1.getRoleTitle)(row.role) : null;
+}

package/build/api/scan-codes/open.d.ts

@@ -0,0 +1,9 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import type { StepContext } from './context';
+/**
+ * Attach the step's Open button to the answer: on the held subject for a
+ * hold, so it stays while the row is held, else on the response. A target
+ * with no row, or a list facet the row does not carry, offers no button.
+ */
+export declare function withOpen(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'open'>, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse>>;

package/build/api/scan-codes/open.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.withOpen = withOpen;
+const escalationService = __importStar(require("../../services/escalation"));
+const types_1 = require("../../types");
+const OPEN_LABEL_DEFAULT = 'Open';
+/** The answers the station shows on its own screen: a hold, a refusal, a write's done copy. */
+function screenOf(data) {
+    if (data.outcome === types_1.SCAN_OUTCOMES.HELD && data.subject)
+        return 'hold';
+    if (data.outcome === types_1.SCAN_OUTCOMES.REFUSED)
+        return 'screen';
+    if (data.outcome === types_1.SCAN_OUTCOMES.EXECUTED
+        && (data.done || data.clearSubject || data.progress || data.already))
+        return 'screen';
+    return null;
+}
+/**
+ * Attach the step's Open button to the answer: on the held subject for a
+ * hold, so it stays while the row is held, else on the response. A target
+ * with no row, or a list facet the row does not carry, offers no button.
+ */
+async function withOpen(result, step, ctx) {
+    const data = result.data;
+    if (!step.open || !data)
+        return result;
+    const screen = screenOf(data);
+    if (!screen)
+        return result;
+    const link = await resolveOpen(step.open, ctx, data);
+    if (!link)
+        return result;
+    if (screen === 'hold')
+        return { ...result, data: { ...data, subject: { ...data.subject, open: link } } };
+    return { ...result, data: { ...data, open: link } };
+}
+async function resolveOpen(open, ctx, data) {
+    const row = await targetRow(open, ctx, data);
+    if (!row)
+        return null;
+    const label = open.label ?? OPEN_LABEL_DEFAULT;
+    if (!open.list)
+        return { label, escalationId: row.id, ...(open.claim ? { claim: true } : {}) };
+    const meta = (row.metadata ?? {});
+    const facets = {};
+    for (const key of open.list.facets) {
+        const value = meta[key];
+        if (!['string', 'number', 'boolean'].includes(typeof value) || value === '')
+            return null;
+        facets[key] = value;
+    }
+    return { label, facets, ...(open.list.role ? { role: open.list.role } : {}) };
+}
+/** The row the button opens: the one the step answered with, the held subject, or the scanned code's own row. */
+async function targetRow(open, ctx, data) {
+    const answered = data.escalation;
+    if (open.target === 'located')
+        return ctx.located ?? null;
+    if (open.target === 'subject' && data.outcome !== types_1.SCAN_OUTCOMES.HELD)
+        return ctx.subject?.row ?? null;
+    if (!answered?.id)
+        return null;
+    if (!open.list || answered.metadata)
+        return answered;
+    return escalationService.getEscalation(String(answered.id));
+}

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

@@ -117,6 +117,7 @@ async function presentStep(step, ctx) {
             escalation,
             choices,
             ...(step.facts ? { facts: renderFacts(step, ctx, escalation) } : {}),
+            ...(step.show ? { show: step.show } : {}),
             notPrimed: ctx.rule.notPrimed,
             ...(autoSelect ? { autoSelect: true } : {}),
         },

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

@@ -105,7 +105,7 @@ async function fillStep(step, ctx) {
             filled: batch.keys.length - batch.pending.length,
         },
     };
-    const candidates = keysFor(batch.pending, ctx.parsed.target, separator);
+    const candidates = (0, fill_labels_1.preferredKeys)(keysFor(batch.pending, ctx.parsed.target, separator), options, row, ctx.subject?.parsed.target);
     if (candidates.length === 0) {
         const declared = keysFor(batch.keys, ctx.parsed.target, separator);
         const markdown = declared.length

package/build/api/users.d.ts

@@ -1,4 +1,4 @@
-import type { LTApiResult } from '../types/sdk';
+import type { LTApiAuth, LTApiResult } from '../types/sdk';
 import type { LTRoleType } from '../types';
 /**
  * List users with optional filters for role, role type, status, and pagination.
@@ -92,13 +92,17 @@ export declare function updateUser(input: {
  * (`remove`); a key absent from the patch is kept. `rename` preserves the
  * value with no key-absent window. Identity-binding keys (badge scan
  * scheme target facets) assert uniqueness among active users in the same
- * statement.
+ * statement. Touching an identity key binds a credential: it needs the
+ * credentialIssuer capability and is recorded in lt_label_jobs by the same
+ * statement as the patch.
  *
  * @param input.id — the user's unique identifier
  * @param input.set — properties to set (typed JSON values)
  * @param input.remove — property keys to delete
  * @param input.rename — `{ oldKey: newKey }` renames, values preserved
- * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ * @param auth — the caller; required to touch an identity key
+ * @returns `{ status: 200, data: User }` with identity keys redacted; 400
+ *   malformed patch; 403 identity key without credentialIssuer; 404 unknown
  *   user; 409 when an identity value already belongs to another active user
  */
 export declare function patchUserProperties(input: {
@@ -106,7 +110,7 @@ export declare function patchUserProperties(input: {
     set?: Record<string, unknown>;
     remove?: string[];
     rename?: Record<string, string>;
-}): Promise<LTApiResult>;
+}, auth?: LTApiAuth): Promise<LTApiResult>;
 /**
  * The property keys the platform itself resolves identities against — every
  * enabled identity scan scheme's target facet. The dashboard marks these as

package/build/api/users.js

@@ -45,6 +45,20 @@ exports.getUserRoles = getUserRoles;
 exports.addUserRole = addUserRole;
 exports.removeUserRole = removeUserRole;
 const userService = __importStar(require("../services/user"));
+const capabilities_1 = require("../modules/capabilities");
+/** A user as the API returns it: identity keys redacted. */
+async function asRead(user) {
+    return userService.redactIdentityKeys(user, await userService.getIdentityPropertyKeys());
+}
+/** A refusal when a wholesale metadata write names an identity key; bindings go through patchUserProperties. */
+async function identityKeyInMetadata(metadata) {
+    if (!metadata || !userService.identityKeysProtected())
+        return null;
+    const named = (await userService.getIdentityPropertyKeys()).filter((k) => k in metadata);
+    if (named.length === 0)
+        return null;
+    return { status: 400, error: `"${named[0]}" is an identity binding; set it with patchUserProperties` };
+}
 /**
  * List users with optional filters for role, role type, status, and pagination.
  *
@@ -59,7 +73,8 @@ const userService = __importStar(require("../services/user"));
 async function listUsers(input) {
     try {
         const result = await userService.listUsers(input);
-        return { status: 200, data: result };
+        const keys = await userService.getIdentityPropertyKeys();
+        return { status: 200, data: { ...result, users: result.users.map((u) => userService.redactIdentityKeys(u, keys)) } };
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -95,7 +110,7 @@ async function getUser(input) {
         if (!user) {
             return { status: 404, error: 'User not found' };
         }
-        return { status: 200, data: user };
+        return { status: 200, data: await asRead(user) };
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -119,6 +134,9 @@ async function createUser(input) {
         if (!input.external_id) {
             return { status: 400, error: 'external_id is required' };
         }
+        const identityRefusal = await identityKeyInMetadata(input.metadata);
+        if (identityRefusal)
+            return identityRefusal;
         if (input.roles) {
             for (const r of input.roles) {
                 if (!r.role || !r.type || !userService.isValidRoleType(r.type)) {
@@ -148,7 +166,7 @@ async function createUser(input) {
             roles: input.roles,
             metadata: input.metadata,
         });
-        return { status: 201, data: user };
+        return { status: 201, data: await asRead(user) };
     }
     catch (err) {
         if (err.code === '23505') {
@@ -173,11 +191,14 @@ async function createUser(input) {
 async function updateUser(input) {
     try {
         const { id, ...fields } = input;
+        const identityRefusal = await identityKeyInMetadata(fields.metadata);
+        if (identityRefusal)
+            return identityRefusal;
         const user = await userService.updateUser(id, fields);
         if (!user) {
             return { status: 404, error: 'User not found' };
         }
-        return { status: 200, data: user };
+        return { status: 200, data: await asRead(user) };
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -189,26 +210,43 @@ async function updateUser(input) {
  * (`remove`); a key absent from the patch is kept. `rename` preserves the
  * value with no key-absent window. Identity-binding keys (badge scan
  * scheme target facets) assert uniqueness among active users in the same
- * statement.
+ * statement. Touching an identity key binds a credential: it needs the
+ * credentialIssuer capability and is recorded in lt_label_jobs by the same
+ * statement as the patch.
  *
  * @param input.id — the user's unique identifier
  * @param input.set — properties to set (typed JSON values)
  * @param input.remove — property keys to delete
  * @param input.rename — `{ oldKey: newKey }` renames, values preserved
- * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ * @param auth — the caller; required to touch an identity key
+ * @returns `{ status: 200, data: User }` with identity keys redacted; 400
+ *   malformed patch; 403 identity key without credentialIssuer; 404 unknown
  *   user; 409 when an identity value already belongs to another active user
  */
-async function patchUserProperties(input) {
+async function patchUserProperties(input, auth) {
     try {
-        const user = await userService.patchUserProperties(input.id, {
-            set: input.set,
-            remove: input.remove,
-            rename: input.rename,
-        });
+        const ops = { set: input.set, remove: input.remove, rename: input.rename };
+        const touched = await userService.identityKeysTouched(ops);
+        let user;
+        const protectedKeys = userService.identityKeysProtected();
+        if (touched.length > 0 && (protectedKeys || auth)) {
+            if (protectedKeys && (!auth || !(await (0, capabilities_1.mayIssueCredentials)(auth)))) {
+                return { status: 403, error: `"${touched[0]}" is an identity binding; credential-issuer access required` };
+            }
+            const recorded = await userService.patchUserPropertiesRecorded(input.id, ops, {
+                action: 'bind',
+                requested_by: auth.userId,
+                source: { keys: touched },
+            });
+            user = recorded?.user ?? null;
+        }
+        else {
+            user = await userService.patchUserProperties(input.id, ops);
+        }
         if (!user) {
             return { status: 404, error: 'User not found' };
         }
-        return { status: 200, data: user };
+        return { status: 200, data: await asRead(user) };
     }
     catch (err) {
         if (err.status === 400 || err.status === 409) {