@proveanything/smartlinks-auth-ui 0.5.21 → 0.6.0

package/SDK_DEBUGGING_GUIDE.md

@@ -0,0 +1,217 @@
+# IframeResponder Debugging Guide
+
+## Issue Summary
+
+The `SmartlinksFrame` React component calls `IframeResponder.attach(iframe)` but:
+- The promise never resolves (or silently fails)
+- No `src` URL is returned to set on the iframe
+- The iframe remains empty with no content
+
+## Logs Needed
+
+Please add `console.log` statements at these key points in `iframeResponder.ts`:
+
+### 1. Constructor Initialization
+
+```typescript
+constructor(options: IframeResponderOptions) {
+  console.log('[IframeResponder] Constructor called', {
+    collectionId: options.collectionId,
+    appId: options.appId,
+    productId: options.productId,
+    hasCache: !!options.cache,
+    hasCachedApps: !!options.cache?.apps,
+  });
+  
+  this.options = options;
+  this.cache = options.cache;
+  this.resolveReady = null;
+  this.ready = new Promise((resolve) => {
+    this.resolveReady = resolve;
+  });
+
+  // After resolveAppUrl() is called:
+  this.resolveAppUrl()
+    .then(() => {
+      console.log('[IframeResponder] App URL resolved successfully:', this.appUrl);
+      this.resolveReady?.();
+    })
+    .catch((err) => {
+      console.error('[IframeResponder] App URL resolution failed:', err);
+      // Make sure this error is propagated!
+    });
+}
+```
+
+### 2. resolveAppUrl Method
+
+```typescript
+private async resolveAppUrl(): Promise<void> {
+  console.log('[IframeResponder] resolveAppUrl started');
+
+  // Check cache first
+  const cachedApps = this.cache.apps;
+  if (cachedApps) {
+    console.log('[IframeResponder] Found cached apps:', cachedApps.length);
+    const app = cachedApps.find(a => a.id === this.options.appId);
+    if (app) {
+      this.appUrl = this.getVersionUrl(app);
+      console.log('[IframeResponder] Using cached app URL:', this.appUrl);
+      return;
+    }
+    console.log('[IframeResponder] App not found in cache, fetching from API');
+  }
+
+  // Fetch from API
+  try {
+    console.log('[IframeResponder] Calling cache.getOrFetch for apps');
+    const apps = await cache.getOrFetch<CollectionApp[]>(
+      `apps:${this.options.collectionId}`,
+      () => this.fetchApps(),
+      { ttl: 5 * 60 * 1000, storage: 'session' }
+    );
+    
+    console.log('[IframeResponder] Got apps from API:', apps?.length, apps);
+    
+    const app = apps.find(a => a.id === this.options.appId);
+    if (!app) {
+      console.error('[IframeResponder] App not found:', this.options.appId, 'Available:', apps.map(a => a.id));
+      throw new Error(`App "${this.options.appId}" not found in collection`);
+    }
+    
+    this.appUrl = this.getVersionUrl(app);
+    console.log('[IframeResponder] Resolved app URL:', this.appUrl);
+  } catch (err) {
+    console.error('[IframeResponder] resolveAppUrl error:', err);
+    this.options.onError?.(err);
+    throw err;
+  }
+}
+```
+
+### 3. fetchApps Method
+
+```typescript
+private async fetchApps(): Promise<CollectionApp[]> {
+  const url = `/api/v1/public/collection/${this.options.collectionId}/apps`;
+  console.log('[IframeResponder] Fetching apps from:', url);
+  
+  try {
+    const response = await fetch(url);
+    console.log('[IframeResponder] Fetch response status:', response.status);
+    
+    if (!response.ok) {
+      const text = await response.text();
+      console.error('[IframeResponder] Fetch failed:', response.status, text);
+      throw new Error(`Failed to fetch apps: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    console.log('[IframeResponder] Fetch response data:', data);
+    return data.items || data;
+  } catch (err) {
+    console.error('[IframeResponder] fetchApps exception:', err);
+    throw err;
+  }
+}
+```
+
+### 4. attach Method
+
+```typescript
+async attach(iframe: HTMLIFrameElement): Promise<string> {
+  console.log('[IframeResponder] attach() called, waiting for ready...');
+  
+  await this.ready;
+  
+  console.log('[IframeResponder] Ready resolved, appUrl:', this.appUrl);
+  
+  this.iframe = iframe;
+  
+  // Set up listeners...
+  
+  const src = this.buildIframeSrc();
+  console.log('[IframeResponder] Built iframe src:', src);
+  
+  return src;
+}
+```
+
+### 5. buildIframeSrc Method
+
+```typescript
+private buildIframeSrc(): string {
+  console.log('[IframeResponder] buildIframeSrc called, appUrl:', this.appUrl);
+  
+  if (!this.appUrl) {
+    console.error('[IframeResponder] Cannot build src - appUrl is null!');
+    throw new Error('App URL not resolved');
+  }
+  
+  const { collectionId, appId, productId } = this.options;
+  const { origin: base, hashPath } = new URL(this.appUrl);
+
+  const params = new URLSearchParams({
+    collectionId,
+    appId,
+  });
+
+  if (productId) {
+    params.append('productId', productId);
+  }
+  
+  const finalUrl = `${base}/#/${hashPath}?${params.toString()}`;
+  console.log('[IframeResponder] Final iframe URL:', finalUrl);
+  return finalUrl;
+}
+```
+
+## What We Need to See
+
+1. **Does the constructor complete?** - "Constructor called" log
+2. **Does URL resolution start?** - "resolveAppUrl started" log
+3. **Is the API called?** - "Fetching apps from" log
+4. **Does the API respond?** - "Fetch response status" log
+5. **Is the app found?** - "Resolved app URL" log
+6. **Does attach wait properly?** - "attach() called" and "Ready resolved" logs
+7. **Is the src built?** - "Built iframe src" log
+
+## Likely Failure Points
+
+Based on symptoms (no logs after "Initializing"), the issue is probably:
+
+1. **`this.ready` promise never resolves** - `resolveAppUrl()` fails silently or hangs
+2. **API fetch hangs** - CORS issue, wrong URL, or network timeout
+3. **cache.getOrFetch hangs** - Storage access issue or internal error
+4. **Error swallowed** - An error occurs but isn't logged/propagated
+
+## Quick Test
+
+Add this to verify the SDK is working at all:
+
+```typescript
+// In IframeResponder constructor
+console.log('[IframeResponder] SDK version check:', {
+  hasCache: typeof cache !== 'undefined',
+  hasCacheGetOrFetch: typeof cache?.getOrFetch === 'function',
+});
+```
+
+## Expected Console Output (Happy Path)
+
+```
+[IframeResponder] Constructor called { collectionId: "power-pop", appId: "dynamicPage" }
+[IframeResponder] resolveAppUrl started
+[IframeResponder] Calling cache.getOrFetch for apps
+[IframeResponder] Fetching apps from: /api/v1/public/collection/power-pop/apps
+[IframeResponder] Fetch response status: 200
+[IframeResponder] Fetch response data: { items: [...] }
+[IframeResponder] Got apps from API: 5
+[IframeResponder] Resolved app URL: https://my-app.lovable.app
+[IframeResponder] App URL resolved successfully: https://my-app.lovable.app
+[IframeResponder] attach() called, waiting for ready...
+[IframeResponder] Ready resolved, appUrl: https://my-app.lovable.app
+[IframeResponder] Built iframe src: https://my-app.lovable.app/#/?collectionId=power-pop&appId=dynamicPage
+```
+
+If any of these logs are missing, that tells us where it's failing.

package/SMARTLINKS_FRAME.md

@@ -0,0 +1,302 @@
+# SmartlinksFrame Component
+
+React component for embedding SmartLinks microapps with automatic URL resolution, API proxying, authentication sync, and deep linking.
+
+## Installation
+
+The component is part of the auth-module and requires `@proveanything/smartlinks` SDK v1.4+:
+
+```bash
+npm install @proveanything/smartlinks
+```
+
+## Quick Start
+
+```tsx
+import { SmartlinksFrame } from '@smartlinks/auth-module';
+
+// URL is auto-resolved from collection.getAppsConfig()
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="warranty-registration"
+  productId="wine-bottle-123"
+/>
+```
+
+## Features
+
+- **Automatic URL Resolution** - Fetches app config from collection and resolves the correct iframe 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 via AuthProvider
+- **Deep Linking** - Synchronizes iframe routes with parent URL state
+- **Responsive Sizing** - Automatically adjusts iframe height to content
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `collectionId` | `string` | ✅ | Collection context |
+| `appId` | `string` | ✅ | App to load (e.g., 'warranty-registration') |
+| `productId` | `string` | | Product context |
+| `proofId` | `string` | | Proof context |
+| `appUrl` | `string` | | Override URL (for local development) |
+| `version` | `'stable' \| 'development'` | | App version (default: 'stable') |
+| `collection` | `object` | | Pre-cached collection data |
+| `product` | `object` | | Pre-cached product data |
+| `proof` | `object` | | Pre-cached proof data |
+| `initialPath` | `string` | | Initial hash path (e.g., '/settings') |
+| `onRouteChange` | `(path, state) => void` | | Called when iframe route changes |
+| `autoResize` | `boolean` | | Auto-adjust height (default: true) |
+| `minHeight` | `number` | | Minimum height in pixels |
+| `maxHeight` | `number` | | Maximum height in pixels |
+| `onReady` | `() => void` | | Called when iframe loads |
+| `onError` | `(error) => void` | | Called on errors |
+| `className` | `string` | | Container CSS class |
+| `style` | `CSSProperties` | | Container inline styles |
+
+## Usage Examples
+
+### Basic Embedding
+
+```tsx
+// App URL resolved automatically from collection apps config
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="warranty"
+  productId="cabernet-2023"
+/>
+```
+
+### With Pre-fetched Data (Faster Loading)
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import * as smartlinks from '@proveanything/smartlinks';
+
+const { data: collection } = useQuery(
+  ['collection', collectionId],
+  () => smartlinks.collection.get(collectionId)
+);
+
+const { data: product } = useQuery(
+  ['product', productId],
+  () => smartlinks.product.get(productId)
+);
+
+<SmartlinksFrame
+  collectionId={collectionId}
+  appId="warranty"
+  productId={productId}
+  collection={collection}
+  product={product}
+/>
+```
+
+### With AuthProvider (Recommended)
+
+When wrapped in `AuthProvider`, authentication is automatically synced:
+
+```tsx
+import { AuthProvider, SmartlinksFrame } from '@smartlinks/auth-module';
+
+<AuthProvider>
+  <SmartlinksFrame
+    collectionId="acme-wines"
+    appId="warranty"
+  />
+</AuthProvider>
+```
+
+### Local Development Override
+
+```tsx
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="warranty"
+  appUrl="http://localhost:5173"
+  version="development"
+/>
+```
+
+### Deep Linking
+
+```tsx
+<SmartlinksFrame
+  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);
+  }}
+/>
+```
+
+### Responsive Height with Constraints
+
+```tsx
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="warranty"
+  autoResize={true}
+  minHeight={400}
+  maxHeight={800}
+/>
+```
+
+## Authentication Integration
+
+The component automatically integrates with `AuthProvider`:
+
+1. **Admin Detection**: Uses `isAdminFromRoles()` to detect admin status from collection/proof roles
+2. **Login Sync**: When iframe triggers login, calls `AuthProvider.login()` to sync session
+3. **Logout Sync**: When iframe triggers logout, calls `AuthProvider.logout()`
+
+### Without AuthProvider
+
+Works in anonymous mode - API requests still proxied, but no auth sync:
+
+```tsx
+// No AuthProvider wrapper - works but no login/logout sync
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="public-app"
+/>
+```
+
+## SDK Helpers
+
+The component uses these SDK functions internally (also exported for direct use):
+
+### `isAdminFromRoles(user, collection, proof?)`
+
+```tsx
+import { isAdminFromRoles } from '@smartlinks/auth-module';
+// or
+import { isAdminFromRoles } from '@proveanything/smartlinks';
+
+const isAdmin = isAdminFromRoles(user, collection);
+```
+
+### `buildIframeSrc(options)`
+
+Manually construct iframe URL:
+
+```tsx
+import { buildIframeSrc } from '@smartlinks/auth-module';
+
+const src = buildIframeSrc({
+  appUrl: 'https://warranty.lovable.app',
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  productId: 'wine-123',
+  isAdmin: false,
+  dark: true,
+  theme: { primary: '#FF6B6B' },
+  initialPath: '/register',
+});
+```
+
+## Caching
+
+The SDK caches app configuration to avoid redundant API calls:
+
+```tsx
+import * as smartlinks from '@proveanything/smartlinks';
+
+// Apps cached for 5 minutes in sessionStorage
+const apps = await smartlinks.cache.getOrFetch(
+  `apps:${collectionId}`,
+  () => smartlinks.collection.getAppsConfig(collectionId),
+  { ttl: 5 * 60 * 1000, storage: 'session' }
+);
+
+// Invalidate cache
+smartlinks.cache.invalidate(`apps:${collectionId}`);
+
+// Clear all cache
+smartlinks.cache.clear();
+```
+
+## Migration from Direct IframeResponder
+
+If you were using `IframeResponder` directly, the React component handles everything:
+
+```tsx
+// BEFORE: Manual IframeResponder usage
+const responder = new smartlinks.IframeResponder({
+  collectionId: 'acme-wines',
+  appId: 'warranty',
+  onAuthLogin: async (token, user) => {
+    smartlinks.setBearerToken(token);
+  },
+  onResize: (h) => {
+    iframe.style.height = `${h}px`;
+  },
+});
+const src = await responder.attach(iframe);
+
+// AFTER: React component handles everything
+<SmartlinksFrame
+  collectionId="acme-wines"
+  appId="warranty"
+/>
+```
+
+## Backend Requirements
+
+The SDK expects this endpoint to be available:
+
+```
+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 URL auto-resolution to work.
+
+## Troubleshooting
+
+### App not loading
+- Verify the appId exists in collection apps configuration
+- Check browser console for errors
+- Ensure `publicIframeUrl` is set in app config
+
+### Authentication not syncing
+- Wrap component in `AuthProvider`
+- Check that auth messages are being received
+- Verify `onAuthLogin` is being called
+
+### Height not updating
+- Ensure `autoResize={true}` (default)
+- Check that iframe is sending resize messages
+- Try setting explicit `minHeight`/`maxHeight`
+
+### URL not resolving
+- Provide explicit `appUrl` prop as fallback
+- Verify backend `/apps-config` endpoint is available
+- Check network tab for API errors