@hotmeshio/long-tail 0.22.1 → 0.22.2

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

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertValidScheme = assertValidScheme;
+exports.assertSchemesCoexist = assertSchemesCoexist;
 exports.assertValidIdentityRule = assertValidIdentityRule;
 exports.assertValidSteps = assertValidSteps;
 const types_1 = require("../../types");
+const scan_code_1 = require("../../shared/scan-code");
 const facet_sql_1 = require("../escalation/facet-sql");
+const validate_subject_1 = require("./validate-subject");
 const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
 /** Double-scan selection tokens — short, label-printable, never scheme-shaped. */
 const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
@@ -22,6 +25,12 @@ function assertValidScheme(scheme) {
     if (!scheme.target_facet)
         throw new Error('scheme target_facet is required');
     const encoding = scheme.encoding ?? types_1.SCAN_ENCODINGS.FIXED;
+    if (!Object.values(types_1.SCAN_ENCODINGS).includes(encoding)) {
+        throw new Error(`unknown scheme encoding "${encoding}"`);
+    }
+    if (encoding === types_1.SCAN_ENCODINGS.GTIN && (scheme.kind ?? types_1.SCAN_SCHEME_KINDS.ACTION) !== types_1.SCAN_SCHEME_KINDS.ACTION) {
+        throw new Error('gtin encoding applies only to action schemes');
+    }
     if (encoding === types_1.SCAN_ENCODINGS.FIXED) {
         if (!Number.isInteger(scheme.target_length) || scheme.target_length < 1) {
             throw new Error('fixed encoding requires a positive integer target_length');
@@ -48,11 +57,50 @@ function assertValidScheme(scheme) {
         if (!Number.isInteger(scheme.grant_max_uses ?? 0) || (scheme.grant_max_uses ?? 0) < 0) {
             throw new Error('grant_max_uses must be a non-negative integer');
         }
+        const scope = scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION;
+        if (!Object.values(types_1.SCAN_GRANT_SCOPES).includes(scope)) {
+            throw new Error(`unknown grant_scope "${scope}"`);
+        }
     }
-    else if (scheme.grant_ttl_seconds != null || (scheme.grant_max_uses ?? 0) !== 0) {
+    else if (scheme.grant_ttl_seconds != null || (scheme.grant_max_uses ?? 0) !== 0
+        || (scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION) !== types_1.SCAN_GRANT_SCOPES.ACTION) {
         throw new Error('grant policy applies only to identity schemes');
     }
 }
+/**
+ * A scheme must read codes no other scheme reads. Delimited and fixed
+ * schemes are told apart by their version prefix; a gtin scheme has none,
+ * so there is at most one, and no enabled fixed scheme may accept a GTIN
+ * length while it is enabled. Throws naming both schemes.
+ */
+function assertSchemesCoexist(candidate, existing) {
+    const others = existing.filter((s) => s.version !== candidate.version);
+    const encoding = candidate.encoding ?? types_1.SCAN_ENCODINGS.FIXED;
+    const enabled = candidate.enabled ?? true;
+    if (encoding === types_1.SCAN_ENCODINGS.GTIN) {
+        const gtin = others.find((s) => s.encoding === types_1.SCAN_ENCODINGS.GTIN);
+        if (gtin) {
+            throw new Error(`scheme ${gtin.version} ("${gtin.name}") already reads manufacturer barcodes; only one gtin scheme is allowed`);
+        }
+        if (!enabled)
+            return;
+        const clash = others.find((s) => s.enabled && s.encoding === types_1.SCAN_ENCODINGS.FIXED
+            && (0, scan_code_1.fixedCodeLengths)(s).some((n) => types_1.GTIN_LENGTHS.includes(n)));
+        if (clash) {
+            throw new Error(`fixed scheme ${clash.version} ("${clash.name}") accepts ${(0, scan_code_1.fixedCodeLengths)(clash).join(' or ')}-digit codes, which a gtin scheme also reads; change its target_length or leave the gtin scheme disabled`);
+        }
+        return;
+    }
+    if (encoding === types_1.SCAN_ENCODINGS.FIXED && enabled) {
+        const lengths = (0, scan_code_1.fixedCodeLengths)({ target_length: candidate.target_length ?? null });
+        if (!lengths.some((n) => types_1.GTIN_LENGTHS.includes(n)))
+            return;
+        const gtin = others.find((s) => s.enabled && s.encoding === types_1.SCAN_ENCODINGS.GTIN);
+        if (gtin) {
+            throw new Error(`a fixed scheme accepting ${lengths.join(' or ')}-digit codes collides with gtin scheme ${gtin.version} ("${gtin.name}"); change target_length or disable the gtin scheme`);
+        }
+    }
+}
 /** Identity rules never walk steps — their fallback is the unknown-badge screen. */
 function assertValidIdentityRule(steps) {
     if (Array.isArray(steps) && steps.length > 0) {
@@ -73,7 +121,8 @@ function assertValidChoices(choices, at) {
             throw new Error(`${cat}: label is required`);
         if (!VALID_VERBS.has(choice.verb))
             throw new Error(`${cat}: unknown verb "${choice.verb}"`);
-        if (choice.verb === types_1.SCAN_VERBS.PRESENT || choice.verb === types_1.SCAN_VERBS.SHOW_LIST) {
+        if (choice.verb === types_1.SCAN_VERBS.PRESENT || choice.verb === types_1.SCAN_VERBS.SHOW_LIST
+            || choice.verb === types_1.SCAN_VERBS.FILL) {
             throw new Error(`${cat}: ${choice.verb} cannot be a choice verb`);
         }
         if (choice.confirm && !choice.confirm.prompt) {
@@ -172,14 +221,23 @@ function assertValidSteps(steps) {
                     && (!container.facets || typeof container.facets !== 'object' || Array.isArray(container.facets))) {
                     throw new Error(`${at}: params.accumulate.container.facets must be an object`);
                 }
-                if (!options?.containerFacet) {
-                    throw new Error(`${at}: params.accumulate.container requires params.accumulate.containerFacet`);
+                if (!options?.containerFacet && options?.from !== 'subject') {
+                    throw new Error(`${at}: params.accumulate.container requires params.accumulate.containerFacet or from: 'subject'`);
                 }
             }
-            if (!options?.containerFacet && !step.params?.itemKey) {
+            if (!options?.containerFacet && !options?.into && !step.params?.itemKey) {
                 throw new Error(`${at}: accumulate requires params.itemKey or params.accumulate.containerFacet`);
             }
         }
+        (0, validate_subject_1.assertValidSubjectStep)(step, at);
+        if (step.done !== undefined) {
+            if (!step.done || typeof step.done !== 'object' || typeof step.done.markdown !== 'string' || !step.done.markdown) {
+                throw new Error(`${at}: done.markdown is required`);
+            }
+            if (!types_1.SCAN_MUTATING_VERBS.includes(step.verb)) {
+                throw new Error(`${at}: done applies only to steps that write`);
+            }
+        }
         assertValidTemplateTokens(step, at);
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);
@@ -198,21 +256,39 @@ function assertValidSteps(steps) {
         }
     });
 }
-const BAG_TOKEN = /\{(claim|item)\.([^}]*)\}/g;
+const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([^}]*)\}/g;
 /**
- * `{claim.<facet>}` and `{item.<facet>}` name facet keys; `{item.…}` reads
- * the located row, which only an item-mode accumulate step has.
+ * Bag tokens name facet keys and may only read what the step has:
+ * `{item.…}` the row an item-mode accumulate or a hold located,
+ * `{subject.…}` the held subject (steps with a subject gate), and
+ * `{container.…}` / `{fill.…}` only inside refusal and done copy, where a
+ * subject accumulate or a fill has read them.
  */
 function assertValidTemplateTokens(step, at) {
-    const text = JSON.stringify(step.params ?? {});
-    const itemMode = step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet;
-    for (const match of text.matchAll(BAG_TOKEN)) {
-        const [token, bag, facet] = match;
-        if (!facet_sql_1.FACET_KEY.test(facet)) {
-            throw new Error(`${at}: template token ${token} must name a facet key`);
-        }
-        if (bag === 'item' && !itemMode) {
-            throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate step has`);
+    const itemRow = (step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet)
+        || step.verb === types_1.SCAN_VERBS.HOLD;
+    const check = (value, inRefusal) => {
+        for (const match of JSON.stringify(value ?? {}).matchAll(BAG_TOKEN)) {
+            const [token, bag, facet] = match;
+            if (!facet_sql_1.FACET_KEY.test(facet)) {
+                throw new Error(`${at}: template token ${token} must name a facet key`);
+            }
+            if (bag === 'item' && !itemRow) {
+                throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate or a hold step has`);
+            }
+            if (bag === 'subject' && !step.subject) {
+                throw new Error(`${at}: ${token} reads the held subject, which only a step with a subject gate has`);
+            }
+            if (bag === 'container' && !(inRefusal && step.params?.accumulate?.from === 'subject')) {
+                throw new Error(`${at}: ${token} is readable only in the refusal or done copy of a from-subject accumulate step`);
+            }
+            if (bag === 'fill' && !(inRefusal && step.verb === types_1.SCAN_VERBS.FILL)) {
+                throw new Error(`${at}: ${token} is readable only in the refusal or done copy of a fill step`);
+            }
         }
-    }
+    };
+    check(step.params, false);
+    check(step.match, false);
+    check(step.refuse, true);
+    check(step.done, true);
 }

package/build/services/scan-code/write.d.ts

@@ -10,6 +10,7 @@ export interface ScanSchemeInput {
     kind?: ScanScheme['kind'];
     grant_ttl_seconds?: number | null;
     grant_max_uses?: number;
+    grant_scope?: ScanScheme['grant_scope'];
     enabled?: boolean;
 }
 export interface ScanRuleInput {

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

@@ -13,6 +13,11 @@ const types_1 = require("../../types");
 const sql_1 = require("./sql");
 const validate_1 = require("./validate");
 const read_1 = require("./read");
+/** Field validation, then the cross-scheme check against what is stored. */
+async function assertSchemeInput(input) {
+    (0, validate_1.assertValidScheme)(input);
+    (0, validate_1.assertSchemesCoexist)(input, await (0, read_1.listScanSchemes)());
+}
 function schemeParams(input) {
     return [
         input.version,
@@ -26,6 +31,7 @@ function schemeParams(input) {
         input.grant_ttl_seconds ?? null,
         input.grant_max_uses ?? 0,
         input.enabled ?? true,
+        input.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION,
     ];
 }
 function ruleParams(input) {
@@ -49,7 +55,7 @@ async function assertStepsForScheme(input) {
     (0, validate_1.assertValidSteps)(input.steps);
 }
 async function upsertScanScheme(input) {
-    (0, validate_1.assertValidScheme)(input);
+    await assertSchemeInput(input);
     const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_SCHEME, schemeParams(input));
     return rows[0];
 }
@@ -80,7 +86,7 @@ async function deleteScanRule(schemeVersion, category) {
 }
 /** Insert-if-absent seeding — DB is the source of truth, never overwrite. */
 async function seedScanScheme(input) {
-    (0, validate_1.assertValidScheme)(input);
+    await assertSchemeInput(input);
     const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_SCHEME, schemeParams(input));
     return (rowCount ?? 0) > 0;
 }
@@ -95,7 +101,7 @@ async function seedScanRule(input) {
  * declaration a zero-row no-op.
  */
 async function applyScanScheme(input) {
-    (0, validate_1.assertValidScheme)(input);
+    await assertSchemeInput(input);
     const { rowCount } = await (0, db_1.getPool)().query(sql_1.APPLY_SCHEME, schemeParams(input));
     return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
 }

package/build/shared/form-validation/field-validator.js

@@ -7,6 +7,7 @@ exports.validateRequireAll = validateRequireAll;
 exports.validateFieldType = validateFieldType;
 exports.validateFieldConstraints = validateFieldConstraints;
 exports.validateField = validateField;
+const x_lt_scan_1 = require("./x-lt-scan");
 const x_lt_options_1 = require("./x-lt-options");
 const ctx_path_1 = require("./ctx-path");
 /**
@@ -160,6 +161,9 @@ function validateFieldConstraints(value, fieldSchema, ctx) {
             return `Must be one of: ${allowed.map((o) => String(o.value)).join(', ')}`;
         }
     }
+    const scanError = (0, x_lt_scan_1.scanSinkError)(value, fieldSchema, ctx);
+    if (scanError)
+        return scanError;
     if (Array.isArray(value)) {
         return isEditableList(fieldSchema) ? validateListConstraints(value, fieldSchema, allowed, ctx) : undefined;
     }

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

@@ -22,3 +22,4 @@ export * from './validate-resolver-payload';
 export * from './invoke-context';
 export * from './display-only-widgets';
 export * from './x-lt-invoke';
+export * from './x-lt-scan';

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

@@ -38,3 +38,4 @@ __exportStar(require("./validate-resolver-payload"), exports);
 __exportStar(require("./invoke-context"), exports);
 __exportStar(require("./display-only-widgets"), exports);
 __exportStar(require("./x-lt-invoke"), exports);
+__exportStar(require("./x-lt-scan"), exports);

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

@@ -0,0 +1,52 @@
+export declare const X_LT_SCAN = "x-lt-scan";
+export declare const X_LT_SCAN_SUBMIT = "x-lt-scan-submit";
+export declare const X_LT_ORDER = "x-lt-order";
+export interface ScanSink {
+    schemes: number[];
+    /** The scanned target (default) or the code as scanned. */
+    value: 'target' | 'code';
+    /** Context paths whose values the field accepts. */
+    expect?: string[];
+    expectError: string;
+    /** Array fields: 'count' takes a value as many times as it is expected. */
+    multiplicity: 'count' | 'once';
+}
+/** The parts of a parsed scan a sink reads. */
+export interface SinkScan {
+    version: number;
+    target: string;
+    code: string;
+}
+type Schema = Record<string, unknown>;
+/** The field's scan configuration, or null when it takes no scans. */
+export declare function readScanSink(fieldSchema: Schema | undefined): ScanSink | null;
+/** Manufacturer barcodes compare as GTINs, so a UPC-A matches its 14-digit form. */
+export declare function sameScanValue(a: string, b: string): boolean;
+/** The values the field accepts, flattened; null when it declares none. */
+export declare function resolveScanExpected(sink: ScanSink, ctx: Record<string, unknown> | undefined): string[] | null;
+/**
+ * The field's error for its current value against what it expects, or
+ * undefined. Strings must be one of the expected values; arrays may hold
+ * each expected value once (or as many times as expected, with 'count').
+ */
+export declare function scanSinkError(value: unknown, fieldSchema: Schema | undefined, ctx: Record<string, unknown> | undefined): string | undefined;
+/** What a scan does to a field: the next value, or the error to show (nothing written). */
+export declare function applyScanToField(current: unknown, scan: SinkScan, fieldSchema: Schema, ctx: Record<string, unknown> | undefined): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The field a scan from `version` fills: the focused field when it takes
+ * that scheme, otherwise the first (in x-lt-order) that takes it and has
+ * room, otherwise the first that takes it. Null: no field takes it, so the
+ * scan runs globally.
+ */
+export declare function pickScanSink(schema: Schema | null | undefined, values: Record<string, unknown>, version: number, focusedField?: string | null): string | null;
+/** True when the form submits on its own once its scan fields are filled. */
+export declare function wantsScanSubmit(schema: Schema | null | undefined): boolean;
+/** True when every required scan field holds a value. */
+export declare function scanFieldsFilled(schema: Schema | null | undefined, values: Record<string, unknown>): boolean;
+export {};

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

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_ORDER = exports.X_LT_SCAN_SUBMIT = exports.X_LT_SCAN = void 0;
+exports.readScanSink = readScanSink;
+exports.sameScanValue = sameScanValue;
+exports.resolveScanExpected = resolveScanExpected;
+exports.scanSinkError = scanSinkError;
+exports.applyScanToField = applyScanToField;
+exports.pickScanSink = pickScanSink;
+exports.wantsScanSubmit = wantsScanSubmit;
+exports.scanFieldsFilled = scanFieldsFilled;
+/**
+ * x-lt-scan: a form field that takes a scan.
+ *
+ * While a form is open and editable, a scan whose scheme a field accepts
+ * fills that field instead of running globally. The field may declare what
+ * it expects (paths into the escalation context); a scan outside that set
+ * is a field error and is not written, and the same check runs server-side
+ * at submit, so a typed wrong value is refused there too.
+ *
+ *   "containerCode": { "type": "string", "x-lt-scan": {
+ *      "schemes": [14], "expect": ["metadata.containerCode"],
+ *      "expect-error": "This item goes in {{expected}}." } }
+ *   "parts": { "type": "array", "items": { "type": "string" },
+ *      "x-lt-scan": { "schemes": [16], "expect": ["envelope.expected_upcs"], "multiplicity": "count" } }
+ *
+ * Root `x-lt-scan-submit: true` submits once every required scan field is
+ * filled and the form validates. A string field is replaced by a scan; an
+ * array field appends, and with `multiplicity: "count"` a value expected n
+ * times takes n scans.
+ */
+const ctx_path_1 = require("./ctx-path");
+exports.X_LT_SCAN = 'x-lt-scan';
+exports.X_LT_SCAN_SUBMIT = 'x-lt-scan-submit';
+exports.X_LT_ORDER = 'x-lt-order';
+const DEFAULT_EXPECT_ERROR = 'Expected {{expected}}';
+/** The field's scan configuration, or null when it takes no scans. */
+function readScanSink(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_SCAN];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const cfg = raw;
+    const schemes = Array.isArray(cfg.schemes) ? cfg.schemes.filter((v) => Number.isInteger(v)) : [];
+    if (schemes.length === 0)
+        return null;
+    const expect = Array.isArray(cfg.expect) ? cfg.expect.filter((v) => typeof v === 'string') : undefined;
+    return {
+        schemes,
+        value: cfg.value === 'code' ? 'code' : 'target',
+        ...(expect?.length ? { expect } : {}),
+        expectError: typeof cfg['expect-error'] === 'string' ? cfg['expect-error'] : DEFAULT_EXPECT_ERROR,
+        multiplicity: cfg.multiplicity === 'count' ? 'count' : 'once',
+    };
+}
+/** Manufacturer barcodes compare as GTINs, so a UPC-A matches its 14-digit form. */
+function sameScanValue(a, b) {
+    if (a === b)
+        return true;
+    const gtin = /^[0-9]{8,14}$/;
+    return gtin.test(a) && gtin.test(b) && a.padStart(14, '0') === b.padStart(14, '0');
+}
+/** The values the field accepts, flattened; null when it declares none. */
+function resolveScanExpected(sink, ctx) {
+    if (!sink.expect)
+        return null;
+    const out = [];
+    for (const path of sink.expect) {
+        const value = (0, ctx_path_1.resolveCtxPath)(path, ctx);
+        const list = Array.isArray(value) ? value : [value];
+        for (const v of list) {
+            if (typeof v === 'string' && v)
+                out.push(v);
+            else if (typeof v === 'number')
+                out.push(String(v));
+        }
+    }
+    return out;
+}
+function expectMessage(sink, expected) {
+    return sink.expectError.replace(/\{\{\s*expected\s*\}\}/g, [...new Set(expected)].join(', ') || 'nothing');
+}
+/**
+ * The field's error for its current value against what it expects, or
+ * undefined. Strings must be one of the expected values; arrays may hold
+ * each expected value once (or as many times as expected, with 'count').
+ */
+function scanSinkError(value, fieldSchema, ctx) {
+    const sink = readScanSink(fieldSchema);
+    if (!sink)
+        return undefined;
+    const expected = resolveScanExpected(sink, ctx);
+    if (expected === null)
+        return undefined;
+    const values = Array.isArray(value) ? value : value === undefined || value === null || value === '' ? [] : [value];
+    // Each expected value admits one scan; 'count' keeps repeats as separate admissions.
+    const budget = sink.multiplicity === 'count' ? [...expected] : [...new Set(expected)];
+    for (const v of values) {
+        const at = budget.findIndex((e) => sameScanValue(String(v), e));
+        if (at === -1)
+            return expectMessage(sink, expected);
+        budget.splice(at, 1);
+    }
+    return undefined;
+}
+/** What a scan does to a field: the next value, or the error to show (nothing written). */
+function applyScanToField(current, scan, fieldSchema, ctx) {
+    const sink = readScanSink(fieldSchema);
+    if (!sink)
+        return { ok: false, error: 'This field takes no scans' };
+    const scanned = sink.value === 'code' ? scan.code : scan.target;
+    const isArray = fieldSchema.type === 'array';
+    const next = isArray ? [...(Array.isArray(current) ? current : []), scanned] : scanned;
+    const error = scanSinkError(next, fieldSchema, ctx);
+    if (error)
+        return { ok: false, error };
+    const max = fieldSchema.maxItems;
+    if (isArray && typeof max === 'number' && next.length > max) {
+        return { ok: false, error: `At most ${max}` };
+    }
+    return { ok: true, value: next };
+}
+/** True when the field has room for another scan. */
+function hasRoom(value, fieldSchema) {
+    if (fieldSchema.type === 'array') {
+        const max = fieldSchema.maxItems;
+        return typeof max !== 'number' || !Array.isArray(value) || value.length < max;
+    }
+    return value === undefined || value === null || value === '';
+}
+/**
+ * The field a scan from `version` fills: the focused field when it takes
+ * that scheme, otherwise the first (in x-lt-order) that takes it and has
+ * room, otherwise the first that takes it. Null: no field takes it, so the
+ * scan runs globally.
+ */
+function pickScanSink(schema, values, version, focusedField) {
+    const properties = (schema?.properties ?? {});
+    const order = Array.isArray(schema?.[exports.X_LT_ORDER]) ? schema[exports.X_LT_ORDER] : [];
+    const names = [...order.filter((n) => n in properties), ...Object.keys(properties).filter((n) => !order.includes(n))];
+    const takes = names.filter((n) => readScanSink(properties[n])?.schemes.includes(version));
+    if (takes.length === 0)
+        return null;
+    if (focusedField && takes.includes(focusedField))
+        return focusedField;
+    return takes.find((n) => hasRoom(values[n], properties[n])) ?? takes[0];
+}
+/** True when the form submits on its own once its scan fields are filled. */
+function wantsScanSubmit(schema) {
+    return schema?.[exports.X_LT_SCAN_SUBMIT] === true;
+}
+/** True when every required scan field holds a value. */
+function scanFieldsFilled(schema, values) {
+    const properties = (schema?.properties ?? {});
+    const required = new Set(schema?.required ?? []);
+    const sinks = Object.keys(properties).filter((n) => readScanSink(properties[n]) && required.has(n));
+    if (sinks.length === 0)
+        return false;
+    return sinks.every((n) => {
+        const v = values[n];
+        if (Array.isArray(v)) {
+            const min = properties[n].minItems;
+            return v.length >= (typeof min === 'number' ? min : 1);
+        }
+        return v !== undefined && v !== null && v !== '';
+    });
+}

package/build/shared/scan-code/gtin.d.ts

@@ -0,0 +1,5 @@
+export declare const GTIN_CODE_LENGTHS: readonly number[];
+/** True when `code` is all digits, a GTIN length, and its mod-10 check digit holds. */
+export declare function isValidGtin(code: string): boolean;
+/** The 14-digit form of a valid GTIN: UPC-A, EAN-13 and EAN-8 left-padded with zeros. */
+export declare function normalizeGtin(code: string): string;

package/build/shared/scan-code/gtin.js

@@ -0,0 +1,25 @@
+"use strict";
+// GTIN (UPC-A, EAN-13, EAN-8, GTIN-14) check digits and normalization.
+// Pure; shared by the server parser and the dashboard's scan capture.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GTIN_CODE_LENGTHS = void 0;
+exports.isValidGtin = isValidGtin;
+exports.normalizeGtin = normalizeGtin;
+exports.GTIN_CODE_LENGTHS = [8, 12, 13, 14];
+/** True when `code` is all digits, a GTIN length, and its mod-10 check digit holds. */
+function isValidGtin(code) {
+    if (!/^[0-9]+$/.test(code) || !exports.GTIN_CODE_LENGTHS.includes(code.length))
+        return false;
+    const digits = code.split('').map(Number);
+    const check = digits.pop();
+    let sum = 0;
+    // Weights run 3,1,3,1… from the digit nearest the check digit.
+    for (let i = digits.length - 1, w = 3; i >= 0; i--, w = w === 3 ? 1 : 3) {
+        sum += digits[i] * w;
+    }
+    return (10 - (sum % 10)) % 10 === check;
+}
+/** The 14-digit form of a valid GTIN: UPC-A, EAN-13 and EAN-8 left-padded with zeros. */
+function normalizeGtin(code) {
+    return code.padStart(14, '0');
+}

package/build/shared/scan-code/index.d.ts

@@ -0,0 +1,2 @@
+export { parseScanCode, fixedCodeLengths, type ParseableScheme, type ParsedCode, type ScanParseFailure, type ScanParseResult, } from './parse';
+export { isValidGtin, normalizeGtin, GTIN_CODE_LENGTHS } from './gtin';

package/build/shared/scan-code/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GTIN_CODE_LENGTHS = exports.normalizeGtin = exports.isValidGtin = exports.fixedCodeLengths = exports.parseScanCode = void 0;
+var parse_1 = require("./parse");
+Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
+Object.defineProperty(exports, "fixedCodeLengths", { enumerable: true, get: function () { return parse_1.fixedCodeLengths; } });
+var gtin_1 = require("./gtin");
+Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return gtin_1.isValidGtin; } });
+Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return gtin_1.normalizeGtin; } });
+Object.defineProperty(exports, "GTIN_CODE_LENGTHS", { enumerable: true, get: function () { return gtin_1.GTIN_CODE_LENGTHS; } });

package/build/shared/scan-code/parse.d.ts

@@ -0,0 +1,46 @@
+/** The scheme fields parsing reads. The server's ScanScheme satisfies it. */
+export interface ParseableScheme {
+    version: number;
+    name: string;
+    encoding: 'fixed' | 'delimited' | 'gtin';
+    delimiter: string;
+    target_length: number | null;
+    enabled: boolean;
+}
+export interface ParsedCode {
+    version: number;
+    category: string;
+    target: string;
+    /** The code as scanned, when the target was normalized from it (GTIN). */
+    raw?: string;
+}
+export interface ScanParseFailure {
+    /** Why the code did not parse. */
+    reason: 'empty' | 'unknown_version' | 'scheme_disabled' | 'malformed';
+    detail: string;
+}
+export type ScanParseResult<S extends ParseableScheme = ParseableScheme> = {
+    ok: true;
+    parsed: ParsedCode;
+    scheme: S;
+} | {
+    ok: false;
+    failure: ScanParseFailure;
+};
+/**
+ * Parse a raw scan string against the configured schemes.
+ *
+ * The leading TWO digits pick the scheme (10-99, so a code never starts with a
+ * leading zero); the scheme then defines how the remainder splits into a
+ * single-digit category (0-9) and the target:
+ * - delimited: `10:1:ABC-123` (delimiter from the scheme row)
+ * - fixed:     `1017554332` (one category digit, then target_length digits)
+ *
+ * A digits-only code that no fixed scheme reads is a manufacturer barcode
+ * when a gtin scheme is configured and its check digit holds: the target is
+ * the 14-digit GTIN and the category is '0'. Config validation keeps fixed
+ * and gtin lengths apart, so the order here never decides a real code.
+ */
+export declare function parseScanCode<S extends ParseableScheme>(raw: string, schemes: S[]): ScanParseResult<S>;
+/** The total code lengths a fixed scheme accepts (with and without the check-digit slack). */
+export declare function fixedCodeLengths(scheme: Pick<ParseableScheme, 'target_length'>): number[];