@hotmeshio/long-tail 0.22.0 → 0.22.2

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/services/workflow-state.d.ts

@@ -0,0 +1,21 @@
+import { WORKFLOW_STATES, isTerminated, workflowStateFromStatus, type WorkflowState } from '../shared/workflow-state';
+export { WORKFLOW_STATES, isTerminated, workflowStateFromStatus, type WorkflowState };
+export interface WorkflowStateReading {
+    /** HotMesh job status: above 0 running, 0 closed, below 0 terminated. */
+    status: number;
+    state: WorkflowState;
+    terminated: boolean;
+    /** The failure message, when the run closed with an error. */
+    error?: string;
+}
+interface StatusHandle {
+    status(): Promise<number>;
+    state(metadata?: boolean): Promise<Record<string, any> | undefined>;
+}
+/**
+ * A workflow's state from its handle. A running run needs only the status.
+ * A closed run can still have failed, so its outcome is read for `$error`.
+ * A terminated run keeps `$error` when HotMesh still holds it; a failed read
+ * of a terminated run carries no reason and is dropped.
+ */
+export declare function readWorkflowState(handle: StatusHandle): Promise<WorkflowStateReading>;

package/build/services/workflow-state.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowStateFromStatus = exports.isTerminated = exports.WORKFLOW_STATES = void 0;
+exports.readWorkflowState = readWorkflowState;
+const workflow_state_1 = require("../shared/workflow-state");
+Object.defineProperty(exports, "WORKFLOW_STATES", { enumerable: true, get: function () { return workflow_state_1.WORKFLOW_STATES; } });
+Object.defineProperty(exports, "isTerminated", { enumerable: true, get: function () { return workflow_state_1.isTerminated; } });
+Object.defineProperty(exports, "workflowStateFromStatus", { enumerable: true, get: function () { return workflow_state_1.workflowStateFromStatus; } });
+function errorMessage(error) {
+    if (error && typeof error === 'object' && 'message' in error)
+        return String(error.message);
+    return typeof error === 'string' ? error : JSON.stringify(error);
+}
+/**
+ * A workflow's state from its handle. A running run needs only the status.
+ * A closed run can still have failed, so its outcome is read for `$error`.
+ * A terminated run keeps `$error` when HotMesh still holds it; a failed read
+ * of a terminated run carries no reason and is dropped.
+ */
+async function readWorkflowState(handle) {
+    const status = await handle.status();
+    if (status > 0)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.RUNNING, terminated: false };
+    const terminated = (0, workflow_state_1.isTerminated)(status);
+    let failure;
+    try {
+        failure = (await handle.state())?.$error;
+    }
+    catch (err) {
+        if (!terminated)
+            failure = err;
+    }
+    const error = failure === undefined || failure === null ? undefined : errorMessage(failure);
+    if (terminated)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.FAILED, terminated, ...(error ? { error } : {}) };
+    if (error)
+        return { status, state: workflow_state_1.WORKFLOW_STATES.FAILED, terminated, error };
+    return { status, state: workflow_state_1.WORKFLOW_STATES.COMPLETED, terminated };
+}

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[];

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

@@ -0,0 +1,133 @@
+"use strict";
+// Scan-code parsing. Pure and isomorphic: the server parses every scan with
+// it, and the dashboard parses locally to route a scan into an open form.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseScanCode = parseScanCode;
+exports.fixedCodeLengths = fixedCodeLengths;
+const gtin_1 = require("./gtin");
+const GTIN_CATEGORY = '0';
+/**
+ * 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.
+ */
+function parseScanCode(raw, schemes) {
+    const code = raw.trim();
+    if (!code) {
+        return { ok: false, failure: { reason: 'empty', detail: 'empty scan code' } };
+    }
+    if (/^[0-9]+$/.test(code)) {
+        const fixed = schemes.find((s) => s.encoding === 'fixed' && s.version === Number(code.slice(0, 2)));
+        const fixedFits = fixed?.enabled && fitsFixed(code, fixed);
+        if (!fixedFits) {
+            const gtin = parseGtin(code, schemes);
+            if (gtin)
+                return gtin;
+        }
+    }
+    const versionToken = code.slice(0, 2);
+    const version = Number(versionToken);
+    if (!/^[0-9]{2}$/.test(versionToken) || version < 10 || version > 99) {
+        return {
+            ok: false,
+            failure: { reason: 'unknown_version', detail: `code must start with a two-digit scheme 10-99, got "${versionToken}"` },
+        };
+    }
+    const scheme = schemes.find((s) => s.version === version);
+    if (!scheme) {
+        return {
+            ok: false,
+            failure: { reason: 'unknown_version', detail: `no scan scheme configured for version ${version}` },
+        };
+    }
+    if (!scheme.enabled) {
+        return {
+            ok: false,
+            failure: { reason: 'scheme_disabled', detail: `scan scheme ${version} ("${scheme.name}") is disabled` },
+        };
+    }
+    if (scheme.encoding === 'gtin') {
+        return malformed(scheme, 'reads manufacturer barcodes, which carry no scheme prefix');
+    }
+    if (scheme.encoding === 'delimited') {
+        return parseDelimited(code, version, scheme);
+    }
+    return parseFixed(code, version, scheme);
+}
+function fitsFixed(code, scheme) {
+    const expected = 3 + (scheme.target_length ?? 0);
+    return code.length === expected || code.length === expected + 1;
+}
+/** A manufacturer barcode, or null when the code is not one any gtin scheme reads. */
+function parseGtin(code, schemes) {
+    if (!(0, gtin_1.isValidGtin)(code))
+        return null;
+    const gtin = schemes.find((s) => s.encoding === 'gtin' && s.enabled)
+        ?? schemes.find((s) => s.encoding === 'gtin');
+    if (!gtin)
+        return null;
+    if (!gtin.enabled) {
+        return {
+            ok: false,
+            failure: { reason: 'scheme_disabled', detail: `scan scheme ${gtin.version} ("${gtin.name}") is disabled` },
+        };
+    }
+    return {
+        ok: true,
+        parsed: { version: gtin.version, category: GTIN_CATEGORY, target: (0, gtin_1.normalizeGtin)(code), raw: code },
+        scheme: gtin,
+    };
+}
+function parseDelimited(code, version, scheme) {
+    const d = scheme.delimiter;
+    // version(2 digits) <d> category(1 digit) <d> target(rest, non-empty)
+    if (code[2] !== d) {
+        return malformed(scheme, `expected "${d}" after the two-digit scheme`);
+    }
+    const category = code.slice(3, 4);
+    if (!/^[0-9]$/.test(category)) {
+        return malformed(scheme, 'category must be a single digit');
+    }
+    if (code[4] !== d) {
+        return malformed(scheme, `expected "${d}" after the category`);
+    }
+    const target = code.slice(5);
+    if (!target) {
+        return malformed(scheme, 'target is empty');
+    }
+    return { ok: true, parsed: { version, category, target }, scheme };
+}
+function parseFixed(code, version, scheme) {
+    const targetLength = scheme.target_length ?? 0;
+    const expected = 2 + 1 + targetLength;
+    // UPC-A wedges deliver the trailing check digit too; accept it as slack.
+    if (!/^[0-9]+$/.test(code)) {
+        return malformed(scheme, 'fixed encoding accepts digits only');
+    }
+    if (code.length !== expected && code.length !== expected + 1) {
+        return malformed(scheme, `expected ${expected} digits (or ${expected + 1} with check digit), got ${code.length}`);
+    }
+    const category = code.slice(2, 3);
+    const target = code.slice(3, 3 + targetLength);
+    return { ok: true, parsed: { version, category, target }, scheme };
+}
+function malformed(scheme, detail) {
+    return {
+        ok: false,
+        failure: { reason: 'malformed', detail: `scheme ${scheme.version} ("${scheme.name}"): ${detail}` },
+    };
+}
+/** The total code lengths a fixed scheme accepts (with and without the check-digit slack). */
+function fixedCodeLengths(scheme) {
+    const expected = 3 + (scheme.target_length ?? 0);
+    return [expected, expected + 1];
+}

package/build/shared/workflow-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A workflow's lifecycle state, read from HotMesh's job status: above 0 the
+ * job is running, 0 it has closed, below 0 it was terminated (an interrupt
+ * lowers the status far below 0). A terminated run is failed. A run that
+ * closed at 0 can still have failed; `readWorkflowState` on the server tells
+ * the two apart from the job's outcome.
+ */
+export declare const WORKFLOW_STATES: {
+    readonly RUNNING: "running";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+};
+export type WorkflowState = (typeof WORKFLOW_STATES)[keyof typeof WORKFLOW_STATES];
+/** The state a job status implies, before any outcome is read. */
+export declare function workflowStateFromStatus(status: number): WorkflowState;
+/** Whether a job status means the run was terminated. */
+export declare function isTerminated(status: number): boolean;

package/build/shared/workflow-state.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_STATES = void 0;
+exports.workflowStateFromStatus = workflowStateFromStatus;
+exports.isTerminated = isTerminated;
+/**
+ * A workflow's lifecycle state, read from HotMesh's job status: above 0 the
+ * job is running, 0 it has closed, below 0 it was terminated (an interrupt
+ * lowers the status far below 0). A terminated run is failed. A run that
+ * closed at 0 can still have failed; `readWorkflowState` on the server tells
+ * the two apart from the job's outcome.
+ */
+exports.WORKFLOW_STATES = {
+    RUNNING: 'running',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+};
+/** The state a job status implies, before any outcome is read. */
+function workflowStateFromStatus(status) {
+    if (status > 0)
+        return exports.WORKFLOW_STATES.RUNNING;
+    if (status === 0)
+        return exports.WORKFLOW_STATES.COMPLETED;
+    return exports.WORKFLOW_STATES.FAILED;
+}
+/** Whether a job status means the run was terminated. */
+function isTerminated(status) {
+    return status < 0;
+}