@proveanything/smartlinks 1.15.21 → 1.15.23

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.21  |  Generated: 2026-08-25T08:34:52.897Z
+Version: 1.15.23  |  Generated: 2026-08-28T10:57:24.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -35,6 +35,7 @@ For detailed guides on specific features:
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
 - **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
+- **[Item Context](item-context.md)** - The `itemContext` container prop derived from a serial-proof URL or NFC tap (what item the URL points at)
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
@@ -8266,6 +8267,37 @@ interface PortalPathParams {
   proof?: Proof | string
   queryParams?: Record<string, string>
   pathOnly?: boolean
+  * Override custom-domain detection. When the collection is served from its own
+  * custom domain, a GS1 link resolves `/01/{gtin}` directly (the host identifies
+  * the collection), so the `/gc/{shortId}` prefix is dropped. Left undefined, this
+  * is auto-detected from `collection.redirectUrl` or a non-platform `portalUrl` host.
+  customDomain?: boolean
+}
+```
+
+**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
 }
 ```
 

package/dist/docs/utils.md

@@ -77,16 +77,26 @@ Builds a full portal URL based on the provided parameters. Returns full URL by d
 
 - `pathOnly` (optional, default: `false`) - Return only the path without domain  
   Set to `true` to get `/c/abc/prod` instead of `https://domain.com/c/abc/prod`
+- `customDomain` (optional) - Override custom-domain detection. When a collection is
+  served from its own custom domain, a GS1 link resolves `/01/{gtin}` directly (the host
+  identifies the collection), so the `/gc/{shortId}` prefix is dropped. Leave unset to
+  auto-detect from `collection.redirectUrl` or a non-platform `portalUrl` host.
 
 **Path Formats:**
 
 - Basic product: `/c/{shortId}/{productId}`
 - With proof: `/c/{shortId}/{productId}/{proofId}`
-- GTIN (own): `/01/{gtin}` (when product.ownGtin is true)
-- GTIN (not own): `/gc/{shortId}/01/{gtin}` (when product.ownGtin is false)
+- GTIN (own, or on a custom domain): `/01/{gtin}` — when `product.ownGtin` is set, **or** the
+  collection is on its own custom domain (bare `/01/` resolves via the host)
+- GTIN (not own, on the shared platform domain): `/gc/{shortId}/01/{gtin}`
 - With batch: adds `/10/{batchId}` and optionally `?17={expiryDate}`
 - With variant: adds `/22/{variantId}`
 
+**Custom domain behaviour:** On `smartlinks.app`, a non-master GTIN needs the `/gc/{shortId}`
+collection prefix so the server can scope it; a master GTIN (`ownGtin`) uses bare `/01/`.
+On a collection's **own custom domain**, the host already identifies the collection, so the
+generator emits the clean `https://customdomain/01/{gtin}` for any product — no `/gc/` prefix.
+
 ## Examples
 
 ### Full URL (Default Behavior)
@@ -209,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

@@ -30,6 +30,13 @@ export interface PortalPathParams {
     queryParams?: Record<string, string>;
     /** Return only the path without domain (default: false, returns full URL) */
     pathOnly?: boolean;
+    /**
+     * Override custom-domain detection. When the collection is served from its own
+     * custom domain, a GS1 link resolves `/01/{gtin}` directly (the host identifies
+     * the collection), so the `/gc/{shortId}` prefix is dropped. Left undefined, this
+     * is auto-detected from `collection.redirectUrl` or a non-platform `portalUrl` host.
+     */
+    customDomain?: boolean;
 }
 /**
  * Builds a portal path/URL based on the provided parameters.
@@ -43,8 +50,9 @@ export interface PortalPathParams {
  * Supports multiple path formats:
  * - Basic product: `/c/{shortId}/{productId}`
  * - With proof: `/c/{shortId}/{productId}/{proofId}`
- * - GTIN (own): `/01/{gtin}` - ownGtin is read from the product object
- * - GTIN (not own): `/gc/{shortId}/01/{gtin}`
+ * - GTIN (own, or on a custom domain): `/01/{gtin}` — `ownGtin` is read from the product;
+ *   a custom domain (see `customDomain` / `collection.redirectUrl`) also uses this bare form
+ * - GTIN (not own, on the shared platform domain): `/gc/{shortId}/01/{gtin}`
  * - With batch: adds `/10/{batchId}` and optionally `?17={expiryDate}`
  * - With variant: adds `/22/{variantId}`
  *
@@ -93,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

@@ -1,3 +1,21 @@
+// Hosts served by the platform itself (not a collection's own custom domain). A base
+// URL on any of these is NOT a custom domain, so non-master GTINs still need the
+// `/gc/{shortId}` collection prefix. `portalUrl` is only ever set to the platform
+// default or a collection's custom domain, so exact-host matching is sufficient here.
+const PLATFORM_HOSTS = ['smartlinks.app', 'mysmartlinks.app', 'zt.smartlinks.io'];
+/** True when `baseUrl`'s host is a collection's own custom domain (not a platform host). */
+function baseIsCustomDomain(baseUrl) {
+    if (!baseUrl)
+        return false;
+    let host;
+    try {
+        host = new URL(baseUrl).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch (_a) {
+        return false;
+    }
+    return host.length > 0 && !PLATFORM_HOSTS.includes(host);
+}
 /**
  * Builds a portal path/URL based on the provided parameters.
  *
@@ -10,8 +28,9 @@
  * Supports multiple path formats:
  * - Basic product: `/c/{shortId}/{productId}`
  * - With proof: `/c/{shortId}/{productId}/{proofId}`
- * - GTIN (own): `/01/{gtin}` - ownGtin is read from the product object
- * - GTIN (not own): `/gc/{shortId}/01/{gtin}`
+ * - GTIN (own, or on a custom domain): `/01/{gtin}` — `ownGtin` is read from the product;
+ *   a custom domain (see `customDomain` / `collection.redirectUrl`) also uses this bare form
+ * - GTIN (not own, on the shared platform domain): `/gc/{shortId}/01/{gtin}`
  * - With batch: adds `/10/{batchId}` and optionally `?17={expiryDate}`
  * - With variant: adds `/22/{variantId}`
  *
@@ -60,20 +79,26 @@
  * ```
  */
 export function buildPortalPath(params) {
-    var _a, _b;
+    var _a, _b, _c;
     const { collection, product, productId, batch, batchId, variant, proof, queryParams = {}, pathOnly = false } = params;
     // Extract values from collection
     const shortId = collection.shortId;
     const baseUrl = 'portalUrl' in collection ? collection.portalUrl : undefined;
+    // A collection on its own custom domain resolves `/01/{gtin}` directly (the host
+    // maps to the collection server-side), so the `/gc/{shortId}` prefix is dropped.
+    // Explicit override wins; otherwise detect from `redirectUrl` (the server's own
+    // custom-domain signal) or a non-platform `portalUrl` host.
+    const redirectUrl = 'redirectUrl' in collection ? collection.redirectUrl : undefined;
+    const customDomain = (_a = params.customDomain) !== null && _a !== void 0 ? _a : (!!redirectUrl || baseIsCustomDomain(baseUrl));
     // Extract product values
     let gtin;
     let ownGtin;
     let extractedProductId;
     if (product) {
         extractedProductId = product.id;
-        gtin = (_a = product.gtin) !== null && _a !== void 0 ? _a : undefined;
+        gtin = (_b = product.gtin) !== null && _b !== void 0 ? _b : undefined;
         // ownGtin is a critical product setting - only read from product, never override
-        ownGtin = 'ownGtin' in product ? (_b = product.ownGtin) !== null && _b !== void 0 ? _b : undefined : undefined;
+        ownGtin = 'ownGtin' in product ? (_c = product.ownGtin) !== null && _c !== void 0 ? _c : undefined : undefined;
     }
     else if (productId) {
         extractedProductId = productId;
@@ -110,32 +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
-        if (ownGtin) {
-            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
@@ -177,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.21  |  Generated: 2026-08-25T08:34:52.897Z
+Version: 1.15.23  |  Generated: 2026-08-28T10:57:24.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -35,6 +35,7 @@ For detailed guides on specific features:
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
 - **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
+- **[Item Context](item-context.md)** - The `itemContext` container prop derived from a serial-proof URL or NFC tap (what item the URL points at)
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
@@ -8266,6 +8267,37 @@ interface PortalPathParams {
   proof?: Proof | string
   queryParams?: Record<string, string>
   pathOnly?: boolean
+  * Override custom-domain detection. When the collection is served from its own
+  * custom domain, a GS1 link resolves `/01/{gtin}` directly (the host identifies
+  * the collection), so the `/gc/{shortId}` prefix is dropped. Left undefined, this
+  * is auto-detected from `collection.redirectUrl` or a non-platform `portalUrl` host.
+  customDomain?: boolean
+}
+```
+
+**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
 }
 ```
 

package/docs/utils.md

@@ -77,16 +77,26 @@ Builds a full portal URL based on the provided parameters. Returns full URL by d
 
 - `pathOnly` (optional, default: `false`) - Return only the path without domain  
   Set to `true` to get `/c/abc/prod` instead of `https://domain.com/c/abc/prod`
+- `customDomain` (optional) - Override custom-domain detection. When a collection is
+  served from its own custom domain, a GS1 link resolves `/01/{gtin}` directly (the host
+  identifies the collection), so the `/gc/{shortId}` prefix is dropped. Leave unset to
+  auto-detect from `collection.redirectUrl` or a non-platform `portalUrl` host.
 
 **Path Formats:**
 
 - Basic product: `/c/{shortId}/{productId}`
 - With proof: `/c/{shortId}/{productId}/{proofId}`
-- GTIN (own): `/01/{gtin}` (when product.ownGtin is true)
-- GTIN (not own): `/gc/{shortId}/01/{gtin}` (when product.ownGtin is false)
+- GTIN (own, or on a custom domain): `/01/{gtin}` — when `product.ownGtin` is set, **or** the
+  collection is on its own custom domain (bare `/01/` resolves via the host)
+- GTIN (not own, on the shared platform domain): `/gc/{shortId}/01/{gtin}`
 - With batch: adds `/10/{batchId}` and optionally `?17={expiryDate}`
 - With variant: adds `/22/{variantId}`
 
+**Custom domain behaviour:** On `smartlinks.app`, a non-master GTIN needs the `/gc/{shortId}`
+collection prefix so the server can scope it; a master GTIN (`ownGtin`) uses bare `/01/`.
+On a collection's **own custom domain**, the host already identifies the collection, so the
+generator emits the clean `https://customdomain/01/{gtin}` for any product — no `/gc/` prefix.
+
 ## Examples
 
 ### Full URL (Default Behavior)
@@ -209,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.21",
+  "version": "1.15.23",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,7 @@
     "README.md"
   ],
   "scripts": {
+    "test": "node test/run.cjs",
     "build": "tsc && node generate-api-summary.js && node generate-openapi.js && node scripts/copy-docs-to-dist.js",
     "docs": "typedoc",
     "docs:summary": "node generate-api-summary.js",