@proveanything/smartlinks-auth-ui 0.5.21 → 0.6.0

package/CUSTOMIZATION_GUIDE.md

@@ -0,0 +1,411 @@
+# UI Customization Guide
+
+The Smartlinks Auth UI module supports flexible customization through a hybrid API-based and props-based approach. This allows you to maintain consistent branding across multiple applications while still allowing per-instance overrides.
+
+## ⚠️ Important: CSS Import Required
+
+Before using any components, you **must** import the CSS file in your application:
+
+```tsx
+import '@smartlinks/auth-ui/dist/index.css';
+```
+
+Add this import to your app's entry point (e.g., `main.tsx`, `index.tsx`, or `App.tsx`).
+
+**Without this CSS import, the authentication UI will appear unstyled.**
+
+### CSS Override and Customization
+
+The module's CSS uses scoped class names (`.auth-*`) and CSS custom properties (CSS variables) to allow easy customization without style conflicts. You can:
+
+1. **Override CSS variables** for quick theming (see below)
+2. **Override specific classes** in your own stylesheet after importing the module CSS
+3. **Use the `customization` prop** to configure colors, fonts, and branding via the component API
+
+## Quick Start
+
+### Option 1: Props-Based Customization (Simplest)
+
+Pass customization directly as props:
+
+```tsx
+import { FirebaseAuthUI } from '@your-org/smartlinks-auth-ui';
+
+function App() {
+  return (
+    <FirebaseAuthUI
+      apiEndpoint="https://api.smartlinks.com/api/v1/authkit"
+      customization={{
+        logoUrl: "https://cdn.acme.com/logo.png",
+        title: "Welcome to Acme",
+        subtitle: "Sign in to continue",
+        primaryColor: "#6366f1",
+        secondaryColor: "#4f46e5",
+        backgroundColor: "#f0f9ff",
+        buttonStyle: "rounded",
+        termsUrl: "https://acme.com/terms",
+        privacyUrl: "https://acme.com/privacy"
+      }}
+      skipConfigFetch={true}
+      onAuthSuccess={(token, user) => {
+        console.log('Auth success:', user);
+      }}
+    />
+  );
+}
+```
+
+### Option 2: API-Based Customization (Multi-Tenant)
+
+For multi-tenant applications, store configuration in Firestore and fetch by `clientId`:
+
+```tsx
+<FirebaseAuthUI
+  apiEndpoint="https://api.smartlinks.com/api/v1/authkit"
+  clientId="acme-corp"
+  onAuthSuccess={(token, user) => {
+    console.log('Auth success:', user);
+  }}
+/>
+```
+
+### Option 3: Hybrid (API + Props Override)
+
+Fetch base config from API but allow per-instance overrides:
+
+```tsx
+<FirebaseAuthUI
+  apiEndpoint="https://api.smartlinks.com/api/v1/authkit"
+  clientId="acme-corp"
+  customization={{
+    title: "Welcome Back!", // Override just the title
+  }}
+  onAuthSuccess={(token, user) => {
+    console.log('Auth success:', user);
+  }}
+/>
+```
+
+## Configuration Options
+
+### Available Configuration Properties
+
+```typescript
+interface AuthUIConfig {
+  branding?: {
+    logoUrl?: string;           // URL to logo image (40x40px recommended)
+    title?: string;             // Main heading text
+    subtitle?: string;          // Subheading text below title
+    primaryColor?: string;      // Primary brand color (hex)
+    secondaryColor?: string;    // Secondary brand color (hex)
+    backgroundColor?: string;   // Background gradient start color (hex)
+    buttonStyle?: 'rounded' | 'square'; // Button and card style
+    fontFamily?: string;        // Custom font family
+    inheritHostStyles?: boolean; // Use host app's CSS variables
+  };
+  signupProminence?: 'minimal' | 'balanced' | 'emphasized'; // New user journey prominence
+  customCss?: string;           // Advanced: inject custom CSS
+  termsUrl?: string;            // Link to Terms of Service
+  privacyUrl?: string;          // Link to Privacy Policy
+  supportEmail?: string;        // Support email (future use)
+}
+```
+
+### Signup Prominence
+
+The `signupProminence` option controls how prominently signup is featured relative to login. This is configured via the admin interface or programmatically:
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| `minimal` | Login is default, small "Sign up" link at bottom | Returning users, locked content |
+| `balanced` | Equal-weight toggle for Sign In / Create Account | General purpose portals |
+| `emphasized` | Signup is default, small "Sign in" link at bottom | Product claiming, onboarding flows |
+
+```tsx
+// Programmatic configuration
+<SmartlinksAuthUI
+  clientId="your-client-123"
+  signupProminence="emphasized"  // For claiming flows
+  onAuthSuccess={handleAuth}
+/>
+
+// Or via customization prop
+<SmartlinksAuthUI
+  clientId="your-client-123"
+  customization={{
+    signupProminence: 'balanced'
+  }}
+  onAuthSuccess={handleAuth}
+/>
+```
+
+## Backend Setup (API-Based Customization)
+
+### 1. Create Firestore Collection
+
+Create a collection named `auth_ui_config` in your Firebase project:
+
+```javascript
+// Document structure
+{
+  clientId: "acme-corp",
+  branding: {
+    logoUrl: "https://cdn.acme.com/logo.png",
+    title: "Welcome to Acme",
+    subtitle: "Sign in to your account",
+    primaryColor: "#6366f1",
+    secondaryColor: "#4f46e5",
+    backgroundColor: "#f0f9ff",
+    buttonStyle: "rounded",
+    fontFamily: "Inter, sans-serif"
+  },
+  customCss: null,
+  termsUrl: "https://acme.com/terms",
+  privacyUrl: "https://acme.com/privacy",
+  supportEmail: "support@acme.com",
+  updatedAt: serverTimestamp()
+}
+```
+
+### 2. Add Backend Endpoint
+
+Add the config helper and endpoint to your backend:
+
+```javascript
+// In your main Express app
+const authUIConfigRoutes = require('./backend-reference/authui-routes-custom');
+
+app.use('/api/v1/authkit', authUIConfigRoutes);
+```
+
+The endpoint `GET /api/v1/authkit/config/:clientId` will now serve configurations.
+
+### 3. Manage Configurations
+
+Use the helper functions to manage configs:
+
+```javascript
+const configHelper = require('./authui-config-helper');
+
+// Save a new config
+await configHelper.saveUIConfig('acme-corp', {
+  logoUrl: "https://cdn.acme.com/logo.png",
+  title: "Welcome to Acme",
+  primaryColor: "#6366f1",
+  // ... other options
+});
+
+// Get a config
+const config = await configHelper.getUIConfig('acme-corp');
+
+// Delete a config
+await configHelper.deleteUIConfig('acme-corp');
+```
+
+## Caching Strategy
+
+The module implements intelligent caching to optimize performance:
+
+1. **Props Override**: Always applied first (no API call)
+2. **localStorage Cache**: Checked for recently fetched configs (1 hour TTL)
+3. **Background Fetch**: Updates cache while showing cached version
+4. **API Fetch**: Only if no cache exists or cache is stale
+
+### Cache Key Format
+
+```
+auth_ui_config_{clientId}
+```
+
+### Cache Structure
+
+```json
+{
+  "config": { /* AuthUIConfig */ },
+  "timestamp": 1234567890
+}
+```
+
+### Clear Cache
+
+```javascript
+// Clear specific client cache
+localStorage.removeItem('auth_ui_config_acme-corp');
+
+// Clear all auth UI caches
+Object.keys(localStorage).forEach(key => {
+  if (key.startsWith('auth_ui_config_')) {
+    localStorage.removeItem(key);
+  }
+});
+```
+
+## Advanced Customization
+
+### Custom CSS Injection
+
+For advanced styling needs, you can inject custom CSS:
+
+```typescript
+customization={{
+  customCss: `
+    .auth-card {
+      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.15) !important;
+    }
+    
+    .auth-title {
+      font-weight: 900 !important;
+      letter-spacing: -0.02em !important;
+    }
+    
+    button[type="submit"] {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
+    }
+  `
+}}
+```
+
+⚠️ **Warning**: Custom CSS can break future updates. Use sparingly and test thoroughly.
+
+### Custom Fonts
+
+To use custom fonts:
+
+1. **Add font link** to your HTML:
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap" rel="stylesheet">
+```
+
+2. **Set in config**:
+
+```typescript
+customization={{
+  fontFamily: "'Poppins', sans-serif"
+}}
+```
+
+## Props Reference
+
+### FirebaseAuthUIProps
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `apiEndpoint` | string | Yes | - | Your API base URL |
+| `clientId` | string | No | - | Client identifier for multi-tenant |
+| `clientName` | string | No | - | Client name for branded emails |
+| `customization` | `Partial<AuthUIConfig>` | No | `{}` | UI customization overrides |
+| `skipConfigFetch` | boolean | No | `false` | Skip API config fetch |
+| `theme` | `'light' \| 'dark'` | No | `'light'` | UI theme |
+| `enabledProviders` | `AuthProvider[]` | No | `['email', 'google', 'phone']` | Auth methods |
+| `redirectUrl` | string | No | - | Post-auth redirect URL |
+| `accountData` | `Record<string, any>` | No | - | Additional account data |
+| `onAuthSuccess` | function | Yes | - | Success callback |
+| `onAuthError` | function | No | - | Error callback |
+| `className` | string | No | `''` | Additional CSS class |
+
+## Priority Order
+
+When multiple sources provide configuration, the priority is:
+
+1. **Props (`customization`)** - Highest priority
+2. **localStorage Cache** - If fresh (< 1 hour old)
+3. **API Fetch** - Fresh data from backend
+4. **Default Values** - Built-in fallbacks
+
+## Best Practices
+
+### For Single-Tenant Apps
+
+Use props-based customization with `skipConfigFetch={true}`:
+
+```tsx
+<FirebaseAuthUI
+  customization={{ /* your config */ }}
+  skipConfigFetch={true}
+  // ... other props
+/>
+```
+
+### For Multi-Tenant SaaS
+
+Use API-based with `clientId`:
+
+```tsx
+<FirebaseAuthUI
+  clientId={currentTenant.id}
+  // Config fetched automatically
+  // ... other props
+/>
+```
+
+### For White-Label Products
+
+Use API-based with props override for per-deployment customization:
+
+```tsx
+<FirebaseAuthUI
+  clientId={currentTenant.id}
+  customization={{
+    logoUrl: deploymentConfig.logoUrl // Override per deployment
+  }}
+  // ... other props
+/>
+```
+
+## Troubleshooting
+
+### Config Not Loading
+
+1. Check browser console for fetch errors
+2. Verify `clientId` is correct
+3. Check backend endpoint is accessible: `GET /api/v1/authkit/config/{clientId}`
+4. Verify Firestore collection `auth_ui_config` exists
+
+### Colors Not Applying
+
+1. Ensure color values are hex format: `#3B82F6` (not `rgb()` or color names)
+2. Check browser dev tools for CSS variable values
+3. Clear localStorage cache and refresh
+
+### Logo Not Showing
+
+1. Verify `logoUrl` is publicly accessible
+2. Check image size (40x40px recommended)
+3. Check browser console for CORS errors
+4. Ensure URL is HTTPS in production
+
+### Cache Issues
+
+Clear the cache manually:
+
+```javascript
+localStorage.removeItem(`auth_ui_config_${clientId}`);
+```
+
+## Security Considerations
+
+1. **Validate redirect URLs** on backend (already implemented)
+2. **Sanitize custom CSS** to prevent XSS (consider Content Security Policy)
+3. **Use HTTPS** for logo and asset URLs
+4. **Rate limit** config endpoint to prevent abuse
+5. **Authenticate** config management endpoints (future enhancement)
+
+## Future Enhancements
+
+Planned features:
+
+- [ ] Admin UI for managing configs
+- [ ] Theme presets (Material, iOS, etc.)
+- [ ] A/B testing support
+- [ ] Analytics integration
+- [ ] Real-time config updates
+- [ ] Config versioning and rollback
+- [ ] Visual editor with live preview
+
+## Support
+
+For issues or questions:
+- Check the [main README](./README.md)
+- Review [Integration Guide](../backend-reference/INTEGRATION_GUIDE.md)
+- Contact: support@smartlinks.com

package/README.md

@@ -289,24 +289,42 @@ The AuthProvider component manages authentication state across your application.
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `clientId` | string | **Yes** | Client identifier for your application |
-| `clientName` | string | No | Client name for branded communications |
-| `accountCacheTTL` | number | No | Account cache TTL in ms (default: 300000 / 5 min) |
-| `preloadAccountInfo` | boolean | No | Fetch account info on login (default: false) |
+| `clientId` | string | No¹ | AuthKit client identifier. **Auto-resolved** from `collection.defaultAuthKitId` when `collectionId` is provided. |
+| `collectionId` | string | No¹ | SmartLinks collection id. Enables contact sync, interaction tracking, and `clientId` auto-resolution. |
+| `proxyMode` | boolean | No | Delegate session to the parent window (iframe embeds). Default `false`. |
+| `accountCacheTTL` | number | No | Account-info cache TTL in ms (default `300_000` = 5 min). |
+| `preloadAccountInfo` | boolean | No | Fetch account info eagerly on login (default `false`). |
+| `enableAutoRefresh` | boolean | No | Background token refresh timer (default `true`). |
+| `refreshThresholdPercent` | number | No | Refresh when this % of the access-token lifetime has elapsed (default `75`). |
+| `refreshCheckInterval` | number | No | Background check interval in ms (default `60_000`). |
+| `refreshOnResume` | boolean | No | Refresh the session when the app returns to the foreground. **Default `true` on native shells** (Capacitor / `window.AuthKit.isNative`), `false` on web. Listens to `App.addListener('appStateChange')` via a dynamic `@capacitor/app` import (no web runtime dep) and to `document.visibilitychange` as a universal fallback. |
+| `enableContactSync` | boolean | No | Default `true` when `collectionId` is set. |
+| `enableInteractionTracking` | boolean | No | Default `true` when `collectionId` is set. |
+| `interactionAppId` | string | No | App id used for interaction events. |
+| `interactionConfig` | object | No | Custom interaction ids — see [`AUTH_STATE_MANAGEMENT.md`](./AUTH_STATE_MANAGEMENT.md). |
+
+¹ Either `clientId` **or** `collectionId` is required. Most apps only need `collectionId` — the kit looks up the collection's `defaultAuthKitId` and uses it for refresh-token rotation and server-side logout. See [`architecture/default-authkit-collection-property`](../.lovable/memory/architecture/default-authkit-collection-property.md).
 
 #### Example
 
 ```tsx
-<AuthProvider 
+// Minimal — clientId auto-resolved from the collection's defaultAuthKitId
+<AuthProvider collectionId="col_abc123">
+  <App />
+</AuthProvider>
+
+// Explicit clientId + long-lived native sessions
+<AuthProvider
   clientId="your-client-123"
-  clientName="Acme Corp"
-  accountCacheTTL={600000} // 10 minutes
-  preloadAccountInfo={true}
+  collectionId="col_abc123"
+  refreshOnResume                  // explicit on (auto-on under Capacitor)
+  accountCacheTTL={600_000}
 >
   <App />
 </AuthProvider>
 ```
 
+
 ### useAuth Hook
 
 Access authentication state and methods anywhere in your app:
@@ -544,6 +562,27 @@ The component automatically handles URL-based authentication flows:
 
 Authentication state automatically syncs across browser tabs using BroadcastChannel API and IndexedDB. When a user logs in or out in one tab, all other tabs update immediately.
 
+### Native / Mobile (Capacitor)
+
+The kit ships first-class support for native shells — Capacitor, Capgo, and Ionic WebView. When a native host is detected (`window.Capacitor.isNativePlatform()` or `window.AuthKit.isNative`):
+
+- **Long-lived sessions** via refresh-token rotation. Login responses carry a `refreshToken` + `refreshTokenExpiresAt`; the kit persists them next to the access JWT and calls `smartlinks.authKit.refreshToken(clientId, ...)` automatically. Reuse / invalid / expired refresh tokens force re-login.
+- **Refresh on resume.** `refreshOnResume` defaults to `true` on native, hooking `App.addListener('appStateChange')` (dynamic import — no web runtime dep) and `document.visibilitychange`. Stale sessions self-heal the moment the user reopens the app.
+- **Secure storage adapter.** Replace IndexedDB with Keychain / Keystore via `setStorageAdapter(adapter)`. See [`CAPACITOR_INTEGRATION.md`](./CAPACITOR_INTEGRATION.md) §5.
+- **Native Google / Apple Sign-In** via the unified `window.AuthKit` bridge. See [`ANDROID_NATIVE_BRIDGE.md`](./ANDROID_NATIVE_BRIDGE.md).
+
+Tell the SmartLinks SDK it's running native so refresh tokens are issued:
+
+```ts
+smartlinks.initializeApi({
+  baseURL: '…',
+  platform: 'native',   // adds X-Client-Platform: native to every request
+  persistToken: false,  // AuthKit owns persistence
+});
+```
+
+Full step-by-step (Keychain adapter, biometric gating, deep-link routing): **[`CAPACITOR_INTEGRATION.md`](./CAPACITOR_INTEGRATION.md)**. Backend contract for the refresh endpoint: **[`../backend-reference/REFRESH_TOKEN_BACKEND_SPEC.md`](../backend-reference/REFRESH_TOKEN_BACKEND_SPEC.md)**.
+
 ## TypeScript Support
 
 Full TypeScript definitions included:
@@ -558,16 +597,37 @@ import type {
   SmartlinksAuthUIProps,
   AccountManagementProps,
   ClaimField,
-  ClaimResult
+  ClaimResult,
+  PersistentStorage,
+  StorageBackend,
 } from '@smartlinks/auth-ui';
 ```
 
 ## Documentation
 
-- **[AUTH_STATE_MANAGEMENT.md](./AUTH_STATE_MANAGEMENT.md)** - Complete guide to authentication state, callbacks, and cross-tab sync
-- **[ACCOUNT_CACHING.md](./ACCOUNT_CACHING.md)** - Account information caching strategies and configuration
-- **[CUSTOMIZATION_GUIDE.md](./CUSTOMIZATION_GUIDE.md)** - Detailed customization and theming guide
-- **[SMARTLINKS_INTEGRATION.md](./SMARTLINKS_INTEGRATION.md)** - Smartlinks SDK integration details
+All guides ship inside the published package so consumers can read them locally (`node_modules/@proveanything/smartlinks-auth-ui/*.md`).
+
+### Core
+- **[AUTH_STATE_MANAGEMENT.md](./AUTH_STATE_MANAGEMENT.md)** — auth state lifecycle, `onAuthStateChange` callbacks, cross-tab sync.
+- **[ACCOUNT_CACHING.md](./ACCOUNT_CACHING.md)** — account-info caching strategy, TTLs, manual invalidation.
+- **[CUSTOMIZATION_GUIDE.md](./CUSTOMIZATION_GUIDE.md)** — theming, branding, dark mode, provider ordering, email template config.
+- **[SMARTLINKS_INTEGRATION.md](./SMARTLINKS_INTEGRATION.md)** — how the kit wires into `@proveanything/smartlinks` (token, refresh, profile, account, logout).
+
+### Native / Mobile
+- **[CAPACITOR_INTEGRATION.md](./CAPACITOR_INTEGRATION.md)** — Capacitor / Capgo setup: native platform flag, secure storage adapter, refresh-on-resume, deep-link routing, native sign-out, biometric gating.
+- **[ANDROID_NATIVE_BRIDGE.md](./ANDROID_NATIVE_BRIDGE.md)** — `window.AuthKit` bridge contract for native Google sign-in, scanner, and other host capabilities.
+
+### Specialized features
+- **[SMARTLINKS_FRAME.md](./SMARTLINKS_FRAME.md)** — `SmartlinksFrame` embed component (optional auth, iframe messaging).
+- **[WHATSAPP_OTP_PLAN.md](./WHATSAPP_OTP_PLAN.md)** — WhatsApp OTP flow and backend contract.
+- **[SDK_DEBUGGING_GUIDE.md](./SDK_DEBUGGING_GUIDE.md)** — troubleshooting SDK init, proxy mode, token storage, iframe ack flow.
+
+### Backend contracts (in `backend-reference/`)
+- **[REFRESH_TOKEN_BACKEND_SPEC.md](../backend-reference/REFRESH_TOKEN_BACKEND_SPEC.md)** — refresh-token endpoint, rotation, reuse detection, family revocation.
+- **[APPLE_SIGNIN_BACKEND_SPEC.md](../backend-reference/APPLE_SIGNIN_BACKEND_SPEC.md)** — Apple Sign-In identity-token verification contract.
+- **[ACCOUNT_MANAGEMENT_API.md](../backend-reference/ACCOUNT_MANAGEMENT_API.md)** — profile / email / password / delete endpoints used by `<AccountManagement>`.
+- **[API_DOCUMENTATION.md](../backend-reference/API_DOCUMENTATION.md)** — full AuthKit REST surface.
+
 
 ## Troubleshooting