@proveanything/smartlinks 1.3.46 → 1.4.1

package/dist/api/auth.d.ts

@@ -92,6 +92,12 @@ export declare namespace auth {
     /**
      * 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.
      */
     function getAccount(): Promise<AccountInfoResponse>;
 }

package/dist/api/auth.js

@@ -1,4 +1,5 @@
-import { post, request, setBearerToken, getApiHeaders } from "../http";
+import { post, request, setBearerToken, getApiHeaders, hasAuthCredentials } from "../http";
+import { SmartlinksApiError } from "../types/error";
 /*
   user: Record<string, any>
   owner: Record<string, any>
@@ -84,8 +85,17 @@ export var auth;
     /**
      * 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.
      */
     async function getAccount() {
+        if (!hasAuthCredentials()) {
+            throw new SmartlinksApiError('Not authenticated: no bearer token or API key is set.', 401, { code: 401, errorCode: 'NOT_AUTHENTICATED', message: 'Not authenticated: no bearer token or API key is set.', details: { local: true } });
+        }
         return request("/public/auth/account");
     }
     auth.getAccount = getAccount;

package/dist/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/dist/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/dist/http.d.ts

@@ -50,15 +50,88 @@ export declare function getBaseURL(): string | null;
  * ```
  */
 export declare function isInitialized(): 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.
+ *
+ * @example
+ * ```ts
+ * if (hasAuthCredentials()) {
+ *   const account = await auth.getAccount()
+ * }
+ * ```
+ */
+export declare function hasAuthCredentials(): boolean;
+/**
+ * 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.
+ *
+ * @param options.enabled             - Turn caching on/off entirely (default: `true`)
+ * @param options.ttlMs               - Default time-to-live in milliseconds (default: `60_000`).
+ *                                      Per-resource rules (collections/products → 1 h,
+ *                                      proofs → 30 s, etc.) override this value.
+ * @param options.maxEntries          - L1 LRU eviction threshold (default: `200`)
+ * @param options.persistence         - Enable IndexedDB L2 cache (`'indexeddb'`) or keep
+ *                                      in-memory only (`'none'`, default). Ignored in Node.js.
+ * @param options.persistenceTtlMs    - How long L2 entries are eligible as an offline stale
+ *                                      fallback, from the original fetch time (default: 7 days).
+ * @param options.serveStaleOnOffline - When `true` (default) and persistence is on, throw
+ *                                      `SmartlinksOfflineError` with stale data instead of
+ *                                      propagating the network error.
+ *
+ * @example
+ * ```ts
+ * // Enable IndexedDB persistence for offline support
+ * configureSdkCache({ persistence: 'indexeddb' })
+ *
+ * // Disable cache entirely in test environments
+ * configureSdkCache({ enabled: false })
+ * ```
+ */
+export declare function configureSdkCache(options: {
+    enabled?: boolean;
+    ttlMs?: number;
+    maxEntries?: number;
+    persistence?: 'none' | 'indexeddb';
+    persistenceTtlMs?: number;
+    serveStaleOnOffline?: boolean;
+}): void;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * invalidateCache()                     // clear everything
+ * invalidateCache('/collection/abc123') // one specific collection
+ * invalidateCache('/product/')          // all product responses
+ * ```
+ */
+export declare function invalidateCache(urlPattern?: string): void;
 /**
  * Upload a FormData payload via proxy with progress events using chunked postMessage.
  * Parent is expected to implement the counterpart protocol.
  */
 export declare function proxyUploadFormData<T>(path: string, formData: FormData, onProgress?: (percent: number) => void): Promise<T>;
 /**
- * Internal helper that performs a GET request to \`\${baseURL}\${path}\`,
+ * 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.
+ *
+ * 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.
  */
 export declare function request<T>(path: string): Promise<T>;
 /**