@proveanything/smartlinks 1.15.21 → 1.15.22

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.22  |  Generated: 2026-08-27T17:34:12.788Z
 
 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,11 @@ 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
 }
 ```
 

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)

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}`
  *

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;
@@ -114,8 +139,11 @@ export function buildPortalPath(params) {
     const searchParams = new URLSearchParams();
     // Build pathname based on GTIN or product ID
     if (gtin) {
-        // GS1 Digital Link format
-        if (ownGtin) {
+        // 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 {

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.22  |  Generated: 2026-08-27T17:34:12.788Z
 
 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,11 @@ 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
 }
 ```
 

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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.15.21",
+  "version": "1.15.22",
   "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",