npm package: @swipelux/onramp-js
Description: Vanilla JavaScript SDK for integrating the Swipelux On-Ramp Widget into any web application.
Latest version: 1.0.6

# @swipelux/onramp-js

Vanilla JavaScript SDK for integrating the Swipelux On-Ramp Widget into any web application.

## Installation

```bash
npm install @swipelux/onramp-js
# or
yarn add @swipelux/onramp-js
# or
pnpm add @swipelux/onramp-js
```

## Usage

### Web Component

The SDK provides a Web Component that you can use directly in your HTML:

```html
<swipelux-widget
  api-key="your_api_key"
  widget-url="https://app.swipelux.com"
></swipelux-widget>
```

### JavaScript API

You can also use the JavaScript API to programmatically control the widget:

```javascript
import { SwipeluxWidget } from '@swipelux/onramp-js';

const widget = new SwipeluxWidget({
  apiKey: 'your_api_key',
  widgetUrl: 'https://app.swipelux.com', // optional
});

// Initialize the widget
sdk.mount(document.getElementById('swipelux-widget'));

// Unmount when done
sdk.unmount();
```

## Configuration

### Required Settings

- `apiKey`: Your Swipelux API key in UUID format (e.g., "123e4567-e89b-12d3-a456-426655440000")

### Optional Settings

- `widgetUrl`: URL where the widget is hosted
  - Default: "https://app.swipelux.com"
  - Use "https://app.dev.swipelux.com" for development environment

- `orderToken`: Order token for prepared orders (e.g., "ord_123xyz")

- `paymentChannel`: Preferred payment method
  - Options: "CARD_PAYMENT" | "WIRE_TRANSFER" | "APPLE_PAY" | "SKRILL"

- `availablePayCurrency`: Available payment currency code (e.g., "USD")

- `availableReceiveCurrency`: Available receive currency configuration
  - Simple format: "BTC", "ETH", etc.
  - Extended format: { code: string, protocol?: string }

- `smartContractData`: Smart contract configuration for NFT purchases
  - Properties:
    - `imgUrl`: Image URL for the smart contract
    - `name`: Name of the smart contract
    - Additional custom properties supported

- `defaultValues`: Pre-filled form values with editability control
  - `targetAddress`: Crypto wallet address
  - `phone`: Phone number
  - `email`: Email address
  - `fiatAmount`: Initial fiat amount

- `colors`: Theme color customization
  - `main`: Primary color
  - `background`: Background color
  - `processing`: Processing state color
  - `warning`: Warning state color
  - `success`: Success state color
  - `link`: Link color

- `externalId`: External reference ID
  - String value or async function returning a string

- `signature`: Branding signature configuration
  - `text`: Signature text
  - `logoUrl`: Logo image URL
  - `href`: Link URL

- `forceNewTransaction`: Force creation of a new transaction
  - Default: false

- `closeOnSuccess`: Automatically close widget after successful transaction
  - Default: false

## Web Component Attributes

When using the web component, attributes should be in kebab-case:

```html
<swipelux-widget
  api-key="your_api_key"
  widget-url="https://app.swipelux.com"
></swipelux-widget>
```

## Browser Support

This SDK uses Web Components and requires modern browser support. It works in all major browsers:

- Chrome/Chromium (and derivatives)
- Firefox
- Safari
- Edge

## Development

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Development with watch mode
pnpm dev

# Lint the code
pnpm lint
```

## TypeScript Support

This package includes TypeScript definitions and can be used in TypeScript projects without additional configuration.

## License

MIT

---

For more information, visit [Swipelux Documentation](https://docs.swipelux.com).