# @zerohash-sdk/onboarding-react

A React SDK that enables frontend React 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.

## Requirements

- React 18.0.0 or higher
- React DOM 18.0.0 or higher

## Installation

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

## Getting Started

Follow these simple steps to integrate Connect Onboarding into your React application:

### 1. Import the Onboarding Component

```tsx
import { Onboarding } from '@zerohash-sdk/onboarding-react';
```

### 2. Add the Onboarding Component to Your App

```tsx
function App() {
  const jwt = 'your-jwt-token'; // Obtain this from your backend

  return (
    <Onboarding
      jwt={jwt}
      env="prod" // or "cert" for testing
      theme="auto" // 'auto' (default), 'light', or 'dark'
    />
  );
}
```

### 3. Configure Event Callbacks (Optional)

Listen to events from the Onboarding SDK to handle user interactions:

```tsx
function App() {
  const jwt = 'your-jwt-token';

  const handleCompleted = ({ participantCode, kycStatus }) => {
    console.log('Onboarding completed:', participantCode, kycStatus);
  };

  const handleError = ({ errorCode, reason }) => {
    console.log('Onboarding error:', errorCode, 'Reason:', reason);
  };

  const handleClose = () => {
    console.log('Onboarding widget closed');
  };

  const handleEvent = ({ type, data }) => {
    console.log('Onboarding event:', type, 'Data:', data);
  };

  const handleLoaded = () => {
    console.log('Onboarding widget loaded and ready');
  };

  return (
    <Onboarding
      jwt={jwt}
      env="prod"
      theme="auto"
      onCompleted={handleCompleted}
      onError={handleError}
      onClose={handleClose}
      onEvent={handleEvent}
      onLoaded={handleLoaded}
    />
  );
}
```

## Complete Example

```tsx
import { Onboarding } from '@zerohash-sdk/onboarding-react';
import React from 'react';

function App() {
  const jwt = 'your-jwt-token';

  return (
    <div className="App">
      <h1>My App</h1>

      <Onboarding
        jwt={jwt}
        env="prod" // 'prod' (default), 'cert', 'dev', or 'local'
        theme="auto" // 'auto' (default), 'light', or 'dark'
        onCompleted={({ participantCode, kycStatus }) => {
          console.log('Completed:', participantCode, kycStatus);
        }}
        onError={({ errorCode, reason }) => {
          console.log('Error:', errorCode, 'Reason:', reason);
        }}
        onClose={() => {
          console.log('Onboarding widget closed');
        }}
        onEvent={({ type, data }) => {
          console.log('Event type:', type, 'Event data:', data);
        }}
        onLoaded={() => {
          console.log('Onboarding widget loaded and ready');
        }}
      />
    </div>
  );
}

export default App;
```

## API Reference

### Onboarding Component Props

| 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    |

> **`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.

## JWT & token renewal

The `jwt` prop is what the widget uses to authenticate.

**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 pass it
as the `jwt` prop.

## More Information & Support

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