@proveanything/smartlinks 1.8.5 → 1.8.7

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

@@ -2,6 +2,27 @@
 
 The SmartLinks platform provides two distinct types of data storage for apps:
 
+## Choose the Right Model First
+
+There are now two different families of flexible app data in SmartLinks, and they solve different problems:
+
+| Need | Best Fit | Why |
+|------|----------|-----|
+| One settings blob per scope | `appConfiguration.getConfig` / `setConfig` | Simple app setup and feature flags |
+| A few keyed scoped documents by ID | `appConfiguration.getData` / `setDataItem` | Lightweight, direct, minimal overhead |
+| Rich app-owned entities with filtering, visibility, ownership, or lifecycle | `app.records` | Better default for real domain objects |
+| Workflow items that move through resolution | `app.cases` | Status, priority, assignment, history |
+| Discussions, comments, reply chains | `app.threads` | Built around replies and conversation flow |
+
+### Rule of Thumb
+
+- Use `appConfiguration` when the thing you are storing is basically config or a small keyed document.
+- Use `app.records` when the thing you are storing is a real object in your app.
+- Use `app.cases` when the object represents work to resolve.
+- Use `app.threads` when the object is conversational.
+
+This matters for AI-generated apps too: if the documentation only mentions `setDataItem`, builders will overuse it. In most non-trivial app flows, `app.records` is usually the stronger default.
+
 ## 1. User-Specific Data (Global per User+App)
 
 **Use the `userAppData` namespace for all user-specific data.**
@@ -77,16 +98,62 @@ await userAppData.remove('garden-planner', 'bed-1');
 
 ## 2. Collection/Product-Scoped Data (Admin Configuration)
 
-**Use the `appConfiguration` namespace for collection/product-scoped data.**
+**Use the `appConfiguration` namespace for collection/product-scoped config and simple keyed documents.**
 
 This data is scoped to specific collections, products, variants, or batches. It's typically configured by collection admins/owners and applies to all users viewing that collection/product.
 
+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
 - Feature flags and toggles
 - Theme and branding settings
 - Public content that all users see
+- Small keyed content entries such as FAQs, menu items, or quick lookup documents
 
 ### API Endpoints
 ```
@@ -146,15 +213,37 @@ await appConfiguration.setDataItem({
 
 ## Comparison Table
 
-| Feature | User Data | Collection/Product Data |
-|---------|-----------|------------------------|
-| **Namespace** | `userAppData` | `appConfiguration` |
-| **Scope** | User + App (global) | Collection/Product/Variant/Batch |
-| **Set by** | Individual users | Collection admins/owners |
-| **Shared across collections?** | ✅ Yes | ❌ No |
-| **Requires auth?** | ✅ Yes (user token) | ✅ Yes (admin token for write) |
-| **Function signature** | Simple: `set(appId, data)` | Options object: `setDataItem({ appId, collectionId, data })` |
-| **Admin write required?** | ❌ No | ✅ Yes (for write operations) |
+| Feature | User Data | Scoped Config/Data | App Objects |
+|---------|-----------|--------------------|-------------|
+| **Namespace** | `userAppData` | `appConfiguration` | `app.records` / `app.cases` / `app.threads` |
+| **Scope** | User + App (global) | Collection/Product/Variant/Batch | Collection + App |
+| **Best for** | Personal preferences and user-owned items | Config blobs and small keyed documents | Rich entities and workflows |
+| **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 | 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 |
+
+---
+
+## When `setDataItem` Is Still the Right Answer
+
+`setDataItem` is still valuable and should not be treated as deprecated. It is the right fit when:
+
+- You need a handful of documents attached to a collection or product
+- Each item has a stable known ID
+- You mostly fetch by exact ID or list all items
+- You do not need rich lifecycle fields, reply chains, assignment, or advanced querying
+
+Examples:
+
+- Product FAQs
+- Menu definitions
+- Marketing content blocks
+- Widget registry entries
+- Static lookup tables for an app
+
+If the object starts needing richer semantics, migrate that use case to `app.records`, `app.cases`, or `app.threads` rather than stretching scoped data items too far.
 
 ---
 

package/dist/docs/overview.md

@@ -140,15 +140,47 @@ 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 |
 |-------------|---------|---------|
 | **Config** (`getConfig`/`setConfig`) | Single JSON document | App settings, feature flags, global options |
 | **Data** (`getData`/`setDataItem`) | Array of documents with IDs | Lists of items, records, entries |
+| **App Objects** (`app.records` / `app.cases` / `app.threads`) | Queryable domain objects | Real app entities, workflows, conversations, richer access control |
 
 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)
 
 For data attached to specific proof instances, use `SL.attestation.create()` and `SL.attestation.list()`.

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: