npm package: @modelnex/sdk
Description: React SDK for natural language control of web apps via AI agents
Latest version: 0.5.61

# @modelnex/sdk

React SDK for ModelNex agent chat, tours, and workflows.

## Install

```bash
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';

export default function AppShell() {
  return (
    <ModelNexProvider
      serverUrl={import.meta.env.DEV ? 'http://localhost:3002' : 'https://api.modelnex.com'}
      websiteId="your-website-id"
      userProfile={{
        type: currentUser.role,
        isNewUser: currentUser.isNewUser,
        userId: currentUser.id,
      }}
    >
      <App />
      <ModelNexChatBubble appName="My Product" />
    </ModelNexProvider>
  );
}
```

`websiteId` identifies the integration. `userProfile` is used for tour/workflow targeting and completion tracking. For local development, pass `serverUrl` explicitly so the SDK does not fall back to the hosted API.

## Tour Start Model

ModelNex currently supports these automatic trigger types:

- `first_visit`
- `feature_unlocked`
- `manual`

Each tour or workflow 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` | Root provider for server connection, chat state, dev tools, tours, and workflows |
| `ModelNexChatBubble` | Unified assistant UI for chat, voice tours, and workflows |
| `useRunCommand` | Run agent commands from custom UI |
| `useTourPlayback` | Low-level playback hook for tours and shared experience runtime |
| `useOnboardingPlayback` | Playback hook preconfigured for workflow playback |
| `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` | Backend base URL for chat, tags, tours, voice, and recording APIs |
| `websiteId` | Tenant/integration identifier |
| `userProfile` | End-user targeting data for tours/workflows |

## 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 |
| `agentName` | Name of the AI agent displayed in the header |
| `onCommand` | Custom backend override for agent command handling |
| `recordingExperienceType` | Save recordings as `'tour'` or `'onboarding'` |
| `className` | Additional class name for the container |
| `theme` | Custom theme overrides for the chat bubble and panel (`accentColor`, `panelWidth`, etc.) |

## Configuration Examples

Here are some real-world examples of how to configure the SDK.

### Fully Customized Provider

```tsx
import { ModelNexProvider } from '@modelnex/sdk';

export function AppShell({ children, currentUser }) {
  return (
    <ModelNexProvider
      websiteId="prod_site_123"

      // User Targeting for Tours & Workflows
      userProfile={{
        userId: currentUser.id,
        isNewUser: currentUser.createdAt > Date.now() - 86400000 * 7, // 7 days
        type: currentUser.role, // e.g. "admin", "viewer"
      }}
    >
      {children}
    </ModelNexProvider>
  );
}
```

### Browser-Injected Dev Mode

```html
<script>
  window.__MODELNEX_DEV_MODE_KEY__ = 'dmk_live_xxxxxxxxx';
</script>
```

The SDK now enables dev tooling only after it finds a browser-injected dev mode key and validates it with the backend for the current `websiteId`.

### Themed Chat Bubble

```tsx
import { ModelNexChatBubble } from '@modelnex/sdk';

export function ChatIntegration() {
  return (
    <ModelNexChatBubble 
      // Branding & Copy
      appName="Acme Corp Dashboard"
      agentName="Acme Assistant"
      welcomeMessage="Hi there! Ask me to navigate to a page or help you with your account."
      placeholder="Type a command or ask a question..."
      defaultCommand="Show me my recent activity"
      
      // Recording defaults
      recordingExperienceType="onboarding" // Default is 'tour'
      
      // Visual Theme Customization
      theme={{
        accentColor: "#f59e0b", // Amber accent
        accentForeground: "#ffffff",
        panelWidth: "400px", // Wider panel
        panelMaxHeight: "700px",
        bubbleSize: "64px", // Larger bubble
        borderRadius: "24px",
        zIndex: 9999
      }}
    />
  );
}
```

## Testing Flows

- Force a tour with `?modelnex_test_tour=TOUR_ID`
- Force a workflow with `?modelnex_test_workflow=FLOW_ID`

## Custom UI

Use `useRunCommand` instead of `ModelNexChatBubble` when you want your own assistant UI:

```tsx
import { useRunCommand } from '@modelnex/sdk';

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).