@moneymq/react 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MoneyMQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -32,55 +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;
 }
-interface PayButtonProps {
-    /** Price ID to fetch details from API */
-    priceId?: string;
-    /** Price object (alternative to priceId) */
-    price?: Price;
-    /** Product object */
-    product?: Product;
+/**
+ * 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 including id and name */
+    product: Product;
+    /** Price details including amount and currency */
+    price: Price;
+    /** Number of items (defaults to 1) */
+    quantity?: number;
+}
+/**
+ * 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>>;
 
-interface PaymentModalProps {
+/**
+ * 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;
+}
+/**
+ * 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;
-    productName?: 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, productName, 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;
@@ -96,4 +327,4 @@ interface UsePaymentReturn {
 }
 declare function usePayment(): UsePaymentReturn;
 
-export { type Branding, 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,55 +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;
 }
-interface PayButtonProps {
-    /** Price ID to fetch details from API */
-    priceId?: string;
-    /** Price object (alternative to priceId) */
-    price?: Price;
-    /** Product object */
-    product?: Product;
+/**
+ * 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 including id and name */
+    product: Product;
+    /** Price details including amount and currency */
+    price: Price;
+    /** Number of items (defaults to 1) */
+    quantity?: number;
+}
+/**
+ * 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>>;
 
-interface PaymentModalProps {
+/**
+ * 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;
+}
+/**
+ * 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;
-    productName?: 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, productName, 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;
@@ -96,4 +327,4 @@ interface UsePaymentReturn {
 }
 declare function usePayment(): UsePaymentReturn;
 
-export { type Branding, 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 };