@modelnex/sdk 0.1.1 → 0.5.3

package/README.md

@@ -1,66 +1,140 @@
 # @modelnex/sdk
 
-React SDK for natural language control of web apps. Register actions and context; an AI agent executes actions in response to user commands.
+React SDK for ModelNex agent chat, tours, and guided onboarding.
 
 ## Install
 
 ```bash
-npm install @modelnex/sdk react zod
+npm install @modelnex/sdk react react-dom zod
 ```
 
+## Unit Tests
+
+Run the SDK unit tests from the `sdk` package directory:
+
+```bash
+cd sdk
+npm test
+```
+
+The SDK test script builds `dist/` first, then runs the unit tests.
+
 ## Quick Start
 
 ```tsx
-import { ModelNexProvider, ModelNexChatBubble } from "@modelnex/sdk";
-
-function App() {
-  const [items, setItems] = React.useState([]);
+import { ModelNexProvider, ModelNexChatBubble } from '@modelnex/sdk';
 
+export default function AppShell() {
   return (
-    <div>
-      <ModelNexChatBubble placeholder="Add item, list all..." />
-      <ul>{items.map(i => <li key={i.id}>{i.title}</li>)}</ul>
-    </div>
+    <ModelNexProvider
+      websiteId="your-website-id"
+      userProfile={{
+        type: currentUser.role,
+        isNewUser: currentUser.isNewUser,
+        userId: currentUser.id,
+      }}
+      tourFacts={{
+        features: currentUser.enabledFeatures,
+      }}
+    >
+      <App />
+      <ModelNexChatBubble appName="My Product" />
+    </ModelNexProvider>
   );
 }
-
-// Wrap your app (serverUrl defaults to http://localhost:3002)
-export default () => (
-  <ModelNexProvider>
-    <App />
-  </ModelNexProvider>
-);
 ```
 
-## Exports
+`websiteId` identifies the integration. `userProfile` is used for tour/onboarding targeting and completion tracking. `tourFacts.features` is used for `feature_unlocked` experiences.
+
+## Tour Start Model
+
+ModelNex currently supports these automatic trigger types:
+
+- `first_visit`
+- `feature_unlocked`
+- `manual`
+
+Each tour or onboarding flow can also configure:
+
+- `startPolicy`: `immediate_start` | `prompt_only` | `manual_only`
+- `notificationType`: `bubble_card` | `modal`
+
+Current behavior:
+
+- `prompt_only + bubble_card` shows an in-bubble prompt
+- `prompt_only + modal` shows a centered modal
+- `immediate_start` starts playback immediately
+- `manual_only` never auto-surfaces
+
+## Main Exports
 
 | Export | Purpose |
 |--------|---------|
-| `ModelNexProvider` | Wraps app, connects to agent server |
-| `useRunCommand` | Run commands programmatically (for custom UI) |
-| `UIStateProvider` | Holds UI state synced to agent |
-| `useUIState` | Read/update UI state |
-| `useViewportTrack` | Track element visibility |
-| `useVisibleIds` | Get visible element IDs |
-| `useAgentViewport` | Register visible IDs with agent |
-| `ModelNexChatBubble` | Optional chat bubble UI |
+| `ModelNexProvider` | Root provider for server connection, chat state, dev tools, tours, and onboarding |
+| `ModelNexChatBubble` | Unified assistant UI for chat, voice tours, and guided onboarding |
+| `useRunCommand` | Run agent commands from custom UI |
+| `useRegisterAction` | Register app actions the agent can execute |
+| `useTourPlayback` | Low-level playback hook for tours and shared experience runtime |
+| `useOnboardingPlayback` | Playback hook preconfigured for onboarding flows |
+| `useExperiencePlayback` | Alias over the shared playback hook |
+| `useRecordingMode` | Low-level recorder hook for custom authoring UI |
+| `useActionHighlight` | Highlight actions currently being executed |
+| `UIStateProvider`, `useUIState` | Sync UI state to the agent |
+| `useViewportTrack`, `useVisibleIds`, `useAgentViewport` | Track and expose visible UI to the agent |
+
+## Provider Props
+
+| Prop | Purpose |
+|------|---------|
+| `serverUrl` | ModelNex server base URL. Defaults to `https://api.modelnex.io` |
+| `commandUrl` | Optional same-origin command proxy base |
+| `websiteId` | Tenant/integration identifier |
+| `userProfile` | End-user targeting data for tours/onboarding |
+| `tourFacts` | Additional facts, currently used for feature-based eligibility |
+| `toursApiBase` | Same-origin API base for tour/onboarding fetches and test URLs |
+| `devMode` | Enables recording/studio tooling for your internal users |
+
+## Chat Bubble Props
+
+| Prop | Purpose |
+|------|---------|
+| `placeholder` | Input placeholder |
+| `defaultCommand` | Fallback command when the input is empty |
+| `welcomeMessage` | Empty-state greeting |
+| `appName` | Product name used in narration and UI copy |
+| `onCommand` | Custom backend override for agent command handling |
+| `recordingExperienceType` | Save recordings as `'tour'` or `'onboarding'` |
+| `className` | Additional class name for the container |
+
+## Testing Flows
+
+- Force a tour with `?modelnex_test_tour=TOUR_ID`
+- Force onboarding with `?modelnex_test_onboarding=FLOW_ID`
+- If you use a same-origin proxy, set `toursApiBase` so test fetches avoid CORS issues
 
 ## Custom UI
 
-Use `useRunCommand` instead of `ModelNexChatBubble` for your own command UI:
+Use `useRunCommand` instead of `ModelNexChatBubble` when you want your own assistant UI:
 
 ```tsx
-const runCommand = useRunCommand();
+import { useRunCommand } from '@modelnex/sdk';
 
-<button onClick={() => runCommand("Add a new card")}>Run</button>
+function MyButton() {
+  const runCommand = useRunCommand();
+  return <button onClick={() => runCommand('Open billing settings')}>Run</button>;
+}
 ```
 
-
 ## Peer Dependencies
 
 - `react` >= 17
+- `react-dom` >= 17
 - `zod` >= 3
 
 ## License
 
 MIT
+
+## Releasing
+
+Releases are published by GitHub Actions from version tags only. See [RELEASING.md](./RELEASING.md).

package/dist/aom-HDYNCIOY.mjs

@@ -0,0 +1,10 @@
+import {
+  clearAOMMap,
+  generateMinifiedAOM,
+  getElementByUid
+} from "./chunk-N65UEB6X.mjs";
+export {
+  clearAOMMap,
+  generateMinifiedAOM,
+  getElementByUid
+};

package/dist/{aom-J6NYMGDW.mjs → chunk-N65UEB6X.mjs}

@@ -62,8 +62,9 @@ function clearAOMMap() {
   uidMap.clear();
   nextUid = 1;
 }
+
 export {
-  clearAOMMap,
   generateMinifiedAOM,
-  getElementByUid
+  getElementByUid,
+  clearAOMMap
 };