@worthai/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.

📦 Installation

Within the monorepo

# Add as workspace dependency
pnpm add @worthai/onboarding-sdk@workspace:*

External projects

# Using npm
npm install @worthai/onboarding-sdk

# Using pnpm
pnpm install @worthai/onboarding-sdk

🛠️ 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.

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',
});

// Listen for onboarding messages
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'ROUTE_URL') {
    console.log('Current route:', event.data.payload.url);
  }
});

// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
// subscription.unsubscribe();

// Append the onboarding app iframe
document
  .getElementById('onboarding-container')
  .appendChild(onboardingApp.iframe);

// Adding event listeners to Prev and Next buttons (for vanilla JS)

const prevButton = document.getElementById('onboarding-prev');
const nextButton = document.getElementById('onboarding-next');

// Next stage navigation command
prevButton && prevButton.addEventListener('click', () => onboardingApp.prev());

// Prev stage navigation command
nextButton && nextButton.addEventListener('click', () => onboardingApp.next());

// In your HTML:
// <div id="onboarding-container"></div>
// <button id="onboarding-prev">Back</button>
// <button id="onboarding-next">Next</button>

createOnboardingConsumerApp(args)

Creates an onboarding consumer app instance for child-to-parent 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.

import { createOnboardingConsumerApp } 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
  }
});

// ⚠️ 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

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

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();

Child Site Implementation

import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';

// Initialize the consumer app
const consumerApp = createOnboardingConsumerApp();

// Listen for parent commands
const subscription = consumerApp.subscribe((event) => {
  if (event.data.type === 'NEXT_STAGE') {
    // Add some logic here...
  }
});

// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
// subscription.unsubscribe();

// Send form data to parent
onboardingConsumerApp.postMessage({
  type: 'ROUTE_URL',
  payload: { url: '/some-route-here' },
});

Custom Raw CSS

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.

Parent Site: Sending Custom CSS

import { createOnboardingApp } from '@worthai/onboarding-sdk';

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;
      }
    `,
  },
});

Child Site: Receiving and Applying Custom CSS

import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';

const consumerApp = createOnboardingConsumerApp();

// 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');

    if (!styleElement) {
      styleElement = document.createElement('style');
      styleElement.id = 'custom-css-injection';
      document.head.appendChild(styleElement);
    }

    // Apply the custom CSS
    styleElement.innerHTML = event.data.payload.css;
  }
});

// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
// subscription.unsubscribe();

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.

🔒 Security

The SDK includes built-in security measures:

• Origin validation: All messages are validated against the specified origin
• Type safety: TypeScript ensures message structure integrity

🧪 Development

Building the SDK

pnpm build

Running Storybook

pnpm storybook

📝 License

Private package - All rights reserved.