@proveanything/smartlinks 1.13.1 → 1.13.3

package/dist/api/asset.js

@@ -316,7 +316,7 @@ export var asset;
         if (typeof options.offset === 'number')
             params.set('offset', String(options.offset));
         const qs = params.toString();
-        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/assets${qs ? `?${qs}` : ''}`;
+        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/asset${qs ? `?${qs}` : ''}`;
         return request(path);
     }
     asset.listAdmin = listAdmin;
@@ -324,7 +324,7 @@ export var asset;
      * Get a single asset by ID (admin).
      */
     async function getAdmin(collectionId, assetId) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/assets/${encodeURIComponent(assetId)}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/asset/${encodeURIComponent(assetId)}`;
         return request(path);
     }
     asset.getAdmin = getAdmin;
@@ -332,7 +332,7 @@ export var asset;
      * Update asset metadata (admin). Use `replaceFile` to swap the file.
      */
     async function updateAdmin(options) {
-        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/assets/${encodeURIComponent(options.assetId)}`;
+        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/asset/${encodeURIComponent(options.assetId)}`;
         const { collectionId: _c, assetId: _a } = options, body = __rest(options, ["collectionId", "assetId"]);
         return put(path, body);
     }
@@ -342,7 +342,7 @@ export var asset;
      * into `versions[]` on the asset.
      */
     async function replaceFile(options) {
-        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/assets/${encodeURIComponent(options.assetId)}/replace`;
+        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/asset/${encodeURIComponent(options.assetId)}/replace`;
         const formData = new FormData();
         formData.append('file', options.file);
         if (options.onProgress && typeof window !== 'undefined' && !isProxyEnabled()) {
@@ -395,7 +395,7 @@ export var asset;
         if (typeof options.graceDays === 'number')
             params.set('graceDays', String(options.graceDays));
         const qs = params.toString();
-        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/assets/${encodeURIComponent(options.assetId)}${qs ? `?${qs}` : ''}`;
+        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/asset/${encodeURIComponent(options.assetId)}${qs ? `?${qs}` : ''}`;
         return del(path);
     }
     asset.deleteAdmin = deleteAdmin;
@@ -403,7 +403,7 @@ export var asset;
      * Restore a soft-deleted asset (clears `deletedAt`).
      */
     async function restoreAdmin(collectionId, assetId) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/assets/${encodeURIComponent(assetId)}/restore`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/asset/${encodeURIComponent(assetId)}/restore`;
         return post(path, {});
     }
     asset.restoreAdmin = restoreAdmin;
@@ -411,7 +411,7 @@ export var asset;
      * Soft-delete multiple assets in one request.
      */
     async function bulkDelete(options) {
-        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/assets/bulk-delete`;
+        const path = `/admin/collection/${encodeURIComponent(options.collectionId)}/asset/bulk-delete`;
         const body = { assetIds: options.assetIds };
         if (typeof options.graceDays === 'number')
             body.graceDays = options.graceDays;

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.1  |  Generated: 2026-05-07T10:59:17.642Z
+Version: 1.13.3  |  Generated: 2026-05-08T10:30:25.776Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1439,6 +1439,16 @@ interface DeepLinkEntry {
   * Do NOT include platform context params (collectionId, appId, productId, etc.) —
   * those are injected by the platform automatically.
   params?: Record<string, string>;
+  * When `true`, this entry is also available as a dynamic data context for widgets
+  * (in addition to being a navigable page / container route).
+  *
+  * Entries with `widget: true` appear in the widget config picker so an admin can
+  * select this dataset to drive how the widget renders. The widget receives `params`
+  * and decides its own presentation — no separate rendering contract is required.
+  *
+  * Omit (or `false`) for entries that are only meaningful as full-page navigation
+  * (e.g. multi-step forms, settings pages, checkout flows).
+  widget?: true;
 }
 ```
 

package/dist/docs/assets.md

@@ -103,7 +103,7 @@ All admin endpoints require authentication. Base path: `/api/admin/collection/:c
 ### List assets
 
 ```
-GET /assets
+GET /asset
 ```
 
 | Parameter   | Type   | Description |
@@ -140,7 +140,7 @@ const { data, total } = await Api.asset.listAdmin({
 ### Get asset
 
 ```
-GET /assets/:assetId
+GET /asset/:assetId
 ```
 
 Returns `Asset` or `404`.
@@ -152,7 +152,7 @@ Returns `Asset` or `404`.
 ### Upload asset
 
 ```
-POST /assets
+POST /asset
 ```
 
 Use the existing `Api.asset.upload()` method (file) or `Api.asset.uploadFromUrl()` (URL import).
@@ -162,7 +162,7 @@ Use the existing `Api.asset.upload()` method (file) or `Api.asset.uploadFromUrl(
 ### Update asset metadata
 
 ```
-PUT /assets/:assetId
+PUT /asset/:assetId
 ```
 
 Updates metadata only. Use `/replace` to swap the file.
@@ -182,7 +182,7 @@ await Api.asset.updateAdmin({
 ### Replace file
 
 ```
-POST /assets/:assetId/replace
+POST /asset/:assetId/replace
 ```
 
 Replaces the file; the previous URL is snapshotted into `versions[]`.
@@ -201,7 +201,7 @@ await Api.asset.replaceFile({
 ### Delete asset (soft)
 
 ```
-DELETE /assets/:assetId?graceDays=30
+DELETE /asset/:assetId?graceDays=30
 ```
 
 Sets `deletedAt` and schedules CDN purge after `graceDays` (default 30). Recoverable until purge.
@@ -215,7 +215,7 @@ await Api.asset.deleteAdmin({ collectionId: 'my-collection', assetId: 'abc123',
 ### Restore asset
 
 ```
-POST /assets/:assetId/restore
+POST /asset/:assetId/restore
 ```
 
 Clears `deletedAt`. Asset becomes active again.
@@ -229,7 +229,7 @@ await Api.asset.restoreAdmin('my-collection', 'abc123')
 ### Bulk delete
 
 ```
-POST /assets/bulk-delete
+POST /asset/bulk-delete
 ```
 
 ```typescript

package/dist/docs/deep-link-discovery.md

@@ -21,6 +21,7 @@ This doc covers both sides of the contract: **suppliers** declare their navigabl
   - [Portal Navigation Menu](#portal-navigation-menu)
   - [AI Orchestration](#ai-orchestration)
   - [Cross-App Navigation](#cross-app-navigation)
+  - [Widget Config Picker — Dynamic Data Context](#widget-config-picker--dynamic-data-context)
   - [Link Picker — Admin Configuration](#link-picker--admin-configuration)
   - [Rendering Links at Runtime](#rendering-links-at-runtime)
 - [TypeScript Types](#typescript-types)
@@ -191,6 +192,18 @@ interface DeepLinkEntry {
    * are injected automatically — do NOT include them here.
    */
   params?: Record<string, string>;
+
+  /**
+   * When `true`, this entry is also available as a dynamic data context for widgets.
+   *
+   * Entries with `widget: true` appear in the widget config picker so an admin can
+   * select this dataset to drive how the widget renders. The widget receives `params`
+   * and decides its own presentation — no additional contract is required.
+   *
+   * Omit for entries that are only meaningful as full-page navigation
+   * (e.g. multi-step forms, settings pages, checkout flows).
+   */
+  widget?: true;
 }
 ```
 
@@ -199,9 +212,12 @@ interface DeepLinkEntry {
 | `title` | ✅ | Displayed in menus and offered to AI agents. Should be concise and human-readable. |
 | `path` | ❌ | Hash route within the app. Defaults to `/` if omitted. |
 | `params` | ❌ | App-specific query params only. Platform params are injected automatically. |
+| `widget` | ❌ | Set to `true` to make this entry selectable in the widget config picker as a dynamic data context. |
 
 > **Tip:** Different entries can share the same `path` if they differ by `params` — for example, two entries pointing at `/settings` with different `tab` params.
 
+> **Container vs widget:** All entries are navigable via a container (full-page render). `widget: true` additionally opts the entry into the widget picker — use it for datasets that make sense as a compact card, e.g. a specific gallery view or a named product showcase. Don't set it on management/settings pages.
+
 ---
 
 ## Quick Start
@@ -500,6 +516,58 @@ if (entry) {
 
 ---
 
+### Widget Config Picker — Dynamic Data Context
+
+When a widget's admin settings include a "which view/dataset to show" picker, use the `widget: true` entries from `appConfig.linkable` as the source. Filter to entries with `widget: true` across all installed apps (or just the widget's own app) and let the admin select one. Persist only the `params` — the title is ephemeral display.
+
+```typescript
+// Fetch linkable entries for a specific app and filter to widget-eligible ones
+const config = await SL.appConfiguration.getConfig({ collectionId, appId: 'media-gallery' });
+const widgetViews = (config?.linkable ?? []).filter(e => e.widget === true);
+
+// widgetViews might be:
+// [
+//   { title: "Gallery: Summer 2026", params: { viewId: "sum26" }, widget: true },
+//   { title: "Gallery: Archive",     params: { viewId: "archive" }, widget: true },
+// ]
+```
+
+```tsx
+// Widget admin settings — view picker
+<select
+  value={JSON.stringify(settings.viewParams ?? {})}
+  onChange={e => saveSettings({ ...settings, viewParams: JSON.parse(e.target.value) })}
+>
+  <option value="{}">— Default view —</option>
+  {widgetViews.map(entry => (
+    <option key={entry.title} value={JSON.stringify(entry.params)}>
+      {entry.title}
+    </option>
+  ))}
+</select>
+```
+
+The widget then reads `settings.viewParams` at render time and uses it to fetch or filter its data. The widget owns all rendering decisions — `params` is just a key.
+
+**Supply side** — when the media gallery creates or renames a gallery view, it syncs `appConfig.linkable` as usual, marking card-appropriate views with `widget: true`:
+
+```typescript
+const linkable = galleryViews.map(view => ({
+  title: view.name,
+  params: { viewId: view.id },
+  widget: view.isCardReady ? true : undefined,   // only opt in views that make sense as cards
+}));
+
+await SL.appConfiguration.setConfig({
+  collectionId, appId: 'media-gallery', admin: true,
+  config: { ...current, linkable },
+});
+```
+
+> **Rule of thumb:** set `widget: true` on dataset entries (gallery views, product showcases, named feeds). Leave it off on management/utility pages (settings, upload config, multi-step forms).
+
+---
+
 ### Link Picker — Admin Configuration
 
 When an admin needs to configure any outbound link — to another installed app, a specific page within an app, or an external URL — **never use a bare text input**. Use `<LinkPicker />` from `@proveanything/smartlinks-utils-ui`. It handles all three `LinkTarget` kinds and produces a single `LinkTarget` value to persist.
@@ -656,6 +724,12 @@ export interface DeepLinkEntry {
    * Do NOT include platform context params (collectionId, appId, etc.).
    */
   params?: Record<string, string>;
+  /**
+   * When `true`, this entry is also available as a dynamic data context for widgets
+   * (in addition to being a navigable page / container route).
+   * Omit for entries that are only meaningful as full-page navigation.
+   */
+  widget?: true;
 }
 
 /** Convenience alias for an array of DeepLinkEntry */

package/dist/openapi.yaml

@@ -105,7 +105,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/CollectionCreateRequest"
-  /admin/collection/assets:
+  /admin/collection/asset:
     get:
       tags:
         - asset
@@ -216,7 +216,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/UpdateAssetOptions"
-  /admin/collection/assets/replace:
+  /admin/collection/asset/replace:
     post:
       tags:
         - asset
@@ -1050,7 +1050,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/ResponsesRequest"
-  /admin/collection/{collectionId}/assets/{assetId}:
+  /admin/collection/{collectionId}/asset/{assetId}:
     get:
       tags:
         - asset
@@ -1082,7 +1082,7 @@ paths:
           description: Unauthorized
         404:
           description: Not found
-  /admin/collection/{collectionId}/assets/{assetId}/restore:
+  /admin/collection/{collectionId}/asset/{assetId}/restore:
     post:
       tags:
         - asset
@@ -15058,6 +15058,9 @@ components:
           type: object
           additionalProperties:
             type: string
+        widget:
+          type: object
+          additionalProperties: true
       required:
         - title
     ExecutorContext:

package/dist/types/appManifest.d.ts

@@ -96,6 +96,18 @@ export interface DeepLinkEntry {
      * those are injected by the platform automatically.
      */
     params?: Record<string, string>;
+    /**
+     * When `true`, this entry is also available as a dynamic data context for widgets
+     * (in addition to being a navigable page / container route).
+     *
+     * Entries with `widget: true` appear in the widget config picker so an admin can
+     * select this dataset to drive how the widget renders. The widget receives `params`
+     * and decides its own presentation — no separate rendering contract is required.
+     *
+     * Omit (or `false`) for entries that are only meaningful as full-page navigation
+     * (e.g. multi-step forms, settings pages, checkout flows).
+     */
+    widget?: true;
 }
 /**
  * Context object passed to every executor factory function.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.1  |  Generated: 2026-05-07T10:59:17.642Z
+Version: 1.13.3  |  Generated: 2026-05-08T10:30:25.776Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1439,6 +1439,16 @@ interface DeepLinkEntry {
   * Do NOT include platform context params (collectionId, appId, productId, etc.) —
   * those are injected by the platform automatically.
   params?: Record<string, string>;
+  * When `true`, this entry is also available as a dynamic data context for widgets
+  * (in addition to being a navigable page / container route).
+  *
+  * Entries with `widget: true` appear in the widget config picker so an admin can
+  * select this dataset to drive how the widget renders. The widget receives `params`
+  * and decides its own presentation — no separate rendering contract is required.
+  *
+  * Omit (or `false`) for entries that are only meaningful as full-page navigation
+  * (e.g. multi-step forms, settings pages, checkout flows).
+  widget?: true;
 }
 ```
 

package/docs/assets.md

@@ -103,7 +103,7 @@ All admin endpoints require authentication. Base path: `/api/admin/collection/:c
 ### List assets
 
 ```
-GET /assets
+GET /asset
 ```
 
 | Parameter   | Type   | Description |
@@ -140,7 +140,7 @@ const { data, total } = await Api.asset.listAdmin({
 ### Get asset
 
 ```
-GET /assets/:assetId
+GET /asset/:assetId
 ```
 
 Returns `Asset` or `404`.
@@ -152,7 +152,7 @@ Returns `Asset` or `404`.
 ### Upload asset
 
 ```
-POST /assets
+POST /asset
 ```
 
 Use the existing `Api.asset.upload()` method (file) or `Api.asset.uploadFromUrl()` (URL import).
@@ -162,7 +162,7 @@ Use the existing `Api.asset.upload()` method (file) or `Api.asset.uploadFromUrl(
 ### Update asset metadata
 
 ```
-PUT /assets/:assetId
+PUT /asset/:assetId
 ```
 
 Updates metadata only. Use `/replace` to swap the file.
@@ -182,7 +182,7 @@ await Api.asset.updateAdmin({
 ### Replace file
 
 ```
-POST /assets/:assetId/replace
+POST /asset/:assetId/replace
 ```
 
 Replaces the file; the previous URL is snapshotted into `versions[]`.
@@ -201,7 +201,7 @@ await Api.asset.replaceFile({
 ### Delete asset (soft)
 
 ```
-DELETE /assets/:assetId?graceDays=30
+DELETE /asset/:assetId?graceDays=30
 ```
 
 Sets `deletedAt` and schedules CDN purge after `graceDays` (default 30). Recoverable until purge.
@@ -215,7 +215,7 @@ await Api.asset.deleteAdmin({ collectionId: 'my-collection', assetId: 'abc123',
 ### Restore asset
 
 ```
-POST /assets/:assetId/restore
+POST /asset/:assetId/restore
 ```
 
 Clears `deletedAt`. Asset becomes active again.
@@ -229,7 +229,7 @@ await Api.asset.restoreAdmin('my-collection', 'abc123')
 ### Bulk delete
 
 ```
-POST /assets/bulk-delete
+POST /asset/bulk-delete
 ```
 
 ```typescript

package/docs/deep-link-discovery.md

@@ -21,6 +21,7 @@ This doc covers both sides of the contract: **suppliers** declare their navigabl
   - [Portal Navigation Menu](#portal-navigation-menu)
   - [AI Orchestration](#ai-orchestration)
   - [Cross-App Navigation](#cross-app-navigation)
+  - [Widget Config Picker — Dynamic Data Context](#widget-config-picker--dynamic-data-context)
   - [Link Picker — Admin Configuration](#link-picker--admin-configuration)
   - [Rendering Links at Runtime](#rendering-links-at-runtime)
 - [TypeScript Types](#typescript-types)
@@ -191,6 +192,18 @@ interface DeepLinkEntry {
    * are injected automatically — do NOT include them here.
    */
   params?: Record<string, string>;
+
+  /**
+   * When `true`, this entry is also available as a dynamic data context for widgets.
+   *
+   * Entries with `widget: true` appear in the widget config picker so an admin can
+   * select this dataset to drive how the widget renders. The widget receives `params`
+   * and decides its own presentation — no additional contract is required.
+   *
+   * Omit for entries that are only meaningful as full-page navigation
+   * (e.g. multi-step forms, settings pages, checkout flows).
+   */
+  widget?: true;
 }
 ```
 
@@ -199,9 +212,12 @@ interface DeepLinkEntry {
 | `title` | ✅ | Displayed in menus and offered to AI agents. Should be concise and human-readable. |
 | `path` | ❌ | Hash route within the app. Defaults to `/` if omitted. |
 | `params` | ❌ | App-specific query params only. Platform params are injected automatically. |
+| `widget` | ❌ | Set to `true` to make this entry selectable in the widget config picker as a dynamic data context. |
 
 > **Tip:** Different entries can share the same `path` if they differ by `params` — for example, two entries pointing at `/settings` with different `tab` params.
 
+> **Container vs widget:** All entries are navigable via a container (full-page render). `widget: true` additionally opts the entry into the widget picker — use it for datasets that make sense as a compact card, e.g. a specific gallery view or a named product showcase. Don't set it on management/settings pages.
+
 ---
 
 ## Quick Start
@@ -500,6 +516,58 @@ if (entry) {
 
 ---
 
+### Widget Config Picker — Dynamic Data Context
+
+When a widget's admin settings include a "which view/dataset to show" picker, use the `widget: true` entries from `appConfig.linkable` as the source. Filter to entries with `widget: true` across all installed apps (or just the widget's own app) and let the admin select one. Persist only the `params` — the title is ephemeral display.
+
+```typescript
+// Fetch linkable entries for a specific app and filter to widget-eligible ones
+const config = await SL.appConfiguration.getConfig({ collectionId, appId: 'media-gallery' });
+const widgetViews = (config?.linkable ?? []).filter(e => e.widget === true);
+
+// widgetViews might be:
+// [
+//   { title: "Gallery: Summer 2026", params: { viewId: "sum26" }, widget: true },
+//   { title: "Gallery: Archive",     params: { viewId: "archive" }, widget: true },
+// ]
+```
+
+```tsx
+// Widget admin settings — view picker
+<select
+  value={JSON.stringify(settings.viewParams ?? {})}
+  onChange={e => saveSettings({ ...settings, viewParams: JSON.parse(e.target.value) })}
+>
+  <option value="{}">— Default view —</option>
+  {widgetViews.map(entry => (
+    <option key={entry.title} value={JSON.stringify(entry.params)}>
+      {entry.title}
+    </option>
+  ))}
+</select>
+```
+
+The widget then reads `settings.viewParams` at render time and uses it to fetch or filter its data. The widget owns all rendering decisions — `params` is just a key.
+
+**Supply side** — when the media gallery creates or renames a gallery view, it syncs `appConfig.linkable` as usual, marking card-appropriate views with `widget: true`:
+
+```typescript
+const linkable = galleryViews.map(view => ({
+  title: view.name,
+  params: { viewId: view.id },
+  widget: view.isCardReady ? true : undefined,   // only opt in views that make sense as cards
+}));
+
+await SL.appConfiguration.setConfig({
+  collectionId, appId: 'media-gallery', admin: true,
+  config: { ...current, linkable },
+});
+```
+
+> **Rule of thumb:** set `widget: true` on dataset entries (gallery views, product showcases, named feeds). Leave it off on management/utility pages (settings, upload config, multi-step forms).
+
+---
+
 ### Link Picker — Admin Configuration
 
 When an admin needs to configure any outbound link — to another installed app, a specific page within an app, or an external URL — **never use a bare text input**. Use `<LinkPicker />` from `@proveanything/smartlinks-utils-ui`. It handles all three `LinkTarget` kinds and produces a single `LinkTarget` value to persist.
@@ -656,6 +724,12 @@ export interface DeepLinkEntry {
    * Do NOT include platform context params (collectionId, appId, etc.).
    */
   params?: Record<string, string>;
+  /**
+   * When `true`, this entry is also available as a dynamic data context for widgets
+   * (in addition to being a navigable page / container route).
+   * Omit for entries that are only meaningful as full-page navigation.
+   */
+  widget?: true;
 }
 
 /** Convenience alias for an array of DeepLinkEntry */

package/openapi.yaml

@@ -105,7 +105,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/CollectionCreateRequest"
-  /admin/collection/assets:
+  /admin/collection/asset:
     get:
       tags:
         - asset
@@ -216,7 +216,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/UpdateAssetOptions"
-  /admin/collection/assets/replace:
+  /admin/collection/asset/replace:
     post:
       tags:
         - asset
@@ -1050,7 +1050,7 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/ResponsesRequest"
-  /admin/collection/{collectionId}/assets/{assetId}:
+  /admin/collection/{collectionId}/asset/{assetId}:
     get:
       tags:
         - asset
@@ -1082,7 +1082,7 @@ paths:
           description: Unauthorized
         404:
           description: Not found
-  /admin/collection/{collectionId}/assets/{assetId}/restore:
+  /admin/collection/{collectionId}/asset/{assetId}/restore:
     post:
       tags:
         - asset
@@ -15058,6 +15058,9 @@ components:
           type: object
           additionalProperties:
             type: string
+        widget:
+          type: object
+          additionalProperties: true
       required:
         - title
     ExecutorContext:

package/package.json

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