@proveanything/smartlinks 1.8.6 → 1.8.7

package/dist/api/appConfiguration.d.ts

@@ -17,9 +17,16 @@ 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. 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

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

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

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.6  |  Generated: 2026-03-17T21:25:13.155Z
+Version: 1.8.7  |  Generated: 2026-03-18T08:55:08.708Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,16 @@ When you need flexible app-specific data, choose the storage model based on shap
 
 Rule of thumb: if you are modelling a real domain object that users will browse, filter, secure, or evolve over time, start with app objects. If you just need a simple keyed payload hanging off a collection or product, scoped data items are still a good fit.
 
+## Settings Visibility
+
+For `appConfiguration` config blobs and `collection` settings groups, keep endpoint choice separate from visibility semantics.
+
+- **`admin: true` means "use the admin endpoint"** for reads or writes.
+- **It does not make every root field private.** Writing through an admin endpoint still saves the normal shared payload.
+- **Root-level fields are the public/shared settings view.** Put public labels, colors, toggles, and general config there.
+- **Use a top-level `admin` object for confidential values.** Public reads omit that block; admin reads include it.
+- **Applies to both** `appConfiguration.getConfig` / `setConfig` **and** `collection.getSettings` / `updateSettings`.
+
 ## API Namespaces
 
 The Smartlinks SDK is organized into the following namespaces:
@@ -5834,10 +5844,17 @@ type AppConfigOptions = {
   /** 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. Best for small keyed scoped documents rather than richer app domain objects. */
   data?: any
@@ -6130,7 +6147,7 @@ Get aggregate statistics for threads POST /threads/aggregate
 Scoped config and keyed data items for collections, products, variants, or batches. Best for settings and small standalone documents, not as the default answer for every app-owned entity.
 
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
-Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
+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`. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
 **getWidgetInstance**(opts: GetWidgetInstanceOptions) → `Promise<WidgetInstance<TWidget>>`
 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]`. ```typescript const widget = await appConfiguration.getWidgetInstance({ collectionId: 'my-collection', appId: 'widget-toolkit', widgetId: 'launch-countdown' }) ```
@@ -6139,7 +6156,7 @@ Resolve a configured widget instance by ID from an app's stored config. This is
 List configured widget instances for an app. Useful for picker UIs, setup schemas, and widget-to-widget references. ```typescript const widgets = await appConfiguration.listWidgetInstances({ collectionId: 'my-collection', appId: 'widget-toolkit' }) ```
 
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
-Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
+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. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 
 **deleteConfig**(opts: AppConfigOptions) → `Promise<void>`
 Delete app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.deleteConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true }); ```
@@ -6614,13 +6631,13 @@ Retrieves all Collections.
 Retrieve a collection by its shortId (public endpoint).
 
 **getSettings**(collectionId: string, settingGroup: string, admin?: boolean) → `Promise<any>`
-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`.
 
 **getAppsConfig**(collectionId: string) → `Promise<AppsConfigResponse>`
 Retrieve all configured app module definitions for a collection (public endpoint).
 
 **updateSettings**(collectionId: string, settingGroup: string, settings: any) → `Promise<any>`
-Update a specific settings group for a collection (admin endpoint).
+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.
 
 **create**(data: CollectionCreateRequest) → `Promise<CollectionResponse>`
 Create a new collection (admin only).

package/dist/docs/ai-guide-template.md

@@ -199,6 +199,26 @@ await SL.appConfiguration.setConfig({
 });
 ```
 
+Important visibility rule for app settings:
+
+- `admin: true` means the SDK uses the admin endpoint.
+- It does not make every root field private.
+- If a value should only be visible to admins, put it under `config.admin`.
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    enableNotifications: true,
+    admin: {
+      apiToken: 'secret-token'
+    }
+  }
+})
+```
+
 ---
 
 ## Metrics & Analytics
@@ -228,6 +248,7 @@ await SL.appConfiguration.setConfig({
 | Issue                 | Cause                      | Fix                                                   |
 | --------------------- | -------------------------- | ----------------------------------------------------- |
 | Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| Secret visible publicly | Saved secret at root level | Put confidential values under the top-level `admin` object |
 | Widget doesn't render | Missing required props     | Ensure `collectionId`, `appId`, and `SL` are provided |
 | Import skips rows     | Invalid `productId`        | Verify product IDs exist in the collection            |
 | Theme not applied     | Missing `?theme=` param    | Check URL parameters or postMessage setup             |

package/dist/docs/app-data-storage.md

@@ -104,6 +104,49 @@ This data is scoped to specific collections, products, variants, or batches. It'
 
 If you need richer app-owned entities with querying, lifecycle, access zones, parent-child relationships, or workflow semantics, use [app-objects.md](app-objects.md) instead of forcing everything through `setDataItem`.
 
+### Critical: `admin: true` Controls the Endpoint, Not Field Privacy
+
+This is the part that often gets misunderstood by apps and AI tools:
+
+- `admin: true` means "call the admin endpoint".
+- It does **not** mean "everything I wrote is now admin-only".
+- For app config and collection settings, root-level fields are usually part of the public payload.
+- If you need confidential values, store them under a top-level `admin` object.
+- Public reads omit that `admin` block; admin reads include it.
+
+Example for app config:
+
+```typescript
+await appConfiguration.setConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true,
+  config: {
+    theme: 'gold',
+    supportEmail: 'support@example.com',
+    admin: {
+      accessToken: 'secret-token',
+      webhookSecret: 'top-secret'
+    }
+  }
+})
+
+const publicView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection'
+})
+// { theme: 'gold', supportEmail: 'support@example.com' }
+
+const adminView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true
+})
+// { theme: 'gold', supportEmail: 'support@example.com', admin: { ... } }
+```
+
+The same visibility pattern applies to collection settings via `collection.getSettings()` / `collection.updateSettings()`.
+
 ### Use Cases
 - App-specific settings for a collection
 - Product-level configuration
@@ -178,7 +221,7 @@ await appConfiguration.setDataItem({
 | **Shared across collections?** | ✅ Yes | ❌ No | ❌ No |
 | **Requires auth?** | ✅ Yes (user token) | ✅ Yes (admin token for write) | Depends on public/admin endpoint and visibility |
 | **Querying / filtering** | Minimal | Minimal | Strong |
-| **Access control zones** | User-scoped only | Scope only | `data` / `owner` / `admin` zones |
+| **Access control zones** | User-scoped only | Root fields + reserved `admin` block for settings/config | `data` / `owner` / `admin` zones |
 | **Admin write required?** | ❌ No | ✅ Yes (for write operations) | Only for admin endpoints / admin fields |
 
 ---

package/dist/docs/overview.md

@@ -140,6 +140,33 @@ await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig, adm
 
 This applies to all write operations: `setConfig`, `setDataItem`, `updateDataItem`, etc.
 
+### Endpoint Auth vs Data Visibility
+
+`admin: true` is an endpoint selector, not a privacy marker.
+
+- It tells the SDK to call the admin endpoint.
+- It allows writes and admin reads.
+- It does **not** mean every root-level field you save becomes admin-only.
+
+For `appConfiguration` config blobs and `collection.getSettings()` groups, root-level fields are typically the public-facing settings. If you need private values such as tokens or secrets, store them inside a top-level `admin` object:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    publicLabel: 'Warranty Portal',
+    color: '#B68C2A',
+    admin: {
+      accessToken: 'secret-token'
+    }
+  }
+})
+```
+
+Public reads omit the `admin` block. Admin reads include it.
+
 ### Config vs Data
 
 | Storage Type | Function | Use Case |
@@ -150,6 +177,8 @@ This applies to all write operations: `setConfig`, `setDataItem`, `updateDataIte
 
 Both can be scoped to **collection level** or **product level** by including `productId`.
 
+For config/settings visibility, remember: root fields are the normal shared payload, while a reserved top-level `admin` object is the place for admin-only values.
+
 Prefer `app.records` over `setDataItem` when the data is becoming a real entity that needs lifecycle, ownership, visibility, relationships, or filtering. Keep `setDataItem` for simple keyed scoped documents and config-adjacent content.
 
 ### Attestations (Proof-level data)

package/dist/openapi.yaml

@@ -79,7 +79,7 @@ paths:
     post:
       tags:
         - collection
-      summary: Update a specific settings group for a collection (admin endpoint).
+      summary: Create a new collection (admin only).
       operationId: collection_create
       security:
         - bearerAuth: []
@@ -5446,7 +5446,7 @@ paths:
     post:
       tags:
         - collection
-      summary: Retrieve all configured app module definitions for a collection (public endpoint).
+      summary: Update a specific settings group for a collection (admin endpoint).
       operationId: collection_updateSettings
       security:
         - bearerAuth: []
@@ -7080,7 +7080,7 @@ paths:
     get:
       tags:
         - collection
-      summary: Retrieve a specific settings group for a collection (public endpoint).
+      summary: Retrieve all configured app module definitions for a collection (public endpoint).
       operationId: collection_getAppsConfig
       security: []
       parameters:

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.6  |  Generated: 2026-03-17T21:25:13.155Z
+Version: 1.8.7  |  Generated: 2026-03-18T08:55:08.708Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,16 @@ When you need flexible app-specific data, choose the storage model based on shap
 
 Rule of thumb: if you are modelling a real domain object that users will browse, filter, secure, or evolve over time, start with app objects. If you just need a simple keyed payload hanging off a collection or product, scoped data items are still a good fit.
 
+## Settings Visibility
+
+For `appConfiguration` config blobs and `collection` settings groups, keep endpoint choice separate from visibility semantics.
+
+- **`admin: true` means "use the admin endpoint"** for reads or writes.
+- **It does not make every root field private.** Writing through an admin endpoint still saves the normal shared payload.
+- **Root-level fields are the public/shared settings view.** Put public labels, colors, toggles, and general config there.
+- **Use a top-level `admin` object for confidential values.** Public reads omit that block; admin reads include it.
+- **Applies to both** `appConfiguration.getConfig` / `setConfig` **and** `collection.getSettings` / `updateSettings`.
+
 ## API Namespaces
 
 The Smartlinks SDK is organized into the following namespaces:
@@ -5834,10 +5844,17 @@ type AppConfigOptions = {
   /** 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. Best for small keyed scoped documents rather than richer app domain objects. */
   data?: any
@@ -6130,7 +6147,7 @@ Get aggregate statistics for threads POST /threads/aggregate
 Scoped config and keyed data items for collections, products, variants, or batches. Best for settings and small standalone documents, not as the default answer for every app-owned entity.
 
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
-Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
+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`. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
 **getWidgetInstance**(opts: GetWidgetInstanceOptions) → `Promise<WidgetInstance<TWidget>>`
 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]`. ```typescript const widget = await appConfiguration.getWidgetInstance({ collectionId: 'my-collection', appId: 'widget-toolkit', widgetId: 'launch-countdown' }) ```
@@ -6139,7 +6156,7 @@ Resolve a configured widget instance by ID from an app's stored config. This is
 List configured widget instances for an app. Useful for picker UIs, setup schemas, and widget-to-widget references. ```typescript const widgets = await appConfiguration.listWidgetInstances({ collectionId: 'my-collection', appId: 'widget-toolkit' }) ```
 
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
-Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
+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. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 
 **deleteConfig**(opts: AppConfigOptions) → `Promise<void>`
 Delete app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.deleteConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true }); ```
@@ -6614,13 +6631,13 @@ Retrieves all Collections.
 Retrieve a collection by its shortId (public endpoint).
 
 **getSettings**(collectionId: string, settingGroup: string, admin?: boolean) → `Promise<any>`
-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`.
 
 **getAppsConfig**(collectionId: string) → `Promise<AppsConfigResponse>`
 Retrieve all configured app module definitions for a collection (public endpoint).
 
 **updateSettings**(collectionId: string, settingGroup: string, settings: any) → `Promise<any>`
-Update a specific settings group for a collection (admin endpoint).
+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.
 
 **create**(data: CollectionCreateRequest) → `Promise<CollectionResponse>`
 Create a new collection (admin only).

package/docs/ai-guide-template.md

@@ -199,6 +199,26 @@ await SL.appConfiguration.setConfig({
 });
 ```
 
+Important visibility rule for app settings:
+
+- `admin: true` means the SDK uses the admin endpoint.
+- It does not make every root field private.
+- If a value should only be visible to admins, put it under `config.admin`.
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    enableNotifications: true,
+    admin: {
+      apiToken: 'secret-token'
+    }
+  }
+})
+```
+
 ---
 
 ## Metrics & Analytics
@@ -228,6 +248,7 @@ await SL.appConfiguration.setConfig({
 | Issue                 | Cause                      | Fix                                                   |
 | --------------------- | -------------------------- | ----------------------------------------------------- |
 | Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| Secret visible publicly | Saved secret at root level | Put confidential values under the top-level `admin` object |
 | Widget doesn't render | Missing required props     | Ensure `collectionId`, `appId`, and `SL` are provided |
 | Import skips rows     | Invalid `productId`        | Verify product IDs exist in the collection            |
 | Theme not applied     | Missing `?theme=` param    | Check URL parameters or postMessage setup             |

package/docs/app-data-storage.md

@@ -104,6 +104,49 @@ This data is scoped to specific collections, products, variants, or batches. It'
 
 If you need richer app-owned entities with querying, lifecycle, access zones, parent-child relationships, or workflow semantics, use [app-objects.md](app-objects.md) instead of forcing everything through `setDataItem`.
 
+### Critical: `admin: true` Controls the Endpoint, Not Field Privacy
+
+This is the part that often gets misunderstood by apps and AI tools:
+
+- `admin: true` means "call the admin endpoint".
+- It does **not** mean "everything I wrote is now admin-only".
+- For app config and collection settings, root-level fields are usually part of the public payload.
+- If you need confidential values, store them under a top-level `admin` object.
+- Public reads omit that `admin` block; admin reads include it.
+
+Example for app config:
+
+```typescript
+await appConfiguration.setConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true,
+  config: {
+    theme: 'gold',
+    supportEmail: 'support@example.com',
+    admin: {
+      accessToken: 'secret-token',
+      webhookSecret: 'top-secret'
+    }
+  }
+})
+
+const publicView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection'
+})
+// { theme: 'gold', supportEmail: 'support@example.com' }
+
+const adminView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true
+})
+// { theme: 'gold', supportEmail: 'support@example.com', admin: { ... } }
+```
+
+The same visibility pattern applies to collection settings via `collection.getSettings()` / `collection.updateSettings()`.
+
 ### Use Cases
 - App-specific settings for a collection
 - Product-level configuration
@@ -178,7 +221,7 @@ await appConfiguration.setDataItem({
 | **Shared across collections?** | ✅ Yes | ❌ No | ❌ No |
 | **Requires auth?** | ✅ Yes (user token) | ✅ Yes (admin token for write) | Depends on public/admin endpoint and visibility |
 | **Querying / filtering** | Minimal | Minimal | Strong |
-| **Access control zones** | User-scoped only | Scope only | `data` / `owner` / `admin` zones |
+| **Access control zones** | User-scoped only | Root fields + reserved `admin` block for settings/config | `data` / `owner` / `admin` zones |
 | **Admin write required?** | ❌ No | ✅ Yes (for write operations) | Only for admin endpoints / admin fields |
 
 ---

package/docs/overview.md

@@ -140,6 +140,33 @@ await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig, adm
 
 This applies to all write operations: `setConfig`, `setDataItem`, `updateDataItem`, etc.
 
+### Endpoint Auth vs Data Visibility
+
+`admin: true` is an endpoint selector, not a privacy marker.
+
+- It tells the SDK to call the admin endpoint.
+- It allows writes and admin reads.
+- It does **not** mean every root-level field you save becomes admin-only.
+
+For `appConfiguration` config blobs and `collection.getSettings()` groups, root-level fields are typically the public-facing settings. If you need private values such as tokens or secrets, store them inside a top-level `admin` object:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    publicLabel: 'Warranty Portal',
+    color: '#B68C2A',
+    admin: {
+      accessToken: 'secret-token'
+    }
+  }
+})
+```
+
+Public reads omit the `admin` block. Admin reads include it.
+
 ### Config vs Data
 
 | Storage Type | Function | Use Case |
@@ -150,6 +177,8 @@ This applies to all write operations: `setConfig`, `setDataItem`, `updateDataIte
 
 Both can be scoped to **collection level** or **product level** by including `productId`.
 
+For config/settings visibility, remember: root fields are the normal shared payload, while a reserved top-level `admin` object is the place for admin-only values.
+
 Prefer `app.records` over `setDataItem` when the data is becoming a real entity that needs lifecycle, ownership, visibility, relationships, or filtering. Keep `setDataItem` for simple keyed scoped documents and config-adjacent content.
 
 ### Attestations (Proof-level data)

package/openapi.yaml

@@ -79,7 +79,7 @@ paths:
     post:
       tags:
         - collection
-      summary: Update a specific settings group for a collection (admin endpoint).
+      summary: Create a new collection (admin only).
       operationId: collection_create
       security:
         - bearerAuth: []
@@ -5446,7 +5446,7 @@ paths:
     post:
       tags:
         - collection
-      summary: Retrieve all configured app module definitions for a collection (public endpoint).
+      summary: Update a specific settings group for a collection (admin endpoint).
       operationId: collection_updateSettings
       security:
         - bearerAuth: []
@@ -7080,7 +7080,7 @@ paths:
     get:
       tags:
         - collection
-      summary: Retrieve a specific settings group for a collection (public endpoint).
+      summary: Retrieve all configured app module definitions for a collection (public endpoint).
       operationId: collection_getAppsConfig
       security: []
       parameters:

package/package.json

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