@proveanything/smartlinks 1.3.46 → 1.4.1

package/dist/persistentCache.d.ts

@@ -0,0 +1,36 @@
+export interface PersistentCacheEntry {
+    /** The cached response data. */
+    data: any;
+    /** Unix ms timestamp of when the data was originally fetched from the network. */
+    timestamp: number;
+    /** Unix ms timestamp of when this entry was written to IndexedDB. */
+    persistedAt: number;
+}
+/**
+ * Returns true only in environments where IndexedDB is genuinely available.
+ * False in Node.js, and in some private-browsing contexts that stub indexedDB
+ * but throw on open.
+ */
+export declare function isIdbAvailable(): boolean;
+/**
+ * Read an entry from IndexedDB.
+ * Returns `null` when IDB is unavailable, the key doesn't exist, or on any error.
+ * Safe to call in Node.js — returns null immediately.
+ */
+export declare function idbGet(key: string): Promise<PersistentCacheEntry | null>;
+/**
+ * Write an entry to IndexedDB.
+ * Fails silently on quota exceeded, private browsing, or any other error.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export declare function idbSet(key: string, entry: PersistentCacheEntry): Promise<void>;
+/**
+ * Delete a single entry from IndexedDB.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export declare function idbDelete(key: string): Promise<void>;
+/**
+ * Clear all IDB entries, or only those whose key contains `pattern`.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export declare function idbClear(pattern?: string): Promise<void>;

package/dist/persistentCache.js

@@ -0,0 +1,178 @@
+// src/persistentCache.ts
+// IndexedDB-backed L2 cache for the SDK's HTTP layer.
+//
+// Every exported function is Node-safe: all IDB access is guarded by
+// isIdbAvailable() and wrapped in try/catch so that failures in private-
+// browsing, quota-exceeded situations, or server-side environments are always
+// silent — they never propagate errors to the caller.
+const DB_NAME = 'smartlinks-sdk-cache';
+const STORE_NAME = 'responses';
+const DB_VERSION = 1;
+let dbPromise = null;
+/**
+ * Returns true only in environments where IndexedDB is genuinely available.
+ * False in Node.js, and in some private-browsing contexts that stub indexedDB
+ * but throw on open.
+ */
+export function isIdbAvailable() {
+    try {
+        return typeof indexedDB !== 'undefined' && indexedDB !== null;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+function openDb() {
+    if (dbPromise)
+        return dbPromise;
+    dbPromise = new Promise((resolve, reject) => {
+        try {
+            const req = indexedDB.open(DB_NAME, DB_VERSION);
+            req.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                if (!db.objectStoreNames.contains(STORE_NAME)) {
+                    db.createObjectStore(STORE_NAME);
+                }
+            };
+            req.onsuccess = (event) => {
+                resolve(event.target.result);
+            };
+            req.onerror = () => {
+                dbPromise = null;
+                reject(req.error);
+            };
+            req.onblocked = () => {
+                dbPromise = null;
+                reject(new Error('[smartlinks] IndexedDB open blocked'));
+            };
+        }
+        catch (err) {
+            dbPromise = null;
+            reject(err);
+        }
+    });
+    return dbPromise;
+}
+/**
+ * Read an entry from IndexedDB.
+ * Returns `null` when IDB is unavailable, the key doesn't exist, or on any error.
+ * Safe to call in Node.js — returns null immediately.
+ */
+export async function idbGet(key) {
+    if (!isIdbAvailable())
+        return null;
+    try {
+        const db = await openDb();
+        return new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readonly');
+                const req = tx.objectStore(STORE_NAME).get(key);
+                req.onsuccess = () => { var _a; return resolve((_a = req.result) !== null && _a !== void 0 ? _a : null); };
+                req.onerror = () => resolve(null);
+            }
+            catch (_a) {
+                resolve(null);
+            }
+        });
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Write an entry to IndexedDB.
+ * Fails silently on quota exceeded, private browsing, or any other error.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export async function idbSet(key, entry) {
+    if (!isIdbAvailable())
+        return;
+    try {
+        const db = await openDb();
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                tx.objectStore(STORE_NAME).put(entry, key);
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => resolve(); // quota exceeded etc — fail silently
+                tx.onabort = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) {
+        // Fail silently — IDB persistence is best-effort
+    }
+}
+/**
+ * Delete a single entry from IndexedDB.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export async function idbDelete(key) {
+    if (!isIdbAvailable())
+        return;
+    try {
+        const db = await openDb();
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                tx.objectStore(STORE_NAME).delete(key);
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => resolve();
+                tx.onabort = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) { }
+}
+/**
+ * Clear all IDB entries, or only those whose key contains `pattern`.
+ * Safe to call in Node.js — no-ops immediately.
+ */
+export async function idbClear(pattern) {
+    if (!isIdbAvailable())
+        return;
+    try {
+        const db = await openDb();
+        if (!pattern) {
+            await new Promise((resolve) => {
+                try {
+                    const tx = db.transaction(STORE_NAME, 'readwrite');
+                    tx.objectStore(STORE_NAME).clear();
+                    tx.oncomplete = () => resolve();
+                    tx.onerror = () => resolve();
+                    tx.onabort = () => resolve();
+                }
+                catch (_a) {
+                    resolve();
+                }
+            });
+            return;
+        }
+        // Pattern-based: enumerate all keys and delete matching ones.
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                const store = tx.objectStore(STORE_NAME);
+                const req = store.getAllKeys();
+                req.onsuccess = () => {
+                    for (const key of req.result) {
+                        if (key.includes(pattern))
+                            store.delete(key);
+                    }
+                    resolve();
+                };
+                req.onerror = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) { }
+}

package/dist/types/error.d.ts

@@ -73,3 +73,39 @@ export declare class SmartlinksApiError extends Error {
      */
     toJSON(): Record<string, any>;
 }
+/**
+ * Thrown when a GET request fails due to network unavailability AND the
+ * persistent cache (IndexedDB) has a previously stored response for that
+ * resource. The `staleData` property contains the cached payload so the
+ * application can render in a degraded/offline state.
+ *
+ * Only thrown when persistence is enabled:
+ * `configureSdkCache({ persistence: 'indexeddb' })`
+ *
+ * @example
+ * ```ts
+ * import { SmartlinksOfflineError } from '@proveanything/smartlinks'
+ *
+ * try {
+ *   const data = await collection.get('abc123')
+ * } catch (err) {
+ *   if (err instanceof SmartlinksOfflineError) {
+ *     showOfflineBanner()
+ *     renderWithData(err.staleData) // use the cached payload
+ *   }
+ * }
+ * ```
+ */
+export declare class SmartlinksOfflineError extends Error {
+    /** The stale cached payload available when the network request failed. */
+    readonly staleData: any;
+    /** Unix ms timestamp of when the stale data was originally fetched from the server. */
+    readonly cachedAt: number;
+    constructor(message: string, 
+    /** The stale cached payload available when the network request failed. */
+    staleData: any, 
+    /** Unix ms timestamp of when the stale data was originally fetched from the server. */
+    cachedAt: number);
+    /** Age of the stale data in milliseconds at the time this error was thrown. */
+    get staleAgeMs(): number;
+}

package/dist/types/error.js

@@ -96,3 +96,45 @@ export class SmartlinksApiError extends Error {
         };
     }
 }
+/**
+ * Thrown when a GET request fails due to network unavailability AND the
+ * persistent cache (IndexedDB) has a previously stored response for that
+ * resource. The `staleData` property contains the cached payload so the
+ * application can render in a degraded/offline state.
+ *
+ * Only thrown when persistence is enabled:
+ * `configureSdkCache({ persistence: 'indexeddb' })`
+ *
+ * @example
+ * ```ts
+ * import { SmartlinksOfflineError } from '@proveanything/smartlinks'
+ *
+ * try {
+ *   const data = await collection.get('abc123')
+ * } catch (err) {
+ *   if (err instanceof SmartlinksOfflineError) {
+ *     showOfflineBanner()
+ *     renderWithData(err.staleData) // use the cached payload
+ *   }
+ * }
+ * ```
+ */
+export class SmartlinksOfflineError extends Error {
+    constructor(message, 
+    /** The stale cached payload available when the network request failed. */
+    staleData, 
+    /** Unix ms timestamp of when the stale data was originally fetched from the server. */
+    cachedAt) {
+        super(message);
+        this.staleData = staleData;
+        this.cachedAt = cachedAt;
+        this.name = 'SmartlinksOfflineError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SmartlinksOfflineError);
+        }
+    }
+    /** Age of the stale data in milliseconds at the time this error was thrown. */
+    get staleAgeMs() {
+        return Date.now() - this.cachedAt;
+    }
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.46  |  Generated: 2026-02-19T21:09:09.402Z
+Version: 1.4.1  |  Generated: 2026-02-20T19:32:34.980Z
 
 This is a concise summary of all available API functions and types.
 
@@ -18,6 +18,7 @@ For detailed guides on specific features:
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
 
 ## API Namespaces
 
@@ -108,13 +109,29 @@ Get the currently configured API base URL. Returns null if initializeApi() has n
 **isInitialized**() → `boolean`
 Returns true if initializeApi() has been called at least once. Useful for guards in widgets or shared modules that want to skip initialization when another module has already done it. ```ts if (!isInitialized()) { initializeApi({ baseURL: 'https://smartlinks.app/api/v1' }) } ```
 
+**hasAuthCredentials**() → `boolean`
+Returns true if the SDK currently has any auth credential set (bearer token or API key). Use this as a cheap pre-flight check before calling endpoints that require authentication, to avoid issuing a network request that you already know will return a 401. ```ts if (hasAuthCredentials()) { const account = await auth.getAccount() } ```
+
+**configureSdkCache**(options: {
+  enabled?: boolean
+  ttlMs?: number
+  maxEntries?: number
+  persistence?: 'none' | 'indexeddb'
+  persistenceTtlMs?: number
+  serveStaleOnOffline?: boolean
+}) → `void`
+Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) ```
+
+**invalidateCache**(urlPattern?: string) → `void`
+Manually invalidate entries in the SDK's GET cache. *contains* this string is removed. Omit (or pass `undefined`) to wipe the entire cache. ```ts invalidateCache()                     // clear everything invalidateCache('/collection/abc123') // one specific collection invalidateCache('/product/')          // all product responses ```
+
 **proxyUploadFormData**(path: string,
   formData: FormData,
   onProgress?: (percent: number) → `void`
 Upload a FormData payload via proxy with progress events using chunked postMessage. Parent is expected to implement the counterpart protocol.
 
 **request**(path: string) → `Promise<T>`
-Internal helper that performs a GET request to \`\${baseURL}\${path}\`, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
+Internal helper that performs a GET request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Cache pipeline (when caching is not skipped): L1 hit  → return from memory (no I/O) L2 hit  → return from IndexedDB, promote to L1 (no network) Miss    → fetch from network, store in L1 + L2 Offline → serve stale L2 entry via SmartlinksOfflineError (if persistence enabled) Concurrent identical GETs share one in-flight promise (deduplication). Node-safe: IndexedDB calls are no-ops when IDB is unavailable.
 
 **post**(path: string,
   body: any,
@@ -4128,7 +4145,7 @@ Tries to register a new user account. Can return a bearer token, or a Firebase t
 Admin: Get a user bearer token (impersonation/automation). POST /admin/auth/userToken All fields are optional; at least one identifier should be provided.
 
 **getAccount**() → `Promise<AccountInfoResponse>`
-Gets current account information for the logged in user. Returns user, owner, account, and location objects.
+Gets current account information for the logged in user. Returns user, owner, account, and location objects. Short-circuits immediately (no network request) when the SDK has no bearer token or API key set — the server would return 401 anyway. Throws a `SmartlinksApiError` with `statusCode 401` and `details.local = true` so callers can distinguish "never authenticated" from an actual server-side token rejection.
 
 ### authKit
 

package/docs/ai-guide-template.md

@@ -0,0 +1,241 @@
+# AI Guide: Example App
+
+<!-- CUSTOMIZE: Replace "Example App" and all content below with your app's specifics. -->
+<!-- This file is consumed by AI orchestrators alongside public/app.manifest.json. -->
+<!-- The manifest provides structured data; this file provides prose context and nuance. -->
+
+---
+
+## Purpose & Identity
+
+<!-- CUSTOMIZE: Describe what your app does in 2-3 sentences. -->
+
+The **Example App** is a template SmartLinks microapp that demonstrates all platform patterns including setup wizards, data imports, widget embedding, and analytics. It serves as a reference implementation for app authors building on the SmartLinks platform.
+
+---
+
+## Setup Wizard Instructions
+
+An AI orchestrator should follow these steps to configure the Example App for a collection. The structured questions and schema are in `app.manifest.json` under `setup`.
+
+### Prerequisites
+
+- The user must have **admin access** to the target collection.
+- The `collectionId` and `appId` must be known (typically from URL context).
+
+### Questions to Ask
+
+Walk the user through each question defined in `setup.questions[]` of the manifest:
+
+1. **App Title** (`appTitle`): Ask what the app should be called. Offer to auto-generate a suggestion using `SL.ai.chat.completions` if the user wants help (see `contentHints` in the manifest).
+2. **Enable Notifications** (`enableNotifications`): Ask whether the app should send notifications to users.
+
+<!-- CUSTOMIZE: Add app-specific guidance for each question. For example: -->
+<!-- "If the user is setting up a competition, suggest a title like 'Win a [Product Name]!'" -->
+<!-- "For plant passports, notifications are typically disabled." -->
+
+### How to Save the Config
+
+After collecting answers, validate against `setup.configSchema` and save:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: {
+    appTitle: "User's chosen title",
+    enableNotifications: false
+  },
+  admin: true  // REQUIRED for admin operations
+});
+```
+
+### Post-Setup Verification
+
+After saving, confirm by reading the config back:
+
+```typescript
+const saved = await SL.appConfiguration.getConfig({
+  collectionId,
+  appId,
+  admin: true
+});
+// Verify saved.appTitle and saved.enableNotifications match expectations
+```
+
+Tell the user: "Your app is configured! You can adjust settings anytime by asking me to update the configuration."
+
+---
+
+## Import Instructions
+
+The app supports bulk import of product-level configuration. The field definitions are in `app.manifest.json` under `import`.
+
+### CSV Template
+
+Generate or share this template with the user:
+
+```csv
+productId,appTitle,enableNotifications
+prod_001,My First Product,true
+prod_002,My Second Product,false
+```
+
+<!-- CUSTOMIZE: Add real-world examples relevant to your app. -->
+
+### Field Validation Rules
+
+| Field                 | Type    | Required | Validation                            |
+| --------------------- | ------- | -------- | ------------------------------------- |
+| `productId`           | string  | ✅       | Must be a valid SmartLinks product ID |
+| `appTitle`            | string  | ✅       | Non-empty string                      |
+| `enableNotifications` | boolean | ❌       | Defaults to `false`                   |
+
+<!-- CUSTOMIZE: Add app-specific validation rules. For example: -->
+<!-- "For plant passports: botanicalName must be in Latin binomial format." -->
+
+### API Call Sequence
+
+For each row in the CSV:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  productId: row.productId,  // From CSV
+  appId,
+  config: {
+    appTitle: row.appTitle,
+    enableNotifications: row.enableNotifications ?? false
+  },
+  admin: true
+});
+```
+
+### Error Handling
+
+- If a `productId` is invalid, log the error and continue with the next row.
+- After processing all rows, report a summary: `"Imported X of Y products successfully. Z failed."`.
+- For failed rows, list the product ID and error message so the user can fix the data.
+
+### Cross-App Import
+
+When importing data for multiple apps simultaneously:
+
+1. Fetch `app.manifest.json` from each app.
+2. Merge `import.fields` arrays (prefix field names with app name if there are conflicts).
+3. Generate a combined CSV template.
+4. For each row, split into separate payloads per app and call each app's `saveWith.method`.
+
+---
+
+## Widget Embedding Guide
+
+### Available Widgets
+
+| Widget          | Description                                | Sizes                    |
+| --------------- | ------------------------------------------ | ------------------------ |
+| `ExampleWidget` | Demo widget showing SmartLinks integration | compact, standard, large |
+
+<!-- CUSTOMIZE: List all widgets your app exports. -->
+
+### Props Reference
+
+All widgets receive `SmartLinksWidgetProps`:
+
+| Prop              | Type           | Required | Description                             |
+| ----------------- | -------------- | -------- | --------------------------------------- |
+| `collectionId`    | string         | ✅       | Collection context                      |
+| `appId`           | string         | ✅       | App identifier                          |
+| `SL`              | SmartLinks SDK | ✅       | Pre-initialized SDK instance            |
+| `productId`       | string         | ❌       | Product context                         |
+| `proofId`         | string         | ❌       | Proof context                           |
+| `user`            | object         | ❌       | Current user info                       |
+| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `publicPortalUrl` | string         | ❌       | URL to full app for deep linking        |
+| `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
+| `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
+| `translations`    | object         | ❌       | Translation overrides                   |
+
+### Example Code
+
+```tsx
+import { ExampleWidget } from '@my-app/widgets';
+
+<ExampleWidget
+  collectionId="col_123"
+  appId="example-app"
+  SL={SL}
+  size="standard"
+  onNavigate={(path) => router.push(path)}
+/>
+```
+
+<!-- CUSTOMIZE: Show real widget usage with app-specific props. -->
+
+---
+
+## Tunable Settings
+
+These settings can be adjusted after initial setup without reconfiguring everything. The AI can modify them in response to user requests like "turn off notifications" or optimization suggestions.
+
+| Setting               | Type    | Description                    |
+| --------------------- | ------- | ------------------------------ |
+| `enableNotifications` | boolean | Toggle notifications on or off |
+
+<!-- CUSTOMIZE: List all tunable fields with guidance on when to change them. -->
+
+To update a tunable setting:
+
+```typescript
+// 1. Read current config
+const current = await SL.appConfiguration.getConfig({ collectionId, appId, admin: true });
+
+// 2. Merge the change
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  config: { ...current, enableNotifications: true },
+  admin: true
+});
+```
+
+---
+
+## Metrics & Analytics
+
+### Tracked Interactions
+
+| Interaction ID | Description                                   |
+| -------------- | --------------------------------------------- |
+| `page-view`    | Tracks each time a user views the public page |
+
+<!-- CUSTOMIZE: List all interaction IDs your app tracks. -->
+
+### KPIs
+
+| KPI         | How to Compute                                                                         |
+| ----------- | -------------------------------------------------------------------------------------- |
+| Total Views | `SL.interactions.countsByOutcome(collectionId, { appId, interactionId: 'page-view' })` |
+
+<!-- CUSTOMIZE: Add app-specific KPIs and interpretation guidance. -->
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                 | Cause                      | Fix                                                   |
+| --------------------- | -------------------------- | ----------------------------------------------------- |
+| Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| 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             |
+
+<!-- CUSTOMIZE: Add app-specific troubleshooting entries. -->
+
+### Getting Help
+
+- **SDK Docs**: `node_modules/@proveanything/smartlinks/docs/`
+- **App Manifest**: `public/app.manifest.json`
+- **Platform Guide**: `src/docs/smartlinks/about.md`

package/package.json

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