# Onramp Web SDK

A TypeScript/JavaScript SDK for integrating Onramp's crypto purchase widget into your web application.

## Installation

Install the SDK using npm:

```bash
npm install @onramp.money/onramp-web-sdk
```

Or using yarn:

```bash
yarn add @onramp.money/onramp-web-sdk
```

## Quick Start

### 1. Import the SDK

**ES6/TypeScript:**
```javascript
import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';
```

**CommonJS:**
```javascript
const { OnrampWebSDK } = require('@onramp.money/onramp-web-sdk');
```

**Browser (UMD):**
```html
<script src="node_modules/@onramp.money/onramp-web-sdk/dist/onramp-web-sdk.umd.js"></script>
```

### 2. Initialize the SDK

```javascript
const onrampSDK = new OnrampWebSDK({
  appId: YOUR_APP_ID, // Required: Get this from Onramp dashboard
  walletAddress: "0x...", // User's wallet address
  coinCode: "USDT", // Cryptocurrency to purchase
  network: "polygon", // Blockchain network
  fiatAmount: 100, // Amount in fiat currency
});
```

### 3. Show the Widget

```javascript
// Display the widget as an overlay
onrampSDK.show();
```

### 4. Handle Events (Optional)

```javascript
// Listen to transaction events
onrampSDK.on('TX_EVENTS', (event) => {
  console.log('Transaction event:', event);
});

// Listen to widget events
onrampSDK.on('WIDGET_EVENTS', (event) => {
  console.log('Widget event:', event);
});

// Listen to KYC events
onrampSDK.on('KYC_EVENTS', (event) => {
  console.log('KYC event:', event);
});
```

### 5. Close the Widget

```javascript
// Close the widget programmatically
onrampSDK.close();
```

## Usage Examples

### Basic Overlay Mode

```javascript
import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';

const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  coinCode: "USDT",
  network: "polygon",
  fiatAmount: 50
});

// Show widget
onrampSDK.show();

// Handle events
onrampSDK.on('TX_EVENTS', (event) => {
  if (event.type === 'ONRAMP_WIDGET_TX_SUCCESSFUL') {
    console.log('Purchase successful!', event.data);
  }
});
```

### Embedded Mode

```html
<!-- Create a container for the widget -->
<div id="onramp-container" style="width: 100%; height: 600px;"></div>
```

```javascript
const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  containerId: "#onramp-container", // Embed in specific container
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  coinCode: "USDT",
  network: "polygon"
});

onrampSDK.show();
```

### Custom Theming

```javascript
const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  theme: {
    lightMode: {
      baseColor: "#6366f1",
      inputRadius: "8px",
      buttonRadius: "12px"
    },
    darkMode: {
      baseColor: "#4f46e5",
      inputRadius: "8px",
      buttonRadius: "12px"
    },
    default: "lightMode"
  }
});

onrampSDK.show();
```

## Configuration Options

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appId` | number | ✅ | Your application ID from Onramp dashboard |
| `walletAddress` | string | ❌ | User's wallet address |
| `coinCode` | string | ❌ | Cryptocurrency code (e.g., "USDT", "ETH") |
| `network` | string | ❌ | Blockchain network (e.g., "polygon", "ethereum") |
| `fiatAmount` | number | ❌ | Pre-filled fiat amount |
| `coinAmount` | number | ❌ | Pre-filled crypto amount |
| `paymentMethod` | number | ❌ | Preferred payment method ID |
| `flowType` | number | ❌ | 1: Buy, 2: Sell, 3: Checkout, 4: Swap |
| `containerId` | string | ❌ | DOM element ID for embedded mode (e.g., "#container") |
| `theme` | object | ❌ | Custom theme configuration |
| `sandbox` | boolean | ❌ | Use sandbox environment for testing |
| `lang` | string | ❌ | Language code (e.g., "en", "es") |
| `phoneNumber` | string | ❌ | Pre-filled phone number |
| `redirectUrl` | string | ❌ | Redirect URL after completion |

## Flow Types

- **1 (Buy/Onramp)**: Purchase cryptocurrency with fiat
- **2 (Sell/Offramp)**: Sell cryptocurrency for fiat
- **3 (Checkout)**: NFT/asset purchase flow
- **4 (Swap)**: Cryptocurrency swap

## Event Types

### Transaction Events (`TX_EVENTS`)
- `ONRAMP_WIDGET_TX_INITIATED`
- `ONRAMP_WIDGET_TX_SUCCESSFUL`
- `ONRAMP_WIDGET_TX_FAILED`

### Widget Events (`WIDGET_EVENTS`)
- `ONRAMP_WIDGET_READY`
- `ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED`
- `ONRAMP_WIDGET_FAILED`
- `ONRAMP_WIDGET_CONTENT_COPIED`

### KYC Events (`KYC_EVENTS`)
- `ONRAMP_KYC_INITIATED`
- `ONRAMP_KYC_SUCCESSFUL`
- `ONRAMP_KYC_FAILED`

## Methods

### `show()`
Displays the Onramp widget.

```javascript
onrampSDK.show();
```

### `close()`
Closes the Onramp widget.

```javascript
onrampSDK.close();
```

### `on(eventType, callback)`
Registers event listeners.

```javascript
onrampSDK.on('TX_EVENTS', (event) => {
  // Handle transaction events
});
```

## Error Handling

```javascript
try {
  onrampSDK.show();
} catch (error) {
  console.error('Failed to show widget:', error.message);
}

// Handle widget events
onrampSDK.on('WIDGET_EVENTS', (event) => {
  if (event.type === 'ONRAMP_WIDGET_FAILED') {
    console.error('Widget failed:', event.data);
  }
});
```

## Complete Example

```html
<!DOCTYPE html>
<html>
<head>
    <title>Onramp Integration</title>
</head>
<body>
    <button id="buy-crypto">Buy Crypto</button>
    <div id="widget-container" style="width: 100%; height: 600px; display: none;"></div>

    <script src="node_modules/@onramp.money/onramp-web-sdk/dist/onramp-web-sdk.umd.js"></script>
    <script>
        const onrampSDK = new OnrampWebSDK({
            appId: 12345,
            walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
            coinCode: "USDT",
            network: "polygon",
            fiatAmount: 100
        });

        // Show widget on button click
        document.getElementById('buy-crypto').addEventListener('click', () => {
            onrampSDK.show();
        });

        // Handle successful transactions
        onrampSDK.on('TX_EVENTS', (event) => {
            if (event.type === 'ONRAMP_WIDGET_TX_SUCCESSFUL') {
                alert('Purchase successful!');
                onrampSDK.close();
            }
        });

        // Handle widget close
        onrampSDK.on('WIDGET_EVENTS', (event) => {
            if (event.type === 'ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED') {
                console.log('Widget closed by user');
            }
        });
    </script>
</body>
</html>
```

## Support

For questions and support:
- Documentation: [https://docs.onramp.money](https://docs.onramp.money)
- Email: support@onramp.money
- Website: [https://onramp.money](https://onramp.money)

## License

ISC