@t402/react 2.3.0 → 2.4.0

package/README.md

@@ -0,0 +1,158 @@
+# @t402/react
+
+React components and hooks for the t402 Payment Protocol. Build payment-aware UIs with pre-built components and reactive hooks.
+
+## Installation
+
+```bash
+npm install @t402/react
+```
+
+## Quick Start
+
+```tsx
+import { PaymentProvider, PaymentButton, usePaymentRequired } from '@t402/react'
+
+function App() {
+  return (
+    <PaymentProvider>
+      <ProtectedContent />
+    </PaymentProvider>
+  )
+}
+
+function ProtectedContent() {
+  const { paymentRequired, requirements, pay, status } = usePaymentRequired('/api/data')
+
+  if (paymentRequired) {
+    return <PaymentButton requirements={requirements} onPay={pay} status={status} />
+  }
+
+  return <div>Premium content loaded!</div>
+}
+```
+
+## Components
+
+### PaymentButton
+
+Renders a payment action button with loading and status states.
+
+```tsx
+import { PaymentButton } from '@t402/react'
+;<PaymentButton requirements={requirements} onPay={handlePay} status={status} />
+```
+
+### PaymentDetails
+
+Displays payment requirements (amount, network, recipient).
+
+```tsx
+import { PaymentDetails } from '@t402/react'
+;<PaymentDetails requirements={requirements} />
+```
+
+### PaymentStatusDisplay
+
+Shows the current payment status with appropriate UI feedback.
+
+```tsx
+import { PaymentStatusDisplay } from '@t402/react'
+;<PaymentStatusDisplay status={status} />
+```
+
+### AddressDisplay
+
+Renders a blockchain address with truncation and copy functionality.
+
+```tsx
+import { AddressDisplay } from '@t402/react'
+;<AddressDisplay address="0x1234...5678" />
+```
+
+## Hooks
+
+### usePaymentRequired
+
+Detects 402 responses and extracts payment requirements.
+
+```tsx
+const {
+  paymentRequired, // boolean - whether payment is needed
+  requirements, // PaymentRequirements[] from 402 response
+  pay, // () => Promise<void> - trigger payment
+  status, // PaymentStatus - current state
+} = usePaymentRequired(url, options)
+```
+
+### usePaymentStatus
+
+Tracks the lifecycle of a payment (idle, pending, confirming, complete, error).
+
+```tsx
+const { status, error, reset } = usePaymentStatus()
+```
+
+### useAsyncPayment
+
+Manages async payment flows with automatic retry and status tracking.
+
+```tsx
+const { execute, status, error } = useAsyncPayment(paymentFn)
+```
+
+## Provider
+
+### PaymentProvider
+
+Wraps your app to provide payment context to all child components.
+
+```tsx
+import { PaymentProvider } from '@t402/react'
+;<PaymentProvider>
+  <App />
+</PaymentProvider>
+```
+
+Access context directly with `usePaymentContext()`.
+
+## Utilities
+
+```typescript
+import {
+  isEvmNetwork,
+  isSvmNetwork,
+  isTonNetwork,
+  getNetworkDisplayName,
+  truncateAddress,
+  formatTokenAmount,
+  choosePaymentRequirement,
+} from '@t402/react'
+
+// Network detection
+isEvmNetwork('eip155:8453') // true
+
+// Display helpers
+getNetworkDisplayName('eip155:8453') // "Base"
+truncateAddress('0x1234567890abcdef') // "0x1234...cdef"
+formatTokenAmount(1500000n, 6) // "1.50"
+```
+
+## Peer Dependencies
+
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0
+
+## Development
+
+```bash
+pnpm build    # Build the package
+pnpm test     # Run unit tests
+```
+
+## Related Packages
+
+- `@t402/core` - Core protocol types
+- `@t402/vue` - Vue components & composables
+- `@t402/paywall` - Universal paywall UI
+- `@t402/fetch` - Fetch wrapper with automatic payment

package/dist/cjs/index.cjs

@@ -628,6 +628,262 @@ function useAsyncPayment(options) {
     reset
   };
 }
+function useGaslessPayment(options) {
+  const { payFn, onSuccess, onError, autoWait = true } = options;
+  const [status, setStatus] = react.useState("idle");
+  const [userOpHash, setUserOpHash] = react.useState(null);
+  const [txHash, setTxHash] = react.useState(null);
+  const [sponsored, setSponsored] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const isMountedRef = react.useRef(true);
+  const pay = react.useCallback(
+    async (params) => {
+      setStatus("loading");
+      setError(null);
+      setUserOpHash(null);
+      setTxHash(null);
+      setSponsored(null);
+      try {
+        const result = await payFn(params);
+        if (isMountedRef.current) {
+          setUserOpHash(result.userOpHash);
+          setSponsored(result.sponsored);
+        }
+        if (autoWait) {
+          const receipt = await result.wait();
+          if (isMountedRef.current) {
+            setTxHash(receipt.txHash);
+            setStatus("success");
+            onSuccess?.(receipt);
+          }
+        } else {
+          if (isMountedRef.current) {
+            setStatus("success");
+            onSuccess?.({ txHash: result.userOpHash, success: true });
+          }
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Gasless payment failed";
+        if (isMountedRef.current) {
+          setError(errorMessage);
+          setStatus("error");
+        }
+        onError?.(err instanceof Error ? err : new Error(errorMessage));
+      }
+    },
+    [payFn, onSuccess, onError, autoWait]
+  );
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setUserOpHash(null);
+    setTxHash(null);
+    setSponsored(null);
+    setError(null);
+  }, []);
+  return {
+    pay,
+    status,
+    userOpHash,
+    txHash,
+    sponsored,
+    error,
+    isLoading: status === "loading",
+    isSuccess: status === "success",
+    isError: status === "error",
+    reset
+  };
+}
+function useBridgePayment(options) {
+  const { bridgeFn, autoBridgeFn, onSuccess, onError, autoWaitForDelivery = false } = options;
+  const [status, setStatus] = react.useState("idle");
+  const [txHash, setTxHash] = react.useState(null);
+  const [messageGuid, setMessageGuid] = react.useState(null);
+  const [dstTxHash, setDstTxHash] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const isMountedRef = react.useRef(true);
+  const executeBridge = react.useCallback(
+    async (bridgeCall) => {
+      setStatus("bridging");
+      setError(null);
+      setTxHash(null);
+      setMessageGuid(null);
+      setDstTxHash(null);
+      try {
+        const result = await bridgeCall();
+        if (isMountedRef.current) {
+          setTxHash(result.txHash);
+          setMessageGuid(result.messageGuid);
+        }
+        if (autoWaitForDelivery) {
+          if (isMountedRef.current) setStatus("waiting");
+          const delivery = await result.waitForDelivery();
+          if (isMountedRef.current) {
+            if (delivery.dstTxHash) setDstTxHash(delivery.dstTxHash);
+            setStatus("success");
+            onSuccess?.({
+              txHash: result.txHash,
+              dstTxHash: delivery.dstTxHash,
+              fromChain: result.fromChain,
+              toChain: result.toChain
+            });
+          }
+        } else {
+          if (isMountedRef.current) {
+            setStatus("success");
+            onSuccess?.({
+              txHash: result.txHash,
+              fromChain: result.fromChain,
+              toChain: result.toChain
+            });
+          }
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Bridge operation failed";
+        if (isMountedRef.current) {
+          setError(errorMessage);
+          setStatus("error");
+        }
+        onError?.(err instanceof Error ? err : new Error(errorMessage));
+      }
+    },
+    [onSuccess, onError, autoWaitForDelivery]
+  );
+  const bridge = react.useCallback(
+    async (params) => {
+      await executeBridge(() => bridgeFn(params));
+    },
+    [bridgeFn, executeBridge]
+  );
+  const autoBridge = react.useCallback(
+    async (params) => {
+      const fn = autoBridgeFn ?? (() => {
+        throw new Error("autoBridgeFn not provided");
+      });
+      await executeBridge(() => fn(params));
+    },
+    [autoBridgeFn, executeBridge]
+  );
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setTxHash(null);
+    setMessageGuid(null);
+    setDstTxHash(null);
+    setError(null);
+  }, []);
+  return {
+    bridge,
+    autoBridge,
+    status,
+    txHash,
+    messageGuid,
+    dstTxHash,
+    error,
+    isLoading: status === "bridging" || status === "quoting" || status === "waiting",
+    isSuccess: status === "success",
+    isError: status === "error",
+    reset
+  };
+}
+function useMultiSigPayment(options) {
+  const { initiateFn, submitFn, onSuccess, onError, autoWait = true } = options;
+  const [status, setStatus] = react.useState("idle");
+  const [requestId, setRequestId] = react.useState(null);
+  const [userOpHash, setUserOpHash] = react.useState(null);
+  const [txHash, setTxHash] = react.useState(null);
+  const [threshold, setThreshold] = react.useState(0);
+  const [collectedCount, setCollectedCount] = react.useState(0);
+  const [isReady, setIsReady] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  const isMountedRef = react.useRef(true);
+  const initiate = react.useCallback(
+    async (params) => {
+      setStatus("initiating");
+      setError(null);
+      setRequestId(null);
+      setUserOpHash(null);
+      setTxHash(null);
+      try {
+        const result = await initiateFn(params);
+        if (isMountedRef.current) {
+          setRequestId(result.requestId);
+          setUserOpHash(result.userOpHash);
+          setThreshold(result.threshold);
+          setCollectedCount(result.collectedCount);
+          setIsReady(result.isReady);
+          setStatus("collecting");
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Failed to initiate multi-sig payment";
+        if (isMountedRef.current) {
+          setError(errorMessage);
+          setStatus("error");
+        }
+        onError?.(err instanceof Error ? err : new Error(errorMessage));
+      }
+    },
+    [initiateFn, onError]
+  );
+  const submit = react.useCallback(async () => {
+    if (!requestId) {
+      const err = new Error("No active request to submit");
+      setError(err.message);
+      setStatus("error");
+      onError?.(err);
+      return;
+    }
+    setStatus("submitting");
+    setError(null);
+    try {
+      const result = await submitFn(requestId);
+      if (autoWait) {
+        const receipt = await result.wait();
+        if (isMountedRef.current) {
+          setTxHash(receipt.txHash);
+          setStatus("success");
+          onSuccess?.(receipt);
+        }
+      } else {
+        if (isMountedRef.current) {
+          setStatus("success");
+          onSuccess?.({ txHash: result.userOpHash, success: true });
+        }
+      }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "Failed to submit multi-sig transaction";
+      if (isMountedRef.current) {
+        setError(errorMessage);
+        setStatus("error");
+      }
+      onError?.(err instanceof Error ? err : new Error(errorMessage));
+    }
+  }, [requestId, submitFn, onSuccess, onError, autoWait]);
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setRequestId(null);
+    setUserOpHash(null);
+    setTxHash(null);
+    setThreshold(0);
+    setCollectedCount(0);
+    setIsReady(false);
+    setError(null);
+  }, []);
+  return {
+    initiate,
+    submit,
+    status,
+    requestId,
+    userOpHash,
+    txHash,
+    threshold,
+    collectedCount,
+    isReady,
+    error,
+    isLoading: status === "initiating" || status === "submitting",
+    isSuccess: status === "success",
+    isError: status === "error",
+    reset
+  };
+}
 var initialState = {
   status: "idle",
   error: null,
@@ -738,6 +994,9 @@ exports.isTronNetwork = isTronNetwork;
 exports.normalizePaymentRequirements = normalizePaymentRequirements;
 exports.truncateAddress = truncateAddress;
 exports.useAsyncPayment = useAsyncPayment;
+exports.useBridgePayment = useBridgePayment;
+exports.useGaslessPayment = useGaslessPayment;
+exports.useMultiSigPayment = useMultiSigPayment;
 exports.usePaymentContext = usePaymentContext;
 exports.usePaymentRequired = usePaymentRequired;
 exports.usePaymentStatus = usePaymentStatus;