Eliciteer Chat SDK

A lightweight TypeScript SDK for conducting AI-powered interviews with Eliciteer.

Installation

npm install eliciteer-chat-sdk
# or
yarn add eliciteer-chat-sdk
# or
pnpm add eliciteer-chat-sdk

Quick Start

Vanilla JavaScript/TypeScript

import { EliciteerClient } from 'eliciteer-chat-sdk';

const client = new EliciteerClient();
// or with custom URL:
// const client = new EliciteerClient({ baseUrl: 'https://your-backend.com' });

// Load an interview by ID
const interview = await client.getInterview('interview-id');
console.log(interview.briefing);
console.log(interview.clientName);

// Send messages
let response = await client.sendMessage('interview-id', 'Hello, I am ready!');
console.log(response.response); // AI's reply

while (!response.isComplete) {
  const userInput = await getUserInput(); // Your input method
  response = await client.sendMessage('interview-id', userInput);
  console.log(response.response);
}

console.log('Interview complete!', response.interviewSummary);

React

import { EliciteerProvider, useInterview } from 'eliciteer-chat-sdk/react';

// Wrap your app with the provider
function App() {
  return (
    <EliciteerProvider config={{}}>
      <InterviewPage interviewId="abc-123" />
    </EliciteerProvider>
  );
}

// Use the hook in your components
function InterviewPage({ interviewId }) {
  const {
    interview,
    messages,
    isLoading,
    isInitializing,
    isComplete,
    error,
    progress,
    uiOptions,
    sendMessage,
  } = useInterview(interviewId);

  const [input, setInput] = useState('');

  if (isInitializing) {
    return <div>Loading...</div>;
  }

  if (isComplete) {
    return (
      <div>
        <h1>Thank you!</h1>
        {interview?.interviewSummary && <p>{interview.interviewSummary}</p>}
      </div>
    );
  }

  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!input.trim()) return;
    setInput('');
    await sendMessage(input);
  };

  return (
    <div>
      {/* Progress */}
      <div>Topic {progress.current + 1} of {progress.total}</div>

      {/* Messages */}
      <div>
        {messages.map((msg, i) => (
          <div key={i} className={msg.role}>
            {msg.content}
          </div>
        ))}
      </div>

      {/* Input */}
      {uiOptions?.type === 'boolean' ? (
        <div>
          <button onClick={() => sendMessage('Yes')} disabled={isLoading}>
            Yes
          </button>
          <button onClick={() => sendMessage('No')} disabled={isLoading}>
            No
          </button>
        </div>
      ) : (
        <form onSubmit={handleSubmit}>
          <input
            value={input}
            onChange={(e) => setInput(e.target.value)}
            disabled={isLoading}
          />
          <button type="submit" disabled={isLoading}>
            Send
          </button>
        </form>
      )}
    </div>
  );
}

API Reference

EliciteerClient

The main client for interacting with the Eliciteer API.

const client = new EliciteerClient({
  baseUrl?: string;     // Optional: Backend URL (default: 'https://api.eliciteer.ai')
  debug?: boolean;      // Optional: Enable debug logging (default: false)
  timeout?: number;     // Optional: Request timeout in ms (default: 30000)
  retries?: number;     // Optional: Number of retry attempts (default: 3)
  fetch?: typeof fetch; // Optional: Custom fetch implementation
});

Methods

getInterview(interviewId: string): Promise<Interview>

Load an interview by ID.

const interview = await client.getInterview('abc-123');

sendMessage(interviewId: string, message: string, options?: ChatOptions): Promise<ChatResponse>

Send a message in the interview.

const response = await client.sendMessage('abc-123', 'Hello!');
console.log(response.response);     // AI's reply
console.log(response.isComplete);   // Whether interview is done
console.log(response.uiOptions);    // UI hints (text or boolean input)

React Hooks

useInterview(interviewId: string, options?: UseInterviewOptions)

Main hook for conducting interviews.

const {
  interview,      // Interview state
  messages,       // Message array
  isLoading,      // Request in progress
  isInitializing, // Initial load
  isComplete,     // Interview done
  error,          // Error if any
  notFound,       // 404 status
  progress,       // { current, total }
  uiOptions,      // Input type hints
  debugInfo,      // Debug data (if enabled)
  sendMessage,    // Send a message
  reload,         // Reload interview
} = useInterview(interviewId, {
  debug: false,                    // Enable debug info
  onComplete: (summary) => {},     // Completion callback
  onError: (error) => {},          // Error callback
});

Types

Interview

interface Interview {
  interviewId: string;
  topicId: string;
  briefing: string;
  clientName?: string;
  status: 'in_progress' | 'completed';
  messages: Message[];
  plan: TopicPlan[];
  currentTopicIndex: number;
  collectedInfo: string;
  interviewSummary?: string;
  createdAt: string;
  completedAt?: string;
}

ChatResponse

interface ChatResponse {
  response: string;
  status: 'continue' | 'completed';
  isComplete: boolean;
  interviewSummary?: string;
  currentTopicIndex: number;
  totalTopics: number;
  uiOptions?: UIOptions;
  debugInfo?: DebugInfo;
}

UIOptions

interface UIOptions {
  type: 'text' | 'boolean';
  options?: string[];
}

Error Handling

The SDK provides typed errors for common scenarios:

import {
  EliciteerError,
  NotFoundError,
  NetworkError,
  TimeoutError,
} from 'eliciteer-chat-sdk';

try {
  await client.sendMessage(interviewId, message);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Interview not found');
  } else if (error instanceof NetworkError) {
    console.log('Network issue');
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

Getting an Interview ID

Interview IDs are created through the Eliciteer platform. To get an interview ID programmatically, call your backend's topic start endpoint:

// This is NOT part of the SDK - call your backend directly
const response = await fetch('https://your-backend.com/topic/{topicId}/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ participantName: 'John Doe' }),
});
const { interview_id } = await response.json();

// Now use the SDK
const { messages, sendMessage } = useInterview(interview_id);

License

Apache-2.0