@proveanything/smartlinks 1.8.4 → 1.8.6

package/dist/api/appConfiguration.d.ts

@@ -1,4 +1,5 @@
 import { CollectionWidgetsResponse, GetCollectionWidgetsOptions } from "../types/appManifest";
+import type { GetWidgetInstanceOptions, WidgetInstance, WidgetInstanceSummary } from "../types/appConfiguration";
 /**
  * Options for collection/product-scoped app configuration.
  * This data is set by admins and applies to all users within the scope.
@@ -20,7 +21,7 @@ export type AppConfigOptions = {
     admin?: boolean;
     /** Configuration object for setConfig */
     config?: any;
-    /** Data object for setDataItem */
+    /** Data object for setDataItem. Best for small keyed scoped documents rather than richer app domain objects. */
     data?: any;
 };
 /**
@@ -193,6 +194,39 @@ export declare namespace appConfiguration {
      * ```
      */
     function getConfig(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Resolve a configured widget instance by ID from an app's stored config.
+     * This is a thin convenience wrapper over `getConfig()` that reads `config.widgets[widgetId]`.
+     *
+     * @param opts - Scope options plus the widget instance ID
+     * @returns The configured widget instance
+     *
+     * @example
+     * ```typescript
+     * const widget = await appConfiguration.getWidgetInstance({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit',
+     *   widgetId: 'launch-countdown'
+     * })
+     * ```
+     */
+    function getWidgetInstance<TWidget = any>(opts: GetWidgetInstanceOptions): Promise<WidgetInstance<TWidget>>;
+    /**
+     * List configured widget instances for an app.
+     * Useful for picker UIs, setup schemas, and widget-to-widget references.
+     *
+     * @param opts - App config scope options
+     * @returns Array of widget instance summaries
+     *
+     * @example
+     * ```typescript
+     * const widgets = await appConfiguration.listWidgetInstances({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit'
+     * })
+     * ```
+     */
+    function listWidgetInstances(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>): Promise<WidgetInstanceSummary[]>;
     /**
      * Set app configuration for a collection/product scope.
      * Requires admin authentication.
@@ -228,7 +262,13 @@ export declare namespace appConfiguration {
      */
     function deleteConfig(opts: AppConfigOptions): Promise<void>;
     /**
-     * Get all data items for an app within a scope.
+      * Get all keyed data items for an app within a scope.
+      * Best for a small set of standalone documents such as FAQs, menus, lookup tables,
+      * or content fragments where the caller typically knows the item IDs.
+      *
+      * If you are modelling richer app entities that need filtering, lifecycle fields,
+      * visibility, ownership, or relationships, prefer `app.records`, `app.cases`,
+      * or `app.threads` instead.
      *
      * @param opts - Options including appId and scope (collectionId, productId, etc.)
      * @returns Array of data items
@@ -244,7 +284,11 @@ export declare namespace appConfiguration {
      */
     function getData(opts: AppConfigOptions): Promise<any[]>;
     /**
-     * Get a single data item by ID within a scope.
+      * Get a single keyed data item by ID within a scope.
+      * This is ideal when you already know the exact ID of a simple scoped document.
+      *
+      * For richer domain objects that users browse or query, prefer `app.records`,
+      * `app.cases`, or `app.threads`.
      *
      * @param opts - Options including appId, scope, and itemId
      * @returns The data item
@@ -261,8 +305,15 @@ export declare namespace appConfiguration {
      */
     function getDataItem(opts: AppConfigOptions): Promise<any>;
     /**
-     * Set/create a data item within a scope.
+      * Set/create a keyed data item within a scope.
      * Requires admin authentication.
+      *
+      * Use this for simple scoped documents attached to a collection/product/variant/batch,
+      * especially when you want a small number of items with stable IDs.
+      *
+      * Do not treat this as the default write path for every app-owned entity. If the data
+      * starts behaving like a real object with lifecycle, filtering, visibility, ownership,
+      * history, or relationships, prefer `app.records`, `app.cases`, or `app.threads`.
      *
      * @param opts - Options including appId, scope, and data
      * @returns The saved data item
@@ -280,7 +331,7 @@ export declare namespace appConfiguration {
      */
     function setDataItem(opts: AppConfigOptions): Promise<any>;
     /**
-     * Delete a data item by ID within a scope.
+      * Delete a keyed data item by ID within a scope.
      * Requires admin authentication.
      *
      * @param opts - Options including appId, scope, and itemId

package/dist/api/appConfiguration.js

@@ -1,5 +1,24 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 // src/api/appConfiguration.ts
 import { request, post, del } from "../http";
+function getWidgetsMap(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return {};
+    const widgets = config.widgets;
+    if (!widgets || typeof widgets !== 'object' || Array.isArray(widgets))
+        return {};
+    return widgets;
+}
 function buildAppPath(opts, type) {
     const base = opts.admin ? "admin" : "public";
     let path = `/${base}`;
@@ -228,6 +247,67 @@ export var appConfiguration;
         return request(path);
     }
     appConfiguration.getConfig = getConfig;
+    /**
+     * Resolve a configured widget instance by ID from an app's stored config.
+     * This is a thin convenience wrapper over `getConfig()` that reads `config.widgets[widgetId]`.
+     *
+     * @param opts - Scope options plus the widget instance ID
+     * @returns The configured widget instance
+     *
+     * @example
+     * ```typescript
+     * const widget = await appConfiguration.getWidgetInstance({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit',
+     *   widgetId: 'launch-countdown'
+     * })
+     * ```
+     */
+    async function getWidgetInstance(opts) {
+        const { widgetId } = opts, configOpts = __rest(opts, ["widgetId"]);
+        const config = await getConfig(configOpts);
+        const widgets = getWidgetsMap(config);
+        const instance = widgets[widgetId];
+        if (!instance || typeof instance !== 'object' || Array.isArray(instance)) {
+            throw new Error(`Widget instance \"${widgetId}\" not found for app \"${opts.appId}\"`);
+        }
+        return instance;
+    }
+    appConfiguration.getWidgetInstance = getWidgetInstance;
+    /**
+     * List configured widget instances for an app.
+     * Useful for picker UIs, setup schemas, and widget-to-widget references.
+     *
+     * @param opts - App config scope options
+     * @returns Array of widget instance summaries
+     *
+     * @example
+     * ```typescript
+     * const widgets = await appConfiguration.listWidgetInstances({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit'
+     * })
+     * ```
+     */
+    async function listWidgetInstances(opts) {
+        const config = await getConfig(opts);
+        const widgets = getWidgetsMap(config);
+        return Object.entries(widgets).map(([id, instance]) => {
+            var _a;
+            const widgetInstance = instance && typeof instance === 'object' && !Array.isArray(instance)
+                ? instance
+                : {};
+            const resolvedId = typeof widgetInstance.id === 'string' && widgetInstance.id.trim()
+                ? widgetInstance.id
+                : id;
+            return Object.assign(Object.assign({}, widgetInstance), { id: resolvedId, name: typeof widgetInstance.name === 'string' && widgetInstance.name.trim()
+                    ? widgetInstance.name
+                    : resolvedId, type: typeof ((_a = widgetInstance.widget) === null || _a === void 0 ? void 0 : _a.type) === 'string'
+                    ? widgetInstance.widget.type
+                    : undefined });
+        });
+    }
+    appConfiguration.listWidgetInstances = listWidgetInstances;
     /**
      * Set app configuration for a collection/product scope.
      * Requires admin authentication.
@@ -271,7 +351,13 @@ export var appConfiguration;
     }
     appConfiguration.deleteConfig = deleteConfig;
     /**
-     * Get all data items for an app within a scope.
+      * Get all keyed data items for an app within a scope.
+      * Best for a small set of standalone documents such as FAQs, menus, lookup tables,
+      * or content fragments where the caller typically knows the item IDs.
+      *
+      * If you are modelling richer app entities that need filtering, lifecycle fields,
+      * visibility, ownership, or relationships, prefer `app.records`, `app.cases`,
+      * or `app.threads` instead.
      *
      * @param opts - Options including appId and scope (collectionId, productId, etc.)
      * @returns Array of data items
@@ -291,7 +377,11 @@ export var appConfiguration;
     }
     appConfiguration.getData = getData;
     /**
-     * Get a single data item by ID within a scope.
+      * Get a single keyed data item by ID within a scope.
+      * This is ideal when you already know the exact ID of a simple scoped document.
+      *
+      * For richer domain objects that users browse or query, prefer `app.records`,
+      * `app.cases`, or `app.threads`.
      *
      * @param opts - Options including appId, scope, and itemId
      * @returns The data item
@@ -314,8 +404,15 @@ export var appConfiguration;
     }
     appConfiguration.getDataItem = getDataItem;
     /**
-     * Set/create a data item within a scope.
+      * Set/create a keyed data item within a scope.
      * Requires admin authentication.
+      *
+      * Use this for simple scoped documents attached to a collection/product/variant/batch,
+      * especially when you want a small number of items with stable IDs.
+      *
+      * Do not treat this as the default write path for every app-owned entity. If the data
+      * starts behaving like a real object with lifecycle, filtering, visibility, ownership,
+      * history, or relationships, prefer `app.records`, `app.cases`, or `app.threads`.
      *
      * @param opts - Options including appId, scope, and data
      * @returns The saved data item
@@ -337,7 +434,7 @@ export var appConfiguration;
     }
     appConfiguration.setDataItem = setDataItem;
     /**
-     * Delete a data item by ID within a scope.
+      * Delete a keyed data item by ID within a scope.
      * Requires admin authentication.
      *
      * @param opts - Options including appId, scope, and itemId