npm package: @supsis/supsis-js
Description: Supsis API SDK - Browser ve Node.js için omnichannel messaging, chatbot, automation, task, ticket ve voice agent entegrasyonu
Author: Supsis Ai
Latest version: 1.2.2

# Supsis JS SDK

Supsis API'sine browser ve Node.js ortamlarından erişim sağlayan JavaScript SDK.

## Özellikler

- 🌐 **Çoklu Platform**: Browser (UMD) ve Node.js (CommonJS/ESM) desteği
- 📝 **TypeScript Desteği**: Tam TypeScript declaration dosyaları
- 🔒 **Güvenli**: Token tabanlı authentication
- 🔄 **Otomatik Retry**: Başarısız isteklerde otomatik yeniden deneme
- 📦 **Modüler**: Sadece ihtiyacınız olan modülleri kullanın
- 🤖 **LLM-Friendly**: Detaylı JSDoc açıklamaları

## Kurulum

### npm

```bash
npm install @supsis/supsis-js
```

### CDN

```html
<!-- Latest -->
<script src="https://static.supsis.live/supsis-js/latest/supsis.min.js"></script>

<!-- Specific version -->
<script src="https://static.supsis.live/supsis-js/1.0.0/supsis.min.js"></script>
```

## Hızlı Başlangıç

### Browser

```html
<script src="https://static.supsis.live/supsis-js/latest/supsis.min.js"></script>
<script>
  const supsis = new SupsisJS({
    email: 'user@example.com',
    password: 'secret',
    siteId: 'site123'
  });
  
  supsis.connect().then(async () => {
    const chats = await supsis.chat.list({ status: 'active' });
    console.log(chats);
  });
</script>
```

### Node.js (CommonJS)

```javascript
const { SupsisJS } = require('@supsis/supsis-js');

const supsis = new SupsisJS({
  email: 'user@example.com',
  password: 'secret',
  siteId: 'site123'
});

await supsis.connect();

const chat = await supsis.chat.get('chatId');
const contacts = await supsis.contact.list({ limit: 10 });
```

### Node.js (ESM)

```javascript
import { SupsisJS } from '@supsis/supsis-js';

const supsis = new SupsisJS({
  email: 'user@example.com',
  password: 'secret',
  siteId: 'site123'
});

await supsis.connect();
```

## Konfigürasyon

```javascript
const supsis = new SupsisJS({
  // Zorunlu
  email: 'user@example.com',
  password: 'secret',
  siteId: 'site123',
  
  // Opsiyonel
  env: 'production',        // 'production' | 'stage' | 'local' (default: 'production')
  baseApiAddress: null,     // OnPrem için custom API URL
  timeout: 30000,           // HTTP timeout (ms)
  retryCount: 3             // Başarısız isteklerde retry sayısı
});
```

### Ortamlar

| env | API URL |
|-----|---------|
| `production` | https://api.supsis.live |
| `stage` | https://beta-api.supsis.live |
| `local` | https://tablet-api-local.supsis.live |

### OnPrem Kullanımı

```javascript
const supsis = new SupsisJS({
  email: 'user@company.com',
  password: 'secret',
  siteId: 'site123',
  baseApiAddress: 'https://api.company-supsis.com'
});
```

## Modüller

### Chat (Conversation)

```javascript
// Chat getir
const chat = await supsis.chat.get('chatId');

// Chat listele
const chats = await supsis.chat.list({
  status: 'active',
  startDate: '2024-01-01',
  limit: 20
});

// Chat mesajlarını getir
const messages = await supsis.chat.getMessages('chatId', { limit: 100 });

// Chat'e not ekle
await supsis.chat.addNote('chatId', 'Müşteri geri aranacak');

// Chat etiketlerini güncelle
await supsis.chat.updateTags('chatId', ['tagId1', 'tagId2']);
```

### Contact (Visitor)

```javascript
// Contact getir
const contact = await supsis.contact.get('contactId');

// Contact ara
const results = await supsis.contact.search({ email: 'user@example.com' });

// Contact oluştur
const newContact = await supsis.contact.create({
  fullname: 'John Doe',
  email: 'john@example.com',
  phone: '+905551234567'
});

// Contact güncelle
await supsis.contact.update('contactId', { fullname: 'Jane Doe' });

// Etiket ekle/kaldır
await supsis.contact.addTag('contactId', 'tagId');
await supsis.contact.removeTag('contactId', 'tagId');
```

### Message

```javascript
// Mesaj getir
const message = await supsis.message.get('messageId');

// Sohbetteki mesajları listele
const messages = await supsis.message.list('conversationId', { limit: 50 });

// Mesajlarda ara
const results = await supsis.message.search({
  query: 'sipariş numarası',
  startDate: '2024-01-01'
});
```

### Task

```javascript
// Görev oluştur
const task = await supsis.task.create({
  title: 'Müşteriyi ara',
  workflowId: 'workflowId',
  pipelineId: 'pipelineId',
  assignee: 'userId',
  dueDate: '2024-12-31'
});

// Görevleri listele
const tasks = await supsis.task.list('workflowId');

// Görevi taşı
await supsis.task.move('taskId', 'newPipelineId');

// Görevi tamamla
await supsis.task.complete('taskId');

// İş akışlarını listele
const workflows = await supsis.task.listWorkflows();
```

### AI Call (Voice Agent)

```javascript
// Arama başlat
const call = await supsis.aicall.makeCall({
  agentId: 'agentId',
  toNumber: '+905551234567',
  fromNumber: '+908501234567',
  variables: {
    customerName: 'John Doe'
  }
});

// Arama detayını getir
const callDetails = await supsis.aicall.getCall('callId');

// Aramaları listele
const calls = await supsis.aicall.listCalls({
  agentId: 'agentId',
  status: 'ended'
});
```

### Table (CustomerTable)

```javascript
// Tabloları listele
const tables = await supsis.table.list();

// Kayıtları listele
const records = await supsis.table.listRecords('tableId', {
  filters: { status: 'active' },
  limit: 50
});

// Kayıt oluştur
const record = await supsis.table.createRecord('tableId', {
  name: 'John Doe',
  email: 'john@example.com'
});
```

### Module (Dynamic Modules)

```javascript
// Modülleri listele
const modules = await supsis.module.list();

// Modül kayıtlarını listele
const leads = await supsis.module.listRecords('Leads', {
  filters: { status: 'new' }
});

// Kayıt oluştur
const lead = await supsis.module.createRecord('Leads', {
  name: 'John Doe',
  company: 'ACME Corp'
});
```

### Cache

```javascript
// Cache yaz
await supsis.cache.write('user:123', { name: 'John' }, {
  expiresIn: { value: 1, unit: 'hours' }
});

// Cache oku
const data = await supsis.cache.read('user:123');

// Cache sil
await supsis.cache.delete('cacheId');
```

### User

```javascript
// Mevcut kullanıcı
const me = await supsis.user.me();

// Kullanıcıları listele
const users = await supsis.user.list();

// Logout
await supsis.user.logout();
```

### Tag

```javascript
// Etiketleri listele
const tags = await supsis.tag.list();

// Etiket oluştur
const tag = await supsis.tag.create({
  name: 'VIP',
  color: '#FF0000',
  type: 'visitor'
});
```

### Site

```javascript
// Özellikleri getir
const features = await supsis.site.getFeatures();

// Cüzdan bilgisi
const wallet = await supsis.site.getWallet();
```

## Module API (Developer Token)

Panelden alınan developer token ile kısıtlı API erişimi:

```javascript
const { SupsisModuleAPI } = require('@supsis/supsis-js');

const api = new SupsisModuleAPI({
  accessToken: 'dev_token_xxx',
  siteId: 'site123'
});

const records = await api.module.listRecords('Leads');
const tables = await api.table.list();
```

## Hata Yönetimi

```javascript
const { SupsisJS, SupsisAPIError } = require('@supsis/supsis-js');

try {
  const chat = await supsis.chat.get('invalidId');
} catch (error) {
  if (error instanceof SupsisAPIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    throw error;
  }
}
```

## TypeScript

```typescript
import { SupsisJS, ChatResponse, ContactResponse } from '@supsis/supsis-js';

const supsis = new SupsisJS({
  email: 'user@example.com',
  password: 'secret',
  siteId: 'site123'
});

await supsis.connect();

const chat: ChatResponse = await supsis.chat.get('chatId');
const contacts: ContactResponse[] = (await supsis.contact.list()).data;
```

## Lisans

MIT