@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
• 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

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.

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

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.