@proveanything/smartlinks 1.3.28 → 1.3.30

package/dist/api/appConfiguration.d.ts

@@ -1,3 +1,4 @@
+import { AppManifest, CollectionWidgetsResponse, GetCollectionWidgetsOptions } from "../types/appManifest";
 export type AppConfigOptions = {
     appId: string;
     collectionId?: string;
@@ -19,4 +20,72 @@ 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>;
+    /**
+     * Fetches ALL widget data (manifests + bundle files) for a collection in one call.
+     * Returns everything needed to render widgets with zero additional requests.
+     *
+     * This is the recommended approach as it solves N+1 query problems and fetches
+     * manifests, JavaScript bundles, and CSS files in parallel on the server.
+     *
+     * @param collectionId - The collection ID
+     * @param options - Optional settings (force: bypass cache)
+     * @returns Promise resolving to collection widgets with manifests and bundle files
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch all widget data for a collection
+     * const { apps } = await Api.AppConfiguration.getCollectionWidgets(collectionId);
+     * // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...]
+     *
+     * // Convert bundle source to dynamic imports
+     * for (const app of apps) {
+     *   const blob = new Blob([app.bundleSource], { type: 'application/javascript' });
+     *   const blobUrl = URL.createObjectURL(blob);
+     *   const widgetModule = await import(blobUrl);
+     *
+     *   // Inject CSS if present
+     *   if (app.bundleCss) {
+     *     const styleTag = document.createElement('style');
+     *     styleTag.textContent = app.bundleCss;
+     *     document.head.appendChild(styleTag);
+     *   }
+     *
+     *   // Now use widgetModule components
+     * }
+     *
+     * // Force refresh all widgets
+     * const { apps: freshApps } = await Api.AppConfiguration.getCollectionWidgets(
+     *   collectionId,
+     *   { force: true }
+     * );
+     * ```
+     */
+    function getCollectionWidgets(collectionId: string, options?: GetCollectionWidgetsOptions): Promise<CollectionWidgetsResponse>;
 }

package/dist/api/appConfiguration.js

@@ -88,4 +88,86 @@ 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;
+    /**
+     * Fetches ALL widget data (manifests + bundle files) for a collection in one call.
+     * Returns everything needed to render widgets with zero additional requests.
+     *
+     * This is the recommended approach as it solves N+1 query problems and fetches
+     * manifests, JavaScript bundles, and CSS files in parallel on the server.
+     *
+     * @param collectionId - The collection ID
+     * @param options - Optional settings (force: bypass cache)
+     * @returns Promise resolving to collection widgets with manifests and bundle files
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch all widget data for a collection
+     * const { apps } = await Api.AppConfiguration.getCollectionWidgets(collectionId);
+     * // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...]
+     *
+     * // Convert bundle source to dynamic imports
+     * for (const app of apps) {
+     *   const blob = new Blob([app.bundleSource], { type: 'application/javascript' });
+     *   const blobUrl = URL.createObjectURL(blob);
+     *   const widgetModule = await import(blobUrl);
+     *
+     *   // Inject CSS if present
+     *   if (app.bundleCss) {
+     *     const styleTag = document.createElement('style');
+     *     styleTag.textContent = app.bundleCss;
+     *     document.head.appendChild(styleTag);
+     *   }
+     *
+     *   // Now use widgetModule components
+     * }
+     *
+     * // Force refresh all widgets
+     * const { apps: freshApps } = await Api.AppConfiguration.getCollectionWidgets(
+     *   collectionId,
+     *   { force: true }
+     * );
+     * ```
+     */
+    async function getCollectionWidgets(collectionId, options) {
+        let path = `/v1/public/collection/${encodeURIComponent(collectionId)}/widgets`;
+        if (options === null || options === void 0 ? void 0 : options.force) {
+            path += '?force=true';
+        }
+        return request(path);
+    }
+    appConfiguration.getCollectionWidgets = getCollectionWidgets;
 })(appConfiguration || (appConfiguration = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.28  |  Generated: 2026-02-14T12:11:55.083Z
+Version: 1.3.30  |  Generated: 2026-02-14T14:44:14.267Z
 
 This is a concise summary of all available API functions and types.
 
@@ -791,6 +791,113 @@ 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
+}
+```
+
+**CollectionWidget** (interface)
+```typescript
+interface CollectionWidget {
+  appId: string;
+  manifestUrl: string;
+  manifest: AppManifest;
+  bundleSource: string;
+  bundleCss?: string; // Optional CSS file
+}
+```
+
+**CollectionWidgetsResponse** (interface)
+```typescript
+interface CollectionWidgetsResponse {
+  apps: CollectionWidget[];
+}
+```
+
+**GetCollectionWidgetsOptions** (interface)
+```typescript
+interface GetCollectionWidgetsOptions {
+  force?: boolean; // Bypass cache and fetch fresh data
+}
+```
+
 ### asset
 
 **Asset** (interface)
@@ -1394,6 +1501,7 @@ interface AppConfig {
   ownersOnly?: boolean
   hidden?: boolean
   publicIframeUrl?: string
+  manifestUrl?: string
   supportsDeepLinks?: boolean;
   usage: {
   collection: boolean;  // use at the collecton level
@@ -3824,6 +3932,13 @@ 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); ```
+
+**getCollectionWidgets**(collectionId: string,
+    options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
+Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This is the recommended approach as it solves N+1 query problems and fetches manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getCollectionWidgets(collectionId); // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...] // Convert bundle source to dynamic imports for (const app of apps) { const blob = new Blob([app.bundleSource], { type: 'application/javascript' }); const blobUrl = URL.createObjectURL(blob); const widgetModule = await import(blobUrl); // Inject CSS if present if (app.bundleCss) { const styleTag = document.createElement('style'); styleTag.textContent = app.bundleCss; document.head.appendChild(styleTag); } // Now use widgetModule components } // Force refresh all widgets const { apps: freshApps } = await Api.AppConfiguration.getCollectionWidgets( collectionId, { force: true } ); ```
+
 ### appRecord
 
 **get**(collectionId: string, appId: string) → `Promise<any>`

package/dist/types/appManifest.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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;
+}
+/**
+ * Single app widget data with manifest and bundle files
+ */
+export interface CollectionWidget {
+    appId: string;
+    manifestUrl: string;
+    manifest: AppManifest;
+    bundleSource: string;
+    bundleCss?: string;
+}
+/**
+ * Response from collection widgets endpoint
+ */
+export interface CollectionWidgetsResponse {
+    apps: CollectionWidget[];
+}
+/**
+ * Options for fetching collection widgets
+ */
+export interface GetCollectionWidgetsOptions {
+    force?: boolean;
+}

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/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.28  |  Generated: 2026-02-14T12:11:55.083Z
+Version: 1.3.30  |  Generated: 2026-02-14T14:44:14.267Z
 
 This is a concise summary of all available API functions and types.
 
@@ -791,6 +791,113 @@ 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
+}
+```
+
+**CollectionWidget** (interface)
+```typescript
+interface CollectionWidget {
+  appId: string;
+  manifestUrl: string;
+  manifest: AppManifest;
+  bundleSource: string;
+  bundleCss?: string; // Optional CSS file
+}
+```
+
+**CollectionWidgetsResponse** (interface)
+```typescript
+interface CollectionWidgetsResponse {
+  apps: CollectionWidget[];
+}
+```
+
+**GetCollectionWidgetsOptions** (interface)
+```typescript
+interface GetCollectionWidgetsOptions {
+  force?: boolean; // Bypass cache and fetch fresh data
+}
+```
+
 ### asset
 
 **Asset** (interface)
@@ -1394,6 +1501,7 @@ interface AppConfig {
   ownersOnly?: boolean
   hidden?: boolean
   publicIframeUrl?: string
+  manifestUrl?: string
   supportsDeepLinks?: boolean;
   usage: {
   collection: boolean;  // use at the collecton level
@@ -3824,6 +3932,13 @@ 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); ```
+
+**getCollectionWidgets**(collectionId: string,
+    options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
+Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This is the recommended approach as it solves N+1 query problems and fetches manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getCollectionWidgets(collectionId); // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...] // Convert bundle source to dynamic imports for (const app of apps) { const blob = new Blob([app.bundleSource], { type: 'application/javascript' }); const blobUrl = URL.createObjectURL(blob); const widgetModule = await import(blobUrl); // Inject CSS if present if (app.bundleCss) { const styleTag = document.createElement('style'); styleTag.textContent = app.bundleCss; document.head.appendChild(styleTag); } // Now use widgetModule components } // Force refresh all widgets const { apps: freshApps } = await Api.AppConfiguration.getCollectionWidgets( collectionId, { force: true } ); ```
+
 ### appRecord
 
 **get**(collectionId: string, appId: string) → `Promise<any>`

package/package.json

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