# @zerohash-sdk/onboarding-js

A JavaScript SDK that enables frontend applications to seamlessly integrate with the Connect Onboarding product.

Connect Onboarding provides a secure, customizable KYC/onboarding flow for new users directly within your application.

## Installation

### Via NPM (recommended)

```bash
npm install @zerohash-sdk/onboarding-js
```

```javascript
import { Onboarding } from '@zerohash-sdk/onboarding-js';
```

### Via CDN

```html
<script
  type="module"
  src="https://sdk-cdn.zerohash.com/onboarding-web/index.js"
></script>
```

Or import directly in your JavaScript code:

```javascript
import { Onboarding } from 'https://sdk-cdn.zerohash.com/onboarding-web/index.js';
```

## Getting Started

### 1. Import the Onboarding module

```javascript
import { Onboarding } from '@zerohash-sdk/onboarding-js';
```

### 1.1 Or import via CDN

```javascript
import { Onboarding } from 'https://sdk-cdn.zerohash.com/onboarding-web/index.js';
```

### 2. Initialize and render the widget

```javascript
const onboarding = new Onboarding({
  jwt: 'your-jwt-token', // Obtain this from your backend
  env: 'prod', // or 'cert' for testing
  theme: 'auto', // 'auto' (default), 'light', or 'dark'
  onCompleted: ({ participantCode, kycStatus }) => {
    console.log('Onboarding completed:', participantCode, kycStatus);
  },
  onError: ({ errorCode, reason }) => {
    console.error('Onboarding error:', errorCode, 'Reason:', reason);
  },
  onClose: () => {
    console.log('Onboarding widget closed');
  },
  onEvent: ({ type, data }) => {
    console.log('Event received:', type, data);
  },
  onLoaded: () => {
    console.log('Onboarding widget loaded and ready');
  },
});

const container = document.getElementById('onboarding-container');
await onboarding.render(container);

// Update configuration dynamically
onboarding.updateConfig({ jwt: 'new-jwt-token' });

// Check if rendered
if (onboarding.isRendered()) {
  console.log('Widget is active');
}

// Clean up when done
onboarding.destroy();
```

### 2.1 Using TypeScript (optional)

```typescript
import { Onboarding, OnboardingConfig } from '@zerohash-sdk/onboarding-js';

const config: OnboardingConfig = {
  jwt: 'your-jwt-token',
  env: 'cert',
  theme: 'dark',
  onCompleted: ({ participantCode, kycStatus }) => {
    console.log(participantCode, kycStatus);
  },
  onError: ({ errorCode, reason }) => {
    console.error(errorCode, reason);
  },
};

const onboarding = new Onboarding(config);
await onboarding.render(document.getElementById('onboarding-container')!);
```

## API Reference

### Configuration

| Prop          | Type                                       | Required | Default  | Description                                     |
| ------------- | ------------------------------------------ | -------- | -------- | ----------------------------------------------- |
| `jwt`         | `string`                                   | Yes      | -        | JWT token for authentication with Connect       |
| `env`         | `"prod" \| "cert" \| "dev" \| "local"`     | No       | `"prod"` | Target environment                              |
| `theme`       | `"auto" \| "light" \| "dark"`              | No       | `"auto"` | Theme mode for the interface                    |
| `onCompleted` | `({ participantCode, kycStatus }) => void` | No       | -        | Callback when onboarding completes successfully |
| `onError`     | `({ errorCode, reason }) => void`          | No       | -        | Callback for error events                       |
| `onClose`     | `() => void`                               | No       | -        | Callback when the widget is closed              |
| `onEvent`     | `({ type, data }) => void`                 | No       | -        | Callback for general events                     |
| `onLoaded`    | `() => void`                               | No       | -        | Callback when the widget is loaded and ready    |

### Constructor

```javascript
new Onboarding(config: OnboardingConfig)
```

### Methods

#### `render(container: HTMLElement): Promise<void>`

```javascript
await onboarding.render(document.getElementById('onboarding-container'));
```

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

```javascript
onboarding.updateConfig({ jwt: 'new-token' });
```

#### `destroy(): void`

```javascript
onboarding.destroy();
```

#### `isRendered(): boolean`

```javascript
if (onboarding.isRendered()) {
  /* Widget is active */
}
```

#### `getConfig(): OnboardingConfig`

```javascript
const config = onboarding.getConfig();
```

## Callback Functions

### onCompleted

```javascript
onCompleted: ({ participantCode, kycStatus }) => {
  // participantCode: Unique participant identifier
  // kycStatus: KYC verification status string
};
```

> **`onboardingFlow: "tax_only"`:** no KYC runs in this flow. `onCompleted` fires once the tax
> certification is saved, with the participant's existing KYC status when it is known, otherwise
> `kycStatus: "UNKNOWN"`. Don't treat it as a new KYC result.

### onError

```javascript
onError: ({ errorCode, reason }) => {
  // errorCode: 'network_error' | 'auth_error' | 'server_error' | etc.
  // reason: Human-readable error description
};
```

### onClose

```javascript
onClose: () => {
  /* Handle close event */
};
```

### onEvent

```javascript
onEvent: ({ type, data }) => {
  // type: Event type string
  // data: Event-specific data object
};
```

### onLoaded

```javascript
onLoaded: () => {
  /* Widget is fully loaded and ready */
};
```

## JWT & token renewal

The `jwt` you pass is what the widget uses to authenticate (`updateConfig({ jwt })`
is the JS-SDK equivalent of `setJWT`).

**The SDK does not support refresh tokens.** It does not renew or re-authenticate
a token on its own — there is no built-in token-refresh mechanism. Token renewal
is handled entirely by the host: obtain a new JWT from your backend and provide
it to the SDK the same way you provided the initial one.

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- All modern browsers with Web Components support

## More Information & Support

For comprehensive documentation or support about Connect, visit our [Documentation Page](https://docs.zerohash.com/).