npm package: @omniai/sdk
Description: Official Node.js SDK for OmniAI API
Author: OmniAI Team
Latest version: 1.0.1

# OmniAI Node.js SDK

Official Node.js/TypeScript SDK for the OmniAI API - Multi-channel messaging platform with AI automation.

## Installation

```bash
npm install @omniai/sdk
```

## Quick Start

```typescript
import { Client } from '@omniai/sdk';

// Initialize client
const client = new Client({ apiKey: 'YOUR_API_KEY' });

// Send a message
const message = await client.messages.send({
  phone: '+5511999999999',
  channel: 'whatsapp',
  type: 'text',
  content: 'Olá! Como posso ajudar?'
});

console.log(`Message sent: ${message.id}`);
```

## Features

- **Full TypeScript support** - Complete type definitions
- **Multi-channel messaging** - WhatsApp, Email, SMS, Telegram
- **Contact management** - Create, update, search contacts
- **Campaign automation** - Schedule and manage marketing campaigns
- **AI-powered features** - Chat completions, sentiment analysis, intent detection
- **Analytics & Reports** - Get insights and export reports
- **Error handling** - Comprehensive error classes
- **Promise-based** - Modern async/await API

## Usage Examples

### Send Messages

```typescript
// Text message
const message = await client.messages.send({
  phone: '+5511999999999',
  channel: 'whatsapp',
  type: 'text',
  content: 'Hello from OmniAI!'
});

// Media message
const mediaMessage = await client.messages.send({
  phone: '+5511999999999',
  channel: 'whatsapp',
  type: 'image',
  content: 'Check this image',
  mediaUrl: 'https://example.com/image.jpg'
});

// Bulk send
const result = await client.messages.sendBulk({
  messages: [
    {
      phone: '+5511999999999',
      channel: 'whatsapp',
      type: 'text',
      content: 'Message 1'
    },
    {
      phone: '+5511888888888',
      channel: 'whatsapp',
      type: 'text',
      content: 'Message 2'
    }
  ]
});
```

### Manage Contacts

```typescript
// Create contact
const contact = await client.contacts.create({
  name: 'João Silva',
  phone: '+5511999999999',
  email: 'joao@example.com',
  tags: ['customer', 'vip']
});

// List contacts
const contacts = await client.contacts.list({
  page: 1,
  limit: 50,
  search: 'João'
});

// Update contact
const updated = await client.contacts.update('contact-123', {
  tags: ['customer', 'vip', 'premium']
});
```

### Create Campaigns

```typescript
const campaign = await client.campaigns.create({
  name: 'Black Friday 2024',
  channel: 'whatsapp',
  messageTemplate: 'Aproveite 50% OFF em todos os produtos!',
  targetAudience: {
    tags: ['customer'],
    segment: 'active'
  },
  scheduledAt: '2024-11-29T09:00:00Z'
});

// Start campaign
await client.campaigns.start(campaign.id);
```

### AI Features

```typescript
// Chat completion
const response = await client.ai.chatCompletion({
  messages: [
    { role: 'user', content: 'Preciso de ajuda com meu pedido' }
  ]
});

// Sentiment analysis
const sentiment = await client.ai.analyzeSentiment({
  text: 'Estou muito satisfeito com o atendimento!'
});
console.log(sentiment.sentiment); // 'positive'

// Intent detection
const intent = await client.ai.extractIntent({
  text: 'Quero cancelar minha assinatura'
});
console.log(intent.intent); // 'cancel_subscription'

// Generate response
const suggestion = await client.ai.generateResponse({
  context: 'Cliente perguntou sobre prazo de entrega',
  userMessage: 'Quando chega meu pedido?',
  tone: 'professional'
});
```

### Analytics

```typescript
// Get overview
const analytics = await client.analytics.getOverview({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  channel: 'whatsapp'
});

// Export report
const exportData = await client.analytics.exportReport({
  reportType: 'messages',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  format: 'pdf'
});
console.log(exportData.downloadUrl);
```

## Error Handling

```typescript
import {
  Client,
  AuthenticationError,
  ValidationError,
  RateLimitError
} from '@omniai/sdk';

const client = new Client({ apiKey: 'YOUR_API_KEY' });

try {
  const message = await client.messages.send({
    phone: '+5511999999999',
    channel: 'whatsapp',
    type: 'text',
    content: 'Hello!'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, please wait');
  }
}
```

## Configuration

```typescript
// Custom configuration
const client = new Client({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.omniaiassist.com/v1',
  timeout: 30000 // 30 seconds
});
```

## TypeScript Support

This SDK is written in TypeScript and includes complete type definitions:

```typescript
import { Client, Message, Contact, Campaign } from '@omniai/sdk';

const client = new Client({ apiKey: 'YOUR_API_KEY' });

// Full type inference
const message: Message = await client.messages.send({
  phone: '+5511999999999',
  channel: 'whatsapp',
  type: 'text',
  content: 'Hello!'
});

// Auto-completion and type checking
message.id; // string
message.status; // MessageStatus
message.createdAt; // string
```

## API Reference

### Messages
- `messages.send(params)` - Send message
- `messages.get(messageId)` - Get message by ID
- `messages.list(params?)` - List messages
- `messages.sendBulk(params)` - Send multiple messages

### Contacts
- `contacts.create(params)` - Create contact
- `contacts.get(contactId)` - Get contact by ID
- `contacts.list(params?)` - List contacts
- `contacts.update(contactId, params)` - Update contact
- `contacts.delete(contactId)` - Delete contact

### Campaigns
- `campaigns.create(params)` - Create campaign
- `campaigns.get(campaignId)` - Get campaign
- `campaigns.list(params?)` - List campaigns
- `campaigns.start(campaignId)` - Start campaign
- `campaigns.pause(campaignId)` - Pause campaign
- `campaigns.delete(campaignId)` - Delete campaign

### AI
- `ai.chatCompletion(params)` - Chat completion
- `ai.analyzeSentiment(params)` - Sentiment analysis
- `ai.extractIntent(params)` - Intent detection
- `ai.generateResponse(params)` - Generate response

### Analytics
- `analytics.getOverview(params)` - Get overview
- `analytics.getMessagesStats(params)` - Messages stats
- `analytics.getAIStats(params)` - AI stats
- `analytics.exportReport(params)` - Export report

## Requirements

- Node.js >= 14.0.0
- axios >= 1.6.0

## License

MIT License - see LICENSE file for details

## Support

- Documentation: https://omniai.belizatech.com.br/support/documentation
- GitHub Issues: https://github.com/omniaiassist/omniai-nodejs-sdk/issues
- Email: support@omniaiassist.com