@hotmeshio/long-tail 0.30.5 → 0.31.1

package/build/services/labels/render-pdf.js

@@ -0,0 +1,138 @@
+"use strict";
+// LabelSheet → PDF at exact page size. Text uses Helvetica unless the host
+// registers a font (start({ labels: { font } })) for scripts beyond Latin-1.
+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.registerLabelFonts = registerLabelFonts;
+exports.scalePath = scalePath;
+exports.renderSheetPdf = renderSheetPdf;
+const pdf_lib_1 = require("pdf-lib");
+const layout_1 = require("../../shared/labels/layout");
+const PT_PER_MM = 72 / 25.4;
+const BLACK = (0, pdf_lib_1.rgb)(0, 0, 0);
+const WHITE = (0, pdf_lib_1.rgb)(1, 1, 1);
+const pt = (mm) => mm * PT_PER_MM;
+let hostFonts = null;
+/** Fonts for label text in PDFs (TrueType or OpenType bytes). */
+function registerLabelFonts(fonts) {
+    hostFonts = fonts;
+}
+/** Characters Helvetica (WinAnsi) cannot draw become "?"; a host font draws them all. */
+function drawable(text, font) {
+    try {
+        font.encodeText(text);
+        return text;
+    }
+    catch {
+        return Array.from(text, (ch) => {
+            try {
+                font.encodeText(ch);
+                return ch;
+            }
+            catch {
+                return '?';
+            }
+        }).join('');
+    }
+}
+function drawElement(page, el, ox, oy, height, fonts) {
+    const y = (mm) => height - pt(oy + mm);
+    if (el.kind === 'rect') {
+        page.drawRectangle({
+            x: pt(ox + el.x), y: y(el.y + el.h), width: pt(el.w), height: pt(el.h),
+            ...(el.fill ? { color: BLACK } : { borderColor: BLACK, borderWidth: pt(el.stroke ?? 0.3) }),
+        });
+        return;
+    }
+    if (el.kind === 'text') {
+        const font = el.weight === 'bold' ? fonts.bold : fonts.regular;
+        const text = drawable(el.text, font);
+        let size = pt(el.size);
+        const max = pt(el.w);
+        const measured = font.widthOfTextAtSize(text, size);
+        if (measured > max)
+            size *= max / measured;
+        const width = font.widthOfTextAtSize(text, size);
+        const x = el.align === 'center' ? pt(ox + el.x) + (max - width) / 2 : pt(ox + el.x);
+        page.drawText(text, { x, y: y(el.y + el.size * 0.8), size, font, color: el.inverse ? WHITE : BLACK });
+        return;
+    }
+    if (el.masked) {
+        page.drawRectangle({ x: pt(ox + el.x), y: y(el.y + el.h), width: pt(el.w), height: pt(el.h), color: (0, pdf_lib_1.rgb)(0.87, 0.87, 0.87) });
+        return;
+    }
+    const scaleY = el.symbology === 'code128' ? pt(el.h) : pt(el.moduleMm);
+    page.drawSvgPath(scalePath(el.path, pt(el.moduleMm), scaleY), { x: pt(ox + el.x), y: height - pt(oy + el.y), color: BLACK });
+}
+/** Scale an SVG path of M/h/v/z commands by (sx, sy); pdf-lib's own scale is uniform. */
+function scalePath(path, sx, sy) {
+    return path.replace(/([Mhv])(-?[\d.]+)(?: (-?[\d.]+))?/g, (_m, cmd, a, b) => {
+        if (cmd === 'M')
+            return `M${Number(a) * sx} ${Number(b) * sy}`;
+        return `${cmd}${Number(a) * (cmd === 'h' ? sx : sy)}`;
+    });
+}
+/** Render a sheet as a PDF document. */
+async function renderSheetPdf(sheet) {
+    const doc = await pdf_lib_1.PDFDocument.create();
+    let fonts;
+    if (hostFonts) {
+        const fontkit = (await Promise.resolve().then(() => __importStar(require('@pdf-lib/fontkit')))).default;
+        doc.registerFontkit(fontkit);
+        const regular = await doc.embedFont(hostFonts.regular, { subset: true });
+        fonts = { regular, bold: hostFonts.bold ? await doc.embedFont(hostFonts.bold, { subset: true }) : regular };
+    }
+    else {
+        fonts = { regular: await doc.embedFont(pdf_lib_1.StandardFonts.Helvetica), bold: await doc.embedFont(pdf_lib_1.StandardFonts.HelveticaBold) };
+    }
+    const { media } = sheet;
+    const width = pt(media.pageWidthMm);
+    const height = pt(media.pageHeightMm);
+    for (const sheetPage of sheet.pages) {
+        const page = doc.addPage([width, height]);
+        if (sheet.cutMarks) {
+            for (const [x1, y1, x2, y2] of (0, layout_1.cutMarkSegments)(media)) {
+                page.drawLine({ start: { x: pt(x1), y: height - pt(y1) }, end: { x: pt(x2), y: height - pt(y2) }, thickness: pt(0.15), color: BLACK });
+            }
+        }
+        for (const placed of sheetPage.labels) {
+            for (const el of placed.elements)
+                drawElement(page, el, placed.x, placed.y, height, fonts);
+        }
+    }
+    doc.setProducer('Long Tail label sheets');
+    doc.setCreationDate(new Date(0));
+    return doc.save();
+}

package/build/services/labels/targets.d.ts

@@ -0,0 +1,18 @@
+import { type ScanScheme } from '../../types';
+import type { LTApiAuth } from '../../types/sdk';
+import type { LabelSource, LabelTarget } from '../../types/labels';
+export declare const MAX_RANGE_PAD = 12;
+/** Targets from pasted lines or CSV. A first row naming `target` is a header; its columns become item tokens. */
+export declare function parseListSource(text: string): LabelTarget[];
+/** Targets from a numeric run: prefix + zero-padded number + suffix. */
+export declare function expandRangeSource(source: Extract<LabelSource, {
+    kind: 'range';
+}>, max: number): LabelTarget[];
+/**
+ * The targets a source names. Identity schemes read users only: a pasted or
+ * ranged credential would mint a badge for no one. Rows are read as the
+ * caller, so a job never prints what the caller cannot see.
+ */
+export declare function resolveLabelTargets(source: LabelSource, scheme: ScanScheme, auth: LTApiAuth): Promise<LabelTarget[]>;
+/** Marks which action targets name a row today, in one statement. */
+export declare function markResolvedTargets(targets: LabelTarget[], scheme: ScanScheme): Promise<void>;

package/build/services/labels/targets.js

@@ -0,0 +1,216 @@
+"use strict";
+// Resolves a print job's source into targets, reading as the caller.
+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.MAX_RANGE_PAD = void 0;
+exports.parseListSource = parseListSource;
+exports.expandRangeSource = expandRangeSource;
+exports.resolveLabelTargets = resolveLabelTargets;
+exports.markResolvedTargets = markResolvedTargets;
+const db_1 = require("../../lib/db");
+const config_1 = require("../../modules/config");
+const types_1 = require("../../types");
+const errors_1 = require("./errors");
+exports.MAX_RANGE_PAD = 12;
+function cap(scheme) {
+    return scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY
+        ? config_1.config.LT_LABELS_MAX_CREDENTIALS_PER_JOB
+        : config_1.config.LT_LABELS_MAX_PER_JOB;
+}
+function assertCount(n, scheme) {
+    if (n === 0)
+        throw new errors_1.LabelRequestError(400, 'the source names no targets');
+    if (n > cap(scheme))
+        throw new errors_1.LabelRequestError(400, `the source names ${n} targets; one job prints at most ${cap(scheme)}`);
+}
+/** Targets from pasted lines or CSV. A first row naming `target` is a header; its columns become item tokens. */
+function parseListSource(text) {
+    const rows = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+        .map((l) => l.split(/[,\t]/).map((c) => c.trim()));
+    if (rows.length === 0)
+        return [];
+    const header = rows[0][0].toLowerCase() === 'target' ? rows.shift().map((h) => h.replace(/[^a-zA-Z0-9_]/g, '_')) : null;
+    return rows.map((cells) => {
+        const item = {};
+        cells.slice(1).forEach((value, i) => { item[header?.[i + 1] || `col${i + 2}`] = value; });
+        return { target: cells[0], item };
+    });
+}
+/** Targets from a numeric run: prefix + zero-padded number + suffix. */
+function expandRangeSource(source, max) {
+    const { from, to, pad = 0, prefix = '', suffix = '' } = source;
+    if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from) {
+        throw new errors_1.LabelRequestError(400, 'a range needs whole numbers with from ≤ to');
+    }
+    if (!Number.isInteger(pad) || pad < 0 || pad > exports.MAX_RANGE_PAD) {
+        throw new errors_1.LabelRequestError(400, `pad must be between 0 and ${exports.MAX_RANGE_PAD}`);
+    }
+    if (to - from + 1 > max)
+        throw new errors_1.LabelRequestError(400, `the range names ${to - from + 1} targets; one job prints at most ${max}`);
+    return Array.from({ length: to - from + 1 }, (_, i) => ({
+        target: `${prefix}${String(from + i).padStart(pad, '0')}${suffix}`,
+    }));
+}
+/** Rows read at once for a selection; each read applies the caller's own access check. */
+const ESCALATION_READ_CHUNK = 25;
+async function escalationTargets(ids, scheme, auth) {
+    const { getEscalation } = await Promise.resolve().then(() => __importStar(require('../../api/escalations/single')));
+    const unique = [...new Set(ids)];
+    const byTarget = new Map();
+    for (let i = 0; i < unique.length; i += ESCALATION_READ_CHUNK) {
+        const chunk = unique.slice(i, i + ESCALATION_READ_CHUNK);
+        const results = await Promise.all(chunk.map((id) => getEscalation({ id }, auth)));
+        results.forEach((result, j) => {
+            if (result.status !== 200) {
+                throw new errors_1.LabelRequestError(result.status === 404 ? 404 : 403, `escalation ${chunk[j]}: ${result.error}`);
+            }
+            addRow(byTarget, result.data, scheme);
+        });
+    }
+    return [...byTarget.values()];
+}
+async function facetTargets(source, scheme, auth) {
+    const { searchByFacets } = await Promise.resolve().then(() => __importStar(require('../../api/escalations/facets')));
+    const result = await searchByFacets({ ...source.query, limit: cap(scheme) + 1 }, auth);
+    if (result.status !== 200)
+        throw new errors_1.LabelRequestError(result.status === 400 ? 400 : 403, result.error ?? 'facet search refused');
+    const byTarget = new Map();
+    for (const row of result.data.escalations)
+        addRow(byTarget, row, scheme);
+    return [...byTarget.values()];
+}
+/** Keep the newest row per target; a member facet contributes each of its values. */
+function addRow(byTarget, row, scheme) {
+    const value = row.metadata?.[scheme.target_facet];
+    const values = Array.isArray(value) && scheme.target_match === types_1.SCAN_TARGET_MATCH.MEMBER ? value : [value];
+    for (const v of values) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        const target = String(v);
+        const seen = byTarget.get(target);
+        if (!seen || String(row.created_at) > String(seen.item?.__created_at ?? '')) {
+            byTarget.set(target, { target, item: { ...row.metadata, __created_at: row.created_at }, resolved: true });
+        }
+    }
+}
+const USERS_WITH_KEY = `
+  SELECT u.id FROM lt_users u
+  WHERE u.metadata ? $1
+    AND ($2::uuid[] IS NOT NULL OR u.status = 'active')
+    AND ($2::uuid[] IS NULL OR u.id = ANY($2::uuid[]))
+    AND ($3::text IS NULL OR EXISTS (SELECT 1 FROM lt_user_roles r WHERE r.user_id = u.id AND r.role = $3))
+  ORDER BY u.display_name NULLS LAST, u.external_id
+  LIMIT $4`;
+async function userTargets(source, scheme) {
+    const { getUser, getIdentityPropertyKeys } = await Promise.resolve().then(() => __importStar(require('../user')));
+    const { onlyUuids } = await Promise.resolve().then(() => __importStar(require('../../lib/uuid')));
+    const ids = source.userIds ? onlyUuids(source.userIds) : null;
+    if (source.userIds && ids.length !== new Set(source.userIds).size) {
+        throw new errors_1.LabelRequestError(400, 'userIds must be user ids');
+    }
+    const { rows } = await (0, db_1.getPool)().query(USERS_WITH_KEY, [scheme.target_facet, ids, source.role ?? null, cap(scheme) + 1]);
+    const identityKeys = await getIdentityPropertyKeys();
+    const users = await Promise.all(rows.map((r) => getUser(r.id)));
+    return users.filter((u) => u !== null).map((u) => {
+        const metadata = { ...(u.metadata ?? {}) };
+        for (const key of identityKeys)
+            delete metadata[key];
+        return {
+            target: String(u.metadata[scheme.target_facet]),
+            userId: u.id,
+            resolved: u.status === 'active',
+            user: {
+                ...metadata,
+                name: u.display_name ?? u.external_id,
+                display_name: u.display_name,
+                email: u.email,
+                roles: u.roles.map((r) => r.role),
+            },
+        };
+    });
+}
+/**
+ * The targets a source names. Identity schemes read users only: a pasted or
+ * ranged credential would mint a badge for no one. Rows are read as the
+ * caller, so a job never prints what the caller cannot see.
+ */
+async function resolveLabelTargets(source, scheme, auth) {
+    const identity = scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY;
+    if (identity && source.kind !== 'users') {
+        throw new errors_1.LabelRequestError(400, 'identity labels print for users; use a users source');
+    }
+    if (!identity && source.kind === 'users') {
+        throw new errors_1.LabelRequestError(400, 'a users source prints identity labels only');
+    }
+    let targets;
+    switch (source.kind) {
+        case 'escalations':
+            if (!Array.isArray(source.ids))
+                throw new errors_1.LabelRequestError(400, 'ids must be a list');
+            assertCount(new Set(source.ids).size, scheme);
+            targets = await escalationTargets(source.ids, scheme, auth);
+            break;
+        case 'facets':
+            targets = await facetTargets(source, scheme, auth);
+            break;
+        case 'users':
+            targets = await userTargets(source, scheme);
+            break;
+        case 'list':
+            targets = parseListSource(String(source.text ?? ''));
+            break;
+        case 'range':
+            targets = expandRangeSource(source, cap(scheme));
+            break;
+        default:
+            throw new errors_1.LabelRequestError(400, `unknown source kind "${source.kind}"`);
+    }
+    for (const t of targets)
+        delete t.item?.__created_at;
+    assertCount(targets.length, scheme);
+    return targets;
+}
+/** Marks which action targets name a row today, in one statement. */
+async function markResolvedTargets(targets, scheme) {
+    const unchecked = targets.filter((t) => t.resolved === undefined);
+    if (unchecked.length === 0)
+        return;
+    const member = scheme.target_match === types_1.SCAN_TARGET_MATCH.MEMBER;
+    const { rows } = await (0, db_1.getPool)().query(`SELECT t FROM unnest($2::text[]) AS t
+     WHERE EXISTS (SELECT 1 FROM lt_escalations e WHERE e.metadata @> ${member ? 'jsonb_build_object($1::text, jsonb_build_array(t))' : 'jsonb_build_object($1::text, t)'})`, [scheme.target_facet, unchecked.map((t) => t.target)]);
+    const found = new Set(rows.map((r) => r.t));
+    for (const t of unchecked)
+        t.resolved = found.has(t.target);
+}

package/build/services/labels/templates/index.d.ts

@@ -0,0 +1,3 @@
+export { listLabelTemplates, getLabelTemplate, mapTemplate } from './read';
+export { upsertLabelTemplate, deleteLabelTemplate, seedLabelTemplate, applyLabelTemplate, LabelTemplateConflictError, } from './write';
+export { assertValidTemplate, LabelTemplateValidationError, MAX_TEMPLATE_CODES, MAX_TEMPLATE_LINES, type TemplateContext, } from './validate';

package/build/services/labels/templates/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEMPLATE_LINES = exports.MAX_TEMPLATE_CODES = exports.LabelTemplateValidationError = exports.assertValidTemplate = exports.LabelTemplateConflictError = exports.applyLabelTemplate = exports.seedLabelTemplate = exports.deleteLabelTemplate = exports.upsertLabelTemplate = exports.mapTemplate = exports.getLabelTemplate = exports.listLabelTemplates = void 0;
+var read_1 = require("./read");
+Object.defineProperty(exports, "listLabelTemplates", { enumerable: true, get: function () { return read_1.listLabelTemplates; } });
+Object.defineProperty(exports, "getLabelTemplate", { enumerable: true, get: function () { return read_1.getLabelTemplate; } });
+Object.defineProperty(exports, "mapTemplate", { enumerable: true, get: function () { return read_1.mapTemplate; } });
+var write_1 = require("./write");
+Object.defineProperty(exports, "upsertLabelTemplate", { enumerable: true, get: function () { return write_1.upsertLabelTemplate; } });
+Object.defineProperty(exports, "deleteLabelTemplate", { enumerable: true, get: function () { return write_1.deleteLabelTemplate; } });
+Object.defineProperty(exports, "seedLabelTemplate", { enumerable: true, get: function () { return write_1.seedLabelTemplate; } });
+Object.defineProperty(exports, "applyLabelTemplate", { enumerable: true, get: function () { return write_1.applyLabelTemplate; } });
+Object.defineProperty(exports, "LabelTemplateConflictError", { enumerable: true, get: function () { return write_1.LabelTemplateConflictError; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "assertValidTemplate", { enumerable: true, get: function () { return validate_1.assertValidTemplate; } });
+Object.defineProperty(exports, "LabelTemplateValidationError", { enumerable: true, get: function () { return validate_1.LabelTemplateValidationError; } });
+Object.defineProperty(exports, "MAX_TEMPLATE_CODES", { enumerable: true, get: function () { return validate_1.MAX_TEMPLATE_CODES; } });
+Object.defineProperty(exports, "MAX_TEMPLATE_LINES", { enumerable: true, get: function () { return validate_1.MAX_TEMPLATE_LINES; } });

package/build/services/labels/templates/read.d.ts

@@ -0,0 +1,4 @@
+import type { LabelTemplate } from '../../../types/labels';
+export declare function mapTemplate(row: any): LabelTemplate;
+export declare function listLabelTemplates(schemeVersion?: number): Promise<LabelTemplate[]>;
+export declare function getLabelTemplate(name: string): Promise<LabelTemplate | null>;

package/build/services/labels/templates/read.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapTemplate = mapTemplate;
+exports.listLabelTemplates = listLabelTemplates;
+exports.getLabelTemplate = getLabelTemplate;
+const db_1 = require("../../../lib/db");
+const sql_1 = require("./sql");
+function mapTemplate(row) {
+    return {
+        name: row.name,
+        scheme_version: row.scheme_version,
+        title: row.title,
+        description: row.description ?? null,
+        codes: row.codes ?? [],
+        text: row.text ?? {},
+        symbology: row.symbology,
+        human_readable: row.human_readable,
+        media: row.media ?? null,
+        sensitive: row.sensitive,
+        enabled: row.enabled,
+        revision: row.revision,
+        source: row.source,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+async function listLabelTemplates(schemeVersion) {
+    const { rows } = schemeVersion === undefined
+        ? await (0, db_1.getPool)().query(sql_1.LIST_TEMPLATES)
+        : await (0, db_1.getPool)().query(sql_1.LIST_TEMPLATES_BY_SCHEME, [schemeVersion]);
+    return rows.map(mapTemplate);
+}
+async function getLabelTemplate(name) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_TEMPLATE, [name]);
+    return rows[0] ? mapTemplate(rows[0]) : null;
+}

package/build/services/labels/templates/sql.d.ts

@@ -0,0 +1,8 @@
+export declare const LIST_TEMPLATES = "SELECT * FROM lt_config_label_templates ORDER BY scheme_version, name";
+export declare const LIST_TEMPLATES_BY_SCHEME = "SELECT * FROM lt_config_label_templates WHERE scheme_version = $1 ORDER BY name";
+export declare const GET_TEMPLATE = "SELECT * FROM lt_config_label_templates WHERE name = $1";
+export declare const DELETE_TEMPLATE = "DELETE FROM lt_config_label_templates WHERE name = $1";
+/** API write. $13 is the expected revision; null writes unconditionally. */
+export declare const UPSERT_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO UPDATE SET scheme_version = EXCLUDED.scheme_version,\n  title = EXCLUDED.title,\n  description = EXCLUDED.description,\n  codes = EXCLUDED.codes,\n  text = EXCLUDED.text,\n  symbology = EXCLUDED.symbology,\n  human_readable = EXCLUDED.human_readable,\n  media = EXCLUDED.media,\n  sensitive = EXCLUDED.sensitive,\n  enabled = EXCLUDED.enabled,\n  source = EXCLUDED.source,\n  revision = lt_config_label_templates.revision + 1\nWHERE $13::int IS NULL OR lt_config_label_templates.revision = $13::int\nRETURNING *";
+export declare const SEED_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO NOTHING";
+export declare const APPLY_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO UPDATE SET scheme_version = EXCLUDED.scheme_version,\n  title = EXCLUDED.title,\n  description = EXCLUDED.description,\n  codes = EXCLUDED.codes,\n  text = EXCLUDED.text,\n  symbology = EXCLUDED.symbology,\n  human_readable = EXCLUDED.human_readable,\n  media = EXCLUDED.media,\n  sensitive = EXCLUDED.sensitive,\n  enabled = EXCLUDED.enabled,\n  source = EXCLUDED.source,\n  revision = lt_config_label_templates.revision + 1\nWHERE (lt_config_label_templates.scheme_version, lt_config_label_templates.title,\n       lt_config_label_templates.description, lt_config_label_templates.codes,\n       lt_config_label_templates.text, lt_config_label_templates.symbology,\n       lt_config_label_templates.human_readable, lt_config_label_templates.media,\n       lt_config_label_templates.sensitive, lt_config_label_templates.enabled,\n       lt_config_label_templates.source)\n  IS DISTINCT FROM\n      (EXCLUDED.scheme_version, EXCLUDED.title, EXCLUDED.description, EXCLUDED.codes,\n       EXCLUDED.text, EXCLUDED.symbology, EXCLUDED.human_readable, EXCLUDED.media,\n       EXCLUDED.sensitive, EXCLUDED.enabled, EXCLUDED.source)\nRETURNING (xmax = 0) AS inserted";

package/build/services/labels/templates/sql.js

@@ -0,0 +1,50 @@
+"use strict";
+// lt_config_label_templates. Writes bump `revision`; the apply pass is a
+// zero-row no-op when the declaration is unchanged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLY_TEMPLATE = exports.SEED_TEMPLATE = exports.UPSERT_TEMPLATE = exports.DELETE_TEMPLATE = exports.GET_TEMPLATE = exports.LIST_TEMPLATES_BY_SCHEME = exports.LIST_TEMPLATES = void 0;
+const COLUMNS = `name, scheme_version, title, description, codes, text, symbology,
+   human_readable, media, sensitive, enabled, source`;
+const VALUES = '$1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12';
+const SET = `scheme_version = EXCLUDED.scheme_version,
+  title = EXCLUDED.title,
+  description = EXCLUDED.description,
+  codes = EXCLUDED.codes,
+  text = EXCLUDED.text,
+  symbology = EXCLUDED.symbology,
+  human_readable = EXCLUDED.human_readable,
+  media = EXCLUDED.media,
+  sensitive = EXCLUDED.sensitive,
+  enabled = EXCLUDED.enabled,
+  source = EXCLUDED.source,
+  revision = lt_config_label_templates.revision + 1`;
+exports.LIST_TEMPLATES = 'SELECT * FROM lt_config_label_templates ORDER BY scheme_version, name';
+exports.LIST_TEMPLATES_BY_SCHEME = 'SELECT * FROM lt_config_label_templates WHERE scheme_version = $1 ORDER BY name';
+exports.GET_TEMPLATE = 'SELECT * FROM lt_config_label_templates WHERE name = $1';
+exports.DELETE_TEMPLATE = 'DELETE FROM lt_config_label_templates WHERE name = $1';
+/** API write. $13 is the expected revision; null writes unconditionally. */
+exports.UPSERT_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO UPDATE SET ${SET}
+WHERE $13::int IS NULL OR lt_config_label_templates.revision = $13::int
+RETURNING *`;
+exports.SEED_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO NOTHING`;
+exports.APPLY_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO UPDATE SET ${SET}
+WHERE (lt_config_label_templates.scheme_version, lt_config_label_templates.title,
+       lt_config_label_templates.description, lt_config_label_templates.codes,
+       lt_config_label_templates.text, lt_config_label_templates.symbology,
+       lt_config_label_templates.human_readable, lt_config_label_templates.media,
+       lt_config_label_templates.sensitive, lt_config_label_templates.enabled,
+       lt_config_label_templates.source)
+  IS DISTINCT FROM
+      (EXCLUDED.scheme_version, EXCLUDED.title, EXCLUDED.description, EXCLUDED.codes,
+       EXCLUDED.text, EXCLUDED.symbology, EXCLUDED.human_readable, EXCLUDED.media,
+       EXCLUDED.sensitive, EXCLUDED.enabled, EXCLUDED.source)
+RETURNING (xmax = 0) AS inserted`;

package/build/services/labels/templates/validate.d.ts

@@ -0,0 +1,19 @@
+import { type ScanRule, type ScanScheme } from '../../../types';
+import type { LabelTemplateInput } from '../../../types/labels';
+/** A template declaration that cannot be stored. */
+export declare class LabelTemplateValidationError extends Error {
+    status: number;
+    constructor(message: string);
+}
+export declare const MAX_TEMPLATE_CODES = 4;
+export declare const MAX_TEMPLATE_LINES = 2;
+export interface TemplateContext {
+    scheme: ScanScheme | null;
+    rules: ScanRule[];
+    /** Every identity key in use, so a token can never print a credential as text. */
+    identityKeys: string[];
+    /** Media preset ids the deployment knows. */
+    mediaIds: string[];
+}
+/** Throws LabelTemplateValidationError unless the template fits its scheme. */
+export declare function assertValidTemplate(input: LabelTemplateInput, ctx: TemplateContext): void;

package/build/services/labels/templates/validate.js

@@ -0,0 +1,93 @@
+"use strict";
+// Template validation against its scheme, its rules and the identity keys.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEMPLATE_LINES = exports.MAX_TEMPLATE_CODES = exports.LabelTemplateValidationError = void 0;
+exports.assertValidTemplate = assertValidTemplate;
+const types_1 = require("../../../shared/labels/types");
+const compose_1 = require("../../../shared/labels/compose");
+const tokens_1 = require("../../../shared/labels/tokens");
+const types_2 = require("../../../types");
+/** A template declaration that cannot be stored. */
+class LabelTemplateValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.status = 400;
+        this.name = 'LabelTemplateValidationError';
+    }
+}
+exports.LabelTemplateValidationError = LabelTemplateValidationError;
+exports.MAX_TEMPLATE_CODES = 4;
+exports.MAX_TEMPLATE_LINES = 2;
+const MAX_TEXT_LENGTH = 160;
+const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function fail(message) {
+    throw new LabelTemplateValidationError(message);
+}
+function assertText(label, text) {
+    if (typeof text !== 'string')
+        fail(`${label} must be text`);
+    if (text.length > MAX_TEXT_LENGTH)
+        fail(`${label} is longer than ${MAX_TEXT_LENGTH} characters`);
+}
+/** Throws LabelTemplateValidationError unless the template fits its scheme. */
+function assertValidTemplate(input, ctx) {
+    if (typeof input.name !== 'string' || !NAME.test(input.name)) {
+        fail('name must be lowercase letters, digits and dashes, starting with a letter or digit');
+    }
+    const { scheme } = ctx;
+    if (!scheme)
+        fail(`scan scheme ${input.scheme_version} does not exist`);
+    if (!(0, compose_1.isMintableScheme)(scheme)) {
+        fail(`scheme ${scheme.version} reads ${scheme.encoding} codes; templates print fixed and delimited codes only`);
+    }
+    if (!input.title || typeof input.title !== 'string')
+        fail('title is required');
+    assertText('title', input.title);
+    if (input.description != null)
+        assertText('description', input.description);
+    if (!Array.isArray(input.codes) || input.codes.length < 1 || input.codes.length > exports.MAX_TEMPLATE_CODES) {
+        fail(`a template prints 1 to ${exports.MAX_TEMPLATE_CODES} codes`);
+    }
+    const categories = new Set();
+    for (const code of input.codes) {
+        if (!ctx.rules.some((r) => r.category === code.category)) {
+            fail(`scheme ${scheme.version} has no rule for category "${code.category}"`);
+        }
+        if (categories.has(code.category))
+            fail(`category "${code.category}" is printed twice`);
+        categories.add(code.category);
+        if (!types_1.LABEL_TONES.includes(code.tone))
+            fail(`tone must be one of ${types_1.LABEL_TONES.join(', ')}`);
+        if (code.caption != null)
+            assertText('caption', code.caption);
+    }
+    const lines = input.text?.lines ?? [];
+    if (!Array.isArray(lines) || lines.length > exports.MAX_TEMPLATE_LINES)
+        fail(`a template prints up to ${exports.MAX_TEMPLATE_LINES} lines`);
+    const texts = [input.text?.title ?? '', ...lines, ...input.codes.map((c) => c.caption ?? '')];
+    texts.forEach((t, i) => assertText(i === 0 ? 'text title' : 'text line', t));
+    const identity = scheme.kind === types_2.SCAN_SCHEME_KINDS.IDENTITY;
+    for (const text of texts) {
+        const unknown = (0, tokens_1.unknownLabelTokens)(text);
+        if (unknown.length)
+            fail(`unknown token {${unknown[0]}}; use {target}, {item.<facet>}, {user.<key>} or {scheme.name}`);
+        const tokens = (0, tokens_1.listLabelTokens)(text);
+        if (identity && tokens.some((t) => t.startsWith('item.')))
+            fail('an identity template reads {user.<key>} tokens, not {item.<facet>}');
+        if (!identity && tokens.some((t) => t.startsWith('user.')))
+            fail('{user.<key>} tokens print on identity templates only');
+        const credential = (0, tokens_1.userTokenKeys)(text).find((k) => ctx.identityKeys.includes(k) || k === scheme.target_facet);
+        if (credential)
+            fail(`{user.${credential}} is an identity credential and never prints as text`);
+        if (identity && tokens.includes('target'))
+            fail('{target} on an identity template is the credential; it never prints as text');
+    }
+    const symbology = input.symbology ?? 'code128';
+    if (!types_1.LABEL_SYMBOLOGIES.includes(symbology)) {
+        fail(`symbology must be one of ${types_1.LABEL_SYMBOLOGIES.join(', ')}`);
+    }
+    if (input.media != null && !ctx.mediaIds.includes(input.media))
+        fail(`unknown media "${input.media}"`);
+    if (identity && input.sensitive === false)
+        fail('a template on an identity scheme is always sensitive');
+}

package/build/services/labels/templates/write.d.ts

@@ -0,0 +1,16 @@
+import type { LabelTemplate, LabelTemplateInput } from '../../../types/labels';
+/** An API write raced another: the stored revision is not the one the caller read. */
+export declare class LabelTemplateConflictError extends Error {
+    status: number;
+    constructor(name: string, revision: number);
+}
+/**
+ * Create or replace a template from the API. With `expectedRevision`, the
+ * write lands only on that revision; otherwise LabelTemplateConflictError.
+ */
+export declare function upsertLabelTemplate(input: LabelTemplateInput, expectedRevision?: number): Promise<LabelTemplate>;
+export declare function deleteLabelTemplate(name: string): Promise<boolean>;
+/** Insert a template only when absent (database-owned configuration). */
+export declare function seedLabelTemplate(input: LabelTemplateInput): Promise<boolean>;
+/** Apply a template declared in code; unchanged declarations write nothing. */
+export declare function applyLabelTemplate(input: LabelTemplateInput): Promise<'applied' | 'unchanged'>;