@modelnex/sdk

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

Install

npm install @modelnex/sdk react react-dom zod

Unit Tests

Run the SDK unit tests from the sdk package directory:

cd sdk
npm test

The SDK test script builds dist/ first, then runs the unit tests.

Quick Start

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
• always
• manual (shown in the dashboard as "Manual or Search")

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

Tour, workflow, and chat

All three run on the same in-product runtime (context, actions, voice). Use them for different jobs:

| Surface | Best for | |--------|-----------| | Tour | Time-bound, mostly linear walkthroughs—especially education and first exposure (e.g. a new screen or release). | | Workflow | Outcome-based paths that branch on UI or account state, including setup, recovery, approvals, and migrations. | | Chat | Open-ended questions and ad hoc help while staying grounded in the same page and agent context. |

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

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

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

For browser-plugin debugging, the shared script-tag path is usually the most reliable because it works across the page world and the extension isolated world:

(() => {
  let el = document.querySelector('script[data-modelnex-dev-mode-key]');
  if (!el) {
    el = document.createElement('script');
    el.setAttribute('data-modelnex-dev-mode-key', '');
    document.documentElement.appendChild(el);
  }
  el.dataset.modelnexDevModeKey = 'mn_dev_03f1da349fb7758aea091234b5bab91426f9';
})();

Themed Chat Bubble

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

Programmatic Workflow Launch

Launch an onboarding workflow directly from your app code:

import { useModelNex } from '@modelnex/sdk';

function SetupButton() {
  const { startWorkFlow } = useModelNex();

  return (
    <button onClick={() => void startWorkFlow('FLOW_ID')}>
      Start Workspace Setup
    </button>
  );
}

This requires a mounted guided playback UI such as ModelNexChatBubble or ModelNexOnboardingPanel.

In the dashboard, this trigger is labeled "Manual or Search" because the same workflows can also be surfaced from chat-bubble search/conversation flows.

Custom UI

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

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.