@worthai/onboarding-sdk 2.0.17 → 3.0.0-beta.2.12.7

package/README.md

@@ -1,276 +1,165 @@
-# @worthai/onboarding-sdk
+# Worth Onboarding SDK
 
-A TypeScript SDK for seamless cross-origin communication between parent and child sites using iframe postMessage API. This SDK provides type-safe utilities for building onboarding flows with secure message passing between applications.
+The Worth Onboarding SDK embeds onboarding experiences directly into your website's DOM.
+Rather than managing an iframe separately, you provide a mount point and lifecycle callbacks,
+and the SDK handles rendering, execution, and teardown.
 
-## 📦 Installation
+SDK 3 delivers improved performance, greater configurability, and seamless host application
+integration compared to its predecessor (SDK 2).
 
-### Within the monorepo
+> "Instead of managing an iframe, you give the SDK a mount point and a set of lifecycle callbacks."
 
-```bash
-# Add as workspace dependency
-pnpm add @worthai/onboarding-sdk@workspace:*
-```
-
-### External projects
-
-```bash
-# Using npm
-npm install @worthai/onboarding-sdk
-
-# Using pnpm
-pnpm install @worthai/onboarding-sdk
-```
+## Key Benefits
 
-## 🛠️ API Reference
-
-### Onboarding-Specific Utilities
-
-#### `createOnboardingApp(args)`
-
-Creates an onboarding app instance for parent-to-child communication with type-safe onboarding messages.
-
-> **Note**: The following example is illustrative code for vanilla TypeScript. Adapt to your framework's patterns when using React or other JavaScript frameworks.
-
-```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
-
-// Create an onboarding app instance and communicate with it
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding-app.com',
-  inviteToken: 'YOUR_INVITE_TOKEN',
-  mode: 'embedded',
-});
+- **Faster integration**: Minimize custom development and deploy Worth's onboarding quickly
+- **Branded experience**: Preserve your brand while leveraging Worth's core capabilities
+- **Flexible embedding**: Mount the flow into any DOM element you control
+- **Type-safe communication**: Built-in TypeScript support with type-safe messaging
 
-// Listen for onboarding messages
-const subscription = onboardingApp.subscribe((event) => {
-  if (event.data.type === 'ROUTE_URL') {
-    console.log('Current route:', event.data.payload.url);
-  }
-});
+## Scope
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+**In scope**: Applicant onboarding embedded in host DOM, JavaScript/TypeScript web SDK,
+modern browser support (last 2 versions of Chrome, Firefox, Safari, Edge), client-side
+rendering.
 
-// Append the onboarding app iframe
-document
-  .getElementById('onboarding-container')
-  .appendChild(onboardingApp.iframe);
+**Out of scope**: Non-onboarding products, mobile native SDKs, server-side rendering,
+offline functionality, legacy browser support.
 
-// Adding event listeners to Prev and Next buttons (for vanilla JS)
+## Installation
 
-const prevButton = document.getElementById('onboarding-prev');
-const nextButton = document.getElementById('onboarding-next');
+```bash
+npm install @worthai/onboarding-sdk
+```
 
-// Next stage navigation command
-prevButton && prevButton.addEventListener('click', () => onboardingApp.prev());
+## Quick Start
 
-// Prev stage navigation command
-nextButton && nextButton.addEventListener('click', () => onboardingApp.next());
+### 1. Add a mount target to your page
 
-// In your HTML:
-// <div id="onboarding-container"></div>
-// <button id="onboarding-prev">Back</button>
-// <button id="onboarding-next">Next</button>
+```html
+<div id="worth-onboarding"></div>
 ```
 
-#### `createOnboardingConsumerApp(args)`
+### 2. Create an instance
 
-Creates an onboarding consumer app instance for child-to-parent communication with type-safe onboarding messages.
+Initialize with your invite token and lifecycle callbacks:
 
-> **Note**: The following example is illustrative code for vanilla TypeScript. Adapt to your framework's patterns when using React or other JavaScript frameworks.
+- `onStepSubmit` — fires when applicants submit each step
+- `onComplete` — fires upon finishing the flow
+- `onError` — handles SDK or runtime errors
 
 ```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
+import { createWorthOnboarding } from '@worthai/onboarding-sdk';
 
-// Create an onboarding consumer app instance for child-to-parent communication
-const consumerApp = createOnboardingConsumerApp();
-
-// Send onboarding messages to parent
-consumerApp.postMessage({
-    type: "ROUTE_URL";
-    payload: {
-        url: '/getting-started';
-    };
-});
-
-// Listen for messages from parent
-const subscription = consumerApp.subscribe((event) => {
-  if (event.data.type === 'NEXT_STAGE') {
-    // Navigate to next stage
-  }
+const onboarding = createWorthOnboarding({
+  inviteToken: '{{YOUR_INVITE_TOKEN}}',
+  onStepSubmit: ({ stepId, values }) => {
+    console.log('Step submitted:', stepId, values);
+  },
+  onComplete: ({ values }) => {
+    console.log('Onboarding completed:', values);
+  },
+  onError: (error) => {
+    console.error('Onboarding error:', error);
+  },
 });
-
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
 ```
 
-## 📋 Message Types
-
-### OnboardingAppMessage Events (Child → Parent)
-
-| Event Type           | Description                                                            |
-| -------------------- | ---------------------------------------------------------------------- |
-| `ROUTE_URL`          | Notifies parent site of current route changes in onboarding app        |
-| `IFRAME_RESIZE`      | Notifies parent site when the iframe needs to resize (includes height) |
-| `IFRAME_INITIALIZED` | Notifies parent site when the iframe has finished initializing         |
-
-### OnboardingConsumerAppMessage Events (Parent → Child)
-
-| Event Type                       | Description                                                                    |
-| -------------------------------- | ------------------------------------------------------------------------------ |
-| `NEXT_STAGE`                     | Navigates the onboarding app to the next stage                                 |
-| `PREV_STAGE`                     | Navigates the onboarding app to the previous stage                             |
-| `SKIP_STAGE`                     | Skips the current stage in the onboarding app                                  |
-| `INVITE_TOKEN_SENT`              | Notifies child site that an invite token has been sent (includes token)        |
-| `IFRAME_RENDERED_ON_PARENT_SITE` | Notifies child site that the iframe has been rendered on the parent site       |
-| `REFRESH_SIZE`                   | Requests the child site to refresh its size                                    |
-| `IFRAME_INITIALIZED`             | Notifies child site that the iframe has been initialized (includes mode)       |
-| `SET_CUSTOM_CSS`                 | Sets custom CSS styles for the iframe (includes CSS string)                    |
-| `SET_IFRAME_MODE`                | Sets the iframe mode (includes mode: 'embedded', 'non-embedded', or undefined) |
-
-## 🔧 Usage Examples
+Optional: use `apiBaseUrl` to target non-production environments.
 
-> **Note**: The following examples are illustrative code for vanilla TypeScript. If you're using React or other JavaScript frameworks, the code should be adapted to the corresponding framework patterns (hooks, lifecycle methods, etc.).
-
-### Parent Site Implementation
+### 3. Mount asynchronously
 
 ```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
-
-// Initialize the onboarding app
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding.example.com',
-});
-
-// Mount the iframe
-document
-  .getElementById('onboarding-container')
-  ?.appendChild(onboardingApp.iframe);
-
-// Listen for route changes
-const subscription = onboardingApp.subscribe((event) => {
-  if (event.data.type === 'ROUTE_URL') {
-    //Some logic here...
-  }
-});
-
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
-
-// Next stage navigation command
-onboardingApp.next();
-
-// Prev stage navigation command
-onboardingApp.prev();
+await onboarding.mount('#worth-onboarding');
 ```
 
-### Child Site Implementation
-
-```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
-
-// Initialize the consumer app
-const consumerApp = createOnboardingConsumerApp();
+Wrap the mount call in try/catch to handle mount failures separately from runtime errors.
 
-// Listen for parent commands
-const subscription = consumerApp.subscribe((event) => {
-  if (event.data.type === 'NEXT_STAGE') {
-    // Add some logic here...
-  }
-});
+### 4. Clean up
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+Call `unmount()` when routes change or components unload. SDK 3 allows only one mounted instance at a time.
 
-// Send form data to parent
-onboardingConsumerApp.postMessage({
-  type: 'ROUTE_URL',
-  payload: { url: '/some-route-here' },
-});
+```typescript
+onboarding.unmount();
 ```
 
-### Custom Raw CSS
+### Framework Integration
 
-The SDK allows parent sites to inject custom CSS styles into the child iframe. This is useful for customizing the appearance of the onboarding flow to match your brand or design requirements.
+In React or similar frameworks, create the instance once, mount during component
+initialization, and unmount in the cleanup function of your effect/lifecycle hook.
 
-#### Parent Site: Sending Custom CSS
+### Content Security Policy
 
-```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
+If your page enforces a strict `style-src` CSP, pass your nonce so injected styles aren't blocked:
 
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding.example.com',
-});
-
-// Send custom CSS to the child iframe
-onboardingApp.postMessage({
-  type: 'SET_CUSTOM_CSS',
-  payload: {
-    css: `
-      body {
-        background: #f0f0f0;
-        font-family: 'Custom Font', sans-serif;
-      }
-      .onboarding-container {
-        padding: 20px;
-        border-radius: 8px;
-      }
-    `,
-  },
+```typescript
+createWorthOnboarding({
+  // ...
+  styleNonce: window.__CSP_NONCE__,
 });
 ```
 
-#### Child Site: Receiving and Applying Custom CSS
+### Error Handling
 
-```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
-
-const consumerApp = createOnboardingConsumerApp();
+Use `isWorthOnboardingError()` to identify Worth-specific errors and branch on their `code` property.
 
-// Listen for custom CSS messages
-const subscription = consumerApp.subscribe((event) => {
-  if (event.data.type === 'SET_CUSTOM_CSS') {
-    // Create or update a style element
-    let styleElement = document.getElementById('custom-css-injection');
+## Migrating from SDK 2
 
-    if (!styleElement) {
-      styleElement = document.createElement('style');
-      styleElement.id = 'custom-css-injection';
-      document.head.appendChild(styleElement);
-    }
+The migration shifts iframe ownership from your application to the SDK itself. Instead of
+creating and managing an iframe with `postMessage` subscriptions, you now mount an embedded
+runtime into a DOM element.
 
-    // Apply the custom CSS
-    styleElement.innerHTML = event.data.payload.css;
-  }
-});
+**Key architectural shift:** With SDK 2, your host page creates and manages a Worth iframe
+directly. With SDK 3, you give the SDK a DOM element and it mounts, renders, and tears down
+the onboarding runtime for you — no iframe and no `postMessage` subscription required.
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
-```
+### Feature Comparison
 
-> **Note**: The child site should handle CSS injection securely and validate that the CSS doesn't contain malicious content. Consider sanitizing the CSS string before applying it in production environments.
+| Aspect     | SDK 2                                  | SDK 3                                                      |
+| ---------- | -------------------------------------- | ---------------------------------------------------------- |
+| Rendering  | Host-managed iframe                    | SDK-managed DOM mount                                      |
+| Setup      | `createOnboardingApp()`                | `createWorthOnboarding()`                                  |
+| Mounting   | `appendChild(iframe)`                  | `await onboarding.mount(target)`                           |
+| Events     | `subscribe()` + postMessage            | Typed callbacks (`onStepSubmit`, `onComplete`, `onError`)  |
+| Navigation | Manual (`next()`, `prev()`, `skip()`)  | SDK-owned (not exposed)                                    |
+| Styling    | `setCustomCss()`                       | Auto-injected on mount                                     |
+| Cleanup    | `unsubscribe()` + `cleanup()`          | `unmount()`                                                |
 
-## 🔒 Security
+### SDK 3 Basic Setup
 
-The SDK includes built-in security measures:
+```typescript
+const onboarding = createWorthOnboarding({
+  inviteToken: 'INVITE_TOKEN',
+  onComplete: ({ values }) => {},
+  onError: (error) => {},
+});
 
-- **Origin validation**: All messages are validated against the specified origin
-- **Type safety**: TypeScript ensures message structure integrity
+await onboarding.mount('#worth-onboarding');
 
-## 🧪 Development
+onboarding.unmount(); // cleanup
+```
 
-### Building the SDK
+### Migration Steps
 
-```bash
-pnpm build
-```
+1. Update package version
+2. Add mount target element
+3. Remove old stylesheet imports
+4. Replace `createOnboardingApp` with `createWorthOnboarding`
+5. Move event handlers to callbacks (`onComplete`, `onError`)
+6. Add `onStepSubmit` if analytics/auditing needed
+7. Handle CSP nonce if applicable
+8. Remove iframe navigation methods
+9. Replace cleanup with `unmount()`
+10. Test full flow end-to-end
 
-### Running Storybook
+## Documentation Links
 
-```bash
-pnpm storybook
-```
+- [Overview](https://docs.worthai.com/onboarding-sdk-3/overview)
+- [Quick Start Guide](https://docs.worthai.com/onboarding-sdk-3/quickstart)
+- [Migration Guide (SDK 2 → SDK 3)](https://docs.worthai.com/onboarding-sdk-3/migrate)
+- [API Reference](https://docs.worthai.com/onboarding-sdk-3/api-reference)
+- [Full Documentation](https://docs.worthai.com/introduction)
+- [Sample SDK initialization](https://docs.worthai.com/onboarding-sdk-3/sample-scenario)
 
-## 📝 License
+## Support
 
-Private package - All rights reserved.
+Questions or issues: [support@joinworth.com](mailto:support@joinworth.com)

package/dist-sdk/sdk3/createWorthOnboarding.d.ts

@@ -0,0 +1,2 @@
+import { WorthOnboarding, WorthOnboardingOptions } from './worthOnboarding.types';
+export declare function createWorthOnboarding(options: WorthOnboardingOptions): WorthOnboarding;

package/dist-sdk/sdk3/errors.d.ts

@@ -0,0 +1,24 @@
+export declare const WorthOnboardingErrorCode: {
+    readonly ALREADY_MOUNTED: "ALREADY_MOUNTED";
+    readonly CALLBACK_FAILED: "CALLBACK_FAILED";
+    readonly INVALID_MOUNT_TARGET: "INVALID_MOUNT_TARGET";
+    readonly INVALID_OPTIONS: "INVALID_OPTIONS";
+    readonly MISSING_INVITE_TOKEN: "MISSING_INVITE_TOKEN";
+    readonly MOUNT_CANCELLED: "MOUNT_CANCELLED";
+    readonly MOUNT_IN_PROGRESS: "MOUNT_IN_PROGRESS";
+    readonly MOUNT_TARGET_NOT_FOUND: "MOUNT_TARGET_NOT_FOUND";
+    readonly RUNTIME_ERROR: "RUNTIME_ERROR";
+    readonly RUNTIME_RENDER_FAILED: "RUNTIME_RENDER_FAILED";
+    readonly UNMOUNT_FAILED: "UNMOUNT_FAILED";
+};
+export type WorthOnboardingErrorCode = (typeof WorthOnboardingErrorCode)[keyof typeof WorthOnboardingErrorCode];
+export interface WorthOnboardingErrorOptions {
+    readonly cause?: unknown;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export declare class WorthOnboardingError extends Error {
+    readonly code: WorthOnboardingErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: WorthOnboardingErrorCode, message: string, options?: WorthOnboardingErrorOptions);
+}
+export declare function isWorthOnboardingError(error: unknown): error is WorthOnboardingError;