@xpayeg/react 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,239 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, FC } from 'react';
+import * as _xpayeg_sdk from '@xpayeg/sdk';
+import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CardElementOptions, CardElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
+export { ActionResult, Appearance, CardElementChangeEvent, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
+
+/**
+ * The checkout object returned by `useCheckout()` on success.
+ * Merges session data with action methods for a single unified API.
+ *
+ * @example
+ * ```tsx
+ * const state = useCheckout();
+ * if (state.type === "success") {
+ *   const checkout: Checkout = state.checkout;
+ *   console.log(checkout.amountTotal);    // session data
+ *   await checkout.confirm();             // action method
+ * }
+ * ```
+ */
+type Checkout = CheckoutSession & CheckoutActions;
+type UseCheckoutResult = {
+    type: "loading";
+} | {
+    type: "error";
+    error: {
+        message: string;
+    };
+} | {
+    type: "success";
+    checkout: Checkout;
+};
+interface XPayProviderProps {
+    /**
+     * XPay instance or a Promise resolving to one.
+     * Use `loadXPay()` from `@xpayeg/sdk` — call it at module level, not inside a component.
+     */
+    xpay: XPayInstance | Promise<XPayInstance | null> | null;
+    /** Elements options. Must include `clientSecret`. */
+    options?: ElementsOptions;
+    children: ReactNode;
+}
+/**
+ * Provides XPay context to all child components.
+ *
+ * Accepts either a resolved XPay instance or a Promise (from `loadXPay()`).
+ * When `options` (with `clientSecret`) is provided, creates an Elements instance
+ * and fetches session data. Use `useCheckout()` in child components to access
+ * session data and action methods.
+ *
+ * @example
+ * ```tsx
+ * import { loadXPay } from "@xpayeg/sdk";
+ * import { XPayProvider, useCheckout, PaymentElement } from "@xpayeg/react";
+ *
+ * const xpayPromise = loadXPay("pk_test_xxx");
+ *
+ * function App() {
+ *   return (
+ *     <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+ *       <CheckoutForm />
+ *     </XPayProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function XPayProvider({ xpay: xpayProp, options, children }: XPayProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the checkout state — a tagged union of `loading`, `error`, or `success`.
+ *
+ * On success, returns a `checkout` object (type `Checkout`) that merges
+ * session data with action methods (confirm, promo codes, quantities, etc.).
+ *
+ * @returns `UseCheckoutResult` — narrow the type by checking `result.type`
+ * @throws Error if used outside of `<XPayProvider>`
+ *
+ * @example
+ * ```tsx
+ * function CheckoutForm() {
+ *   const state = useCheckout();
+ *
+ *   if (state.type === "loading") return <Skeleton />;
+ *   if (state.type === "error") return <p>{state.error.message}</p>;
+ *
+ *   const { checkout } = state;
+ *   return <button onClick={() => checkout.confirm()}>
+ *     Pay {checkout.currency} {checkout.amountTotal}
+ *   </button>;
+ * }
+ * ```
+ */
+declare function useCheckout(): UseCheckoutResult;
+/**
+ * Access the raw XPay SDK instance. Returns `null` while the SDK is loading.
+ *
+ * Most merchants should use `useCheckout()` instead. Use `useXPay()` only when
+ * you need direct access to `xpay.confirmPayment()` or `xpay.checkout()`.
+ */
+declare function useXPay(): XPayInstance | null;
+/**
+ * Access the Elements instance. Returns `null` while the session is loading.
+ *
+ * Use this for direct element management. In most cases, use `useCheckout()` instead
+ * which provides both session data and action methods.
+ */
+declare function useElements(): Elements | null;
+
+/**
+ * Convenience hook for payment confirmation.
+ *
+ * @example
+ * ```tsx
+ * const { confirmPayment, isConfirming } = useConfirmPayment();
+ * ```
+ */
+declare function useConfirmPayment(): {
+    confirmPayment: () => Promise<{
+        type: "error";
+        error: {
+            message: string;
+            code: null;
+        };
+    }>;
+    isConfirming: boolean;
+} | {
+    confirmPayment: (options?: Omit<_xpayeg_sdk.ConfirmPaymentOptions, "elements">) => Promise<_xpayeg_sdk.ActionResult>;
+    isConfirming: boolean;
+};
+
+interface PaymentElementProps {
+    /** Element configuration options (layout, default payment method, ordering) */
+    options?: PaymentElementOptions;
+    /** Fired when the element is mounted and the iframe content is ready */
+    onReady?: () => void;
+    /**
+     * Fired on every state change — payment method selection, card field input, completion.
+     * Use `event.complete` to enable/disable your pay button.
+     */
+    onChange?: (event: PaymentElementChangeEvent) => void;
+    /** Fired when the element's iframe starts loading — show a custom loading skeleton */
+    onLoaderStart?: () => void;
+    /** Fired when the element fails to load (network error, invalid client secret) */
+    onLoadError?: (event: {
+        type: string;
+        message: string;
+        code?: string;
+    }) => void;
+    /** CSS class name for the container `<div>` */
+    className?: string;
+    /** HTML id for the container `<div>` */
+    id?: string;
+}
+/**
+ * Renders the XPay Payment Element — a full payment method selector with card form.
+ *
+ * Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+ * Handles mount/unmount lifecycle, StrictMode, and SSR automatically.
+ *
+ * @example
+ * ```tsx
+ * <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+ *   <PaymentElement
+ *     onChange={(e) => setPaymentReady(e.complete)}
+ *     onLoadError={(e) => console.error(e.message)}
+ *   />
+ * </XPayProvider>
+ * ```
+ */
+declare const PaymentElement: FC<PaymentElementProps>;
+
+interface CardElementProps {
+    /** Element configuration options */
+    options?: CardElementOptions;
+    /** Fired when the element is mounted and the iframe content is ready */
+    onReady?: () => void;
+    /** Fired on every card field change — use `event.complete` to enable/disable your pay button */
+    onChange?: (event: CardElementChangeEvent) => void;
+    /** Fired when the element's iframe starts loading */
+    onLoaderStart?: () => void;
+    /** Fired when the element fails to load */
+    onLoadError?: (event: {
+        type: string;
+        message: string;
+        code?: string;
+    }) => void;
+    /** CSS class name for the container `<div>` */
+    className?: string;
+    /** HTML id for the container `<div>` */
+    id?: string;
+}
+/**
+ * Renders the XPay Card Element — a card-only form (number, expiry, CVV).
+ *
+ * Use this when you handle payment method selection yourself.
+ * Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+ *
+ * @example
+ * ```tsx
+ * <CardElement
+ *   onChange={(e) => setCardReady(e.complete)}
+ * />
+ * ```
+ */
+declare const CardElement: FC<CardElementProps>;
+
+interface CheckoutButtonProps {
+    /** Checkout session client secret */
+    clientSecret: string;
+    /** Button content */
+    children?: ReactNode;
+    /** Checkout options (callbacks, appearance, locale) */
+    checkoutOptions?: Omit<CheckoutOptions, "clientSecret" | "mode">;
+    className?: string;
+    disabled?: boolean;
+}
+/**
+ * Button that opens the drop-in checkout modal on click.
+ *
+ * Must be inside XPayProvider.
+ *
+ * @example
+ * ```tsx
+ * <XPayProvider xpay={xpay}>
+ *   <CheckoutButton
+ *     clientSecret="cs_test_abc_secret_xyz"
+ *     checkoutOptions={{
+ *       onComplete: (result) => router.push('/success'),
+ *       onClose: () => console.log('Closed'),
+ *     }}
+ *   >
+ *     Pay Now
+ *   </CheckoutButton>
+ * </XPayProvider>
+ * ```
+ */
+declare const CheckoutButton: FC<CheckoutButtonProps>;
+
+export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
+export type { CardElementProps, Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };

package/dist/index.d.mts

@@ -0,0 +1,239 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, FC } from 'react';
+import * as _xpayeg_sdk from '@xpayeg/sdk';
+import { CheckoutSession, CheckoutActions, XPayInstance, ElementsOptions, Elements, PaymentElementOptions, PaymentElementChangeEvent, CardElementOptions, CardElementChangeEvent, CheckoutOptions } from '@xpayeg/sdk';
+export { ActionResult, Appearance, CardElementChangeEvent, CheckoutActions, CheckoutSession, ConfirmPaymentOptions, ElementsOptions, PaymentElementChangeEvent, PaymentMethodInfo, XPayError } from '@xpayeg/sdk';
+
+/**
+ * The checkout object returned by `useCheckout()` on success.
+ * Merges session data with action methods for a single unified API.
+ *
+ * @example
+ * ```tsx
+ * const state = useCheckout();
+ * if (state.type === "success") {
+ *   const checkout: Checkout = state.checkout;
+ *   console.log(checkout.amountTotal);    // session data
+ *   await checkout.confirm();             // action method
+ * }
+ * ```
+ */
+type Checkout = CheckoutSession & CheckoutActions;
+type UseCheckoutResult = {
+    type: "loading";
+} | {
+    type: "error";
+    error: {
+        message: string;
+    };
+} | {
+    type: "success";
+    checkout: Checkout;
+};
+interface XPayProviderProps {
+    /**
+     * XPay instance or a Promise resolving to one.
+     * Use `loadXPay()` from `@xpayeg/sdk` — call it at module level, not inside a component.
+     */
+    xpay: XPayInstance | Promise<XPayInstance | null> | null;
+    /** Elements options. Must include `clientSecret`. */
+    options?: ElementsOptions;
+    children: ReactNode;
+}
+/**
+ * Provides XPay context to all child components.
+ *
+ * Accepts either a resolved XPay instance or a Promise (from `loadXPay()`).
+ * When `options` (with `clientSecret`) is provided, creates an Elements instance
+ * and fetches session data. Use `useCheckout()` in child components to access
+ * session data and action methods.
+ *
+ * @example
+ * ```tsx
+ * import { loadXPay } from "@xpayeg/sdk";
+ * import { XPayProvider, useCheckout, PaymentElement } from "@xpayeg/react";
+ *
+ * const xpayPromise = loadXPay("pk_test_xxx");
+ *
+ * function App() {
+ *   return (
+ *     <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+ *       <CheckoutForm />
+ *     </XPayProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function XPayProvider({ xpay: xpayProp, options, children }: XPayProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the checkout state — a tagged union of `loading`, `error`, or `success`.
+ *
+ * On success, returns a `checkout` object (type `Checkout`) that merges
+ * session data with action methods (confirm, promo codes, quantities, etc.).
+ *
+ * @returns `UseCheckoutResult` — narrow the type by checking `result.type`
+ * @throws Error if used outside of `<XPayProvider>`
+ *
+ * @example
+ * ```tsx
+ * function CheckoutForm() {
+ *   const state = useCheckout();
+ *
+ *   if (state.type === "loading") return <Skeleton />;
+ *   if (state.type === "error") return <p>{state.error.message}</p>;
+ *
+ *   const { checkout } = state;
+ *   return <button onClick={() => checkout.confirm()}>
+ *     Pay {checkout.currency} {checkout.amountTotal}
+ *   </button>;
+ * }
+ * ```
+ */
+declare function useCheckout(): UseCheckoutResult;
+/**
+ * Access the raw XPay SDK instance. Returns `null` while the SDK is loading.
+ *
+ * Most merchants should use `useCheckout()` instead. Use `useXPay()` only when
+ * you need direct access to `xpay.confirmPayment()` or `xpay.checkout()`.
+ */
+declare function useXPay(): XPayInstance | null;
+/**
+ * Access the Elements instance. Returns `null` while the session is loading.
+ *
+ * Use this for direct element management. In most cases, use `useCheckout()` instead
+ * which provides both session data and action methods.
+ */
+declare function useElements(): Elements | null;
+
+/**
+ * Convenience hook for payment confirmation.
+ *
+ * @example
+ * ```tsx
+ * const { confirmPayment, isConfirming } = useConfirmPayment();
+ * ```
+ */
+declare function useConfirmPayment(): {
+    confirmPayment: () => Promise<{
+        type: "error";
+        error: {
+            message: string;
+            code: null;
+        };
+    }>;
+    isConfirming: boolean;
+} | {
+    confirmPayment: (options?: Omit<_xpayeg_sdk.ConfirmPaymentOptions, "elements">) => Promise<_xpayeg_sdk.ActionResult>;
+    isConfirming: boolean;
+};
+
+interface PaymentElementProps {
+    /** Element configuration options (layout, default payment method, ordering) */
+    options?: PaymentElementOptions;
+    /** Fired when the element is mounted and the iframe content is ready */
+    onReady?: () => void;
+    /**
+     * Fired on every state change — payment method selection, card field input, completion.
+     * Use `event.complete` to enable/disable your pay button.
+     */
+    onChange?: (event: PaymentElementChangeEvent) => void;
+    /** Fired when the element's iframe starts loading — show a custom loading skeleton */
+    onLoaderStart?: () => void;
+    /** Fired when the element fails to load (network error, invalid client secret) */
+    onLoadError?: (event: {
+        type: string;
+        message: string;
+        code?: string;
+    }) => void;
+    /** CSS class name for the container `<div>` */
+    className?: string;
+    /** HTML id for the container `<div>` */
+    id?: string;
+}
+/**
+ * Renders the XPay Payment Element — a full payment method selector with card form.
+ *
+ * Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+ * Handles mount/unmount lifecycle, StrictMode, and SSR automatically.
+ *
+ * @example
+ * ```tsx
+ * <XPayProvider xpay={xpayPromise} options={{ clientSecret }}>
+ *   <PaymentElement
+ *     onChange={(e) => setPaymentReady(e.complete)}
+ *     onLoadError={(e) => console.error(e.message)}
+ *   />
+ * </XPayProvider>
+ * ```
+ */
+declare const PaymentElement: FC<PaymentElementProps>;
+
+interface CardElementProps {
+    /** Element configuration options */
+    options?: CardElementOptions;
+    /** Fired when the element is mounted and the iframe content is ready */
+    onReady?: () => void;
+    /** Fired on every card field change — use `event.complete` to enable/disable your pay button */
+    onChange?: (event: CardElementChangeEvent) => void;
+    /** Fired when the element's iframe starts loading */
+    onLoaderStart?: () => void;
+    /** Fired when the element fails to load */
+    onLoadError?: (event: {
+        type: string;
+        message: string;
+        code?: string;
+    }) => void;
+    /** CSS class name for the container `<div>` */
+    className?: string;
+    /** HTML id for the container `<div>` */
+    id?: string;
+}
+/**
+ * Renders the XPay Card Element — a card-only form (number, expiry, CVV).
+ *
+ * Use this when you handle payment method selection yourself.
+ * Must be used inside `<XPayProvider>` with an `options` prop containing `clientSecret`.
+ *
+ * @example
+ * ```tsx
+ * <CardElement
+ *   onChange={(e) => setCardReady(e.complete)}
+ * />
+ * ```
+ */
+declare const CardElement: FC<CardElementProps>;
+
+interface CheckoutButtonProps {
+    /** Checkout session client secret */
+    clientSecret: string;
+    /** Button content */
+    children?: ReactNode;
+    /** Checkout options (callbacks, appearance, locale) */
+    checkoutOptions?: Omit<CheckoutOptions, "clientSecret" | "mode">;
+    className?: string;
+    disabled?: boolean;
+}
+/**
+ * Button that opens the drop-in checkout modal on click.
+ *
+ * Must be inside XPayProvider.
+ *
+ * @example
+ * ```tsx
+ * <XPayProvider xpay={xpay}>
+ *   <CheckoutButton
+ *     clientSecret="cs_test_abc_secret_xyz"
+ *     checkoutOptions={{
+ *       onComplete: (result) => router.push('/success'),
+ *       onClose: () => console.log('Closed'),
+ *     }}
+ *   >
+ *     Pay Now
+ *   </CheckoutButton>
+ * </XPayProvider>
+ * ```
+ */
+declare const CheckoutButton: FC<CheckoutButtonProps>;
+
+export { CardElement, CheckoutButton, PaymentElement, XPayProvider, useCheckout, useConfirmPayment, useElements, useXPay };
+export type { CardElementProps, Checkout, CheckoutButtonProps, PaymentElementProps, UseCheckoutResult };