@phantom/react-native-sdk 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -30,10 +30,10 @@ yarn add @phantom/react-native-sdk
 
 ```bash
 # For Expo projects
-npx expo install expo-secure-store expo-web-browser expo-auth-session expo-router
+npx expo install expo-secure-store expo-web-browser expo-auth-session expo-router react-native-svg
 
 # For bare React Native projects (additional setup required)
-npm install expo-secure-store expo-web-browser expo-auth-session
+npm install expo-secure-store expo-web-browser expo-auth-session react-native-svg
 
 # Required polyfill for cryptographic operations
 npm install react-native-get-random-values
@@ -83,12 +83,13 @@ Wrap your app with `PhantomProvider`:
 
 ```tsx
 // App.tsx or _layout.tsx (for Expo Router)
-import { PhantomProvider, AddressType } from "@phantom/react-native-sdk";
+import { PhantomProvider, AddressType, darkTheme } from "@phantom/react-native-sdk";
 
 export default function App() {
   return (
     <PhantomProvider
       config={{
+        providers: ["google", "apple"],
         appId: "your-app-id", // Get your app ID from phantom.com/portal
         scheme: "mywalletapp", // Must match app.json scheme
         addressTypes: [AddressType.solana],
@@ -96,6 +97,9 @@ export default function App() {
           redirectUrl: "mywalletapp://phantom-auth-callback",
         },
       }}
+      theme={darkTheme} // Optional: Customize modal appearance
+      appIcon="https://your-app.com/icon.png" // Optional: Your app icon
+      appName="Your App Name" // Optional: Your app name
     >
       <YourAppContent />
     </PhantomProvider>
@@ -103,7 +107,53 @@ export default function App() {
 }
 ```
 
-### 3. Use hooks in your components
+### 3. Use the connection modal (Recommended)
+
+The SDK includes a built-in bottom sheet modal that provides a user-friendly interface for connecting to Phantom. The modal supports multiple authentication methods (Google, Apple) and handles all connection logic automatically.
+
+```tsx
+// WalletScreen.tsx
+import React from "react";
+import { View, Button, Text } from "react-native";
+import { useModal, useAccounts } from "@phantom/react-native-sdk";
+
+export function WalletScreen() {
+  const modal = useModal();
+  const { isConnected, addresses } = useAccounts();
+
+  if (!isConnected) {
+    return (
+      <View style={{ padding: 20 }}>
+        <Button title="Connect Wallet" onPress={() => modal.open()} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={{ padding: 20 }}>
+      <Text style={{ fontSize: 18, marginBottom: 10 }}>Wallet Connected</Text>
+      {addresses.map((addr, index) => (
+        <Text key={index}>
+          {addr.addressType}: {addr.address}
+        </Text>
+      ))}
+      <Button title="Manage Wallet" onPress={() => modal.open()} />
+    </View>
+  );
+}
+```
+
+**Modal Features:**
+
+- **Multiple Auth Providers**: Google, Apple
+- **Bottom Sheet UI**: Native bottom sheet design for mobile
+- **Automatic State Management**: Shows connect screen when disconnected, wallet management when connected
+- **Error Handling**: Clear error messages displayed in the modal
+- **Loading States**: Visual feedback during connection attempts
+
+### 4. Or use hooks directly
+
+Alternatively, you can use the hooks directly for more control:
 
 ```tsx
 // WalletScreen.tsx
@@ -114,8 +164,8 @@ import { useConnect, useAccounts, useSolana, useEthereum, useDisconnect } from "
 export function WalletScreen() {
   const { connect, isConnecting, error: connectError } = useConnect();
   const { addresses, isConnected } = useAccounts();
-  const solana = useSolana();
-  const ethereum = useEthereum();
+  const { solana } = useSolana();
+  const { ethereum } = useEthereum();
   const { disconnect } = useDisconnect();
 
   const handleConnect = async () => {
@@ -197,11 +247,20 @@ The main provider component that initializes the SDK and provides context to all
 #### Configuration Options
 
 ```typescript
+interface PhantomProviderProps {
+  config: PhantomSDKConfig;
+  debugConfig?: PhantomDebugConfig;
+  theme?: PhantomTheme; // Optional: Customize modal appearance
+  appIcon?: string; // Optional: Your app icon URL (shown in modal)
+  appName?: string; // Optional: Your app name (shown in modal)
+  children: ReactNode;
+}
+
 interface PhantomSDKConfig {
   scheme: string; // Custom URL scheme for your app
   appId: string; // Your app ID from phantom.com/portal (required)
   addressTypes: [AddressType, ...AddressType[]]; // e.g., [AddressType.solana]
-  
+
   // Optional configuration
   embeddedWalletType?: "user-wallet"; // optional, defaults to "user-wallet", currently the only supported type
   apiBaseUrl?: string; // e.g., "https://api.phantom.app/v1/wallets" (optional, has default)
@@ -209,12 +268,39 @@ interface PhantomSDKConfig {
     authUrl?: string; // Custom auth URL (optional)
     redirectUrl?: string; // Custom redirect URL (optional)
   };
-  autoConnect?: boolean; // Auto-connect to existing session on SDK instantiation (optional, defaults to true)
 }
 ```
 
 ### Hooks
 
+#### useModal
+
+Control the connection modal visibility. The modal automatically shows the appropriate content based on connection status.
+
+```typescript
+const modal = useModal();
+
+// Open the modal
+modal.open(); // Shows connect options when disconnected, wallet management when connected
+
+// Close the modal
+modal.close();
+
+// Check if modal is open
+const isOpen = modal.isOpened;
+```
+
+**Returns:**
+
+- `open()` - Function to open the modal
+- `close()` - Function to close the modal
+- `isOpened` - Boolean indicating if modal is currently visible
+
+**Modal Behavior:**
+
+- **When disconnected**: Shows authentication provider options (Google, Apple)
+- **When connected**: Shows connected wallet addresses and disconnect button
+
 #### useConnect
 
 Manages wallet connection functionality.
@@ -222,10 +308,9 @@ Manages wallet connection functionality.
 ```typescript
 const { connect, isConnecting, error } = useConnect();
 
-// Connect with specific provider
-await connect({ provider: "google" });
-await connect({ provider: "apple" });
-await connect({ provider: "jwt", jwtToken: "your-jwt-token" });
+// Connect with specific provider (React Native supported providers)
+await connect({ provider: "google" }); // Google OAuth
+await connect({ provider: "apple" }); // Apple ID
 ```
 
 #### useAccounts
@@ -276,14 +361,44 @@ if (isAvailable) {
   // Sign a transaction (without sending)
   const signedTx = await ethereum.signTransaction(transactionData);
 
-  // Sign and send a transaction  
+  // Sign and send a transaction
   const result = await ethereum.sendTransaction(transactionData);
 
+  // Switch to a different chain
+  await ethereum.switchChain(137); // Switch to Polygon
+  await ethereum.switchChain("0x89"); // Also accepts hex strings
+
   // Get current chain ID
   const chainId = await ethereum.getChainId();
 }
 ```
 
+**Available Methods:**
+
+- `getAccounts()` - Get connected Ethereum accounts
+- `signPersonalMessage(message, address)` - Sign personal message
+- `signTypedData(typedData, address)` - Sign EIP-712 typed data
+- `signTransaction(transaction)` - Sign transaction without sending
+- `sendTransaction(transaction)` - Sign and send transaction
+- `switchChain(chainId)` - Switch chains (accepts chain ID as number or hex string)
+- `getChainId()` - Get current chain ID
+- `isConnected()` - Check connection status
+
+**Supported EVM Networks:**
+
+| Network          | Chain ID   | Usage                            |
+| ---------------- | ---------- | -------------------------------- |
+| Ethereum Mainnet | `1`        | `ethereum.switchChain(1)`        |
+| Ethereum Sepolia | `11155111` | `ethereum.switchChain(11155111)` |
+| Polygon Mainnet  | `137`      | `ethereum.switchChain(137)`      |
+| Polygon Amoy     | `80002`    | `ethereum.switchChain(80002)`    |
+| Base Mainnet     | `8453`     | `ethereum.switchChain(8453)`     |
+| Base Sepolia     | `84532`    | `ethereum.switchChain(84532)`    |
+| Arbitrum One     | `42161`    | `ethereum.switchChain(42161)`    |
+| Arbitrum Sepolia | `421614`   | `ethereum.switchChain(421614)`   |
+| Monad Mainnet    | `143`      | `ethereum.switchChain(143)`      |
+| Monad Testnet    | `10143`    | `ethereum.switchChain(10143)`    |
+
 #### useDisconnect
 
 Manages wallet disconnection.
@@ -294,15 +409,70 @@ const { disconnect, isDisconnecting } = useDisconnect();
 await disconnect();
 ```
 
+## Theming
+
+Customize the modal appearance by passing a `theme` prop to the `PhantomProvider`. The SDK includes built-in `darkTheme` (default).
+
+### Using Built-in Theme
+
+```tsx
+import { PhantomProvider, darkTheme } from "@phantom/react-native-sdk";
+
+<PhantomProvider config={config} theme={darkTheme} appIcon="https://your-app.com/icon.png" appName="Your App Name">
+  <App />
+</PhantomProvider>;
+```
+
+### Custom Theme
+
+You can pass a partial theme object to customize specific properties:
+
+```tsx
+import { PhantomProvider } from "@phantom/react-native-sdk";
+
+const customTheme = {
+  brand: "#7C3AED", // Primary brand color
+  background: "#1A1A1A", // Background color
+  primary: "#FFFFFF", // Primary text color
+  secondary: "#A0A0A0", // Secondary text color
+  error: "#EF4444", // Error color
+  borderRadius: 12, // Border radius for elements
+};
+
+<PhantomProvider config={config} theme={customTheme}>
+  <App />
+</PhantomProvider>;
+```
+
+**Theme Properties:**
+
+- `brand` - Primary brand color (buttons, accents)
+- `background` - Background color for modal
+- `primary` - Primary text color
+- `secondary` - Secondary text color (labels, descriptions)
+- `error` - Error text and border color
+- `borderRadius` - Border radius for buttons and containers
+
 ## Authentication Flows
 
-### OAuth Providers
+### Available Providers
+
+The SDK supports multiple authentication providers that you specify when calling `connect()`:
+
+- **Google** (`provider: "google"`) - Google OAuth authentication
+- **Apple** (`provider: "apple"`) - Apple ID authentication
 
-The SDK supports multiple OAuth providers:
+> **Note**: React Native SDK does not support Phantom Login or injected provider (browser extension) authentication. These are only available in the Browser SDK and React SDK for web applications.
 
-- **Google** (`provider: 'google'`)
-- **Apple** (`provider: 'apple'`)
-- **JWT** (`provider: 'jwt'`) - For custom authentication
+**Example Usage:**
+
+```tsx
+// Google OAuth
+await connect({ provider: "google" });
+
+// Apple ID
+await connect({ provider: "apple" });
+```
 
 ### Authentication Process
 
@@ -344,6 +514,7 @@ import { PhantomProvider, AddressType } from "@phantom/react-native-sdk";
 <PhantomProvider
   config={{
     appId: "your-app-id",
+    providers: ["google", "apple"],
     scheme: "myapp",
     addressTypes: [AddressType.solana],
   }}
@@ -360,6 +531,7 @@ import { PhantomProvider, AddressType } from "@phantom/react-native-sdk";
 <PhantomProvider
   config={{
     appId: "your-app-id",
+    providers: ["google", "apple"],
     scheme: "mycompany-wallet",
     addressTypes: [AddressType.solana, AddressType.ethereum],
     authOptions: {
@@ -472,12 +644,3 @@ interface PhantomDebugConfig {
   enabled?: boolean; // Enable debug logging (default: false)
 }
 ```
-
-## Support
-
-- **Documentation**: [phantom.app/docs](https://phantom.app/docs)
-- **GitHub Issues**: [github.com/phantom/wallet-sdk/issues](https://github.com/phantom/wallet-sdk/issues)
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import * as _phantom_embedded_provider_core from '@phantom/embedded-provider-core';
-import { EmbeddedProviderConfig, EmbeddedProvider, WalletAddress, ConnectResult } from '@phantom/embedded-provider-core';
-export { ConnectResult, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
-import * as _phantom_chain_interfaces from '@phantom/chain-interfaces';
+import { EmbeddedProviderConfig, EmbeddedProviderAuthType, EmbeddedProvider, WalletAddress, ConnectResult } from '@phantom/embedded-provider-core';
+export { ConnectErrorEventData, ConnectEventData, ConnectResult, ConnectStartEventData, DisconnectEventData, EmbeddedProviderEvent, EmbeddedProviderEventMap, EventCallback, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
+import { PhantomTheme } from '@phantom/wallet-sdk-ui';
+export { PhantomTheme, darkTheme, lightTheme } from '@phantom/wallet-sdk-ui';
+import { ISolanaChain, IEthereumChain } from '@phantom/chain-interfaces';
 export { AddressType } from '@phantom/client';
 export { NetworkId } from '@phantom/constants';
 
@@ -12,10 +14,9 @@ interface PhantomDebugConfig {
     enabled?: boolean;
 }
 interface PhantomSDKConfig extends Omit<EmbeddedProviderConfig, "apiBaseUrl" | "embeddedWalletType" | "authOptions"> {
+    providers: EmbeddedProviderAuthType[];
     /** Custom URL scheme for your app (e.g., "myapp") */
     scheme: string;
-    /** Enable auto-connect to existing sessions (default: true) */
-    autoConnect?: boolean;
     /** Base URL for Phantom API (default: "https://api.phantom.app/v1/wallets") */
     apiBaseUrl?: string;
     /** Authentication options */
@@ -26,35 +27,50 @@ interface PhantomSDKConfig extends Omit<EmbeddedProviderConfig, "apiBaseUrl" | "
     };
 }
 interface ConnectOptions {
-    /** OAuth provider to use */
-    provider?: "google" | "apple" | "jwt";
-    /** JWT token for JWT authentication */
-    jwtToken?: string;
+    /** OAuth provider to use (required) */
+    provider: EmbeddedProviderAuthType;
     /** Custom authentication data */
     customAuthData?: Record<string, any>;
 }
 
+interface PhantomProviderProps {
+    children: ReactNode;
+    config: PhantomSDKConfig;
+    debugConfig?: PhantomDebugConfig;
+    theme?: Partial<PhantomTheme>;
+    appIcon?: string;
+    appName?: string;
+}
+declare function PhantomProvider({ children, config, debugConfig, theme, appIcon, appName }: PhantomProviderProps): react_jsx_runtime.JSX.Element;
+
+interface PhantomErrors {
+    connect?: Error;
+    spendingLimit?: boolean;
+}
 interface PhantomContextValue {
     sdk: EmbeddedProvider;
     isConnected: boolean;
     isConnecting: boolean;
-    connectError: Error | null;
+    errors: PhantomErrors;
     addresses: WalletAddress[];
     walletId: string | null;
     setWalletId: (walletId: string | null) => void;
+    user: ConnectResult | null;
+    allowedProviders: EmbeddedProviderAuthType[];
+    clearError: (key: keyof PhantomErrors) => void;
 }
-interface PhantomProviderProps {
-    children: ReactNode;
-    config: PhantomSDKConfig;
-    debugConfig?: PhantomDebugConfig;
-}
-declare function PhantomProvider({ children, config, debugConfig }: PhantomProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePhantom(): PhantomContextValue;
 
+declare function useModal(): {
+    open: () => void;
+    close: () => void;
+    isOpened: boolean;
+};
+
 declare function useConnect(): {
-    connect: (_options?: ConnectOptions) => Promise<ConnectResult>;
+    connect: (options: ConnectOptions) => Promise<ConnectResult>;
     isConnecting: boolean;
-    error: Error | null;
+    error: Error | undefined;
 };
 
 declare function useDisconnect(): {
@@ -75,7 +91,7 @@ declare function useAccounts(): {
  * @returns Solana chain interface with connection enforcement
  */
 declare function useSolana(): {
-    solana: _phantom_chain_interfaces.ISolanaChain;
+    solana: ISolanaChain;
     isAvailable: boolean;
 };
 
@@ -85,8 +101,8 @@ declare function useSolana(): {
  * @returns Ethereum chain interface with connection enforcement
  */
 declare function useEthereum(): {
-    ethereum: _phantom_chain_interfaces.IEthereumChain;
+    ethereum: IEthereumChain;
     isAvailable: boolean;
 };
 
-export { ConnectOptions, PhantomDebugConfig, PhantomProvider, PhantomSDKConfig, useAccounts, useConnect, useDisconnect, useEthereum, usePhantom, useSolana };
+export { ConnectOptions, PhantomDebugConfig, PhantomProvider, PhantomSDKConfig, useAccounts, useConnect, useDisconnect, useEthereum, useModal, usePhantom, useSolana };