> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worthai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

## createOnboardingApp

API reference for all Onboarding SDK methods, types, and options.

### Import

```typescript theme={null}
import { createOnboardingApp } from '@worthai/onboarding-sdk';
```

### Parameters

The function accepts a single argument object with the following properties:

| Property          | Type                                        | Description                                                                                                                                                        |
| ----------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `origin`          | `string`                                    | The origin URL of the onboarding app                                                                                                                               |
| `inviteToken`     | `string`                                    | The invite token used to authenticate and initialize the onboarding session                                                                                        |
| `mode?`           | `'embedded' \| 'non-embedded' \| undefined` | The iframe mode. When set to `'embedded'`, the iframe is embedded in the parent site. When `'non-embedded'` or `undefined`, the iframe operates in standalone mode |
| `loadingTimeout?` | `number`                                    | Loading timeout in milliseconds. The minimum allowed value is 15000 ms                                                                                             |

### Example

```typescript theme={null}
import { createOnboardingApp } from '@joinworth/onboarding-sdk';

const onboardingApp = createOnboardingApp({
  origin: '{{WORTH_ONBOARDING_APP_DOMAIN}}',
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  mode: 'embedded',
});
```

### Returned Methods

The `createOnboardingApp` function returns an object with the following methods and properties:

#### `subscribe(callback)`

Subscribes to messages from the Worth Onboarding App. Returns a subscription object with an `unsubscribe` method.

**Parameters:**

* `callback: (event: MessageEvent<OnboardingAppMessage>) => void` - A callback function that receives message events from the Worth Onboarding App

**Returns:**

* `{ unsubscribe: () => void }` - A subscription object with an `unsubscribe` method to stop listening to messages

**Example:**

```typescript theme={null}
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'ROUTE_URL') {
    console.log('Current route:', event.data.payload.url);
  }
});

// Clean up when done
subscription.unsubscribe();
```

**Message Types Received:**

* `ROUTE_URL` - Notifies when the route changes in the onboarding app
* `IFRAME_RESIZE` - Notifies when the iframe needs to resize (includes height)
* `IFRAME_INITIALIZED` - Notifies when the iframe has finished initializing
* `ONBOARDING_STARTED` - Signals that the onboarding flow is ready; the parent clears the loading state and the SDK initializes the detached iframe.
* `STAGE_NAVIGATION` - Updates as the user moves through stage. With this event that the parent receives it, updates navigation, and re-renders the buttons and labels accordingly. See more details about [how this message type is handled](#handling-stage_navigation-message-type).
* `LOADING_TIMED_OUT` - Fired when the onboarding app does not load within the configured time limit. This event requires the `loadingTimeout` option to be set when creating the `createOnboardingApp` instance. Fallback event to hide loading state.
* `RESTARTING` - Fired when the onboarding app is restarted after `LOADING_TIMED_OUT`.
* `AUTHENTICATION_STATUS` - Notifies when the onboarding app's `isAuthenticated` state changes.
* `ONBOARDING_COMPLETED` - Fired when the full onboarding is submitted.
* `ERROR` - Handles ERROR events from the onboarding SDK subscription.
  See more details about [how this message type is handled](#handling-error-message-type).

***

#### Handling STAGE\_NAVIGATION message type

Drives navigation actions, and the SDK app responds with the new navigation state and stage metadata.

```typescript theme={null}
// Object definition
export type StageNavigation = {
  isInitialStage: boolean;
  isLastStage: boolean;
  stage: string | undefined;
  nextStatus: {
    visible: boolean;
    disabled: boolean;
    loading: boolean;
    isSubmit: boolean;
  };
  prevStatus: { visible: boolean; disabled: boolean; loading: boolean };
  skipStatus: { visible: boolean; disabled: boolean; loading: boolean };
};
```

##### Field‑by‑field semantics

* ***isInitialStage:*** true when the current stage is the very first step of the flow.
  The parent uses this to decide that “Back” should leave the flow entirely instead of going to a previous stage.
* ***isLastStage:*** true when the current stage is the final step.
  The parent uses this to change both behavior (navigate to a “completed” route instead of NEXT\_STAGE) and label (“Complete” vs “Next”).
* ***stage:*** A logical identifier for the current stage (e.g. "personal-info", "documents", etc.).
  In your parent UI it’s currently just displayed for observability / debugging.
* ***nextStatus:*** controls the Next/Complete button
* ***visible:*** whether the Next/Complete button should be rendered at all.
* ***disabled:*** whether the button is clickable (e.g. when validation not satisfied).
* ***loading:*** whether the action is in progress (you could map this to a spinner on the button if desired).
* ***isSubmit:*** the child is telling you “this click actually submits data / form”, even if it’s not the very last stage. You could use this to show different copy or confirmation.
* ***prevStatus:*** controls the Back button
  Same idea: visible, disabled, loading communicate whether Back should be shown and usable.
* ***skipStatus:*** controls the Skip button
  Same structure:\*\*\* visible, disabled, loading, telling you whether skipping is allowed on this particular stage.

**Example:** How the parent consumes STAGE\_NAVIGATION.
The parent subscribes to SDK events and stores stageNavigation into local state:

```typescript theme={null}
// Get Button Inner Elements
const prevButton = document.getElementById('prev-btn');

const skipButton = document.getElementById('skip-btn');

const nextButton = document.getElementById('next-btn');

// Listen for onboarding messages
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'STAGE_NAVIGATION') {
    console.log('Current stage:', event.data.payload.stageNavigation);
    const stageNavigation = event.data.payload.stageNavigation;

    // Set prev button disabled state based on stageNavigation event
    if (prevButton) {
      prevButton.disabled = stageNavigation.prevStatus.disabled;
    }

    // Set skip button disabled state based on stageNavigation event
    if (skipButton) {
      skipButton.disabled = stageNavigation.skipStatus.disabled;
    }

    // Set next button disabled state based on stageNavigation event
    if (nextButton) {
      nextButton.disabled = stageNavigation.nextStatus.disabled;
    }
  }
});

// Get the current stage navigation
const navigation = onboardingApp.navigation();

/** Prev button handler **/

// That navigation object (of type StageNavigation)
// then directly drives your buttons:
prevButton?.addEventListener('click', () => {
  if (navigation?.isInitialStage) {
    // HERE: implement code to back to home or previous page
    window.location.href = '/';
  } else {
    onboardingApp.prev();
  }
});

/** Skip button handler **/
skipButton?.addEventListener('click', () => {
  onboardingApp.skip();
});

/** Next button handler **/
nextButton?.addEventListener('click', () => {
  if (navigation?.isLastStage) {
    // HERE: implement code to navigate into onboarding-completed page
    // or custom redirection
    window.location.href = '../onboarding-completed';
  } else {
    onboardingApp.next();
  }
});
```

***

#### Handling ERROR message type

Extracts the error message and displays it via notification UI component.

```typescript theme={null}
// Listen for onboarding messages
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'ERROR') {
    const message = event.data.payload.error.message;

    // Show error message into your Notification UI Component
    alert(`Error Title: ${message}`);
  }
});
```

***

#### `setMode(mode)`

Sets the iframe mode to control how the onboarding app is displayed. Sends a `SET_IFRAME_MODE` message to the Worth Onboarding App.

**Parameters:**

* `mode: 'embedded' | 'non-embedded' | undefined` - The mode to set
  * `'embedded'` - The iframe is embedded within the parent site's layout
  * `'non-embedded'` - The iframe is displayed in standalone mode
  * `undefined` - Uses as default `non-embedded` mode

**Returns:** `void`

**Example:**

```typescript theme={null}
// Switch to embedded mode
onboardingApp.setMode('embedded');

// Switch to non-embedded mode
onboardingApp.setMode('non-embedded');

// Toggle mode based on checkbox
const modeToggle = document.getElementById('mode-toggle');
modeToggle?.addEventListener('change', (event) => {
  const isEmbedded = (event.target as HTMLInputElement).checked;
  onboardingApp.setMode(isEmbedded ? 'embedded' : 'non-embedded');
});
```

***

#### `next()`

Navigates the onboarding app to the next stage. Sends a `NEXT_STAGE` message to the Worth Onboarding App.

**Parameters:** None

**Returns:** `void`

**Example:**

```typescript theme={null}
const nextButton = document.getElementById('next-btn');
nextButton?.addEventListener('click', () => {
  onboardingApp.next();
});
```

***

#### `prev()`

Navigates the onboarding app to the previous stage. Sends a `PREV_STAGE` message to the Worth Onboarding App.

**Parameters:** None

**Returns:** `void`

**Example:**

```typescript theme={null}
const prevButton = document.getElementById('prev-btn');
prevButton?.addEventListener('click', () => {
  onboardingApp.prev();
});
```

#### `skip()`

Skips the current onboarding app stage. Sends a `SKIP_STAGE` message to the Worth Onboarding App.

**Parameters:** None

**Returns:** `void`

**Example:**

```typescript theme={null}
const prevButton = document.getElementById('prev-btn');
prevButton?.addEventListener('click', () => {
  onboardingApp.prev();
});
```

***

#### `setCustomCss(css)`

Injects custom CSS styles into the Worth Onboarding App iframe. Sends a `SET_CUSTOM_CSS` message to the Worth Onboarding App.

**Parameters:**

* `css: string` - A string containing CSS rules to apply to the Worth Onboarding App

**Returns:** `void`

**Example:**

```typescript theme={null}
// Apply custom background color
onboardingApp.setCustomCss('body { background: #f0f0f0; }');

// Apply multiple styles
onboardingApp.setCustomCss(`
  body {
    background: #ffffff;
    font-family: 'Custom Font', sans-serif;
  }
  .onboarding-container {
    padding: 20px;
    border-radius: 8px;
  }
`);

// Dynamic CSS based on user preference
const themeToggle = document.getElementById('theme-toggle');
themeToggle?.addEventListener('change', (event) => {
  const isDark = (event.target as HTMLInputElement).checked;
  onboardingApp.setCustomCss(
    isDark
      ? 'body { background: #1a1a1a; color: #ffffff; }'
      : 'body { background: #ffffff; color: #000000; }',
  );
});
```

***

#### `refreshSize()`

Requests the Worth Onboarding App to recalculate and report its size. This is useful when the iframe content changes dynamically. Sends a `REFRESH_SIZE` message to the Worth Onboarding App.

**Parameters:** None

**Returns:** `void`

**Example:**

```typescript theme={null}
// Refresh size after content changes
onboardingApp.refreshSize();

// Refresh size on window resize
window.addEventListener('resize', () => {
  onboardingApp.refreshSize();
});

// Refresh size on button click
const refreshButton = document.getElementById('refresh-size-btn');
refreshButton?.addEventListener('click', () => {
  onboardingApp.refreshSize();
});
```

***

#### `iframe`

A read-only property that contains the Worth Onboarding App. This is the actual iframe DOM element that should be appended to your page.

**Type:** `HTMLIFrameElement`

**Example:**

```typescript theme={null}
// Append iframe to container
const container = document.getElementById('onboarding-container');
if (container) {
  container.appendChild(onboardingApp.iframe);
}

// Example of creating and appending in vanilla TypeScript
function setupOnboarding() {
  const onboardingApp = createOnboardingApp({
    origin: '{{WORTH_ONBOARDING_APP_DOMAIN}}',
    inviteToken: 'YOUR_TOKEN',
  });

  const container = document.getElementById('onboarding-container');
  if (container) {
    container.appendChild(onboardingApp.iframe);
  }
}

// Call setup function during your app's initialization
setupOnboarding();
```