@privateav/sdk 3.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SafePassage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# PrivateAV SDK v3.4
+
+A lightweight SDK for integrating PrivateAV age verification into your website or application.
+
+## Features
+
+- **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 across environments
+- **Secure**: HMAC-signed state parameters, automatic session management
+- **Compliant**: Enforces minimum age of 25
+
+## Installation
+
+```bash
+npm install @privateav/sdk
+```
+
+Or load directly from jsDelivr CDN (no bundler required):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@privateav/sdk@latest/dist/privateav.min.js"></script>
+```
+
+## Quick Start
+
+### With npm/bundler
+
+```javascript
+import { PrivateAV } from '@privateav/sdk';
+
+const sp = new PrivateAV({
+  apiKey: 'pk_...',  // Your public key from the dashboard
+  returnUrl: window.location.origin + '/verified'
+});
+
+// Start verification - redirects user to PrivateAV
+await sp.verify();
+```
+
+### With CDN (no bundler)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@privateav/sdk@latest/dist/privateav.min.js"></script>
+<script>
+  const sp = new PrivateAV({
+    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 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 |
+
+## Verification Options
+
+Override settings per-verification:
+
+```javascript
+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
+});
+```
+
+### Verification Modes
+
+- **L1**: Age estimation using computer vision (faster, less friction)
+- **L2**: Full ID document verification (more thorough)
+
+## Integration Modes
+
+### Same-Tab Redirect (Default)
+
+User is redirected to PrivateAV, then back to your `returnUrl`:
+
+```javascript
+const sp = new PrivateAV({
+  apiKey: 'pk_...',
+  returnUrl: '/age-verified'
+});
+
+await sp.verify();
+// User is redirected to PrivateAV...
+// After verification, user returns to /age-verified?sessionId=xxx&status=verified
+```
+
+### New-Tab Mode
+
+Verification opens in a popup window:
+
+```javascript
+const sp = new PrivateAV({
+  apiKey: 'pk_...',
+  returnUrl: '/age-verified',
+  mode: 'new-tab',
+  onComplete: (result) => {
+    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);
+  }
+});
+
+await sp.verify();
+```
+
+## Server-Side Validation (Required!)
+
+After verification completes, **always validate the result on your server** before granting access:
+
+```javascript
+// 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.privateav.com/api/v1/sessions/${sessionId}`,
+    {
+      headers: {
+        'Authorization': `Bearer ${process.env.SAFEPASSAGE_SECRET_KEY}`
+      }
+    }
+  );
+
+  const session = await response.json();
+
+  if (session.status === 'VERIFIED') {
+    // Grant access
+    req.session.ageVerified = true;
+    res.redirect('/content');
+  } else {
+    res.redirect('/age-verification-failed');
+  }
+});
+```
+
+> **Security Note**: Never trust client-side verification status alone. Always validate server-side using your secret key.
+
+## Webhooks (Recommended)
+
+For reliable verification tracking, configure webhooks in your dashboard:
+
+```javascript
+// 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>
+  <title>Age Verification</title>
+  <script src="https://cdn.jsdelivr.net/npm/@privateav/sdk@latest/dist/privateav.min.js"></script>
+</head>
+<body>
+  <button id="verify-btn">Verify Your Age</button>
+
+  <script>
+    const sp = new PrivateAV({
+      apiKey: 'pk_...',
+      returnUrl: window.location.origin + '/verified'
+    });
+
+    document.getElementById('verify-btn').onclick = () => sp.verify();
+  </script>
+</body>
+</html>
+```
+
+### React Component
+
+```jsx
+import { useState } from 'react';
+import { PrivateAV } from '@privateav/sdk';
+
+function AgeGate() {
+  const [verifying, setVerifying] = useState(false);
+
+  const sp = new PrivateAV({
+    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 { PrivateAV, PrivateAVConfig, VerificationResult } from '@privateav/sdk';
+
+const config: PrivateAVConfig = {
+  apiKey: process.env.NEXT_PUBLIC_SAFEPASSAGE_KEY!,
+  returnUrl: '/verified',
+  mode: 'new-tab',
+  onComplete: (result: VerificationResult) => {
+    console.log(`Session ${result.sessionId}: ${result.status}`);
+  }
+};
+
+const sp = new PrivateAV(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 });
+```
+
+## Error Handling
+
+```javascript
+const sp = new PrivateAV({
+  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);
+    }
+  }
+});
+```
+
+## API Keys
+
+PrivateAV 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.privateav.com/api) instead.
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+- 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.
+
+## Support
+
+- [Documentation](https://docs.privateav.com)
+- [API Reference](https://docs.privateav.com/api)
+- [Dashboard](https://portal.privateav.com)

package/brands/privateav/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PrivateAV SDK - Redirect-based age verification
+ */
+import { VerificationSDK } from '../../core/VerificationSDK';
+import type { SDKConfig, VerificationOptions, VerificationResult, SessionValidationResponse, SessionCreationResponse, CreateSessionRequest } from '../../types/base';
+export interface PrivateAVConfig extends SDKConfig {
+}
+export declare class PrivateAV extends VerificationSDK {
+    constructor(config: PrivateAVConfig);
+}
+export declare const VERSION = "3.4.2";
+export type { SDKConfig, VerificationOptions, VerificationResult, SessionValidationResponse, SessionCreationResponse, CreateSessionRequest, };
+export default PrivateAV;

package/brands/privateav/urls.d.ts

@@ -0,0 +1,3 @@
+import type { BrandUrls, BrandConstants } from '../../core/VerificationSDK';
+export declare const BRAND_URLS: BrandUrls;
+export declare const BRAND_CONSTANTS: BrandConstants;

package/core/VerificationSDK.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Verification SDK - Redirect-based age verification
+ *
+ * Lightweight SDK for integrating age verification using redirect flow.
+ * Provides a secure, easy-to-implement solution with comprehensive
+ * security features and flexible integration options.
+ */
+import type { SDKConfig, VerificationOptions } from '../types/base';
+export interface UrlConfig {
+    apiUrl: string;
+    verifyUiUrl: string;
+    engineUrl: string;
+    wsUrl: string;
+    trustedOrigins: string[];
+}
+export interface BrandUrls {
+    production: UrlConfig;
+    staging: UrlConfig;
+}
+export interface BrandConstants {
+    name: string;
+    hmacSecretProd: string;
+    hmacSecretStaging: string;
+    messageType: string;
+    legacyMessageType?: string;
+    popupName: string;
+    docsUrl: string;
+}
+/**
+ * SDK Main Class
+ *
+ * Primary SDK class that manages verification sessions with comprehensive
+ * security and error handling. Supports both redirect and new-tab modes with
+ * automatic session management and PostMessage communication.
+ */
+export declare class VerificationSDK {
+    private config;
+    private readonly brandUrls;
+    private readonly brandConstants;
+    private popupWindow;
+    private messageListener;
+    private popupMonitorInterval;
+    private unloadListener;
+    private isVerificationInProgress;
+    private currentSessionId;
+    private lastVerifyUrl;
+    private lastSessionToken;
+    private temporaryHandoffToken;
+    /**
+     * Initialize SDK
+     *
+     * Validates configuration, sets up security measures, and prepares the SDK
+     * for verification operations. Performs comprehensive environment validation
+     * and security initialization.
+     */
+    constructor(config: SDKConfig, brandUrls: BrandUrls, brandConstants: BrandConstants);
+    /**
+     * Initiate verification with race condition protection
+     */
+    verify(options?: VerificationOptions): Promise<void>;
+    /**
+     * Build verification URL with HMAC-signed state
+     */
+    private buildVerificationUrl;
+    /**
+     * Redirect in same tab
+     */
+    private redirect;
+    /**
+     * Open in new tab with PostMessage communication and proper cleanup
+     */
+    private openNewTab;
+    /**
+     * Set up automatic cleanup on page unload to prevent memory leaks
+     */
+    private setupAutoCleanup;
+    /**
+     * Auto-detect environment based on current URL
+     */
+    private detectEnvironment;
+    /**
+     * Get the current environment
+     */
+    getEnvironment(): 'production' | 'staging';
+    /**
+     * Unlock verification process to allow new verifications
+     */
+    private unlockVerification;
+    /**
+     * Internal cleanup method to prevent memory leaks
+     */
+    private cleanup;
+    /**
+     * Remove auto-cleanup listeners
+     */
+    private removeAutoCleanupListeners;
+    /**
+     * Public cleanup method for manual resource management
+     */
+    destroy(): void;
+    /**
+     * Get Portal API URL based on environment and brand
+     */
+    private getPortalApiUrl;
+    /**
+     * Get Engine URL based on environment and brand
+     */
+    private getEngineUrl;
+    /**
+     * Get WebSocket URL based on environment and brand
+     */
+    private getWebSocketUrl;
+    /**
+     * Detect if this is a public key (pk_ prefix) vs private key (sk_ prefix)
+     */
+    private isPublicKey;
+    /**
+     * Create session internally for public keys
+     */
+    private createInternalSession;
+    private getUrlConfig;
+    private getTrustedOrigins;
+    private getHmacSecret;
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from './brands/privateav';
+export { default } from './brands/privateav';