langit-sdk/README.md

React SDK for Langit Token bridging with MetaMask integration

# Langit SDK

React SDK for Langit Token bridging with MetaMask and WalletConnect integration.

## Features

- ✅ **MetaMask Web Extension** support
- ✅ **MetaMask Mobile** support via WalletConnect v2
- ✅ **Cross-chain token bridging** with Hyperlane
- ✅ **React hooks** for easy integration
- ✅ **TypeScript** support
- ✅ **Mobile-responsive** components

## Installation

```bash
npm install langit-sdk
```

## Quick Start

### Basic Usage (MetaMask Web Only)

```tsx
import React from 'react';
import { useLangitPay } from 'langit-sdk';

function App() {
  const { connectWallet, approve, transfer, address, error } = useLangitPay(
    config,
    approveParams,
    transferParams,
    6 // token decimals
  );

  const handleConnect = async () => {
    try {
      await connectWallet('metamask'); // Connect to MetaMask Web
    } catch (error) {
      console.error('Connection failed:', error);
    }
  };

  return (
    <div>
      {!address ? (
        <button onClick={handleConnect}>Connect MetaMask</button>
      ) : (
        <div>
          <p>Connected: {address}</p>
          <button onClick={approve}>Approve</button>
          <button onClick={transfer}>Transfer</button>
        </div>
      )}
      {error && <p>Error: {error}</p>}
    </div>
  );
}
```

### With Mobile Support

```tsx
import React from 'react';
import { useLangitPay } from 'langit-sdk';

function App() {
  const { connectWallet, approve, transfer, address, error } = useLangitPay(
    config,
    approveParams,
    transferParams,
    6, // token decimals
    {
      walletConnectConfig: {
        projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
        chains: [1, 5, 137, 42161],
        optionalChains: [1, 5, 137, 42161],
        showQrModal: true,
        metadata: {
          name: 'Your App',
          description: 'Your app description',
          url: 'https://yourapp.com',
          icons: ['https://yourapp.com/icon.png']
        }
      }
    }
  );

  const handleConnect = async () => {
    try {
      await connectWallet(); // Auto-detects best wallet type
    } catch (error) {
      console.error('Connection failed:', error);
    }
  };

  return (
    <div>
      {!address ? (
        <button onClick={handleConnect}>Connect Wallet</button>
      ) : (
        <div>
          <p>Connected: {address}</p>
          <button onClick={approve}>Approve</button>
          <button onClick={transfer}>Transfer</button>
        </div>
      )}
      {error && <p>Error: {error}</p>}
    </div>
  );
}
```

### Specific Wallet Connection

```tsx
// Connect to MetaMask Web Extension
const handleConnectMetaMask = async () => {
  await connectWallet('metamask');
};

// Connect to MetaMask Mobile via WalletConnect
const handleConnectWalletConnect = async () => {
  await connectWallet('walletconnect');
};
```

### Using the Component

#### Basic Usage (MetaMask Web Only)
```tsx
import { LangitPayComponent } from 'langit-sdk';

function App() {
  return (
    <LangitPayComponent
      transactionParams={{
        recipientAddress: '0x123...',
        transferAmount: 10.5
      }}
      onSuccess={(txHash) => console.log('Success:', txHash)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

#### With Mobile Support (MetaMask + WalletConnect)
```tsx
import { LangitPayComponent } from 'langit-sdk';

function App() {
  return (
    <LangitPayComponent
      transactionParams={{
        recipientAddress: '0x123...',
        transferAmount: 10.5
      }}
      walletConnectProjectId="YOUR_WALLETCONNECT_PROJECT_ID"
      enableWalletConnect={true}
      onSuccess={(txHash) => console.log('Success:', txHash)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

## WalletConnect Setup

### 1. Get Project ID

1. Go to [WalletConnect Cloud](https://cloud.walletconnect.com)
2. Create a new project
3. Copy your Project ID

### 2. Enable in Your Component

Simply add the `walletConnectProjectId` and `enableWalletConnect` props to your `LangitPayComponent`:

```tsx
<LangitPayComponent
  transactionParams={transactionParams}
  walletConnectProjectId="YOUR_PROJECT_ID_HERE"
  enableWalletConnect={true}
  onSuccess={onSuccess}
  onError={onError}
/>
```

## Browser Support

- ✅ Chrome/Chromium
- ✅ Firefox
- ✅ Safari
- ✅ Edge
- ✅ Mobile browsers (iOS Safari, Android Chrome)
- ✅ In-app browsers (Facebook, Instagram, etc.)

## Troubleshooting

### WalletConnect Issues

1. **Project ID not set**: Make sure you've replaced `'YOUR_WALLETCONNECT_PROJECT_ID'` with your actual project ID
2. **QR code not showing**: Check that `showQrModal: true` is set in your config
3. **Mobile deep link not working**: Ensure you're not in an in-app browser

### MetaMask Issues

1. **MetaMask not detected**: Make sure MetaMask is installed and unlocked
2. **Wrong network**: Ensure you're on the correct network for your transaction
3. **Transaction rejected**: Check your MetaMask settings and gas fees

## Development

```bash
# Install dependencies
npm install

# Build the SDK
npm run build

# Watch for changes
npm run dev
```

## License

MIT