@safepassage/sdk/types/base.d.ts

SafePassage SDK - Lightweight redirect-based age verification

/**
 * SDK type definitions (brand-neutral).
 */
export interface SDKConfig {
    /**
     * Public API key (starts with pk_)
     */
    apiKey: string;
    /**
     * URL to redirect to after successful verification
     * Must be pre-registered in the dashboard
     */
    returnUrl: string;
    /**
     * URL to redirect to if user cancels verification in new-tab mode
     * Optional; cancellation redirects append `status=cancelled` and `sessionId`.
     */
    cancelUrl?: string;
    /**
     * Environment to use
     * @default Auto-detected based on hostname (production unless staging detected)
     */
    environment?: 'production' | 'staging';
    /**
     * Verification mode
     * @default 'redirect'
     */
    mode?: 'redirect' | 'new-tab';
    /**
     * New-tab target behavior (new-tab mode only)
     * @default 'popup'
     */
    newTabTarget?: 'popup' | 'tab';
    /**
     * Default challenge age (minimum 25)
     * Can be overridden per verification
     */
    defaultChallengeAge?: number;
    /**
     * Default verification mode
     * Can be overridden per verification
     */
    defaultVerificationMode?: 'L1' | 'L2';
    /**
     * Override API URL
     */
    apiUrl?: string;
    /**
     * Override Verify UI URL
     */
    verifyUrl?: string;
    /**
     * Callback when verification completes (new-tab mode only)
     */
    onComplete?: (result: VerificationResult) => void;
    /**
     * Callback when user cancels (new-tab mode only)
     * Return false to suppress automatic cancelUrl redirect.
     */
    onCancel?: () => boolean | void;
    /**
     * Default UI language for verification screens
     * Supported: 'en', 'de', 'es', 'fr'
     * Can be overridden per verification call
     */
    language?: string;
    /**
     * Callback for errors
     */
    onError?: (error: Error) => void;
}
export interface VerificationOptions {
    /**
     * 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';
    /**
     * External user identifier from merchant system
     * Optional parameter that will be returned with verification results
     * Useful for correlating sessions with merchant user records
     */
    externalUserId?: string;
    /**
     * Skip the intro screen and go directly to camera access
     * Useful for embedded/streamlined flows where user has already consented
     * @default false
     */
    skipIntro?: boolean;
    /**
     * Automatically redirect to returnUrl immediately after successful verification
     * Skips the success screen for seamless embedded experiences
     * @default false
     */
    autoReturn?: boolean;
    /**
     * UI language override for this verification
     * Supported: 'en', 'de', 'es', 'fr'
     * Takes precedence over SDKConfig.language
     */
    language?: string;
}
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';
    /**
     * Timestamp when verification completed (milliseconds since epoch)
     */
    timestamp?: number;
    /**
     * External user identifier if provided during verification
     */
    externalUserId?: string;
}
export interface StatePayload {
    merchantId: string;
    sessionId: string;
    returnUrl: string;
    /** Optional cancel redirect for new-tab abandonment */
    cancelUrl?: string;
    challengeAge?: number;
    verificationMode?: 'L1' | 'L2';
    hasOverrides?: boolean;
    externalUserId?: string;
    timestamp: number;
    apiUrl?: string;
    engineUrl?: string;
    wsUrl?: string;
    environment?: 'production' | 'staging';
    features?: {
        testMode: boolean;
        warmupPeriodMs: number;
        qualityThreshold: number;
        sandboxMode?: boolean;
    };
    handoffToken?: string;
    sessionToken?: string;
    verifyUrl?: string;
}
export interface SessionValidationResponse {
    sessionId: string;
    merchantId: string;
    status: 'verified' | 'failed' | 'cancelled';
    verified: boolean;
    accessGranted?: boolean;
    /**
     * @deprecated This field is no longer provided and will always be undefined.
     */
    estimatedAge?: number;
    challengeAge: number;
    verificationMode: 'L1' | 'L2';
    verificationMethod?: 'facial' | 'document' | 'combined';
    timestamp: string;
    expiresAt: string;
}
export interface SessionCreationResponse {
    sessionId?: string;
    sessionToken: string;
    verifyUrl: string;
    expiresAt: string;
    testMode?: boolean;
    sandboxMode?: boolean;
    externalUserId?: string;
    handoffToken?: string;
    billingBlock?: {
        code: 'SUBSCRIPTION_REQUIRED' | 'PLAN_LIMIT_REACHED' | 'SANDBOX_LIMIT_REACHED';
        message: string;
        portalUrl?: string;
    };
}
export interface CreateSessionRequest {
    returnUrl: string;
    cancelUrl?: string;
    challengeAge?: number;
    verificationMode?: 'L1' | 'L2';
    merchantName?: string;
    externalUserId?: string;
}