@moneymq/react 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -32,73 +32,286 @@ interface SandboxContextState {
     isSandboxMode: boolean;
     sandboxAccounts: SandboxAccount[];
 }
+declare const MoneyMQContext: React.Context<MoneyMQClient | null>;
+declare const SandboxContext: React.Context<SandboxContextState>;
 declare function useMoneyMQ(): MoneyMQClient;
 declare function useSandbox(): SandboxContextState;
 declare function MoneyMQProvider({ children, client, branding, }: MoneyMQProviderProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Represents a completed payment transaction.
+ *
+ * @example
+ * ```tsx
+ * const handleSuccess = (payment: Payment) => {
+ *   console.log(`Payment ${payment.id} completed for ${payment.amount} ${payment.currency}`);
+ *   console.log(`Transaction signature: ${payment.signature}`);
+ * };
+ * ```
+ */
 interface Payment$1 {
+    /** Unique payment identifier (e.g., "pay_1234567890") */
     id: string;
+    /** Payment amount in the currency's standard unit (e.g., 9.99 for $9.99) */
     amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Current status of the payment */
     status: 'pending' | 'completed' | 'failed';
+    /** Blockchain transaction signature (available after completion) */
     signature?: string;
 }
+/**
+ * Represents a price for a product.
+ *
+ * @example
+ * ```tsx
+ * const price: Price = {
+ *   id: 'price_abc123',
+ *   unit_amount: 999, // $9.99 in cents
+ *   currency: 'USDC',
+ *   product: 'prod_xyz789',
+ * };
+ * ```
+ */
 interface Price {
+    /** Unique price identifier from your catalog */
     id: string;
+    /** Price amount in cents (e.g., 999 for $9.99) */
     unit_amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Associated product ID */
     product?: string;
 }
+/**
+ * Represents a product in your catalog.
+ *
+ * @example
+ * ```tsx
+ * const product: Product = {
+ *   id: 'prod_xyz789',
+ *   name: 'Pro Subscription',
+ *   description: 'Monthly access to premium features',
+ * };
+ * ```
+ */
 interface Product {
+    /** Unique product identifier from your catalog */
     id: string;
+    /** Display name shown to the customer */
     name: string;
+    /** Optional description for additional context */
     description?: string;
 }
+/**
+ * Represents an item in the checkout basket.
+ *
+ * @example
+ * ```tsx
+ * const item: BasketItem = {
+ *   product: { id: 'prod_123', name: 'Pro Plan' },
+ *   price: { id: 'price_456', unit_amount: 999, currency: 'USDC' },
+ *   quantity: 1,
+ * };
+ * ```
+ */
 interface BasketItem {
-    /** Product details */
+    /** Product details including id and name */
     product: Product;
-    /** Price details */
+    /** Price details including amount and currency */
     price: Price;
-    /** Quantity (defaults to 1) */
+    /** Number of items (defaults to 1) */
     quantity?: number;
 }
-interface PayButtonProps {
-    /** Basket of items to purchase */
+/**
+ * Props for the CheckoutButton component.
+ *
+ * @example
+ * ```tsx
+ * <CheckoutButton
+ *   basket={[{ product, price }]}
+ *   onSuccess={(payment) => console.log('Paid!', payment.id)}
+ *   onError={(error) => console.error('Failed:', error)}
+ *   variant="solid"
+ * >
+ *   Pay Now
+ * </CheckoutButton>
+ * ```
+ */
+interface CheckoutButtonProps {
+    /** Array of items to purchase. Each item includes product, price, and optional quantity. */
     basket: BasketItem[];
+    /** Callback fired when payment completes successfully. Receives the Payment object with transaction details. */
     onSuccess?: (payment: Payment$1) => void;
+    /** Callback fired when payment fails. Receives the Error with failure details. */
     onError?: (error: Error) => void;
+    /** Button style variant. "solid" has a filled background, "outline" has a border only. @default "solid" */
     variant?: 'solid' | 'outline';
+    /** Custom button content. If not provided, displays "Pay". */
     children?: React.ReactNode;
+    /** Disable the button, preventing clicks. */
     disabled?: boolean;
+    /** Enable debug mode to show a debug panel with account balance in the checkout modal. @default false */
+    debug?: boolean;
 }
-declare const PayButton: React.ForwardRefExoticComponent<PayButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * A button component that opens a checkout modal for processing payments.
+ *
+ * Must be used within a `MoneyMQProvider`. When clicked, displays a modal where
+ * users can select their wallet and complete the payment.
+ *
+ * @example
+ * ```tsx
+ * import { MoneyMQProvider, CheckoutButton } from '@moneymq/react';
+ *
+ * function App() {
+ *   const product = { id: 'prod_123', name: 'Pro Plan' };
+ *   const price = { id: 'price_456', unit_amount: 999, currency: 'USDC' };
+ *
+ *   return (
+ *     <MoneyMQProvider client={client}>
+ *       <CheckoutButton
+ *         basket={[{ product, price }]}
+ *         onSuccess={(payment) => {
+ *           console.log('Payment completed:', payment.signature);
+ *         }}
+ *       >
+ *         Subscribe - $9.99
+ *       </CheckoutButton>
+ *     </MoneyMQProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link CheckoutButtonProps} for available props
+ * @see {@link CheckoutModal} for the modal component used internally
+ */
+declare const CheckoutButton: React.ForwardRefExoticComponent<CheckoutButtonProps & React.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Represents a line item in the checkout, including product, price, quantity, and calculated subtotal.
+ *
+ * @example
+ * ```tsx
+ * const lineItem: LineItem = {
+ *   product: { id: 'prod_123', name: 'Pro Plan' },
+ *   price: { id: 'price_456', unit_amount: 999, currency: 'USDC' },
+ *   quantity: 2,
+ *   subtotal: 19.98,
+ * };
+ * ```
+ */
 interface LineItem {
+    /** Product information */
     product: {
+        /** Unique product identifier */
         id: string;
+        /** Display name shown to the customer */
         name: string;
+        /** Optional description */
         description?: string;
     };
+    /** Price information */
     price: {
+        /** Unique price identifier */
         id: string;
+        /** Price amount in cents (e.g., 999 for $9.99) */
         unit_amount: number;
+        /** Currency code (e.g., "USDC") */
         currency: string;
     };
+    /** Quantity of this item */
     quantity: number;
+    /** Calculated subtotal (unit_amount / 100 * quantity) */
     subtotal: number;
 }
-interface PaymentModalProps {
+/**
+ * Props for the CheckoutModal component.
+ *
+ * @example
+ * ```tsx
+ * <CheckoutModal
+ *   visible={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   amount={9.99}
+ *   currency="USDC"
+ *   recipient="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
+ *   onSuccess={(signature) => console.log('Paid:', signature)}
+ * />
+ * ```
+ */
+interface CheckoutModalProps {
+    /** Whether the modal is visible */
     visible: boolean;
+    /** Callback to close the modal */
     onClose: () => void;
+    /** Total payment amount (e.g., 9.99 for $9.99) */
     amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Recipient wallet address */
     recipient: string;
+    /** Optional line items to display in the checkout summary */
     lineItems?: LineItem[];
+    /** Callback fired when payment completes. Receives the transaction signature. */
     onSuccess?: (signature: string) => void;
+    /** Callback fired when payment fails. Receives the Error with failure details. */
     onError?: (error: Error) => void;
+    /** Accent color for UI elements. @default "#ec4899" */
     accentColor?: string;
+    /** Enable debug mode to show account balance panel. @default false */
+    debug?: boolean;
 }
-declare function PaymentModal({ visible, onClose, amount, currency, recipient, lineItems, onSuccess, onError, accentColor, }: PaymentModalProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * A modal component for completing payments.
+ *
+ * Displays a payment interface where users can:
+ * - View the total amount and line items
+ * - Select a payment method (browser wallet or sandbox account)
+ * - Complete the payment transaction
+ *
+ * Must be used within a `MoneyMQProvider`. Usually used internally by `CheckoutButton`,
+ * but can be rendered directly for custom checkout flows.
+ *
+ * @example
+ * ```tsx
+ * import { MoneyMQProvider, CheckoutModal } from '@moneymq/react';
+ *
+ * function CustomCheckout() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <MoneyMQProvider client={client}>
+ *       <button onClick={() => setIsOpen(true)}>Pay</button>
+ *       <CheckoutModal
+ *         visible={isOpen}
+ *         onClose={() => setIsOpen(false)}
+ *         amount={9.99}
+ *         currency="USDC"
+ *         recipient="7xKXtg..."
+ *         lineItems={[
+ *           {
+ *             product: { id: 'prod_1', name: 'Pro Plan' },
+ *             price: { id: 'price_1', unit_amount: 999, currency: 'USDC' },
+ *             quantity: 1,
+ *             subtotal: 9.99,
+ *           },
+ *         ]}
+ *         onSuccess={(signature) => {
+ *           console.log('Payment successful:', signature);
+ *           setIsOpen(false);
+ *         }}
+ *       />
+ *     </MoneyMQProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link CheckoutModalProps} for available props
+ * @see {@link CheckoutButton} for a simpler button-based checkout
+ */
+declare function CheckoutModal({ visible, onClose, amount, currency, recipient, lineItems, onSuccess, onError, accentColor, debug, }: CheckoutModalProps): react_jsx_runtime.JSX.Element | null;
 
 interface Payment {
     id: string;
@@ -114,4 +327,4 @@ interface UsePaymentReturn {
 }
 declare function usePayment(): UsePaymentReturn;
 
-export { type BasketItem, type Branding, type LineItem, type MoneyMQClient, MoneyMQProvider, type MoneyMQProviderProps, PayButton, type PayButtonProps, type Payment$1 as Payment, PaymentModal, type PaymentModalProps, type Price, type Product, type SandboxAccount, type UsePaymentReturn, useMoneyMQ, usePayment, useSandbox };
+export { type BasketItem, type Branding, CheckoutButton, type CheckoutButtonProps, CheckoutModal, type CheckoutModalProps, type LineItem, type MoneyMQClient, MoneyMQContext, MoneyMQProvider, type MoneyMQProviderProps, type Payment$1 as Payment, type Price, type Product, type SandboxAccount, SandboxContext, type UsePaymentReturn, useMoneyMQ, usePayment, useSandbox };

package/dist/index.d.ts

@@ -32,73 +32,286 @@ interface SandboxContextState {
     isSandboxMode: boolean;
     sandboxAccounts: SandboxAccount[];
 }
+declare const MoneyMQContext: React.Context<MoneyMQClient | null>;
+declare const SandboxContext: React.Context<SandboxContextState>;
 declare function useMoneyMQ(): MoneyMQClient;
 declare function useSandbox(): SandboxContextState;
 declare function MoneyMQProvider({ children, client, branding, }: MoneyMQProviderProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Represents a completed payment transaction.
+ *
+ * @example
+ * ```tsx
+ * const handleSuccess = (payment: Payment) => {
+ *   console.log(`Payment ${payment.id} completed for ${payment.amount} ${payment.currency}`);
+ *   console.log(`Transaction signature: ${payment.signature}`);
+ * };
+ * ```
+ */
 interface Payment$1 {
+    /** Unique payment identifier (e.g., "pay_1234567890") */
     id: string;
+    /** Payment amount in the currency's standard unit (e.g., 9.99 for $9.99) */
     amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Current status of the payment */
     status: 'pending' | 'completed' | 'failed';
+    /** Blockchain transaction signature (available after completion) */
     signature?: string;
 }
+/**
+ * Represents a price for a product.
+ *
+ * @example
+ * ```tsx
+ * const price: Price = {
+ *   id: 'price_abc123',
+ *   unit_amount: 999, // $9.99 in cents
+ *   currency: 'USDC',
+ *   product: 'prod_xyz789',
+ * };
+ * ```
+ */
 interface Price {
+    /** Unique price identifier from your catalog */
     id: string;
+    /** Price amount in cents (e.g., 999 for $9.99) */
     unit_amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Associated product ID */
     product?: string;
 }
+/**
+ * Represents a product in your catalog.
+ *
+ * @example
+ * ```tsx
+ * const product: Product = {
+ *   id: 'prod_xyz789',
+ *   name: 'Pro Subscription',
+ *   description: 'Monthly access to premium features',
+ * };
+ * ```
+ */
 interface Product {
+    /** Unique product identifier from your catalog */
     id: string;
+    /** Display name shown to the customer */
     name: string;
+    /** Optional description for additional context */
     description?: string;
 }
+/**
+ * Represents an item in the checkout basket.
+ *
+ * @example
+ * ```tsx
+ * const item: BasketItem = {
+ *   product: { id: 'prod_123', name: 'Pro Plan' },
+ *   price: { id: 'price_456', unit_amount: 999, currency: 'USDC' },
+ *   quantity: 1,
+ * };
+ * ```
+ */
 interface BasketItem {
-    /** Product details */
+    /** Product details including id and name */
     product: Product;
-    /** Price details */
+    /** Price details including amount and currency */
     price: Price;
-    /** Quantity (defaults to 1) */
+    /** Number of items (defaults to 1) */
     quantity?: number;
 }
-interface PayButtonProps {
-    /** Basket of items to purchase */
+/**
+ * Props for the CheckoutButton component.
+ *
+ * @example
+ * ```tsx
+ * <CheckoutButton
+ *   basket={[{ product, price }]}
+ *   onSuccess={(payment) => console.log('Paid!', payment.id)}
+ *   onError={(error) => console.error('Failed:', error)}
+ *   variant="solid"
+ * >
+ *   Pay Now
+ * </CheckoutButton>
+ * ```
+ */
+interface CheckoutButtonProps {
+    /** Array of items to purchase. Each item includes product, price, and optional quantity. */
     basket: BasketItem[];
+    /** Callback fired when payment completes successfully. Receives the Payment object with transaction details. */
     onSuccess?: (payment: Payment$1) => void;
+    /** Callback fired when payment fails. Receives the Error with failure details. */
     onError?: (error: Error) => void;
+    /** Button style variant. "solid" has a filled background, "outline" has a border only. @default "solid" */
     variant?: 'solid' | 'outline';
+    /** Custom button content. If not provided, displays "Pay". */
     children?: React.ReactNode;
+    /** Disable the button, preventing clicks. */
     disabled?: boolean;
+    /** Enable debug mode to show a debug panel with account balance in the checkout modal. @default false */
+    debug?: boolean;
 }
-declare const PayButton: React.ForwardRefExoticComponent<PayButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * A button component that opens a checkout modal for processing payments.
+ *
+ * Must be used within a `MoneyMQProvider`. When clicked, displays a modal where
+ * users can select their wallet and complete the payment.
+ *
+ * @example
+ * ```tsx
+ * import { MoneyMQProvider, CheckoutButton } from '@moneymq/react';
+ *
+ * function App() {
+ *   const product = { id: 'prod_123', name: 'Pro Plan' };
+ *   const price = { id: 'price_456', unit_amount: 999, currency: 'USDC' };
+ *
+ *   return (
+ *     <MoneyMQProvider client={client}>
+ *       <CheckoutButton
+ *         basket={[{ product, price }]}
+ *         onSuccess={(payment) => {
+ *           console.log('Payment completed:', payment.signature);
+ *         }}
+ *       >
+ *         Subscribe - $9.99
+ *       </CheckoutButton>
+ *     </MoneyMQProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link CheckoutButtonProps} for available props
+ * @see {@link CheckoutModal} for the modal component used internally
+ */
+declare const CheckoutButton: React.ForwardRefExoticComponent<CheckoutButtonProps & React.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Represents a line item in the checkout, including product, price, quantity, and calculated subtotal.
+ *
+ * @example
+ * ```tsx
+ * const lineItem: LineItem = {
+ *   product: { id: 'prod_123', name: 'Pro Plan' },
+ *   price: { id: 'price_456', unit_amount: 999, currency: 'USDC' },
+ *   quantity: 2,
+ *   subtotal: 19.98,
+ * };
+ * ```
+ */
 interface LineItem {
+    /** Product information */
     product: {
+        /** Unique product identifier */
         id: string;
+        /** Display name shown to the customer */
         name: string;
+        /** Optional description */
         description?: string;
     };
+    /** Price information */
     price: {
+        /** Unique price identifier */
         id: string;
+        /** Price amount in cents (e.g., 999 for $9.99) */
         unit_amount: number;
+        /** Currency code (e.g., "USDC") */
         currency: string;
     };
+    /** Quantity of this item */
     quantity: number;
+    /** Calculated subtotal (unit_amount / 100 * quantity) */
     subtotal: number;
 }
-interface PaymentModalProps {
+/**
+ * Props for the CheckoutModal component.
+ *
+ * @example
+ * ```tsx
+ * <CheckoutModal
+ *   visible={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   amount={9.99}
+ *   currency="USDC"
+ *   recipient="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
+ *   onSuccess={(signature) => console.log('Paid:', signature)}
+ * />
+ * ```
+ */
+interface CheckoutModalProps {
+    /** Whether the modal is visible */
     visible: boolean;
+    /** Callback to close the modal */
     onClose: () => void;
+    /** Total payment amount (e.g., 9.99 for $9.99) */
     amount: number;
+    /** Currency code (e.g., "USDC") */
     currency: string;
+    /** Recipient wallet address */
     recipient: string;
+    /** Optional line items to display in the checkout summary */
     lineItems?: LineItem[];
+    /** Callback fired when payment completes. Receives the transaction signature. */
     onSuccess?: (signature: string) => void;
+    /** Callback fired when payment fails. Receives the Error with failure details. */
     onError?: (error: Error) => void;
+    /** Accent color for UI elements. @default "#ec4899" */
     accentColor?: string;
+    /** Enable debug mode to show account balance panel. @default false */
+    debug?: boolean;
 }
-declare function PaymentModal({ visible, onClose, amount, currency, recipient, lineItems, onSuccess, onError, accentColor, }: PaymentModalProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * A modal component for completing payments.
+ *
+ * Displays a payment interface where users can:
+ * - View the total amount and line items
+ * - Select a payment method (browser wallet or sandbox account)
+ * - Complete the payment transaction
+ *
+ * Must be used within a `MoneyMQProvider`. Usually used internally by `CheckoutButton`,
+ * but can be rendered directly for custom checkout flows.
+ *
+ * @example
+ * ```tsx
+ * import { MoneyMQProvider, CheckoutModal } from '@moneymq/react';
+ *
+ * function CustomCheckout() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <MoneyMQProvider client={client}>
+ *       <button onClick={() => setIsOpen(true)}>Pay</button>
+ *       <CheckoutModal
+ *         visible={isOpen}
+ *         onClose={() => setIsOpen(false)}
+ *         amount={9.99}
+ *         currency="USDC"
+ *         recipient="7xKXtg..."
+ *         lineItems={[
+ *           {
+ *             product: { id: 'prod_1', name: 'Pro Plan' },
+ *             price: { id: 'price_1', unit_amount: 999, currency: 'USDC' },
+ *             quantity: 1,
+ *             subtotal: 9.99,
+ *           },
+ *         ]}
+ *         onSuccess={(signature) => {
+ *           console.log('Payment successful:', signature);
+ *           setIsOpen(false);
+ *         }}
+ *       />
+ *     </MoneyMQProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link CheckoutModalProps} for available props
+ * @see {@link CheckoutButton} for a simpler button-based checkout
+ */
+declare function CheckoutModal({ visible, onClose, amount, currency, recipient, lineItems, onSuccess, onError, accentColor, debug, }: CheckoutModalProps): react_jsx_runtime.JSX.Element | null;
 
 interface Payment {
     id: string;
@@ -114,4 +327,4 @@ interface UsePaymentReturn {
 }
 declare function usePayment(): UsePaymentReturn;
 
-export { type BasketItem, type Branding, type LineItem, type MoneyMQClient, MoneyMQProvider, type MoneyMQProviderProps, PayButton, type PayButtonProps, type Payment$1 as Payment, PaymentModal, type PaymentModalProps, type Price, type Product, type SandboxAccount, type UsePaymentReturn, useMoneyMQ, usePayment, useSandbox };
+export { type BasketItem, type Branding, CheckoutButton, type CheckoutButtonProps, CheckoutModal, type CheckoutModalProps, type LineItem, type MoneyMQClient, MoneyMQContext, MoneyMQProvider, type MoneyMQProviderProps, type Payment$1 as Payment, type Price, type Product, type SandboxAccount, SandboxContext, type UsePaymentReturn, useMoneyMQ, usePayment, useSandbox };