npm package: @getjai/ragagent-typescript-client
Description: Complete TypeScript client library for RagAgent with MCP and REST API support
Author: RagAgent Team
Latest version: 1.2.0

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

```bash
npm install @getjai/ragagent-typescript-client
```

### Basic Usage

```typescript
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`

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

### WhatsApp Messaging

#### Send Text Message

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

#### Send Image Message

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

#### Send Interactive Buttons

```typescript
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

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

#### Search Knowledge Base

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

### Conversation Management

#### List Active Conversations

```typescript
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:

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

### Error Handling

```typescript
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

```typescript
// 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:

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

## 🔗 Integration Examples

### Next.js Integration

```typescript
// 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

```typescript
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

```bash
# 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](LICENSE) file for details.

## 🆘 Support

- [GitHub Issues](https://github.com/ragagent/typescript-client/issues)
- [Documentation](https://docs.ragagent.com)
- [Discord Community](https://discord.gg/ragagent)

## 🔄 Changelog

### v1.0.0
- Initial release
- Full TypeScript support
- Complete MCP protocol implementation
- WhatsApp messaging capabilities
- Knowledge base operations
- Multi-tenant support