@t402/react 2.0.0

package/dist/esm/index.d.ts

@@ -0,0 +1,593 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PaymentRequirements, PaymentRequired } from '@t402/core/types';
+export { PaymentRequired, PaymentRequirements } from '@t402/core/types';
+import * as react from 'react';
+
+/**
+ * Payment status states
+ */
+type PaymentStatus$1 = "idle" | "loading" | "success" | "error";
+/**
+ * Payment context state
+ */
+interface PaymentState {
+    /** Current payment status */
+    status: PaymentStatus$1;
+    /** Error message if status is 'error' */
+    error: string | null;
+    /** The payment required response from server */
+    paymentRequired: PaymentRequired | null;
+    /** Currently selected payment requirement */
+    selectedRequirement: PaymentRequirements | null;
+    /** Whether we're in testnet mode */
+    isTestnet: boolean;
+}
+/**
+ * Payment context actions
+ */
+interface PaymentActions {
+    /** Set the payment required data */
+    setPaymentRequired: (data: PaymentRequired) => void;
+    /** Select a specific payment requirement */
+    selectRequirement: (requirement: PaymentRequirements) => void;
+    /** Set the payment status */
+    setStatus: (status: PaymentStatus$1) => void;
+    /** Set an error message */
+    setError: (error: string | null) => void;
+    /** Reset the payment state */
+    reset: () => void;
+}
+/**
+ * Complete payment context value
+ */
+interface PaymentContextValue extends PaymentState, PaymentActions {
+}
+/**
+ * Props for PaymentProvider
+ */
+interface PaymentProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Initial payment required data */
+    initialPaymentRequired?: PaymentRequired;
+    /** Whether to default to testnet mode */
+    testnet?: boolean;
+}
+/**
+ * Props for PaymentButton component
+ */
+interface PaymentButtonProps {
+    /** Click handler */
+    onClick?: () => void | Promise<void>;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Whether the button is in loading state */
+    loading?: boolean;
+    /** Button text */
+    children?: React.ReactNode;
+    /** Additional CSS class names */
+    className?: string;
+    /** Button variant */
+    variant?: "primary" | "secondary" | "outline";
+    /** Button size */
+    size?: "sm" | "md" | "lg";
+}
+/**
+ * Props for PaymentStatus component
+ */
+interface PaymentStatusProps {
+    /** Current status */
+    status: PaymentStatus$1;
+    /** Message to display */
+    message?: string;
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Props for PaymentDetails component
+ */
+interface PaymentDetailsProps {
+    /** Payment requirements to display */
+    requirement: PaymentRequirements;
+    /** Whether to show the network name */
+    showNetwork?: boolean;
+    /** Whether to show the asset */
+    showAsset?: boolean;
+    /** Whether to show the recipient address */
+    showRecipient?: boolean;
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Props for Spinner component
+ */
+interface SpinnerProps {
+    /** Spinner size */
+    size?: "sm" | "md" | "lg";
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Props for AddressDisplay component
+ */
+interface AddressDisplayProps {
+    /** The address to display */
+    address: string;
+    /** Number of characters to show at start */
+    startChars?: number;
+    /** Number of characters to show at end */
+    endChars?: number;
+    /** Whether to show copy button */
+    copyable?: boolean;
+    /** Additional CSS class names */
+    className?: string;
+}
+
+/**
+ * A simple loading spinner component.
+ *
+ * @param props - Component props.
+ * @returns The spinner element.
+ *
+ * @example
+ * ```tsx
+ * import { Spinner } from "@t402/react";
+ *
+ * function LoadingState() {
+ *   return (
+ *     <div>
+ *       <Spinner size="md" />
+ *       <span>Loading...</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function Spinner({ size, className }: SpinnerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A payment button component with loading state support.
+ *
+ * @param props - Component props.
+ * @returns The button element.
+ *
+ * @example
+ * ```tsx
+ * import { PaymentButton } from "@t402/react";
+ *
+ * function PaymentFlow() {
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   const handlePayment = async () => {
+ *     setLoading(true);
+ *     await processPayment();
+ *     setLoading(false);
+ *   };
+ *
+ *   return (
+ *     <PaymentButton
+ *       onClick={handlePayment}
+ *       loading={loading}
+ *       variant="primary"
+ *       size="lg"
+ *     >
+ *       Pay $10.00
+ *     </PaymentButton>
+ *   );
+ * }
+ * ```
+ */
+declare function PaymentButton({ onClick, disabled, loading, children, className, variant, size, }: PaymentButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A component to display payment status with appropriate styling.
+ *
+ * @param props - Component props.
+ * @returns The status display element.
+ *
+ * @example
+ * ```tsx
+ * import { PaymentStatus } from "@t402/react";
+ *
+ * function PaymentFlow() {
+ *   const [status, setStatus] = useState("idle");
+ *
+ *   return (
+ *     <PaymentStatus
+ *       status={status}
+ *       message={status === "loading" ? "Processing payment..." : undefined}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function PaymentStatus({ status, message, className }: PaymentStatusProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A component to display payment requirement details.
+ *
+ * @param props - Component props.
+ * @returns The payment details element.
+ *
+ * @example
+ * ```tsx
+ * import { PaymentDetails } from "@t402/react";
+ *
+ * function PaymentFlow({ requirement }) {
+ *   return (
+ *     <PaymentDetails
+ *       requirement={requirement}
+ *       showNetwork={true}
+ *       showAsset={true}
+ *       showRecipient={true}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function PaymentDetails({ requirement, showNetwork, showAsset, showRecipient, className, }: PaymentDetailsProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A component to display blockchain addresses with optional copy functionality.
+ *
+ * @param props - Component props.
+ * @returns The address display element.
+ *
+ * @example
+ * ```tsx
+ * import { AddressDisplay } from "@t402/react";
+ *
+ * function WalletInfo() {
+ *   return (
+ *     <AddressDisplay
+ *       address="0x1234567890abcdef1234567890abcdef12345678"
+ *       copyable={true}
+ *       startChars={6}
+ *       endChars={4}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function AddressDisplay({ address, startChars, endChars, copyable, className, }: AddressDisplayProps): react_jsx_runtime.JSX.Element;
+
+interface UsePaymentRequiredOptions {
+    /** Callback when payment is successful */
+    onSuccess?: (response: Response) => void;
+    /** Callback when payment fails */
+    onError?: (error: Error) => void;
+}
+interface UsePaymentRequiredResult {
+    /** The payment required data from a 402 response */
+    paymentRequired: PaymentRequired | null;
+    /** Current status of the fetch operation */
+    status: PaymentStatus$1;
+    /** Error message if status is 'error' */
+    error: string | null;
+    /** Fetch a resource and capture 402 response */
+    fetchResource: (url: string, options?: RequestInit) => Promise<Response | null>;
+    /** Reset the state */
+    reset: () => void;
+}
+/**
+ * Hook to fetch a resource and capture 402 Payment Required responses.
+ *
+ * @param options - Configuration options.
+ * @returns State and methods for handling 402 responses.
+ *
+ * @example
+ * ```tsx
+ * import { usePaymentRequired } from "@t402/react";
+ *
+ * function ProtectedResource() {
+ *   const { paymentRequired, status, fetchResource } = usePaymentRequired({
+ *     onSuccess: (response) => console.log("Access granted!"),
+ *   });
+ *
+ *   const handleFetch = async () => {
+ *     const response = await fetchResource("/api/protected");
+ *     if (response && response.ok) {
+ *       const data = await response.json();
+ *       // Handle successful response
+ *     }
+ *   };
+ *
+ *   if (paymentRequired) {
+ *     return <PaymentUI data={paymentRequired} />;
+ *   }
+ *
+ *   return <button onClick={handleFetch}>Access Resource</button>;
+ * }
+ * ```
+ */
+declare function usePaymentRequired(options?: UsePaymentRequiredOptions): UsePaymentRequiredResult;
+
+interface StatusMessage {
+    /** Message text */
+    text: string;
+    /** Message type */
+    type: "info" | "success" | "error" | "warning";
+    /** Optional auto-dismiss timeout in ms */
+    timeout?: number;
+}
+interface UsePaymentStatusResult {
+    /** Current payment status */
+    status: PaymentStatus$1;
+    /** Current status message */
+    message: StatusMessage | null;
+    /** Set the status */
+    setStatus: (status: PaymentStatus$1, message?: string) => void;
+    /** Set a success message */
+    setSuccess: (message: string, timeout?: number) => void;
+    /** Set an error message */
+    setError: (message: string) => void;
+    /** Set an info message */
+    setInfo: (message: string, timeout?: number) => void;
+    /** Set a warning message */
+    setWarning: (message: string, timeout?: number) => void;
+    /** Clear the current message */
+    clearMessage: () => void;
+    /** Reset to idle state */
+    reset: () => void;
+}
+/**
+ * Hook for managing payment status and status messages.
+ *
+ * @returns State and methods for status management.
+ *
+ * @example
+ * ```tsx
+ * import { usePaymentStatus } from "@t402/react";
+ *
+ * function PaymentFlow() {
+ *   const {
+ *     status,
+ *     message,
+ *     setStatus,
+ *     setSuccess,
+ *     setError,
+ *   } = usePaymentStatus();
+ *
+ *   const handlePayment = async () => {
+ *     setStatus("loading", "Processing payment...");
+ *     try {
+ *       await processPayment();
+ *       setSuccess("Payment successful!", 3000);
+ *     } catch (err) {
+ *       setError("Payment failed. Please try again.");
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {message && <StatusMessage message={message} />}
+ *       <button onClick={handlePayment} disabled={status === "loading"}>
+ *         Pay Now
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function usePaymentStatus(): UsePaymentStatusResult;
+
+interface UseAsyncPaymentOptions<T> {
+    /** The async payment function to execute */
+    paymentFn: () => Promise<T>;
+    /** Callback on successful payment */
+    onSuccess?: (result: T) => void;
+    /** Callback on payment error */
+    onError?: (error: Error) => void;
+    /** Callback when payment starts */
+    onStart?: () => void;
+}
+interface UseAsyncPaymentResult<T> {
+    /** Execute the payment */
+    execute: () => Promise<T | null>;
+    /** Current payment status */
+    status: PaymentStatus$1;
+    /** Result of successful payment */
+    result: T | null;
+    /** Error message if payment failed */
+    error: string | null;
+    /** Whether payment is in progress */
+    isLoading: boolean;
+    /** Whether payment succeeded */
+    isSuccess: boolean;
+    /** Whether payment failed */
+    isError: boolean;
+    /** Reset the state */
+    reset: () => void;
+}
+/**
+ * Hook for managing async payment operations with loading states.
+ *
+ * @param options - Configuration including the payment function and callbacks.
+ * @returns State and methods for managing the async payment.
+ *
+ * @example
+ * ```tsx
+ * import { useAsyncPayment } from "@t402/react";
+ *
+ * function PaymentButton({ paymentPayload }) {
+ *   const { execute, isLoading, isSuccess, error } = useAsyncPayment({
+ *     paymentFn: async () => {
+ *       const response = await fetch("/api/protected", {
+ *         headers: { "X-Payment": paymentPayload },
+ *       });
+ *       return response.json();
+ *     },
+ *     onSuccess: (data) => console.log("Payment succeeded:", data),
+ *     onError: (err) => console.error("Payment failed:", err),
+ *   });
+ *
+ *   return (
+ *     <button onClick={execute} disabled={isLoading}>
+ *       {isLoading ? "Processing..." : "Pay Now"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useAsyncPayment<T>(options: UseAsyncPaymentOptions<T>): UseAsyncPaymentResult<T>;
+
+declare const PaymentContext: react.Context<PaymentContextValue | null>;
+/**
+ * Payment context provider for t402 payment state management.
+ *
+ * @param props - Provider props including children and initial state.
+ * @returns The provider component wrapping children.
+ *
+ * @example
+ * ```tsx
+ * import { PaymentProvider } from "@t402/react";
+ *
+ * function App() {
+ *   return (
+ *     <PaymentProvider testnet={true}>
+ *       <PaymentFlow />
+ *     </PaymentProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function PaymentProvider({ children, initialPaymentRequired, testnet, }: PaymentProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the payment context.
+ *
+ * @returns The payment context value.
+ * @throws Error if used outside of PaymentProvider.
+ *
+ * @example
+ * ```tsx
+ * import { usePaymentContext } from "@t402/react";
+ *
+ * function PaymentFlow() {
+ *   const { status, selectedRequirement, setStatus } = usePaymentContext();
+ *
+ *   const handlePayment = async () => {
+ *     setStatus("loading");
+ *     // ... payment logic
+ *   };
+ *
+ *   return <button onClick={handlePayment}>Pay</button>;
+ * }
+ * ```
+ */
+declare function usePaymentContext(): PaymentContextValue;
+
+/** EVM Chain IDs (CAIP-2 format: eip155:chainId) */
+declare const EVM_CHAIN_IDS: {
+    readonly ETHEREUM_MAINNET: "1";
+    readonly BASE_MAINNET: "8453";
+    readonly BASE_SEPOLIA: "84532";
+    readonly ARBITRUM_MAINNET: "42161";
+    readonly ARBITRUM_SEPOLIA: "421614";
+};
+/** Solana Network References (CAIP-2 format: solana:genesisHash) */
+declare const SOLANA_NETWORK_REFS: {
+    readonly MAINNET: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    readonly DEVNET: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+};
+/** TON Network References (CAIP-2 format: ton:workchain) */
+declare const TON_NETWORK_REFS: {
+    readonly MAINNET: "-239";
+    readonly TESTNET: "-3";
+};
+/** TRON Network References */
+declare const TRON_NETWORK_REFS: {
+    readonly MAINNET: "mainnet";
+    readonly NILE: "nile";
+    readonly SHASTA: "shasta";
+};
+/**
+ * Normalizes payment requirements into an array.
+ *
+ * @param paymentRequirements - A single requirement or array of requirements.
+ * @returns An array of payment requirements.
+ */
+declare function normalizePaymentRequirements(paymentRequirements: PaymentRequirements | PaymentRequirements[]): PaymentRequirements[];
+/**
+ * Returns preferred networks for payment selection.
+ *
+ * @param testnet - Whether to prefer testnet networks.
+ * @returns Ordered list of preferred networks (CAIP-2 format).
+ */
+declare function getPreferredNetworks(testnet: boolean): string[];
+/**
+ * Selects the most appropriate payment requirement.
+ *
+ * @param paymentRequirements - Available payment requirements.
+ * @param testnet - Whether to prefer testnet networks.
+ * @returns The selected payment requirement.
+ */
+declare function choosePaymentRequirement(paymentRequirements: PaymentRequirements | PaymentRequirements[], testnet: boolean): PaymentRequirements;
+/**
+ * Determines if the network is EVM-based.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns True if the network is EVM-based.
+ */
+declare function isEvmNetwork(network: string): boolean;
+/**
+ * Determines if the network is Solana-based.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns True if the network is Solana-based.
+ */
+declare function isSvmNetwork(network: string): boolean;
+/**
+ * Determines if the network is TON-based.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns True if the network is TON-based.
+ */
+declare function isTonNetwork(network: string): boolean;
+/**
+ * Determines if the network is TRON-based.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns True if the network is TRON-based.
+ */
+declare function isTronNetwork(network: string): boolean;
+/**
+ * Gets a human-readable display name for a network.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns A display name suitable for UI use.
+ */
+declare function getNetworkDisplayName(network: string): string;
+/**
+ * Determines if the network is a testnet.
+ *
+ * @param network - The network identifier (CAIP-2 format).
+ * @returns True if the network is a testnet.
+ */
+declare function isTestnetNetwork(network: string): boolean;
+/**
+ * Truncates an address for display.
+ *
+ * @param address - The full address.
+ * @param startChars - Number of characters to show at start (default: 6).
+ * @param endChars - Number of characters to show at end (default: 4).
+ * @returns The truncated address.
+ */
+declare function truncateAddress(address: string, startChars?: number, endChars?: number): string;
+/**
+ * Formats a token amount for display.
+ *
+ * @param amount - The amount as a string (in smallest unit).
+ * @param decimals - The token decimals (default: 6 for USDT).
+ * @param maxDecimals - Maximum decimal places to show (default: 2).
+ * @returns The formatted amount.
+ */
+declare function formatTokenAmount(amount: string, decimals?: number, maxDecimals?: number): string;
+/**
+ * Gets the asset display name.
+ *
+ * @param asset - The asset identifier (e.g., "usdt", "usdt0").
+ * @returns A display name suitable for UI use.
+ */
+declare function getAssetDisplayName(asset: string): string;
+
+export { AddressDisplay, type AddressDisplayProps, EVM_CHAIN_IDS, type PaymentActions, PaymentButton, type PaymentButtonProps, PaymentContext, type PaymentContextValue, PaymentDetails, type PaymentDetailsProps, PaymentProvider, type PaymentProviderProps, type PaymentState, type PaymentStatus$1 as PaymentStatus, PaymentStatus as PaymentStatusDisplay, type PaymentStatusProps, SOLANA_NETWORK_REFS, Spinner, type SpinnerProps, TON_NETWORK_REFS, TRON_NETWORK_REFS, choosePaymentRequirement, formatTokenAmount, getAssetDisplayName, getNetworkDisplayName, getPreferredNetworks, isEvmNetwork, isSvmNetwork, isTestnetNetwork, isTonNetwork, isTronNetwork, normalizePaymentRequirements, truncateAddress, useAsyncPayment, usePaymentContext, usePaymentRequired, usePaymentStatus };