@bsv/dpp-profiles 0.3.0-beta.1

package/dist/gs1-epc-binary.js

@@ -0,0 +1,252 @@
+/**
+ * EPC binary strings, decoded for the one scope the discovery profile
+ * declares (`spec/gs1-discovery.md` §3): a serialised trade item under the
+ * GS1 EPC Tag Data Standard's SGTIN-96 and SGTIN-198 schemes. A compressed GS1
+ * Digital Link URI whose compression string begins `eh` or `ex` carries such a
+ * string (GS1 Digital Link URI: Compression Technical Standard for EPC binary
+ * strings, release 1.0.0, July 2025, §4.1 and §4.2), and a GS1-Conformant
+ * Resolver must decompress it (GS1-Conformant Resolver 1.2.1 §2.3).
+ *
+ * Everything here is arithmetic over a bit string: the two alphabets of §4.1
+ * and §4.2, the SGTIN partition table of the Tag Data Standard, the 38-bit
+ * integer serial of SGTIN-96 and the twenty seven-bit characters of SGTIN-198.
+ * Nothing is guessed: a header this module does not implement, a company
+ * prefix or item reference outside its partition's digit count, a serial with
+ * a character the GS1 encodable set 82 does not contain, or a string of the
+ * wrong length is refused by name. A decoding establishes what the bits say
+ * and no more; it is not evidence that the GTIN was allocated to anyone.
+ */
+import { gs1CheckDigit } from './identifiers.js';
+/** The EPC header of the SGTIN-96 scheme (Tag Data Standard). */
+export const SGTIN_96_HEADER = 0x30;
+/** The EPC header of the SGTIN-198 scheme (Tag Data Standard). */
+export const SGTIN_198_HEADER = 0x36;
+/** The file-safe, URI-safe base 64 alphabet of the compression standard §4.1 (RFC 4648 §5). */
+export const URI_SAFE_BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/**
+ * The SGTIN partition table of the Tag Data Standard: for each partition
+ * value, the bits and digits of the GS1 Company Prefix and of the item
+ * reference (indicator digit included). The two digit counts always sum to
+ * thirteen, so the GTIN-14 is the indicator digit, the company prefix, the
+ * rest of the item reference and a check digit.
+ */
+export const SGTIN_PARTITIONS = [
+    { companyPrefixBits: 40, companyPrefixDigits: 12, itemReferenceBits: 4, itemReferenceDigits: 1 },
+    { companyPrefixBits: 37, companyPrefixDigits: 11, itemReferenceBits: 7, itemReferenceDigits: 2 },
+    { companyPrefixBits: 34, companyPrefixDigits: 10, itemReferenceBits: 10, itemReferenceDigits: 3 },
+    { companyPrefixBits: 30, companyPrefixDigits: 9, itemReferenceBits: 14, itemReferenceDigits: 4 },
+    { companyPrefixBits: 27, companyPrefixDigits: 8, itemReferenceBits: 17, itemReferenceDigits: 5 },
+    { companyPrefixBits: 24, companyPrefixDigits: 7, itemReferenceBits: 20, itemReferenceDigits: 6 },
+    { companyPrefixBits: 20, companyPrefixDigits: 6, itemReferenceBits: 24, itemReferenceDigits: 7 },
+];
+/** The GS1 AI encodable character set 82, which the SGTIN-198 serial and every Digital Link qualifier value draw from. */
+export const GS1_CHARACTER_SET_82 = /^[!"%&'()*+,\-./0-9:;<=>?A-Z_a-z]+$/;
+const refuse = (reason, detail, header) => ({ ok: false, reason, detail, ...(header == null ? {} : { header }) });
+/** A string of `0` and `1` from lower-case hexadecimal, four bits per character (compression standard §4.2.1). */
+export function bitsFromHex(hex) {
+    if (hex.length === 0 || !/^[0-9a-f]+$/.test(hex))
+        return undefined;
+    let bits = '';
+    for (const character of hex)
+        bits += parseInt(character, 16).toString(2).padStart(4, '0');
+    return bits;
+}
+/** A string of `0` and `1` from the URI-safe base 64 alphabet, six bits per character (compression standard §4.1). */
+export function bitsFromUriSafeBase64(text) {
+    if (text.length === 0)
+        return undefined;
+    let bits = '';
+    for (const character of text) {
+        const index = URI_SAFE_BASE64_ALPHABET.indexOf(character);
+        if (index === -1)
+            return undefined;
+        bits += index.toString(2).padStart(6, '0');
+    }
+    return bits;
+}
+function integerOf(bits) {
+    let value = 0n;
+    for (const bit of bits)
+        value = (value << 1n) | (bit === '1' ? 1n : 0n);
+    return value;
+}
+/**
+ * The serial of an SGTIN-198: twenty seven-bit characters, the string ending
+ * at the first all-zero character, everything after it required to be zero
+ * padding. The Tag Data Standard draws the characters from the encodable set
+ * 82; a character outside it, or an empty serial, is refused.
+ */
+function decodeSerial198(bits) {
+    let serial = '';
+    let ended = false;
+    for (let index = 0; index < 20; index++) {
+        const code = Number(integerOf(bits.slice(index * 7, index * 7 + 7)));
+        if (code === 0) {
+            ended = true;
+            continue;
+        }
+        if (ended)
+            return { error: 'a character follows the serial terminator' };
+        const character = String.fromCharCode(code);
+        if (!GS1_CHARACTER_SET_82.test(character))
+            return { error: `character code ${code} is outside the GS1 encodable set 82` };
+        serial += character;
+    }
+    if (serial.length === 0)
+        return { error: 'the serial is empty' };
+    return { serial };
+}
+/** The Tag Data Standard's percent-escaping of the pure-identity URI's serial component. */
+function escapeSerialForUri(serial) {
+    return serial.replace(/[%"&/<>?#]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+}
+/**
+ * Decode an EPC binary string, given as bits, under the SGTIN-96 and SGTIN-198
+ * schemes. The bit count must be exactly the scheme's length; a hexadecimal
+ * encoding of a 198-bit string carries two padding bits, which must be zero.
+ */
+export function decodeEpcBinaryBits(bits) {
+    if (bits.length < 8)
+        return refuse('length', `${bits.length} bits cannot carry an EPC header`);
+    const header = Number(integerOf(bits.slice(0, 8)));
+    const headerHex = header.toString(16).padStart(2, '0');
+    let scheme;
+    let serialBits;
+    if (header === SGTIN_96_HEADER) {
+        scheme = 'sgtin-96';
+        serialBits = 38;
+        if (bits.length !== 96)
+            return refuse('length', `SGTIN-96 is 96 bits; ${bits.length} were given`, headerHex);
+    }
+    else if (header === SGTIN_198_HEADER) {
+        scheme = 'sgtin-198';
+        serialBits = 140;
+        if (bits.length === 200) {
+            if (bits.slice(198) !== '00')
+                return refuse('length', 'the two padding bits after an SGTIN-198 must be zero', headerHex);
+            bits = bits.slice(0, 198);
+        }
+        else if (bits.length !== 198) {
+            return refuse('length', `SGTIN-198 is 198 bits (200 in hexadecimal with zero padding); ${bits.length} were given`, headerHex);
+        }
+    }
+    else {
+        return refuse('unsupported-epc-scheme', `EPC header ${headerHex} is not SGTIN-96 (30) or SGTIN-198 (36); only serialised trade items are decoded`, headerHex);
+    }
+    const filter = Number(integerOf(bits.slice(8, 11)));
+    const partition = Number(integerOf(bits.slice(11, 14)));
+    const layout = SGTIN_PARTITIONS[partition];
+    if (layout == null)
+        return refuse('partition', `partition value ${partition} is not defined for SGTIN`, headerHex);
+    let at = 14;
+    const companyPrefixValue = integerOf(bits.slice(at, at + layout.companyPrefixBits));
+    at += layout.companyPrefixBits;
+    const itemReferenceValue = integerOf(bits.slice(at, at + layout.itemReferenceBits));
+    at += layout.itemReferenceBits;
+    if (companyPrefixValue >= 10n ** BigInt(layout.companyPrefixDigits))
+        return refuse('company-prefix', `the company prefix exceeds ${layout.companyPrefixDigits} digits`, headerHex);
+    if (itemReferenceValue >= 10n ** BigInt(layout.itemReferenceDigits))
+        return refuse('item-reference', `the item reference exceeds ${layout.itemReferenceDigits} digits`, headerHex);
+    const companyPrefix = companyPrefixValue.toString().padStart(layout.companyPrefixDigits, '0');
+    const itemReference = itemReferenceValue.toString().padStart(layout.itemReferenceDigits, '0');
+    let serial;
+    const serialField = bits.slice(at, at + serialBits);
+    if (scheme === 'sgtin-96') {
+        serial = integerOf(serialField).toString();
+    }
+    else {
+        const decoded = decodeSerial198(serialField);
+        if ('error' in decoded)
+            return refuse('serial', decoded.error, headerHex);
+        serial = decoded.serial;
+    }
+    const thirteen = `${itemReference[0]}${companyPrefix}${itemReference.slice(1)}`;
+    const gtin = `${thirteen}${gs1CheckDigit(thirteen)}`;
+    return {
+        ok: true,
+        scheme,
+        header,
+        filter,
+        partition,
+        companyPrefix,
+        itemReference,
+        gtin,
+        serial,
+        epcUri: `urn:epc:id:sgtin:${companyPrefix}.${itemReference}.${escapeSerialForUri(serial)}`,
+    };
+}
+/**
+ * Decode the compression string of a special compressed GS1 Digital Link URI:
+ * the two characters after the slash select the alphabet (`eh` hexadecimal,
+ * `ex` URI-safe base 64) and the rest is the EPC binary string.
+ */
+export function decodeEpcCompressionString(compressionString) {
+    if (compressionString.startsWith('eh')) {
+        const payload = compressionString.slice(2);
+        if (payload.length === 0)
+            return refuse('empty', 'nothing follows the eh prefix');
+        const bits = bitsFromHex(payload);
+        if (bits == null)
+            return refuse('not-hex', 'the characters after eh are not lower-case hexadecimal');
+        return decodeEpcBinaryBits(bits);
+    }
+    if (compressionString.startsWith('ex')) {
+        const payload = compressionString.slice(2);
+        if (payload.length === 0)
+            return refuse('empty', 'nothing follows the ex prefix');
+        const bits = bitsFromUriSafeBase64(payload);
+        if (bits == null)
+            return refuse('not-uri-safe-base64', 'the characters after ex are not from the URI-safe base 64 alphabet');
+        return decodeEpcBinaryBits(bits);
+    }
+    return refuse('unsupported-epc-scheme', 'the compression string begins with neither eh nor ex; the general GS1 Digital Link compression is not decoded here');
+}
+/**
+ * The inverse, for tests and for a writer that prints a compressed carrier:
+ * an SGTIN-96 or SGTIN-198 EPC binary string as bits, from its parts. Refuses
+ * a serial the scheme cannot carry rather than truncating it.
+ */
+export function encodeSgtinBits(input) {
+    const layout = SGTIN_PARTITIONS[input.partition];
+    if (layout == null)
+        throw new Error('partition value must be 0 to 6');
+    if (!/^\d+$/.test(input.companyPrefix) || input.companyPrefix.length !== layout.companyPrefixDigits)
+        throw new Error(`a partition ${input.partition} company prefix has ${layout.companyPrefixDigits} digits`);
+    if (!/^\d+$/.test(input.itemReference) || input.itemReference.length !== layout.itemReferenceDigits)
+        throw new Error(`a partition ${input.partition} item reference has ${layout.itemReferenceDigits} digits`);
+    if (!Number.isInteger(input.filter) || input.filter < 0 || input.filter > 7)
+        throw new Error('the filter value is three bits');
+    const field = (value, width) => value.toString(2).padStart(width, '0');
+    let bits = field(BigInt(input.scheme === 'sgtin-96' ? SGTIN_96_HEADER : SGTIN_198_HEADER), 8) + field(BigInt(input.filter), 3) + field(BigInt(input.partition), 3);
+    bits += field(BigInt(input.companyPrefix), layout.companyPrefixBits) + field(BigInt(input.itemReference), layout.itemReferenceBits);
+    if (input.scheme === 'sgtin-96') {
+        if (!/^(0|[1-9]\d*)$/.test(input.serial) || BigInt(input.serial) >= 2n ** 38n)
+            throw new Error('an SGTIN-96 serial is an integer below 2^38 without leading zeros');
+        bits += field(BigInt(input.serial), 38);
+    }
+    else {
+        if (input.serial.length === 0 || input.serial.length > 20 || !GS1_CHARACTER_SET_82.test(input.serial))
+            throw new Error('an SGTIN-198 serial is 1 to 20 characters of the GS1 encodable set 82');
+        for (const character of input.serial)
+            bits += field(BigInt(character.charCodeAt(0)), 7);
+        bits = bits.padEnd(198, '0');
+    }
+    return bits;
+}
+/** Bits to the `eh` form: lower-case hexadecimal, zero-padded to a multiple of four bits. */
+export function hexFromBits(bits) {
+    const padded = bits.padEnd(Math.ceil(bits.length / 4) * 4, '0');
+    let hex = '';
+    for (let at = 0; at < padded.length; at += 4)
+        hex += parseInt(padded.slice(at, at + 4), 2).toString(16);
+    return hex;
+}
+/** Bits to the `ex` form: the URI-safe base 64 alphabet, zero-padded to a multiple of six bits. */
+export function uriSafeBase64FromBits(bits) {
+    const padded = bits.padEnd(Math.ceil(bits.length / 6) * 6, '0');
+    let text = '';
+    for (let at = 0; at < padded.length; at += 6)
+        text += URI_SAFE_BASE64_ALPHABET[parseInt(padded.slice(at, at + 6), 2)];
+    return text;
+}
+//# sourceMappingURL=gs1-epc-binary.js.map

package/dist/gs1-epc-binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gs1-epc-binary.js","sourceRoot":"","sources":["../src/gs1-epc-binary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAA;AACnC,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA;AAEpC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,wBAAwB,GAAG,kEAAkE,CAAA;AAE1G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsI;IACjK,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE;IAChG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE;IAChG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;IACjG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;IAChG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;IAChG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;IAChG,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;CACjG,CAAA;AAED,0HAA0H;AAC1H,MAAM,CAAC,MAAM,oBAAoB,GAAG,qCAAqC,CAAA;AAyCzE,MAAM,MAAM,GAAG,CAAC,MAAkC,EAAE,MAAc,EAAE,MAAe,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;AAEhL,kHAAkH;AAClH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAClE,IAAI,IAAI,GAAG,EAAE,CAAA;IACb,KAAK,MAAM,SAAS,IAAI,GAAG;QAAE,IAAI,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACzF,OAAO,IAAI,CAAA;AACb,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACvC,IAAI,IAAI,GAAG,EAAE,CAAA;IACb,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QACzD,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAA;QAClC,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC5C,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,KAAK,GAAG,EAAE,CAAA;IACd,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACvE,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,IAAY;IACnC,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,IAAI,KAAK,GAAG,KAAK,CAAA;IACjB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YACf,KAAK,GAAG,IAAI,CAAA;YACZ,SAAQ;QACV,CAAC;QACD,IAAI,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAA;QACxE,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,IAAI,sCAAsC,EAAE,CAAA;QACzH,MAAM,IAAI,SAAS,CAAA;IACrB,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAA;IAChE,OAAO,EAAE,MAAM,EAAE,CAAA;AACnB,CAAC;AAED,4FAA4F;AAC5F,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;AAChI,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,MAAM,kCAAkC,CAAC,CAAA;IAC9F,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACtD,IAAI,MAA+B,CAAA;IACnC,IAAI,UAAkB,CAAA;IACtB,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QAC/B,MAAM,GAAG,UAAU,CAAA;QACnB,UAAU,GAAG,EAAE,CAAA;QACf,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,MAAM,CAAC,QAAQ,EAAE,wBAAwB,IAAI,CAAC,MAAM,aAAa,EAAE,SAAS,CAAC,CAAA;IAC9G,CAAC;SAAM,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QACvC,MAAM,GAAG,WAAW,CAAA;QACpB,UAAU,GAAG,GAAG,CAAA;QAChB,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC,QAAQ,EAAE,sDAAsD,EAAE,SAAS,CAAC,CAAA;YACxH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QAC3B,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC/B,OAAO,MAAM,CAAC,QAAQ,EAAE,iEAAiE,IAAI,CAAC,MAAM,aAAa,EAAE,SAAS,CAAC,CAAA;QAC/H,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,MAAM,CAAC,wBAAwB,EAAE,cAAc,SAAS,kFAAkF,EAAE,SAAS,CAAC,CAAA;IAC/J,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IACnD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IACvD,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAA;IAC1C,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,WAAW,EAAE,mBAAmB,SAAS,2BAA2B,EAAE,SAAS,CAAC,CAAA;IAClH,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,MAAM,kBAAkB,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAA;IACnF,EAAE,IAAI,MAAM,CAAC,iBAAiB,CAAA;IAC9B,MAAM,kBAAkB,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAA;IACnF,EAAE,IAAI,MAAM,CAAC,iBAAiB,CAAA;IAC9B,IAAI,kBAAkB,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC;QAAE,OAAO,MAAM,CAAC,gBAAgB,EAAE,8BAA8B,MAAM,CAAC,mBAAmB,SAAS,EAAE,SAAS,CAAC,CAAA;IAClL,IAAI,kBAAkB,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC;QAAE,OAAO,MAAM,CAAC,gBAAgB,EAAE,8BAA8B,MAAM,CAAC,mBAAmB,SAAS,EAAE,SAAS,CAAC,CAAA;IAClL,MAAM,aAAa,GAAG,kBAAkB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAA;IAC7F,MAAM,aAAa,GAAG,kBAAkB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAA;IAC7F,IAAI,MAAc,CAAA;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,UAAU,CAAC,CAAA;IACnD,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAA;IAC5C,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,eAAe,CAAC,WAAW,CAAC,CAAA;QAC5C,IAAI,OAAO,IAAI,OAAO;YAAE,OAAO,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QACzE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IACzB,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;IAC/E,MAAM,IAAI,GAAG,GAAG,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAA;IACpD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM;QACN,MAAM;QACN,MAAM;QACN,SAAS;QACT,aAAa;QACb,aAAa;QACb,IAAI;QACJ,MAAM;QACN,MAAM,EAAE,oBAAoB,aAAa,IAAI,aAAa,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE;KAC3F,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAyB;IAClE,IAAI,iBAAiB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAA;QACjF,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;QACjC,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,MAAM,CAAC,SAAS,EAAE,wDAAwD,CAAC,CAAA;QACpG,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAA;IAClC,CAAC;IACD,IAAI,iBAAiB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAA;QACjF,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;QAC3C,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,MAAM,CAAC,qBAAqB,EAAE,oEAAoE,CAAC,CAAA;QAC5H,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,wBAAwB,EAAE,oHAAoH,CAAC,CAAA;AAC/J,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAA4I;IAC1K,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAChD,IAAI,MAAM,IAAI,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IACrE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,MAAM,CAAC,mBAAmB;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,KAAK,CAAC,SAAS,uBAAuB,MAAM,CAAC,mBAAmB,SAAS,CAAC,CAAA;IAC9M,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,MAAM,CAAC,mBAAmB;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,KAAK,CAAC,SAAS,uBAAuB,MAAM,CAAC,mBAAmB,SAAS,CAAC,CAAA;IAC9M,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IAC9H,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC9F,IAAI,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAA;IAClK,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAA;IACnI,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAA;QACnK,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;IACzC,CAAC;SAAM,CAAC;QACN,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAA;QAC/L,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,MAAM;YAAE,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACvF,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAC/D,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC;QAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACvG,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAC/D,IAAI,IAAI,GAAG,EAAE,CAAA;IACb,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC;QAAE,IAAI,IAAI,wBAAwB,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACrH,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/gs1-resolution.d.ts

@@ -0,0 +1,392 @@
+import { type EpcBinaryRefusalReason, type SgtinDecoding } from './gs1-epc-binary.js';
+/**
+ * The GS1 Web vocabulary namespace the resolver standard expands `gs1:` to
+ * (GS1-Conformant Resolver 1.2.1 §2.14). The published linkset context maps
+ * the same prefix to `http://gs1.org/voc/`; `normaliseLinkType` treats the
+ * three spellings as one so a linkset from another resolver is read
+ * correctly and this module always writes the standard's own.
+ */
+export declare const GS1_VOCABULARY = "https://ref.gs1.org/voc/";
+/** The GS1 link types this profile uses, as full IRIs; a linkset key is always the full IRI. */
+export declare const GS1_LINK_TYPES: {
+    readonly defaultLink: "https://ref.gs1.org/voc/defaultLink";
+    readonly defaultLinkMulti: "https://ref.gs1.org/voc/defaultLinkMulti";
+    readonly pip: "https://ref.gs1.org/voc/pip";
+    readonly sustainabilityInfo: "https://ref.gs1.org/voc/sustainabilityInfo";
+    readonly certificationInfo: "https://ref.gs1.org/voc/certificationInfo";
+    readonly epcis: "https://ref.gs1.org/voc/epcis";
+    readonly traceability: "https://ref.gs1.org/voc/traceability";
+    readonly recallStatus: "https://ref.gs1.org/voc/recallStatus";
+    readonly handledBy: "https://ref.gs1.org/voc/handledBy";
+};
+/**
+ * The namespace of the link types this standard owns, and the one relation it
+ * defines: a link to a passport's portable evidence package
+ * (`spec/portable-evidence.md`), for which the GS1 vocabulary has no term.
+ * The pinned linkset schema admits a link relation key only as a bare
+ * lower-case token or as an `http(s)` IRI of letters, digits, dots and
+ * slashes, so the relation is spelled without a hyphen under the programme's
+ * public host and versioned in its path; the standard's usual
+ * `bsv-blockchain.github.io` base cannot be a link relation under that schema.
+ */
+export declare const DPP_LINK_NAMESPACE = "https://dpp.bsvb.net/link/";
+export declare const DPP_EVIDENCE_PACKAGE_LINK_TYPE = "https://dpp.bsvb.net/link/evidencePackage/1";
+/** The media types and relations of the resolver standard §2.9 and §2.10. */
+export declare const LINKSET_MEDIA_TYPE = "application/linkset+json";
+export declare const LINKSET_CONTEXT_URI = "https://ref.gs1.org/standards/resolver/1.2.1/linkset-context";
+export declare const JSON_LD_CONTEXT_RELATION = "http://www.w3.org/ns/json-ld#context";
+/** The one primary key this profile hosts, and its three key qualifiers in the order the URI syntax fixes. */
+export declare const SUPPORTED_PRIMARY_KEY = "01";
+export declare const GTIN_QUALIFIER_ORDER: readonly ["22", "10", "21"];
+export type GtinQualifierAi = (typeof GTIN_QUALIFIER_ORDER)[number];
+export interface AiValue {
+    ai: string;
+    value: string;
+}
+export interface DataAttribute extends AiValue {
+    /** True when this module knows the AI's format and the value met it; false when the AI is unknown here and only the character set was checked. */
+    validated: boolean;
+}
+export interface LinkTypeRequest {
+    /** The query parameter as written. */
+    raw: string;
+    /** The full IRI, when the value was a full IRI or a `gs1:` CURIE. */
+    iri?: string;
+    /** True for `linkset` (and its common alias `all`): the client wants the list, not a redirect. */
+    linkset?: boolean;
+}
+export interface Gs1Key {
+    ai: '01';
+    /** Fourteen digits. */
+    value: string;
+    qualifiers: AiValue[];
+}
+export interface ParsedUncompressedUri {
+    kind: 'uncompressed';
+    origin: string;
+    host: string;
+    /** The path before `/01`, without a trailing slash; empty for a root resolver. */
+    pathStem: string;
+    primaryKey: {
+        ai: '01';
+        value: string;
+        checkDigitValid: boolean;
+        demonstration: boolean;
+    };
+    /** In the order the syntax fixes: 22, then 10, then 21. */
+    qualifiers: AiValue[];
+    dataAttributes: DataAttribute[];
+    linkType?: LinkTypeRequest;
+    /** Query parameters that are neither AIs nor linkType, preserved for forwarding. */
+    otherQuery: Array<[string, string]>;
+}
+export interface ParsedCompressedUri {
+    kind: 'compressed';
+    origin: string;
+    host: string;
+    pathStem: string;
+    prefix: 'eh' | 'ex';
+    /** The whole compression string, prefix included. */
+    compressionString: string;
+    /** The query string as given, so it can be carried to the uncompressed form. */
+    query: string;
+}
+export type UriRefusalReason = 'not-a-url' | 'scheme' | 'percent-encoding' | 'no-primary-key' | 'unsupported-primary-key' | 'primary-key-not-a-gtin' | 'trailing-segment' | 'qualifier-order' | 'qualifier-repeated' | 'qualifier-unsupported' | 'qualifier-value' | 'key-in-query' | 'attribute-ai' | 'attribute-value';
+export interface InvalidUri {
+    kind: 'invalid';
+    reason: UriRefusalReason;
+    detail: string;
+}
+export type ParsedGs1Uri = ParsedUncompressedUri | ParsedCompressedUri | InvalidUri;
+/**
+ * Read a GS1 Digital Link URI in the grammar this profile hosts: primary key
+ * 01, its key qualifiers 22, 10 and 21 in that order, data attributes in the
+ * query, `linkType` beside them, and the special compressed form of the EPC
+ * binary standard. Refusals are answers, not exceptions, each with the
+ * standard's reason: a resolver turns them into 400 and a client into a
+ * finding. One trailing slash is tolerated (resolver standard §2.13).
+ *
+ * A URI this reads is syntactically a GS1 Digital Link URI and nothing more:
+ * the check digit is reported, not enforced, because a historical record may
+ * carry a GTIN that fails it, and allocation authority is never inferred.
+ */
+export declare function parseGs1DigitalLinkUri(uri: string): ParsedGs1Uri;
+export interface Decompressed {
+    ok: true;
+    /** The fully uncompressed URI under the stem the compressed form carried. */
+    uri: string;
+    key: Gs1Key;
+    epc: SgtinDecoding;
+}
+export type DecompressionResult = Decompressed | {
+    ok: false;
+    reason: 'not-compressed' | EpcBinaryRefusalReason;
+    detail: string;
+    header?: string;
+};
+/**
+ * Turn a special compressed GS1 Digital Link URI into its uncompressed form
+ * (compression standard §4.2.1 and §4.2.2): the stem up to the compression
+ * string is kept, the EPC binary string after `eh` or `ex` is decoded under
+ * the Tag Data Standard, and the result is `${stem}/01/{gtin}/21/{serial}`.
+ * A query string is carried across unchanged. An uncompressed URI is refused
+ * as `not-compressed` rather than echoed, so a caller never mistakes a
+ * pass-through for a decoding.
+ */
+export declare function decompressGs1DigitalLink(uri: string): DecompressionResult;
+/** The key an uncompressed parse names, or one built from its parts with the qualifiers put in canonical order. */
+export declare function gs1KeyOf(source: ParsedUncompressedUri | {
+    gtin: string;
+    qualifiers?: AiValue[];
+}): Gs1Key;
+/**
+ * The canonical spelling of a key tuple, `01:{gtin14}` followed by each
+ * qualifier as `ai:value` in the syntax's order, joined by `|`. Two Digital
+ * Link URIs under different hosts with the same tuple name the same entity;
+ * the same serial under a different GTIN does not. Equivalence is a statement
+ * about identifiers only: it is not authority to bind a signed credential to
+ * a passport, which needs the binding evidence `spec/gs1-discovery.md` §2
+ * names.
+ */
+export declare function gs1KeyTuple(key: Gs1Key | ParsedUncompressedUri): string;
+export declare function sameGs1Key(a: Gs1Key | ParsedUncompressedUri, b: Gs1Key | ParsedUncompressedUri): boolean;
+/** The granularity a key tuple names, by its most specific qualifier. */
+export type KeyGranularity = 'model' | 'variant' | 'lot' | 'item';
+export declare function granularityOf(qualifiers: readonly AiValue[]): KeyGranularity;
+/** The uncompressed Digital Link URI of a key under a resolver root (origin plus optional stem, no trailing slash). */
+export declare function uncompressedUri(resolverRoot: string, key: Gs1Key): string;
+/** The path of the legacy evidence JSON answered at the API origin, and its alias, for an item key; undefined for any other granularity. */
+export declare function legacyEvidencePaths(key: Gs1Key): {
+    legacy: string;
+    alias: string;
+} | undefined;
+export type Disclosure = 'public' | 'restricted';
+export interface ResolutionLink {
+    /** The descriptive link relation type, as a full IRI. */
+    rel: string;
+    href: string;
+    title: string;
+    /** An IANA media type, when declared. */
+    type?: string;
+    /** BCP 47 language tags, when declared. */
+    hreflang?: string[];
+    context?: string[];
+    /** `single`: the entity's one default link (no optional attributes); `multi`: a default refined by request headers. */
+    default?: 'single' | 'multi';
+    /** Whether public discovery may return the link; a restricted link is only ever returned to an authorised audience, and access is enforced again at its target. */
+    disclosure: Disclosure;
+    /** Whether the resolver forwards the request's query string on redirect; the standard's default is to forward everything (§2.12). */
+    forwardQuery?: boolean;
+}
+export interface ResolutionRecord {
+    key: {
+        ai: '01';
+        value: string;
+    };
+    /** The qualifiers this record is registered at, in the syntax's order; a record with 21 carries neither 22 nor 10 (resolver standard §2.5.10). */
+    qualifiers: AiValue[];
+    /** The exact signed passport identifier bound to this entity, where the binding is established; never inferred from the key. */
+    passportId?: string;
+    /** A reference to the evidence or policy establishing that binding. */
+    bindingRef?: string;
+    links: ResolutionLink[];
+    /** The revision of the configuration the record was written under. */
+    configurationRevision: string;
+    description?: string;
+}
+/**
+ * Every rule a record must meet before it is stored, so the resolver validates
+ * at ingestion and not at every request (resolver standard §2.4): a GTIN
+ * whose check digit holds, qualifiers in order with no repeat and no TPX, a
+ * serial never registered beside a variant or a lot, at most one single
+ * default link with no optional attributes, and every link with an `https`
+ * target, a title, a relation the linkset schema can carry, and declared
+ * disclosure. An empty list means the record is admissible.
+ */
+export declare function resolutionRecordProblems(record: ResolutionRecord): string[];
+export interface ResolutionRequest {
+    key: Gs1Key;
+    /** Public discovery never sees a restricted link; an authorised audience sees it flagged. */
+    audience: 'public' | 'authorised';
+    /** The requested link type as a full IRI, `linkset` for the list, or absent for the default. */
+    linkType?: string | 'linkset';
+    /** Acceptable media types, most preferred first (`parseAcceptHeader`). */
+    accept?: string[];
+    /** Preferred languages, most preferred first (`parseAcceptLanguage`). */
+    acceptLanguage?: string[];
+    context?: string[];
+    /** The origin and stem the linkset anchors are written under. */
+    resolverRoot: string;
+}
+export interface ResolvedLink extends ResolutionLink {
+    /** The uncompressed URI of the record the link was registered at, never the request's. */
+    anchor: string;
+    /** The granularity of that record: a model-level link answering an item request is still model information. */
+    granularity: KeyGranularity;
+    record: ResolutionRecord;
+}
+export interface MatchedRecord {
+    record: ResolutionRecord;
+    anchor: string;
+    granularity: KeyGranularity;
+}
+export type ResolutionOutcome = {
+    outcome: 'no-records';
+    matched: [];
+} | {
+    outcome: 'linkset';
+    matched: MatchedRecord[];
+    links: ResolvedLink[];
+} | {
+    outcome: 'redirect';
+    matched: MatchedRecord[];
+    link: ResolvedLink;
+    links: ResolvedLink[];
+} | {
+    outcome: 'multiple-choices';
+    matched: MatchedRecord[];
+    candidates: ResolvedLink[];
+    links: ResolvedLink[];
+} | {
+    outcome: 'not-found';
+    matched: MatchedRecord[];
+    requested: string;
+    links: ResolvedLink[];
+};
+/** `text/html;q=0.9, application/json` to `['application/json', 'text/html']`: q-values honoured, zero excluded. */
+export declare function parseAcceptHeader(header: string | undefined): string[];
+/** `fr-CH, fr;q=0.9, en;q=0.8` to `['fr-CH', 'fr', 'en']`. */
+export declare function parseAcceptLanguage(header: string | undefined): string[];
+/**
+ * The records a request selects: the union the resolver standard §2.5.10
+ * fixes, most specific level first, so a link registered at the lot level is
+ * found under a serialised request and a link at the model level under every
+ * request. Each match keeps its own anchor and granularity.
+ */
+export declare function matchRecords(records: readonly ResolutionRecord[], key: Gs1Key, resolverRoot: string): MatchedRecord[];
+/**
+ * The best match among candidates of one link type (resolver standard §2.6.3,
+ * media type before language before context): the unique best, or every
+ * candidate when the best is not unique, so the resolver answers 300 rather
+ * than choosing.
+ */
+export declare function bestMatch<L extends ResolutionLink>(candidates: readonly L[], request: Pick<ResolutionRequest, 'accept' | 'acceptLanguage' | 'context'>): {
+    unique: L;
+} | {
+    tie: L[];
+} | undefined;
+/**
+ * Resolve a request against the records this resolver holds, exactly as the
+ * standard's flow chart does and without any I/O: which records the key
+ * selects, which links the audience may see, then the default, the requested
+ * type, the list, or the refusal. A restricted link is never returned to a
+ * public audience. The redirect target is the link's own `href`; forwarding
+ * the request's query string onto it (§2.12) is the route's step, because
+ * the query is the route's to read.
+ */
+export declare function resolveLinks(records: readonly ResolutionRecord[], request: ResolutionRequest): ResolutionOutcome;
+export interface LinksetLink {
+    href: string;
+    title: string;
+    type?: string;
+    hreflang?: string[];
+    context?: string[];
+    fwqs?: boolean;
+    public?: boolean;
+}
+/** One link context object of RFC 9264 as the GS1 schema shapes it: the anchor, an optional description and the links keyed by relation. */
+export type LinksetEntry = {
+    anchor: string;
+    description?: string;
+} & Record<string, unknown>;
+export interface LinksetDocument {
+    linkset: LinksetEntry[];
+}
+/** One relation IRI for the three spellings of the GS1 vocabulary; anything else is returned as given. */
+export declare function normaliseLinkType(iri: string): string;
+/**
+ * The linkset a resolver returns for a request (resolver standard §2.9 and
+ * §2.10): one link context object per matched record, most specific first,
+ * its anchor the uncompressed URI of that record's own identifier, every link
+ * under its descriptive relation and a default additionally under
+ * `gs1:defaultLink` or `gs1:defaultLinkMulti`. Links a public audience may
+ * not see are absent, not blanked; a restricted link shown to an authorised
+ * audience says `public: false`. The document validates against the pinned
+ * linkset schema.
+ */
+export declare function linksetDocument(records: readonly ResolutionRecord[], request: Omit<ResolutionRequest, 'linkType'>): LinksetDocument | undefined;
+export interface LinkSelection {
+    rel: string;
+    mediaType?: string;
+    language?: string;
+    context?: string;
+}
+export type SelectedLink = {
+    outcome: 'selected';
+    link: LinksetLink;
+    anchor: string;
+    scope: {
+        key?: Gs1Key;
+        granularity: KeyGranularity | 'unknown';
+    };
+} | {
+    outcome: 'ambiguous';
+    candidates: Array<{
+        link: LinksetLink;
+        anchor: string;
+    }>;
+} | {
+    outcome: 'not-found';
+    available: string[];
+};
+/**
+ * A discovery client's choice over a linkset another resolver returned: the
+ * links under the requested relation (a full IRI or a `gs1:` CURIE) across
+ * every link context object, the best match by media type, language and
+ * context, and the anchor's own scope beside the result, so a link found at
+ * the model level under an item request is handed back as model
+ * information. An anchor that is not a Digital Link URI this module reads
+ * has scope `unknown`; it is not guessed.
+ */
+export declare function selectLink(linkset: LinksetDocument, selection: LinkSelection): SelectedLink;
+export interface ResolverDescriptionConfig {
+    /** The origin, with an optional stem, the resolver answers at; no trailing slash. */
+    resolverRoot: string;
+    name?: string;
+    contact?: {
+        fn?: string;
+        hasAddress?: {
+            streetAddress?: string;
+            locality?: string;
+            region?: string;
+            'postal-code'?: string;
+        };
+        hasTelephone?: string;
+    };
+    supportedContextValuesEnumerated?: string[];
+    extensionProfile?: string;
+}
+export interface ResolverDescription {
+    name?: string;
+    resolverRoot: string;
+    supportedPrimaryKeys: ['01'];
+    supportedLinkType: Array<{
+        namespace: string;
+        prefix: string;
+    }>;
+    linkTypeDefaultCanBeLinkset: false;
+    supportedContextValuesEnumerated?: string[];
+    contact?: ResolverDescriptionConfig['contact'];
+    extensionProfile?: string;
+    jsonLdContextLocation: string;
+}
+/**
+ * The `/.well-known/gs1resolver` document (resolver standard §3) for the one
+ * scope this profile hosts: primary key 01 with every qualifier, the GS1
+ * vocabulary and this standard's own link namespace, `linkset` never the
+ * default, and the pinned GS1 context for JSON linksets. It is published only
+ * by an origin that actually provides the resolver contract; the legacy API
+ * origin does not describe itself as one.
+ */
+export declare function describeResolver(config: ResolverDescriptionConfig): ResolverDescription;
+//# sourceMappingURL=gs1-resolution.d.ts.map