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

package/README.md

@@ -1,276 +1,293 @@
-# @worthai/onboarding-sdk
+# Onboarding Application
 
-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.
+## Install
 
-## 📦 Installation
-
-### Within the monorepo
-
-```bash
-# Add as workspace dependency
-pnpm add @worthai/onboarding-sdk@workspace:*
-```
-
-### External projects
+This project uses [pnpm](https://pnpm.io) for dependency management. See
+[pnpm vs npm](https://pnpm.io/pnpm-vs-npm) for how pnpm differs from npm.
 
 ```bash
-# Using npm
-npm install @worthai/onboarding-sdk
-
-# Using pnpm
-pnpm install @worthai/onboarding-sdk
+pnpm install
 ```
 
-## 🛠️ API Reference
+## Run Locally
 
-### Onboarding-Specific Utilities
+### Development
 
-#### `createOnboardingApp(args)`
+Start the development server:
 
-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.
+```bash
+pnpm dev
+```
 
-```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
+Then open
 
-// Create an onboarding app instance and communicate with it
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding-app.com',
-  inviteToken: 'YOUR_INVITE_TOKEN',
-  mode: 'embedded',
-});
+➜  Local:  [http://localhost:5180](http://localhost:5180)
 
-// Listen for onboarding messages
-const subscription = onboardingApp.subscribe((event) => {
-  if (event.data.type === 'ROUTE_URL') {
-    console.log('Current route:', event.data.payload.url);
-  }
-});
+➜  Network: shown in your terminal output, if needed
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+### Optimized Build + Serve
 
-// Append the onboarding app iframe
-document
-  .getElementById('onboarding-container')
-  .appendChild(onboardingApp.iframe);
+To test an optimized production build locally:
 
-// Adding event listeners to Prev and Next buttons (for vanilla JS)
+```bash
+pnpm build
+pnpm start
+```
 
-const prevButton = document.getElementById('onboarding-prev');
-const nextButton = document.getElementById('onboarding-next');
+Then open
+  
+  ➜  Local:  [http://localhost:4173](http://localhost:4173)
+  
+  ➜  Network: shown in your terminal output, if needed
 
-// Next stage navigation command
-prevButton && prevButton.addEventListener('click', () => onboardingApp.prev());
+## Test
 
-// Prev stage navigation command
-nextButton && nextButton.addEventListener('click', () => onboardingApp.next());
+Run the test suite:
 
-// In your HTML:
-// <div id="onboarding-container"></div>
-// <button id="onboarding-prev">Back</button>
-// <button id="onboarding-next">Next</button>
+```bash
+pnpm test
 ```
 
-#### `createOnboardingConsumerApp(args)`
+`vitest` starts in watch mode by default, which is useful during local
+development because it reruns tests as files change. `vitest run` runs the test
+suite once and exits, good for single run checks before putting a PR up for review.
 
-Creates an onboarding consumer app instance for child-to-parent communication with type-safe onboarding messages.
+Run tests with coverage:
 
-> **Note**: The following example is illustrative code for vanilla TypeScript. Adapt to your framework's patterns when using React or other JavaScript frameworks.
+```bash
+pnpm test:coverage
+```
 
-```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
+Open the Vitest UI:
 
-// Create an onboarding consumer app instance for child-to-parent communication
-const consumerApp = createOnboardingConsumerApp();
+```bash
+pnpm test:ui
+```
 
-// Send onboarding messages to parent
-consumerApp.postMessage({
-    type: "ROUTE_URL";
-    payload: {
-        url: '/getting-started';
-    };
-});
+## Check
 
-// Listen for messages from parent
-const subscription = consumerApp.subscribe((event) => {
-  if (event.data.type === 'NEXT_STAGE') {
-    // Navigate to next stage
-  }
-});
+Run quality checks:
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+```bash
+pnpm check
 ```
 
-## 📋 Message Types
-
-### OnboardingAppMessage Events (Child → Parent)
+PRs going into `main` will be required to pass both quality and test checks before
+they can be merged. Before requesting a PR into `main`, run both the quality check and the test suite locally.
 
-| 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         |
+## SDK 3 Package Boundary
 
-### OnboardingConsumerAppMessage Events (Parent → Child)
+This repository is the source for the SDK 3 onboarding package surface. The SDK
+entrypoint is isolated from the app entrypoint so the existing `/onboarding` app
+build remains deployable.
 
-| 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) |
+```ts
+import { createWorthOnboarding } from '@worthai/onboarding-sdk';
 
-## 🔧 Usage Examples
+const onboarding = createWorthOnboarding({
+  apiBaseUrl: 'https://api.example.com',
+  inviteToken: 'INVITE_TOKEN'
+});
 
-> **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.).
+await onboarding.mount('#worth-onboarding');
+```
 
-### Parent Site Implementation
+The SDK owns an in-memory router for the mounted onboarding flow so customer
+pages do not need to serve or navigate under `/onboarding`.
 
-```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
+Production SDK usage does not require service path configuration. The SDK owns
+the auth, case, and integration service prefixes used by the embedded runtime.
+Use the optional `apiBaseUrl` option only for local, staging, or other non-default
+API origins.
+Styles are injected automatically during `mount()`. Hosts with a strict
+`style-src` Content Security Policy can pass `styleNonce` with their
+request-level CSP nonce.
 
-// Initialize the onboarding app
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding.example.com',
-});
+SDK browser storage and IndexedDB state are namespaced under
+`worth:onboarding-sdk` by default. Consumers can override this with
+`storageNamespace` for deterministic isolation, but the SDK supports one mounted
+onboarding runtime at a time.
 
-// Mount the iframe
-document
-  .getElementById('onboarding-container')
-  ?.appendChild(onboardingApp.iframe);
+The SDK 3 subpath remains available for consumers that need to pin the current package
+boundary:
 
-// Listen for route changes
-const subscription = onboardingApp.subscribe((event) => {
-  if (event.data.type === 'ROUTE_URL') {
-    //Some logic here...
-  }
-});
+```ts
+import { createWorthOnboarding } from '@worthai/onboarding-sdk/sdk3';
+```
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+For script-tag usage, load the browser-global bundle from the package, then call
+`window.WorthAI.createWorthOnboarding`:
+
+```html
+<script
+  src="https://unpkg.com/@worthai/onboarding-sdk@<version>/dist-sdk/sdk3/worthai-onboarding-sdk.global.js"
+></script>
+<script type="module">
+  const onboarding = window.WorthAI.createWorthOnboarding({
+    apiBaseUrl: 'https://api.example.com',
+    inviteToken: 'INVITE_TOKEN'
+  });
+
+  await onboarding.mount('#worth-onboarding');
+</script>
+```
 
-// Next stage navigation command
-onboardingApp.next();
+Build the deployed app and SDK artifacts separately:
 
-// Prev stage navigation command
-onboardingApp.prev();
+```bash
+pnpm build
+pnpm build:sdk
 ```
 
-### Child Site Implementation
+`pnpm build` writes the deployable app to `dist/`. `pnpm build:sdk` writes
+package artifacts to `dist-sdk/sdk3/` and does not replace the app `dist/`
+output.
+SDK artifacts are minified by default. For a local debug SDK build with readable
+output and source maps, run:
 
-```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
+```bash
+WORTH_SDK_DEBUG=true pnpm build:sdk
+```
 
-// Initialize the consumer app
-const consumerApp = createOnboardingConsumerApp();
+## Folder Structure
+
+```text
+.
+|-- README.md
+|-- react-vs-solid.README.md
+|-- package.json
+|-- vite.config.ts
+|-- src/
+|   |-- App.tsx
+|   |-- index.tsx
+|   |-- routes.ts
+|   |-- routeDefinitions.ts
+|   |-- components/
+|   |   |-- alerts/
+|   |   |-- buttons/
+|   |   |-- card/
+|   |   |-- form/
+|   |   |   |-- modular/
+|   |   |       |-- inputs/
+|   |   |       |-- layoutContent/
+|   |   |       |-- widgets/
+|   |   |-- global/
+|   |   |-- icons/
+|   |   |-- progress/
+|   |   |-- step/
+|   |-- lib/
+|   |   |-- axios/
+|   |   |-- flowComposer/
+|   |   |   |-- componentRegistry/
+|   |   |   |   |-- catalogs/
+|   |   |   |-- db/
+|   |   |   |-- flow/
+|   |   |   |-- form/
+|   |   |   |-- rules/
+|   |   |   |-- schema/
+|   |   |-- google/
+|   |   |-- storage/
+|   |-- pages/
+|   |   |-- Composer/
+|   |   |   |-- editor/
+|   |   |   |-- steps/
+|   |   |-- Login/
+|   |-- services/
+|       |-- auth/
+|       |-- case/
+```
 
-// Listen for parent commands
-const subscription = consumerApp.subscribe((event) => {
-  if (event.data.type === 'NEXT_STAGE') {
-    // Add some logic here...
-  }
-});
+## Core FlowComposer Feature
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
+`FlowComposer` is the schema-driven engine for the onboarding journey. It reads
+the flow definition, resolves the current step, renders the matching UI
+components, and manages step-to-step progression so forms can be updated by
+changing configuration instead of rebuilding screens by hand.
 
-// Send form data to parent
-onboardingConsumerApp.postMessage({
-  type: 'ROUTE_URL',
-  payload: { url: '/some-route-here' },
-});
-```
+## Catalog Pattern
 
-### Custom Raw CSS
+A catalog is the typed source of truth for what the schema is allowed to describe. In Flow Composer,
+catalogs define supported field, layout, widget, and custom step types, including their metadata and
+configuration schemas.
 
-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.
+Catalogs do not render UI. They answer, "is this a valid thing the schema can ask for?"
 
-#### Parent Site: Sending Custom CSS
+## Registry Pattern
 
-```typescript
-import { createOnboardingApp } from '@worthai/onboarding-sdk';
+A registry maps known catalog entries to the renderer functions that produce UI at runtime. In Flow
+Composer, the component registry takes validated schema items and resolves the field, layout, widget, or
+step renderer that should handle each item.
 
-const onboardingApp = createOnboardingApp({
-  origin: 'https://onboarding.example.com',
-});
+The catalog defines what exists. The registry decides how a known item becomes UI.
 
-// 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;
-      }
-    `,
-  },
-});
-```
+## Flow Composer Routes
 
-#### Child Site: Receiving and Applying Custom CSS
+- `/flow`: Renders the current `schema.json` and reflects the flow experience users would see.
+- `/flow/editor`: Admin-focused route with a Monaco editor attached to `StepContainer` for live schema editing.
 
-```typescript
-import { createOnboardingConsumerApp } from '@worthai/onboarding-sdk';
+## Route Params: `:formKey` and `:stepKey`
 
-const consumerApp = createOnboardingConsumerApp();
+Flow routes include dynamic params to identify what should be rendered:
 
-// 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');
+- `:formKey` identifies which form definition is active.
+- `:stepKey` identifies the specific step within that form.
 
-    if (!styleElement) {
-      styleElement = document.createElement('style');
-      styleElement.id = 'custom-css-injection';
-      document.head.appendChild(styleElement);
-    }
+Example pattern:
 
-    // Apply the custom CSS
-    styleElement.innerHTML = event.data.payload.css;
-  }
-});
+`/flow/:formKey/:stepKey`
 
-// ⚠️ Important: Remember to unsubscribe when component unmounts or cleanup is needed
-// subscription.unsubscribe();
-```
+Example concrete URL:
 
-> **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.
+`/flow/company-info/get-started`
 
-## 🔒 Security
+In practice, these params let the app deep-link to a specific form and step,
+and are what flow navigation uses to move between steps in a predictable way.
 
-The SDK includes built-in security measures:
+### Current Limitation
 
-- **Origin validation**: All messages are validated against the specified origin
-- **Type safety**: TypeScript ensures message structure integrity
+The editor currently does not write changes back to files. Any live schema
+edits in `/flow/editor` are in-memory only and will be lost on page refresh
+until persistence is implemented.
 
-## 🧪 Development
+## Application Tech Stack
 
-### Building the SDK
+| Technology | Purpose |
+| --- | --- |
+| [`solid-js`](https://docs.solidjs.com/) | Provides the reactive UI framework used to build the application. |
+| [`@solidjs/router`](https://docs.solidjs.com/solid-router) | Handles client-side routing for the Solid application. |
+| [`@solid-primitives/utils`](https://primitives.solidjs.community/package/utils/) | Provides shared utility helpers that complement Solid's reactive primitives. |
+| [`@modular-forms/solid`](https://modularforms.dev/) | Provides form state management and validation helpers for Solid components. |
+| [`vite`](https://vite.dev/guide/) | Provides the development server and production build tooling for the app. |
+| [`typescript`](https://www.typescriptlang.org/docs/) | Adds static typing and compile-time checks for the application code. |
+| [`@biomejs/biome`](https://biomejs.dev/) | Provides code formatting and linting to keep the codebase consistent. |
+| [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) | Runs markdown linting and automatic fixes for project documentation. |
+| [`tailwindcss`](https://tailwindcss.com/docs) | Provides utility-first CSS classes for styling the application. |
+| [`daisyui`](https://daisyui.com/) | Adds Tailwind CSS component classes and themes for faster UI development. |
+| [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) | Resolves conflicting Tailwind CSS classes when composing class strings. |
+| [`@fontsource/figtree`](https://fontsource.org/fonts/figtree) | Provides the Figtree font as an installable package for application styling. |
+| [`axios`](https://axios-http.com/docs/intro) | Handles HTTP requests to backend services and external APIs. |
+| [`axios-retry`](https://github.com/softonic/axios-retry) | Adds retry behavior to Axios requests for transient network or service failures. |
+| [`dexie`](https://dexie.org/docs/) | Provides a friendly IndexedDB wrapper for local browser storage. |
+| [`zod`](https://zod.dev/) | Defines and validates runtime schemas for application data. |
+| [`jsonc-parser`](https://github.com/microsoft/node-jsonc-parser) | Parses and edits JSON with comments for configuration-like content. |
+| [`lodash`](https://lodash.com/docs/) | Provides general-purpose utility functions for working with collections, objects, and values. |
+| [`libphonenumber-js`](https://gitlab.com/catamphetamine/libphonenumber-js) | Parses, formats, and validates phone numbers. |
+| [`@googlemaps/js-api-loader`](https://googlemaps.github.io/js-api-loader/) | Loads the Google Maps JavaScript API on demand from application code. |
+| [`@googlemaps/places`](https://www.npmjs.com/package/@googlemaps/places) | Provides Google Places API client utilities and types for place-related features. |
+| [`monaco-editor`](https://microsoft.github.io/monaco-editor/) | Provides the browser-based code editor used for rich editing experiences. |
+| [`monaco-json`](https://github.com/microsoft/monaco-json) | Adds JSON language support and validation features to Monaco editor. |
 
-```bash
-pnpm build
-```
+## Why SolidJS
 
-### Running Storybook
+SolidJS was chosen over React because of its fine-grained reactivity model. React relies on repeated component renders,
+meaning each state change can trigger broader recalculation across the component tree.
 
-```bash
-pnpm storybook
-```
+In contrast, Solid updates only the exact reactive nodes that depend on a changed value.
+There is no full component re-execution; only the minimal set of dependent expressions re-run.
 
-## 📝 License
+This distinction is core to the architecture. Flow Composer is highly dynamic, and its performance and
+predictability depend on updating only what actually changed. Solid's reactive model maps directly to that
+requirement, making it a better fit for this system.
 
-Private package - All rights reserved.
+For deeper SolidJS reading, see [`react-vs-solid.README.md`](react-vs-solid.README.md) and
+[Solid.js Best Practices](https://www.brenelz.com/posts/solid-js-best-practices/).

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;