@safepassage/sdk/dist/index.d.ts

SafePassage SDK - Lightweight redirect-based age verification

/**
 * SafePassage SDK Type Definitions
 */
export interface SafePassageConfig {
    /**
     * Public API key (starts with pk_live_ or pk_test_)
     */
    apiKey: string;
    /**
     * URL to redirect to after successful verification
     * Must be pre-registered in dashboard
     */
    returnUrl: string;
    /**
     * URL to redirect to if user cancels verification
     * Must be pre-registered in dashboard
     */
    cancelUrl: string;
    /**
     * Environment to use
     * @default Auto-detected based on hostname
     */
    environment?: 'production' | 'staging' | 'development';
    /**
     * Verification mode
     * @default 'redirect'
     */
    mode?: 'redirect' | 'new-tab';
    /**
     * Default challenge age (minimum 25)
     * Can be overridden per verification
     */
    defaultChallengeAge?: number;
    /**
     * Default verification mode
     * Can be overridden per verification
     */
    defaultVerificationMode?: 'L1' | 'L2';
    /**
     * Callback when verification completes (new-tab mode only)
     */
    onComplete?: (result: VerificationResult) => void;
    /**
     * Callback when user cancels (new-tab mode only)
     */
    onCancel?: () => void;
    /**
     * Callback for errors
     */
    onError?: (error: Error) => void;
}
export interface VerificationOptions {
    /**
     * Merchant-generated UUID v4 for this verification session
     * Required for private keys (sk_), optional for public keys (pk_)
     * For public keys: SDK will generate session internally
     */
    sessionId?: string;
    /**
     * Minimum age to verify (minimum 25)
     * @default Uses merchant dashboard configuration
     */
    challengeAge?: number;
    /**
     * Verification mode
     * L1: Age estimation allowed if user appears older
     * L2: Full ID verification required
     * @default Uses merchant dashboard configuration
     */
    verificationMode?: 'L1' | 'L2';
}
export interface VerificationResult {
    /**
     * The session ID that was verified
     */
    sessionId: string;
    /**
     * Binary result: 'verified' or 'failed'
     * Full details available via server-side API
     */
    status: 'verified' | 'failed' | 'cancelled';
}
export interface StatePayload {
    merchantId: string;
    sessionId: string;
    returnUrl: string;
    cancelUrl: string;
    challengeAge?: number;
    verificationMode?: 'L1' | 'L2';
    hasOverrides?: boolean;
    timestamp: number;
}
export interface SessionValidationResponse {
    sessionId: string;
    merchantId: string;
    status: 'verified' | 'failed';
    verified: boolean;
    estimatedAge?: number;
    challengeAge: number;
    verificationMode: 'L1' | 'L2';
    verificationMethod?: 'facial' | 'document' | 'combined';
    timestamp: string;
    expiresAt: string;
}
export interface SessionCreationResponse {
    sessionToken: string;
    verifyUrl: string;
    expiresAt: string;
}
export interface CreateSessionRequest {
    sessionId: string;
    returnUrl: string;
    cancelUrl?: string;
    challengeAge?: number;
    verificationMode?: 'L1' | 'L2';
    merchantName?: string;
}