@avalabs/avacloud-waas-react 1.0.0

package/README.md

@@ -0,0 +1,287 @@
+# @avalabs/avacloud-waas-react
+
+Official React SDK for AvaCloud Authentication and wallet integration. This library provides a seamless way to integrate AvaCloud authentication and wallet functionality into your React applications.
+
+[![npm version](https://img.shields.io/npm/v/@avalabs/avacloud-waas-react.svg)](https://www.npmjs.com/package/@avalabs/avacloud-waas-react)
+[![License](https://img.shields.io/npm/l/@avalabs/avacloud-waas-react.svg)](https://github.com/ava-labs/avacloud-waas-react/blob/main/LICENSE)
+
+
+## Installation
+
+```bash
+# npm
+npm install @avalabs/avacloud-waas-react
+
+# yarn
+yarn add @avalabs/avacloud-waas-react
+
+# pnpm
+pnpm add @avalabs/avacloud-waas-react
+```
+
+## Quick Start
+
+Wrap your application with the `AvaCloudWalletProvider`:
+
+```tsx
+import { AvaCloudWalletProvider } from '@avalabs/avacloud-waas-react';
+
+function App() {
+  return (
+    <AvaCloudWalletProvider 
+      orgId="your-avacloud-org-id" // Required
+      chainId={43113} // Avalanche Fuji Testnet
+    >
+      <YourApp />
+    </AvaCloudWalletProvider>
+  );
+}
+```
+
+Use the authentication hooks and components in your application:
+
+```tsx
+import { useAvaCloudWallet, LoginButton, WalletDisplay } from '@avalabs/avacloud-waas-react';
+
+function YourComponent() {
+  const { isAuthenticated, isLoading, user, wallet } = useAvaCloudWallet();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <>
+          <p>Welcome, {user?.email || 'User'}!</p>
+          <WalletDisplay />
+        </>
+      ) : (
+        <LoginButton />
+      )}
+    </div>
+  );
+}
+```
+
+## Core Components
+
+### AvaCloudWalletProvider
+
+The main provider component that wraps your application and provides authentication context.
+
+```tsx
+<AvaCloudWalletProvider
+  authServiceUrl="https://auth.avacloud.io"
+  chainId={43113}
+  darkMode={false}
+  onAuthSuccess={(user) => console.log('Auth success', user)}
+  onAuthError={(error) => console.error('Auth error', error)}
+  onWalletUpdate={(wallet) => console.log('Wallet updated', wallet)}
+>
+  {children}
+</AvaCloudWalletProvider>
+```
+
+#### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `authServiceUrl` | `string` | URL of the AvaCloud authentication service |
+| `chainId` | `number` | (Optional) EVM chain ID to use (defaults to Avalanche Fuji Testnet - 43113) |
+| `darkMode` | `boolean` | (Optional) Whether to use dark mode for UI components |
+| `onAuthSuccess` | `(user: Auth0User) => void` | (Optional) Callback called when authentication is successful |
+| `onAuthError` | `(error: Error) => void` | (Optional) Callback called when authentication fails |
+| `onWalletUpdate` | `(wallet: WalletInfo) => void` | (Optional) Callback called when wallet information is updated |
+
+### UI Components
+
+- `LoginButton`: Button component for initiating the login flow
+- `WalletButton`: Button component for displaying wallet information and actions
+- `WalletDisplay`: Component for displaying wallet address and balance
+- `UserProfile`: Component for displaying user profile information
+- `WalletCard`: Card component for displaying wallet information
+- `TokensView`: Component for displaying token balances
+- `SendView`: Component for sending tokens
+- `ReceiveView`: Component for receiving tokens (displays QR code)
+- `ExportView`: Component for exporting wallet information
+
+## Hooks
+
+### useAvaCloudWallet
+
+The main hook for accessing authentication state and methods.
+
+```tsx
+const {
+  isAuthenticated,
+  isLoading,
+  user,
+  wallet,
+  login,
+  logout,
+  addAccount,
+} = useAvaCloudWallet();
+```
+
+### useAuth
+
+Simplified hook for basic authentication state.
+
+```tsx
+const { isAuthenticated, login, logout } = useAuth();
+```
+
+### useSignMessage
+
+Hook for signing messages with the connected wallet.
+
+```tsx
+const { signMessage, isLoading, error } = useSignMessage();
+
+const handleSign = async () => {
+  try {
+    const signature = await signMessage('Hello, AvaCloud!');
+    console.log('Signature:', signature);
+  } catch (error) {
+    console.error('Error signing message:', error);
+  }
+};
+```
+
+### useSignTransaction
+
+Hook for signing transactions with the connected wallet.
+
+```tsx
+const { signTransaction, isLoading, error } = useSignTransaction();
+
+const handleSignTx = async () => {
+  try {
+    const signedTx = await signTransaction({
+      to: '0x...',
+      value: '0.1',
+      data: '0x...',
+    });
+    console.log('Signed transaction:', signedTx);
+  } catch (error) {
+    console.error('Error signing transaction:', error);
+  }
+};
+```
+
+### useTransferTokens
+
+Hook for transferring tokens.
+
+```tsx
+const { transfer, isLoading, error } = useTransferTokens();
+
+const handleTransfer = async () => {
+  try {
+    const txHash = await transfer({
+      to: '0x...',
+      amount: '0.1',
+      tokenAddress: '0x...', // Optional, use null for native token
+    });
+    console.log('Transaction hash:', txHash);
+  } catch (error) {
+    console.error('Error transferring tokens:', error);
+  }
+};
+```
+
+## Advanced Usage
+
+### Theme Customization
+
+Use the `ThemeProvider` to customize the appearance of UI components:
+
+```tsx
+import { ThemeProvider } from '@avalabs/avacloud-waas-react';
+
+function App() {
+  return (
+    <ThemeProvider darkMode={true}>
+      <YourApp />
+    </ThemeProvider>
+  );
+}
+```
+
+### Custom Authentication Flow
+
+You can implement a custom authentication flow using the lower-level hooks:
+
+```tsx
+import { usePostMessage } from '@avalabs/avacloud-waas-react';
+
+function CustomAuth() {
+  const { sendMessage, lastMessage } = usePostMessage();
+
+  const handleCustomLogin = () => {
+    sendMessage({
+      type: 'login',
+      payload: {
+        // Custom payload
+      }
+    });
+  };
+
+  // Handle response in useEffect
+  useEffect(() => {
+    if (lastMessage?.type === 'login_success') {
+      // Handle successful login
+    }
+  }, [lastMessage]);
+
+  return (
+    <button onClick={handleCustomLogin}>
+      Custom Login
+    </button>
+  );
+}
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](https://github.com/ava-labs/avacloud-waas-react/blob/main/CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Ava Labs, Inc.](https://github.com/ava-labs)
+
+## Using the AvaCloud Organization ID
+
+The `AvaCloudWalletProvider` requires an AvaCloud organization ID (`orgId`). This will be used to fetch the organization configuration from the AvaCloud API, which includes the mapping to the appropriate Cubist organization ID used for wallet operations.
+
+```jsx
+import { AvaCloudWalletProvider } from '@avalabs/avacloud-waas-react';
+
+function App() {
+  return (
+    <AvaCloudWalletProvider
+      authServiceUrl="https://ac-auth-service.vercel.app/"
+      orgId="your-avacloud-org-id" // Required AvaCloud organization ID
+    >
+      <YourApp />
+    </AvaCloudWalletProvider>
+  );
+}
+```
+
+When provided, the `orgId` will be used to:
+
+1. Fetch the organization configuration from the AvaCloud API
+2. Map to a Cubist organization ID as specified in the configuration
+3. Use the mapped ID for Cubist authentication and wallet operations
+
+This enables organizations to have their AvaCloud identity seamlessly map to their Cubist wallets.