@proveanything/smartlinks 2.0.5 → 2.0.9

package/dist/docs/manifests.md

@@ -32,7 +32,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
     "instanceResolution": true,
     "instanceParam": "widgetId",
     "files": {
-      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
+      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.esm.js" },
       "css": null
     },
     "components": [
@@ -46,13 +46,13 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   },
   "containers": {
     "files": {
-      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" },
+      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" },
       "css": null
     },
     "components": [{ "name": "PublicContainer", "description": "Full app view." }]
   },
   "executor": {
-    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" } },
+    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.esm.js" } },
     "factory": "createMyAppExecutor",
     "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
     "description": "Programmatic configuration and SEO API for My App."

package/dist/docs/mobile-admin-container.md

@@ -1,6 +1,6 @@
 # Mobile Admin Container SDK
 
-> **Version:** 1.0 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.0 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
@@ -271,7 +271,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
   "meta": { "appId": "my-app", "name": "My App", "version": "1.0.0" },
 
   "containers": {
-    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" }, "css": "dist/containers.css" },
+    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" }, "css": "dist/containers.css" },
     "components": [
       { "name": "PublicContainer", "description": "Default consumer experience" }
     ]
@@ -281,7 +281,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
     "files": {
       "js": {
         "umd": "dist/mobile-admin.umd.js",
-        "esm": "dist/mobile-admin.es.js"
+        "esm": "dist/mobile-admin.esm.js"
       },
       "css": null
     },
@@ -416,7 +416,7 @@ The mobile admin bundle has its own Vite config: `vite.config.mobile-admin.ts`.
 
 ```
 dist/mobile-admin.umd.js
-dist/mobile-admin.es.js
+dist/mobile-admin.esm.js
 dist/mobile-admin.css    (if needed)
 ```
 

package/dist/docs/mpa.md

@@ -56,9 +56,9 @@ vite build
 | Step | Config / Script | Gate env var | Output |
 |------|----------------|-------------|--------|
 | 1 | `vite.config.ts` | Always runs | `index.html`, `admin.html`, `assets/*` |
-| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.es.js`, `widgets.css` |
-| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.es.js`, `containers.css` |
-| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.es.js` |
+| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.esm.js`, `widgets.css` |
+| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.esm.js`, `containers.css` |
+| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.esm.js` |
 | 5 | `scripts/hash-bundles.mjs` | Always runs | Renames bundles with content hashes; patches `dist/app.manifest.json` |
 
 Steps 2–4 produce a harmless stub file when their gate env var is not set. Step 5 detects and skips stub files automatically.
@@ -107,7 +107,7 @@ dist/
 └── executor-[hash].es.js           ← Executor bundle (ESM)
 ```
 
-> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [AI-Native App Manifests](manifests.md) guide for the CSS null warning.
+> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [App Configuration Files](app-manifest.md) for the CSS null warning.
 
 ---
 
@@ -133,6 +133,6 @@ If the embedded app exposes nested screens, document its "up" navigation path wi
 | [Widgets](widgets.md) | Widget bundle: components, props, settings |
 | [Containers](containers.md) | Container bundle: full-app embeds |
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
-| [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
+| [App Configuration Files](app-manifest.md) | Manifest + admin reference; widget settings schema; AI workflows |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
 | [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/dist/docs/native-facade.md

@@ -1,6 +1,6 @@
 # Native Capability Facade (`host.native` / `SL.native`)
 
-> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.12 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
 

package/dist/docs/overview.md

@@ -1,25 +1,21 @@
 # SmartLinks Microapp Development Guide
 
-> **Platform revision:** R4.6 · **SDK minimum:** `@proveanything/smartlinks@1.4.1`  
-> **Last updated:** 2026-03-03
+> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` · React 19 · Vite 8 · Router 7 · Tailwind 4 · TS 6.
+> The canonical version/host stack lives in [host-dependency-contract.md](host-dependency-contract.md).
 
 ---
 
 ## What Is a SmartLinks Microapp?
 
-SmartLinks microapps are **modular, embeddable React applications** that extend the SmartLinks digital twin platform. They provide specialised functionality — product information displays, warranty registration, competitions, pamphlet generators, and more — while inheriting context, authentication, and theming from the parent platform.
+SmartLinks connects **physical products to digital experiences**: each item has a digital identity — a **proof** — that a consumer reaches by scanning a QR / NFC tag, then claims and enriches over time. A **microapp** is a focused, embeddable React experience a brand adds to that product's digital life: product info, warranty registration, authenticity checks, manuals, competitions, loyalty, post-purchase support, and more.
 
-### The Digital Twin Ecosystem
+Rather than baking every feature into the core platform, functionality is distributed across purpose-built apps, so a brand adds exactly the experiences its product needs. Each app:
 
-SmartLinks is a **digital twin platform** that connects physical products to digital experiences. Each physical item (a wine bottle, a luxury handbag, a piece of equipment) has a corresponding digital identity — a "proof" — that can be scanned, claimed, and enriched with data over time.
-
-Microapps are the **extensibility layer** of this ecosystem. Rather than building monolithic features into the core platform, functionality is distributed across purpose-built apps that:
-
-- **Embed seamlessly** via iframes in the SmartLinks Portal (public) and Admin Console (management)
-- **Share context** through URL parameters (collection, product, or proof being viewed)
-- **Inherit identity** from the parent platform's authentication system
-- **Adapt visually** to the brand's theme configuration
-- **Communicate bidirectionally** with the parent via postMessage for deep linking and navigation
+- **Embeds** in the SmartLinks Portal (public) and Admin Console (management)
+- **Shares context** through URL parameters (collection, product, proof)
+- **Inherits identity** from the parent platform's auth
+- **Adapts** to the brand's theme
+- **Communicates** with the parent via postMessage for deep linking and navigation
 
 ### Deployment Modes
 
@@ -45,7 +41,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 
 > Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
 
-> **Minimum SDK version: `1.4.1`** — Ensure `@proveanything/smartlinks` is at least this version. If not, update with `npm install @proveanything/smartlinks@latest`.
+> **SDK baseline: `@proveanything/smartlinks@^2.0`** (R5). Install/update with `npm install @proveanything/smartlinks@^2.0`. Individual features may need a higher minor — see the relevant doc. The single source of truth for the R5 host/version stack is [`host-dependency-contract.md`](host-dependency-contract.md).
 
 | Topic | File | When to Use |
 |-------|------|-------------|
@@ -64,12 +60,13 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Server Functions** | `docs/server-functions.md` | App-authored server-side functions `(ctx, event) ⇒ result`: security model, runtime surface, invoking |
+| **Agent Tools** | `docs/agent-tools.md` | Exposing your app's actions to the SmartLinks agent — an MCP facade over server functions; declare now, live loop staged; replaces `app.admin.json` AI setup |
 | **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
+| **Host Dependency Contract (R5)** | `docs/host-dependency-contract.md` | The libraries the host provides (React 19, Router 7, Radix, liquidjs, …), the externalise-don't-bundle rule + Vite config, and React-18 backwards-compat |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
-| **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
 | **Real-time Messaging** | `docs/realtime.md` | Adding Ably real-time features (chat, live updates) |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
@@ -87,6 +84,21 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Proof Share Grants** | `docs/proof-share-grants.md` | Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner) |
 | **Proof Ownership Transfer** | `docs/proof-ownership-transfer.md` | Moving a proof's single owner (directed transfer / open release), accept/cancel, and the state machine |
 | **appConfig / Feature Flags** | `docs/appConfig.md` | `appConfig` settings contract — installed apps, `system.features`/`entitledAppGroups`/`meters`, `isFeatureEnabled()` helper |
+| **App Objects** | `docs/app-objects.md` | Queryable domain objects — `app.records` / `app.cases` / `app.threads`: JSONB zones, visibility, policies, aggregations |
+| **App Data Storage** | `docs/app-data-storage.md` | Decision guide: pick between `appConfiguration` / `userAppData` / `app.records` |
+| **Attestations** | `docs/attestations.md` | Postgres attestations API (proof-level user/admin data; replaces the legacy Firestore path) |
+| **Caching** | `docs/caching.md` | SDK GET cache tiers + TTLs, `invalidateCache({ exact })`, and `force`/push guidance |
+| **Comms & Broadcasts** | `docs/comms.md` | Transactional comms, campaigns, consent, push |
+| **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
+| **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
+| **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
+| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
+| **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
+| **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |
+| **AI Tools & Skills** | `docs/ai-tools-and-skills.md` | Platform AI capability registry (web research, extraction, images) |
+| **Proof Comms Triggers** | `docs/proof-comms-triggers.md` | Transactional comms fired as a side-effect of proof actions |
 
 ---
 
@@ -97,6 +109,15 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **Context via URL params** — All contextual data is passed through URL parameters
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
+
+> **Use the host-provided `SL`, don't instantiate your own.** When your app runs in a
+> container/iframe, the host injects an already-initialized, authenticated SDK instance (the
+> `SL` prop / the externalized `@proveanything/smartlinks` singleton). Import and use *that*.
+> Calling `initializeApi()` yourself to spin up a **second** SDK instance is a common source
+> of bugs: it won't share the host's auth (so it looks signed-out), won't share the host's
+> cache (duplicate requests, stale data), and in proxy mode it bypasses the host's request
+> routing. Rule of thumb: **host-provided `SL` for anything the platform owns** (auth, config,
+> data, cache); only app-owned state is yours.
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
 - **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 

package/dist/docs/portal-back-button.md

@@ -1,8 +1,7 @@
 # Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
-> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
-> microapp authors discover it.
+> **For sub-app authors.** How to cooperate with the portal shell's top-level
+> back/up control. See also [`mpa.md`](mpa.md).
 
 When a sub-app is embedded by a portal shell, the shell renders a top-level
 back button. By default that button **exits the app entirely** when tapped —

package/dist/docs/sequences.md

@@ -1,6 +1,6 @@
 # Sequences & claim-order allocation
 
-> **Preview — SmartLinks SDK 2.0.0-alpha.** APIs may change before 2.0.0 stable.
+> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
 
 A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
 onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue

package/dist/docs/server-functions.md

@@ -1,8 +1,7 @@
 # Server functions ("edge functions")
 
-> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
-> toward 2.0.0 stable (author → register → install → run → test). These APIs may change before
-> then. Published under the npm `next` tag; `latest` remains 1.x.
+> **SmartLinks SDK 2.x** (current `latest`). Part of the installable-app platform
+> (author → register → install → run → test). Install `@proveanything/smartlinks@^2`.
 
 A **server function** is arbitrary server-side JavaScript your app deploys directly into
 SmartLinks. It runs on the SmartLinks servers — with access to the full SDK, to your app's

package/dist/docs/widgets.md

@@ -14,7 +14,7 @@ Widgets are self-contained React components that:
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
-│ Parent SmartLinks Portal (React 18)                             │
+│ Parent SmartLinks Portal (React 19)                             │
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
 │  │ Competition  │  │ Music App    │  │ Warranty     │          │
@@ -53,53 +53,7 @@ Widgets are typically single-view components and don't need internal routing. If
 
 ### 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]);
-}
-```
+Widgets read their context through the shared **`useAppContext()`** hook so the same code works in both direct-component and iframe modes. The hook and `AppContext` provider are defined once — see **[building-react-components.md](building-react-components.md#the-useappcontext-pattern)** for the full implementation (don't re-define it per app).
 
 **Usage in your widget:**
 
@@ -344,7 +298,7 @@ Declare support in `app.manifest.json`:
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
-        "esm": "dist/widgets.es.js"
+        "esm": "dist/widgets.esm.js"
       },
       "css": null
     },
@@ -511,7 +465,7 @@ export { MyWidget } from './MyWidget';
 // Update the manifest
 export const WIDGET_MANIFEST = {
   version: '1.0.0',
-  reactVersion: '18.x',
+  reactVersion: '19.x',
   widgets: [
     // ... existing widgets
     {
@@ -570,7 +524,7 @@ The project includes a separate Vite config for building widgets:
 # Build widgets only
 vite build --config vite.config.widget.ts
 
-# Output: dist/widgets.es.js
+# Output: dist/widgets.esm.js
 ```
 
 ### Build Configuration
@@ -582,23 +536,11 @@ The widget build:
 - Minifies with esbuild for production
 - Outputs to `/dist` alongside the main app (not a separate folder)
 
-### Externalized Dependencies (Peer Dependencies)
-
-The widget bundle does **not** include these libraries—the parent app must provide them:
+### Externalized dependencies
 
-| Package | Why Externalized |
-|---------|------------------|
-| `react`, `react-dom` | Parent's React context |
-| `@proveanything/smartlinks` | Passed via props as `SL` |
-| `@proveanything/smartlinks-auth-ui` | Auth UI components (also available globally as `window.SmartlinksAuthUI`) |
-| `tailwind-merge` | Utility for merging Tailwind classes |
-| `clsx` | Utility for conditional class names |
-| `class-variance-authority` | Utility for component variants |
+The widget bundle does **not** include the host's shared libraries (React, the SDK, Radix, LiquidJS, …) — it **externalizes** them and resolves them from the host at runtime, so the bundle stays tiny and there's exactly one shared instance.
 
-These are standard packages that any modern React + Tailwind app will have. Externalizing them:
-1. Reduces bundle size significantly
-2. Removes JSDoc comments that inflate the bundle
-3. Ensures consistent behavior with parent's versions
+**The canonical, versioned list is the shared-dependency contract — don't hand-maintain your own here.** Import it from the SDK (`SHARED_DEPENDENCY_SPECIFIERS`) for your build's `external` list, and see **[host-dependency-contract.md](host-dependency-contract.md)** for the full table, the Vite `external`/`globals` config, and the *never bundle your own React* rule. `@proveanything/smartlinks-auth-ui` is externalized too (host global `window.SmartlinksAuthUI`) — do not ship a second copy.
 
 ### Enabling Widget Builds
 
@@ -626,7 +568,7 @@ import * as SL from '@proveanything/smartlinks';
 
 // Dynamic import from app's CDN
 const CompetitionWidget = lazy(() => 
-  import('https://competition-app.example.com/widgets.es.js')
+  import('https://competition-app.example.com/widgets.esm.js')
     .then(m => ({ default: m.CompetitionWidget }))
 );
 
@@ -670,7 +612,7 @@ import { WidgetWrapper, CompetitionWidget } from 'competition-app/widgets';
 import { WIDGET_MANIFEST } from 'competition-app/widgets';
 
 // Verify React version compatibility
-if (!WIDGET_MANIFEST.reactVersion.startsWith('18')) {
+if (!WIDGET_MANIFEST.reactVersion.startsWith('19')) {
   console.warn('Widget React version mismatch');
 }
 
@@ -741,7 +683,7 @@ Each app exports a `WIDGET_MANIFEST` for discovery:
 ```typescript
 export const WIDGET_MANIFEST = {
   version: '1.0.0',        // Widget bundle version
-  reactVersion: '18.x',    // Required React version
+  reactVersion: '19.x',    // Required React version
   widgets: [
     {
       name: 'ExampleWidget',

package/dist/http.d.ts

@@ -168,22 +168,38 @@ export declare function configureSdkCache(options: {
     serveStaleOnOffline?: boolean;
     clearOnPageLoad?: boolean;
 }): void;
+/** Options for {@link invalidateCache}. */
+export interface InvalidateCacheOptions {
+    /**
+     * Match the path **exactly** (ignoring any query string) instead of the default
+     * substring match. Use this to clear one resource without wiping everything
+     * nested under it — e.g. `invalidateCache('/collection/abc', { exact: true })`
+     * drops only that entry, not `/collection/abc/settings|widgets|products|proofs`.
+     */
+    exact?: boolean;
+}
 /**
  * Manually invalidate entries in the SDK's GET cache.
  *
- * @param urlPattern - Optional substring match. Every cache entry whose key
- *   *contains* this string is removed. Omit (or pass `undefined`) to wipe the
- *   entire cache.
+ * Note: the GET cache is **in-memory, per page load** (with an optional L2
+ * IndexedDB layer when persistence is enabled) — it does not persist across
+ * reloads unless you opt into persistence, so it rarely needs disabling "for
+ * correctness".
+ *
+ * @param urlPattern - Substring match by default (every entry whose key
+ *   *contains* this string is removed). With `{ exact: true }`, matches the path
+ *   precisely. Omit to wipe the entire cache.
+ * @param options - See {@link InvalidateCacheOptions}.
  *
  * @example
  * ```ts
- * invalidateCache()                     // clear everything
- * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all legacy singular product responses
- * invalidateCache('/products/')         // all canonical plural product responses
+ * invalidateCache()                                  // clear everything
+ * invalidateCache('/collection/abc123')              // that collection AND everything under it
+ * invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry
+ * invalidateCache('/products/')                      // all canonical plural product responses
  * ```
  */
-export declare function invalidateCache(urlPattern?: string): void;
+export declare function invalidateCache(urlPattern?: string, options?: InvalidateCacheOptions): void;
 /**
  * Upload a FormData payload via proxy with progress events using chunked postMessage.
  * Parent is expected to implement the counterpart protocol.

package/dist/http.js

@@ -25,8 +25,8 @@ var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _ar
     function reject(value) { resume("throw", value); }
     function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
 };
-import { SmartlinksApiError, SmartlinksOfflineError } from "./types/error";
-import { idbGet, idbSet, idbClear } from './persistentCache';
+import { SmartlinksApiError, SmartlinksOfflineError } from "./types/error.js";
+import { idbGet, idbSet, idbClear } from './persistentCache.js';
 let baseURL = null;
 let apiKey = undefined;
 let bearerToken = undefined;
@@ -424,7 +424,7 @@ function normalizeErrorResponse(responseBody, statusCode) {
  * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
  * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
  */
-import { iframe } from './iframe';
+import { iframe } from './iframe.js';
 export function initializeApi(options) {
     var _a;
     // Normalize baseURL by removing trailing slashes.
@@ -660,29 +660,47 @@ export function configureSdkCache(options) {
 /**
  * Manually invalidate entries in the SDK's GET cache.
  *
- * @param urlPattern - Optional substring match. Every cache entry whose key
- *   *contains* this string is removed. Omit (or pass `undefined`) to wipe the
- *   entire cache.
+ * Note: the GET cache is **in-memory, per page load** (with an optional L2
+ * IndexedDB layer when persistence is enabled) — it does not persist across
+ * reloads unless you opt into persistence, so it rarely needs disabling "for
+ * correctness".
+ *
+ * @param urlPattern - Substring match by default (every entry whose key
+ *   *contains* this string is removed). With `{ exact: true }`, matches the path
+ *   precisely. Omit to wipe the entire cache.
+ * @param options - See {@link InvalidateCacheOptions}.
  *
  * @example
  * ```ts
- * invalidateCache()                     // clear everything
- * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all legacy singular product responses
- * invalidateCache('/products/')         // all canonical plural product responses
+ * invalidateCache()                                  // clear everything
+ * invalidateCache('/collection/abc123')              // that collection AND everything under it
+ * invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry
+ * invalidateCache('/products/')                      // all canonical plural product responses
  * ```
  */
-export function invalidateCache(urlPattern) {
+export function invalidateCache(urlPattern, options) {
     if (!urlPattern) {
         clearHttpCache('invalidateCache(all)');
         if (cachePersistence !== 'none')
             idbClear().catch(() => { });
         return;
     }
-    for (const key of httpCache.keys()) {
-        if (key.includes(urlPattern))
-            httpCache.delete(key);
+    if (options === null || options === void 0 ? void 0 : options.exact) {
+        const exactKey = buildCacheKey(urlPattern);
+        for (const key of httpCache.keys()) {
+            // Compare the path portion (drop query) so exact clears query variants of
+            // the same path but never sub-resources beneath it.
+            if (key.split('?')[0] === exactKey)
+                httpCache.delete(key);
+        }
+    }
+    else {
+        for (const key of httpCache.keys()) {
+            if (key.includes(urlPattern))
+                httpCache.delete(key);
+        }
     }
+    // L2 (IndexedDB) sweep remains substring-based; the exact win is the in-memory L1.
     if (cachePersistence !== 'none')
         idbClear(urlPattern).catch(() => { });
 }

package/dist/iframe.d.ts

@@ -1,5 +1,5 @@
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
-export type { IframeResponderOptions, CachedData, CollectionApp, RouteChangeMessage, SmartlinksIframeMessage, ProxyRequest, CustomProxyRequest, UploadStartMessage, UploadChunkMessage, UploadEndMessage, } from './types/iframeResponder';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
+export type { IframeResponderOptions, CachedData, CollectionApp, RouteChangeMessage, SmartlinksIframeMessage, ProxyRequest, CustomProxyRequest, UploadStartMessage, UploadChunkMessage, UploadEndMessage, } from './types/iframeResponder.js';
 export declare namespace iframe {
     interface IframeResizeOptions {
         /** Minimum ms between height postMessages (default 100). */

package/dist/iframe.js

@@ -3,7 +3,7 @@
 // These helpers are optional and safe in non-browser / Node environments.
 // They build on the existing proxyMode infrastructure but can also be used standalone.
 // Re-export IframeResponder for parent-side iframe communication
-export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
+export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
 export var iframe;
 (function (iframe) {
     let autoResizeTimer;

package/dist/iframeResponder.d.ts

@@ -1,4 +1,4 @@
-import type { IframeResponderOptions, CachedData } from './types/iframeResponder';
+import type { IframeResponderOptions, CachedData } from './types/iframeResponder.js';
 /**
  * Parent-side iframe responder for SmartLinks microapp embedding.
  *
@@ -30,6 +30,12 @@ export declare class IframeResponder {
     private iframe;
     private options;
     private cache;
+    /**
+     * Timestamp of the last anonymous (`401`) `/account` result, so a burst of
+     * "am I logged in?" checks on one page load doesn't re-hit the API 3–4 times.
+     * Only used while `cache.user` is unset; cleared the moment a login lands.
+     */
+    private lastAnonAccountAt;
     private uploads;
     private activeStreams;
     private isInitialLoad;

package/dist/iframeResponder.js

@@ -1,9 +1,9 @@
 // =============================================================================
 // IframeResponder - Parent-side iframe communication handler
 // =============================================================================
-import * as cache from './cache';
-import { collection } from './api/collection';
-import { getBaseURL } from './http';
+import * as cache from './cache.js';
+import { collection } from './api/collection.js';
+import { getBaseURL, hasAuthCredentials } from './http.js';
 /**
  * Parent-side iframe responder for SmartLinks microapp embedding.
  *
@@ -34,6 +34,12 @@ import { getBaseURL } from './http';
 export class IframeResponder {
     constructor(options) {
         this.iframe = null;
+        /**
+         * Timestamp of the last anonymous (`401`) `/account` result, so a burst of
+         * "am I logged in?" checks on one page load doesn't re-hit the API 3–4 times.
+         * Only used while `cache.user` is unset; cleared the moment a login lands.
+         */
+        this.lastAnonAccountAt = 0;
         this.uploads = new Map();
         this.activeStreams = new Map();
         this.isInitialLoad = true;
@@ -346,8 +352,10 @@ export class IframeResponder {
                     // TODO: Validate token using SDK auth utilities when available
                     // await auth.verifyToken(token);
                     await this.options.onAuthLogin(token, user, accountData);
-                    // Update cache with new user
+                    // Update cache with new user; drop any stale "anonymous" account marker
+                    // so the next check reflects the fresh login immediately.
                     this.cache.user = user;
+                    this.lastAnonAccountAt = 0;
                     this.sendResponse(event, {
                         type: 'smartlinks:authkit:login-acknowledged',
                         messageId,
@@ -414,6 +422,35 @@ export class IframeResponder {
                     return;
                 }
             }
+            // "Am I logged in?" (GET /account) with no logged-in user cached. The positive
+            // path above already served logged-in users (cache.user set).
+            if (proxyData.method === 'GET' && path.includes('/account') && !this.cache.user) {
+                const notAuthenticated = () => {
+                    response.statusCode = 401;
+                    response.error = 'Not authenticated';
+                    response.errorBody = { account: null, errorCode: 'NOT_AUTHENTICATED' };
+                    this.sendResponse(event, response);
+                };
+                // Pre-emptive gate: will this request carry ANY credential the server could
+                // validate? The portal authenticates by bearer token (not cookie), and the
+                // proxy fetch forwards no cookie, so if neither the parent SDK nor the
+                // forwarded headers carry a token, the call is provably pointless — answer
+                // "not authenticated" locally, zero network calls.
+                const headers = (proxyData.headers || {});
+                const hasHeaderAuth = Object.keys(headers).some((k) => k.toLowerCase() === 'authorization' && !!headers[k]);
+                if (!hasAuthCredentials() && !hasHeaderAuth) {
+                    notAuthenticated();
+                    return;
+                }
+                // A credential IS present but no user is cached (e.g. an expired token):
+                // the first check goes to the network, then its 401 is remembered briefly
+                // so repeat checks in the same page load don't re-hit the API.
+                const ANON_ACCOUNT_TTL_MS = 30000;
+                if (this.lastAnonAccountAt && Date.now() - this.lastAnonAccountAt < ANON_ACCOUNT_TTL_MS) {
+                    notAuthenticated();
+                    return;
+                }
+            }
             // Forward to actual API using SDK's configured baseURL
             const baseUrl = getBaseURL();
             if (!baseUrl) {
@@ -434,6 +471,10 @@ export class IframeResponder {
                 response.error = (responseData === null || responseData === void 0 ? void 0 : responseData.message) || (responseData === null || responseData === void 0 ? void 0 : responseData.errorText) || `Request failed with status ${fetchResponse.status}`;
                 response.statusCode = fetchResponse.status;
                 response.errorBody = responseData;
+                // Remember an anonymous /account result so repeat checks skip the network.
+                if (fetchResponse.status === 401 && path.includes('/account') && !this.cache.user) {
+                    this.lastAnonAccountAt = Date.now();
+                }
             }
             else {
                 response.data = responseData;