@payos-inc/payos-wallet-onboard-js/README.md

PayOS Wallet Onboard JavaScript SDK for easy integration of the PayOS onboarding flow.

# PayOS Wallet Onboard JavaScript SDK

The **PayOS Wallet Onboard** JavaScript SDK provides an easy way to integrate the PayOS wallet creation and payment method onboarding flow into your web application.

## Features

- Simple integration with just a few lines of code
- Mounts an iframe-based UI for the PayOS Wallet Onboard flow
- Handles communication between your application and the PayOS Wallet Onboard UI
- Customizable callbacks for success, close, and error events
- Supports different environments (sandbox, production)

## Installation

```bash
npm install @payos-inc/payos-wallet-onboard-js
# or
yarn add @payos-inc/payos-wallet-onboard-js
```

## Usage

### Simple Initialization (Token Only)

```javascript
import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

// Initialize with just the link_session_token
const payOS = PayOSWalletOnboardSDK.init('YOUR_LINK_SESSION_TOKEN');

// The UI is automatically mounted in a default container.
// To remove it later:
// payOS.unmount();
```

### Initialization with Options

```javascript
import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

PayOSWalletOnboardSDK.init({
  token: 'YOUR_LINK_SESSION_TOKEN',
  containerId: 'my-custom-container', // Optional: Specify your own container element ID
  environment: 'sandbox', // 'sandbox' or 'production'
  merchantName: 'Your Merchant Name', // Optional: Displayed in the UI
  onSuccess: (walletUserId) => {
    console.log('PayOS Wallet Onboard successful!', walletUserId);
    // User completed the flow, proceed with walletUserId
  },
  onClose: () => {
    console.log('PayOS Wallet Onboard closed by user.');
    // User closed the iframe before completing
  },
  onError: (error) => {
    console.error('PayOS Wallet Onboard error:', error);
    // Handle errors during the flow
  }
});
```

### Initialization with Container Element

Provide an HTML element or a CSS selector string directly:

```javascript
import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

// Using a selector
PayOSWalletOnboardSDK.init('#payos-container-div', {
  token: 'YOUR_LINK_SESSION_TOKEN',
  // ... other options
});

// Using an HTMLElement
const container = document.getElementById('payos-container-div');
PayOSWalletOnboardSDK.init(container, {
  token: 'YOUR_LINK_SESSION_TOKEN',
  // ... other options
});
```

### Direct Script Inclusion

Include the UMD build from a public CDN:

```html
<!-- Using unpkg CDN -->
<script src="https://unpkg.com/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>

<!-- Or using jsdelivr CDN -->
<script src="https://cdn.jsdelivr.net/npm/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>

<div id="payos-onboard-container"></div>
<script>
  // Use the global PayOSWalletOnboard object
  window.PayOSWalletOnboard.init('#payos-onboard-container', {
    token: 'YOUR_LINK_SESSION_TOKEN',
    onSuccess: (walletUserId) => console.log('Success!', walletUserId),
    onClose: () => console.log('Closed.'),
    onError: (err) => console.error('Error:', err)
  });

  // Or use the simplified initPayOS global
  // window.initPayOS('YOUR_LINK_SESSION_TOKEN', { /* options */ });
</script>
```

## API Reference

### `PayOSWalletOnboardSDK.init(tokenOrOptionsOrContainer, [options])`

Initializes and mounts the PayOS Wallet Onboard flow. Returns a `PayOSWalletOnboardInstance`.

#### Parameters:

- `tokenOrOptionsOrContainer`: Can be one of:
  - A string with the link_session_token
  - A SimpleOptions object with configuration
  - An HTMLElement or selector string for the container
- `options` (optional): When providing a container, this should be SimpleOptions or PayOSWalletOnboardOptions

#### SimpleOptions:

```typescript
interface SimpleOptions {
  token: string;                                  // Required: The link_session_token
  containerId?: string;                           // Optional: ID of container element or create new if not found
  environment?: "sandbox" | "production";         // Optional: Which environment to use
  merchantName?: string;                          // Optional: Display name in the UI
  customBaseUrl?: string;                         // Optional: Override the iframe URL
  onSuccess?: (walletUserId?: string) => void;    // Optional: Called on successful completion
  onClose?: () => void;                           // Optional: Called when user closes 
  onError?: (error: Error) => void;               // Optional: Called when error occurs
}
```

#### Advanced Usage with `PayOSWalletOnboardOptions`:

For more advanced configurations, you can import and use `PayOSWalletOnboardOptions`:

```typescript
import { PayOSWalletOnboard, PayOSWalletOnboardOptions } from '@payos-inc/payos-wallet-onboard-js';

const options: PayOSWalletOnboardOptions = {
  container: '#my-container',
  token: 'YOUR_LINK_SESSION_TOKEN',
  environment: 'sandbox',
  merchantName: 'Your Merchant Name',
  walletUserId: 'optional-existing-user-id',
  height: '600px',                                // Custom iframe height
  onClose: (data) => {                            // More detailed close data
    if (data.success) {
      console.log('Success with ID:', data.walletUserId);
    } else {
      console.log('Closed without completing');
    }
  },
  onError: (error) => console.error(error)
};

const instance = new PayOSWalletOnboard(options);
instance.mount();
```

### `PayOSWalletOnboardInstance`

The object returned by `init()`.

- `mount()`: Mounts or re-mounts the iframe UI.
- `unmount()`: Removes the iframe UI from the DOM.

## Events

The SDK communicates with your application through callbacks:

- `onSuccess`: Called when the user successfully completes the onboarding process with a walletUserId
- `onClose`: Called when the user closes the iframe without completing
- `onError`: Called when an error occurs during the onboarding process

The iframe uses the postMessage API internally with the following message types:
- `PAYOS_LINK_CLOSE`: When the iframe is closed (with success=true/false)
- `PAYOS_LINK_ERROR`: When an error occurs in the iframe

## Browser Support

The SDK is compatible with all modern browsers (Chrome, Firefox, Safari, Edge) that support iframes and the postMessage API.

## License

MIT License - see LICENSE file for details.