@proveanything/smartlinks 1.15.22 → 1.15.23

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.22  |  Generated: 2026-08-27T17:34:12.788Z
+Version: 1.15.23  |  Generated: 2026-08-28T10:57:24.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -8275,6 +8275,32 @@ interface PortalPathParams {
 }
 ```
 
+**Gs1DigitalLinkParams** (interface)
+```typescript
+interface Gs1DigitalLinkParams {
+  collection?: Collection | { shortId?: string; portalUrl?: string; redirectUrl?: string }
+  domain?: string
+  gtin?: string
+  product?: Product
+  ownGtin?: boolean
+  cpv?: string | { id: string }
+  variant?: string | { id: string }
+  lot?: string | { id: string }
+  batch?: BatchResponse | string
+  serial?: string | { id?: string; serialNumber?: string }
+  expiry?: string | Date
+  * Any other GS1 Application Identifiers as `{ [ai]: value }` — e.g.
+  * `{ '11': prodDate, '3103': '000500' }`. Date AIs (11/12/13/15/16/17) accept a
+  * `Date` and are formatted `YYMMDD`; path-qualifier AIs (22/10/21) are placed in
+  * the path in canonical order; everything else becomes a query-string data attribute.
+  ais?: Record<string, string | number | Date>
+  linkType?: string
+  queryParams?: Record<string, string>
+  customDomain?: boolean
+  pathOnly?: boolean
+}
+```
+
 ## API Functions
 
 ### analytics.admin

package/dist/docs/utils.md

@@ -219,6 +219,52 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123?utm_source=email&utm_campaign=launch&lang=fr
 ```
 
+## GS1 Digital Links — `buildGs1DigitalLink(params)`
+
+`buildPortalPath` covers portal routing; when you specifically want a **GS1 Digital Link**
+with the full range of Application Identifiers (AIs), use `buildGs1DigitalLink`. It emits
+path qualifiers in the **canonical GS1 order** — `/01/{gtin}/22/{cpv}/10/{lot}/21/{serial}` —
+routes data attributes (expiry, production date, weights, …) to the query string, and applies
+the same custom-domain scoping (bare `/01/` on a custom domain or for a master GTIN, `/gc/{shortId}`
+otherwise).
+
+**Named inputs** for the common AIs, plus a generic **`ais` map** for anything else:
+
+| Input | AI | Notes |
+|-------|----|-------|
+| `gtin` / `product.gtin` | 01 | Primary identifier (required) |
+| `cpv` / `variant` | 22 | Consumer Product Variant (path) |
+| `lot` / `batch` | 10 | Batch/lot (path); a batch object also supplies its expiry |
+| `serial` | 21 | Specific item — a string, or an object (`serialNumber` ?? `id`, e.g. a proof / serial / virtual id) |
+| `expiry` | 17 | Date → `YYMMDD` (query) |
+| `ais: { [ai]: value }` | any | Date AIs (11/12/13/15/16/17) formatted `YYMMDD`; qualifier AIs (22/10/21) go in the path; the rest become query attributes |
+| `linkType` | — | GS1 `linkType`, added as `?linkType=` |
+
+```typescript
+// Variant + lot + serial + expiry, on a custom domain
+utils.buildGs1DigitalLink({
+  collection,               // portalUrl = https://acme.com
+  gtin: '05012345678900',
+  variant: 'red',
+  lot: 'LOT42',
+  serial: proof,            // AI 21 from proof.serialNumber ?? proof.id
+  expiry: '2026-06-30',
+})
+// → https://acme.com/01/05012345678900/22/red/10/LOT42/21/{serial}?17=260630
+
+// Arbitrary AIs via the generic map
+utils.buildGs1DigitalLink({
+  collection,
+  gtin: '05012345678900',
+  ais: { '11': new Date(2025, 0, 1), '3103': '000500' }, // production date + net weight
+  linkType: 'gs1:pip',
+})
+// → https://.../01/05012345678900?11=250101&3103=000500&linkType=gs1%3Apip
+```
+
+`buildPortalPath` delegates its GTIN paths to this function, so both stay in sync (and both now
+emit qualifiers in canonical `22 → 10 → 21` order).
+
 ## Use Cases
 
 ### QR Code Generation

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { iframe } from "./iframe";
 export * as cache from './cache';
 export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
 export * as utils from './utils';
-export type { PortalPathParams, ConditionParams, ConditionDebugOptions, ConditionDebugLogger, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils';
+export type { PortalPathParams, Gs1DigitalLinkParams, ConditionParams, ConditionDebugOptions, ConditionDebugLogger, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils';
 export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, AuthLocation, } from "./api/auth";
 export type { UserAccountRegistrationRequest, } from "./types/auth";
 export type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, CommsSettings, TopicConfig, CommsSettingsGetResponse, CommsSettingsPatchBody, CommsPublicTopicsResponse, UnsubscribeQuery, UnsubscribeResponse, CommsConsentUpsertRequest, CommsPreferencesUpsertRequest, CommsSubscribeRequest, CommsSubscribeResponse, CommsSubscriptionCheckQuery, CommsSubscriptionCheckResponse, CommsListMethodsQuery, CommsListMethodsResponse, RegisterEmailMethodRequest, RegisterSmsMethodRequest, RegisterMethodResponse, SubscriptionsResolveRequest, SubscriptionsResolveResponse, } from "./types/comms";

package/dist/utils/paths.d.ts

@@ -101,3 +101,87 @@ export interface PortalPathParams {
  * ```
  */
 export declare function buildPortalPath(params: PortalPathParams): string;
+export interface Gs1DigitalLinkParams {
+    /** Collection — provides the base domain (`portalUrl`), `shortId` (for `/gc` scoping) and custom-domain detection. */
+    collection?: Collection | {
+        shortId?: string;
+        portalUrl?: string;
+        redirectUrl?: string;
+    };
+    /** Explicit base domain (e.g. `"https://acme.com"`), overriding `collection.portalUrl`. */
+    domain?: string;
+    /** GTIN — the product's AI 01 identifier. Required (or provide `product`). */
+    gtin?: string;
+    /** Product object — extracts `gtin` and `ownGtin` when not given explicitly. */
+    product?: Product;
+    /** Override the global-owner flag; otherwise read from `product.ownGtin`. */
+    ownGtin?: boolean;
+    /** Consumer Product Variant (AI 22). A string or an object with `id`. */
+    cpv?: string | {
+        id: string;
+    };
+    /** Alias of `cpv` (AI 22). */
+    variant?: string | {
+        id: string;
+    };
+    /** Batch / lot (AI 10). A string or an object with `id`. */
+    lot?: string | {
+        id: string;
+    };
+    /** Alias of `lot` (AI 10). A `BatchResponse` also contributes its expiry date (AI 17) unless `expiry` is set. */
+    batch?: BatchResponse | string;
+    /** Serial (AI 21) — the specific item / proof. A string (serial / NFC / virtual id) or an object (`serialNumber` ?? `id`, e.g. a proof). */
+    serial?: string | {
+        id?: string;
+        serialNumber?: string;
+    };
+    /** Expiry date (AI 17). A `Date`, ISO string, or `YYMMDD` string. */
+    expiry?: string | Date;
+    /**
+     * Any other GS1 Application Identifiers as `{ [ai]: value }` — e.g.
+     * `{ '11': prodDate, '3103': '000500' }`. Date AIs (11/12/13/15/16/17) accept a
+     * `Date` and are formatted `YYMMDD`; path-qualifier AIs (22/10/21) are placed in
+     * the path in canonical order; everything else becomes a query-string data attribute.
+     */
+    ais?: Record<string, string | number | Date>;
+    /** GS1 `linkType` (added as a `?linkType=` query param). */
+    linkType?: string;
+    /** Additional non-GS1 query params. */
+    queryParams?: Record<string, string>;
+    /** Override custom-domain detection (see {@link buildPortalPath}). */
+    customDomain?: boolean;
+    /** Return only the path, without a domain. */
+    pathOnly?: boolean;
+}
+/**
+ * Builds a GS1 Digital Link for a product, with full support for the standard
+ * Application Identifiers. Path qualifiers are emitted in the canonical GS1 order
+ * (`/01/{gtin}/22/{cpv}/10/{lot}/21/{serial}`); data attributes (expiry, production
+ * date, weights, …) become query params; `linkType` is appended for GS1 resolution.
+ *
+ * A bare `/01/{gtin}` is used when the product owns the GTIN globally (`ownGtin`) or
+ * the collection is on its own custom domain; otherwise the GTIN is scoped to the
+ * collection with the `/gc/{shortId}` prefix on the shared platform domain.
+ *
+ * @example
+ * ```ts
+ * // GTIN + variant + lot + serial + expiry, on a custom domain
+ * buildGs1DigitalLink({
+ *   collection,                 // portalUrl = https://acme.com
+ *   gtin: '05012345678900',
+ *   variant: 'red',
+ *   lot: 'LOT42',
+ *   serial: proof,              // AI 21 from proof.serialNumber ?? proof.id
+ *   expiry: '2026-06-30',
+ * })
+ * // → https://acme.com/01/05012345678900/22/red/10/LOT42/21/{serial}?17=260630
+ *
+ * // Arbitrary AIs via the generic map
+ * buildGs1DigitalLink({
+ *   collection, gtin: '05012345678900',
+ *   ais: { '11': new Date('2025-01-01'), '3103': '000500' }, // production date + net weight (kg)
+ *   linkType: 'gs1:pip',
+ * })
+ * ```
+ */
+export declare function buildGs1DigitalLink(params: Gs1DigitalLinkParams): string;

package/dist/utils/paths.js

@@ -135,35 +135,25 @@ export function buildPortalPath(params) {
             ? proof
             : proof.id
         : undefined;
-    let pathname = '';
-    const searchParams = new URLSearchParams();
-    // Build pathname based on GTIN or product ID
+    // GTIN → delegate to the GS1 Digital Link generator (canonical AI ordering:
+    // /01/{gtin}/22/{cpv}/10/{lot}/21/{serial}, data attributes as query params).
     if (gtin) {
-        // GS1 Digital Link format. A bare `/01/{gtin}` is used when the product owns the
-        // GTIN globally (master registry) OR when we're on the collection's custom domain
-        // (the host resolves the collection). Otherwise the GTIN must be scoped to the
-        // collection with the `/gc/{shortId}` prefix on the shared platform domain.
-        if (ownGtin || customDomain) {
-            pathname = `/01/${gtin}`;
-        }
-        else {
-            pathname = `/gc/${shortId}/01/${gtin}`;
-        }
-        // Add batch (GS1 AI 10)
-        if (extractedBatchId) {
-            pathname += `/10/${extractedBatchId}`;
-            // Add expiry date as query param (GS1 AI 17)
-            if (expiryDate) {
-                const dateStr = formatExpiryDate(expiryDate);
-                searchParams.append('17', dateStr);
-            }
-        }
-        // Add variant (GS1 AI 22)
-        if (variantId) {
-            pathname += `/22/${variantId}`;
-        }
+        return buildGs1DigitalLink({
+            domain: baseUrl,
+            collection,
+            gtin,
+            ownGtin,
+            customDomain,
+            variant: variantId,
+            lot: extractedBatchId,
+            expiry: expiryDate,
+            queryParams,
+            pathOnly,
+        });
     }
-    else if (extractedProductId) {
+    let pathname = '';
+    const searchParams = new URLSearchParams();
+    if (extractedProductId) {
         // Regular product path
         pathname = `/c/${shortId}/${extractedProductId}`;
         // Add proof to path
@@ -205,3 +195,129 @@ function formatExpiryDate(date) {
     const day = date.getDate().toString().padStart(2, '0');
     return `${year}${month}${day}`;
 }
+// ─── GS1 Digital Link generator ──────────────────────────────────────────────
+/** GS1 path qualifiers for a GTIN (AI 01) key, in the canonical GS1 Digital Link order. */
+const GTIN_PATH_QUALIFIERS = ['22', '10', '21'];
+/** GS1 Application Identifiers whose value is a date — formatted `YYMMDD`. */
+const DATE_AIS = new Set(['11', '12', '13', '15', '16', '17']);
+/** Pull a code out of a string or an object (`serialNumber` preferred, then `id`). */
+function extractCode(v) {
+    var _a;
+    if (v == null)
+        return undefined;
+    if (typeof v === 'string')
+        return v;
+    return (_a = v.serialNumber) !== null && _a !== void 0 ? _a : v.id;
+}
+/**
+ * Builds a GS1 Digital Link for a product, with full support for the standard
+ * Application Identifiers. Path qualifiers are emitted in the canonical GS1 order
+ * (`/01/{gtin}/22/{cpv}/10/{lot}/21/{serial}`); data attributes (expiry, production
+ * date, weights, …) become query params; `linkType` is appended for GS1 resolution.
+ *
+ * A bare `/01/{gtin}` is used when the product owns the GTIN globally (`ownGtin`) or
+ * the collection is on its own custom domain; otherwise the GTIN is scoped to the
+ * collection with the `/gc/{shortId}` prefix on the shared platform domain.
+ *
+ * @example
+ * ```ts
+ * // GTIN + variant + lot + serial + expiry, on a custom domain
+ * buildGs1DigitalLink({
+ *   collection,                 // portalUrl = https://acme.com
+ *   gtin: '05012345678900',
+ *   variant: 'red',
+ *   lot: 'LOT42',
+ *   serial: proof,              // AI 21 from proof.serialNumber ?? proof.id
+ *   expiry: '2026-06-30',
+ * })
+ * // → https://acme.com/01/05012345678900/22/red/10/LOT42/21/{serial}?17=260630
+ *
+ * // Arbitrary AIs via the generic map
+ * buildGs1DigitalLink({
+ *   collection, gtin: '05012345678900',
+ *   ais: { '11': new Date('2025-01-01'), '3103': '000500' }, // production date + net weight (kg)
+ *   linkType: 'gs1:pip',
+ * })
+ * ```
+ */
+export function buildGs1DigitalLink(params) {
+    var _a, _b, _c, _d, _e, _f;
+    const { collection, product, expiry, linkType, ais = {}, queryParams = {}, pathOnly = false } = params;
+    const gtin = (_b = (_a = params.gtin) !== null && _a !== void 0 ? _a : product === null || product === void 0 ? void 0 : product.gtin) !== null && _b !== void 0 ? _b : undefined;
+    if (!gtin) {
+        throw new Error('buildGs1DigitalLink requires a `gtin` (or a `product` that has one)');
+    }
+    const ownGtin = (_c = params.ownGtin) !== null && _c !== void 0 ? _c : (product && 'ownGtin' in product ? !!product.ownGtin : false);
+    // Base domain + custom-domain scoping (same rules as buildPortalPath).
+    const shortId = collection === null || collection === void 0 ? void 0 : collection.shortId;
+    const baseUrl = (_d = params.domain) !== null && _d !== void 0 ? _d : (collection && 'portalUrl' in collection ? collection.portalUrl : undefined);
+    const redirectUrl = collection && 'redirectUrl' in collection ? collection.redirectUrl : undefined;
+    const customDomain = (_e = params.customDomain) !== null && _e !== void 0 ? _e : (!!redirectUrl || baseIsCustomDomain(baseUrl));
+    // ── Path qualifiers (AI 22 → 10 → 21) ──
+    const pathAIs = {};
+    const cpv = extractCode((_f = params.cpv) !== null && _f !== void 0 ? _f : params.variant);
+    if (cpv != null)
+        pathAIs['22'] = cpv;
+    let batchExpiry;
+    let lot = extractCode(params.lot);
+    if (lot == null && params.batch != null) {
+        if (typeof params.batch === 'string') {
+            lot = params.batch;
+        }
+        else {
+            lot = params.batch.id;
+            const exp = params.batch.expiryDate;
+            if (exp) {
+                batchExpiry = (typeof exp === 'object' && 'seconds' in exp)
+                    ? new Date(exp.seconds * 1000)
+                    : exp;
+            }
+        }
+    }
+    if (lot != null)
+        pathAIs['10'] = lot;
+    const serial = extractCode(params.serial);
+    if (serial != null)
+        pathAIs['21'] = serial;
+    // ── Data attributes (query string) ──
+    const attrs = {};
+    const setAttr = (ai, value) => {
+        attrs[ai] = DATE_AIS.has(ai) && (value instanceof Date || typeof value === 'string')
+            ? formatExpiryDate(value)
+            : String(value);
+    };
+    const effectiveExpiry = expiry !== null && expiry !== void 0 ? expiry : batchExpiry;
+    if (effectiveExpiry != null)
+        setAttr('17', effectiveExpiry);
+    // Generic AI map: classify each entry as a path qualifier or a data attribute.
+    for (const [ai, value] of Object.entries(ais)) {
+        if (value == null)
+            continue;
+        if (GTIN_PATH_QUALIFIERS.includes(ai)) {
+            pathAIs[ai] = String(value);
+        }
+        else {
+            setAttr(ai, value);
+        }
+    }
+    // ── Compose the path ──
+    let pathname = (ownGtin || customDomain || !shortId) ? `/01/${gtin}` : `/gc/${shortId}/01/${gtin}`;
+    for (const ai of GTIN_PATH_QUALIFIERS) {
+        if (pathAIs[ai] != null)
+            pathname += `/${ai}/${pathAIs[ai]}`;
+    }
+    // ── Query string ──
+    const searchParams = new URLSearchParams();
+    for (const [ai, value] of Object.entries(attrs))
+        searchParams.append(ai, value);
+    if (linkType)
+        searchParams.append('linkType', linkType);
+    for (const [k, v] of Object.entries(queryParams))
+        searchParams.append(k, v);
+    const queryString = searchParams.toString();
+    const fullPath = pathname + (queryString ? `?${queryString}` : '');
+    if (pathOnly)
+        return fullPath;
+    const domain = baseUrl || 'https://smartlinks.app';
+    return domain.replace(/\/$/, '') + fullPath;
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.22  |  Generated: 2026-08-27T17:34:12.788Z
+Version: 1.15.23  |  Generated: 2026-08-28T10:57:24.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -8275,6 +8275,32 @@ interface PortalPathParams {
 }
 ```
 
+**Gs1DigitalLinkParams** (interface)
+```typescript
+interface Gs1DigitalLinkParams {
+  collection?: Collection | { shortId?: string; portalUrl?: string; redirectUrl?: string }
+  domain?: string
+  gtin?: string
+  product?: Product
+  ownGtin?: boolean
+  cpv?: string | { id: string }
+  variant?: string | { id: string }
+  lot?: string | { id: string }
+  batch?: BatchResponse | string
+  serial?: string | { id?: string; serialNumber?: string }
+  expiry?: string | Date
+  * Any other GS1 Application Identifiers as `{ [ai]: value }` — e.g.
+  * `{ '11': prodDate, '3103': '000500' }`. Date AIs (11/12/13/15/16/17) accept a
+  * `Date` and are formatted `YYMMDD`; path-qualifier AIs (22/10/21) are placed in
+  * the path in canonical order; everything else becomes a query-string data attribute.
+  ais?: Record<string, string | number | Date>
+  linkType?: string
+  queryParams?: Record<string, string>
+  customDomain?: boolean
+  pathOnly?: boolean
+}
+```
+
 ## API Functions
 
 ### analytics.admin

package/docs/utils.md

@@ -219,6 +219,52 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123?utm_source=email&utm_campaign=launch&lang=fr
 ```
 
+## GS1 Digital Links — `buildGs1DigitalLink(params)`
+
+`buildPortalPath` covers portal routing; when you specifically want a **GS1 Digital Link**
+with the full range of Application Identifiers (AIs), use `buildGs1DigitalLink`. It emits
+path qualifiers in the **canonical GS1 order** — `/01/{gtin}/22/{cpv}/10/{lot}/21/{serial}` —
+routes data attributes (expiry, production date, weights, …) to the query string, and applies
+the same custom-domain scoping (bare `/01/` on a custom domain or for a master GTIN, `/gc/{shortId}`
+otherwise).
+
+**Named inputs** for the common AIs, plus a generic **`ais` map** for anything else:
+
+| Input | AI | Notes |
+|-------|----|-------|
+| `gtin` / `product.gtin` | 01 | Primary identifier (required) |
+| `cpv` / `variant` | 22 | Consumer Product Variant (path) |
+| `lot` / `batch` | 10 | Batch/lot (path); a batch object also supplies its expiry |
+| `serial` | 21 | Specific item — a string, or an object (`serialNumber` ?? `id`, e.g. a proof / serial / virtual id) |
+| `expiry` | 17 | Date → `YYMMDD` (query) |
+| `ais: { [ai]: value }` | any | Date AIs (11/12/13/15/16/17) formatted `YYMMDD`; qualifier AIs (22/10/21) go in the path; the rest become query attributes |
+| `linkType` | — | GS1 `linkType`, added as `?linkType=` |
+
+```typescript
+// Variant + lot + serial + expiry, on a custom domain
+utils.buildGs1DigitalLink({
+  collection,               // portalUrl = https://acme.com
+  gtin: '05012345678900',
+  variant: 'red',
+  lot: 'LOT42',
+  serial: proof,            // AI 21 from proof.serialNumber ?? proof.id
+  expiry: '2026-06-30',
+})
+// → https://acme.com/01/05012345678900/22/red/10/LOT42/21/{serial}?17=260630
+
+// Arbitrary AIs via the generic map
+utils.buildGs1DigitalLink({
+  collection,
+  gtin: '05012345678900',
+  ais: { '11': new Date(2025, 0, 1), '3103': '000500' }, // production date + net weight
+  linkType: 'gs1:pip',
+})
+// → https://.../01/05012345678900?11=250101&3103=000500&linkType=gs1%3Apip
+```
+
+`buildPortalPath` delegates its GTIN paths to this function, so both stay in sync (and both now
+emit qualifiers in canonical `22 → 10 → 21` order).
+
 ## Use Cases
 
 ### QR Code Generation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.15.22",
+  "version": "1.15.23",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",