npm package: @swapper-finance/deposit-sdk
Description: Easy iframe embedding for Swapper deposit widget with full TypeScript support
Latest version: 0.2.12

# @swapper-finance/deposit-sdk

Easy iframe embedding SDK for the Swapper Finance deposit widget with full TypeScript support.

<div align="center">
  <img src="http://swapper.finance/assets/widget/ui.png" alt="Swapper Widget" height="400px">
</div>

The SDK provides two integration options: **iframe embedding** for seamless integration into your application, and **modal popup** for a focused user experience. Both options support full customization and TypeScript types.


## Installation

```bash
npm install @swapper-finance/deposit-sdk
```

## Quick Start

### Option 1: Embed in Container

```typescript
import { SwapperIframe } from '@swapper-finance/deposit-sdk';

// Create and mount the iframe
const swapper = new SwapperIframe({
  container: '#swapper-container', // or pass an HTMLElement
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});
```

### Option 2: Open in Modal Popup

```typescript
import { openSwapperModal } from '@swapper-finance/deposit-sdk';

// Open in a centered modal with backdrop
const modal = openSwapperModal({
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});

// Close programmatically if needed
// modal.close();
```

## Configuration Options

### Required Parameters

- `integratorId` - Your integrator identifier
- `dstChainId` - Destination chain ID
- `dstTokenAddr` - Destination token address
- `depositWalletAddress` - Wallet address for deposits

### Optional Parameters

#### Styling

The SDK supports a three-tier styling system:

```typescript
const swapper = new SwapperIframe({
  // ... required params
  styles: {
    // Level 1: Theme mode (light or dark)
    themeMode: 'dark',
    
    // Level 2: Brand colors
    brandTheme: {
      primaryColor: '#FF6B35',
      secondaryColor: '#004E89',
    },
    
    // Level 3: Component-specific overrides (highest priority)
    componentStyles: {
      backgroundColor: '#1A1A1A',
      textColor: '#E8E8E8',
      borderRadius: '12px',
      width: '100%',
      primaryButtonBackground: '#FF6B35',
      primaryButtonText: '#FFFFFF',
      // ... more style options
    },
  },
});
```

#### Custom Contract Calls

```typescript
import { ContractCallType } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  // ... required params
  customContractCalls: [
    {
      callType: ContractCallType.CALL,
      target: '0x...',
      value: '0',
      callData: '0x...',
      payload: '0x...'
    },
  ],
});
```

## API Reference

### Constructor

```typescript
new SwapperIframe(options: SwapperIframeOptions)
```

### Methods

#### `mount(container: HTMLElement | string): void`

Mounts the iframe to a container element.

```typescript
swapper.mount('#my-container');
// or
swapper.mount(document.getElementById('my-container'));
```

#### `updateConfig(config: Partial<SwapperConfig>): void`

Updates the configuration dynamically via postMessage.

```typescript
swapper.updateConfig({
  depositWalletAddress: '0xNewAddress...',
  dstChainId: '1',
});
```

#### `updateStyles(styles: SwapperStyles): void`

Updates only the styles.

```typescript
swapper.updateStyles({
  themeMode: 'light',
  brandTheme: {
    primaryColor: '#836FFF',
  },
});
```

#### `updateCustomContractCalls(calls: ContractCall[]): void`

Updates custom contract calls.

```typescript
swapper.updateCustomContractCalls([
  {
    callType: ContractCallType.CALL,
    target: '0x...',
    value: '0',
    callData: '0x...',
    payload: '0x...',
  },
]);
```

#### `getConfig(): SwapperConfig`

Returns the current configuration.

```typescript
const config = swapper.getConfig();
console.log(config.depositWalletAddress);
```

#### `destroy(): void`

Removes the iframe and cleans up event listeners.

```typescript
swapper.destroy();
```

## Widget Events

The widget emits structured events via `postMessage` that you can listen to through the SDK. This lets you react to user actions like completed transactions.

### Event Envelope

Every event posted from the iframe follows this shape:

```typescript
interface SwapperWidgetEvent {
  type: "SWAPPER_EVENT";       // discriminator
  version: "1.0";              // protocol version
  name: WidgetEventName;       // e.g. "transaction_success"
  timestamp: string;           // ISO 8601
  payload: WidgetEventPayload; // event-specific data
}
```

### Listening with `onEvent` (recommended)

The simplest way to listen for widget events is to pass an `onEvent` callback in the config. It receives every event (equivalent to `.on("*", ...)`):

```typescript
import { SwapperIframe, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  container: '#swapper-container',
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
  onEvent: (event) => {
    if (event.type === WidgetEventName.TRANSACTION_SUCCESS) {
      const payload = event.data as TransactionSuccessPayload;
      console.log('Transaction succeeded:', payload.txHash);
    }
  },
});
```

This also works with `openSwapperModal`:

```typescript
import { openSwapperModal, WidgetEventName } from '@swapper-finance/deposit-sdk';

openSwapperModal({
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
  onEvent: (event) => {
    console.log('Widget event:', event.type, event.data);
  },
});
```

### Listening with `on()` / `off()`

For more granular control, you can register handlers on the iframe instance directly:

```typescript
import { SwapperIframe, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

const swapper = new SwapperIframe({
  container: '#swapper-container',
  integratorId: 'your-integrator-id',
  dstChainId: '8453',
  dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
});

// Listen for a specific event
swapper.on(WidgetEventName.TRANSACTION_SUCCESS, (event) => {
  const payload = event.data as TransactionSuccessPayload;
  console.log('Transaction succeeded:', payload.txHash);
  console.log('Deposit option:', payload.depositOption); // "walletDeposit" | "transferCrypto" | "depositWithCash"
});

// Listen for all events with wildcard
swapper.on('*', (event) => {
  console.log('Widget event:', event.type, event.data);
});

// Remove a specific handler
const handler = (event) => { /* ... */ };
swapper.on(WidgetEventName.TRANSACTION_SUCCESS, handler);
swapper.off(WidgetEventName.TRANSACTION_SUCCESS, handler);
```

### Listening with `window.addEventListener`

You can also listen for events directly on the window. Each event is a `MessageEvent` containing a `SwapperWidgetEvent` envelope:

```typescript
import { WIDGET_EVENT_PROTOCOL_VERSION, WidgetEventName } from '@swapper-finance/deposit-sdk';
import type { SwapperWidgetEvent, TransactionSuccessPayload } from '@swapper-finance/deposit-sdk';

window.addEventListener('message', (event: MessageEvent) => {
  if (event.data?.type !== 'SWAPPER_EVENT') return;

  const message = event.data as SwapperWidgetEvent;

  if (message.version !== WIDGET_EVENT_PROTOCOL_VERSION) return;

  if (message.name === WidgetEventName.TRANSACTION_SUCCESS) {
    const payload = message.payload as TransactionSuccessPayload;
    console.log('Tx hash:', payload.txHash);
    console.log('Explorer:', payload.explorerUrl);
  }
});
```

### `TransactionSuccessPayload`

| Field            | Type              | Required | Description                           |
|------------------|-------------------|----------|---------------------------------------|
| `depositOption`  | `DepositFlowType` | Yes      | `"walletDeposit"`, `"transferCrypto"`, or `"depositWithCash"` |
| `txHash`         | `string`          | No       | Transaction hash                      |
| `explorerUrl`    | `string`          | No       | Link to block explorer                |
| `tokenSymbol`    | `string`          | No       | Token symbol (e.g. `"USDC"`)          |
| `tokenAddress`   | `string`          | No       | Token contract address                |
| `chainId`        | `string`          | No       | Chain ID of the transaction           |
| `amountReceived` | `string`          | No       | Amount received                       |

## Modal API Reference

### Opening a Modal

#### Quick Function: `openSwapperModal(options)`

```typescript
import { openSwapperModal } from '@swapper-finance/deposit-sdk';

const modal = openSwapperModal({
  // Required configuration
  integratorId: 'your-id',
  dstChainId: '8453',
  dstTokenAddr: '0x...',
  depositWalletAddress: '0x...',
  
  // Optional: Widget styling
  styles: {
    themeMode: 'light',
  },
  
  // Optional: Modal styling
  modalStyle: {
    overlayColor: 'rgba(0, 0, 0, 0.8)',
    borderRadius: '16px'
  },
  
  // Optional: Callback when closed
  onClose: () => {
    console.log('Modal was closed');
  },
});

// Close programmatically
modal.close();
```

### Modal Options

#### `modalStyle` Configuration

```typescript
interface ModalStyle {
  /**
   * Modal width (default: '450px')
   */
  width?: string;
  
  /**
   * Modal height (default: '560px')
   */
  height?: string;
  
  /**
   * Background overlay color (default: 'rgba(0, 0, 0, 0.7)')
   */
  overlayColor?: string;
  
  /**
   * Modal border radius (default: '16px')
   */
  borderRadius?: string;
  
  /**
   * Z-index for modal (default: 10000)
   */
  zIndex?: number;
  
  /**
   * Show close button (default: false)
   * Set to true to show a close button
   */
  showCloseButton?: boolean;
}
```

### Modal Class Methods

#### `SwapperModal` Class

For more control, use the `SwapperModal` class directly:

```typescript
import { SwapperModal } from '@swapper-finance/deposit-sdk';

// Create modal instance
const modal = new SwapperModal({
  integratorId: 'your-id',
  dstChainId: '8453',
  dstTokenAddr: '0x...',
  depositWalletAddress: '0x...',
  modalStyle: {
    showCloseButton: true, // Optional: show close button
  },
  onClose: () => {
    console.log('Modal closed');
  },
});

// Open modal
modal.open();

// Close modal
modal.close();

// Check if open
if (modal.isModalOpen()) {
  console.log('Modal is open');
}

// Get iframe instance
const iframe = modal.getIframe();

// Destroy completely
modal.destroy();
```

## Available Style Properties

### ComponentStyles

```typescript
interface ComponentStyles {
  // Layout
  backgroundColor?: string;
  borderRadius?: string;
  width?: string;

  // Typography
  textColor?: string;

  // Buttons
  primaryButtonBackground?: string;
  primaryButtonText?: string;
  secondaryButtonBackground?: string;
  secondaryButtonText?: string;
  disabledButtonBackground?: string;
  disabledButtonText?: string;

  // Status colors
  successColor?: string;
  warningColor?: string;
  errorColor?: string;

  // Brand colors
  primaryColor?: string;
  secondaryColor?: string;

  // Additional UI elements
  inputBackground?: string;
  inputBorder?: string;
  cardBackground?: string;
  borderColor?: string;
}
```

## Examples

### Modal Popup Usage

```html
<!DOCTYPE html>
<html>
<head>
  <title>Swapper Modal</title>
</head>
<body>
  <button id="open-modal">Open Swapper</button>
  
  <script type="module">
    import { openSwapperModal } from '@swapper-finance/deposit-sdk';
    
    document.getElementById('open-modal').onclick = () => {
      openSwapperModal({
        integratorId: 'your-integrator-id',
        dstChainId: '8453',
        dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
        modalStyle: {
          width: '600px',
          height: '800px',
        },
        onClose: () => {
          console.log('Modal closed');
        },
      });
    };
  </script>
</body>
</html>
```

### React Example (Embedded)

```tsx
import { useEffect, useRef } from 'react';
import { SwapperIframe } from '@swapper-finance/deposit-sdk';

function SwapperWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  const swapperRef = useRef<SwapperIframe | null>(null);

  useEffect(() => {
    if (containerRef.current && !swapperRef.current) {
      swapperRef.current = new SwapperIframe({
        container: containerRef.current,
        integratorId: 'your-integrator-id',
        dstChainId: '8453',
        dstTokenAddr: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        depositWalletAddress: '0x2A018F2506acaEEE2C10632514Fc5DCa9eE2c28A',
      });
    }

    return () => {
      swapperRef.current?.destroy();
      swapperRef.current = null;
    };
  }, []);

  return <div ref={containerRef} />;
}
```