otx-swap 1.2.1 → 1.2.3

package/README.md

@@ -1,73 +1,467 @@
-# React + TypeScript + Vite
+# OTX Swap Widget
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+A lightweight, customizable React widget for cross-chain token swaps powered by Optimex protocol.
 
-Currently, two official plugins are available:
+## Features
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- Cross-chain swaps between EVM, Bitcoin, and Solana networks
+- Bring Your Own Wallet (BYOW) - integrate with your existing wallet infrastructure
+- Fully customizable theming
+- TypeScript support with full type definitions
+- Lightweight bundle (~313KB gzipped: ~72KB)
+- Lifecycle callbacks for tracking swap progress
 
-## React Compiler
+## Installation
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+```bash
+npm install otx-swap
+# or
+yarn add otx-swap
+# or
+pnpm add otx-swap
+```
 
-## Expanding the ESLint configuration
+### Peer Dependencies
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+```bash
+npm install react react-dom
+```
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+## Quick Start
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+```tsx
+import { SwapWidget } from "otx-swap";
+import type { ExternalWalletClient } from "otx-swap";
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
+function App() {
+  // Build wallet client from your wallet provider
+  const walletClient: ExternalWalletClient = {
+    evm: {
+      address: "0x...",
+      publicKey: "0x...",
+      chain: { id: 1, name: "Ethereum", type: "EVM" },
+      sendTransaction: async (tx) => {
+        // Your wallet's sendTransaction implementation
+        return txHash;
+      },
+      getChainId: async () => 1,
+      switchChain: async (chainId) => {
+        // Your wallet's switchChain implementation
       },
-      // other options...
     },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
+  };
+
+  return (
+    <SwapWidget
+      apiBaseUrl="https://api.optimex.io"
+      walletClient={walletClient}
+      onRequestWallet={(networkId) => {
+        // Called when user needs to connect wallet
+        console.log("Connect wallet for network:", networkId);
+      }}
+    />
+  );
+}
+```
+
+## API Reference
+
+### SwapWidget Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `apiBaseUrl` | `string` | Yes | - | Optimex API base URL |
+| `walletClient` | `ExternalWalletClient` | Yes | - | Connected wallet client object |
+| `onRequestWallet` | `(networkId?: string) => void` | No | - | Callback when wallet connection is needed |
+| `theme` | `PartialThemeConfig` | No | - | Custom theme configuration |
+| `defaultFromToken` | `string` | No | - | Default source token ID |
+| `defaultToToken` | `string` | No | - | Default destination token ID |
+| `defaultSlippage` | `number` | No | `0.75` | Default slippage tolerance (%) |
+| `hideHistory` | `boolean` | No | `false` | Hide transaction history button |
+| `affiliateFee` | `number` | No | - | Affiliate fee in basis points |
+| `affiliateAddress` | `string` | No | - | Affiliate fee recipient address |
+| `affiliateProvider` | `string` | No | - | Affiliate provider identifier |
+| `tradeTimeout` | `number` | No | - | Trade timeout in minutes |
+| `scriptTimeout` | `number` | No | - | Script timeout in minutes |
+| `queryClient` | `QueryClient` | No | - | Shared React Query client |
+| `renderLoading` | `ComponentType` | No | - | Custom loading component |
+| `renderError` | `ComponentType` | No | - | Custom error component |
+| `children` | `ReactNode` | No | - | Custom content instead of default SwapCard |
+
+### Lifecycle Callbacks
+
+Track swap progress with these callbacks:
+
+```tsx
+<SwapWidget
+  apiBaseUrl="https://api.optimex.io"
+  walletClient={walletClient}
+  onQuote={(data) => {
+    // Called when quote is received
+    console.log("Quote received:", data.quote.trade_id);
+  }}
+  onWalletTx={(data) => {
+    // Called when wallet transaction is sent
+    console.log("Wallet TX:", data.tx_hash);
+  }}
+  onSubmitTx={(data) => {
+    // Called when transaction is submitted to network
+    console.log("Submit TX status:", data.status);
+  }}
+  onSwapComplete={(data) => {
+    // Called when swap is completed successfully
+    console.log("Swap complete:", data.trade.trade_id);
+  }}
+  onError={(data) => {
+    // Called when an error occurs
+    console.error("Error at stage:", data.stage, data.error);
+  }}
+/>
+```
+
+#### Callback Types
+
+```typescript
+interface QuoteCallbackData {
+  quote: Quote;
+  from_token: Token;
+  to_token: Token;
+  amount_in: string;
+}
+
+interface WalletTxCallbackData {
+  trade_id: string;
+  tx_hash: string;
+  from_token: Token;
+  to_token: Token;
+  amount_in: string;
+}
+
+interface SubmitTxCallbackData {
+  trade_id: string;
+  tx_hash: string;
+  status: "success" | "error";
+  error?: string;
+}
+
+interface SwapCompleteCallbackData {
+  trade: Trade;
+  tx_hash: string;
+}
+
+interface SwapErrorCallbackData {
+  error: Error;
+  stage: "quote" | "approval" | "wallet_tx" | "submit_tx" | "tracking";
+  trade_id?: string;
+}
+```
+
+## Wallet Integration
+
+### ExternalWalletClient Interface
+
+The widget requires a wallet client that implements the `ExternalWalletClient` interface:
+
+```typescript
+interface ExternalWalletClient {
+  evm?: EvmWalletAccount;    // EVM wallet (Ethereum, Polygon, etc.)
+  btc?: WalletAccount;        // Bitcoin wallet
+  solana?: WalletAccount;     // Solana wallet
+}
+```
+
+### EVM Wallet
+
+```typescript
+interface EvmWalletAccount {
+  address: string;
+  publicKey: string;
+  chain: {
+    id: number;
+    name: string;
+    type: "EVM";
+  };
+  sendTransaction: (tx: EvmTransactionRequest) => Promise<string>;
+  getChainId: () => Promise<number>;
+  switchChain: (chainId: number) => Promise<void>;
+}
+
+interface EvmTransactionRequest {
+  to: `0x${string}`;
+  value?: bigint;
+  data?: `0x${string}`;
+  chainId?: number;
+}
+```
+
+### Bitcoin Wallet
+
+```typescript
+interface WalletAccount {
+  address: string;
+  publicKey: string;  // BTC public key (different from address)
+  chain: {
+    id: string;       // "mainnet" or "testnet"
+    name: string;
+    type: "BTC";
+  };
+  sendTransaction: (tx: BitcoinTransactionRequest) => Promise<string>;
+}
+
+interface BitcoinTransactionRequest {
+  toAddress: string;
+  amount: bigint;
+  options?: {
+    feeRate?: number;
+    memo?: string;
+    memos?: string[];
+  };
+}
+```
+
+### Solana Wallet
+
+```typescript
+interface WalletAccount {
+  address: string;
+  publicKey: string;
+  chain: {
+    id: string;
+    name: string;
+    type: "Solana";
+  };
+  sendTransaction: (tx: unknown) => Promise<string>;
+}
+```
+
+### Integration Examples
+
+#### With wagmi (EVM)
+
+```tsx
+import { useAccount, useSendTransaction, useChainId, useSwitchChain } from "wagmi";
+import { SwapWidget } from "otx-swap";
+import type { ExternalWalletClient, EvmTransactionRequest } from "otx-swap";
+
+function SwapWithWagmi() {
+  const { address, isConnected } = useAccount();
+  const chainId = useChainId();
+  const { sendTransactionAsync } = useSendTransaction();
+  const { switchChainAsync } = useSwitchChain();
+
+  const walletClient: ExternalWalletClient = {
+    evm: isConnected && address ? {
+      address,
+      publicKey: address,
+      chain: { id: chainId, name: "Ethereum", type: "EVM" },
+      sendTransaction: async (tx: unknown) => {
+        const evmTx = tx as EvmTransactionRequest;
+        return sendTransactionAsync({
+          to: evmTx.to,
+          value: evmTx.value,
+          data: evmTx.data,
+        });
       },
-      // other options...
+      getChainId: async () => chainId,
+      switchChain: async (id) => {
+        await switchChainAsync({ chainId: id });
+      },
+    } : undefined,
+  };
+
+  return (
+    <SwapWidget
+      apiBaseUrl="https://api.optimex.io"
+      walletClient={walletClient}
+    />
+  );
+}
+```
+
+#### With Unisat (Bitcoin)
+
+```tsx
+import { SwapWidget } from "otx-swap";
+import type { ExternalWalletClient, BitcoinTransactionRequest } from "otx-swap";
+
+function SwapWithUnisat() {
+  const [btcAddress, setBtcAddress] = useState<string | null>(null);
+  const [btcPublicKey, setBtcPublicKey] = useState<string | null>(null);
+
+  const connectUnisat = async () => {
+    const unisat = (window as any).unisat;
+    const accounts = await unisat.requestAccounts();
+    const pubKey = await unisat.getPublicKey();
+    setBtcAddress(accounts[0]);
+    setBtcPublicKey(pubKey);
+  };
+
+  const walletClient: ExternalWalletClient = {
+    btc: btcAddress && btcPublicKey ? {
+      address: btcAddress,
+      publicKey: btcPublicKey,
+      chain: { id: "mainnet", name: "Bitcoin", type: "BTC" },
+      sendTransaction: async (tx: unknown) => {
+        const btcTx = tx as BitcoinTransactionRequest;
+        const unisat = (window as any).unisat;
+        return unisat.sendBitcoin(btcTx.toAddress, Number(btcTx.amount));
+      },
+    } : undefined,
+  };
+
+  return (
+    <SwapWidget
+      apiBaseUrl="https://api.optimex.io"
+      walletClient={walletClient}
+      onRequestWallet={() => connectUnisat()}
+    />
+  );
+}
+```
+
+## Theming
+
+Customize the widget appearance with the `theme` prop:
+
+```tsx
+<SwapWidget
+  apiBaseUrl="https://api.optimex.io"
+  walletClient={walletClient}
+  theme={{
+    colors: {
+      primary: "#3B82F6",
+      primaryHover: "#2563EB",
+      background: "#0F172A",
+      surface: "#1E293B",
+      surfaceHover: "#334155",
+      text: "#F8FAFC",
+      textSecondary: "#94A3B8",
+      border: "#334155",
+      success: "#22C55E",
+      error: "#EF4444",
+      warning: "#F59E0B",
     },
-  },
-])
+    borderRadius: "md", // "none" | "sm" | "md" | "lg" | "full"
+    fontFamily: "Inter, sans-serif",
+  }}
+/>
+```
+
+### Theme Colors
+
+| Color | Description |
+|-------|-------------|
+| `primary` | Primary action color (buttons, links) |
+| `primaryHover` | Primary color on hover |
+| `secondary` | Secondary accent color |
+| `background` | Widget background color |
+| `surface` | Card/panel background color |
+| `surfaceHover` | Surface color on hover |
+| `text` | Primary text color |
+| `textSecondary` | Secondary/muted text color |
+| `border` | Border color |
+| `success` | Success state color |
+| `error` | Error state color |
+| `warning` | Warning state color |
+
+## Custom Components
+
+### Custom Loading Component
+
+```tsx
+import { SwapWidget } from "otx-swap";
+import type { CustomLoadingProps } from "otx-swap";
+
+function MyLoadingSpinner({ className }: CustomLoadingProps) {
+  return (
+    <div className={className}>
+      <span>Loading...</span>
+    </div>
+  );
+}
+
+<SwapWidget
+  apiBaseUrl="https://api.optimex.io"
+  walletClient={walletClient}
+  renderLoading={MyLoadingSpinner}
+/>
+```
+
+### Custom Error Component
+
+```tsx
+import type { CustomErrorProps } from "otx-swap";
+
+function MyErrorComponent({ error, onRetry, className }: CustomErrorProps) {
+  return (
+    <div className={className}>
+      <p>Error: {error?.message}</p>
+      <button onClick={onRetry}>Retry</button>
+    </div>
+  );
+}
+
+<SwapWidget
+  apiBaseUrl="https://api.optimex.io"
+  walletClient={walletClient}
+  renderError={MyErrorComponent}
+/>
+```
+
+## Standalone Components
+
+The widget also exports standalone components for custom layouts:
+
+```tsx
+import { SwapCard, ConnectButton, useWallet } from "otx-swap";
+
+// Use ConnectButton separately
+<ConnectButton
+  connectLabel="Connect Wallet"
+  showNetworkBadge={true}
+  onClick={() => {
+    // Custom connect logic
+  }}
+/>
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  SwapWidgetProps,
+  ExternalWalletClient,
+  WalletAccount,
+  EvmWalletAccount,
+  EvmTransactionRequest,
+  BitcoinTransactionRequest,
+  ChainInfo,
+  Token,
+  Quote,
+  Trade,
+  TradeState,
+  NetworkType,
+  ThemeConfig,
+  PartialThemeConfig,
+  ThemeColors,
+  QuoteCallbackData,
+  WalletTxCallbackData,
+  SubmitTxCallbackData,
+  SwapCompleteCallbackData,
+  SwapErrorCallbackData,
+  SwapCallbacks,
+} from "otx-swap";
 ```
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 75+
+- Safari 13+
+- Edge 80+
+
+## License
+
+MIT