react-native-payvessel 1.0.0

package/src/types.ts

@@ -0,0 +1,200 @@
+/**
+ * Payment status enum
+ */
+export enum PaymentStatus {
+  SUCCESS = 'success',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  PENDING = 'pending',
+}
+
+/**
+ * Payment channels supported by Payvessel
+ */
+export enum PaymentChannel {
+  BANK_TRANSFER = 'BANK_TRANSFER',
+  CARD = 'CARD',
+}
+
+/**
+ * Checkout configuration
+ */
+export interface CheckoutConfig {
+  /** Your Payvessel API key */
+  apiKey: string;
+}
+
+/**
+ * Customer information for checkout
+ */
+export interface CustomerInfo {
+  /** Customer's email address */
+  email: string;
+  /** Customer's phone number */
+  phoneNumber?: string;
+  /** Customer's full name */
+  name: string;
+}
+
+/**
+ * Payment information
+ */
+export interface PaymentInfo {
+  /** Amount to charge (as string or number) */
+  amount: string | number;
+  /** Currency code (default: NGN) */
+  currency?: string;
+  /** Payment channels to enable */
+  channels?: PaymentChannel[];
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Unique transaction reference */
+  reference?: string;
+}
+
+/**
+ * Checkout parameters combining customer and payment info
+ */
+export interface CheckoutParams extends CustomerInfo, PaymentInfo {}
+
+/**
+ * Transaction data returned from initialization
+ */
+export interface TransactionData {
+  id: string;
+  reference: string;
+  access_code: string;
+  amount: number;
+  currency: string;
+  customer_email: string;
+  customer_name: string;
+  status: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Success response from checkout
+ */
+export interface PayvesselSuccessResponse {
+  status: PaymentStatus.SUCCESS;
+  reference?: string;
+  transactionId?: string;
+  accessCode?: string;
+  paymentId?: string;
+  data?: TransactionData | Record<string, unknown>;
+}
+
+/**
+ * Error response from checkout
+ */
+export interface PayvesselErrorResponse {
+  status: PaymentStatus.FAILED;
+  message: string;
+  code?: string;
+}
+
+/**
+ * Close response
+ */
+export interface PayvesselCloseResponse {
+  status: PaymentStatus.CANCELLED;
+  reference?: string;
+}
+
+/**
+ * Combined response type
+ */
+export type PayvesselResponse = 
+  | PayvesselSuccessResponse 
+  | PayvesselErrorResponse 
+  | PayvesselCloseResponse;
+
+/**
+ * Callback types
+ */
+export type OnSuccessCallback = (response: PayvesselSuccessResponse) => void;
+export type OnErrorCallback = (error: PayvesselErrorResponse) => void;
+export type OnCloseCallback = () => void;
+export type OnSuccessfulOrderCallback = (response: PayvesselSuccessResponse) => void;
+
+/**
+ * Props for PayvesselCheckout component
+ */
+export interface PayvesselCheckoutProps {
+  /** Whether the checkout modal is visible */
+  visible: boolean;
+  
+  /** Your Payvessel API key */
+  apiKey: string;
+  
+  /** Customer's email address */
+  customerEmail: string;
+  
+  /** Customer's phone number */
+  customerPhoneNumber?: string;
+  
+  /** Amount to charge */
+  amount: string | number;
+  
+  /** Currency code (default: NGN) */
+  currency?: string;
+  
+  /** Customer's full name */
+  customerName: string;
+  
+  /** Payment channels to enable (default: ['BANK_TRANSFER']) */
+  channels?: PaymentChannel[] | string[];
+  
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  
+  /** Unique transaction reference */
+  reference?: string;
+  
+  /** Called when transaction is initialized successfully */
+  onSuccess?: OnSuccessCallback;
+  
+  /** Called when an error occurs */
+  onError?: OnErrorCallback;
+  
+  /** Called when checkout is closed */
+  onClose?: OnCloseCallback;
+  
+  /** Called when payment is confirmed successful */
+  onSuccessfulOrder?: OnSuccessfulOrderCallback;
+  
+  /** Show close button (default: true) */
+  showCloseButton?: boolean;
+  
+  /** Close button text (default: '✕') */
+  closeButtonText?: string;
+  
+  /** Loading text (default: 'Initializing checkout...') */
+  loadingText?: string;
+  
+  /** Header title (default: 'Checkout') */
+  headerTitle?: string;
+  
+  /** Show header (default: true) */
+  showHeader?: boolean;
+}
+
+/**
+ * Hook return type
+ */
+export interface UsePayvesselReturn {
+  /** Whether checkout is visible */
+  isVisible: boolean;
+  /** Whether checkout is loading */
+  isLoading: boolean;
+  /** Current error message */
+  error: string | null;
+  /** Transaction data */
+  transactionData: TransactionData | null;
+  /** Open the checkout */
+  openCheckout: (params: CheckoutParams) => void;
+  /** Close the checkout */
+  closeCheckout: () => void;
+  /** The checkout component to render */
+  CheckoutModal: React.FC;
+}

package/src/usePayvessel.ts

@@ -0,0 +1,156 @@
+/**
+ * usePayvessel Hook
+ *
+ * A React Hook for programmatically controlling the Payvessel checkout.
+ */
+
+import { useState, useCallback } from 'react';
+import type {
+  CheckoutParams,
+  TransactionData,
+  PayvesselSuccessResponse,
+  PayvesselErrorResponse,
+} from './types';
+import { PaymentStatus } from './types';
+
+export interface UsePayvesselOptions {
+  /** Your Payvessel API key */
+  apiKey: string;
+  /** Called when payment is successful */
+  onSuccess?: (response: PayvesselSuccessResponse) => void;
+  /** Called when payment fails */
+  onError?: (error: PayvesselErrorResponse) => void;
+  /** Called when checkout is closed */
+  onClose?: () => void;
+}
+
+export interface UsePayvesselReturn {
+  /** Whether the checkout is currently visible */
+  isVisible: boolean;
+  /** Whether the checkout is loading */
+  isLoading: boolean;
+  /** Current error message, if any */
+  error: string | null;
+  /** Transaction data from initialization */
+  transactionData: TransactionData | null;
+  /** Open the checkout with given parameters */
+  openCheckout: (params: CheckoutParams) => void;
+  /** Close the checkout */
+  closeCheckout: () => void;
+  /** Reset any error state */
+  resetError: () => void;
+  /** Props to spread on PayvesselCheckout component */
+  checkoutProps: {
+    visible: boolean;
+    apiKey: string;
+    customerEmail: string;
+    customerPhoneNumber?: string;
+    customerName: string;
+    amount: string | number;
+    currency?: string;
+    channels?: string[];
+    metadata?: Record<string, unknown>;
+    reference?: string;
+    onSuccess?: (response: PayvesselSuccessResponse) => void;
+    onError?: (error: PayvesselErrorResponse) => void;
+    onClose?: () => void;
+  } | null;
+}
+
+/**
+ * Hook for managing Payvessel checkout state
+ *
+ * @example
+ * ```tsx
+ * const { openCheckout, closeCheckout, checkoutProps } = usePayvessel({
+ *   apiKey: 'YOUR_API_KEY',
+ *   onSuccess: (response) => console.log('Payment successful', response),
+ *   onError: (error) => console.log('Payment failed', error),
+ *   onClose: () => console.log('Checkout closed'),
+ * });
+ *
+ * // Open checkout
+ * openCheckout({
+ *   email: 'customer@example.com',
+ *   name: 'John Doe',
+ *   amount: 1000,
+ * });
+ *
+ * // In your JSX
+ * {checkoutProps && <PayvesselCheckout {...checkoutProps} />}
+ * ```
+ */
+export function usePayvessel(options: UsePayvesselOptions): UsePayvesselReturn {
+  const { apiKey, onSuccess, onError, onClose } = options;
+
+  const [isVisible, setIsVisible] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [transactionData, setTransactionData] = useState<TransactionData | null>(null);
+  const [checkoutParams, setCheckoutParams] = useState<CheckoutParams | null>(null);
+
+  const openCheckout = useCallback((params: CheckoutParams) => {
+    setCheckoutParams(params);
+    setIsVisible(true);
+    setIsLoading(true);
+    setError(null);
+  }, []);
+
+  const closeCheckout = useCallback(() => {
+    setIsVisible(false);
+    setIsLoading(false);
+    setCheckoutParams(null);
+    setTransactionData(null);
+    onClose?.();
+  }, [onClose]);
+
+  const resetError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const handleSuccess = useCallback((response: PayvesselSuccessResponse) => {
+    setIsLoading(false);
+    setTransactionData(response.data as TransactionData || null);
+    onSuccess?.(response);
+    closeCheckout();
+  }, [onSuccess, closeCheckout]);
+
+  const handleError = useCallback((errorResponse: PayvesselErrorResponse) => {
+    setIsLoading(false);
+    setError(errorResponse.message);
+    onError?.(errorResponse);
+  }, [onError]);
+
+  const handleClose = useCallback(() => {
+    closeCheckout();
+  }, [closeCheckout]);
+
+  const checkoutProps = checkoutParams ? {
+    visible: isVisible,
+    apiKey,
+    customerEmail: checkoutParams.email,
+    customerPhoneNumber: checkoutParams.phoneNumber,
+    customerName: checkoutParams.name,
+    amount: checkoutParams.amount,
+    currency: checkoutParams.currency,
+    channels: checkoutParams.channels,
+    metadata: checkoutParams.metadata,
+    reference: checkoutParams.reference,
+    onSuccess: handleSuccess,
+    onError: handleError,
+    onClose: handleClose,
+  } : null;
+
+  return {
+    isVisible,
+    isLoading,
+    error,
+    transactionData,
+    openCheckout,
+    closeCheckout,
+    resetError,
+    checkoutProps,
+  };
+}
+
+export default usePayvessel;