@reevit/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,628 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Reevit React SDK Types
+ * Core type definitions for the unified payment widget
+ */
+type PaymentMethod = 'card' | 'mobile_money' | 'bank_transfer';
+type MobileMoneyNetwork = 'mtn' | 'vodafone' | 'airteltigo';
+interface ReevitCheckoutConfig {
+    /** Your Reevit public key (pk_live_xxx or pk_test_xxx) */
+    publicKey: string;
+    /** Amount in the smallest currency unit (e.g., pesewas for GHS) */
+    amount: number;
+    /** Currency code (e.g., 'GHS', 'NGN', 'USD') */
+    currency: string;
+    /** Customer email address */
+    email?: string;
+    /** Customer phone number (required for mobile money) */
+    phone?: string;
+    /** Unique reference for this transaction */
+    reference?: string;
+    /** Additional metadata to attach to the payment */
+    metadata?: Record<string, unknown>;
+    /** Payment methods to display */
+    paymentMethods?: PaymentMethod[];
+}
+interface ReevitCheckoutCallbacks {
+    /** Called when payment is successful */
+    onSuccess?: (result: PaymentResult) => void;
+    /** Called when payment fails */
+    onError?: (error: PaymentError) => void;
+    /** Called when user closes the checkout */
+    onClose?: () => void;
+    /** Called when checkout state changes */
+    onStateChange?: (state: CheckoutState) => void;
+}
+interface ReevitCheckoutProps extends ReevitCheckoutConfig, ReevitCheckoutCallbacks {
+    /** Custom trigger element */
+    children?: React.ReactNode;
+    /** Whether to open automatically */
+    autoOpen?: boolean;
+    /** Custom theme */
+    theme?: ReevitTheme;
+}
+type CheckoutState = 'idle' | 'loading' | 'ready' | 'method_selected' | 'processing' | 'success' | 'failed' | 'closed';
+interface PaymentResult {
+    /** Unique payment ID from Reevit */
+    paymentId: string;
+    /** Reference provided or generated */
+    reference: string;
+    /** Amount paid in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Payment method used */
+    paymentMethod: PaymentMethod;
+    /** PSP that processed the payment */
+    psp: string;
+    /** PSP's transaction reference */
+    pspReference: string;
+    /** Payment status */
+    status: 'success' | 'pending';
+    /** Any additional data from the PSP */
+    metadata?: Record<string, unknown>;
+}
+interface PaymentError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable?: boolean;
+    /** Original error from PSP if available */
+    originalError?: unknown;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+interface ReevitTheme {
+    /** Primary brand color */
+    primaryColor?: string;
+    /** Background color */
+    backgroundColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Border radius for inputs and buttons */
+    borderRadius?: string;
+    /** Font family to use */
+    fontFamily?: string;
+    /** Whether to use dark mode */
+    darkMode?: boolean;
+}
+interface MobileMoneyFormData {
+    phone: string;
+    network: MobileMoneyNetwork;
+}
+interface PaymentIntent {
+    /** Unique payment intent ID */
+    id: string;
+    /** Client secret for authenticating client-side operations */
+    clientSecret: string;
+    /** Amount in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Payment status */
+    status: 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled';
+    /** Recommended PSP based on routing rules */
+    recommendedPsp: 'paystack' | 'hubtel' | 'flutterwave';
+    /** Available payment methods for this intent */
+    availableMethods: PaymentMethod[];
+    /** Connection ID (from Reevit backend) */
+    connectionId?: string;
+    /** Provider name (from backend) */
+    provider?: string;
+    /** Fee amount charged by PSP */
+    feeAmount?: number;
+    /** Fee currency */
+    feeCurrency?: string;
+    /** Net amount after fees */
+    netAmount?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+
+interface ReevitContextValue {
+    publicKey: string;
+    amount: number;
+    currency: string;
+}
+declare function useReevitContext(): ReevitContextValue;
+declare function ReevitCheckout({ publicKey, amount, currency, email, phone, reference, metadata, paymentMethods, onSuccess, onError, onClose, onStateChange, children, autoOpen, theme, }: ReevitCheckoutProps): react_jsx_runtime.JSX.Element;
+
+interface PaymentMethodSelectorProps {
+    methods: PaymentMethod[];
+    selectedMethod: PaymentMethod | null;
+    onSelect: (method: PaymentMethod) => void;
+    disabled?: boolean;
+}
+declare function PaymentMethodSelector({ methods, selectedMethod, onSelect, disabled, }: PaymentMethodSelectorProps): react_jsx_runtime.JSX.Element;
+
+interface MobileMoneyFormProps {
+    onSubmit: (data: MobileMoneyFormData) => void;
+    onCancel: () => void;
+    isLoading?: boolean;
+    initialPhone?: string;
+}
+declare function MobileMoneyForm({ onSubmit, onCancel, isLoading, initialPhone, }: MobileMoneyFormProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useReevit hook
+ * Core hook for managing Reevit checkout state and API interactions
+ */
+
+interface UseReevitOptions {
+    config: ReevitCheckoutConfig;
+    onSuccess?: (result: PaymentResult) => void;
+    onError?: (error: PaymentError) => void;
+    onClose?: () => void;
+    onStateChange?: (state: CheckoutState) => void;
+    /** Custom API base URL (for testing or self-hosted deployments) */
+    apiBaseUrl?: string;
+}
+declare function useReevit(options: UseReevitOptions): {
+    status: CheckoutState;
+    paymentIntent: PaymentIntent | null;
+    selectedMethod: PaymentMethod | null;
+    error: PaymentError | null;
+    result: PaymentResult | null;
+    initialize: (method?: PaymentMethod) => Promise<void>;
+    selectMethod: (method: PaymentMethod) => void;
+    processPayment: (paymentData: Record<string, unknown>) => Promise<void>;
+    handlePspSuccess: (pspData: Record<string, unknown>) => Promise<void>;
+    handlePspError: (error: PaymentError) => void;
+    reset: () => void;
+    close: () => Promise<void>;
+    isLoading: boolean;
+    isReady: boolean;
+    isComplete: boolean;
+    canRetry: boolean;
+};
+
+declare global {
+    interface Window {
+        PaystackPop?: PaystackPopupInterface;
+    }
+}
+interface PaystackPopupInterface {
+    setup: (config: PaystackConfig) => {
+        openIframe: () => void;
+    };
+}
+interface PaystackConfig {
+    key: string;
+    email: string;
+    amount: number;
+    currency?: string;
+    ref?: string;
+    metadata?: Record<string, unknown>;
+    channels?: string[];
+    callback: (response: PaystackResponse) => void;
+    onClose: () => void;
+}
+interface PaystackResponse {
+    reference: string;
+    trans: string;
+    status: string;
+    message: string;
+    transaction: string;
+    trxref: string;
+}
+interface PaystackBridgeProps {
+    publicKey: string;
+    email: string;
+    amount: number;
+    currency?: string;
+    reference?: string;
+    metadata?: Record<string, unknown>;
+    channels?: ('card' | 'bank' | 'ussd' | 'qr' | 'mobile_money' | 'bank_transfer')[];
+    onSuccess: (result: PaymentResult) => void;
+    onError: (error: PaymentError) => void;
+    onClose: () => void;
+    autoStart?: boolean;
+}
+declare function loadPaystackScript(): Promise<void>;
+declare function PaystackBridge({ publicKey, email, amount, currency, reference, metadata, channels, onSuccess, onError, onClose, autoStart, }: PaystackBridgeProps): react_jsx_runtime.JSX.Element;
+
+declare global {
+    interface Window {
+        HubtelCheckout?: HubtelCheckoutInterface;
+    }
+}
+interface HubtelCheckoutInterface {
+    initPayment: (config: HubtelConfig) => void;
+}
+interface HubtelConfig {
+    merchantAccount: string;
+    basicDescription: string;
+    totalAmount: number;
+    currency: string;
+    clientReference: string;
+    customerEmail?: string;
+    customerMsisdn?: string;
+    callbackUrl?: string;
+    onComplete?: (response: HubtelResponse) => void;
+    onCancel?: () => void;
+}
+interface HubtelResponse {
+    status: 'Success' | 'Failed' | 'Cancelled';
+    transactionId: string;
+    clientReference: string;
+    amount: number;
+    currency: string;
+    message?: string;
+}
+interface HubtelBridgeProps {
+    merchantAccount: string;
+    amount: number;
+    currency?: string;
+    reference?: string;
+    email?: string;
+    phone?: string;
+    description?: string;
+    onSuccess: (result: PaymentResult) => void;
+    onError: (error: PaymentError) => void;
+    onClose: () => void;
+    autoStart?: boolean;
+}
+declare function loadHubtelScript(): Promise<void>;
+declare function HubtelBridge({ merchantAccount, amount, currency, reference, email, phone, description, onSuccess, onError, onClose, autoStart, }: HubtelBridgeProps): react_jsx_runtime.JSX.Element;
+
+declare global {
+    interface Window {
+        FlutterwaveCheckout?: (config: FlutterwaveConfig) => void;
+    }
+}
+interface FlutterwaveConfig {
+    public_key: string;
+    tx_ref: string;
+    amount: number;
+    currency: string;
+    payment_options?: string;
+    customer: {
+        email: string;
+        phone_number?: string;
+        name?: string;
+    };
+    customizations?: {
+        title?: string;
+        description?: string;
+        logo?: string;
+    };
+    meta?: Record<string, unknown>;
+    callback: (response: FlutterwaveResponse) => void;
+    onclose: () => void;
+}
+interface FlutterwaveResponse {
+    status: 'successful' | 'failed' | 'cancelled';
+    transaction_id: number;
+    tx_ref: string;
+    flw_ref: string;
+    amount: number;
+    currency: string;
+    charged_amount: number;
+    payment_type: string;
+}
+interface FlutterwaveBridgeProps {
+    publicKey: string;
+    amount: number;
+    currency?: string;
+    reference?: string;
+    email: string;
+    phone?: string;
+    name?: string;
+    paymentOptions?: string;
+    title?: string;
+    description?: string;
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    onSuccess: (result: PaymentResult) => void;
+    onError: (error: PaymentError) => void;
+    onClose: () => void;
+    autoStart?: boolean;
+}
+declare function loadFlutterwaveScript(): Promise<void>;
+declare function FlutterwaveBridge({ publicKey, amount, currency, reference, email, phone, name, paymentOptions, title, description, logo, metadata, onSuccess, onError, onClose, autoStart, }: FlutterwaveBridgeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * StripeBridge.tsx
+ * React component for Stripe payment integration
+ */
+declare global {
+    interface Window {
+        Stripe?: (publishableKey: string) => StripeInstance;
+    }
+}
+interface StripeInstance {
+    elements: (options?: {
+        clientSecret: string;
+        appearance?: StripeAppearance;
+    }) => StripeElements;
+    confirmPayment: (options: {
+        elements: StripeElements;
+        confirmParams?: {
+            return_url?: string;
+        };
+        redirect?: 'if_required';
+    }) => Promise<{
+        error?: StripeError;
+        paymentIntent?: {
+            id: string;
+            status: string;
+        };
+    }>;
+}
+interface StripeElements {
+    create: (type: 'payment' | 'card', options?: Record<string, unknown>) => StripeElement;
+    getElement: (type: string) => StripeElement | null;
+    submit: () => Promise<{
+        error?: StripeError;
+    }>;
+}
+interface StripeElement {
+    mount: (selector: string | HTMLElement) => void;
+    unmount: () => void;
+    on: (event: string, handler: (e: any) => void) => void;
+    destroy: () => void;
+}
+interface StripeError {
+    type: string;
+    message: string;
+    code?: string;
+}
+interface StripeAppearance {
+    theme?: 'stripe' | 'night' | 'flat';
+    variables?: Record<string, string>;
+    rules?: Record<string, Record<string, string>>;
+}
+interface StripeBridgeProps {
+    publishableKey: string;
+    clientSecret: string;
+    amount: number;
+    currency: string;
+    appearance?: StripeAppearance;
+    onSuccess: (result: {
+        paymentIntentId: string;
+        status: string;
+    }) => void;
+    onError: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    onReady?: () => void;
+    onCancel?: () => void;
+}
+declare function loadStripeScript(): Promise<void>;
+declare function StripeBridge({ publishableKey, clientSecret, amount, currency, appearance, onSuccess, onError, onReady, onCancel, }: StripeBridgeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * MonnifyBridge.tsx
+ * React component for Monnify payment integration (Nigeria)
+ */
+declare global {
+    interface Window {
+        MonnifySDK?: {
+            initialize: (config: MonnifyConfig) => void;
+        };
+    }
+}
+interface MonnifyConfig {
+    amount: number;
+    currency: string;
+    reference: string;
+    customerName: string;
+    customerEmail: string;
+    customerMobileNumber?: string;
+    apiKey: string;
+    contractCode: string;
+    paymentDescription?: string;
+    isTestMode?: boolean;
+    metadata?: Record<string, unknown>;
+    onComplete: (response: MonnifyResponse) => void;
+    onClose: () => void;
+}
+interface MonnifyResponse {
+    status: 'SUCCESS' | 'FAILED' | 'PENDING';
+    message: string;
+    transactionReference: string;
+    paymentReference: string;
+    authorizedAmount?: number;
+    paymentStatus?: string;
+}
+interface MonnifyBridgeProps {
+    apiKey: string;
+    contractCode: string;
+    amount: number;
+    currency: string;
+    reference: string;
+    customerName: string;
+    customerEmail: string;
+    customerPhone?: string;
+    paymentDescription?: string;
+    isTestMode?: boolean;
+    metadata?: Record<string, unknown>;
+    autoOpen?: boolean;
+    onSuccess: (result: {
+        transactionReference: string;
+        paymentReference: string;
+        amount: number;
+    }) => void;
+    onError: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    onClose?: () => void;
+}
+declare function loadMonnifyScript(): Promise<void>;
+declare function MonnifyBridge({ apiKey, contractCode, amount, currency, reference, customerName, customerEmail, customerPhone, paymentDescription, isTestMode, metadata, autoOpen, onSuccess, onError, onClose, }: MonnifyBridgeProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * MPesaBridge.tsx
+ * React component for M-Pesa STK Push integration (Kenya/Tanzania)
+ *
+ * Note: M-Pesa uses server-to-server STK Push initiated by the backend.
+ * This component handles the UI flow while the customer approves on their phone.
+ */
+interface MPesaBridgeProps {
+    /** API endpoint to initiate STK Push (your backend) */
+    apiEndpoint: string;
+    /** Customer phone number in format 254XXXXXXXXX */
+    phoneNumber: string;
+    /** Amount to charge */
+    amount: number;
+    /** Currency (KES or TZS) */
+    currency: string;
+    /** Unique transaction reference */
+    reference: string;
+    /** Payment description */
+    description?: string;
+    /** Called when STK Push is successfully sent */
+    onInitiated?: (checkoutRequestId: string) => void;
+    /** Called when payment is confirmed (via webhook/polling) */
+    onSuccess: (result: {
+        transactionId: string;
+        reference: string;
+    }) => void;
+    /** Called on error */
+    onError: (error: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Custom headers for API calls (e.g., authorization) */
+    headers?: Record<string, string>;
+}
+declare function MPesaBridge({ apiEndpoint, phoneNumber, amount, currency, reference, description, onInitiated, onSuccess, onError, headers, }: MPesaBridgeProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Hook for M-Pesa payment status polling
+ * Use this to check payment status after STK Push is initiated
+ */
+declare function useMPesaStatusPolling(statusEndpoint: string, checkoutRequestId: string | null, options: {
+    interval?: number;
+    maxAttempts?: number;
+    headers?: Record<string, string>;
+    onSuccess: (result: {
+        transactionId: string;
+    }) => void;
+    onFailed: (error: {
+        message: string;
+    }) => void;
+    onTimeout: () => void;
+}): {
+    startPolling: () => Promise<void>;
+};
+
+/**
+ * Reevit API Client
+ *
+ * Handles communication with the Reevit backend for payment operations.
+ */
+
+interface PaymentIntentResponse {
+    id: string;
+    connection_id: string;
+    provider: string;
+    status: string;
+    client_secret: string;
+    amount: number;
+    currency: string;
+    fee_amount: number;
+    fee_currency: string;
+    net_amount: number;
+}
+interface PaymentDetailResponse {
+    id: string;
+    connection_id: string;
+    provider: string;
+    method: string;
+    status: string;
+    amount: number;
+    currency: string;
+    fee_amount: number;
+    fee_currency: string;
+    net_amount: number;
+    customer_id?: string;
+    client_secret: string;
+    provider_ref_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+interface ReevitAPIClientConfig {
+    /** Your Reevit public key */
+    publicKey: string;
+    /** Base URL for the Reevit API (defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Reevit API Client
+ */
+declare class ReevitAPIClient {
+    private readonly publicKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: ReevitAPIClientConfig);
+    /**
+     * Makes an authenticated API request
+     */
+    private request;
+    /**
+     * Creates a payment intent
+     */
+    createPaymentIntent(config: ReevitCheckoutConfig, method: PaymentMethod, country?: string): Promise<{
+        data?: PaymentIntentResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Retrieves a payment intent by ID
+     */
+    getPaymentIntent(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Confirms a payment after PSP callback
+     */
+    confirmPayment(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Cancels a payment intent
+     */
+    cancelPaymentIntent(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Maps SDK payment method to backend format
+     */
+    private mapPaymentMethod;
+}
+/**
+ * Creates a new Reevit API client instance
+ */
+declare function createReevitClient(config: ReevitAPIClientConfig): ReevitAPIClient;
+
+/**
+ * Utility functions for the Reevit React SDK
+ */
+/**
+ * Format amount for display
+ */
+declare function formatAmount(amount: number, currency: string): string;
+/**
+ * Validate phone number for mobile money
+ */
+declare function validatePhone(phone: string, network?: string): boolean;
+/**
+ * Format phone number for display
+ */
+declare function formatPhone(phone: string): string;
+/**
+ * Detect mobile money network from phone number
+ */
+declare function detectNetwork(phone: string): string | null;
+
+export { type CheckoutState, FlutterwaveBridge, HubtelBridge, MPesaBridge, type MPesaBridgeProps, MobileMoneyForm, type MobileMoneyFormData, type MobileMoneyNetwork, MonnifyBridge, type MonnifyBridgeProps, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, PaymentMethodSelector, type PaymentResult, PaystackBridge, ReevitAPIClient, type ReevitAPIClientConfig, ReevitCheckout, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitCheckoutProps, type ReevitTheme, StripeBridge, type StripeBridgeProps, createReevitClient, detectNetwork, formatAmount, formatPhone, loadFlutterwaveScript, loadHubtelScript, loadMonnifyScript, loadPaystackScript, loadStripeScript, useMPesaStatusPolling, useReevit, useReevitContext, validatePhone };