@authorizeearth/react 1.0.3

package/dist/index.d.mts

@@ -0,0 +1,566 @@
+import React from 'react';
+
+/**
+ * SDK Type Definitions
+ *
+ * Public and internal TypeScript types for the AuthorizeEarth SDK.
+ * Types marked @internal are not part of the public API.
+ *
+ * @module types
+ */
+/**
+ * Display mode for the verification UI.
+ *
+ * - `modal`: Centered overlay with backdrop, suitable for desktop (default)
+ * - `fullscreen`: Full viewport coverage, used automatically on mobile
+ */
+type DisplayMode = 'modal' | 'fullscreen';
+/**
+ * Theme mode for the verification UI.
+ *
+ * - `light`: Light theme with white backgrounds (default)
+ * - `dark`: Dark theme with dark backgrounds (requires custom branding)
+ *
+ * Note: Dark theme requires custom branding to be configured in the
+ * AuthorizeEarth dashboard. If requested without custom branding,
+ * the SDK will automatically fall back to light mode.
+ */
+type Theme = 'light' | 'dark';
+/**
+ * Configuration options for initializing the AuthorizeEarth SDK.
+ *
+ * @example
+ * ```typescript
+ * const config: AuthorizeEarthConfig = {
+ *   sessionToken: 'sess_xxx',
+ *   displayMode: 'modal',
+ *   theme: 'light',
+ *   onSuccess: (result) => console.log(result),
+ *   onError: (error) => console.error(error),
+ * };
+ * ```
+ */
+interface AuthorizeEarthConfig {
+    /**
+     * Session token obtained from your backend via the AuthorizeEarth API.
+     * Required for all verification flows.
+     *
+     * Create a session by calling POST /v1/merchant/integration/session
+     * with your API key from your backend server.
+     */
+    sessionToken: string;
+    /**
+     * How to display the verification UI.
+     *
+     * - `modal`: Centered overlay (default, recommended for desktop)
+     * - `fullscreen`: Full viewport (automatically used on mobile)
+     *
+     * @default 'modal'
+     */
+    displayMode?: DisplayMode;
+    /**
+     * Theme for the verification UI.
+     *
+     * Note: `dark` theme requires custom branding to be configured
+     * in your AuthorizeEarth dashboard. Without custom branding,
+     * the SDK will automatically fall back to light mode.
+     *
+     * @default 'light'
+     */
+    theme?: Theme;
+    /**
+     * Called when verification completes successfully.
+     *
+     * @param result - Contains status, verificationId, and sessionId
+     */
+    onSuccess?: (result: VerificationResult) => void;
+    /**
+     * Called when an error occurs during verification.
+     *
+     * Note: Not all errors are fatal. Check `error.details.can_retry`
+     * to determine if the user can retry the current step.
+     *
+     * @param error - Contains error code, message, and optional details
+     */
+    onError?: (error: VerificationError) => void;
+    /**
+     * Called when the user closes the verification UI.
+     * Use this to handle abandonment tracking or cleanup.
+     */
+    onClose?: () => void;
+    /**
+     * Called for lifecycle events during the verification process.
+     * Useful for analytics, progress tracking, and debugging.
+     *
+     * @param event - Contains event type, timestamp, and optional metadata
+     */
+    onEvent?: (event: VerificationEvent) => void;
+    /**
+     * Enable test mode for development and testing.
+     *
+     * When true, uses the sandbox environment and requires
+     * `templateId` to be set. No real verifications are performed.
+     *
+     * @default false
+     */
+    testMode?: boolean;
+    /**
+     * Template ID for test mode sessions.
+     *
+     * Required when `testMode` is true. Specifies which verification
+     * template to use in the sandbox environment.
+     * Ignored in production mode.
+     */
+    templateId?: string;
+    /**
+     * Integration ID for test mode.
+     *
+     * Optional identifier to associate test sessions with a
+     * specific integration configuration.
+     * Only applies when `testMode` is true.
+     */
+    integrationId?: string;
+    /**
+     * External hash for test mode session validation.
+     *
+     * Used to validate test sessions against expected values.
+     * Only applies when `testMode` is true.
+     */
+    externalHash?: string;
+    /**
+     * Simulate specific error conditions in test mode.
+     *
+     * Useful for testing your error handling logic without
+     * triggering real verification failures.
+     * Only applies when `testMode` is true.
+     *
+     * @example 'max_attempts' | 'document_expired' | 'face_mismatch'
+     */
+    simulateError?: string;
+}
+/**
+ * Result returned upon successful verification.
+ *
+ * @example
+ * ```typescript
+ * onSuccess: (result) => {
+ *   if (result.status === 'verified') {
+ *     grantAccess(result.verificationId);
+ *   } else if (result.status === 'review_required') {
+ *     showPendingMessage();
+ *   }
+ * }
+ * ```
+ */
+interface VerificationResult {
+    /**
+     * Final status of the verification.
+     *
+     * - `verified`: Identity confirmed, user passed all checks
+     * - `rejected`: Identity could not be verified
+     * - `review_required`: Manual review needed before final decision
+     */
+    status: 'verified' | 'rejected' | 'review_required';
+    /**
+     * Unique identifier for this verification attempt.
+     * Use this to retrieve detailed results from the API.
+     */
+    verificationId: string;
+    /**
+     * Session ID associated with this verification.
+     * Matches the sessionToken used to initialize the SDK.
+     */
+    sessionId: string;
+    /**
+     * Additional data returned by the verification process.
+     * Contents vary based on your integration configuration.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Error information when verification fails or encounters issues.
+ *
+ * @example
+ * ```typescript
+ * onError: (error) => {
+ *   if (error.details?.can_retry) {
+ *     showRetryButton();
+ *   } else {
+ *     showFinalError(error.message);
+ *   }
+ * }
+ * ```
+ */
+interface VerificationError {
+    /**
+     * Machine-readable error code for programmatic handling.
+     *
+     * @example 'max_attempts' | 'document_expired' | 'session_expired'
+     */
+    code: string;
+    /**
+     * Human-readable error description suitable for display.
+     */
+    message: string;
+    /**
+     * Additional error context when available.
+     *
+     * May include:
+     * - `can_retry`: Whether the user can retry the current step
+     * - `attempts_remaining`: Number of attempts left (if applicable)
+     * - `category`: Error category for grouping
+     * - `is_fatal`: Whether this error ends the session
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * Lifecycle event emitted during the verification process.
+ *
+ * Subscribe to events via the `onEvent` callback to track
+ * progress, implement analytics, or handle specific states.
+ */
+interface VerificationEvent {
+    /** The type of event that occurred. */
+    type: VerificationEventType;
+    /** Unix timestamp (ms) when the event occurred. */
+    timestamp: number;
+    /**
+     * Additional event-specific data.
+     *
+     * Contents vary by event type. For example, `step_changed`
+     * events include `stepIndex`, `stepType`, and `totalSteps`.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * All possible verification event types.
+ *
+ * | Event | Description |
+ * |-------|-------------|
+ * | `open` | SDK UI has been opened |
+ * | `ready` | Iframe loaded and ready for interaction |
+ * | `step_changed` | User moved to a new verification step |
+ * | `document_captured` | Document image was captured |
+ * | `selfie_captured` | Selfie image was captured |
+ * | `liveness_complete` | Liveness verification completed |
+ * | `processing` | Verification is being processed |
+ * | `complete` | Verification flow completed |
+ * | `error` | An error occurred |
+ * | `close` | User closed the UI |
+ * | `camera_fullscreen_request` | Camera needs fullscreen access |
+ * | `camera_fullscreen_exit` | Exiting camera fullscreen |
+ * | `theme_validated` | Theme validation completed |
+ */
+type VerificationEventType = 'open' | 'ready' | 'step_changed' | 'document_captured' | 'selfie_captured' | 'liveness_complete' | 'processing' | 'complete' | 'error' | 'close' | 'camera_fullscreen_request' | 'camera_fullscreen_exit' | 'theme_validated';
+/**
+ * SDK instance returned by create().
+ *
+ * Use these methods to control the verification UI lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const instance = create(config);
+ *
+ * // Open when user clicks button
+ * button.onclick = () => instance.open();
+ *
+ * // Clean up when component unmounts
+ * onUnmount(() => instance.destroy());
+ * ```
+ */
+interface AuthorizeEarthInstance {
+    /**
+     * Opens the verification UI.
+     *
+     * Creates the iframe and displays it in the configured mode.
+     * No-op if already open or if the instance has been destroyed.
+     */
+    open: () => void;
+    /**
+     * Requests to close the verification UI.
+     *
+     * Sends a close request to the iframe, which may prompt
+     * the user to confirm if verification is in progress.
+     */
+    close: () => void;
+    /**
+     * Destroys the instance and cleans up all resources.
+     *
+     * Removes the iframe, event listeners, and DOM elements.
+     * Call this when done with the instance to prevent memory leaks.
+     * After calling destroy(), the instance cannot be reopened.
+     */
+    destroy: () => void;
+}
+
+/**
+ * Core SDK Module
+ *
+ * Main entry point for creating and managing AuthorizeEarth
+ * verification instances. Handles iframe lifecycle, message
+ * communication, and UI state management.
+ *
+ * @module core
+ */
+
+/**
+ * Creates a new AuthorizeEarth verification instance.
+ *
+ * This is the primary method for initializing the SDK. It returns
+ * an instance with methods to control the verification flow.
+ *
+ * @example
+ * ```typescript
+ * const verification = create({
+ *   sessionToken: 'sess_xxx',
+ *   theme: 'light',
+ *   displayMode: 'modal',
+ *   onSuccess: (result) => {
+ *     console.log('Verified:', result.verificationId);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Failed:', error.message);
+ *   },
+ * });
+ *
+ * // Open when ready (e.g., on button click)
+ * verification.open();
+ *
+ * // Clean up when done
+ * verification.destroy();
+ * ```
+ *
+ * @param config - Configuration options for the verification
+ * @returns Instance with open, close, and destroy methods
+ */
+declare function create(config: AuthorizeEarthConfig): AuthorizeEarthInstance;
+/**
+ * Creates and immediately opens a verification instance.
+ *
+ * Convenience method that combines create() and open() for
+ * simple use cases where immediate display is desired.
+ *
+ * @example
+ * ```typescript
+ * start({
+ *   sessionToken: 'sess_xxx',
+ *   onSuccess: (result) => console.log('Success:', result),
+ * });
+ * ```
+ *
+ * @param config - Configuration options for the verification
+ */
+declare function start(config: AuthorizeEarthConfig): void;
+
+/**
+ * React Bindings
+ *
+ * React hook and component for integrating AuthorizeEarth
+ * identity verification into React applications.
+ *
+ * @module react
+ */
+
+/**
+ * Configuration for the useAuthorizeEarth hook.
+ *
+ * Extends the core SDK configuration with React-specific patterns
+ * like nullable sessionToken for loading states.
+ */
+interface UseAuthorizeEarthConfig {
+    /**
+     * Session token from your backend.
+     *
+     * Pass `null` while the token is loading. The hook will not
+     * be ready until a valid token string is provided.
+     */
+    sessionToken: string | null;
+    /**
+     * How to display the verification UI.
+     * @default 'modal'
+     */
+    displayMode?: DisplayMode;
+    /**
+     * Theme for the verification UI.
+     *
+     * Note: `dark` requires custom branding configured in your
+     * AuthorizeEarth dashboard.
+     * @default 'light'
+     */
+    theme?: Theme;
+    /** Called when verification completes successfully. */
+    onSuccess?: (result: VerificationResult) => void;
+    /** Called when an error occurs during verification. */
+    onError?: (error: VerificationError) => void;
+    /** Called when the user closes the verification UI. */
+    onClose?: () => void;
+    /** Called for lifecycle events during verification. */
+    onEvent?: (event: VerificationEvent) => void;
+    /**
+     * Enable test mode for development and testing.
+     * Requires `templateId` when true.
+     * @default false
+     */
+    testMode?: boolean;
+    /**
+     * Template ID for test mode sessions.
+     * Required when `testMode` is true.
+     */
+    templateId?: string;
+    /**
+     * Integration ID for test mode.
+     */
+    integrationId?: string;
+    /**
+     * Simulate specific error conditions in test mode.
+     */
+    simulateError?: string;
+}
+/**
+ * Return value from the useAuthorizeEarth hook.
+ */
+interface UseAuthorizeEarthReturn {
+    /**
+     * Opens the verification UI.
+     * No-op if not ready or if sessionToken is null.
+     */
+    open: () => void;
+    /**
+     * Requests the verification UI to close.
+     */
+    close: () => void;
+    /**
+     * Whether the SDK is initialized and ready to open.
+     * Will be false while sessionToken is null or loading.
+     */
+    ready: boolean;
+    /**
+     * Initialization error, if any occurred.
+     * Check this before rendering to handle edge cases.
+     */
+    error: Error | null;
+}
+/**
+ * React hook for integrating AuthorizeEarth identity verification.
+ *
+ * Manages the SDK instance lifecycle, ensuring proper cleanup on
+ * unmount and when configuration changes.
+ *
+ * @example Basic usage
+ * ```tsx
+ * function VerifyButton({ sessionToken }) {
+ *   const { open, ready } = useAuthorizeEarth({
+ *     sessionToken,
+ *     onSuccess: (result) => {
+ *       console.log('Verified:', result.verificationId);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <button onClick={open} disabled={!ready}>
+ *       {ready ? 'Verify Identity' : 'Loading...'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example With theme and display mode
+ * ```tsx
+ * const { open, ready } = useAuthorizeEarth({
+ *   sessionToken,
+ *   theme: 'dark',
+ *   displayMode: 'fullscreen',
+ *   onSuccess: handleSuccess,
+ *   onError: handleError,
+ * });
+ * ```
+ *
+ * @param config - Hook configuration options
+ * @returns Object with open/close methods and ready/error state
+ */
+declare function useAuthorizeEarth(config: UseAuthorizeEarthConfig): UseAuthorizeEarthReturn;
+/**
+ * Props for the AuthorizeEarthButton component.
+ *
+ * Combines SDK configuration with standard button props.
+ */
+interface AuthorizeEarthButtonProps {
+    /**
+     * Session token from your backend.
+     * Pass `null` while loading - the button will be disabled.
+     */
+    sessionToken: string | null;
+    /**
+     * How to display the verification UI.
+     * @default 'modal'
+     */
+    displayMode?: DisplayMode;
+    /**
+     * Theme for the verification UI.
+     * @default 'light'
+     */
+    theme?: Theme;
+    /** Called when verification completes successfully. */
+    onSuccess?: (result: VerificationResult) => void;
+    /** Called when an error occurs during verification. */
+    onError?: (error: VerificationError) => void;
+    /** Called when the user closes the verification UI. */
+    onClose?: () => void;
+    /** Called for lifecycle events during verification. */
+    onEvent?: (event: VerificationEvent) => void;
+    /** Enable test mode. Requires `templateId`. */
+    testMode?: boolean;
+    /** Template ID for test mode sessions. */
+    templateId?: string;
+    /** Integration ID for test mode. */
+    integrationId?: string;
+    /** Simulate specific error conditions in test mode. */
+    simulateError?: string;
+    /**
+     * Button content.
+     * @default 'Verify Identity'
+     */
+    children?: React.ReactNode;
+    /** CSS class name for the button element. */
+    className?: string;
+    /** Inline styles for the button element. */
+    style?: React.CSSProperties;
+    /**
+     * Force disable the button.
+     * The button is also disabled when `!ready`.
+     */
+    disabled?: boolean;
+}
+/**
+ * Pre-built button component for triggering identity verification.
+ *
+ * Wraps the useAuthorizeEarth hook with a button element,
+ * automatically handling disabled states while loading.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AuthorizeEarthButton
+ *   sessionToken={sessionToken}
+ *   onSuccess={(result) => console.log('Success:', result)}
+ *   onError={(error) => console.error('Error:', error)}
+ * >
+ *   Verify Your Identity
+ * </AuthorizeEarthButton>
+ * ```
+ *
+ * @example With theme and styling
+ * ```tsx
+ * <AuthorizeEarthButton
+ *   sessionToken={sessionToken}
+ *   theme="dark"
+ *   displayMode="modal"
+ *   className="btn btn-primary"
+ *   onSuccess={handleSuccess}
+ * >
+ *   Start Verification
+ * </AuthorizeEarthButton>
+ * ```
+ */
+declare function AuthorizeEarthButton({ sessionToken, displayMode, theme, testMode, templateId, integrationId, simulateError, onSuccess, onError, onClose, onEvent, children, className, style, disabled, }: AuthorizeEarthButtonProps): JSX.Element;
+
+export { AuthorizeEarthButton, type AuthorizeEarthButtonProps, type AuthorizeEarthConfig, type AuthorizeEarthInstance, type DisplayMode, type Theme, type UseAuthorizeEarthConfig, type UseAuthorizeEarthReturn, type VerificationError, type VerificationEvent, type VerificationEventType, type VerificationResult, create, start, useAuthorizeEarth };