Spirit Bot Widget

A type-safe widget library for integrating Spirit Bot into React and React Native applications. Published as a single package with platform-specific exports.

Installation

npm install @echortech/bot-widget

Peer dependencies (install what your platform needs):

# Web
npm install react react-dom

# Mobile
npm install react react-native

Quick Start

React (Web)

import { ChatWidget, GreetingPopup } from '@echortech/bot-widget';

export function App() {
  return (
    <ChatWidget
      jwtToken={userToken}
      firmId={firmId}
      botUrl="https://spirit-bot-service.example.com"
      onError={(err) => console.error(err)}
    />
  );
}

React Native (Mobile)

import { ChatWidget, GreetingModal } from '@echortech/bot-widget/native';

export function App() {
  return (
    <ChatWidget
      jwtToken={userToken}
      firmId={firmId}
      botUrl="https://spirit-bot-service.example.com"
      height={500}
      onError={(err) => console.error(err)}
    />
  );
}

Core Only (API Client / Types)

import { BotAPIClient } from '@echortech/bot-widget/core';

const client = new BotAPIClient(botUrl, jwtToken, firmId);
const response = await client.sendMessage('Hello', chatId);

Exports

| Import Path | What You Get | |-------------|-------------| | @echortech/bot-widget | React web components + core (types, API client, utils) | | @echortech/bot-widget/native | React Native components + core | | @echortech/bot-widget/core | Core only (types, BotAPIClient, utilities) |

Components

Web (@echortech/bot-widget)

• ChatWidget — Full chat interface with message history, auto-scroll, loading states, error display
• GreetingPopup — Contextual greeting notifications with priority badges and action buttons

Mobile (@echortech/bot-widget/native)

• ChatWidget — Mobile-optimized chat with KeyboardAvoidingView and gesture-friendly input
• GreetingModal — Modal-based greeting with TouchableOpacity actions

Configuration (All Components)

interface BotWidgetConfig {
  jwtToken: string;          // JWT token for authentication
  firmId: string;            // Firm ID header
  botUrl: string;            // Base URL of Spirit Bot Service
  chatId?: number;           // Chat session ID (default: 1001)
  filingId?: string;         // Optional filing context
  taxYear?: number;          // Optional tax year context
  onError?: (error: BotAPIError) => void;
  onSuccess?: (response: any) => void;
}

API Client

The BotAPIClient handles all HTTP communication with the Spirit Bot Service:

| Method | Endpoint | Description | |--------|----------|-------------| | sendMessage(message, chatId, context?) | POST /chat | Send message, get bot response | | getGreeting() | POST /greet | Get contextual greeting | | getDocumentsNeeded(chatId) | GET /filing/documents-needed | List required documents | | getFormPath(chatId) | GET /filing/form-path | Get smart form structure | | startIntake() | POST /filing/intake/start | Start intake questionnaire | | answerIntakeQuestion(sessionId, answer) | POST /filing/intake/answer | Answer intake question | | getProfile(chatId) | GET /filing/profile | Get user profile | | healthCheck() | GET /health | Service health check |

Authentication: JWT token in Authorization: Bearer header, firm ID in x-firm-id header — handled automatically.

Development

pnpm install          # Install dependencies
pnpm build            # Build web + native
pnpm build:web        # Build web only
pnpm build:native     # Build native only
pnpm test             # Run all tests (vitest + jest)
pnpm test:web         # Run web + core tests only
pnpm test:native      # Run React Native tests only
pnpm type-check       # TypeScript type checking
pnpm dev              # Watch mode

Project Structure

src/
  core/       # Types, BotAPIClient, utility functions (shared by both platforms)
  web/        # React components + CSS (ChatWidget, GreetingPopup)
  native/     # React Native components (ChatWidget, GreetingModal)

Both platforms compile separately (tsconfig.web.json / tsconfig.native.json) to handle different JSX modes, then output to dist/web/ and dist/native/.

License

MIT