@proveanything/smartlinks 1.3.27 → 1.3.29

package/dist/api/appConfiguration.d.ts

@@ -1,3 +1,4 @@
+import { AppManifest } from "../types/appManifest";
 export type AppConfigOptions = {
     appId: string;
     collectionId?: string;
@@ -19,4 +20,30 @@ export declare namespace appConfiguration {
     function getDataItem(opts: AppConfigOptions): Promise<any>;
     function setDataItem(opts: AppConfigOptions): Promise<any>;
     function deleteDataItem(opts: AppConfigOptions): Promise<void>;
+    /**
+     * Fetches an app's manifest file through the proxy API.
+     * The manifest is cached on the server for 5 minutes.
+     *
+     * @param manifestUrl - The full URL to the manifest file (e.g., 'https://smartlinks.app/apps/my-app/v1.0.0/app.manifest.json')
+     * @param force - If true, bypasses cache and fetches fresh manifest
+     * @returns Promise resolving to the manifest object, or empty object if not found
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Use with appsConfig
+     * const appsConfig = await Api.Collection.Public.getAppsConfig(collectionId);
+     * const app = appsConfig.apps[0];
+     * if (app.manifestUrl) {
+     *   const manifest = await Api.AppConfiguration.getManifest(app.manifestUrl);
+     *   if (manifest.widgets) {
+     *     console.log('Available widgets:', manifest.widgets);
+     *   }
+     * }
+     *
+     * // Force refresh
+     * const freshManifest = await Api.AppConfiguration.getManifest(app.manifestUrl, true);
+     * ```
+     */
+    function getManifest(manifestUrl: string, force?: boolean): Promise<AppManifest>;
 }

package/dist/api/appConfiguration.js

@@ -88,4 +88,37 @@ export var appConfiguration;
         return del(path);
     }
     appConfiguration.deleteDataItem = deleteDataItem;
+    /**
+     * Fetches an app's manifest file through the proxy API.
+     * The manifest is cached on the server for 5 minutes.
+     *
+     * @param manifestUrl - The full URL to the manifest file (e.g., 'https://smartlinks.app/apps/my-app/v1.0.0/app.manifest.json')
+     * @param force - If true, bypasses cache and fetches fresh manifest
+     * @returns Promise resolving to the manifest object, or empty object if not found
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Use with appsConfig
+     * const appsConfig = await Api.Collection.Public.getAppsConfig(collectionId);
+     * const app = appsConfig.apps[0];
+     * if (app.manifestUrl) {
+     *   const manifest = await Api.AppConfiguration.getManifest(app.manifestUrl);
+     *   if (manifest.widgets) {
+     *     console.log('Available widgets:', manifest.widgets);
+     *   }
+     * }
+     *
+     * // Force refresh
+     * const freshManifest = await Api.AppConfiguration.getManifest(app.manifestUrl, true);
+     * ```
+     */
+    async function getManifest(manifestUrl, force) {
+        let path = `/public/app/manifest?url=${encodeURIComponent(manifestUrl)}`;
+        if (force) {
+            path += '&force=true';
+        }
+        return request(path);
+    }
+    appConfiguration.getManifest = getManifest;
 })(appConfiguration || (appConfiguration = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.27  |  Generated: 2026-02-14T12:01:11.475Z
+Version: 1.3.29  |  Generated: 2026-02-14T14:15:49.096Z
 
 This is a concise summary of all available API functions and types.
 
@@ -791,6 +791,88 @@ interface AppConfigurationResponse {
 }
 ```
 
+### appManifest
+
+**AppManifest** (interface)
+```typescript
+interface AppManifest {
+  $schema?: string;
+  meta?: {
+  name: string;
+  description?: string;
+  version: string;
+  platformRevision?: string;
+  appId: string;
+  };
+  widgets?: Array<{
+  name: string;
+  description?: string;
+  sizes?: string[];
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+  }>;
+  setup?: {
+  description?: string;
+  questions?: Array<{
+  id: string;
+  prompt: string;
+  type: string;
+  default?: any;
+  required?: boolean;
+  }>;
+  configSchema?: Record<string, any>;
+  saveWith?: {
+  method: string;
+  scope: string;
+  admin?: boolean;
+  };
+  contentHints?: Record<string, {
+  aiGenerate?: boolean;
+  prompt?: string;
+  }>;
+  };
+  import?: {
+  description?: string;
+  scope?: string;
+  fields?: Array<{
+  name: string;
+  type: string;
+  required?: boolean;
+  default?: any;
+  description?: string;
+  }>;
+  csvExample?: string;
+  saveWith?: {
+  method: string;
+  scope: string;
+  admin?: boolean;
+  note?: string;
+  };
+  };
+  tunable?: {
+  description?: string;
+  fields?: Array<{
+  name: string;
+  description?: string;
+  type: string;
+  }>;
+  };
+  metrics?: {
+  interactions?: Array<{
+  id: string;
+  description?: string;
+  }>;
+  kpis?: Array<{
+  name: string;
+  compute?: string;
+  }>;
+  };
+  [key: string]: any; // Allow additional custom fields
+}
+```
+
 ### asset
 
 **Asset** (interface)
@@ -1394,6 +1476,7 @@ interface AppConfig {
   ownersOnly?: boolean
   hidden?: boolean
   publicIframeUrl?: string
+  manifestUrl?: string
   supportsDeepLinks?: boolean;
   usage: {
   collection: boolean;  // use at the collecton level
@@ -3824,6 +3907,9 @@ Post a chat message to the AI (admin or public)
 
 **deleteDataItem**(opts: AppConfigOptions) → `Promise<void>`
 
+**getManifest**(manifestUrl: string, force?: boolean) → `Promise<AppManifest>`
+Fetches an app's manifest file through the proxy API. The manifest is cached on the server for 5 minutes. ```typescript // Use with appsConfig const appsConfig = await Api.Collection.Public.getAppsConfig(collectionId); const app = appsConfig.apps[0]; if (app.manifestUrl) { const manifest = await Api.AppConfiguration.getManifest(app.manifestUrl); if (manifest.widgets) { console.log('Available widgets:', manifest.widgets); } } // Force refresh const freshManifest = await Api.AppConfiguration.getManifest(app.manifestUrl, true); ```
+
 ### appRecord
 
 **get**(collectionId: string, appId: string) → `Promise<any>`

package/dist/docs/utils.md

@@ -12,40 +12,46 @@ import { utils } from '@proveanything/smartlinks'
 
 ## Path Builder Utility
 
-Pass in objects (collection, product, batch, etc.) and the function extracts what it needs to build portal URLs.
+Builds full portal URLs by default. Pass in objects (collection, product, batch, etc.) and the function extracts what it needs. Uses `collection.portalUrl` as the domain, or defaults to `https://zt.smartlinks.io`.
 
 ### Basic Usage
 
-Pass objects where you have them, or just IDs for simpler cases:
-
 ```typescript
-import { utils } from '@evrythng/smartlinks'
+import { utils } from '@proveanything/smartlinks'
 
-// Pass objects - extracts shortId, portalUrl, product ID, GTIN, ownGtin
-const path = utils.buildPortalPath({
-  collection: myCollection,
+// Returns full URL by default (uses collection.portalUrl)
+const url = utils.buildPortalPath({
+  collection: myCollection,  // uses collection.portalUrl or default domain
   product: myProduct  // ownGtin is read from product, not overridden
 })
 // Returns: https://portal.smartlinks.io/c/abc123/prod123
 
+// Return just the path (no domain)
+const path = utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1',
+  pathOnly: true  // Set to true for path only
+})
+// Returns: /c/abc123/prod1
+
 // Or just IDs if you don't have full objects
-const path2 = utils.buildPortalPath({
+const url2 = utils.buildPortalPath({
   collection: { shortId: 'abc123' },
   productId: 'prod1'
 })
-// Returns: /c/abc123/prod1
+// Returns: https://zt.smartlinks.io/c/abc123/prod1 (default domain)
 ```
 
 ## Path Builder Function
 
 ### `buildPortalPath(params)`
 
-Builds a portal path/URL based on the provided parameters.
+Builds a full portal URL based on the provided parameters. Returns full URL by default using `collection.portalUrl` or `https://zt.smartlinks.io`.
 
 **Parameters:**
 
 - `collection` (required) - Collection object or `{ shortId: string, portalUrl?: string }`  
-  Extracts: `shortId` and optional `portalUrl` for base URL
+  Extracts: `shortId` and optional `portalUrl` for base domain
   
 - `product` (optional) - Full product object  
   Extracts: `id`, `gtin`, and `ownGtin` (ownGtin is a critical product setting - read only, never overridden)
@@ -69,6 +75,9 @@ Builds a portal path/URL based on the provided parameters.
   
 - `queryParams` (optional) - Additional query parameters object
 
+- `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`
+
 **Path Formats:**
 
 - Basic product: `/c/{shortId}/{productId}`
@@ -80,16 +89,23 @@ Builds a portal path/URL based on the provided parameters.
 
 ## Examples
 
-### Pass Objects
+### Full URL (Default Behavior)
 
 ```typescript
-// Collection and product objects
+// Returns full URL using collection.portalUrl
 utils.buildPortalPath({
-  collection: myCollection,  // extracts shortId and portalUrl
-  product: myProduct  // extracts id, gtin, ownGtin (if present)
+  collection: myCollection,  // uses collection.portalUrl
+  product: myProduct
 })
 // Returns: https://portal.smartlinks.io/c/abc123/prod123
 
+// Without portalUrl, uses default domain
+utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1'
+})
+// Returns: https://zt.smartlinks.io/c/abc123/prod1
+
 // With proof object
 utils.buildPortalPath({
   collection: myCollection,
@@ -99,6 +115,27 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123/proof789
 ```
 
+### Path Only (No Domain)
+
+```typescript
+// Set pathOnly: true to get just the path
+utils.buildPortalPath({
+  collection: myCollection,
+  product: myProduct,
+  pathOnly: true
+})
+// Returns: /c/abc123/prod123
+
+// Useful when you need to build your own full URL
+const path = utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1',
+  pathOnly: true
+})
+const customUrl = `https://mycustomdomain.com${path}`
+// Result: https://mycustomdomain.com/c/abc123/prod1
+```
+
 ### GTIN Paths
 
 ```typescript
@@ -172,19 +209,6 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123?utm_source=email&utm_campaign=launch&lang=fr
 ```
 
-### Just IDs (No Full Objects)
-
-```typescript
-// Minimal - just IDs
-utils.buildPortalPath({
-  collection: { shortId: 'abc123' },
-  productId: 'prod1',
-  batchId: 'batch1',
-  variant: 'var1'
-})
-// Returns: /c/abc123/prod1
-```
-
 ## Use Cases
 
 ### QR Code Generation

package/dist/types/appManifest.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SmartLinks App Manifest structure
+ * Defines the configuration, widgets, setup, import, and metrics for a microapp
+ */
+export interface AppManifest {
+    $schema?: string;
+    meta?: {
+        name: string;
+        description?: string;
+        version: string;
+        platformRevision?: string;
+        appId: string;
+    };
+    widgets?: Array<{
+        name: string;
+        description?: string;
+        sizes?: string[];
+        props?: {
+            required?: string[];
+            optional?: string[];
+        };
+    }>;
+    setup?: {
+        description?: string;
+        questions?: Array<{
+            id: string;
+            prompt: string;
+            type: string;
+            default?: any;
+            required?: boolean;
+        }>;
+        configSchema?: Record<string, any>;
+        saveWith?: {
+            method: string;
+            scope: string;
+            admin?: boolean;
+        };
+        contentHints?: Record<string, {
+            aiGenerate?: boolean;
+            prompt?: string;
+        }>;
+    };
+    import?: {
+        description?: string;
+        scope?: string;
+        fields?: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+            default?: any;
+            description?: string;
+        }>;
+        csvExample?: string;
+        saveWith?: {
+            method: string;
+            scope: string;
+            admin?: boolean;
+            note?: string;
+        };
+    };
+    tunable?: {
+        description?: string;
+        fields?: Array<{
+            name: string;
+            description?: string;
+            type: string;
+        }>;
+    };
+    metrics?: {
+        interactions?: Array<{
+            id: string;
+            description?: string;
+        }>;
+        kpis?: Array<{
+            name: string;
+            compute?: string;
+        }>;
+    };
+    [key: string]: any;
+}

package/dist/types/appManifest.js

@@ -0,0 +1,2 @@
+// src/types/appManifest.ts
+export {};

package/dist/types/collection.d.ts

@@ -91,6 +91,8 @@ export interface AppConfig {
     hidden?: boolean;
     /** Universal iframe URL for external embedding */
     publicIframeUrl?: string;
+    /** Where to get the app manifest for AI and widget definitions */
+    manifestUrl?: string;
     /** supports multiple pages / deep links into the app */
     supportsDeepLinks?: boolean;
     /** App component configuration */

package/dist/types/index.d.ts

@@ -27,3 +27,4 @@ export * from "./order";
 export * from "./crate";
 export * from "./iframeResponder";
 export * from "./ai";
+export * from "./appManifest";

package/dist/types/index.js

@@ -29,3 +29,4 @@ export * from "./order";
 export * from "./crate";
 export * from "./iframeResponder";
 export * from "./ai";
+export * from "./appManifest";

package/dist/utils/paths.d.ts

@@ -28,10 +28,15 @@ export interface PortalPathParams {
     proof?: Proof | string;
     /** Additional query parameters */
     queryParams?: Record<string, string>;
+    /** Return only the path without domain (default: false, returns full URL) */
+    pathOnly?: boolean;
 }
 /**
  * Builds a portal path/URL based on the provided parameters.
  *
+ * Returns a full URL by default using collection.portalUrl or the default smartlinks domain.
+ * Set pathOnly: true to return just the path without the domain.
+ *
  * Pass in objects where available (collection, product, batch, etc.) and the function
  * will extract the needed properties. You can also pass just IDs if you don't have the full objects.
  *
@@ -44,17 +49,25 @@ export interface PortalPathParams {
  * - With variant: adds `/22/{variantId}`
  *
  * @param params - Path parameters
- * @returns The built portal path or URL
+ * @returns The built portal URL (default) or path (if pathOnly: true)
  *
  * @example
  * ```typescript
- * // Basic product path (pass objects)
+ * // Returns full URL by default
  * buildPortalPath({
- *   collection: myCollection,
- *   product: myProduct  // reads ownGtin from product if present
+ *   collection: myCollection,  // uses collection.portalUrl
+ *   product: myProduct
  * })
  * // Returns: https://portal.smartlinks.io/c/abc123/prod1
  *
+ * // Return just the path
+ * buildPortalPath({
+ *   collection: myCollection,
+ *   product: myProduct,
+ *   pathOnly: true
+ * })
+ * // Returns: /c/abc123/prod1
+ *
  * // GTIN path (ownGtin read from product)
  * buildPortalPath({
  *   collection: myCollection,
@@ -68,7 +81,7 @@ export interface PortalPathParams {
  *   product: myProduct,
  *   batch: myBatch  // extracts id and expiryDate
  * })
- * // Returns: /01/1234567890123/10/batch1?17=260630
+ * // Returns: https://portal.smartlinks.io/01/1234567890123/10/batch1?17=260630
  *
  * // Or just pass IDs
  * buildPortalPath({
@@ -76,7 +89,7 @@ export interface PortalPathParams {
  *   productId: 'prod1',
  *   batchId: 'batch1'  // just the ID, no expiry
  * })
- * // Returns: /c/abc123/prod1
+ * // Returns: https://smartlinks.app/c/abc123/prod1
  * ```
  */
 export declare function buildPortalPath(params: PortalPathParams): string;

package/dist/utils/paths.js

@@ -1,6 +1,9 @@
 /**
  * Builds a portal path/URL based on the provided parameters.
  *
+ * Returns a full URL by default using collection.portalUrl or the default smartlinks domain.
+ * Set pathOnly: true to return just the path without the domain.
+ *
  * Pass in objects where available (collection, product, batch, etc.) and the function
  * will extract the needed properties. You can also pass just IDs if you don't have the full objects.
  *
@@ -13,17 +16,25 @@
  * - With variant: adds `/22/{variantId}`
  *
  * @param params - Path parameters
- * @returns The built portal path or URL
+ * @returns The built portal URL (default) or path (if pathOnly: true)
  *
  * @example
  * ```typescript
- * // Basic product path (pass objects)
+ * // Returns full URL by default
  * buildPortalPath({
- *   collection: myCollection,
- *   product: myProduct  // reads ownGtin from product if present
+ *   collection: myCollection,  // uses collection.portalUrl
+ *   product: myProduct
  * })
  * // Returns: https://portal.smartlinks.io/c/abc123/prod1
  *
+ * // Return just the path
+ * buildPortalPath({
+ *   collection: myCollection,
+ *   product: myProduct,
+ *   pathOnly: true
+ * })
+ * // Returns: /c/abc123/prod1
+ *
  * // GTIN path (ownGtin read from product)
  * buildPortalPath({
  *   collection: myCollection,
@@ -37,7 +48,7 @@
  *   product: myProduct,
  *   batch: myBatch  // extracts id and expiryDate
  * })
- * // Returns: /01/1234567890123/10/batch1?17=260630
+ * // Returns: https://portal.smartlinks.io/01/1234567890123/10/batch1?17=260630
  *
  * // Or just pass IDs
  * buildPortalPath({
@@ -45,11 +56,11 @@
  *   productId: 'prod1',
  *   batchId: 'batch1'  // just the ID, no expiry
  * })
- * // Returns: /c/abc123/prod1
+ * // Returns: https://smartlinks.app/c/abc123/prod1
  * ```
  */
 export function buildPortalPath(params) {
-    const { collection, product, productId, batch, batchId, variant, proof, queryParams = {} } = params;
+    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;
@@ -138,11 +149,14 @@ export function buildPortalPath(params) {
     // Build final URL
     const queryString = searchParams.toString();
     const fullPath = pathname + (queryString ? `?${queryString}` : '');
-    if (baseUrl) {
-        const cleanBaseUrl = baseUrl.replace(/\/$/, '');
-        return cleanBaseUrl + fullPath;
+    // Return path only if requested
+    if (pathOnly) {
+        return fullPath;
     }
-    return fullPath;
+    // Return full URL using collection.portalUrl or default domain
+    const domain = baseUrl || 'https://smartlinks.app';
+    const cleanDomain = domain.replace(/\/$/, '');
+    return cleanDomain + fullPath;
 }
 /**
  * Formats an expiry date to YYMMDD format.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.27  |  Generated: 2026-02-14T12:01:11.475Z
+Version: 1.3.29  |  Generated: 2026-02-14T14:15:49.096Z
 
 This is a concise summary of all available API functions and types.
 
@@ -791,6 +791,88 @@ interface AppConfigurationResponse {
 }
 ```
 
+### appManifest
+
+**AppManifest** (interface)
+```typescript
+interface AppManifest {
+  $schema?: string;
+  meta?: {
+  name: string;
+  description?: string;
+  version: string;
+  platformRevision?: string;
+  appId: string;
+  };
+  widgets?: Array<{
+  name: string;
+  description?: string;
+  sizes?: string[];
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+  }>;
+  setup?: {
+  description?: string;
+  questions?: Array<{
+  id: string;
+  prompt: string;
+  type: string;
+  default?: any;
+  required?: boolean;
+  }>;
+  configSchema?: Record<string, any>;
+  saveWith?: {
+  method: string;
+  scope: string;
+  admin?: boolean;
+  };
+  contentHints?: Record<string, {
+  aiGenerate?: boolean;
+  prompt?: string;
+  }>;
+  };
+  import?: {
+  description?: string;
+  scope?: string;
+  fields?: Array<{
+  name: string;
+  type: string;
+  required?: boolean;
+  default?: any;
+  description?: string;
+  }>;
+  csvExample?: string;
+  saveWith?: {
+  method: string;
+  scope: string;
+  admin?: boolean;
+  note?: string;
+  };
+  };
+  tunable?: {
+  description?: string;
+  fields?: Array<{
+  name: string;
+  description?: string;
+  type: string;
+  }>;
+  };
+  metrics?: {
+  interactions?: Array<{
+  id: string;
+  description?: string;
+  }>;
+  kpis?: Array<{
+  name: string;
+  compute?: string;
+  }>;
+  };
+  [key: string]: any; // Allow additional custom fields
+}
+```
+
 ### asset
 
 **Asset** (interface)
@@ -1394,6 +1476,7 @@ interface AppConfig {
   ownersOnly?: boolean
   hidden?: boolean
   publicIframeUrl?: string
+  manifestUrl?: string
   supportsDeepLinks?: boolean;
   usage: {
   collection: boolean;  // use at the collecton level
@@ -3824,6 +3907,9 @@ Post a chat message to the AI (admin or public)
 
 **deleteDataItem**(opts: AppConfigOptions) → `Promise<void>`
 
+**getManifest**(manifestUrl: string, force?: boolean) → `Promise<AppManifest>`
+Fetches an app's manifest file through the proxy API. The manifest is cached on the server for 5 minutes. ```typescript // Use with appsConfig const appsConfig = await Api.Collection.Public.getAppsConfig(collectionId); const app = appsConfig.apps[0]; if (app.manifestUrl) { const manifest = await Api.AppConfiguration.getManifest(app.manifestUrl); if (manifest.widgets) { console.log('Available widgets:', manifest.widgets); } } // Force refresh const freshManifest = await Api.AppConfiguration.getManifest(app.manifestUrl, true); ```
+
 ### appRecord
 
 **get**(collectionId: string, appId: string) → `Promise<any>`

package/docs/utils.md

@@ -12,40 +12,46 @@ import { utils } from '@proveanything/smartlinks'
 
 ## Path Builder Utility
 
-Pass in objects (collection, product, batch, etc.) and the function extracts what it needs to build portal URLs.
+Builds full portal URLs by default. Pass in objects (collection, product, batch, etc.) and the function extracts what it needs. Uses `collection.portalUrl` as the domain, or defaults to `https://zt.smartlinks.io`.
 
 ### Basic Usage
 
-Pass objects where you have them, or just IDs for simpler cases:
-
 ```typescript
-import { utils } from '@evrythng/smartlinks'
+import { utils } from '@proveanything/smartlinks'
 
-// Pass objects - extracts shortId, portalUrl, product ID, GTIN, ownGtin
-const path = utils.buildPortalPath({
-  collection: myCollection,
+// Returns full URL by default (uses collection.portalUrl)
+const url = utils.buildPortalPath({
+  collection: myCollection,  // uses collection.portalUrl or default domain
   product: myProduct  // ownGtin is read from product, not overridden
 })
 // Returns: https://portal.smartlinks.io/c/abc123/prod123
 
+// Return just the path (no domain)
+const path = utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1',
+  pathOnly: true  // Set to true for path only
+})
+// Returns: /c/abc123/prod1
+
 // Or just IDs if you don't have full objects
-const path2 = utils.buildPortalPath({
+const url2 = utils.buildPortalPath({
   collection: { shortId: 'abc123' },
   productId: 'prod1'
 })
-// Returns: /c/abc123/prod1
+// Returns: https://zt.smartlinks.io/c/abc123/prod1 (default domain)
 ```
 
 ## Path Builder Function
 
 ### `buildPortalPath(params)`
 
-Builds a portal path/URL based on the provided parameters.
+Builds a full portal URL based on the provided parameters. Returns full URL by default using `collection.portalUrl` or `https://zt.smartlinks.io`.
 
 **Parameters:**
 
 - `collection` (required) - Collection object or `{ shortId: string, portalUrl?: string }`  
-  Extracts: `shortId` and optional `portalUrl` for base URL
+  Extracts: `shortId` and optional `portalUrl` for base domain
   
 - `product` (optional) - Full product object  
   Extracts: `id`, `gtin`, and `ownGtin` (ownGtin is a critical product setting - read only, never overridden)
@@ -69,6 +75,9 @@ Builds a portal path/URL based on the provided parameters.
   
 - `queryParams` (optional) - Additional query parameters object
 
+- `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`
+
 **Path Formats:**
 
 - Basic product: `/c/{shortId}/{productId}`
@@ -80,16 +89,23 @@ Builds a portal path/URL based on the provided parameters.
 
 ## Examples
 
-### Pass Objects
+### Full URL (Default Behavior)
 
 ```typescript
-// Collection and product objects
+// Returns full URL using collection.portalUrl
 utils.buildPortalPath({
-  collection: myCollection,  // extracts shortId and portalUrl
-  product: myProduct  // extracts id, gtin, ownGtin (if present)
+  collection: myCollection,  // uses collection.portalUrl
+  product: myProduct
 })
 // Returns: https://portal.smartlinks.io/c/abc123/prod123
 
+// Without portalUrl, uses default domain
+utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1'
+})
+// Returns: https://zt.smartlinks.io/c/abc123/prod1
+
 // With proof object
 utils.buildPortalPath({
   collection: myCollection,
@@ -99,6 +115,27 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123/proof789
 ```
 
+### Path Only (No Domain)
+
+```typescript
+// Set pathOnly: true to get just the path
+utils.buildPortalPath({
+  collection: myCollection,
+  product: myProduct,
+  pathOnly: true
+})
+// Returns: /c/abc123/prod123
+
+// Useful when you need to build your own full URL
+const path = utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1',
+  pathOnly: true
+})
+const customUrl = `https://mycustomdomain.com${path}`
+// Result: https://mycustomdomain.com/c/abc123/prod1
+```
+
 ### GTIN Paths
 
 ```typescript
@@ -172,19 +209,6 @@ utils.buildPortalPath({
 // Returns: https://portal.smartlinks.io/c/abc123/prod123?utm_source=email&utm_campaign=launch&lang=fr
 ```
 
-### Just IDs (No Full Objects)
-
-```typescript
-// Minimal - just IDs
-utils.buildPortalPath({
-  collection: { shortId: 'abc123' },
-  productId: 'prod1',
-  batchId: 'batch1',
-  variant: 'var1'
-})
-// Returns: /c/abc123/prod1
-```
-
 ## Use Cases
 
 ### QR Code Generation

package/package.json

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