@getjai/ragagent-typescript-client

Type-safe TypeScript client for RagAgent MCP Protocol with full support for WhatsApp messaging, knowledge base operations, and multi-tenant architecture.

🚀 Quick Start

Installation

npm install @getjai/ragagent-typescript-client

Basic Usage

import { TypedMCPClient } from '@getjai/ragagent-typescript-client';
import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';

// Initialize the client
const client = new TypedMCPClient({
  name: 'MyApp',
  version: '1.0.0'
});

// Connect to RagAgent MCP server
const transport = new Transport(/* your transport config */);
await client.connect(transport);

// Send a WhatsApp message with full type safety
const result = await client.sendWhatsAppMessage({
  user_phone_number: '+5511999999999',
  agent_phone_number: '+5511888888888',
  message: 'Hello from RagAgent!'
});

console.log('Message sent:', result);

📋 Features

• Full Type Safety: Complete TypeScript support with auto-completion
• MCP Protocol: Built on Model Context Protocol for reliable communication
• WhatsApp Integration: Send messages, images, buttons, and interactive content
• Knowledge Base: Query and search ontology-based knowledge systems
• Multi-tenant: Support for multiple tenant configurations
• Campaign Management: Create and manage WhatsApp campaigns
• Analytics: Access messaging and conversation analytics

🔧 API Reference

Core Client

TypedMCPClient

const client = new TypedMCPClient({
  name: 'YourAppName',
  version: '1.0.0'
});

WhatsApp Messaging

Send Text Message

await client.sendWhatsAppMessage({
  user_phone_number: '+5511999999999',
  agent_phone_number: '+5511888888888',
  message: 'Your message here'
});

Send Image Message

await client.sendWhatsAppImage({
  user_phone_number: '+5511999999999',
  agent_phone_number: '+5511888888888',
  image_url: 'https://example.com/image.jpg',
  caption: 'Optional caption'
});

Send Interactive Buttons

await client.sendWhatsAppButtons({
  user_phone_number: '+5511999999999',
  agent_phone_number: '+5511888888888',
  header_text: 'Choose an option',
  body_text: 'Please select one of the options below:',
  footer_text: 'Powered by RagAgent',
  buttons: [
    { type: 'reply', reply: { id: 'btn1', title: 'Option 1' } },
    { type: 'reply', reply: { id: 'btn2', title: 'Option 2' } }
  ]
});

Knowledge Base Operations

Query Ontology

const knowledge = await client.queryKnowledgeBase({
  uri: 'http://example.com/ontology#concept',
  tenant_id: 'your-tenant-id',
  depth: 2
});

Search Knowledge Base

const results = await client.searchKnowledgeBase({
  query: 'search term',
  tenant_id: 'your-tenant-id'
});

Conversation Management

List Active Conversations

const conversations = await client.listActiveConversations({
  tenant_id: 'your-tenant-id',
  status: 'active',
  limit: 50
});

🛠️ Advanced Usage

Custom Tool Calls

For tools not covered by convenience methods, use the generic callTool method:

const result = await client.callTool({
  name: 'custom_tool_name',
  arguments: {
    param1: 'value1',
    param2: 'value2'
  }
});

Error Handling

try {
  const result = await client.sendWhatsAppMessage({
    user_phone_number: '+5511999999999',
    agent_phone_number: '+5511888888888',
    message: 'Hello!'
  });
  
  if (result.isError) {
    console.error('Tool execution failed:', result.content);
  } else {
    console.log('Success:', result.content);
  }
} catch (error) {
  console.error('Connection error:', error);
}

Connection Management

// Connect
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

// Disconnect when done
await client.disconnect();

📦 Type Definitions

The package includes comprehensive TypeScript definitions for all RagAgent tools and parameters:

import type {
  SendTextMessageRequest,
  SendImageMessageRequest,
  QueryOntologyRequest,
  SearchOntologyRequest,
  MCPToolResponse
} from '@getjai/ragagent-typescript-client/types';

🔗 Integration Examples

Next.js Integration

// pages/api/send-message.ts
import { TypedMCPClient } from '@getjai/ragagent-typescript-client';

export default async function handler(req, res) {
  const client = new TypedMCPClient({ name: 'NextJS-App', version: '1.0.0' });
  
  try {
    await client.connect(/* your transport */);
    
    const result = await client.sendWhatsAppMessage({
      user_phone_number: req.body.phone,
      agent_phone_number: process.env.AGENT_PHONE,
      message: req.body.message
    });
    
    res.json({ success: true, result });
  } catch (error) {
    res.status(500).json({ error: error.message });
  } finally {
    await client.disconnect();
  }
}

Express.js Integration

import express from 'express';
import { TypedMCPClient } from '@getjai/ragagent-typescript-client';

const app = express();
const client = new TypedMCPClient({ name: 'Express-App', version: '1.0.0' });

app.post('/send-message', async (req, res) => {
  try {
    const result = await client.sendWhatsAppMessage(req.body);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

🏗️ Development

Building from Source

# Clone the repository
git clone https://github.com/ragagent/typescript-client.git
cd typescript-client

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run linting
npm run lint

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues
• Documentation
• Discord Community

🔄 Changelog

v1.0.0

• Initial release
• Full TypeScript support
• Complete MCP protocol implementation
• WhatsApp messaging capabilities
• Knowledge base operations
• Multi-tenant support