@safepassage/sdk 3.4.1 → 3.4.3

package/README.md

@@ -1,22 +1,15 @@
-# SafePassage SDK v3.0.12 - Performance-Optimized
+# SafePassage SDK v3.4
 
-A lightweight SDK for integrating SafePassage age verification using a simple redirect flow.
-
-## What's New in v3.0.12
-
-- **40% faster launch times**: Removed blocking config fetch, saving 100-300ms
-- **Instant redirects**: SDK now redirects immediately without API calls
-- **Improved reliability**: Eliminates dependency on config endpoint
+A lightweight SDK for integrating SafePassage age verification into your website or application.
 
 ## Features
 
-- **Ultra-lightweight**: 17.6KB minified
-- **Instant verification**: No blocking API calls during launch
-- **Simple integration**: Just 10 lines of code
+- **Ultra-lightweight**: ~18KB minified
+- **Simple integration**: 5 lines of code to get started
 - **Two modes**: Same-tab redirect or new-tab popup
 - **TypeScript support**: Full type definitions included
-- **Auto-environment detection**: Works seamlessly in development
-- **Secure**: Merchant-generated session IDs prevent attacks
+- **Auto-environment detection**: Works seamlessly across environments
+- **Secure**: HMAC-signed state parameters, automatic session management
 - **Compliant**: Enforces minimum age of 25
 
 ## Installation
@@ -25,286 +18,327 @@ A lightweight SDK for integrating SafePassage age verification using a simple re
 npm install @safepassage/sdk
 ```
 
+Or load directly from jsDelivr CDN (no bundler required):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
+```
+
 ## Quick Start
 
+### With npm/bundler
+
 ```javascript
-// Initialize SDK
-const safePassage = new SafePassage({
-  apiKey: 'sk_xxxxx',         // Your API key
-  returnUrl: 'https://yoursite.com/verified'
+import { SafePassage } from '@safepassage/sdk';
+
+const sp = new SafePassage({
+  apiKey: 'pk_...',  // Your public key from the dashboard
+  returnUrl: window.location.origin + '/verified'
 });
 
-// Generate a session ID (must be UUID v4)
-const sessionId = crypto.randomUUID();
+// Start verification - redirects user to SafePassage
+await sp.verify();
+```
 
-// Trigger verification
-safePassage.verify({ 
-  sessionId: sessionId,             // Required: merchant-generated UUID
-  challengeAge: 25,                 // Optional: minimum age (25 or higher)
-  verificationMode: 'L1'            // Optional: 'L1' or 'L2'
-});
+### With CDN (no bundler)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
+<script>
+  const sp = new SafePassage({
+    apiKey: 'pk_...',
+    returnUrl: window.location.origin + '/verified'
+  });
+
+  document.getElementById('verify-btn').onclick = () => sp.verify();
+</script>
 ```
 
+That's it! The SDK handles session creation automatically.
+
 ## Configuration
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| apiKey | string | Yes | Your API key (pk_xxx for client-side, sk_xxx for server-side) |
-| returnUrl | string | Yes | URL to redirect after successful verification |
-| environment | string | No | 'production', 'staging', or 'development' (auto-detected) |
-| mode | string | No | 'redirect' (default) or 'new-tab' |
-| onComplete | function | No | Callback for new-tab mode completion |
+| apiKey | string | Yes | Your public API key (`pk_...`) |
+| returnUrl | string | Yes | URL to redirect after verification |
+| environment | string | No | `'production'` or `'staging'` (auto-detected) |
+| mode | string | No | `'redirect'` (default) or `'new-tab'` |
+| defaultChallengeAge | number | No | Default minimum age (25 or higher) |
+| defaultVerificationMode | string | No | `'L1'` or `'L2'` |
+| onComplete | function | No | Callback for new-tab mode |
+| onCancel | function | No | Called when user closes popup (new-tab mode) |
 | onError | function | No | Error handler |
 
-### API Key Types
-
-SafePassage provides two types of API keys:
-
-- **Public Keys (`pk_`)**: Safe for client-side use (websites, mobile apps)
-  - Limited to creating and initiating verifications
-  - Cannot read verification results or override settings
-  - SDK auto-generates sessionId if not provided
-  
-- **Secret Keys (`sk_`)**: Server-side only - keep these private!
-  - Full API access including reading verification results
-  - Can override challenge age and verification mode
-  - Requires merchant-generated sessionId
-
 ## Verification Options
 
-```javascript
-safePassage.verify({
-  sessionId: 'uuid-v4',        // Required for sk_ keys, optional for pk_ keys
-  challengeAge: 30,            // Optional: min 25 (sk_ keys only)
-  verificationMode: 'L2'       // Optional: 'L1' or 'L2' (sk_ keys only)
-});
-```
-
-### Configuration Override Behavior
-
-When you pass `challengeAge` or `verificationMode` to the `verify()` method, these values take precedence over your dashboard configuration for that specific verification session:
+Override settings per-verification:
 
-- **No overrides**: Uses your current dashboard settings
-- **With overrides**: SDK values are used instead of dashboard settings
-- **Challenge age**: Must be 25 or higher (lower values will be rejected)
-- **Verification mode**: 
-  - `'L1'`: Age estimation with computer vision
-  - `'L2'`: Always requires ID verification
-
-Example use cases:
 ```javascript
-// Use dashboard defaults
-safePassage.verify({ sessionId: crypto.randomUUID() });
-
-// Override just challenge age
-safePassage.verify({ 
-  sessionId: crypto.randomUUID(),
-  challengeAge: 30  // Require age 30+ for this session
+await sp.verify({
+  challengeAge: 30,           // Override minimum age for this session
+  verificationMode: 'L2',     // Force ID verification for this session
+  externalUserId: 'user-123', // Your user ID (returned in webhooks)
+  skipIntro: true,            // Skip intro screen
+  autoReturn: true            // Auto-redirect after success
 });
+```
 
-// Override just verification mode
-safePassage.verify({ 
-  sessionId: crypto.randomUUID(),
-  verificationMode: 'L2'  // Force ID check for this session
-});
+### Verification Modes
 
-// Override both
-safePassage.verify({ 
-  sessionId: crypto.randomUUID(),
-  challengeAge: 30,
-  verificationMode: 'L2'  // ID required for 30+ verification
-});
-```
+- **L1**: Age estimation using computer vision (faster, less friction)
+- **L2**: Full ID document verification (more thorough)
 
-## Modes
+## Integration Modes
 
 ### Same-Tab Redirect (Default)
-User is redirected to SafePassage, then back to your site:
+
+User is redirected to SafePassage, then back to your `returnUrl`:
 
 ```javascript
-const safePassage = new SafePassage({
-  apiKey: 'sk_xxxxx',
+const sp = new SafePassage({
+  apiKey: 'pk_...',
   returnUrl: '/age-verified'
 });
 
-safePassage.verify({ sessionId: crypto.randomUUID() });
+await sp.verify();
+// User is redirected to SafePassage...
+// After verification, user returns to /age-verified?sessionId=xxx&status=verified
 ```
 
 ### New-Tab Mode
+
 Verification opens in a popup window:
 
 ```javascript
-const safePassage = new SafePassage({
-  apiKey: 'sk_xxxxx',
+const sp = new SafePassage({
+  apiKey: 'pk_...',
   returnUrl: '/age-verified',
   mode: 'new-tab',
   onComplete: (result) => {
-    console.log('Verified:', result.sessionId);
-    // Validate on your server!
+    console.log('Verification complete:', result.sessionId, result.status);
+    // Validate on your server, then update UI
+  },
+  onCancel: () => {
+    console.log('User closed the verification window');
+  },
+  onError: (error) => {
+    console.error('Verification error:', error.message);
   }
 });
 
-safePassage.verify({ sessionId: crypto.randomUUID() });
-```
-
-## URL Query Parameters
-
-SafePassage supports optional query parameters for streamlined verification flows:
-
-### skip_intro
-Skip the introductory screen and navigate directly to camera access:
-
-```javascript
-// Via SDK (automatic)
-safePassage.verify({ sessionId: crypto.randomUUID() });
-
-// Via server-side session creation
-const url = new URL(verifyUrl);
-url.searchParams.set('skip_intro', 'true');
-window.location.href = url.toString();
+await sp.verify();
 ```
 
-### auto_return
-Automatically redirect to `returnUrl` after successful verification (redirect mode only):
+## Server-Side Validation (Required!)
 
-```javascript
-// Via server-side session creation
-const url = new URL(verifyUrl);
-url.searchParams.set('auto_return', 'true');
-window.location.href = url.toString();
-```
+After verification completes, **always validate the result on your server** before granting access:
 
-### Combined Example
 ```javascript
-const url = new URL(verifyUrl);
-url.searchParams.set('skip_intro', 'true');
-url.searchParams.set('auto_return', 'true');
-// Result: Streamlined flow with minimal user interaction
-window.location.href = url.toString();
-```
-
-**For comprehensive parameter documentation, usage examples, and integration patterns, see [URL Parameters Reference](../../../docs/technical/api/VERIFY_UI_PARAMETERS.md).**
-
-## Server-Side Validation (Required!)
+// Node.js / Express example
+app.get('/age-verified', async (req, res) => {
+  const { sessionId } = req.query;
+
+  // Validate with your SECRET key (sk_...)
+  const response = await fetch(
+    `https://api.safepassageapp.com/api/v1/sessions/${sessionId}`,
+    {
+      headers: {
+        'Authorization': `Bearer ${process.env.SAFEPASSAGE_SECRET_KEY}`
+      }
+    }
+  );
 
-Always validate the session on your server:
+  const session = await response.json();
 
-```javascript
-// Node.js example
-const response = await fetch('https://api.safepassageapp.com/v1/sessions/validate', {
-  method: 'POST',
-  headers: {
-    'Authorization': 'Bearer sk_xxxxx', // Secret key
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({ sessionId })
+  if (session.status === 'VERIFIED') {
+    // Grant access
+    req.session.ageVerified = true;
+    res.redirect('/content');
+  } else {
+    res.redirect('/age-verification-failed');
+  }
 });
-
-const result = await response.json();
-if (result.verified && result.estimatedAge >= result.challengeAge) {
-  // Grant access
-}
 ```
 
-## UUID Generation
+> **Security Note**: Never trust client-side verification status alone. Always validate server-side using your secret key.
+
+## Webhooks (Recommended)
 
-You must generate session IDs on your end. Use the built-in crypto.randomUUID() when available:
+For reliable verification tracking, configure webhooks in your dashboard:
 
 ```javascript
-// Modern browsers and Node.js 16+
-const sessionId = crypto.randomUUID();
-
-// Fallback for older environments
-function generateUUID() {
-  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
-    const r = Math.random() * 16 | 0;
-    const v = c === 'x' ? r : (r & 0x3 | 0x8);
-    return v.toString(16);
-  });
+// Webhook payload example
+{
+  "event": "verification.completed",
+  "sessionId": "abc-123",
+  "verified": true,
+  "externalUserId": "your-user-id",  // If provided during verify()
+  "timestamp": "2025-01-15T10:30:00Z"
 }
 ```
 
 ## Complete Example
 
+### HTML + CDN
+
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-  <!-- Install via NPM: npm install @safepassage/sdk -->
-  <script src="node_modules/@safepassage/sdk/dist/safepassage.min.js"></script>
+  <title>Age Verification</title>
+  <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
 </head>
 <body>
-  <button onclick="verifyAge()">Verify Your Age</button>
+  <button id="verify-btn">Verify Your Age</button>
 
   <script>
-    const safePassage = new SafePassage({
-      apiKey: 'sk_xxxxx',
-      returnUrl: window.location.href + '?verified=true'
+    const sp = new SafePassage({
+      apiKey: 'pk_...',
+      returnUrl: window.location.origin + '/verified'
     });
 
-    function verifyAge() {
-      // Use crypto.randomUUID() if available, otherwise fallback
-      const sessionId = typeof crypto.randomUUID === 'function' 
-        ? crypto.randomUUID()
-        : 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
-            const r = Math.random() * 16 | 0;
-            const v = c === 'x' ? r : (r & 0x3 | 0x8);
-            return v.toString(16);
-          });
-      
-      sessionStorage.setItem('pendingVerification', sessionId);
-      safePassage.verify({ sessionId });
-    }
-
-    // Check if returning from verification
-    const urlParams = new URLSearchParams(window.location.search);
-    if (urlParams.get('verified') === 'true') {
-      const sessionId = sessionStorage.getItem('pendingVerification');
-      // Validate session server-side here
-      console.log('Validate session:', sessionId);
-    }
+    document.getElementById('verify-btn').onclick = () => sp.verify();
   </script>
 </body>
 </html>
 ```
 
+### React Component
+
+```jsx
+import { useState } from 'react';
+import { SafePassage } from '@safepassage/sdk';
+
+function AgeGate() {
+  const [verifying, setVerifying] = useState(false);
+
+  const sp = new SafePassage({
+    apiKey: process.env.NEXT_PUBLIC_SAFEPASSAGE_KEY,
+    returnUrl: window.location.origin + '/verified'
+  });
+
+  const handleVerify = async () => {
+    setVerifying(true);
+    try {
+      await sp.verify();
+    } catch (error) {
+      console.error('Failed to start verification:', error);
+      setVerifying(false);
+    }
+  };
+
+  return (
+    <button onClick={handleVerify} disabled={verifying}>
+      {verifying ? 'Redirecting...' : 'Verify Your Age'}
+    </button>
+  );
+}
+```
+
 ## TypeScript
 
 Full TypeScript support included:
 
 ```typescript
-import { SafePassage, SafePassageConfig } from '@safepassage/sdk';
+import { SafePassage, SafePassageConfig, VerificationResult } from '@safepassage/sdk';
 
 const config: SafePassageConfig = {
-  apiKey: process.env.SAFEPASSAGE_PUBLIC_KEY!,
-  returnUrl: '/verified'
+  apiKey: process.env.NEXT_PUBLIC_SAFEPASSAGE_KEY!,
+  returnUrl: '/verified',
+  mode: 'new-tab',
+  onComplete: (result: VerificationResult) => {
+    console.log(`Session ${result.sessionId}: ${result.status}`);
+  }
 };
 
-const safePassage = new SafePassage(config);
+const sp = new SafePassage(config);
+```
+
+## Skip Parameters
+
+For streamlined embedded flows:
+
+```javascript
+// Skip intro screen (go directly to camera)
+await sp.verify({ skipIntro: true });
+
+// Auto-redirect after success (no success screen)
+await sp.verify({ autoReturn: true });
+
+// Both - minimal user interaction
+await sp.verify({ skipIntro: true, autoReturn: true });
 ```
 
-## Migration from v2
+## Error Handling
 
-New streamlined approach (10 lines):
 ```javascript
-const safePassage = new SafePassage({
-  apiKey: 'sk_xxxxx',
-  returnUrl: '/verified'
+const sp = new SafePassage({
+  apiKey: 'pk_...',
+  returnUrl: '/verified',
+  onError: (error) => {
+    if (error.message.includes('popup')) {
+      alert('Please allow popups for age verification');
+    } else if (error.message.includes('rate limit')) {
+      alert('Too many attempts. Please wait a moment.');
+    } else {
+      console.error('Verification error:', error);
+    }
+  }
 });
-safePassage.verify({ sessionId: crypto.randomUUID() });
 ```
 
+## API Keys
+
+SafePassage uses two types of API keys:
+
+| Key Type | Prefix | Use Case |
+|----------|--------|----------|
+| Public Key | `pk_` | Client-side SDK (this package) |
+| Secret Key | `sk_` | Server-side validation only |
+
+> **Important**: This SDK only works with public keys (`pk_`). For server-side integrations using secret keys, use the [Direct API](https://docs.safepassageapp.com/api) instead.
+
 ## Browser Support
 
 - Chrome 60+
 - Firefox 60+
 - Safari 12+
 - Edge 79+
-- Mobile browsers
+- Mobile browsers (iOS Safari, Chrome for Android)
+
+## Security Best Practices
+
+1. **Use public keys client-side** - Never expose secret keys in browser code
+2. **Validate server-side** - Always verify results using your secret key
+3. **Configure webhooks** - For reliable, tamper-proof verification notifications
+4. **Register callback URLs** - Pre-register your `returnUrl` in the dashboard
+5. **Use HTTPS** - SDK enforces HTTPS in production
+
+## Cleanup
+
+When done with the SDK (e.g., in SPA route changes):
+
+```javascript
+sp.destroy();
+```
+
+## Migration from v3.0.x
+
+If you were using merchant-generated session IDs:
+
+```javascript
+// Old (v3.0.x)
+safePassage.verify({ sessionId: crypto.randomUUID() });
+
+// New (v3.4+) - sessionId is auto-generated
+await sp.verify();
+```
+
+The SDK now creates sessions automatically via the API when using public keys.
 
-## Security Notes
+## Support
 
-1. Always generate session IDs on the merchant side
-2. Validate sessions server-side before granting access
-3. Pre-register callback URLs in your dashboard
-4. Never expose your secret key (sk_xxx)
+- [Documentation](https://docs.safepassageapp.com)
+- [API Reference](https://docs.safepassageapp.com/api)
+- [Dashboard](https://portal.safepassageapp.com)

package/dist/core/SafePassageSDK.d.ts

@@ -49,6 +49,7 @@ export declare class SafePassage {
     private currentSessionId;
     private lastVerifyUrl;
     private lastSessionToken;
+    private temporaryHandoffToken;
     /**
      * Initialize SafePassage SDK
      *

package/dist/core/SafePassageSDK.js

@@ -63,6 +63,8 @@ export class SafePassage {
         this.lastVerifyUrl = null;
         // Server-provided session token (WS auth)
         this.lastSessionToken = null;
+        // Temporary storage for QR handoff token to include in state
+        this.temporaryHandoffToken = null;
         validateConfig(config);
         // Normalize environment: treat 'development' or any unknown value as 'production'
         let normalizedEnvironment = config.environment || this.detectEnvironment();
@@ -210,7 +212,7 @@ export class SafePassage {
                 qualityThreshold: 0.6,
             },
             // Include handoffToken if available (for QR code desktop flow)
-            handoffToken: this._temporaryHandoffToken,
+            handoffToken: this.temporaryHandoffToken || undefined,
             // Include sessionToken and verifyUrl to make UI auth deterministic
             sessionToken: this.lastSessionToken || undefined,
             verifyUrl: this.lastVerifyUrl || undefined,
@@ -285,7 +287,7 @@ export class SafePassage {
         }
         // Set up PostMessage listener with enhanced security
         this.messageListener = (event) => {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+            var _a, _b, _c, _d, _e, _f;
             // Enhanced origin validation with strict allowlist
             if (!validatePostMessageOrigin(event, this.config.environment)) {
                 logSecurityEvent('POSTMESSAGE_ORIGIN_BLOCKED', {
@@ -330,11 +332,9 @@ export class SafePassage {
             if (result.status === 'verified') {
                 (_d = (_c = this.config).onComplete) === null || _d === void 0 ? void 0 : _d.call(_c, result);
             }
-            else if (result.status === 'cancelled') {
-                (_f = (_e = this.config).onCancel) === null || _f === void 0 ? void 0 : _f.call(_e);
-            }
             else {
-                (_h = (_g = this.config).onError) === null || _h === void 0 ? void 0 : _h.call(_g, new Error(`Verification failed: ${result.status}`));
+                // Status is 'failed' - trigger error callback
+                (_f = (_e = this.config).onError) === null || _f === void 0 ? void 0 : _f.call(_e, new Error(`Verification failed: ${result.status}`));
             }
         };
         window.addEventListener('message', this.messageListener);
@@ -611,7 +611,7 @@ export class SafePassage {
             // Store the handoffToken if it exists for desktop QR flow
             if (sessionData.handoffToken) {
                 // Store it temporarily so it can be included in the state
-                this._temporaryHandoffToken = sessionData.handoffToken;
+                this.temporaryHandoffToken = sessionData.handoffToken;
             }
             // Log successful session creation
             logSecurityEvent('INTERNAL_SESSION_CREATED', {

package/dist/index.d.ts

@@ -18,4 +18,4 @@
  */
 export { SafePassage, SafePassage as default } from './core/SafePassageSDK';
 export type { SafePassageConfig, VerificationOptions, VerificationResult, SessionValidationResponse, } from './types';
-export declare const VERSION = "3.4.1";
+export declare const VERSION = "3.4.3";