@hotmeshio/long-tail 0.30.4 → 0.31.0

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

@@ -1,5 +1,5 @@
 import type { LTUserRecord, LTRoleType, LTUserStatus } from '../../types';
-import type { CreateUserInput, UpdateUserInput, UserPropertyOps } from './types';
+import type { CreateUserInput, PropertyPatchRecord, UpdateUserInput, UserPropertyOps } from './types';
 export declare function attachRoles(user: any): Promise<LTUserRecord>;
 export declare function createUser(input: CreateUserInput): Promise<LTUserRecord>;
 export declare function getUser(id: string): Promise<LTUserRecord | null>;
@@ -56,6 +56,18 @@ export declare function getIdentityPropertyKeys(): Promise<string[]>;
  * A tripped guard raises UserPropertyConflictError (409).
  */
 export declare function patchUserProperties(id: string, ops: UserPropertyOps): Promise<LTUserRecord | null>;
+/**
+ * The identity keys a patch touches: set, removed, or renamed from or to.
+ */
+export declare function identityKeysTouched(ops: UserPropertyOps): Promise<string[]>;
+/**
+ * patchUserProperties, with an lt_label_jobs row written by the same
+ * statement. Returns the user and the ledger row id; null for an unknown user.
+ */
+export declare function patchUserPropertiesRecorded(id: string, ops: UserPropertyOps, record: PropertyPatchRecord): Promise<{
+    user: LTUserRecord;
+    jobId: string;
+} | null>;
 export declare function deleteUser(id: string): Promise<boolean>;
 export declare function listUsers(filters: {
     role?: string;

package/build/services/user/crud.js

@@ -14,6 +14,8 @@ exports.getUserByMetadataValue = getUserByMetadataValue;
 exports.updateUser = updateUser;
 exports.getIdentityPropertyKeys = getIdentityPropertyKeys;
 exports.patchUserProperties = patchUserProperties;
+exports.identityKeysTouched = identityKeysTouched;
+exports.patchUserPropertiesRecorded = patchUserPropertiesRecorded;
 exports.deleteUser = deleteUser;
 exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
@@ -159,8 +161,12 @@ async function updateUser(id, input) {
         values.push(await bcryptjs_1.default.hash(input.password, 10));
     }
     if (input.metadata !== undefined) {
-        sets.push(`metadata = $${idx++}`);
-        values.push(JSON.stringify(input.metadata));
+        // Identity bindings the replacement leaves out are kept, read in the same statement.
+        const keysIdx = idx++;
+        const metadataIdx = idx++;
+        sets.push(`metadata = COALESCE((SELECT jsonb_object_agg(k, lt_users.metadata -> k) FROM unnest($${keysIdx}::text[]) AS k ` +
+            `WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? k), '{}'::jsonb) || $${metadataIdx}::jsonb`);
+        values.push(await getIdentityPropertyKeys(), JSON.stringify(input.metadata));
     }
     if (sets.length === 0) {
         return getUser(id);
@@ -215,6 +221,29 @@ async function getIdentityPropertyKeys() {
  * A tripped guard raises UserPropertyConflictError (409).
  */
 async function patchUserProperties(id, ops) {
+    const patched = await runPropertyPatch(id, ops, null);
+    return patched?.user ?? null;
+}
+/**
+ * The identity keys a patch touches: set, removed, or renamed from or to.
+ */
+async function identityKeysTouched(ops) {
+    const keys = new Set([
+        ...Object.keys(ops.set ?? {}),
+        ...(ops.remove ?? []),
+        ...Object.entries(ops.rename ?? {}).flat(),
+    ]);
+    return (await getIdentityPropertyKeys()).filter((k) => keys.has(k));
+}
+/**
+ * patchUserProperties, with an lt_label_jobs row written by the same
+ * statement. Returns the user and the ledger row id; null for an unknown user.
+ */
+async function patchUserPropertiesRecorded(id, ops, record) {
+    const patched = await runPropertyPatch(id, ops, record);
+    return patched ? { user: patched.user, jobId: patched.jobId } : null;
+}
+async function runPropertyPatch(id, ops, record) {
     const set = ops.set ?? {};
     const remove = ops.remove ?? [];
     const rename = ops.rename ?? {};
@@ -258,18 +287,20 @@ async function patchUserProperties(id, ops) {
     const removeAll = [...new Set([...remove, ...renameEntries.map(([prev]) => prev)])];
     const renamePairs = renameEntries.map(([prev, next]) => ({ prev, next }));
     const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.PATCH_USER_PROPERTIES, [
-        id,
-        removeAll,
-        JSON.stringify(renamePairs),
-        JSON.stringify(set),
-        JSON.stringify(guard),
-    ]);
-    if (rows[0])
-        return attachRoles(rows[0]);
+    const params = [id, removeAll, JSON.stringify(renamePairs), JSON.stringify(set), JSON.stringify(guard)];
+    const { rows } = record
+        ? await pool.query(sql_1.PATCH_USER_PROPERTIES_RECORDED, [...params, JSON.stringify(record)])
+        : await pool.query(sql_1.PATCH_USER_PROPERTIES, params);
+    if (rows[0]) {
+        const { ledger_id: jobId = null, ...row } = rows[0];
+        return { user: await attachRoles(row), jobId };
+    }
     const exists = await pool.query(sql_1.VERIFY_USER_BY_ID, [id]);
     if (!exists.rows[0])
         return null;
+    if (record?.require_active && exists.rows[0].status !== 'active') {
+        throw new UserPropertyValidationError('identity bindings are issued to active users only');
+    }
     // The user exists, so the identity guard is what blocked the write. Name
     // the first guarded key for the caller; the row was not touched.
     throw new UserPropertyConflictError(Object.keys(guard)[0] ?? 'identity binding');

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

@@ -1,5 +1,6 @@
-export { CreateUserInput, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
-export { createUser, getUser, getUserNames, UserNameRecord, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
+export { CreateUserInput, PropertyPatchRecord, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
+export { redactIdentityKeys, setIdentityKeyProtection, identityKeysProtected } from './redact';
+export { createUser, getUser, getUserNames, UserNameRecord, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, patchUserPropertiesRecorded, identityKeysTouched, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, grantRoleIfAbsent, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';

package/build/services/user/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUserNames = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.identityKeysTouched = exports.patchUserPropertiesRecorded = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUserNames = exports.getUser = exports.createUser = exports.identityKeysProtected = exports.setIdentityKeyProtection = exports.redactIdentityKeys = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
+var redact_1 = require("./redact");
+Object.defineProperty(exports, "redactIdentityKeys", { enumerable: true, get: function () { return redact_1.redactIdentityKeys; } });
+Object.defineProperty(exports, "setIdentityKeyProtection", { enumerable: true, get: function () { return redact_1.setIdentityKeyProtection; } });
+Object.defineProperty(exports, "identityKeysProtected", { enumerable: true, get: function () { return redact_1.identityKeysProtected; } });
 var crud_1 = require("./crud");
 Object.defineProperty(exports, "createUser", { enumerable: true, get: function () { return crud_1.createUser; } });
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return crud_1.getUser; } });
@@ -12,6 +16,8 @@ Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: functi
 Object.defineProperty(exports, "getUserByMetadataValue", { enumerable: true, get: function () { return crud_1.getUserByMetadataValue; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
 Object.defineProperty(exports, "patchUserProperties", { enumerable: true, get: function () { return crud_1.patchUserProperties; } });
+Object.defineProperty(exports, "patchUserPropertiesRecorded", { enumerable: true, get: function () { return crud_1.patchUserPropertiesRecorded; } });
+Object.defineProperty(exports, "identityKeysTouched", { enumerable: true, get: function () { return crud_1.identityKeysTouched; } });
 Object.defineProperty(exports, "getIdentityPropertyKeys", { enumerable: true, get: function () { return crud_1.getIdentityPropertyKeys; } });
 Object.defineProperty(exports, "UserPropertyConflictError", { enumerable: true, get: function () { return crud_1.UserPropertyConflictError; } });
 Object.defineProperty(exports, "UserPropertyValidationError", { enumerable: true, get: function () { return crud_1.UserPropertyValidationError; } });

package/build/services/user/redact.d.ts

@@ -0,0 +1,17 @@
+import type { LTUserRecord } from '../../types';
+/**
+ * Whether identity keys are protected: left out of user reads, refused in
+ * wholesale metadata writes, and written only with credentialIssuer. On by
+ * default; start({ labels: { protectIdentityKeys: false } }) turns it off.
+ */
+export declare function setIdentityKeyProtection(on: boolean): void;
+export declare function identityKeysProtected(): boolean;
+/**
+ * A user record as a reader sees it. `identity_bound` names the identity keys
+ * the user carries; while protection is on, their values (badge tokens and
+ * other printed credentials) leave `metadata`, and printing a credential is
+ * the only path that reveals one.
+ */
+export declare function redactIdentityKeys<T extends Pick<LTUserRecord, 'metadata'>>(user: T, identityKeys: string[]): T & {
+    identity_bound: string[];
+};

package/build/services/user/redact.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setIdentityKeyProtection = setIdentityKeyProtection;
+exports.identityKeysProtected = identityKeysProtected;
+exports.redactIdentityKeys = redactIdentityKeys;
+const config_1 = require("../../modules/config");
+let protectIdentityKeys = config_1.config.LT_PROTECT_IDENTITY_KEYS;
+/**
+ * Whether identity keys are protected: left out of user reads, refused in
+ * wholesale metadata writes, and written only with credentialIssuer. On by
+ * default; start({ labels: { protectIdentityKeys: false } }) turns it off.
+ */
+function setIdentityKeyProtection(on) {
+    protectIdentityKeys = on;
+}
+function identityKeysProtected() {
+    return protectIdentityKeys;
+}
+/**
+ * A user record as a reader sees it. `identity_bound` names the identity keys
+ * the user carries; while protection is on, their values (badge tokens and
+ * other printed credentials) leave `metadata`, and printing a credential is
+ * the only path that reveals one.
+ */
+function redactIdentityKeys(user, identityKeys) {
+    const metadata = user.metadata ? { ...user.metadata } : user.metadata;
+    const bound = identityKeys.filter((key) => !!metadata && key in metadata);
+    if (metadata && protectIdentityKeys)
+        for (const key of bound)
+            delete metadata[key];
+    return { ...user, metadata, identity_bound: bound };
+}

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

@@ -33,23 +33,16 @@ export declare const GET_NAMES_BY_IDS = "SELECT id, display_name, external_id, e
  */
 export declare const GET_USERS_BY_METADATA_VALUE: string;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
-export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
+export declare const VERIFY_USER_BY_ID = "SELECT id, status FROM lt_users WHERE id = $1 LIMIT 1";
+export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
 /**
- * Atomic per-key patch of the user's properties dictionary — ONE statement,
- * never read-merge-write. Composition (later wins on key collision):
- *
- *   base minus ($2: removed keys ∪ rename old-names)
- *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
- *      the source key is absent)
- *   || sets ($4: typed JSON values)
- *
- * $5 is the identity-binding guard: {key: value} pairs that must not already
- * belong to ANOTHER active user (the write-side counterpart of the
- * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
- * back means the user is missing OR the guard tripped — the caller
- * distinguishes with VERIFY_USER_BY_ID.
+ * The same patch, recorded in lt_label_jobs in the same statement: the ledger
+ * row exists exactly when the patch landed. $6 is the ledger row as JSON
+ * (action, requested_by, source, and for a reissue the template and media);
+ * it never carries the identity value. With `require_active`, only an active
+ * user is patched, checked in the same statement.
  */
-export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
+export declare const PATCH_USER_PROPERTIES_RECORDED: string;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";

package/build/services/user/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_NAMES_BY_IDS = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_FOR_AUTH = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = exports.USER_SAFE_COLUMNS_U = exports.USER_SAFE_COLUMNS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES_RECORDED = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_NAMES_BY_IDS = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_FOR_AUTH = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = exports.USER_SAFE_COLUMNS_U = exports.USER_SAFE_COLUMNS = void 0;
 /**
  * Every lt_users column a client may see. password_hash and oauth_provider_id
  * are credentials and never appear here — no user read path selects them (the
@@ -61,7 +61,7 @@ exports.GET_NAMES_BY_IDS = 'SELECT id, display_name, external_id, email FROM lt_
  */
 exports.GET_USERS_BY_METADATA_VALUE = `SELECT ${exports.USER_SAFE_COLUMNS} FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2`;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
-exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
+exports.VERIFY_USER_BY_ID = 'SELECT id, status FROM lt_users WHERE id = $1 LIMIT 1';
 /**
  * Atomic per-key patch of the user's properties dictionary — ONE statement,
  * never read-merge-write. Composition (later wins on key collision):
@@ -77,7 +77,7 @@ exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
  * back means the user is missing OR the guard tripped — the caller
  * distinguishes with VERIFY_USER_BY_ID.
  */
-exports.PATCH_USER_PROPERTIES = `
+const PATCH_USER_PROPERTIES_UPDATE = `
   UPDATE lt_users SET metadata = (
     (COALESCE(metadata, '{}'::jsonb) - $2::text[])
     || COALESCE((
@@ -94,6 +94,30 @@ exports.PATCH_USER_PROPERTIES = `
       WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v
     )
   RETURNING *`;
+exports.PATCH_USER_PROPERTIES = PATCH_USER_PROPERTIES_UPDATE;
+/**
+ * The same patch, recorded in lt_label_jobs in the same statement: the ledger
+ * row exists exactly when the patch landed. $6 is the ledger row as JSON
+ * (action, requested_by, source, and for a reissue the template and media);
+ * it never carries the identity value. With `require_active`, only an active
+ * user is patched, checked in the same statement.
+ */
+exports.PATCH_USER_PROPERTIES_RECORDED = `
+  WITH patched AS (${PATCH_USER_PROPERTIES_UPDATE.replace('WHERE id = $1', "WHERE id = $1 AND (($6::jsonb->>'require_active')::boolean IS NOT TRUE OR status = 'active')")}),
+  recorded AS (
+    INSERT INTO lt_label_jobs (
+      action, requested_by, sensitive, source, subject_user_ids, label_count,
+      template_name, template_revision, template_snapshot, scheme_version, scheme_kind, media, output
+    )
+    SELECT $6::jsonb->>'action', ($6::jsonb->>'requested_by')::uuid, true,
+           COALESCE($6::jsonb->'source', '{}'::jsonb), ARRAY[patched.id],
+           COALESCE(($6::jsonb->>'label_count')::int, 0),
+           $6::jsonb->>'template_name', ($6::jsonb->>'template_revision')::int, $6::jsonb->'template_snapshot',
+           ($6::jsonb->>'scheme_version')::int, $6::jsonb->>'scheme_kind', $6::jsonb->'media', $6::jsonb->>'output'
+    FROM patched
+    RETURNING id
+  )
+  SELECT patched.*, (SELECT id FROM recorded) AS ledger_id FROM patched`;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
           r.role, r.type AS role_type, r.read_scope, r.write_scope

package/build/services/user/types.d.ts

@@ -24,7 +24,10 @@ export interface UpdateUserInput {
     display_name?: string;
     password?: string;
     status?: LTUserStatus;
-    /** Wholesale REPLACE of the properties dictionary — for per-key edits use patchUserProperties. */
+    /**
+     * Wholesale REPLACE of the properties dictionary — for per-key edits use
+     * patchUserProperties. Identity bindings absent from the replacement are kept.
+     */
     metadata?: Record<string, any>;
 }
 /**
@@ -37,3 +40,20 @@ export interface UserPropertyOps {
     remove?: string[];
     rename?: Record<string, string>;
 }
+/** The lt_label_jobs row a recorded property patch writes beside the patch. */
+export interface PropertyPatchRecord {
+    action: 'bind' | 'reissue';
+    requested_by: string;
+    /** Patch only an active user; checked in the patch statement. */
+    require_active?: boolean;
+    /** Which identity keys changed; never their values. */
+    source: Record<string, unknown>;
+    label_count?: number;
+    template_name?: string;
+    template_revision?: number;
+    template_snapshot?: unknown;
+    scheme_version?: number;
+    scheme_kind?: string;
+    media?: unknown;
+    output?: string;
+}

package/build/shared/labels/compose.d.ts

@@ -0,0 +1,12 @@
+import type { ParseableScheme } from '../scan-code/parse';
+/** A code that cannot be composed under its scheme. */
+export declare class ScanComposeError extends Error {
+    constructor(message: string);
+}
+/** Whether the scheme's codes are minted by the engine (and so printable from a template). */
+export declare function isMintableScheme(scheme: Pick<ParseableScheme, 'encoding'>): boolean;
+/**
+ * The code a scan of `target` under `category` reads. Throws ScanComposeError
+ * when the scheme only reads codes (gtin, pattern) or the target does not fit.
+ */
+export declare function composeScanCode(scheme: Pick<ParseableScheme, 'version' | 'encoding' | 'delimiter' | 'target_length'>, category: string, target: string): string;

package/build/shared/labels/compose.js

@@ -0,0 +1,43 @@
+"use strict";
+// The inverse of parseScanCode for the encodings the engine mints.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanComposeError = void 0;
+exports.isMintableScheme = isMintableScheme;
+exports.composeScanCode = composeScanCode;
+/** A code that cannot be composed under its scheme. */
+class ScanComposeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScanComposeError';
+    }
+}
+exports.ScanComposeError = ScanComposeError;
+const PRINTABLE_ASCII = /^[\x21-\x7e]+$/;
+/** Whether the scheme's codes are minted by the engine (and so printable from a template). */
+function isMintableScheme(scheme) {
+    return scheme.encoding === 'fixed' || scheme.encoding === 'delimited';
+}
+/**
+ * The code a scan of `target` under `category` reads. Throws ScanComposeError
+ * when the scheme only reads codes (gtin, pattern) or the target does not fit.
+ */
+function composeScanCode(scheme, category, target) {
+    if (!/^[0-9]$/.test(category)) {
+        throw new ScanComposeError(`category must be a single digit, got "${category}"`);
+    }
+    const version = String(scheme.version);
+    if (scheme.encoding === 'delimited') {
+        if (!target || !PRINTABLE_ASCII.test(target)) {
+            throw new ScanComposeError(`target "${target}" must be printable ASCII with no spaces`);
+        }
+        return `${version}${scheme.delimiter}${category}${scheme.delimiter}${target}`;
+    }
+    if (scheme.encoding === 'fixed') {
+        const length = scheme.target_length ?? 0;
+        if (!new RegExp(`^[0-9]{${length}}$`).test(target)) {
+            throw new ScanComposeError(`target "${target}" must be exactly ${length} digits`);
+        }
+        return `${version}${category}${target}`;
+    }
+    throw new ScanComposeError(`scheme ${version} reads ${scheme.encoding} codes; the engine does not mint them`);
+}

package/build/shared/labels/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export { composeScanCode, isMintableScheme, ScanComposeError } from './compose';
+export { renderLabelText, listLabelTokens, unknownLabelTokens, userTokenKeys, type LabelTokenContext } from './tokens';
+export { LABEL_MEDIA, DEFAULT_LABEL_MEDIA_ID, LabelMediaError, assertValidMedia, resolveMedia, slotOrigin, slotsPerPage, } from './media';
+export { encodeSymbol, quietZoneModules, SymbolEncodeError, type EncodedSymbol } from './symbol';
+export { layoutLabelContent, GLYPH_ADVANCE, type LabelContentOptions } from './label-content';
+export { buildLabelSheet, cutMarkSegments, LabelLayoutError, MAX_COPIES, type LabelSheetInput } from './layout';
+export { renderSheetSvg, escapeXml, type SvgRenderOptions } from './render-svg';
+export { renderSheetZpl, zplField, ZplRenderError } from './render-zpl';

package/build/shared/labels/index.js

@@ -0,0 +1,54 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZplRenderError = exports.zplField = exports.renderSheetZpl = exports.escapeXml = exports.renderSheetSvg = exports.MAX_COPIES = exports.LabelLayoutError = exports.cutMarkSegments = exports.buildLabelSheet = exports.GLYPH_ADVANCE = exports.layoutLabelContent = exports.SymbolEncodeError = exports.quietZoneModules = exports.encodeSymbol = exports.slotsPerPage = exports.slotOrigin = exports.resolveMedia = exports.assertValidMedia = exports.LabelMediaError = exports.DEFAULT_LABEL_MEDIA_ID = exports.LABEL_MEDIA = exports.userTokenKeys = exports.unknownLabelTokens = exports.listLabelTokens = exports.renderLabelText = exports.ScanComposeError = exports.isMintableScheme = exports.composeScanCode = void 0;
+__exportStar(require("./types"), exports);
+var compose_1 = require("./compose");
+Object.defineProperty(exports, "composeScanCode", { enumerable: true, get: function () { return compose_1.composeScanCode; } });
+Object.defineProperty(exports, "isMintableScheme", { enumerable: true, get: function () { return compose_1.isMintableScheme; } });
+Object.defineProperty(exports, "ScanComposeError", { enumerable: true, get: function () { return compose_1.ScanComposeError; } });
+var tokens_1 = require("./tokens");
+Object.defineProperty(exports, "renderLabelText", { enumerable: true, get: function () { return tokens_1.renderLabelText; } });
+Object.defineProperty(exports, "listLabelTokens", { enumerable: true, get: function () { return tokens_1.listLabelTokens; } });
+Object.defineProperty(exports, "unknownLabelTokens", { enumerable: true, get: function () { return tokens_1.unknownLabelTokens; } });
+Object.defineProperty(exports, "userTokenKeys", { enumerable: true, get: function () { return tokens_1.userTokenKeys; } });
+var media_1 = require("./media");
+Object.defineProperty(exports, "LABEL_MEDIA", { enumerable: true, get: function () { return media_1.LABEL_MEDIA; } });
+Object.defineProperty(exports, "DEFAULT_LABEL_MEDIA_ID", { enumerable: true, get: function () { return media_1.DEFAULT_LABEL_MEDIA_ID; } });
+Object.defineProperty(exports, "LabelMediaError", { enumerable: true, get: function () { return media_1.LabelMediaError; } });
+Object.defineProperty(exports, "assertValidMedia", { enumerable: true, get: function () { return media_1.assertValidMedia; } });
+Object.defineProperty(exports, "resolveMedia", { enumerable: true, get: function () { return media_1.resolveMedia; } });
+Object.defineProperty(exports, "slotOrigin", { enumerable: true, get: function () { return media_1.slotOrigin; } });
+Object.defineProperty(exports, "slotsPerPage", { enumerable: true, get: function () { return media_1.slotsPerPage; } });
+var symbol_1 = require("./symbol");
+Object.defineProperty(exports, "encodeSymbol", { enumerable: true, get: function () { return symbol_1.encodeSymbol; } });
+Object.defineProperty(exports, "quietZoneModules", { enumerable: true, get: function () { return symbol_1.quietZoneModules; } });
+Object.defineProperty(exports, "SymbolEncodeError", { enumerable: true, get: function () { return symbol_1.SymbolEncodeError; } });
+var label_content_1 = require("./label-content");
+Object.defineProperty(exports, "layoutLabelContent", { enumerable: true, get: function () { return label_content_1.layoutLabelContent; } });
+Object.defineProperty(exports, "GLYPH_ADVANCE", { enumerable: true, get: function () { return label_content_1.GLYPH_ADVANCE; } });
+var layout_1 = require("./layout");
+Object.defineProperty(exports, "buildLabelSheet", { enumerable: true, get: function () { return layout_1.buildLabelSheet; } });
+Object.defineProperty(exports, "cutMarkSegments", { enumerable: true, get: function () { return layout_1.cutMarkSegments; } });
+Object.defineProperty(exports, "LabelLayoutError", { enumerable: true, get: function () { return layout_1.LabelLayoutError; } });
+Object.defineProperty(exports, "MAX_COPIES", { enumerable: true, get: function () { return layout_1.MAX_COPIES; } });
+var render_svg_1 = require("./render-svg");
+Object.defineProperty(exports, "renderSheetSvg", { enumerable: true, get: function () { return render_svg_1.renderSheetSvg; } });
+Object.defineProperty(exports, "escapeXml", { enumerable: true, get: function () { return render_svg_1.escapeXml; } });
+var render_zpl_1 = require("./render-zpl");
+Object.defineProperty(exports, "renderSheetZpl", { enumerable: true, get: function () { return render_zpl_1.renderSheetZpl; } });
+Object.defineProperty(exports, "zplField", { enumerable: true, get: function () { return render_zpl_1.zplField; } });
+Object.defineProperty(exports, "ZplRenderError", { enumerable: true, get: function () { return render_zpl_1.ZplRenderError; } });

package/build/shared/labels/label-content.d.ts

@@ -0,0 +1,17 @@
+import type { LabelContent, LabelElement, LabelSymbology, LabelWarningKind } from './types';
+export interface LabelContentOptions {
+    symbology: LabelSymbology;
+    humanReadable: boolean;
+    minModuleMm: number;
+}
+export interface LabelContentResult {
+    elements: LabelElement[];
+    warnings: {
+        kind: LabelWarningKind;
+        detail: string;
+    }[];
+}
+/** Average glyph advance as a fraction of the font size, for fitting text without font metrics. */
+export declare const GLYPH_ADVANCE = 0.56;
+/** Lay out one label's content inside a `width` × `height` box. */
+export declare function layoutLabelContent(content: LabelContent, width: number, height: number, opts: LabelContentOptions): LabelContentResult;

package/build/shared/labels/label-content.js

@@ -0,0 +1,137 @@
+"use strict";
+// Lays out one label: title, lines, then one panel per code (caption band,
+// symbol, readable code). Coordinates are millimetres from the label's corner.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLYPH_ADVANCE = void 0;
+exports.layoutLabelContent = layoutLabelContent;
+const symbol_1 = require("./symbol");
+/** Average glyph advance as a fraction of the font size, for fitting text without font metrics. */
+exports.GLYPH_ADVANCE = 0.56;
+const MIN_TEXT_MM = 1.6;
+const MAX_LINEAR_MODULE_MM = 0.6;
+const MAX_MATRIX_MODULE_MM = 1.4;
+const MAX_BAR_HEIGHT_MM = 30;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+/** The largest font size up to `size` at which `text` fits `width`, or null below the floor. */
+function fitText(text, width, size) {
+    const fitted = Math.min(size, width / Math.max(1, text.length * exports.GLYPH_ADVANCE));
+    return fitted >= MIN_TEXT_MM ? fitted : null;
+}
+/** Text that fits `width` at the floor size, cut with an ellipsis. */
+function truncateTo(text, width) {
+    const max = Math.max(1, Math.floor(width / (MIN_TEXT_MM * exports.GLYPH_ADVANCE)));
+    return text.length <= max ? text : `${text.slice(0, Math.max(1, max - 1))}…`;
+}
+function textRow(text, box, size, weight, out) {
+    let fitted = fitText(text, box.w, size);
+    let shown = text;
+    if (fitted === null) {
+        shown = truncateTo(text, box.w);
+        fitted = MIN_TEXT_MM;
+        out.warnings.push({ kind: 'overflow', detail: `"${text}" is too long for the label and was shortened` });
+    }
+    out.elements.push({ kind: 'text', x: box.x, y: box.y, w: box.w, size: fitted, text: shown, weight, align: 'center' });
+    return size * 1.2;
+}
+function planPanel(code, box, opts) {
+    const elements = [];
+    const gap = clamp(box.h * 0.04, 0.4, 1.5);
+    let y = box.y;
+    if (code.caption) {
+        const band = clamp(box.h * 0.2, 2.2, 7);
+        const size = Math.min(band * 0.62, box.w / Math.max(1, code.caption.length * exports.GLYPH_ADVANCE));
+        if (code.tone === 'solid')
+            elements.push({ kind: 'rect', x: box.x, y, w: box.w, h: band, fill: true });
+        if (code.tone === 'outline')
+            elements.push({ kind: 'rect', x: box.x, y, w: box.w, h: band, fill: false, stroke: clamp(band * 0.08, 0.2, 0.5) });
+        elements.push({
+            kind: 'text', x: box.x, y: y + (band - size) / 2, w: box.w, size: Math.max(size, MIN_TEXT_MM),
+            text: code.caption, weight: 'bold', align: 'center', inverse: code.tone === 'solid',
+        });
+        y += band + gap;
+    }
+    const readable = opts.humanReadable ? clamp(box.h * 0.1, 1.6, 3.2) : 0;
+    const symbolH = box.y + box.h - y - (readable ? readable + gap : 0);
+    const encoded = (0, symbol_1.encodeSymbol)(opts.symbology, code.code);
+    const quiet = (0, symbol_1.quietZoneModules)(opts.symbology);
+    const linear = opts.symbology === 'code128';
+    const moduleMm = linear
+        ? Math.min(MAX_LINEAR_MODULE_MM, box.w / (encoded.widthModules + 2 * quiet))
+        : Math.min(MAX_MATRIX_MODULE_MM, Math.min(box.w, symbolH) / (encoded.widthModules + 2 * quiet));
+    const w = encoded.widthModules * moduleMm;
+    const h = linear ? Math.min(symbolH, MAX_BAR_HEIGHT_MM) : encoded.heightModules * moduleMm;
+    elements.push({
+        kind: 'symbol', x: box.x + (box.w - w) / 2, y, w, h,
+        symbology: opts.symbology, data: code.code, moduleMm, path: encoded.path,
+    });
+    if (readable) {
+        elements.push({
+            kind: 'text', x: box.x, y: y + h + gap, w: box.w,
+            size: Math.max(MIN_TEXT_MM, Math.min(readable * 0.85, box.w / Math.max(1, code.code.length * exports.GLYPH_ADVANCE))),
+            text: code.code, weight: 'regular', align: 'center',
+        });
+    }
+    return { moduleMm, elements, quietOk: symbolH > 0 && w + 2 * quiet * moduleMm <= box.w + 1e-6 };
+}
+function planPanels(codes, area, across, opts) {
+    const n = codes.length;
+    const gap = clamp(Math.min(area.w, area.h) * 0.05, 0.8, 4);
+    return codes.map((code, i) => {
+        const box = across
+            ? { x: area.x + i * ((area.w - gap * (n - 1)) / n + gap), y: area.y, w: (area.w - gap * (n - 1)) / n, h: area.h }
+            : { x: area.x, y: area.y + i * ((area.h - gap * (n - 1)) / n + gap), w: area.w, h: (area.h - gap * (n - 1)) / n };
+        return planPanel(code, box, opts);
+    });
+}
+const smallest = (plans) => Math.min(...plans.map((p) => p.moduleMm));
+/** Lay out one label's content inside a `width` × `height` box. */
+function layoutLabelContent(content, width, height, opts) {
+    const out = { elements: [], warnings: [] };
+    const pad = clamp(Math.min(width, height) * 0.05, 1, 4);
+    const inner = { x: pad, y: pad, w: width - 2 * pad, h: height - 2 * pad };
+    let y = inner.y;
+    if (content.title) {
+        y += textRow(content.title, { ...inner, y }, clamp(inner.h * 0.15, 2.2, 10), 'bold', out);
+    }
+    const lineSize = clamp(inner.h * 0.09, 1.8, 6);
+    for (const line of content.lines.filter(Boolean)) {
+        y += textRow(line, { ...inner, y }, lineSize, 'regular', out);
+    }
+    if (content.codes.length === 0)
+        return out;
+    const area = { x: inner.x, y: y + (y > inner.y ? pad / 2 : 0), w: inner.w, h: 0 };
+    area.h = inner.y + inner.h - area.y;
+    let plans;
+    try {
+        const stacked = planPanels(content.codes, area, false, opts);
+        const across = content.codes.length > 1 ? planPanels(content.codes, area, true, opts) : stacked;
+        plans = smallest(across) > smallest(stacked) ? across : stacked;
+    }
+    catch (err) {
+        if (!(err instanceof symbol_1.SymbolEncodeError))
+            throw err;
+        out.warnings.push({ kind: 'unencodable', detail: err.message });
+        return out;
+    }
+    for (const plan of plans)
+        out.elements.push(...plan.elements);
+    const module = smallest(plans);
+    if (module < opts.minModuleMm) {
+        out.warnings.push({
+            kind: 'scale',
+            detail: `bars print at ${module.toFixed(2)} mm, below the ${opts.minModuleMm} mm a scanner reads reliably; use larger labels or fewer codes`,
+        });
+    }
+    if (plans.some((p) => !p.quietOk)) {
+        out.warnings.push({ kind: 'quiet_zone', detail: 'a code has too little blank margin around it to scan reliably' });
+    }
+    if (content.masked) {
+        for (const el of out.elements) {
+            if (el.kind === 'symbol')
+                Object.assign(el, { data: '', path: '', masked: true });
+            if (el.kind === 'text' && content.codes.some((c) => c.code === el.text))
+                el.text = '•'.repeat(8);
+        }
+    }
+    return out;
+}

package/build/shared/labels/layout.d.ts

@@ -0,0 +1,23 @@
+import type { LabelContent, LabelMedia, LabelSheet, LabelSymbology } from './types';
+export interface LabelSheetInput {
+    media: LabelMedia;
+    labels: LabelContent[];
+    symbology: LabelSymbology;
+    humanReadable: boolean;
+    /** The first slot to print on page one, counted from 1, so used labels are skipped. */
+    startPosition?: number;
+    /** Copies of each label, printed together. */
+    copies?: number;
+    /** One label per page, in the start slot (placards). */
+    onePerPage?: boolean;
+    cutMarks?: boolean;
+}
+/** A sheet request that cannot be laid out. */
+export declare class LabelLayoutError extends Error {
+    constructor(message: string);
+}
+export declare const MAX_COPIES = 50;
+/** Lay out every label of a job onto pages. */
+export declare function buildLabelSheet(input: LabelSheetInput): LabelSheet;
+/** Short tick marks at every label corner, outside the label, for cutting card stock. */
+export declare function cutMarkSegments(media: LabelMedia, length?: number): Array<[number, number, number, number]>;