# @socket.tech/bungee

Below it will show you how to integrate the `@socket.tech/bungee` package into a React application with RainbowKit for wallet connection.

## What is Bungee?

Bungee is a swap and bridge widget that enables users to swap tokens across different blockchains. The `@socket.tech/bungee` package provides a React component that can be easily integrated into any web application.

- Live Product: [bungee.exchange](https://bungee.exchange/)
- NPM Package: [@socket.tech/bungee](https://www.npmjs.com/package/@socket.tech/bungee)
- Documentation: [docs.bungee.exchange](https://docs.bungee.exchange)

## Installation & Setup

### 1. Install Dependencies

The Bungee package requires several peer dependencies that you must install manually:

```bash
pnpm install @socket.tech/bungee react react-dom wagmi viem @tanstack/react-query @solana/wallet-adapter-react
```

> Note: Peer dependencies are NOT automatically installed. You must install them explicitly in your project.

### 2. Import Required CSS

Add the Bungee styles to your application:

```tsx
import "@socket.tech/bungee/styles.css";
import "@socket.tech/bungee/fonts.css";
```

### 3. Basic Usage

```tsx
import { Bungee, type BungeeConfig } from "@socket.tech/bungee";

const config: BungeeConfig = {
  apiKey: "your-api-key-here",
};

export default function App() {
  return <Bungee config={config} />;
}
```

## Configuration Reference

### BungeeConfig Interface

The `BungeeConfig` interface provides extensive customization options:

#### Required Properties

- `apiKey` (string): Your Bungee API key

#### Optional Properties

- `affiliateId` (string): For integrator tracking
- `baseUrl` (string): Custom API base URL. Defaults to public api
- `theme` (Theme): Theming configuration
- `rpcs` (object): Custom RPC URLs
  - `solana` (string): Solana RPC URL
  - `eip155` (string): Ethereum Mainnet RPC URL to use for transactions. Integrators can provide custom RPC endpoints (e.g., QuickNode, Alchemy) for benefits such as faster transaction processing, better analytics, rate limits, or other infrastructure requirements.
- `initialValues` (object): Default values
  - `fromChain` (number): Default source chain ID
  - `toChain` (number): Default destination chain ID
  - `inputTokens` (string[]): Default input token addresses
  - `outputTokens` (string[]): Default output token addresses
  - `amount` (string[]): Default amounts
  - `outputRatio` (number[]): Output ratios
  - `locale` (SupportedLocale): UI locale (currently only "en-US")
  - `sortPreference` ("fast" | "best"): Route sorting preference
  - `swapSlippage` (number): Default slippage tolerance
- `supportedTokens` (object): Restrict available tokens
  - `from` (object): Tokens by chain ID for source
  - `to` (object): Tokens by chain ID for destination
- `supportedChains` (object): Restrict available chains
  - `from` (number[]): Available source chains
  - `to` (number[]): Available destination chains
- `eventHandlers` (EventHandlers): Event callbacks
- `features` (object): Feature flags
  - `internalToasts` (boolean): Show/hide internal toasts (default: true)
  - `internalTxHistory` (boolean): Show/hide transaction history (default: true)
  - `autoRouting` (boolean): Auto-routing feature (not implemented)
  - `refuel` (boolean): Refuel feature (not implemented)

### Theme Configuration

Customize the widget appearance with the `theme` property:

```tsx
const theme = {
  width: 420, // or "full" for full width
  borderRadius: "base", // "none" | "sm" | "base" | "md" | "lg"
  fonts: {
    primary: "Inter, sans-serif",
    secondary: "Roboto, sans-serif"
  },
  colors: {
    text: {
      primary: "#FFFFFF",
      secondary: "#A0A0A0",
      button: "#000000",
      theme: "#3B82F6",
      accent1: "#10B981",
      accent2: "#F59E0B",
      accent3: "#EF4444",
      accent4: "#8B5CF6"
    },
    bg: {
      layer1: "#1F2937",
      layer2: "#374151",
      layer3: "#4B5563",
      accent1: "#10B981",
      accent3: "#EF4444",
      accent4: "#8B5CF6",
      main: "#111827",
      theme: "#3B82F6"
    },
    border: {
      strong: "#6B7280",
      theme: "#3B82F6"
    },
    icon: {
      primary: "#FFFFFF",
      secondary: "#A0A0A0",
      theme: "#3B82F6"
    }
  }
};
```

Color Format Support: Colors support both hex (`#FFFFFF`) and RGB (`rgb(255, 255, 255)`) formats.

### Event Handlers

Handle user interactions and widget events:

```tsx
const eventHandlers = {
  onFromTokenChange: (token: Token) => {
    console.log("Source token changed:", token);
  },
  onToTokenChange: (token: Token) => {
    console.log("Destination token changed:", token);
  },
  onFromChainChange: (chain: Chain) => {
    console.log("Source chain changed:", chain);
  },
  onToChainChange: (chain: Chain) => {
    console.log("Destination chain changed:", chain);
  },
  onEvent: (eventType: "success" | "error" | "warning", eventData: EventData) => {
    console.log("Widget event:", eventType, eventData);
  },
  onOpenWalletConnect: (network: "solana" | "eip155") => {
    // Open your custom wallet connection modal
    openWalletModal(network);
  },
  onSwapInitiated: (data: { chainId: number; hash: string; type: OrderFlowType }) => {
    console.log("Swap initiated:", data);
  },
  logEvent: (log: { event: Event; error: unknown; context?: Record<string, unknown> }) => {
    // Handle analytics and error logging
    console.log("Analytics event:", log);
  }
};
```

### Imperative API

The imperative API is used for **external controls**, allowing parent components to interact with the widget components programmatically. This enables you to control the widget's state and behavior from outside the widget itself.

**Use Case Example**: In the Bungee app, when you click on a history item in the sidebar, it opens the inflight screen in the widget. This interaction is facilitated by the imperative API, where the parent sidebar component communicates with the widget to navigate to a specific screen.

```tsx
import { useRef } from "react";
import { Bungee, type BungeeImperativeAPIType } from "@socket.tech/bungee";

export default function App() {
  const bungeeRef = useRef<BungeeImperativeAPIType>(null);

  const handleSetInflightData = (data: OrderData) => {
    // Parent component can control widget state externally
    bungeeRef.current?.setInflightData(data);
  };

  return <Bungee config={config} ref={bungeeRef} />;
}
```

Available Methods:
- `setInflightData(data: OrderData)`: Track pending transactions and navigate to inflight screen

### Type Exports

The package exports several TypeScript types:

```tsx
import type {
  BungeeConfig,
  BungeeImperativeAPIType,
  Token,
  Chain
} from "@socket.tech/bungee";
```

## Links

- Web App: [bungee.exchange](https://bungee.exchange/)
- Bungee Lite Package: [@socket.tech/bungee](https://www.npmjs.com/package/@socket.tech/bungee)
- Bungee Protocol Docs: [docs.bungee.exchange/](https://docs.bungee.exchange)