Libby Chatbot API Client

TypeScript/JavaScript client for the Libby AI chatbot API. Libby is a specialized AI librarian agent with deep expertise in DominKnow products and learning content authoring.

Features

✨ Full TypeScript support with complete type definitions
🚀 Simple API - Easy to use, hard to misuse
💬 Conversation management - Create and continue conversations
📝 Message history - Retrieve past conversations
⭐ Feedback support - Submit ratings and comments
🔒 Type-safe - Catch errors at compile time

Installation

npm install @dominknow/libby-client

Quick Start

import { ChatbotAPIClient, Rating } from '@dominknow/libby-client';

// Create client instance
const client = new ChatbotAPIClient(
    'https://your-api-url.com/libby',
    'optional-auth-token'
);

// Start a new conversation
const response = await client.sendMessage(
    { message: 'What is DominKnow Flow?' },
    'user-123'
);

console.log(response.agentMessage.content);

// Continue the conversation
const followUp = await client.sendMessage(
    {
        conversationId: response.conversation.id,
        message: 'Tell me more about responsive design'
    },
    'user-123'
);

API Reference

Constructor

new ChatbotAPIClient(baseUrl?: string, userToken?: string)

Parameters:

• baseUrl (optional) - API base URL. Defaults to https://mcp.sandbox.dominknow.one/libby
• userToken (optional) - Authentication token for the user

Send Message

Send a message to Libby and receive a response.

sendMessage(request: SendMessageRequest, userId: string): Promise<SendMessageResponse>

Parameters:

• request.message - The message text to send
• request.conversationId (optional) - ID of existing conversation to continue
• userId - ID of the user sending the message

Returns: Promise containing the conversation, user message, and agent response

Example:

// Start new conversation
const response = await client.sendMessage(
    { message: 'How do I create a quiz in Flow?' },
    'user-123'
);

// Continue existing conversation
const followUp = await client.sendMessage(
    {
        conversationId: response.conversation.id,
        message: 'Can I add images to quiz questions?'
    },
    'user-123'
);

Get Conversation

Retrieve a conversation and all its messages.

getConversation(request: GetConversationRequest): Promise<GetConversationResponse>

Parameters:

• request.conversationId - ID of the conversation to retrieve

Returns: Promise containing the conversation and all messages

Example:

const conversation = await client.getConversation({
    conversationId: 'conv-123'
});

console.log(`Total messages: ${conversation.messages.length}`);
conversation.messages.forEach(msg => {
    console.log(`${msg.role}: ${msg.content}`);
});

List Conversations

List all conversations for a user with optional pagination.

listConversations(request: ListConversationsRequest): Promise<ListConversationsResponse>

Parameters:

• request.userId - ID of the user
• request.limit (optional) - Maximum number of conversations to return
• request.offset (optional) - Number of conversations to skip

Returns: Promise containing conversations array and total count

Example:

// Get all conversations
const all = await client.listConversations({
    userId: 'user-123'
});

// Get with pagination
const page = await client.listConversations({
    userId: 'user-123',
    limit: 10,
    offset: 0
});

console.log(`Showing ${page.conversations.length} of ${page.total} conversations`);

Submit Message Feedback

Submit feedback for a specific message.

submitMessageFeedback(request: SubmitMessageFeedbackRequest): Promise<SubmitMessageFeedbackResponse>

Parameters:

• request.messageId - ID of the message
• request.feedback - Feedback type (FeedbackType.GOOD or FeedbackType.BAD)
• request.comment (optional) - Text comment explaining the feedback

Returns: Promise containing the updated message

Example:

import { FeedbackType } from '@dominknow/libby-client';

await client.submitMessageFeedback({
    messageId: 'msg-123',
    feedback: FeedbackType.GOOD,
    comment: 'Very helpful response!'
});

Submit Conversation Feedback

Submit overall feedback for an entire conversation.

submitConversationFeedback(request: SubmitConversationFeedbackRequest): Promise<SubmitConversationFeedbackResponse>

Parameters:

• request.conversationId - ID of the conversation
• request.rating - Rating from 1-5 (use Rating enum)
• request.comment (optional) - Text comment about the conversation

Returns: Promise containing the updated conversation

Example:

import { Rating } from '@dominknow/libby-client';

await client.submitConversationFeedback({
    conversationId: 'conv-123',
    rating: Rating.FIVE,
    comment: 'Excellent support experience!'
});

TypeScript Types

Message Types

enum MessageRole {
    USER = 'USER',
    AGENT = 'AGENT'
}

interface UserMessage {
    role: MessageRole.USER;
    id: string;
    conversationId: string;
    timestamp: string;
    content: string;
}

interface AgentMessage {
    role: MessageRole.AGENT;
    id: string;
    conversationId: string;
    timestamp: string;
    content: string;
    reasoningText?: string;
    feedback?: MessageFeedback;
}

type Message = UserMessage | AgentMessage;

Conversation Type

interface Conversation {
    id: string;
    userId: string;
    createdAt: string;
    updatedAt: string;
    title?: string;
    feedback?: ConversationFeedback;
}

Feedback Types

enum FeedbackType {
    GOOD = 'GOOD',
    BAD = 'BAD'
}

enum Rating {
    ONE = 1,
    TWO = 2,
    THREE = 3,
    FOUR = 4,
    FIVE = 5
}

interface MessageFeedback {
    type: FeedbackType;
    comment?: string;
    timestamp: string;
}

interface ConversationFeedback {
    rating: Rating;
    comment?: string;
    timestamp: string;
}

Complete Example

import { 
    ChatbotAPIClient, 
    Rating,
    FeedbackType 
} from '@dominknow/libby-client';

async function chatWithLibby() {
    // Initialize client
    const client = new ChatbotAPIClient();
    const userId = 'user-123';

    // Start conversation
    console.log('Starting conversation...');
    const firstMessage = await client.sendMessage(
        { message: 'What is DominKnow Flow?' },
        userId
    );

    console.log('Libby:', firstMessage.agentMessage.content);

    // Continue conversation
    const followUp = await client.sendMessage(
        {
            conversationId: firstMessage.conversation.id,
            message: 'How do I publish a project?'
        },
        userId
    );

    console.log('Libby:', followUp.agentMessage.content);

    // Get full conversation history
    const history = await client.getConversation({
        conversationId: firstMessage.conversation.id
    });

    console.log(`Total messages: ${history.messages.length}`);

    // Submit feedback
    await client.submitConversationFeedback({
        conversationId: firstMessage.conversation.id,
        rating: Rating.FIVE,
        comment: 'Very helpful!'
    });

    // List all conversations
    const conversations = await client.listConversations({ userId });
    console.log(`Total conversations: ${conversations.total}`);
}

chatWithLibby().catch(console.error);

Error Handling

The client throws errors for failed API requests. Always wrap calls in try-catch blocks:

try {
    const response = await client.sendMessage(
        { message: 'Hello!' },
        'user-123'
    );
    console.log(response.agentMessage.content);
} catch (error) {
    console.error('API Error:', error.message);
}

Environment Configuration

You can configure the API URL using environment variables or constructor parameters:

// Option 1: Constructor parameter
const client = new ChatbotAPIClient('https://api.example.com/libby');

// Option 2: Default sandbox environment
const client = new ChatbotAPIClient(); // Uses sandbox by default

License

MIT

Support

For issues and questions, please visit the GitHub repository.