@proveanything/smartlinks 1.8.4 → 1.8.6

package/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,19 @@ 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`.
+
 ### 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 +170,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 | Scope only | `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/docs/app-manifest.md

@@ -46,6 +46,8 @@ The manifest is loaded automatically by the platform for every collection page.
   "admin": "app.admin.json",
 
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
@@ -127,8 +129,36 @@ Declares the widget bundle. Omit if the app has no widget component.
 | `files.js.umd` | UMD bundle path — used for dynamic `<script>` loading |
 | `files.js.esm` | ESM bundle path — used for `import()` / native ES modules (optional but recommended) |
 | `files.css` | CSS bundle path — omit if the widget ships no styles |
+| `instanceResolution` | Optional boolean. When `true`, this app supports resolving configured widget instances by ID from app config |
+| `instanceParam` | Optional string. Query/hash param used for instance lookup. Defaults to `"widgetId"` |
 | `components[]` | One entry per exported widget component (see below) |
 
+**Widget instance resolution**
+
+Apps such as widget toolkits often store reusable widget instances in collection-scoped app config, for example under `config.widgets.launch-countdown`. When your widget bundle can self-configure from one of those stored instances, declare that capability in the manifest:
+
+```json
+"widgets": {
+  "instanceResolution": true,
+  "instanceParam": "widgetId",
+  "files": {
+    "js": {
+      "umd": "dist/widgets.umd.js",
+      "esm": "dist/widgets.es.js"
+    },
+    "css": null
+  },
+  "components": [
+    {
+      "name": "WidgetToolkitResolver",
+      "description": "Resolves and renders a configured widget instance by ID."
+    }
+  ]
+}
+```
+
+This tells the platform and other apps that they can deep-link into a stored widget instance using a URL or embed context such as `?appId=widget-toolkit&widgetId=launch-countdown`.
+
 **Component fields:**
 
 | Field | Type | Description |
@@ -281,6 +311,8 @@ Fetched only by the admin UI and AI-assisted setup flows — never loaded on the
 }
 ```
 
+> `dynamic-select` widget pickers are a reasonable future extension for admin schemas, but they are not a built-in question type in the SDK today. For now, treat widget-instance selection as an app-level UI convention powered by `appConfiguration.listWidgetInstances()`.
+
 ### Field Reference
 
 #### `aiGuide`

package/docs/deep-link-discovery.md

@@ -35,6 +35,8 @@ Deep-linkable states come from **two sources** depending on their nature:
 | **App manifest** (`app.manifest.json`) | Fixed routes built into the app | Only when the app itself is updated |
 | **App config** (`appConfig.linkable`) | Content-driven entries that vary by collection | When admins create, remove, or rename content |
 
+Widget-oriented apps can also use the same deep-link model with `widgetId` rather than `pageId`: the app config stores reusable widget instances, and the URL or embed context selects a specific instance to render.
+
 Consumers merge both sources to get the full set of navigable states for an app.
 
 ```text
@@ -232,6 +234,7 @@ The parent platform constructs the final navigation URL from an entry by combini
 | Entry | Resolved URL |
 |-------|--------------|
 | `{ title: "About Us", params: { pageId: "about-us" } }` | `https://app.example.com/#/?collectionId=abc&appId=my-app&pageId=about-us` |
+| `{ title: "Launch Countdown", params: { widgetId: "launch-countdown" } }` | `https://app.example.com/#/?collectionId=abc&appId=widget-toolkit&widgetId=launch-countdown` |
 | `{ title: "Advanced Settings", path: "/settings", params: { tab: "advanced" } }` | `https://app.example.com/admin.html#/settings?collectionId=abc&appId=my-app&tab=advanced` |
 | `{ title: "Gallery", path: "/gallery" }` | `https://app.example.com/#/gallery?collectionId=abc&appId=my-app` |
 | `{ title: "Home" }` | `https://app.example.com/#/?collectionId=abc&appId=my-app` |
@@ -259,6 +262,31 @@ This section only applies to **dynamic links stored in `appConfig.linkable`**. S
 
 Apps **MUST** update `appConfig.linkable` whenever the set of dynamic navigable states changes:
 
+For widget toolkits, that usually means syncing entries from your stored widget instance map:
+
+```typescript
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+})
+
+const linkable = widgets.map(widget => ({
+  title: widget.name,
+  params: { widgetId: widget.id },
+}))
+
+const current = await SL.appConfiguration.getConfig({ collectionId, appId: 'widget-toolkit', admin: true }) ?? {}
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+  config: { ...current, linkable },
+})
+```
+
+This gives the portal and AI orchestrators the same discoverability for widget instances that page-driven apps already get for `pageId` content.
+
 - A page is created, deleted, published, or unpublished
 - A page's `deepLinkable` flag is toggled
 - A page title changes

package/docs/manifests.md

@@ -19,7 +19,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 |---------|---------|-------------|
 | `meta` | App identity, version, appId, SEO priority | All workflows |
 | `admin` | Pointer to `app.admin.json` | Admin orchestrators |
-| `widgets` | Bundle files + component definitions + settings schemas | Widget Builder |
+| `widgets` | Bundle files + component definitions + settings schemas; can also declare widget-instance resolution via `widgetId` | Widget Builder |
 | `containers` | Bundle files + component definitions | Container Loader |
 | `executor` | Bundle files, factory name, exports list | Server / AI |
 | `linkable` | Static deep-link routes | Portal menus / AI nav |
@@ -29,6 +29,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   "meta": { "name": "My App", "appId": "my-app", "version": "1.0.0" },
   "admin": "app.admin.json",
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
       "css": null
@@ -62,6 +64,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 }
 ```
 
+When `instanceResolution` is enabled, the app is declaring that consumers can pass a widget instance identifier such as `?appId=widget-toolkit&widgetId=launch-countdown`, and the widget bundle will resolve its stored configuration from app config.
+
 > ⚠️ **`css` is `null` by default.** Most widgets and containers use Tailwind/shadcn classes inherited from the parent and produce **no CSS output file**. Set `"css": null` in the manifest. Only set it to a filename if your widget/container ships a custom CSS file that actually exists in `dist/`. The parent portal checks this value before injecting a `<link>` tag — a non-null value pointing to a missing file will cause a 404.
 
 ---

package/docs/overview.md

@@ -146,9 +146,12 @@ This applies to all write operations: `setConfig`, `setDataItem`, `updateDataIte
 |-------------|---------|---------|
 | **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`.
 
+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/docs/widgets.md

@@ -202,6 +202,141 @@ Widgets support two navigation patterns:
 
 ## Building a Widget
 
+---
+
+## Widget Instance Resolution
+
+Some apps expose a **widget resolver** instead of a single hard-coded widget. The resolver receives a `widgetId`, looks up a stored instance in app config, and renders the correct widget with its saved settings.
+
+This pattern is useful for widget toolkits, promo blocks, countdown libraries, CTA collections, and any app where admins create multiple reusable widget instances.
+
+### URL and embed convention
+
+Use `widgetId` the same way page-oriented apps use `pageId`:
+
+```text
+?appId=widget-toolkit&widgetId=launch-countdown
+```
+
+This works naturally in:
+
+- direct container or iframe links
+- widget-to-widget references
+- content slots that need to embed a preconfigured widget instance
+- platform deep-link routing when the manifest declares widget instance resolution
+
+### Manifest declaration
+
+Declare support in `app.manifest.json`:
+
+```json
+{
+  "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
+    "files": {
+      "js": {
+        "umd": "dist/widgets.umd.js",
+        "esm": "dist/widgets.es.js"
+      },
+      "css": null
+    },
+    "components": [
+      {
+        "name": "WidgetToolkitResolver",
+        "description": "Resolves and renders widget instances by ID."
+      }
+    ]
+  }
+}
+```
+
+### SDK helpers
+
+The SDK now includes two thin helpers on `SL.appConfiguration`:
+
+```typescript
+const widget = await SL.appConfiguration.getWidgetInstance({
+  collectionId,
+  appId: 'widget-toolkit',
+  widgetId: 'launch-countdown',
+})
+
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+```
+
+`getWidgetInstance()` is intentionally just a wrapper over `getConfig()` that reads `config.widgets[widgetId]`. That keeps the integration simple today while giving the platform freedom to optimize the lookup later.
+
+### Stored config shape
+
+The recommended storage shape is:
+
+```json
+{
+  "widgets": {
+    "launch-countdown": {
+      "id": "launch-countdown",
+      "name": "Launch Countdown",
+      "widget": {
+        "type": "countdown",
+        "targetDate": "2026-06-01T00:00:00Z",
+        "label": "Launching in..."
+      }
+    }
+  }
+}
+```
+
+### Resolver pattern
+
+```typescript
+const WidgetToolkitResolver: React.FC<SmartLinksWidgetProps & { widgetId?: string }> = ({
+  collectionId,
+  appId,
+  widgetId,
+  SL,
+  ...props
+}) => {
+  const [instance, setInstance] = React.useState<any | null>(null)
+
+  React.useEffect(() => {
+    if (!widgetId) return
+    SL.appConfiguration.getWidgetInstance({ collectionId, appId, widgetId })
+      .then(setInstance)
+      .catch(console.error)
+  }, [collectionId, appId, widgetId, SL])
+
+  if (!widgetId || !instance) return null
+
+  switch (instance.widget?.type) {
+    case 'countdown':
+      return <CountdownWidget {...props} {...instance.widget} />
+    case 'cta-button':
+      return <CtaButtonWidget {...props} {...instance.widget} />
+    default:
+      return null
+  }
+}
+```
+
+### Listing widget instances
+
+`listWidgetInstances()` is useful for picker UIs and cross-app references:
+
+```typescript
+const options = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+
+// [{ id: 'launch-countdown', name: 'Launch Countdown', type: 'countdown' }]
+```
+
+This is a good foundation for future admin question types or dynamic selects, but the SDK does not currently define a built-in `dynamic-select` schema field.
+
 ### 1. Create the Widget Component
 
 ```typescript

package/openapi.yaml

@@ -11433,6 +11433,49 @@ components:
       required:
         - id
         - name
+    GetWidgetInstanceOptions:
+      type: object
+      properties:
+        appId:
+          type: string
+        collectionId:
+          type: string
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        admin:
+          type: boolean
+        widgetId:
+          type: string
+      required:
+        - appId
+        - widgetId
+    WidgetInstance:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        widget:
+          $ref: "#/components/schemas/TWidget"
+      required:
+        - id
+    WidgetInstanceSummary:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+      required:
+        - id
+        - name
     AppBundle:
       type: object
       properties:
@@ -11493,6 +11536,22 @@ components:
           additionalProperties: true
       required:
         - name
+    AppManifestWidgets:
+      type: object
+      properties:
+        files:
+          $ref: "#/components/schemas/AppManifestFiles"
+        components:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppWidgetComponent"
+        instanceResolution:
+          type: boolean
+        instanceParam:
+          type: string
+      required:
+        - files
+        - components
     AppContainerComponent:
       type: object
       properties:
@@ -11785,6 +11844,8 @@ components:
         admin:
           type: string
         widgets:
+          $ref: "#/components/schemas/AppManifestWidgets"
+        containers:
           type: object
           additionalProperties: true
         files:
@@ -11793,9 +11854,6 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AppContainerComponent"
-        containers:
-          type: object
-          additionalProperties: true
         linkable:
           type: array
           items:
@@ -11809,8 +11867,6 @@ components:
         - function
         - files
         - components
-        - files
-        - components
     CollectionAppWidget:
       type: object
       properties:

package/package.json

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