npm package: @kortex-ai/hub-client
Description: Official TypeScript/JavaScript client for Kortex Hub API
Author: Kortex
Latest version: 1.1.0

# @kortex-ai/hub-client

Official TypeScript client for the Kortex Hub API.

## Features

- **Type-safe** - Full TypeScript support with comprehensive type definitions
- **Never throws** - All methods return `Result` types for safe error handling
- **Modern** - Works in Node.js, Deno, Bun, and browsers

## Installation

```bash
pnpm add @kortex-ai/hub-client
```

## Quick Start

```typescript
import { KortexClient } from '@kortex-ai/hub-client'

const client = new KortexClient({
  organizationToken: 'your-organization-token',
})

const { data, error } = await client.sendTemplate({
  waId: '1234567890',
  template: { name: 'welcome_message', language: 'ro' },
})

if (error) {
  console.error('Error:', error.message)
  return
}

console.log('Success:', data)
```

## API Reference

### `assignTags(payload)`

Assign tags to a conversation.

```typescript
await client.assignTags({
  waId: '1234567890',
  tags: ['important', 'vip'],
})
```

- `waId` (string, required) - WhatsApp ID
- `tags` (string[], required) - Tag names to assign

---

### `sendNotification(payload)`

Send notifications through specified channels.

```typescript
await client.sendNotification({
  sendOptions: ['dashboard', 'email'],
  notification: {
    category: 'general',
    title: 'Update Available',
    message: 'Version 2.0 is out!',
    link: 'https://example.com',
  },
})
```

- `sendOptions` (`('dashboard' | 'email' | 'push')[]`, required) - Delivery channels
- `notification` (BareNotification, required) - Notification details with category, title, message

---

### `sendTemplate(payload)`

Send a WhatsApp template message with optional AI history tracking.

```typescript
await client.sendTemplate({
  waId: '1234567890',
  template: {
    name: 'order_confirmation',
    language: 'ro',
    body_variables: ['John', '#12345'],
    header_variable: 'Welcome!',
    button_variables: ['https://track.example.com/12345'],
  },
  aiHistory: {
    userMessages: ['I want to place an order'],
    assistantMessages: ['Your order has been confirmed'],
    toolSlugs: ['CREATE_ORDER:SHOPIFY'],
  },
  clientName: 'John Doe',
})
```

- `waId` (string, required) - WhatsApp ID
- `template.name` (string, required) - Template name
- `template.language` (string, optional) - Language code (default: `ro`)
- `template.body_variables` (string[], optional) - Variables for body `{{1}}`, `{{2}}`, etc.
- `template.header_variable` (string, optional) - Single variable for header `{{1}}`
- `template.button_variables` (string[], optional) - URL button variables (max 2)
- `aiHistory` (object, optional) - AI history to append after sending
  - `userMessages` (string[], optional) - User messages to append
  - `assistantMessages` (string[], optional) - Assistant messages to append (the rendered template text is automatically added as the last assistant message)
  - `toolSlugs` (string[], optional) - Tool slugs to mark as executed
- `clientName` (string, optional) - Client name for conversation upsert

---

### `addNote(payload)`

Add an internal note to a conversation (does not send a WhatsApp message).

```typescript
await client.addNote({
  waId: '1234567890',
  noteText: 'Customer asked for delivery window after 6 PM',
  clientName: 'John Doe',
})
```

- `waId` (string, required) - WhatsApp ID
- `noteText` (string, required) - Note content
- `clientName` (string, optional) - Client name for conversation upsert

---

### `stopConversationAi(payload)`

Stop or start AI for a conversation.

```typescript
await client.stopConversationAi({
  waId: '1234567890',
  stopAi: true,
})
```

- `waId` (string, required) - WhatsApp ID
- `stopAi` (boolean, required) - `true` to stop AI, `false` to start

---

### `upsertConversation(payload)`

Create or update a conversation.

```typescript
const { data } = await client.upsertConversation({
  waId: '1234567890',
  clientName: 'John Doe',
})

console.log(data) // ConversationWithTags
```

- `waId` (string, required) - WhatsApp ID
- `clientName` (string, required) - Client name

**Returns:** `{ message: string, data: ConversationWithTags }`

---

## Error Handling

All methods return `Result<T, KortexAPIError>` and never throw.

```typescript
const { data, error } = await client.sendTemplate({ ... })

if (error) {
  console.error('Failed:', error.message)
  return
}

console.log('Success:', data)
```

## License

MIT