@proveanything/smartlinks 1.8.5 → 1.8.7

package/dist/api/appConfiguration.d.ts

@@ -17,11 +17,18 @@ export type AppConfigOptions = {
     batchId?: string;
     /** Item ID - required for getDataItem/deleteDataItem */
     itemId?: string;
-    /** Use admin endpoints instead of public */
+    /**
+     * Use admin endpoints instead of public.
+     * This selects which endpoint is called; it does not by itself make root-level config fields private.
+     */
     admin?: boolean;
-    /** Configuration object for setConfig */
+    /**
+     * Configuration object for setConfig.
+     * For admin-only values in app config, store them under a top-level `admin` object.
+     * Public reads return the root config but omit `config.admin`.
+     */
     config?: any;
-    /** Data object for setDataItem */
+    /** Data object for setDataItem. Best for small keyed scoped documents rather than richer app domain objects. */
     data?: any;
 };
 /**
@@ -152,6 +159,8 @@ export declare namespace userAppData {
 /**
  * Collection/Product-scoped app configuration.
  * This is admin-managed configuration that applies to all users within the scope.
+ * Root-level config fields are typically part of the public view; if you need admin-only
+ * values, store them under a top-level `admin` object so public reads can omit them.
  *
  * @example
  * ```typescript
@@ -180,7 +189,10 @@ export declare namespace userAppData {
  */
 export declare namespace appConfiguration {
     /**
-     * Get app configuration for a collection/product scope.
+    * Get app configuration for a collection/product scope.
+    * Public reads return the public view of the config. If the stored config contains a
+    * top-level `admin` object, that block is omitted from public responses and included
+    * when `opts.admin === true`.
      *
      * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
      * @returns The configuration object
@@ -228,8 +240,10 @@ export declare namespace appConfiguration {
      */
     function listWidgetInstances(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>): Promise<WidgetInstanceSummary[]>;
     /**
-     * Set app configuration for a collection/product scope.
-     * Requires admin authentication.
+    * Set app configuration for a collection/product scope.
+    * Requires admin authentication.
+    * Writing through the admin endpoint does not make every root-level field private.
+    * Use `config.admin` for confidential values that should only be returned on admin reads.
      *
      * @param opts - Configuration options including appId, scope, and config data
      * @returns The saved configuration
@@ -262,7 +276,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
@@ -278,7 +298,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
@@ -295,8 +319,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
@@ -314,7 +345,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

@@ -200,6 +200,8 @@ export var userAppData;
 /**
  * Collection/Product-scoped app configuration.
  * This is admin-managed configuration that applies to all users within the scope.
+ * Root-level config fields are typically part of the public view; if you need admin-only
+ * values, store them under a top-level `admin` object so public reads can omit them.
  *
  * @example
  * ```typescript
@@ -229,7 +231,10 @@ export var userAppData;
 export var appConfiguration;
 (function (appConfiguration) {
     /**
-     * Get app configuration for a collection/product scope.
+    * Get app configuration for a collection/product scope.
+    * Public reads return the public view of the config. If the stored config contains a
+    * top-level `admin` object, that block is omitted from public responses and included
+    * when `opts.admin === true`.
      *
      * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
      * @returns The configuration object
@@ -309,8 +314,10 @@ export var appConfiguration;
     }
     appConfiguration.listWidgetInstances = listWidgetInstances;
     /**
-     * Set app configuration for a collection/product scope.
-     * Requires admin authentication.
+    * Set app configuration for a collection/product scope.
+    * Requires admin authentication.
+    * Writing through the admin endpoint does not make every root-level field private.
+    * Use `config.admin` for confidential values that should only be returned on admin reads.
      *
      * @param opts - Configuration options including appId, scope, and config data
      * @returns The saved configuration
@@ -351,7 +358,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
@@ -371,7 +384,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
@@ -394,8 +411,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
@@ -417,7 +441,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

package/dist/api/collection.d.ts

@@ -22,9 +22,13 @@ export declare namespace collection {
      */
     function getShortId(shortId: string): Promise<CollectionResponse>;
     /**
-     * Retrieve a specific settings group for a collection (public endpoint).
+     * Retrieve a specific settings group for a collection.
+     * Public reads return the public view of the settings group. If the stored payload contains
+     * a top-level `admin` object, that block is omitted from public responses and included when
+     * `admin === true`.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
+     * @param admin – If true, use the admin endpoint and include the admin-only settings block
      * @returns Promise resolving to the settings object
      */
     function getSettings(collectionId: string, settingGroup: string, admin?: boolean): Promise<any>;
@@ -37,6 +41,9 @@ export declare namespace collection {
     function getAppsConfig(collectionId: string): Promise<AppsConfigResponse>;
     /**
      * Update a specific settings group for a collection (admin endpoint).
+     * This writes through the admin endpoint, but root-level fields are still part of the public
+     * settings payload. Put confidential values under `settings.admin` if they should only be
+     * returned on admin reads.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
      * @param settings – The settings payload to persist

package/dist/api/collection.js

@@ -38,9 +38,13 @@ export var collection;
     }
     collection.getShortId = getShortId;
     /**
-     * Retrieve a specific settings group for a collection (public endpoint).
+     * Retrieve a specific settings group for a collection.
+     * Public reads return the public view of the settings group. If the stored payload contains
+     * a top-level `admin` object, that block is omitted from public responses and included when
+     * `admin === true`.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
+     * @param admin – If true, use the admin endpoint and include the admin-only settings block
      * @returns Promise resolving to the settings object
      */
     async function getSettings(collectionId, settingGroup, admin) {
@@ -62,6 +66,9 @@ export var collection;
     collection.getAppsConfig = getAppsConfig;
     /**
      * Update a specific settings group for a collection (admin endpoint).
+     * This writes through the admin endpoint, but root-level fields are still part of the public
+     * settings payload. Put confidential values under `settings.admin` if they should only be
+     * returned on admin reads.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
      * @param settings – The settings payload to persist