gs1-core 0.1.0

package/dist/interpret.d.ts

@@ -0,0 +1,5 @@
+import { AIDefinition, GS1Date, GS1DateTime, InterpretedValue } from './types.js';
+export declare function resolveYear(yy: number, now?: Date): number;
+export declare function parseDate6(value: string, ai?: string): GS1Date;
+export declare function parseDateTime(value: string, ai?: string): GS1DateTime;
+export declare function interpretValue(ai: string, definition: AIDefinition, value: string): InterpretedValue | undefined;

package/dist/interpret.js

@@ -0,0 +1,107 @@
+import { GS1Error, } from './types.js';
+export function resolveYear(yy, now = new Date()) {
+    // GS1 sliding window: the resolved year is within -49/+50 of the current one
+    const currentYear = now.getFullYear();
+    const currentCentury = currentYear - (currentYear % 100);
+    const diff = yy - (currentYear % 100);
+    if (diff >= 51)
+        return currentCentury - 100 + yy;
+    if (diff <= -50)
+        return currentCentury + 100 + yy;
+    return currentCentury + yy;
+}
+function lastDayOfMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function pad(n, width = 2) {
+    return String(n).padStart(width, '0');
+}
+export function parseDate6(value, ai) {
+    if (!/^\d{6}$/.test(value)) {
+        throw new GS1Error(`date "${value}" must be 6 digits (YYMMDD)`, ai);
+    }
+    const year = resolveYear(Number(value.slice(0, 2)));
+    const month = Number(value.slice(2, 4));
+    let day = Number(value.slice(4, 6));
+    if (month < 1 || month > 12) {
+        throw new GS1Error(`date "${value}" has invalid month ${month}`, ai);
+    }
+    const maxDay = lastDayOfMonth(year, month);
+    if (day === 0)
+        day = maxDay; // DD "00" means end of month
+    if (day > maxDay) {
+        throw new GS1Error(`date "${value}" has invalid day ${day}`, ai);
+    }
+    return { year, month, day, iso: `${year}-${pad(month)}-${pad(day)}` };
+}
+export function parseDateTime(value, ai) {
+    if (!/^\d+$/.test(value) || ![8, 10, 12].includes(value.length)) {
+        if (/^\d{6}$/.test(value))
+            return { ...parseDate6(value, ai), hour: 0 };
+        throw new GS1Error(`date/time "${value}" must be YYMMDDHH[MM[SS]]`, ai);
+    }
+    const date = parseDate6(value.slice(0, 6), ai);
+    const hour = Number(value.slice(6, 8));
+    if (hour > 23) {
+        throw new GS1Error(`date/time "${value}" has invalid hour ${hour}`, ai);
+    }
+    const result = { ...date, hour };
+    result.iso = `${date.iso}T${pad(hour)}`;
+    if (value.length >= 10) {
+        const minute = Number(value.slice(8, 10));
+        if (minute > 59) {
+            throw new GS1Error(`date/time "${value}" has invalid minute ${minute}`, ai);
+        }
+        result.minute = minute;
+        result.iso += `:${pad(minute)}`;
+    }
+    else {
+        result.iso += ':00';
+    }
+    if (value.length === 12) {
+        const second = Number(value.slice(10, 12));
+        if (second > 59) {
+            throw new GS1Error(`date/time "${value}" has invalid second ${second}`, ai);
+        }
+        result.second = second;
+        result.iso += `:${pad(second)}`;
+    }
+    return result;
+}
+export function interpretValue(ai, definition, value) {
+    switch (definition.kind) {
+        case 'date':
+            return parseDate6(value, ai);
+        case 'datetime':
+            return parseDateTime(value, ai);
+        case 'dateRange': {
+            const start = parseDate6(value.slice(0, 6), ai);
+            if (value.length === 6)
+                return { start };
+            return { start, end: parseDate6(value.slice(6, 12), ai) };
+        }
+        case 'count':
+            return Number(value);
+        case 'decimal': {
+            const decimals = decimalPosition(ai, definition);
+            return Number(value) / 10 ** decimals;
+        }
+        case 'currencyDecimal': {
+            const decimals = decimalPosition(ai, definition);
+            return {
+                currency: value.slice(0, 3),
+                amount: Number(value.slice(3)) / 10 ** decimals,
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+function decimalPosition(ai, definition) {
+    // for families like "310n" the 4th digit of the concrete AI is the number
+    // of digits after the implied decimal point
+    if (definition.ai.endsWith('n'))
+        return Number(ai[3]);
+    return 0;
+}
+//# sourceMappingURL=interpret.js.map

package/dist/interpret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpret.js","sourceRoot":"","sources":["../src/interpret.ts"],"names":[],"mappings":"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"}

package/dist/parse.d.ts

@@ -0,0 +1,10 @@
+import { GS1Element } from './types.js';
+import { ValidationOptions } from './element.js';
+export declare const GS = "\u001D";
+export interface ParseRawOptions extends ValidationOptions {
+    fnc1?: string;
+}
+export declare function parseElementString(input: string, options?: ValidationOptions): GS1Element[];
+export declare function parseRawString(input: string, options?: ParseRawOptions): GS1Element[];
+export declare function parse(input: string, options?: ParseRawOptions): GS1Element[];
+export declare function toRecord(elements: GS1Element[]): Record<string, string>;

package/dist/parse.js

@@ -0,0 +1,94 @@
+import { GS1Error } from './types.js';
+import { getAIDefinition } from './ai.js';
+import { createElement } from './element.js';
+// ASCII Group Separator, the standard FNC1 representation in transmitted data
+export const GS = '\x1D';
+// ]C1 = GS1-128, ]e0-]e2 = DataBar, ]d2 = GS1 DataMatrix, ]Q3 = GS1 QR, ]J1 = DotCode
+const SYMBOLOGY_ID = /^\](C1|e0|e1|e2|d2|Q3|J1)/;
+export function parseElementString(input, options = {}) {
+    if (!input.startsWith('(')) {
+        throw new GS1Error(`element string must start with "(", got "${input.slice(0, 8)}..."`);
+    }
+    const elements = [];
+    const aiToken = /\((\d{2,4})\)/g;
+    let match = aiToken.exec(input);
+    if (!match || match.index !== 0) {
+        throw new GS1Error(`expected "(ai)" at start of element string`);
+    }
+    while (match) {
+        const ai = match[1];
+        const valueStart = aiToken.lastIndex;
+        // parentheses are legal inside CSET 82 values, so tokens that are not
+        // valid AIs belong to the value
+        let next = aiToken.exec(input);
+        while (next && !getAIDefinition(next[1]))
+            next = aiToken.exec(input);
+        const valueEnd = next ? next.index : input.length;
+        const value = input.slice(valueStart, valueEnd);
+        if (value.length === 0) {
+            throw new GS1Error(`empty value in element string`, ai);
+        }
+        elements.push(createElement(ai, value, options));
+        match = next;
+    }
+    return elements;
+}
+export function parseRawString(input, options = {}) {
+    const fnc1 = options.fnc1 ?? GS;
+    let data = input.replace(SYMBOLOGY_ID, '');
+    while (data.startsWith(fnc1))
+        data = data.slice(fnc1.length);
+    const elements = [];
+    let pos = 0;
+    while (pos < data.length) {
+        if (data.startsWith(fnc1, pos)) {
+            pos += fnc1.length;
+            continue;
+        }
+        // GS1 AIs are prefix-free: try 2-, 3-, then 4-digit AIs
+        let ai;
+        let definition;
+        for (const len of [2, 3, 4]) {
+            const candidate = data.slice(pos, pos + len);
+            if (candidate.length < len || !/^\d+$/.test(candidate))
+                break;
+            const def = getAIDefinition(candidate);
+            if (def) {
+                ai = candidate;
+                definition = def;
+                break;
+            }
+        }
+        if (!ai || !definition) {
+            throw new GS1Error(`unrecognised application identifier at position ${pos + 1} ("${data.slice(pos, pos + 4)}")`);
+        }
+        pos += ai.length;
+        let value;
+        if (definition.fixedLength !== undefined) {
+            value = data.slice(pos, pos + definition.fixedLength);
+            if (value.length < definition.fixedLength) {
+                throw new GS1Error(`expected ${definition.fixedLength} characters but only ${value.length} remain`, ai);
+            }
+            pos += definition.fixedLength;
+        }
+        else {
+            const sep = data.indexOf(fnc1, pos);
+            value = sep === -1 ? data.slice(pos) : data.slice(pos, sep);
+            pos = sep === -1 ? data.length : sep;
+        }
+        elements.push(createElement(ai, value, options));
+    }
+    return elements;
+}
+export function parse(input, options = {}) {
+    if (input.startsWith('('))
+        return parseElementString(input, options);
+    return parseRawString(input, options);
+}
+export function toRecord(elements) {
+    const record = {};
+    for (const element of elements)
+        record[element.ai] = element.value;
+    return record;
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}

package/dist/spec.d.ts

@@ -0,0 +1,4 @@
+import { SpecComponent } from './types.js';
+export declare function compileSpec(spec: string): SpecComponent[];
+export declare function validateValue(ai: string, components: SpecComponent[], value: string): void;
+export declare function describeSpec(components: SpecComponent[]): string;

package/dist/spec.js

@@ -0,0 +1,70 @@
+import { GS1Error } from './types.js';
+const CSET82 = /^[!"%&'()*+,\-./0-9:;<=>?A-Z_a-z]$/;
+const CSET39 = /^[#\-/0-9A-Z]$/;
+function inSet(ch, set) {
+    switch (set) {
+        case 'N':
+            return ch >= '0' && ch <= '9';
+        case 'X':
+            return CSET82.test(ch);
+        case 'Y':
+            return CSET39.test(ch);
+        case 'M':
+            return ch === '-';
+    }
+}
+const SET_NAMES = {
+    N: 'digits',
+    X: 'CSET 82 characters',
+    Y: 'CSET 39 characters',
+    M: '"-"',
+};
+export function compileSpec(spec) {
+    const components = spec.split('+').map((part, index) => {
+        const m = /^([NXYM])(?:(\d+)|\.\.(\d+))$/.exec(part);
+        if (!m)
+            throw new GS1Error(`invalid format spec "${part}" in "${spec}"`);
+        const set = m[1];
+        if (m[2] !== undefined) {
+            const len = Number(m[2]);
+            return { set, min: len, max: len, fixed: true };
+        }
+        // a variable component after the first is optional (e.g. GDTI serial)
+        const max = Number(m[3]);
+        return { set, min: index === 0 ? 1 : 0, max, fixed: false };
+    });
+    for (let i = 0; i < components.length - 1; i++) {
+        if (!components[i].fixed) {
+            throw new GS1Error(`invalid spec "${spec}": variable component before the end`);
+        }
+    }
+    return components;
+}
+export function validateValue(ai, components, value) {
+    let pos = 0;
+    for (const comp of components) {
+        const remaining = value.length - pos;
+        const take = comp.fixed ? comp.min : remaining;
+        if (take < comp.min || remaining < take) {
+            throw new GS1Error(`value "${value}" is too short, expected ${describeSpec(components)}`, ai);
+        }
+        if (take > comp.max) {
+            throw new GS1Error(`value "${value}" is too long, expected ${describeSpec(components)}`, ai);
+        }
+        for (let i = pos; i < pos + take; i++) {
+            if (!inSet(value[i], comp.set)) {
+                throw new GS1Error(`character "${value[i]}" at position ${i + 1} of "${value}" is not allowed (expected ${SET_NAMES[comp.set]})`, ai);
+            }
+        }
+        pos += take;
+    }
+    if (pos < value.length) {
+        throw new GS1Error(`value "${value}" is too long, expected ${describeSpec(components)}`, ai);
+    }
+}
+export function describeSpec(components) {
+    return components
+        .map((c) => (c.fixed ? `${c.set}${c.min}` : `${c.set}..${c.max}`))
+        .join('+');
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export type CharacterSet = 'N' | 'X' | 'Y' | 'M';
+export interface SpecComponent {
+    set: CharacterSet;
+    min: number;
+    max: number;
+    fixed: boolean;
+}
+export type InterpretationKind = 'date' | 'datetime' | 'dateRange' | 'decimal' | 'currencyDecimal' | 'count';
+export interface AIDefinition {
+    ai: string;
+    title: string;
+    description: string;
+    spec: string;
+    components: SpecComponent[];
+    predefinedLength: boolean;
+    fixedLength?: number;
+    checkDigitPosition?: number;
+    kind?: InterpretationKind;
+}
+export interface GS1Date {
+    year: number;
+    month: number;
+    day: number;
+    iso: string;
+}
+export interface GS1DateTime extends GS1Date {
+    hour: number;
+    minute?: number;
+    second?: number;
+}
+export type InterpretedValue = number | GS1Date | GS1DateTime | {
+    start: GS1Date;
+    end?: GS1Date;
+} | {
+    currency: string;
+    amount: number;
+};
+export interface GS1Element {
+    ai: string;
+    value: string;
+    definition: AIDefinition;
+    interpreted?: InterpretedValue;
+}
+export type ElementInput = Array<{
+    ai: string;
+    value: string;
+}> | Record<string, string>;
+export declare class GS1Error extends Error {
+    readonly ai?: string;
+    constructor(message: string, ai?: string);
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+export class GS1Error extends Error {
+    ai;
+    constructor(message, ai) {
+        super(ai ? `AI (${ai}): ${message}` : message);
+        this.name = 'GS1Error';
+        this.ai = ai;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA6DA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,EAAE,CAAU;IAErB,YAAY,OAAe,EAAE,EAAW;QACtC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "gs1-core",
+  "version": "0.1.0",
+  "description": "Zero-dependency library to parse, validate and generate GS1 element strings, raw barcode data and GS1 Digital Link URIs",
+  "keywords": [
+    "gs1",
+    "barcode",
+    "gtin",
+    "sscc",
+    "application-identifier",
+    "datamatrix",
+    "gs1-128",
+    "digital-link"
+  ],
+  "license": "MIT",
+  "author": "rmingon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmingon/gs1-core.git"
+  },
+  "homepage": "https://github.com/rmingon/gs1-core#readme",
+  "bugs": {
+    "url": "https://github.com/rmingon/gs1-core/issues"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,195 @@
+# gs1-core
+
+Parse, validate and generate GS1 strings in JavaScript/TypeScript. Zero dependencies.
+
+Supports the three ways GS1 data travels:
+
+| Format | Example |
+| --- | --- |
+| Human-readable element string | `(01)09506000134352(17)261231(10)ABC123` |
+| Raw barcode data (GS1-128, DataMatrix, QR) | `]d201095060001343521726123110ABC123` |
+| GS1 Digital Link URI | `https://id.gs1.org/01/09506000134352/10/ABC123?17=261231` |
+
+## Features
+
+- Full AI dictionary: ~180 Application Identifiers from the GS1 General Specifications, including the decimal families (`310n`-`369n`, `390n`-`395n`)
+- Validation of format specs, CSET 82 / CSET 39 character sets, dates, and check digits (GTIN, SSCC, GLN, GSIN, GSRN, GDTI, GCN, GRAI, ITIP)
+- One `parse()` call handles element strings and raw scanner data, including symbology identifiers (`]C1`, `]d2`, `]Q3`, ...)
+- Dates, weights and measures with implied decimal point, currency amounts and counts are returned as typed values, not strings
+- GS1 Digital Link URIs with correct primary key and qualifier ordering
+- ESM, fully typed, works in Node.js >= 18 and modern bundlers
+
+## Installation
+
+```sh
+npm install gs1-core
+```
+
+## Quick start
+
+```ts
+import { parse } from 'gs1-core';
+
+const elements = parse('(01)09506000134352(17)261231(3103)000189(10)ABC123');
+
+for (const el of elements) {
+  console.log(el.ai, el.definition.title, el.value, el.interpreted);
+}
+// 01    GTIN              09506000134352
+// 17    USE BY OR EXPIRY  261231   { year: 2026, month: 12, day: 31, iso: '2026-12-31' }
+// 3103  NET WEIGHT (kg)   000189   0.189
+// 10    BATCH/LOT         ABC123
+```
+
+## Usage
+
+### Parsing scanner output
+
+Raw data uses ASCII GS (`\x1D`) as the FNC1 separator by default, and a leading symbology identifier is skipped automatically:
+
+```ts
+import { parseRawString, toRecord } from 'gs1-core';
+
+const elements = parseRawString(']C101095060001343521726123110ABC123\x1D21SER99');
+
+toRecord(elements);
+// { '01': '09506000134352', '17': '261231', '10': 'ABC123', '21': 'SER99' }
+
+// Some scanners are configured to substitute FNC1 with another character:
+parseRawString('10LOT1|21SER1', { fnc1: '|' });
+```
+
+Parsing validates by default. Unknown AIs, wrong lengths, illegal characters, bad check digits and impossible dates all throw a `GS1Error` that tells you which AI failed. Pass `{ validate: false }` to parse structure only.
+
+```ts
+import { GS1Error, parse } from 'gs1-core';
+
+try {
+  parse('(01)09506000134353'); // wrong check digit
+} catch (err) {
+  if (err instanceof GS1Error) console.error(err.ai, err.message);
+  // '01' 'AI (01): invalid check digit in "09506000134353" (position 14)'
+}
+```
+
+### Generating strings
+
+```ts
+import { generateElementString, generateRawString } from 'gs1-core';
+
+const items = [
+  { ai: '01', value: '09506000134352' },
+  { ai: '10', value: 'ABC123' },
+  { ai: '17', value: '261231' },
+];
+
+generateElementString(items);
+// '(01)09506000134352(10)ABC123(17)261231'
+
+generateRawString(items);
+// '010950600013435217261231' + '10ABC123'
+```
+
+`generateRawString` produces the content to encode after the leading FNC1 of a GS1-128 / GS1 DataMatrix / GS1 QR symbol. Predefined-length AIs are moved to the front so fewer separators are needed (disable with `{ optimize: false }`), and variable-length values are GS-terminated only when another element follows.
+
+Values are validated before generation, so you cannot emit an invalid GS1 string. Check digit helpers are available if you need to compute one first:
+
+```ts
+import { withCheckDigit, computeCheckDigit, verifyCheckDigit } from 'gs1-core';
+
+withCheckDigit('0950600013435');    // '09506000134352'
+computeCheckDigit('0950600013435'); // 2
+verifyCheckDigit('09506000134352'); // true
+```
+
+### GS1 Digital Link
+
+```ts
+import { generateDigitalLink, parseDigitalLink } from 'gs1-core';
+
+generateDigitalLink(
+  [
+    { ai: '01', value: '09506000134352' },
+    { ai: '10', value: 'ABC123' },
+    { ai: '17', value: '261231' },
+  ],
+  { domain: 'https://id.example.com' }, // default: https://id.gs1.org
+);
+// 'https://id.example.com/01/09506000134352/10/ABC123?17=261231'
+
+parseDigitalLink('https://id.gs1.org/01/4006381333931?17=261231');
+// GTINs are normalised to 14 digits, resolver path prefixes are handled,
+// and non-AI query parameters (linkType, ...) are ignored.
+```
+
+### AI dictionary
+
+```ts
+import { AI_DEFINITIONS, getAIDefinition } from 'gs1-core';
+
+getAIDefinition('3103');
+// {
+//   ai: '310n', title: 'NET WEIGHT (kg)', spec: 'N6',
+//   predefinedLength: true, fixedLength: 6, kind: 'decimal', ...
+// }
+
+for (const def of AI_DEFINITIONS.values()) {
+  console.log(def.ai, def.spec, def.title);
+}
+```
+
+## Interpreted values
+
+`element.interpreted` carries a typed value when the AI has a known semantic:
+
+| Kind | AIs (examples) | Type |
+| --- | --- | --- |
+| `date` | 11, 13, 15, 17, 7006, ... | `{ year, month, day, iso }`. `DD = 00` resolves to the last day of the month; 2-digit years follow the GS1 -49/+50 sliding window |
+| `datetime` | 7003, 7011, 8008, 4324, 4325 | `{ year, ..., hour, minute?, second?, iso }` |
+| `dateRange` | 7007 | `{ start, end? }` |
+| `decimal` | 310n-369n, 390n, 392n, 394n, 395n | `number` (implied decimal point from the 4th AI digit) |
+| `currencyDecimal` | 391n, 393n | `{ currency, amount }` (ISO 4217 numeric code) |
+| `count` | 30, 37, 8111, ... | `number` |
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `parse(input, options?)` | Parse any GS1 string, auto-detecting the format |
+| `parseElementString(input, options?)` | Parse `(01)...(10)...` element strings |
+| `parseRawString(input, options?)` | Parse raw barcode data (`fnc1` option for custom separators) |
+| `parseDigitalLink(uri, options?)` | Parse a GS1 Digital Link URI |
+| `generateElementString(input, options?)` | Build a human-readable element string |
+| `generateRawString(input, options?)` | Build raw barcode content (`fnc1`, `optimize` options) |
+| `generateDigitalLink(input, options?)` | Build a Digital Link URI (`domain` option) |
+| `computeCheckDigit(digits)` / `verifyCheckDigit(digits)` / `withCheckDigit(digits)` | GS1 mod-10 check digit helpers |
+| `getAIDefinition(ai)` / `AI_DEFINITIONS` | AI dictionary lookup / full table |
+| `toRecord(elements)` | Convert parsed elements to `{ ai: value }` |
+| `parseDate6`, `parseDateTime`, `resolveYear`, `interpretValue` | Low-level interpretation helpers |
+
+Generator functions accept either an array of `{ ai, value }` pairs (order preserved) or a plain record `{ '01': '...', '10': '...' }`. Note that JavaScript iterates integer-like keys such as `'10'` before keys like `'01'`, so use the array form when order matters.
+
+All errors are instances of `GS1Error`, which exposes the offending `ai` when known.
+
+## Known limitations
+
+- In human-readable element strings, a value that itself contains a `"(AI)"`-shaped sequence (parentheses are legal CSET 82 characters) is ambiguous and will be split. Use the raw format for such data; this ambiguity is inherent to the human-readable notation.
+- Trailing components documented as mandatory by GS1 for a few AIs (e.g. the postal code of AI 421) are treated as optional.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+```sh
+git clone https://github.com/rmingon/gs1-core.git
+cd gs1-core
+npm install
+npm test        # run the vitest suite
+npm run build   # type-check and emit dist/
+```
+
+If you spot a missing or outdated Application Identifier, please open an issue with a reference to the relevant GS1 General Specifications section. The whole dictionary lives in [src/ai.ts](src/ai.ts).
+
+## License
+
+[MIT](./LICENSE)