@safepassage/sdk 3.4.9 → 3.4.10

package/README.md

@@ -67,12 +67,13 @@ That's it! The SDK handles session creation automatically.
 |--------|------|----------|-------------|
 | apiKey | string | Yes | Your public API key (`pk_...`) |
 | returnUrl | string | Yes | URL to redirect after verification |
+| cancelUrl | string | No | URL to redirect to if user closes the verification window (new-tab mode) |
 | 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) |
+| onCancel | function | No | Called when user closes popup (new-tab mode). Return `false` to suppress automatic `cancelUrl` redirect. |
 | onError | function | No | Error handler |
 
 ## Verification Options
@@ -119,6 +120,7 @@ Verification opens in a popup window:
 const sp = new SafePassage({
   apiKey: 'pk_...',
   returnUrl: '/age-verified',
+  cancelUrl: '/age-cancelled',
   mode: 'new-tab',
   onComplete: (result) => {
     console.log('Verification complete:', result.sessionId, result.status);
@@ -126,6 +128,8 @@ const sp = new SafePassage({
   },
   onCancel: () => {
     console.log('User closed the verification window');
+    // Return false if you want to handle navigation manually
+    // return false;
   },
   onError: (error) => {
     console.error('Verification error:', error.message);
@@ -135,6 +139,10 @@ const sp = new SafePassage({
 await sp.verify();
 ```
 
+If `cancelUrl` is provided, the SDK will redirect the opener to `cancelUrl` with
+`status=cancelled` and `sessionId` when the user closes the verification window.
+Return `false` from `onCancel` to suppress the automatic redirect.
+
 ## Server-Side Validation (Required!)
 
 After verification completes, **always validate the result on your server** before granting access:
@@ -146,7 +154,7 @@ app.get('/age-verified', async (req, res) => {
 
   // Validate with your SECRET key (sk_...)
   const response = await fetch(
-    `https://api.safepassageapp.com/api/v1/sessions/${sessionId}`,
+    `https://api.safepassage.live/api/v1/sessions/${sessionId}`,
     {
       headers: {
         'Authorization': `Bearer ${process.env.SAFEPASSAGE_SECRET_KEY}`
@@ -183,8 +191,6 @@ For reliable verification tracking, configure webhooks in your dashboard:
 }
 ```
 
-Webhook `timestamp` values are ISO 8601 strings. SDK `onComplete` results use milliseconds since epoch.
-
 ## Complete Example
 
 ### HTML + CDN
@@ -253,8 +259,6 @@ import { SafePassage, SafePassageConfig, VerificationResult } from '@safepassage
 const config: SafePassageConfig = {
   apiKey: process.env.NEXT_PUBLIC_SAFEPASSAGE_KEY!,
   returnUrl: '/verified',
-  // Optional: used as a fallback redirect for Emblem login failures
-  cancelUrl: '/verify-cancelled',
   mode: 'new-tab',
   onComplete: (result: VerificationResult) => {
     console.log(`Session ${result.sessionId}: ${result.status}`);
@@ -306,7 +310,7 @@ SafePassage uses two types of API keys:
 | 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.
+> **Important**: This SDK only works with public keys (`pk_`). For server-side integrations using secret keys, use the [Direct API](https://docs.safepassage.live/api) instead.
 
 ## Browser Support
 
@@ -348,6 +352,6 @@ The SDK now creates sessions automatically via the API when using public keys.
 
 ## Support
 
-- [Documentation](https://docs.safepassageapp.com)
-- [API Reference](https://docs.safepassageapp.com/api)
-- [Dashboard](https://portal.safepassageapp.com)
+- [Documentation](https://docs.safepassage.live)
+- [API Reference](https://docs.safepassage.live/api)
+- [Dashboard](https://portal.safepassage.live)

package/brands/safepassage/index.d.ts

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

package/brands/safepassage/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,132 @@
+/**
+ * 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 hasReceivedResult;
+    private lastVerifyUrl;
+    private lastSessionToken;
+    private lastExternalUserId;
+    private temporaryHandoffToken;
+    private static readonly LOCAL_HOSTNAMES;
+    /**
+     * 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;
+    private handleCancellation;
+    private redirectToCancelUrl;
+    /**
+     * 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 getAllowedCustomOrigins;
+    private getLocalOrigin;
+    private applyLocalVerifyOverride;
+    private getHmacSecret;
+}

package/index.d.ts

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