# @verisav/gs1-dpp-utils

**Validate GTIN, GLN & GS1 Digital Link URIs for EU Digital Product Passports.**  
Zero dependencies. Compliant with GS1 GSMP (GSCN 23-103). Aligned with EU ESPR and DPP use cases.

**Used in production at [Verisav](https://www.verisav.fr)** for the [DPP Compliance Checker](https://tools.verisav.fr/tools/dpp-compliance-checker), [GLN Validator](https://tools.verisav.fr/tools/gln-validator), and [DPP QR Generator](https://tools.verisav.fr/tools/dpp-qr-generator).

## Install

```bash
npm install @verisav/gs1-dpp-utils
```

## Usage

```ts
import {
  validateGTIN,
  validateGLN,
  generateGS1DigitalLinkURI,
  validateGS1DigitalLinkURI,
  extractGTINFromJSONLD,
  extractGLNFromJSONLD,
  generateGLN,
} from '@verisav/gs1-dpp-utils'

// Validate GTIN (GTIN-8, -12, -13, -14)
validateGTIN('1234567890128')   // { valid: true, type: 'GTIN-13' }
validateGTIN('123')             // { valid: false, error: '...' }

// Validate GLN (13 digits)
validateGLN('9501101530003')    // { valid: true }

// Generate GS1 Digital Link URI
generateGS1DigitalLinkURI('1234567890128')
// 'https://id.gs1.org/01/1234567890128'

generateGS1DigitalLinkURI('1234567890128', { serial: 'SN-ABC', lot: 'LOT1' })
// 'https://id.gs1.org/01/1234567890128/21/SN-ABC/10/LOT1'

// Validate a Digital Link URL
validateGS1DigitalLinkURI('https://id.gs1.org/01/1234567890128/21/SN123')
// { valid: true, isGS1: true, gtin: '1234567890128', details: { ai01: '...', ai21: '...' } }

// Extract from JSON-LD (DPP, Schema.org Product, etc.)
extractGTINFromJSONLD({ gtin: '1234567890128', name: 'Product' })  // '1234567890128'
extractGLNFromJSONLD(dppJsonLd)  // GLN from manufacturer address if present

// Generate test GLN (testing only; production GLNs are assigned by GS1)
generateGLN('950')  // e.g. '9501234567890'
```

## API

| Function | Description |
|----------|-------------|
| `validateGTIN(gtin)` | Returns `{ valid, type?, error? }`. Supports GTIN-8, 12, 13, 14. |
| `validateGLN(gln)` | Returns `{ valid, error? }`. GLN is always 13 digits. |
| `generateGS1DigitalLinkURI(gtin, params?)` | Builds `https://id.gs1.org/01/{GTIN}[/AI/value...]`. Returns `null` if GTIN invalid. |
| `validateGS1DigitalLinkURI(uri)` | Parses and validates a GS1 Digital Link URL. Returns `{ valid, isGS1, gtin?, details?, error? }`. |
| `extractGTINFromJSONLD(obj)` | Extracts GTIN from `identifier` (PropertyValue) or `gtin`. |
| `extractGLNFromJSONLD(obj)` | Extracts GLN from `identifier` or `manufacturer.address`. |
| `generateGLN(prefix?)` | Generates a valid 13-digit GLN (test prefix `950` by default). |

## References

- [GS1 Digital Link](https://www.gs1.org/standards/Digital-Link/)
- [GS1 GTIN](https://www.gs1.org/standards/id-keys/gtin)
- [GS1 GLN](https://www.gs1.org/standards/id-keys/gln)
- [EU ESPR / Digital Product Passport](https://digital-strategy.ec.europa.eu/en/policies/digital-product-passport)

## License

MIT