npm package: @soulsolidity/zap-widgets
Description: SDK for interacting with the SoulZap protocol
Author: SoulSolidity
Latest version: 0.0.1-alpha13

# SoulZap SDK

A React SDK for integrating SoulZap functionality into your applications. This SDK provides a set of UI components and utilities to enable users to zap from one token to another across different chains.

## Features

- **DEX-like UI/UX**: Interactive swapping interface
- **Token Selection**: Dynamically fetch supported tokens from the registry
- **Customizable UI**: Style components to match your branding
- **Wallet Integration**: Works with any wallet connection library
- **Flexible Integration**: Easy-to-use components for React applications
- **TypeScript Support**: Full type definitions for all components and utilities

## Installation

```bash
npm install zap:sdk
# or
yarn add zap:sdk
```

## Quick Start

```jsx
import { ZapProvider, ZapWidget } from 'zap:sdk';
import { useAccount } from 'wagmi';

function App() {
  // Get wallet address from your preferred wallet library
  const { address } = useAccount();

  // Handle successful zap
  const handleSuccess = (result) => {
    console.log('Zap successful:', result);
  };

  // Handle zap error
  const handleError = (error) => {
      console.error('Zap failed:', error);
  };

  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget 
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </ZapProvider>
  );
}
```

## Components

### ZapWidget

The main component that provides a complete UI for zapping tokens.

```jsx
<ZapWidget 
  className="custom-class"
  theme="light" // 'light', 'dark', or 'auto'
  onSuccess={handleSuccess}
  onError={handleError}
/>
```

#### Props

- `className`: Custom CSS class for styling
- `theme`: UI theme ('light', 'dark', or 'auto')
- `onSuccess`: Callback for successful zap
- `onError`: Callback for zap errors

### ZapProvider

Context provider that manages the state and functionality for the zap components.

```jsx
<ZapProvider
  defaultChainId={56}
  defaultFromToken="0x0000000000000000000000000000000000000000"
  defaultUserAddress={walletAddress}
>
  {/* Your components */}
</ZapProvider>
```

#### Props

- `defaultChainId`: Default chain ID to use
- `defaultFromToken`: Default token address to use as the source token
- `defaultUserAddress`: User's wallet address from your wallet connection library

### Individual Components

The SDK also exports individual components for custom integrations:

- `TokenSelector`: Component for selecting tokens
- `AmountInput`: Input field for token amounts
- `ChainSelector`: Component for selecting blockchain networks
- `TransactionPreview`: Component for previewing transactions

## Wallet Integration

The SDK is designed to work with any wallet connection library. Simply pass the user's wallet address to the `ZapProvider` component:

```jsx
// With wagmi/viem
import { useAccount } from 'wagmi';

function App() {
  const { address } = useAccount();
  
  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget />
    </ZapProvider>
  );
}

// With ethers.js
import { useState, useEffect } from 'react';
import { ethers } from 'ethers';

function App() {
  const [address, setAddress] = useState('');
  
  useEffect(() => {
    const connectWallet = async () => {
      if (window.ethereum) {
        const provider = new ethers.providers.Web3Provider(window.ethereum);
        const accounts = await provider.send('eth_requestAccounts', []);
        setAddress(accounts[0]);
      }
    };
    
    connectWallet();
  }, []);
  
  return (
    <ZapProvider defaultUserAddress={address}>
      <ZapWidget />
    </ZapProvider>
  );
}
```

## API

### Hooks

- `useZap()`: Hook to access the zap context and functionality

### Utilities

- `fetchRegistry()`: Fetch the zap registry data
- `transformRegistryToTokens()`: Transform registry data into a list of tokens
- `getSupportedChains()`: Get supported chains from the registry
- `getTokensByChain()`: Get tokens for a specific chain
- `makeZapRequest()`: Make a zap API call
- `formatAddress()`: Format an address to a shortened form
- `formatNumber()`: Format a number to a readable string
- `isValidAddress()`: Validate if a string is a valid Ethereum address
- `chainIdToName()`: Format a chain ID to its network name

## API Endpoint

The SDK interacts with the following API endpoint:

```
GET http://localhost:3001/zap?fromToken=<address>&fromAmount=<amount>&toToken=<address>&chain=<chainId>&user=<walletAddress>
```

## Registry Data

The SDK fetches supported tokens from the registry at:
`https://raw.githubusercontent.com/SoulSolidity/registry/main/data/constants/zap.json`

## Customization

### Styling

The SDK uses Tailwind CSS for styling. You can customize the appearance by:

1. Providing custom classes via the `className` prop
2. Setting the `theme` prop to 'light', 'dark', or 'auto'
3. Overriding the CSS variables in your application

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build the SDK
npm run build:sdk
```

## License

MIT