@proveanything/smartlinks 1.8.6 → 1.8.9

package/dist/docs/containers.md

@@ -26,6 +26,190 @@ Imagine a homepage displaying 10 app widgets. If containers were bundled with wi
 
 ---
 
+## Dual-Mode Rendering
+
+Containers can run in **two modes**, and the same container code must work in both:
+
+| Mode | How It Works | Who Provides the Router? |
+|------|-------------|--------------------------|
+| **Direct Component** | Container runs directly in the parent's React context | **The framework** — wraps your component in `MemoryRouter` |
+| **Iframe** | Container runs inside an iframe with its own URL | **Your app** — you manage your own `HashRouter` |
+
+### The Critical Rule: No Router Wrappers in Your Export
+
+> **❌ Your exported `PublicContainer` must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct-component mode, the framework already wraps your container in a `MemoryRouter`. If your component includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**The routing architecture:**
+
+```
+Direct Component Mode:
+  Portal Shell (HashRouter)
+    └─ ContentOrchestrator
+         └─ MemoryRouter ← framework provides this
+              └─ <YourContainer /> ← only contains <Routes>, no <Router>
+                   └─ <Route path="/" element={<Home />} />
+                   └─ <Route path="/detail/:id" element={<Detail />} />
+
+Iframe Mode:
+  <iframe src="your-app-url">
+    └─ <HashRouter> ← your App.tsx provides this
+         └─ <Routes>
+              └─ <Route path="/" element={<Home />} />
+```
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+
+### The Router Contract
+
+In direct-component mode, the framework's `MemoryRouter` gives you full React Router capabilities:
+
+- ✅ `useNavigate()` works — navigates within your container's routes
+- ✅ `useLocation()` works — returns current location in the MemoryRouter
+- ✅ `useParams()` works — reads params from your route definitions
+- ✅ `<Routes>` / `<Route>` work — define your internal navigation
+- ✅ `useSearchParams()` works — manages search params within the MemoryRouter
+- ⚠️ `window.location` does **NOT** reflect your container's route — it reflects the portal's URL
+
+**Example: Correct Container Structure**
+
+```tsx
+// ❌ WRONG — has Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <MemoryRouter>  {/* ❌ Don't do this! */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </MemoryRouter>
+  );
+};
+
+// ✅ CORRECT — no Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>  {/* ✅ Routes are fine, just no Router */}
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+```
+
+### The `useAppContext()` Pattern
+
+To write containers that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  initialPath?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your container:**
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+import { AppContext } from '@/hooks/useAppContext';
+import { Home } from '@/pages/Home';
+import { Detail } from '@/pages/Detail';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+
+// src/pages/Home.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+import { useNavigate } from 'react-router-dom';
+
+export function Home() {
+  const { collectionId, productId, SL } = useAppContext();
+  const navigate = useNavigate();
+  
+  return (
+    <div>
+      <h1>Collection: {collectionId}</h1>
+      <button onClick={() => navigate('/detail/123')}>
+        View Detail
+      </button>
+    </div>
+  );
+}
+```
+
+### Deep Linking
+
+The framework sets the `MemoryRouter`'s initial route based on the `pageId` or `initialPath` prop. For example, if the portal navigates to your container with `pageId: 'settings'`, your router will start at `/settings`.
+
+To advertise deep-linkable pages, declare them in your `app.manifest.json`:
+
+```json
+{
+  "linkable": [
+    { "title": "Home", "path": "/" },
+    { "title": "Settings", "path": "/settings" },
+    { "title": "Item Detail", "path": "/item/:itemId" }
+  ]
+}
+```
+
+---
+
 ## Container Props
 
 Container props extend the standard `SmartLinksWidgetProps` with an additional `className` prop:

package/dist/docs/overview.md

@@ -45,6 +45,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | Topic | File | When to Use |
 |-------|------|-------------|
 | **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
+| **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
 | **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
 | **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |
 | **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |
@@ -140,6 +141,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 +178,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/docs/widgets.md

@@ -30,6 +30,104 @@ Widgets are self-contained React components that:
 
 ---
 
+## Dual-Mode Rendering
+
+Widgets can run in **two modes**, and the same widget code must work in both:
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Widget runs directly in the parent's React context | Default - when loaded as ESM/UMD in the parent app |
+| **Iframe** | Widget runs inside an iframe with its own URL | Fallback or when full isolation is needed |
+
+### The Critical Rule: No Router Wrappers
+
+> **❌ Your widget component must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct component mode, the parent application already provides routing context. If your widget includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ❌ Your **exported widget** (`PublicComponent.tsx`) should NOT include any Router
+
+Widgets are typically single-view components and don't need internal routing. If you need multi-page navigation, use a container instead.
+
+### The `useAppContext()` Pattern
+
+To write widgets that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your widget:**
+
+```tsx
+// src/exports/PublicComponent.tsx
+import { AppContext } from '@/hooks/useAppContext';
+import { WidgetContent } from '@/components/WidgetContent';
+
+export const PublicComponent = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <WidgetContent />
+    </AppContext.Provider>
+  );
+};
+
+// src/components/WidgetContent.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+
+export function WidgetContent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // Works in both direct-component and iframe modes!
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+---
+
 ## Widget Props Interface
 
 All widgets receive the `SmartLinksWidgetProps` interface:

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.9  |  Generated: 2026-03-19T15:02:36.521Z
 
 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 |
 
 ---