captivate-chat-api

Hybrid WebSocket/REST-based chat API for real-time conversations with support for bot and human agents. Features WebSocket communication for real-time messaging and REST endpoints for data retrieval operations.

Installation

Install the package using npm:

``bash
npm install captivate-chat-api
`

What's New

$3

As of v6.0.0, instances are now singleton for better management. No adjustments are needed - the change is automatic and backward compatible.

$3

Client sending operations have been refactored from WebSocket to HTTP REST for improved reliability and performance:

- 🔄 HTTP REST for Sending: All client sending operations (sendMessage, setMetadata, setPrivateMetadata, sendAction) now use HTTP REST endpoints instead of WebSocket events
- ⚡ Improved Reliability: HTTP requests provide better error handling and retry mechanisms compared to WebSocket events
- 📡 Hybrid Architecture: WebSocket is still used for real-time message reception and event handling, while HTTP handles all outgoing operations
- 🔧 Backward Compatibility: All existing method signatures remain unchanged - no code changes required
- 📊 Better Performance: HTTP requests offer more predictable latency and better handling of network issues

Methods now using HTTP REST:
- conversation.sendMessage() - Sends messages via HTTP with immediate confirmation
- conversation.setMetadata() - Updates metadata via HTTP with response confirmation
- conversation.setPrivateMetadata() - Updates private metadata via HTTP with response confirmation
- conversation.sendAction() - Sends custom actions via HTTP with response confirmation

Methods now using HTTP REST:
- conversation.getMetadata() - Uses HTTP request with direct response (no WebSocket)
- conversation.editMessage() - Uses HTTP request with direct response (no WebSocket)

Methods still using WebSocket:
- All event listeners (onMessage, onError, onConversationUpdate, onActionReceived) - Continue to work via WebSocket for real-time updates

$3

The library now includes a debug mode that allows you to control logging output:

`typescript
import { CaptivateChatAPI } from 'captivate-chat-api';

// Enable debug mode to see detailed logs
CaptivateChatAPI.setDebugMode(true);

// Create and use the API - you'll see detailed logs with [CaptivateChatAPI] prefix
const api = await CaptivateChatAPI.create('YOUR_API_KEY');

// Disable debug mode to hide logs
CaptivateChatAPI.setDebugMode(false);

// Check current debug mode status
const isDebugEnabled = CaptivateChatAPI.getDebugMode();
console.log('Debug mode enabled:', isDebugEnabled);
`

Debug Mode Features:
- 🔍 Targeted Logging: Only affects CaptivateChatAPI logs, not your website's console.log calls
- 🏷️ Clear Prefixing: All debug logs are prefixed with [CaptivateChatAPI] for easy identification
- ⚡ Performance: Debug logs are completely disabled when debug mode is off
- 🔧 Easy Control: Simple static methods to enable/disable debug mode globally

What Gets Logged in Debug Mode:
- HTTP request/response details
- WebSocket connection events
- Message sending confirmations
- Metadata operations
- Action confirmations
- Error details

Important: Debug mode only affects CaptivateChatAPI internal logging. Your apps console.log calls remain unaffected.

The CaptivateChatFileManager class has been significantly improved with:

- 🎉 Direct Usage: Use fileInput directly as files: fileInput instead of files: fileInput.files
- 🔧 Convenience Methods: Easy access to file properties with getFilename(), getTextContent(), getFileType()
- 📦 Single File Factory: New createFile() method for direct file object creation
- 🔄 Array-like Behavior: Proxy-based implementation supports array access and iteration
- 💾 Storage Options: Choose between service storage (storage: true) or developer storage (storage: false)
- 🔗 URL Support: When storage: false, provide your own URL for sendMessage compatibility
- ⚡ Performance: Eliminated API URL duplication and optimized internal structure
- 🔒 Backward Compatibility: All existing code continues to work without changes

$3

1. Simplified API: No more complex .files[0] access patterns
2. Better Developer Experience: Cleaner, more intuitive method names
3. Flexible Usage: Choose between wrapper (create()) or direct (createFile()) approaches
4. Type Safety: Full TypeScript support with proper type definitions

Usage

$3

Important: CaptivateChatAPI automatically enforces a singleton pattern per API key and mode combination. This means:

- Creating multiple instances with the same API key returns the same instance
- Prevents duplicate WebSocket connections and resource waste
- Works automatically with both new CaptivateChatAPI() and CaptivateChatAPI.create()

`typescript
import { CaptivateChatAPI } from 'captivate-chat-api';

// First instance created
const api1 = await CaptivateChatAPI.create('YOUR_API_KEY', 'prod');

// Returns the same instance (singleton)
const api2 = await CaptivateChatAPI.create('YOUR_API_KEY', 'prod');
// api1 === api2 ✅

// Different mode creates separate instance
const apiDev = await CaptivateChatAPI.create('YOUR_API_KEY', 'dev');
// apiDev !== api1 ✅

// Using new also returns singleton
const api3 = new CaptivateChatAPI('YOUR_API_KEY', 'prod');
// api3 === api1 === api2 ✅

// Cleanup when done
api1.dispose(); // Closes socket and removes from registry

// After disposal, new instance can be created
const api4 = await CaptivateChatAPI.create('YOUR_API_KEY', 'prod');
// api4 !== api1 ✅ (new instance)
`

Helper Methods:
`typescript
// Check if instance exists
if (CaptivateChatAPI.hasInstance('YOUR_API_KEY', 'prod')) {
const api = CaptivateChatAPI.getInstance('YOUR_API_KEY', 'prod');
}
`

$3

Most users will only need to use a single API key. Use the CaptivateChatAPI class for all standard chat operations:

`typescript
import { CaptivateChatAPI } from 'captivate-chat-api';

const api = new CaptivateChatAPI('YOUR_API_KEY');
await api.connect();

const conversation = await api.createConversation('user123');
`

You can use all the features described below (creating conversations, sending messages, etc.) with a single API key using this class.

$3

Import and initialize the API client:

Option 1: Using the static factory method (Recommended)
`typescript
import { CaptivateChatAPI } from 'captivate-chat-api';

// Create and connect in one step
const api = await CaptivateChatAPI.create('YOUR_API_KEY');
// API is ready to use!
`

Option 2: Manual instantiation and connection
`typescript
import { CaptivateChatAPI } from 'captivate-chat-api';

const api = new CaptivateChatAPI('YOUR_API_KEY');

// Connect to the WebSocket server
await api.connect();
`

$3

Create a new conversation with the following options:

1. Basic setup with just a user ID:
`typescript
const conversation = await api.createConversation('user123');
`

2. Include user information and custom data:
`typescript
const conversation = await api.createConversation(
'user123',
{
name: 'John Doe',
email: 'john@example.com'
},
{
customField: 'value'
},
'user-first' // Start the conversation with user-first or bot-first mode
);
`

3. (New) Include private metadata (not visible to frontend):
`typescript
const conversation = await api.createConversation(
'user123',
{ name: 'John Doe' },
{ publicKey: 'visible' },
'user-first',
{ secretKey: 'hidden', internalFlag: true } // privateMetadata
);
`
- The privateMetadata parameter is optional and, if provided, will be sent under the private key in the metadata. This is intended for backend/internal use and will not be returned to the frontend when fetching metadata.
- This change is backwards compatible: existing usages of createConversation do not need to change.

$3

1. Send a text message to the conversation:
`typescript
await conversation.sendMessage('Hello!');
`

2. Send a file with text message (recommended format):
`typescript
await conversation.sendMessage({
text: "Here's the document you requested",
files: [fileObject]
});
`

3. Listen for responses:
`typescript
conversation.onMessage((message, type) => {
console.log(${type}: ${message});
});
`

$3

> ⚠️ Important: The recommended way to handle files is through conversation.fileManager, which automatically includes the API key and conversation ID context. The direct CaptivateChatFileManager.create() method will be deprecated soon and is kept only for backwards compatibility. Please migrate to using conversation.fileManager for new code.

The CaptivateChatFileManager class provides automatic file-to-text conversion and structured file handling for chat messages. The class now includes several convenience methods and supports direct usage as a files array.

#### Basic File Upload (Recommended Way)

✅ Recommended: Use conversation.fileManager which automatically includes the conversation context:

`typescript
// Upload a local file with storage (default behavior) - RECOMMENDED
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf'
// storage defaults to true - file stored by service
// API key and conversation ID are automatically included
});

// Send file with text message
await conversation.sendMessage({
text: "Here's the document you requested",
files: fileInput // 🎉 No need for .files anymore!
});
`

#### Basic File Upload (Legacy - Deprecated Soon)

⚠️ Legacy: Direct usage of CaptivateChatFileManager.create() is kept for backwards compatibility but will be deprecated:

`typescript
import { CaptivateChatFileManager } from 'captivate-chat-api';

// Upload a local file with storage (default behavior) - LEGACY
const fileInput = await CaptivateChatFileManager.create({
file: file,
fileName: 'document.pdf'
// storage defaults to true - file stored by service
});

// Send file with text message
await conversation.sendMessage({
text: "Here's the document you requested",
files: fileInput // 🎉 No need for .files anymore!
});
`

#### File Storage Options

The library now supports two storage modes:

1. Service Storage (Default) - storage: true

✅ Recommended:
`typescript
// File stored by the service (default behavior) - RECOMMENDED
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf'
// storage defaults to true - file stored by service
});
`

⚠️ Legacy (Deprecated Soon):
`typescript
// File stored by the service (default behavior) - LEGACY
const fileInput = await CaptivateChatFileManager.create({
file: file,
fileName: 'document.pdf'
// storage defaults to true - file stored by service
});
`

// File object includes storage information:
// {
// filename: 'document.pdf',
// type: 'application/pdf',
// file: File,
// textContent: { ... },
// storage: {
// fileKey: 'uploads/1704067200000-...',
// presignedUrl: 'https://my-bucket.s3.amazonaws.com/...',
// expiresIn: 1704070800,
// fileSize: 1024,
// processingTime: 15
// }
// }
`

2. Developer Storage - storage: false

✅ Recommended:
`typescript
// File processed without storage, provide your own URL - RECOMMENDED
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf',
storage: false,
url: 'https://my-bucket.s3.amazonaws.com/documents/document.pdf' // Required
});
`

⚠️ Legacy (Deprecated Soon):
`typescript
// File processed without storage, provide your own URL - LEGACY
const fileInput = await CaptivateChatFileManager.create({
file: file,
fileName: 'document.pdf',
storage: false,
url: 'https://my-bucket.s3.amazonaws.com/documents/document.pdf' // Required
});
`

// File object includes your URL:
// {
// filename: 'document.pdf',
// type: 'application/pdf',
// file: File,
// url: 'https://my-bucket.s3.amazonaws.com/documents/document.pdf',
// textContent: { ... }
// }
`

Storage Benefits:
- Service Storage: Automatic file management, presigned URLs, no developer overhead
- Developer Storage: Full control over storage location, access permissions, and costs

#### Secure URL Management

When using service storage, you can generate fresh secure URLs for accessing stored files:

`typescript
// Create file with storage (Recommended way)
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf'
// storage defaults to true
});

// Refresh secure URL (expires in 2 hours by default)
const refreshedUrl = await fileInput.refreshSecureUrl();
console.log('Refreshed secure URL:', refreshedUrl);

// Refresh secure URL with custom expiration (1 hour)
const customUrl = await fileInput.refreshSecureUrl(3600);

// Generate secure URL from file key directly
const fileKey = 'uploads/1704067200000-uuid-example.txt';
const directUrl = await CaptivateChatFileManager.getSecureFileUrl(fileKey, 7200);
`

Use Cases:
- Expired URLs: Refresh secure URLs when the original expires
- Custom Expiration: Set different expiration times for different use cases
- Direct Access: Generate secure URLs from file keys without file objects

#### Convenience Methods

The CaptivateChatFileManager class now includes several convenience methods for easier access to file properties:

`typescript
// Recommended way
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf'
});

// Get file information easily
console.log('Filename:', fileInput.getFilename());
console.log('File type:', fileInput.getFileType());
console.log('Text content:', fileInput.getTextContent());
console.log('Text length:', fileInput.getTextContent().length);

// Get the first file object if needed
const firstFile = fileInput.getFirstFile();

// Convert to files array explicitly (though not needed anymore)
const filesArray = fileInput.toFilesArray();
`

#### Developer Storage with URL

✅ Recommended:
`typescript
// Process file without service storage, provide your own URL - RECOMMENDED
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf',
storage: false,
url: 'https://my-bucket.s3.amazonaws.com/documents/document.pdf' // Required
});

await conversation.sendMessage({
text: "Document from my storage",
files: fileInput // 🎉 Direct usage supported!
});
`

#### Multiple Files

✅ Option 1: Using conversation.fileManager.createMultiple() (Recommended)

`typescript
// Process multiple files with service storage (default) - RECOMMENDED
const files = [file1, file2, file3];
const fileInput = await conversation.fileManager.createMultiple({
files: files
// storage defaults to true
});

await conversation.sendMessage({
text: "Multiple documents attached",
files: fileInput // 🎉 All files processed and ready!
});
`

✅ Option 2: Multiple files with developer storage (Recommended)

`typescript
// Process multiple files without service storage - RECOMMENDED
const files = [file1, file2, file3];
const urls = [
'https://my-bucket.s3.amazonaws.com/file1.pdf',
'https://my-bucket.s3.amazonaws.com/file2.pdf',
'https://my-bucket.s3.amazonaws.com/file3.pdf'
];

const fileInput = await conversation.fileManager.createMultiple({
files: files,
storage: false,
urls: urls // Required when storage is false
});

await conversation.sendMessage({
text: "Multiple documents from my storage",
files: fileInput
});
`

⚠️ Option 3: Using CaptivateChatFileManager.createMultiple() (Legacy - Deprecated Soon)

`typescript
// Process multiple files without service storage - LEGACY
const files = [file1, file2, file3];
const urls = [
'https://my-bucket.s3.amazonaws.com/file1.pdf',
'https://my-bucket.s3.amazonaws.com/file2.pdf',
'https://my-bucket.s3.amazonaws.com/file3.pdf'
];

const fileInput = await CaptivateChatFileManager.createMultiple({
files: files,
storage: false,
urls: urls // Required when storage is false
});

await conversation.sendMessage({
text: "Multiple documents from my storage",
files: fileInput
});
`

Option 4: Manual processing (still supported)

✅ Recommended:
`typescript
// Process multiple files manually - RECOMMENDED
const files = [file1, file2, file3];
const fileInputs = await Promise.all(
files.map(file => conversation.fileManager.create({
file: file
}))
);

// Combine all files
const allFiles = fileInputs.flatMap(input => input);

await conversation.sendMessage({
text: "Multiple documents attached",
files: allFiles
});
`

⚠️ Legacy (Deprecated Soon):
`typescript
// Process multiple files manually - LEGACY
const files = [file1, file2, file3];
const fileInputs = await Promise.all(
files.map(file => CaptivateChatFileManager.create({
file: file
}))
);

// Combine all files
const allFiles = fileInputs.flatMap(input => input);

await conversation.sendMessage({
text: "Multiple documents attached",
files: allFiles
});
`

#### Alternative: Single File Factory Method

For even simpler usage when you only need one file object, you can use the createFile() method:

✅ Recommended:
`typescript
// Get just the file object directly (no wrapper) with service storage - RECOMMENDED
const fileObj = await conversation.fileManager.createFile({
file: file,
fileName: 'document.pdf'
// storage defaults to true
});

await conversation.sendMessage({
text: "Here's the document",
files: fileObj // 🎉 Direct usage - no array wrapping needed!
});

// Or with developer storage
const fileObjWithUrl = await conversation.fileManager.createFile({
file: file,
fileName: 'document.pdf',
storage: false,
url: 'https://my-bucket.s3.amazonaws.com/document.pdf'
});

await conversation.sendMessage({
text: "Here's the document from my storage",
files: fileObjWithUrl // 🎉 Direct usage - no array wrapping needed!
});
`

⚠️ Legacy (Deprecated Soon):
`typescript
// Get just the file object directly (no wrapper) with service storage - LEGACY
const fileObj = await CaptivateChatFileManager.createFile({
file: file,
fileName: 'document.pdf'
// storage defaults to true
});

await conversation.sendMessage({
text: "Here's the document",
files: fileObj // 🎉 Direct usage - no array wrapping needed!
});
`

#### File Input Structure

The CaptivateChatFileManager creates a structured object with:

Service Storage (storage: true):
`typescript
{
type: 'files',
files: [
{
filename: 'document.pdf',
type: 'application/pdf',
file: File | Blob, // Original file
textContent: {
type: 'file_content',
text: 'Extracted text from file...',
metadata: {
source: 'file_attachment',
originalFileName: 'document.pdf',
storageType: 'direct'
}
},
storage: {
fileKey: 'uploads/1704067200000-...',
presignedUrl: 'https://my-bucket.s3.amazonaws.com/...',
expiresIn: 1704070800,
fileSize: 1024,
processingTime: 15
}
}
]
}
`

Developer Storage (storage: false):
`typescript
{
type: 'files',
files: [
{
filename: 'document.pdf',
type: 'application/pdf',
file: File | Blob, // Original file
url: 'https://my-bucket.s3.amazonaws.com/document.pdf', // Developer's URL
textContent: {
type: 'file_content',
text: 'Extracted text from file...',
metadata: {
source: 'file_attachment',
originalFileName: 'document.pdf',
storageType: 'direct'
}
}
}
]
}
`

#### Supported File Types

- Documents: PDF, DOCX, TXT, XLSX, CSV
- Images: PNG, JPG, JPEG (with OCR text extraction)
- Any file type supported by the file-to-text API

#### WebSocket Payload Format

Files are sent in the following WebSocket payload structure:

`json
{
"action": "sendMessage",
"event": {
"event_type": "user_message",
"event_payload": {
"type": "message_create",
"client_msg_id": "unique-message-id-1234567890",
"conversation_id": "your-conversation-id",
"content": {
"text": "Here's the document you requested",
"files": [
{
"filename": "document.pdf",
"type": "application/pdf",
"textContent": {
"type": "file_content",
"text": "Extracted text from PDF...",
"metadata": {
"source": "file_attachment",
"originalFileName": "document.pdf",
"storageType": "direct"
}
}
}
]
}
}
}
}
`

$3

Edit a previously sent message in the conversation:

`typescript
await conversation.editMessage('messageId123', 'Updated message text');
// Or with a custom object:
await conversation.editMessage('messageId123', { type: 'text', text: 'Updated message text', files: [], actions: [] });
`

The method returns a promise that resolves when the edit is confirmed by the server (message_edited_success event).

$3

Use event listeners to handle various updates, errors, or custom actions:

1. Error handling:
`typescript
conversation.onError((error) => {
console.error('Error:', error);
});
`

2. Updates on conversation status:
`typescript
conversation.onConversationUpdate((update) => {
console.log('Conversation Update:', update);
});
`

3. Handling custom actions:
`typescript
conversation.onActionReceived((actions) => {
console.log(Actions:, actions);
});
`

$3

Retrieve the transcript of a conversation:

`typescript
const transcript = await conversation.getTranscript();
console.log('Transcript:', transcript);
`

$3

Delete the current conversation with optional soft delete:

`typescript
// Soft delete (default - safer option)
await conversation.delete();
console.log('Conversation soft deleted');

// Explicit soft delete
await conversation.delete({ softDelete: true });
console.log('Conversation soft deleted');

// Hard delete (permanent - deletes everything including transcripts)
await conversation.delete({ softDelete: false });
console.log('Conversation permanently deleted');
`

Delete Types:
- Soft Delete (default): Marks conversation as deleted but preserves data including transcripts for potential recovery
- Hard Delete: Permanently removes everything including transcripts, messages, and all associated data

$3

Set the time-to-live for the entire conversation session, which controls how long the conversation data (including chat history, files, and all associated data) will be retained on the server. The server uses this TTL value to manage the lifecycle of the entire conversation session.

`typescript
// Set TTL to 1 day
await conversation.setTimeToLive(1);

// Set TTL to 7 days
await conversation.setTimeToLive(7);

// Set TTL to 30 days
await conversation.setTimeToLive(30);
`

How it works:
1. Path TTL: Sets the time-to-live for the conversation path (apiKey/conversationId) on the file-to-text service
2. Metadata Update: Automatically stores the TTL value in conversation metadata as timeToLive
3. Session Retention: The entire conversation session (chat history, files, messages, transcripts, and all associated data) will be retained for the specified number of days
4. Server Behavior: The server considers this TTL value for the current session and will manage data retention accordingly
5. Activity-Based: Important: The TTL timer is only active from the last activity/usage of the conversation. Each time the conversation is used (sending messages, receiving messages, or any activity), the TTL timer resets from that point

Important Notes:
- The days parameter must be a positive integer
- The TTL applies to the entire conversation session, not just files
- This includes chat history, messages, transcripts, files, and all conversation data
- The TTL value is stored in conversation metadata for easy reference
- The server uses this metadata to determine data retention policies for the session
- TTL is activity-based: The countdown starts from the last activity in the conversation, not from when the TTL was set. Each new activity resets the timer

Use Cases:
- Temporary Conversations: Set short TTL (1-7 days) for temporary support sessions or one-time interactions
- Compliance: Set specific TTLs based on data retention requirements and regulatory compliance
- Data Management: Automatically clean up old conversation data after the TTL expires
- Privacy: Ensure sensitive conversation data is automatically purged after a set period

$3

Fetch a list of conversations associated with a specific user ID. This method supports both legacy (v1) and advanced (v2) usage with filter, search, and pagination. Both versions return the same response format. The method supports backward compatibility with both string and object parameters.

Note:
- search parameter uses wildcard matching by default (e.g., "fred" matches "frederick", "alfred", etc.)
- filter parameter uses exact matching only (e.g., "fred" only matches "fred")

Legacy usage (v1) - String parameter (backward compatible):
`typescript
const conversations = await api.getUserConversations('user123');
console.log('User Conversations:', conversations);
/*
Returns Conversation Object
*/
`

Legacy usage (v1) - Options object:
`typescript
const conversations = await api.getUserConversations({
userId: 'user123'
});
console.log('User Conversations:', conversations);
/*
Returns Conversation Object
*/
`

Advanced usage (v2, with filter and pagination):
`typescript
const conversations = await api.getUserConversations({
userId: 'user123',
filter: { mode: 'dbfred' }, // exact match only
pagination: { page: '1', limit: '10' }
});
console.log('Filtered & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
`

Advanced usage (v2, with search and pagination):
`typescript
const conversations = await api.getUserConversations({
userId: 'user123',
search: { mode: 'fred' }, // wildcard match (matches "frederick", "alfred", etc.)
pagination: { page: '1', limit: '10' }
});
console.log('Searched & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
`

Advanced usage (v2, with both filter and search):
`typescript
const conversations = await api.getUserConversations({
userId: 'user123',
filter: { mode: 'dbfred' }, // exact match
search: { mode: 'fred' }, // wildcard match
pagination: { page: '1', limit: '10' }
});
console.log('Filtered, Searched & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
`

$3

For advanced use cases where you need to fetch and interact with conversations across multiple API keys, use the CaptivateChatManager class. This manager handles multiple CaptivateChatAPI instances and ensures each Conversation uses the correct socket for its API key.

Note: Most users do not need this. Only use the manager if you need to aggregate or interact with conversations across multiple API keys.

Key Features:
- Automatically deduplicates API keys to prevent duplicate instances
- Leverages singleton pattern from CaptivateChatAPI
- Provides disposal methods for cleanup

Option 1: Using the static factory method (Recommended)
`typescript
import { CaptivateChatManager } from 'captivate-chat-api';

const apiKeys = [
'YOUR_API_KEY_1',
'YOUR_API_KEY_2',
'YOUR_API_KEY_1' // Duplicate - automatically filtered out
];

// Create and connect all instances in one step
const manager = await CaptivateChatManager.create(apiKeys, 'dev');

const { conversations, pagination } = await manager.getUserConversations({
userId: '66f016f09d5961b684ce05f0',
apiKeys,
pagination: { page: '1', limit: '90' }
});

for (const conv of conversations) {
const transcript = await conv.getTranscript();
console.log(Transcript for ${conv.getConversationId()}:, transcript);
}

// Cleanup when done
manager.disposeAll(); // Closes all WebSocket connections
`

Option 2: Manual instantiation and connection
`typescript
import { CaptivateChatManager } from 'captivate-chat-api';

const apiKeys = [
'YOUR_API_KEY_1',
'YOUR_API_KEY_2'
];

const manager = new CaptivateChatManager(apiKeys, 'dev');
await manager.connectAll();

const { conversations, pagination } = await manager.getUserConversations({
userId: '66f016f09d5961b684ce05f0',
apiKeys,
pagination: { page: '1', limit: '90' }
});

for (const conv of conversations) {
const transcript = await conv.getTranscript();
console.log(Transcript for ${conv.getConversationId()}:, transcript);
}
`

Disposal Methods:
`typescript
// Dispose single API instance
manager.dispose('YOUR_API_KEY_1');

// Dispose all instances
manager.disposeAll();
`

- Use CaptivateChatAPI for single-key scenarios.
- Use CaptivateChatManager for multi-key scenarios.

$3

Delete all conversations for a specific user with optional soft delete:

`typescript
// Soft delete (default - safer option)
await api.deleteUserConversations('user123');
console.log('User conversations soft deleted');

// Explicit soft delete
await api.deleteUserConversations('user123', { softDelete: true });
console.log('User conversations soft deleted');

// Hard delete (permanent - deletes everything including transcripts)
await api.deleteUserConversations('user123', { softDelete: false });
console.log('User conversations permanently deleted');
`

Delete Types:
- Soft Delete (default): Marks all user conversations as deleted but preserves data including transcripts for potential recovery
- Hard Delete: Permanently removes all user conversations including transcripts, messages, and all associated data

$3

Here's a complete example of how to use the API:

`typescript
import { CaptivateChatAPI, CaptivateChatFileManager } from 'captivate-chat-api';

(async () => {
try {
// Create and connect to the API in one step
const api = await CaptivateChatAPI.create('YOUR_API_KEY', 'prod');
console.log('Connected to CaptivateChat API');

// Create a conversation
const conversation = await api.createConversation(
'user123',
{
name: 'John Doe',
email: 'john@example.com',
},
{ role: 'admin' },
'bot-first'
);

console.log('Conversation started:', conversation);

// Listen for messages
conversation.onMessage((message, type) => {
console.log(Received (${type}): ${message});
});

// Send a text message
await conversation.sendMessage('Hello! How can I assist you today?');

// Send a file with text message (Recommended way)
const fileInput = await conversation.fileManager.create({
file: file,
fileName: 'document.pdf'
});

await conversation.sendMessage({
text: "Here's the document you requested",
files: fileInput // 🎉 Direct usage - no .files needed!
});

// Handle conversation updates
conversation.onConversationUpdate((update) => {
console.log('Conversation Update:', update);
});

// Fetch the transcript
const transcript = await conversation.getTranscript();
console.log('Transcript:', transcript);

// Get user conversations (backward compatible)
const conversations = await api.getUserConversations('user123');
console.log('User Conversations:', conversations);

// Get user conversations with advanced filtering (new API)
const filteredConversations = await api.getUserConversations({
userId: 'user123',
filter: { status: 'active' },
search: { title: 'meeting' },
pagination: { page: '1', limit: '10' }
});
console.log('Filtered Conversations:', filteredConversations);

// Delete the conversation (soft delete by default)
await conversation.delete();
console.log('Conversation soft deleted successfully.');

// Or delete permanently
// await conversation.delete({ softDelete: false });
// console.log('Conversation permanently deleted.');

} catch (error) {
console.error('Error:', error);
}
})();
`

$3

Switch to development mode for testing:
`typescript
const api = new CaptivateChatAPI('YOUR_API_KEY', 'dev');
`

Environment Support

The API supports the following environments:
- Browser
- Node.js
- React Native

$3

File-to-text conversion is handled by the external API endpoint:
- Production: https://file-to-text.prod.captivat.io/api/file-to-text
- Supported formats: PDF, DOCX, TXT, PNG, JPG, JPEG
- Features: OCR for images, metadata extraction, automatic text conversion

API Reference

$3

A utility class for processing files and converting them to text for chat messages. The class now supports direct usage as a files array and includes convenience methods for easier file property access.

#### Methods

- static create(options: { file: File | Blob; fileName?: string; fileType?: string; storage?: boolean; url?: string }): Promise
Creates a CaptivateChatFileManager from a local file with automatic text extraction. storage defaults to true.

- static createFile(options: { file: File | Blob; fileName?: string; fileType?: string; storage?: boolean; url?: string }): Promise
(New) Creates a single file object directly (no wrapper) with automatic text extraction. storage defaults to true.

- static createMultiple(options: { files: (File | Blob)[]; storage?: boolean; urls?: string[] }): Promise
(New) Creates a single CaptivateChatFileManager from multiple files, processing them in parallel. storage defaults to true.

- getFilename(): string | undefined
(New) Gets the filename of the first file.

- getTextContent(): string
(New) Gets the text content of the first file.

- getFileType(): string | undefined
(New) Gets the file type of the first file.

- getFirstFile(): FileObject | undefined
(New) Gets the first file object from the files array.

- toFilesArray(): Array
(New) Returns the files array explicitly.

- refreshSecureUrl(expiresIn?: number): Promise
(New) Refreshes the secure URL for the first file (if it has storage information).

- static getSecureFileUrl(fileKey: string, expiresIn?: number): Promise
(New) Generates a secure URL for accessing a stored file by file key.

#### Properties

- type: 'files' - Always 'files' for file inputs
- files: Array - Array of processed file objects
- length: number - (New) Returns the length of the files array for array-like behavior

#### Array-like Behavior

The CaptivateChatFileManager class now supports array-like behavior through a proxy, allowing you to use it directly as a files array:

`typescript
const fileInput = await CaptivateChatFileManager.create(file, options);

// All of these work:
files: fileInput // ✅ Direct usage
files: fileInput.files // ✅ Traditional usage (still supported)
fileInput[0] // ✅ Array access
fileInput.length // ✅ Array length
`

#### FileObject Structure

Service Storage (storage: true):
`typescript
{
filename: string;
type: string;
file: File | Blob; // Original file
textContent: {
type: 'file_content';
text: string;
metadata: {
source: 'file_attachment';
originalFileName: string;
storageType: 'direct';
};
};
storage: {
fileKey: string;
presignedUrl: string;
expiresIn: number;
fileSize: number;
processingTime: number;
};
}
`

Developer Storage (storage: false):
`typescript
{
filename: string;
type: string;
file: File | Blob; // Original file
url: string; // Developer's URL (required when storage is false)
textContent: {
type: 'file_content';
text: string;
metadata: {
source: 'file_attachment';
originalFileName: string;
storageType: 'direct';
};
};
}
`

$3

#### Methods
- constructor(apiKey: string, mode: 'prod' | 'dev' = 'prod')
Initializes the API with the given API key and mode. Enforces singleton pattern: returns existing instance if one already exists for the given API key/mode combination.

- static create(apiKey: string, mode: 'prod' | 'dev' = 'prod'): Promise
Static factory method that creates and connects a CaptivateChatAPI instance. Enforces singleton pattern: constructor returns existing instance if one exists. Returns a promise that resolves to a ready-to-use, connected API instance.

- static getInstance(apiKey: string, mode: 'prod' | 'dev' = 'prod'): CaptivateChatAPI | undefined
(New) Gets an existing instance for the given API key and mode, if one exists. Returns undefined if no instance exists.

- static hasInstance(apiKey: string, mode: 'prod' | 'dev' = 'prod'): boolean
(New) Checks if an instance exists for the given API key and mode. Returns true if an instance exists, false otherwise.

- dispose(): void
(New) Disposes of this instance, closing the WebSocket connection and removing it from the registry. After calling dispose(), a new instance can be created for the same API key/mode combination.

- static setDebugMode(enabled: boolean): void
(New) Sets the debug mode for CaptivateChatAPI logging. When enabled, detailed logs are shown with [CaptivateChatAPI] prefix.

- static getDebugMode(): boolean
(New) Gets the current debug mode state. Returns true if debug mode is enabled, false otherwise.

- connect(): Promise
Connects to the WebSocket server.

- isSocketActive(): boolean
(New) Checks if the WebSocket connection is active and open. Returns true if the socket is open, false otherwise.

- createConversation(userId: string, userBasicInfo?: object, userData?: object, autoConversationStart?: 'bot-first' | 'user-first'): Promise
Creates a new conversation.

- getConversation(conversationId: string): Conversation
Retrieves an existing conversation by its ID.

- getUserConversations(userIdOrOptions: string | { userId: string; filter?: object; search?: object; pagination?: { page?: string | number; limit?: string | number }; apiKeys?: string[] }): Promise
Fetches a list of conversations associated with the given user ID. Supports backward compatibility with string parameter or options object. If filter, search, pagination, or apiKeys is provided, uses the v2 API for advanced querying. Both filter and search parameters are supported for different querying needs. The apiKeys parameter allows grouping conversations by API key. Returns Conversation Object

- deleteUserConversations(userId: string, options?: { softDelete?: boolean }): Promise
Deletes all conversations associated with the given user ID. options.softDelete defaults to true (safer option).
---

$3

#### Methods
- sendMessage(content: string): Promise
Sends a text message to the conversation.

- sendMessage(content: object): Promise
Sends a structured message. Supports:
- Text only: { type: 'text', text: 'Hello' }
- Files only: { type: 'files', files: [...] }
- Combined: { text: 'Hello', files: [...] } (recommended)

- setMetadata(metadata: object): Promise
Updates metadata for the conversation.

- setPrivateMetadata(privateMeta: object): Promise
(New) Updates private metadata for the conversation (not visible to frontend). Example:
`typescript
await conversation.setPrivateMetadata({ secret: 'mySecretValue', internalFlag: true });
`
This will set the metadata under the private key. The private metadata is intended for backend/internal use only and will not be returned to the frontend when fetching metadata.

- getMetadata(): Promise