@volr/react 0.1.49 → 0.1.54

package/README.md

@@ -1,6 +1,6 @@
 # @volr/react
 
-Volr React SDK - React hooks and UI components for Volr Web3 Payment Builder.
+Volr React SDK - React hooks for Volr Web3 Payment Builder.
 
 ## Installation
 
@@ -13,7 +13,7 @@ yarn add @volr/react
 ### Basic Setup
 
 ```tsx
-import { VolrProvider, useVolrWallet } from '@volr/react';
+import { VolrProvider, useVolr } from '@volr/react';
 
 function App() {
   return (
@@ -29,58 +29,109 @@ function App() {
 }
 
 function YourApp() {
-  const { evm } = useVolrWallet();
+  const { evm, isLoggedIn, logout } = useVolr();
+
+  if (!isLoggedIn) {
+    return <div>Please login</div>;
+  }
 
   // Read contract
   const balance = await evm(8453).readContract({
     address: '0x...',
     abi: erc20Abi,
     functionName: 'balanceOf',
-    args: ['0x...'],
+    args: [evm.address],
   });
 
   // Send transaction
-  const result = await evm(8453).sendTransaction(
+  const result = await evm(8453).sendTransaction({
+    to: '0x...',
+    data: '0x...',
+  });
+
+  // Send batch
+  const result = await evm(8453).sendBatch([
     {
-      to: '0x...',
-      data: '0x...',
+      target: '0x...',
+      abi: erc20Abi,
+      functionName: 'transfer',
+      args: ['0x...', BigInt(1000000)],
     },
-    {
-      policyId: '0x' + '0'.repeat(64),
-      signer: mySigner,
-    }
-  );
+  ]);
 }
 ```
 
-### Advanced Usage
+## API
+
+### useVolr
 
-For advanced users who need more control, you can use the low-level hooks:
+Main hook for wallet operations.
 
 ```tsx
-import { usePrecheck, useRelay, buildCall } from '@volr/react';
+const {
+  evm,        // EvmNamespace - chain client factory + address
+  email,      // string | undefined
+  isLoggedIn, // boolean
+  signerType, // 'passkey' | 'external_wallet' | 'mpc' | undefined
+  logout,     // () => Promise<void>
+  isLoading,  // boolean
+  error,      // Error | null
+} = useVolr();
+
+// Get EVM address
+const address = evm.address;
+
+// Get chain client
+const client = evm(8453);
+```
 
-function AdvancedComponent() {
-  const { precheck } = usePrecheck();
-  const { relay } = useRelay();
+### EvmClient
 
-  // Build call manually
-  const call = buildCall({
-    target: '0x...',
+Returned by `evm(chainId)`.
+
+```tsx
+const client = evm(8453);
+
+// Read contract
+const balance = await client.readContract({
+  address: tokenAddress,
+  abi: erc20Abi,
+  functionName: 'balanceOf',
+  args: [userAddress],
+});
+
+// Send single transaction
+const result = await client.sendTransaction({
+  to: '0x...',
+  data: '0x...',
+  value: 0n,
+});
+
+// Send batch (with ABI)
+const result = await client.sendBatch([
+  {
+    target: tokenAddress,
     abi: erc20Abi,
     functionName: 'transfer',
-    args: ['0x...', BigInt(1000000)],
-  });
-
-  // Use precheck and relay directly
-  const quote = await precheck({ auth, calls: [call] });
-  const result = await relay(input, { signer, rpcClient });
-}
+    args: [recipient, amount],
+    gasLimit: 100000n,
+  },
+]);
+
+// Send batch (raw calls)
+const result = await client.sendBatch([
+  {
+    target: '0x...',
+    data: '0x...',
+    value: 0n,
+    gasLimit: 100000n,
+  },
+]);
 ```
 
 ## Features
 
-- **Developer-Friendly API**: `useVolrWallet()` provides a simple, intuitive interface
+- **Simple API**: `useVolr()` provides everything you need
 - **Session Management**: Automatic token refresh and tab synchronization
 - **EIP-7702 Support**: Gasless transactions with session keys
 - **Passkey Integration**: Secure signing with device passkeys
@@ -90,7 +141,7 @@ function AdvancedComponent() {
 
 ## OAuth Handling
 
-The SDK provides a dedicated hook `useVolrAuthCallback` to simplify handling OAuth redirects. This is useful for custom login flows where you need to process the callback from social providers (Google, Twitter, Apple).
+The SDK provides `useVolrAuthCallback` to handle OAuth redirects:
 
 ```tsx
 import { useVolrAuthCallback } from '@volr/react';
@@ -99,11 +150,9 @@ function AuthCallback() {
   const { isLoading, error, isNewUser, user } = useVolrAuthCallback({
     onSuccess: (user) => {
       console.log('Logged in:', user);
-      // Navigate to dashboard or home
     },
     onError: (err) => {
       console.error('Login failed:', err);
-      // Show error message or redirect to login
     },
   });
 
@@ -114,33 +163,21 @@ function AuthCallback() {
 }
 ```
 
-This hook automatically:
-1. Parses URL parameters (`success`, `userId`, `isNewUser`, `error`)
-2. Refreshes the session to establish the authentication cookie
-3. Fetches the full user profile
-4. Updates the global `VolrProvider` context state
-
 ## Failure Semantics
 
-- Relay enforces strict failure-by-default:
-  - `revertOnFail` defaults to `true` and any failed call reverts the entire batch.
-  - Calls to non-contract addresses are rejected.
-  - For ERC20 methods (`transfer`, `transferFrom`, `approve`, `increaseAllowance`, `decreaseAllowance`), if a token returns `false`, the batch is treated as failed (even if it doesn't revert).
-  - Backend precheck rejects obvious failures (non-contract targets; ERC20 `false` on simulation) before submitting.
+- `revertOnFail` defaults to `true` - any failed call reverts the entire batch
+- Calls to non-contract addresses are rejected
+- For ERC20 methods, if a token returns `false`, the batch is treated as failed
 
 ## Diagnostics
 
-When gas estimation or simulation fails, the backend includes a `developerDiagnostics` object in the error response (and FAILED transaction meta). This contains:
+When gas estimation or simulation fails, the backend includes `developerDiagnostics` in the error response:
+
+- `topLevel.reason`: Decoded revert reason
+- `calls[]`: Per-call diagnostics with `target`, `selector`, `isContract`, `callResult`, `decodedRevert`
 
-- `topLevel.reason`: Decoded revert reason for the overall execution attempt
-- `calls[]`: Per-call diagnostics with:
-  - `index`, `target`, `selector`
-  - `isContract` (EOA detection)
-  - `callResult` (raw `eth_call` return data)
-  - `decodedRevert` (human-readable when available)
+Use these to pinpoint which call failed and why.
 
-The SDK surfaces these in console for convenience:
-- Precheck errors: `[volr][precheck] developerDiagnostics: ...`
-- Relay errors: `[volr][relay] developerDiagnostics: ...`
+## License
 
-Use these to pinpoint which call failed and why (e.g., EOA target, ERC20 returned false, custom revert).
+MIT

package/dist/index.cjs

@@ -10104,10 +10104,10 @@ function VolrProvider({ config, children }) {
   );
   return /* @__PURE__ */ jsxRuntime.jsx(VolrContext.Provider, { value: publicValue, children: /* @__PURE__ */ jsxRuntime.jsx(InternalAuthContext.Provider, { value: internalValue, children }) });
 }
-function useVolr() {
+function useVolrContext() {
   const context = react.useContext(VolrContext);
   if (!context) {
-    throw new Error("useVolr must be used within VolrProvider");
+    throw new Error("useVolrContext must be used within VolrProvider");
   }
   return context;
 }
@@ -10189,7 +10189,7 @@ function validateRelayInput(input, config = {}) {
 
 // src/hooks/usePrecheck.ts
 function usePrecheck() {
-  const { precheck: precheckContext } = useVolr();
+  const { precheck: precheckContext } = useVolrContext();
   const [isLoading, setIsLoading] = react.useState(false);
   const [error, setError] = react.useState(null);
   const precheck = react.useCallback(
@@ -10223,7 +10223,7 @@ function useInternalAuth() {
   return context;
 }
 function useRelay() {
-  const { relay: relayContext } = useVolr();
+  const { relay: relayContext } = useVolrContext();
   const { client } = useInternalAuth();
   const [isLoading, setIsLoading] = react.useState(false);
   const [error, setError] = react.useState(null);
@@ -10279,7 +10279,7 @@ function useRelay() {
           authorizationList: [authorizationTuple]
         };
         validateRelayInput(relayInput);
-        return await relayContext(relayInput, {
+        return relayContext(relayInput, {
           idempotencyKey: opts.idempotencyKey
         });
       } catch (err) {
@@ -18383,9 +18383,9 @@ async function sendCalls(args) {
   }
 }
 
-// src/hooks/useVolrWallet.ts
-function useVolrWallet() {
-  const { user, config, provider, setProvider } = useVolr();
+// src/hooks/useVolr.ts
+function useVolr() {
+  const { user, config, provider, setProvider, logout, isLoading, error } = useVolrContext();
   const { precheck } = usePrecheck();
   const { relay } = useRelay();
   const { client } = useInternalAuth();
@@ -18393,7 +18393,7 @@ function useVolrWallet() {
     createGetRpcUrl({ client, rpcOverrides: config.rpcOverrides }),
     [client, config.rpcOverrides]
   );
-  const evm = react.useCallback(
+  const evmFactory = react.useCallback(
     (chainId) => {
       if (chainId === 0) {
         throw new Error("chainId cannot be 0");
@@ -18415,12 +18415,12 @@ function useVolrWallet() {
           const { publicClient: client2 } = await ensureRpcClient();
           return client2.readContract(args);
         },
-        sendTransaction: async (tx, opts) => {
+        sendTransaction: async (tx, opts = {}) => {
           const { publicClient: publicClient2, extendedRpcClient: rpcClient } = await ensureRpcClient();
           const from14 = opts.from ?? user?.evmAddress;
           if (!from14) {
             throw new Error(
-              "from address is required. Provide it in opts.from or set user.evmAddress in VolrProvider. If you haven't set up a wallet provider yet, please complete the onboarding flow."
+              "from address is required. Provide it in opts.from or ensure user is logged in."
             );
           }
           const call2 = {
@@ -18451,7 +18451,7 @@ function useVolrWallet() {
           const from14 = opts.from ?? user?.evmAddress;
           if (!from14) {
             throw new Error(
-              "from address is required. Provide it in opts.from or set user.evmAddress in VolrProvider. If you haven't set up a wallet provider yet, please complete the onboarding flow."
+              "from address is required. Provide it in opts.from or ensure user is logged in."
             );
           }
           const isCallArray = (calls2) => {
@@ -18482,12 +18482,23 @@ function useVolrWallet() {
         })
       };
     },
-    [user, config, provider, precheck, relay, getRpcUrl]
+    [user, config, provider, precheck, relay, getRpcUrl, setProvider, client]
   );
-  return { evm };
+  const evm = Object.assign(evmFactory, {
+    address: user?.evmAddress
+  });
+  return {
+    evm,
+    email: user?.email,
+    isLoggedIn: user !== null,
+    signerType: user?.signerType,
+    logout,
+    isLoading,
+    error
+  };
 }
 function useVolrLogin() {
-  const { config, setUser } = useVolr();
+  const { config, setUser } = useVolrContext();
   const { setAccessToken, setRefreshToken, client } = useInternalAuth();
   const toVolrUser = react.useCallback((u) => {
     return {
@@ -18654,7 +18665,7 @@ function createAxiosInstance(baseUrl, apiKey) {
 
 // src/hooks/useVolrAuthCallback.ts
 function useVolrAuthCallback(options = {}) {
-  const { config, setUser } = useVolr();
+  const { config, setUser } = useVolrContext();
   const { refreshAccessToken, setAccessToken, setRefreshToken, client } = useInternalAuth();
   const [isLoading, setIsLoading] = react.useState(true);
   const [error, setError] = react.useState(null);
@@ -18779,7 +18790,7 @@ function balanceOfCalldata(address) {
   return `${selector}${pad32(address).slice(2)}`;
 }
 function useDepositListener(input) {
-  const { config } = useVolr();
+  const { config } = useVolrContext();
   const { client } = useInternalAuth();
   const [status, setStatus] = react.useState({ state: "idle" });
   const intervalRef = react.useRef(null);
@@ -19033,7 +19044,7 @@ async function enrollPasskey(params) {
   }
 }
 function usePasskeyEnrollment() {
-  const { config, setProvider, setUser, user } = useVolr();
+  const { config, setProvider, setUser, user } = useVolrContext();
   const { client } = useInternalAuth();
   const [step, setStep] = react.useState("idle");
   const [isEnrolling, setIsEnrolling] = react.useState(false);
@@ -19222,7 +19233,7 @@ async function registerWalletProvider(params) {
   });
 }
 function useMpcConnection() {
-  const { setProvider } = useVolr();
+  const { setProvider } = useVolrContext();
   const { client } = useInternalAuth();
   const [step, setStep] = react.useState("idle");
   const [isConnecting, setIsConnecting] = react.useState(false);
@@ -19566,11 +19577,9 @@ exports.useDepositListener = useDepositListener;
 exports.useInternalAuth = useInternalAuth;
 exports.useMpcConnection = useMpcConnection;
 exports.usePasskeyEnrollment = usePasskeyEnrollment;
-exports.usePrecheck = usePrecheck;
-exports.useRelay = useRelay;
 exports.useVolr = useVolr;
 exports.useVolrAuthCallback = useVolrAuthCallback;
+exports.useVolrContext = useVolrContext;
 exports.useVolrLogin = useVolrLogin;
-exports.useVolrWallet = useVolrWallet;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map