@safepassage/sdk 3.0.4 → 3.0.6

package/README.md

@@ -248,14 +248,9 @@ const config: SafePassageConfig = {
 const safePassage = new SafePassage(config);
 ```
 
-## Migration from v2 (iframe)
+## Migration from v2
 
-Old iframe approach (1000+ lines):
-```javascript
-// Complex iframe setup...
-```
-
-New redirect approach (10 lines):
+New streamlined approach (10 lines):
 ```javascript
 const safePassage = new SafePassage({
   apiKey: 'sk_live_xxxxx',

package/dist/core/SafePassageSDK.d.ts

@@ -1,8 +1,44 @@
 /**
  * SafePassage SDK - Redirect-based age verification
- * Lightweight SDK for integrating SafePassage age verification using redirect flow
+ *
+ * Lightweight SDK for integrating SafePassage age verification using redirect flow.
+ * Provides a secure, easy-to-implement solution for age verification with comprehensive
+ * security features and flexible integration options.
+ *
+ * Key Features:
+ * - Redirect and new-tab verification modes
+ * - Automatic session management for public API keys
+ * - HMAC-signed state parameters for security
+ * - Rate limiting and race condition protection
+ * - Comprehensive security validation and logging
+ * - PostMessage communication for new-tab mode
+ * - Automatic cleanup and resource management
+ * - Environment-specific configuration
+ *
+ * Security Features:
+ * - Origin validation for PostMessage communication
+ * - HTTPS enforcement in production
+ * - Rate limiting per API key and origin
+ * - State parameter signing with timestamps and nonces
+ * - Comprehensive security event logging
+ * - Protection against race conditions and replay attacks
+ *
+ * @author SafePassage Engineering
+ * @version 2.0.0
+ * @since 1.0.0
  */
 import type { SafePassageConfig, VerificationOptions } from '../types';
+/**
+ * SafePassage SDK Main Class
+ *
+ * Primary SDK class that manages age verification sessions with comprehensive
+ * security and error handling. Supports both redirect and new-tab modes with
+ * automatic session management and PostMessage communication.
+ *
+ * The class implements multiple security layers including origin validation,
+ * rate limiting, state signing, and comprehensive event logging to ensure
+ * secure verification flows.
+ */
 export declare class SafePassage {
     private config;
     private popupWindow;
@@ -11,58 +47,175 @@ export declare class SafePassage {
     private unloadListener;
     private isVerificationInProgress;
     private currentSessionId;
+    /**
+     * Initialize SafePassage SDK
+     *
+     * Validates configuration, sets up security measures, and prepares the SDK
+     * for verification operations. Performs comprehensive environment validation
+     * and security initialization.
+     *
+     * @param {SafePassageConfig} config - SDK configuration object
+     * @throws {Error} If configuration validation fails
+     */
     constructor(config: SafePassageConfig);
     /**
      * Initiate age verification with race condition protection
+     *
+     * Main verification method that handles session creation, security validation,
+     * and verification flow initiation. Includes race condition protection and
+     * comprehensive error handling.
+     *
+     * For public keys (pk_*), automatically creates sessions via the portal API.
+     * For private keys (sk_*), requires a pre-created sessionId.
+     *
+     * @param {VerificationOptions} [options={}] - Verification options
+     * @param {string} [options.sessionId] - Session ID (required for private keys)
+     * @param {number} [options.challengeAge] - Age challenge override
+     * @param {string} [options.verificationMode] - Verification mode override
+     * @param {string} [options.externalUserId] - External user identifier
+     * @returns {Promise<void>} Promise that resolves when verification is initiated
+     * @throws {Error} If verification cannot be started or is already in progress
      */
     verify(options?: VerificationOptions): Promise<void>;
     /**
      * Build verification URL with HMAC-signed state
+     *
+     * Constructs the verification URL with signed state parameter containing
+     * all necessary configuration and security information. The state parameter
+     * includes HMAC signature for integrity protection.
+     *
+     * @param {VerificationOptions} options - Verification options
+     * @returns {Promise<string>} Complete verification URL
+     * @private
      */
     private buildVerificationUrl;
     /**
      * Redirect in same tab
+     *
+     * Performs a full page redirect to the verification URL.
+     * Used for redirect mode verification.
+     *
+     * @param {string} url - Verification URL to redirect to
+     * @private
      */
     private redirect;
     /**
      * Open in new tab with PostMessage communication and proper cleanup
+     *
+     * Opens verification URL in a new tab/window and sets up secure PostMessage
+     * communication for receiving verification results. Includes comprehensive
+     * security validation and automatic cleanup.
+     *
+     * @param {string} url - Verification URL to open
+     * @param {string} sessionId - Session ID for result correlation
+     * @private
      */
     private openNewTab;
     /**
      * Set up automatic cleanup on page unload to prevent memory leaks
+     *
+     * Registers event listeners for page unload events to ensure proper
+     * cleanup of resources and verification state. Handles both traditional
+     * page navigation and single-page application route changes.
+     *
+     * @private
      */
     private setupAutoCleanup;
     /**
      * Auto-detect environment based on current URL
+     *
+     * Analyzes the current hostname to determine the appropriate environment
+     * configuration. Used when environment is not explicitly specified.
+     *
+     * @returns {'production' | 'staging' | 'development'} Detected environment
+     * @private
      */
     private detectEnvironment;
     /**
      * Unlock verification process to allow new verifications
+     *
+     * Resets the verification lock state to allow new verification attempts.
+     * Called after successful completion, errors, or cleanup.
+     *
+     * @private
      */
     private unlockVerification;
     /**
      * Internal cleanup method to prevent memory leaks
+     *
+     * Cleans up popup windows, event listeners, and intervals.
+     * Does not unlock verification state - that's handled by specific callers.
+     *
+     * @private
      */
     private cleanup;
     /**
      * Remove auto-cleanup listeners
+     *
+     * Removes page unload event listeners that were set up for automatic cleanup.
+     *
+     * @private
      */
     private removeAutoCleanupListeners;
     /**
      * Public cleanup method for manual resource management
+     *
+     * Completely destroys the SDK instance, cleaning up all resources and
+     * removing all event listeners. Should be called when the SDK is no longer needed.
+     *
+     * @public
      */
     destroy(): void;
+    /**
+     * Get Portal API URL based on environment
+     *
+     * Returns the appropriate portal-api URL for the current environment.
+     *
+     * @returns {string} Portal API URL
+     * @private
+     */
+    private getPortalApiUrl;
+    /**
+     * Get Engine URL based on environment
+     *
+     * Returns the appropriate verify-engine URL for the current environment.
+     * In production, engine access is proxied through portal-api.
+     *
+     * @returns {string} Engine URL
+     * @private
+     */
+    private getEngineUrl;
+    /**
+     * Get WebSocket URL based on environment
+     *
+     * Returns the appropriate WebSocket URL for the current environment.
+     * In production, WebSocket connections are proxied through portal-api.
+     *
+     * @returns {string} WebSocket URL
+     * @private
+     */
+    private getWebSocketUrl;
     /**
      * Detect if this is a public key (pk_ prefix) vs private key (sk_ prefix)
+     *
+     * Determines API key type based on prefix to handle different authentication flows.
+     *
+     * @returns {boolean} True if public key, false if private key
+     * @private
      */
     private isPublicKey;
     /**
      * Create session internally for public keys
+     *
+     * Creates a verification session via the portal API for public key authentication.
+     * Generates a UUID session ID and submits session creation request with
+     * verification parameters.
+     *
+     * @param {VerificationOptions} options - Verification options
+     * @returns {Promise<string>} Created session ID
+     * @throws {Error} If session creation fails
+     * @private
      */
     private createInternalSession;
-    /**
-     * Get portal API URL based on environment
-     */
-    private getPortalApiUrl;
 }
 export default SafePassage;