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

package/README.md

@@ -1,293 +1,165 @@
-# Onboarding Application
+# Worth Onboarding SDK
 
-## Install
+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.
 
-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.
+SDK 3 delivers improved performance, greater configurability, and seamless host application
+integration compared to its predecessor (SDK 2).
 
-```bash
-pnpm install
-```
-
-## Run Locally
-
-### Development
+> "Instead of managing an iframe, you give the SDK a mount point and a set of lifecycle callbacks."
 
-Start the development server:
-
-```bash
-pnpm dev
-```
+## Key Benefits
 
-Then open
+- **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
 
-➜  Local:  [http://localhost:5180](http://localhost:5180)
-
-➜  Network: shown in your terminal output, if needed
-
-### Optimized Build + Serve
-
-To test an optimized production build locally:
-
-```bash
-pnpm build
-pnpm start
-```
+## Scope
 
-Then open
-  
-  ➜  Local:  [http://localhost:4173](http://localhost:4173)
-  
-  ➜  Network: shown in your terminal output, if needed
+**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.
 
-## Test
+**Out of scope**: Non-onboarding products, mobile native SDKs, server-side rendering,
+offline functionality, legacy browser support.
 
-Run the test suite:
+## Installation
 
 ```bash
-pnpm test
+npm install @worthai/onboarding-sdk
 ```
 
-`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.
+## Quick Start
 
-Run tests with coverage:
+### 1. Add a mount target to your page
 
-```bash
-pnpm test:coverage
-```
-
-Open the Vitest UI:
-
-```bash
-pnpm test:ui
-```
-
-## Check
-
-Run quality checks:
-
-```bash
-pnpm check
+```html
+<div id="worth-onboarding"></div>
 ```
 
-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.
+### 2. Create an instance
 
-## SDK 3 Package Boundary
+Initialize with your invite token and lifecycle callbacks:
 
-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.
+- `onStepSubmit` — fires when applicants submit each step
+- `onComplete` — fires upon finishing the flow
+- `onError` — handles SDK or runtime errors
 
-```ts
+```typescript
 import { createWorthOnboarding } from '@worthai/onboarding-sdk';
 
 const onboarding = createWorthOnboarding({
-  apiBaseUrl: 'https://api.example.com',
-  inviteToken: 'INVITE_TOKEN'
+  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);
+  },
 });
-
-await onboarding.mount('#worth-onboarding');
 ```
 
-The SDK owns an in-memory router for the mounted onboarding flow so customer
-pages do not need to serve or navigate under `/onboarding`.
-
-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.
-
-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.
-
-The SDK 3 subpath remains available for consumers that need to pin the current package
-boundary:
-
-```ts
-import { createWorthOnboarding } from '@worthai/onboarding-sdk/sdk3';
-```
+Optional: use `apiBaseUrl` to target non-production environments.
 
-For script-tag usage, load the browser-global bundle from the package, then call
-`window.WorthAI.createWorthOnboarding`:
+### 3. Mount asynchronously
 
-```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>
+```typescript
+await onboarding.mount('#worth-onboarding');
 ```
 
-Build the deployed app and SDK artifacts separately:
-
-```bash
-pnpm build
-pnpm build:sdk
-```
+Wrap the mount call in try/catch to handle mount failures separately from runtime errors.
 
-`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:
+### 4. Clean up
 
-```bash
-WORTH_SDK_DEBUG=true pnpm build:sdk
-```
+Call `unmount()` when routes change or components unload. SDK 3 allows only one mounted instance at a time.
 
-## 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/
+```typescript
+onboarding.unmount();
 ```
 
-## Core FlowComposer Feature
-
-`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.
-
-## Catalog Pattern
-
-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.
-
-Catalogs do not render UI. They answer, "is this a valid thing the schema can ask for?"
-
-## Registry Pattern
+### Framework Integration
 
-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.
+In React or similar frameworks, create the instance once, mount during component
+initialization, and unmount in the cleanup function of your effect/lifecycle hook.
 
-The catalog defines what exists. The registry decides how a known item becomes UI.
+### Content Security Policy
 
-## Flow Composer Routes
+If your page enforces a strict `style-src` CSP, pass your nonce so injected styles aren't blocked:
 
-- `/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
+createWorthOnboarding({
+  // ...
+  styleNonce: window.__CSP_NONCE__,
+});
+```
 
-## Route Params: `:formKey` and `:stepKey`
+### Error Handling
 
-Flow routes include dynamic params to identify what should be rendered:
+Use `isWorthOnboardingError()` to identify Worth-specific errors and branch on their `code` property.
 
-- `:formKey` identifies which form definition is active.
-- `:stepKey` identifies the specific step within that form.
+## Migrating from SDK 2
 
-Example pattern:
+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.
 
-`/flow/:formKey/:stepKey`
+**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.
 
-Example concrete URL:
+### Feature Comparison
 
-`/flow/company-info/get-started`
+| 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()`                                                |
 
-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.
+### SDK 3 Basic Setup
 
-### Current Limitation
+```typescript
+const onboarding = createWorthOnboarding({
+  inviteToken: 'INVITE_TOKEN',
+  onComplete: ({ values }) => {},
+  onError: (error) => {},
+});
 
-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.
+await onboarding.mount('#worth-onboarding');
 
-## Application Tech Stack
+onboarding.unmount(); // cleanup
+```
 
-| 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. |
+### Migration Steps
 
-## Why SolidJS
+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
 
-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.
+## Documentation Links
 
-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.
+- [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)
 
-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.
+## Support
 
-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/).
+Questions or issues: [support@joinworth.com](mailto:support@joinworth.com)