npm package: @kirimchat/sdk
Description: TypeScript SDK for KirimChat Public API
Author: KirimChat
Latest version: 1.0.1

# @kirimchat/sdk

TypeScript SDK for KirimChat Public API - Send messages via WhatsApp, Instagram, and Messenger.

[![npm version](https://badge.fury.io/js/@kirimchat%2Fsdk.svg)](https://www.npmjs.com/package/@kirimchat/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

✅ Full TypeScript support with auto-generated types  
✅ WhatsApp, Instagram, and Messenger messaging  
✅ Template messages with variables  
✅ Interactive messages (buttons, lists)  
✅ Customer management  
✅ Native `fetch` API (Node.js 18+, browser)  
✅ ESM + CJS dual build  

## Installation

```bash
npm install @kirimchat/sdk
# or
pnpm add @kirimchat/sdk
# or
yarn add @kirimchat/sdk
```

## Requirements

- Node.js >= 18.0.0 (for native `fetch` support)
- KirimChat API key (get it from [dashboard](https://app.kirim.chat/settings/developers))

## Quick Start

```typescript
import { sendMessage, client } from '@kirimchat/sdk'

// Configure SDK
client.setConfig({
  baseUrl: 'https://api-prod.kirim.chat/api/v1/public',
  headers: {
    Authorization: 'Bearer kc_live_your_api_key_here'
  }
})

// Send a WhatsApp message
const result = await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'text',
    content: 'Hello from KirimChat SDK!'
  }
})

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

## Usage

### Configuration

```typescript
import { client } from '@kirimchat/sdk'

client.setConfig({
  baseUrl: 'https://api-prod.kirim.chat/api/v1/public',
  headers: {
    Authorization: 'Bearer kc_live_your_api_key_here',
    'X-Custom-Header': 'value' // Optional: additional headers
  }
})
```

### Customer Management

```typescript
import { createCustomer, getCustomerById, getCustomerByPhone, listCustomers } from '@kirimchat/sdk'

// Create a customer
const customer = await createCustomer({
  body: {
    phone_number: '628123456789',
    name: 'John Doe',
    consent_status: true,
    tags: ['lead', 'website']
  }
})

// Get customer by ID
const customerById = await getCustomerById({
  path: { customerId: 'clxxx1234567890' }
})

// Get customer by phone number
const customerByPhone = await getCustomerByPhone({
  path: { phoneNumber: '628123456789' }
})

// List customers with filters
const customers = await listCustomers({
  query: {
    page: 1,
    limit: 20,
    consent_status: 'true',
    search: 'John',
    sort_by: 'created_at',
    sort_order: 'desc'
  }
})
```

### Sending Messages

#### Text Message

```typescript
import { sendMessage } from '@kirimchat/sdk'

await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'text',
    content: 'Hello, how can I help you?'
  }
})
```

#### Media Message

```typescript
await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'image',
    media_url: 'https://example.com/image.jpg',
    caption: 'Check out our latest product!'
  }
})
```

#### Interactive Message (Buttons)

```typescript
await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'interactive',
    interactive: {
      type: 'button',
      body: { text: 'How would you rate our service?' },
      action: {
        buttons: [
          { type: 'reply', reply: { id: 'good', title: 'Good' } },
          { type: 'reply', reply: { id: 'ok', title: 'Okay' } },
          { type: 'reply', reply: { id: 'bad', title: 'Bad' } }
        ]
      }
    }
  }
})
```

#### Interactive Message (List)

```typescript
await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'interactive',
    interactive: {
      type: 'list',
      body: { text: 'Please select a service' },
      action: {
        button: 'View Menu',
        sections: [
          {
            title: 'Services',
            rows: [
              { id: 'haircut', title: 'Haircut', description: 'Basic haircut' },
              { id: 'coloring', title: 'Hair Coloring', description: 'Full color' }
            ]
          }
        ]
      }
    }
  }
})
```

#### Template Message

```typescript
await sendMessage({
  body: {
    phone_number: '628123456789',
    channel: 'whatsapp',
    message_type: 'template',
    template: {
      name: 'order_confirmation',
      language: { code: 'id' },
      components: [
        {
          type: 'body',
          parameters: [
            { type: 'text', text: 'John Doe' },
            { type: 'text', text: 'INV-12345' }
          ]
        }
      ]
    }
  }
})
```

### Message Status

```typescript
import { getMessageStatus, markMessageAsRead } from '@kirimchat/sdk'

// Get message status
const status = await getMessageStatus({
  path: { messageId: 'msg_xyz789' }
})

// Mark message as read
await markMessageAsRead({
  path: { messageId: 'msg_xyz789' }
})
```

### Typing Indicator

```typescript
import { sendTypingIndicator } from '@kirimchat/sdk'

// Send typing indicator
await sendTypingIndicator({
  path: { customerIdentifier: '628123456789' },
  body: {
    channel: 'whatsapp'
  }
})
```

### Templates

```typescript
import { listTemplates, getTemplate } from '@kirimchat/sdk'

// List templates
const templates = await listTemplates({
  query: {
    status: 'APPROVED',
    category: 'MARKETING',
    limit: 100
  }
})

// Get specific template
const template = await getTemplate({
  path: { templateId: 'tmpl_xyz789' }
})
```

### Connected Accounts

```typescript
import { listInstagramAccounts, listMessengerPages } from '@kirimchat/sdk'

// List Instagram accounts
const igAccounts = await listInstagramAccounts()

// List Facebook Pages (Messenger)
const fbPages = await listMessengerPages()
```

## Error Handling

```typescript
import { sendMessage } from '@kirimchat/sdk'

try {
  await sendMessage({
    body: {
      phone_number: '628123456789',
      channel: 'whatsapp',
      message_type: 'text',
      content: 'Hello!'
    }
  })
} catch (error) {
  console.error('API Error:', error)
}
```

## Examples

See the [examples](./examples) directory for more usage examples:

- [basic-usage.ts](./examples/basic-usage.ts) - Health check and listing customers
- [send-message.ts](./examples/send-message.ts) - Sending text, media, and interactive messages
- [customer-management.ts](./examples/customer-management.ts) - Creating and managing customers
- [template-message.ts](./examples/template-message.ts) - Sending WhatsApp template messages

## API Reference

Full API documentation: https://docs.kirim.chat

## Development

```bash
# Install dependencies
pnpm install

# Generate SDK from OpenAPI spec
pnpm generate

# Type check
pnpm typecheck

# Build
pnpm build
```

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

MIT © KirimChat

## Support

- Documentation: https://docs.kirim.chat
- Email: support@kirim.chat
- Website: https://kirim.chat