npm package: @solo-pay/widget-js
Description: Lightweight, framework-agnostic payment widget for SoloPay
Author: Solo Pay Team
Latest version: 0.1.8

# @solo-pay/widget-js

Lightweight, framework-agnostic payment widget for SoloPay.

## Installation

```bash
npm install @solo-pay/widget-js
# or
yarn add @solo-pay/widget-js
# or
pnpm add @solo-pay/widget-js
```

### CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@solo-pay/widget-js/dist/widget.min.js"></script>
```

## Usage

### Vanilla JavaScript

```javascript
const soloPay = new SoloPay({ publicKey: 'pk_live_xxx' });

soloPay.requestPayment({
  orderId: 'order-123',
  amount: '10',
  tokenAddress: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
  successUrl: 'https://example.com/success',
  failUrl: 'https://example.com/fail',
});
```

### React / Next.js

```tsx
import { SoloPay } from '@solo-pay/widget-js';
import { useEffect, useRef } from 'react';

export default function CheckoutButton() {
  const soloPayRef = useRef<SoloPay | null>(null);

  useEffect(() => {
    soloPayRef.current = new SoloPay({ publicKey: 'pk_live_xxx' });
    return () => soloPayRef.current?.destroy();
  }, []);

  const handlePay = () => {
    soloPayRef.current?.requestPayment(
      {
        orderId: 'order-123',
        amount: '10',
        tokenAddress: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
        successUrl: `${window.location.origin}/success`,
        failUrl: `${window.location.origin}/fail`,
      },
      undefined,
      {
        onClose: () => console.log('Widget closed'),
      }
    );
  };

  return <button onClick={handlePay}>Pay Now</button>;
}
```

> **Note:** For Next.js App Router, add `'use client'` at the top of the file.

## SDK Reference

### `new SoloPay(config)`

| Option      | Type      | Default                         | Description                                                         |
| ----------- | --------- | ------------------------------- | ------------------------------------------------------------------- |
| `publicKey` | `string`  | required                        | Your SoloPay public key                                             |
| `widgetUrl` | `string`  | `https://widget.solonetwork.io` | Widget base URL (no path). SDK uses `/` on mobile, `/pc` on desktop |
| `debug`     | `boolean` | `false`                         | Enable debug logging                                                |

**Behaviour:** PC opens a popup window; mobile redirects to the widget page.

### `soloPay.requestPayment(request, options?)`

Opens the payment widget.

**Parameters:**

- `request` - Payment request object (see below)
- `options` - Optional: `{ onClose?: () => void }`

**Request:**

| Parameter      | Type               | Required | Description             |
| -------------- | ------------------ | -------- | ----------------------- |
| `orderId`      | `string`           | Yes      | Unique order identifier |
| `amount`       | `string \| number` | Yes      | Payment amount          |
| `tokenAddress` | `string`           | Yes      | Token contract address  |
| `successUrl`   | `string`           | Yes      | Redirect URL on success |
| `failUrl`      | `string`           | Yes      | Redirect URL on failure |

**Options:**

| Option    | Type         | Description                              |
| --------- | ------------ | ---------------------------------------- |
| `onClose` | `() => void` | Callback when the widget/popup is closed |

### `soloPay.getWidgetUrl(request)`

Returns the widget URL for custom implementations.

### `soloPay.closeWidget()`

Closes the payment popup if open.

### `soloPay.destroy()`

Destroys the SDK instance and cleans up resources.

## License

MIT