@proveanything/smartlinks 1.3.8 → 1.3.9

package/dist/docs/iframe-responder.md

@@ -0,0 +1,463 @@
+# IframeResponder - Parent-Side Iframe Communication
+
+The `IframeResponder` enables bidirectional communication between a parent application and an embedded iframe, both using the SmartLinks SDK. This allows seamless integration of microapps within your application with automatic API proxying, authentication sync, and deep linking.
+
+## Features
+
+- **Automatic URL Resolution** - Fetches app configuration from collection and resolves the correct URL
+- **API Request Proxying** - Forwards API requests from iframe to parent's authenticated session
+- **Smart Caching** - Reduces API calls by serving cached collection, product, and proof data
+- **Authentication Sync** - Handles login/logout events between parent and iframe
+- **Deep Linking** - Synchronizes iframe routes with parent URL state
+- **Responsive Sizing** - Calculates and reports optimal iframe dimensions
+- **Chunked File Uploads** - Proxies large file uploads through the parent
+
+## Basic Usage
+
+### 1. Create and Attach Responder
+
+```typescript
+import * as smartlinks from '@proveanything/smartlinks';
+
+// Initialize SDK
+smartlinks.initializeApi({
+  baseURL: 'https://api.smartlinks.io',
+  apiKey: 'your-api-key',
+});
+
+// Create responder (URL resolved automatically from collection apps)
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty-registration',
+  productId: 'wine-bottle-123', // Optional context
+  onAuthLogin: async (token, user) => {
+    // Handle authentication from iframe
+    smartlinks.setBearerToken(token);
+    console.log('User logged in:', user);
+  },
+  onResize: (height) => {
+    // Update iframe height
+    iframeElement.style.height = `${height}px`;
+  },
+});
+
+// Attach to iframe element
+const iframe = document.getElementById('app-iframe') as HTMLIFrameElement;
+const src = await responder.attach(iframe);
+iframe.src = src;
+
+// Cleanup when done
+// responder.destroy();
+```
+
+### 2. With Pre-cached Data (Faster Loading)
+
+```typescript
+// Fetch data upfront
+const collection = await smartlinks.collection.get('acme-wines');
+const product = await smartlinks.product.get('wine-bottle-123');
+const user = await smartlinks.auth.getAccountInfo();
+
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty-registration',
+  productId: 'wine-bottle-123',
+  
+  // Pre-populate cache for instant API responses
+  cache: {
+    collection,
+    product,
+    user: user ? {
+      uid: user.uid,
+      email: user.email,
+      displayName: user.displayName,
+      accountData: user.accountData,
+    } : null,
+  },
+  
+  onAuthLogin: async (token, user) => {
+    smartlinks.setBearerToken(token);
+  },
+});
+
+const src = await responder.attach(iframeElement);
+iframeElement.src = src;
+```
+
+## Configuration Options
+
+### IframeResponderOptions
+
+```typescript
+interface IframeResponderOptions {
+  // Required
+  collectionId: string;        // Collection context
+  appId: string;                // App to load (e.g., 'warranty-registration')
+  
+  // Optional Context
+  productId?: string;           // Product context
+  proofId?: string;             // Proof context
+  isAdmin?: boolean;            // Admin mode flag
+  
+  // URL Configuration
+  version?: 'stable' | 'development'; // App version (default: 'stable')
+  appUrl?: string;              // Override URL (for local dev)
+  initialPath?: string;         // Initial hash path (e.g., '/settings')
+  
+  // Data
+  cache?: CachedData;           // Pre-cached data
+  
+  // Callbacks
+  onAuthLogin?: (token: string, user: any, accountData?: any) => Promise<void>;
+  onAuthLogout?: () => Promise<void>;
+  onRouteChange?: (path: string, state: Record<string, string>) => void;
+  onResize?: (height: number) => void;
+  onError?: (error: Error) => void;
+  onReady?: () => void;
+}
+```
+
+## Advanced Examples
+
+### Deep Linking / Route Synchronization
+
+Keep the parent URL in sync with iframe navigation:
+
+```typescript
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  initialPath: '/products/wine-123',
+  
+  onRouteChange: (path, state) => {
+    // Update parent URL with iframe route
+    const url = new URL(window.location.href);
+    url.searchParams.set('app-path', path);
+    Object.entries(state).forEach(([key, value]) => {
+      url.searchParams.set(key, value);
+    });
+    window.history.pushState({}, '', url);
+  },
+});
+```
+
+### Local Development Override
+
+```typescript
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  
+  // Override URL for local development
+  appUrl: 'http://localhost:5173',
+  version: 'development',
+});
+```
+
+### Admin Mode with Role Detection
+
+```typescript
+const user = await smartlinks.auth.getAccountInfo();
+const collection = await smartlinks.collection.get('acme-wines');
+
+const isAdmin = smartlinks.isAdminFromRoles(user, collection);
+
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  isAdmin, // Pass admin status to iframe
+  cache: { collection, user },
+});
+```
+
+### Responsive Height Management
+
+```typescript
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  
+  onResize: (height) => {
+    // Smooth height transitions
+    iframe.style.transition = 'height 0.3s ease';
+    iframe.style.height = `${height}px`;
+    
+    // Or calculate viewport-based height
+    const maxHeight = window.innerHeight - 100;
+    iframe.style.height = `${Math.min(height, maxHeight)}px`;
+  },
+});
+```
+
+## Helper Functions
+
+### buildIframeSrc()
+
+Manually construct an iframe src URL without using the full responder:
+
+```typescript
+const src = smartlinks.buildIframeSrc({
+  appUrl: 'https://warranty.lovable.app',
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  productId: 'wine-123',
+  isAdmin: false,
+  dark: true,
+  theme: {
+    primary: '#FF6B6B',
+    secondary: '#4ECDC4',
+  },
+  initialPath: '/register',
+});
+
+iframe.src = src;
+```
+
+### isAdminFromRoles()
+
+Check if a user has admin access:
+
+```typescript
+const user = await smartlinks.auth.getAccountInfo();
+const collection = await smartlinks.collection.get('acme-wines');
+
+const isAdmin = smartlinks.isAdminFromRoles(user, collection);
+// or with proof
+const isAdminOfProof = smartlinks.isAdminFromRoles(user, collection, proof);
+```
+
+## Cache Utilities
+
+The `cache` module provides TTL-based caching:
+
+```typescript
+import * as smartlinks from '@proveanything/smartlinks';
+
+// Cache with 5-minute TTL
+const apps = await smartlinks.cache.getOrFetch(
+  'apps:acme-wines',
+  () => smartlinks.collection.getApps('acme-wines'),
+  { ttl: 5 * 60 * 1000, storage: 'session' }
+);
+
+// Invalidate cache
+smartlinks.cache.invalidate('apps:acme-wines');
+
+// Clear all cache
+smartlinks.cache.clear();
+```
+
+### Cache Storage Options
+
+- `memory` - In-memory only (default, cleared on page reload)
+- `session` - sessionStorage (persists across page reloads in same tab)
+- `local` - localStorage (persists across browser sessions)
+
+## Backend API Requirement
+
+The SDK uses the existing `getAppsConfig()` endpoint:
+
+```
+GET /public/collection/:collectionId/apps-config
+
+Response:
+{
+  "apps": [
+    {
+      "id": "warranty-registration",
+      "srcAppId": "warranty-v2",
+      "name": "Warranty Registration",
+      "publicIframeUrl": "https://warranty.lovable.app",
+      "active": true,
+      "category": "Commerce",
+      "usage": {
+        "collection": true,
+        "product": true,
+        "proof": false,
+        "widget": false
+      }
+    }
+  ]
+}
+```
+
+Each app must have a `publicIframeUrl` configured for the IframeResponder to work.
+
+## Complete Integration Example
+
+```typescript
+import * as smartlinks from '@proveanything/smartlinks';
+
+// Initialize SDK
+smartlinks.initializeApi({
+  baseURL: 'https://api.smartlinks.io',
+  apiKey: 'your-api-key',
+});
+
+class AppManager {
+  private responder: smartlinks.IframeResponder | null = null;
+  
+  async loadApp(containerId: string) {
+    // Create iframe
+    const iframe = document.createElement('iframe');
+    iframe.style.width = '100%';
+    iframe.style.border = 'none';
+    document.getElementById(containerId)?.appendChild(iframe);
+    
+    // Fetch context data
+    const collection = await smartlinks.collection.get('acme-wines');
+    const product = await smartlinks.product.get('wine-123');
+    
+    // Determine admin status
+    try {
+      const user = await smartlinks.auth.getAccountInfo();
+      const isAdmin = smartlinks.isAdminFromRoles(user, collection);
+      
+      // Create responder
+      this.responder = new smartlinks.IframeResponder({
+        collectionId: 'acme-wines',
+        appId: 'warranty',
+        productId: 'wine-123',
+        isAdmin,
+        cache: { collection, product, user },
+        
+        onAuthLogin: async (token, user) => {
+          smartlinks.setBearerToken(token);
+          this.responder?.updateCache({ user });
+        },
+        
+        onAuthLogout: async () => {
+          smartlinks.setBearerToken('');
+          this.responder?.updateCache({ user: null });
+        },
+        
+        onRouteChange: (path, state) => {
+          console.log('Route changed:', path, state);
+        },
+        
+        onResize: (height) => {
+          iframe.style.height = `${height}px`;
+        },
+        
+        onError: (error) => {
+          console.error('Iframe error:', error);
+        },
+      });
+      
+      // Attach and load
+      const src = await this.responder.attach(iframe);
+      iframe.src = src;
+      
+    } catch (err) {
+      console.error('Failed to load app:', err);
+    }
+  }
+  
+  destroy() {
+    this.responder?.destroy();
+    this.responder = null;
+  }
+}
+
+// Usage
+const manager = new AppManager();
+await manager.loadApp('app-container');
+
+// Cleanup on unmount
+// manager.destroy();
+```
+
+## Message Protocol
+
+The responder handles these message types from the iframe:
+
+### Route Changes
+```typescript
+{
+  type: 'smartlinks-route-change',
+  path: '/products/wine-123',
+  context: { collectionId: 'acme-wines', appId: 'warranty' },
+  state: { tab: 'details' }
+}
+```
+
+### Resize Events
+```typescript
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:resize',
+  payload: { height: 800 }
+}
+```
+
+### Authentication
+```typescript
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login',
+  payload: { token: '...', user: {...}, messageId: 'abc123' }
+}
+```
+
+### API Proxy
+```typescript
+{
+  _smartlinksProxyRequest: true,
+  id: 'req-123',
+  method: 'GET',
+  path: 'public/product/wine-123',
+  headers: { 'Authorization': 'Bearer ...' }
+}
+```
+
+## TypeScript Support
+
+All types are exported for full TypeScript support:
+
+```typescript
+import type {
+  IframeResponderOptions,
+  CachedData,
+  CollectionApp,
+  RouteChangeMessage,
+  SmartlinksIframeMessage,
+} from '@proveanything/smartlinks';
+```
+
+## Browser Compatibility
+
+- Modern browsers with ES6+ support
+- Requires `postMessage`, `MessageEvent`, `ResizeObserver` APIs
+- Falls back gracefully in Node.js environments (no-ops for browser-only features)
+
+## Best Practices
+
+1. **Pre-cache data** when possible to eliminate loading delays
+2. **Handle onError** to catch and log communication issues
+3. **Clean up** responder with `destroy()` when unmounting
+4. **Use version control** to test against development versions
+5. **Validate tokens** server-side for security
+6. **Set height dynamically** based on content using `onResize`
+7. **Sync routes** with parent navigation for better UX
+
+## Troubleshooting
+
+### App not loading
+- Verify the appId exists in collection apps configuration
+- Check browser console for errors
+- Ensure backend API endpoint is available
+
+### Authentication not syncing
+- Implement `onAuthLogin` callback
+- Verify token is being set with `setBearerToken()`
+- Check that auth messages are being received
+
+### Height not updating
+- Implement `onResize` callback
+- Ensure iframe has CSS styling for height changes
+- Check that iframe is sending resize messages
+
+### Cache not working
+- Verify cache storage option is supported (sessionStorage/localStorage)
+- Check browser storage isn't disabled
+- Clear cache and retry with `smartlinks.cache.clear()`

package/dist/iframe.d.ts

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

package/dist/iframe.js

@@ -2,6 +2,8 @@
 // Utilities to communicate with parent window when running inside an iframe.
 // 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 var iframe;
 (function (iframe) {
     let autoResizeTimer;

package/dist/iframeResponder.d.ts

@@ -0,0 +1,93 @@
+import type { IframeResponderOptions, CachedData } from './types/iframeResponder';
+/**
+ * Parent-side iframe responder for SmartLinks microapp embedding.
+ *
+ * Handles all bidirectional communication with embedded iframes:
+ * - API proxy requests (with caching)
+ * - Authentication state synchronization
+ * - Deep linking / route changes
+ * - Resize management
+ * - Chunked file upload proxying
+ *
+ * @example
+ * ```typescript
+ * const responder = new IframeResponder({
+ *   collectionId: 'my-collection',
+ *   appId: 'warranty',
+ *   onAuthLogin: async (token, user) => {
+ *     smartlinks.setBearerToken(token);
+ *   },
+ * });
+ *
+ * const src = await responder.attach(iframeElement);
+ * iframeElement.src = src;
+ *
+ * // Cleanup
+ * responder.destroy();
+ * ```
+ */
+export declare class IframeResponder {
+    private iframe;
+    private options;
+    private cache;
+    private uploads;
+    private isInitialLoad;
+    private messageHandler;
+    private resizeHandler;
+    private appUrl;
+    private ready;
+    private resolveReady;
+    constructor(options: IframeResponderOptions);
+    /**
+     * Attach to an iframe element.
+     * Returns the src URL to set on the iframe.
+     */
+    attach(iframe: HTMLIFrameElement): Promise<string>;
+    /**
+     * Update cached data (e.g., after user logs in).
+     */
+    updateCache(data: Partial<CachedData>): void;
+    /**
+     * Cleanup - remove event listeners and clear state.
+     */
+    destroy(): void;
+    private resolveAppUrl;
+    private getVersionUrl;
+    private buildIframeSrc;
+    private calculateViewportHeight;
+    private handleMessage;
+    private handleRouteChange;
+    private handleStandardMessage;
+    private handleProxyRequest;
+    private getCachedResponse;
+    private handleUpload;
+    private sendResponse;
+}
+/**
+ * Determine admin status from collection/proof roles.
+ */
+export declare function isAdminFromRoles(user: {
+    uid: string;
+} | null | undefined, collection?: {
+    roles?: Record<string, any>;
+}, proof?: {
+    roles?: Record<string, any>;
+}): boolean;
+/**
+ * Build iframe src URL with all context params.
+ * Standalone helper for cases where you don't need the full IframeResponder.
+ */
+export declare function buildIframeSrc(options: {
+    appUrl: string;
+    collectionId: string;
+    appId: string;
+    productId?: string;
+    proofId?: string;
+    isAdmin?: boolean;
+    dark?: boolean;
+    theme?: {
+        primary?: string;
+        secondary?: string;
+    };
+    initialPath?: string;
+}): string;