@coherenceplatform/sdk/README.md

Coherence SDK for embedding AI-powered chat into your applications

# Coherence SDK

JavaScript SDK for integrating Coherence AI-powered chat into your applications. Signup for free for Coherence at app.withcoherence.com

## Installation

### Option 1: NPM Package

```bash
npm install @coherenceplatform/sdk
```

```javascript
import CoherenceSDK from '@coherenceplatform/sdk';

const coherence = new CoherenceSDK({
  demo: { enabled: true, appId: 'your-app-id' }
});

await coherence.init();
```

### Option 2: Script Tag

```html
<script src="https://app.withcoherence.com/sdk/coherence-sdk.js"></script>
<script>
  const coherence = new CoherenceSDK({
    demo: { enabled: true, appId: 'your-app-id' }
  });
  
  coherence.init().then(() => {
    console.log('Coherence SDK ready!');
  });
</script>
```

## Configuration

> **Note**: Most configuration (name, placeholderText, threadSuggestions, etc.) should be set in the Coherence Dashboard. Dashboard settings override any local configuration.

### Authentication Modes

The SDK supports three authentication modes:

#### 1. Demo Mode (Quick Testing)
```javascript
const coherence = new CoherenceSDK({
  demo: {
    enabled: true,
    appId: 'your-app-id'  // Get from Coherence Dashboard
  }
});
await coherence.init();
```

#### 2. OAuth Mode
```javascript
const coherence = new CoherenceSDK({
  oauth: {
    enabled: true,
    appId: 'your-app-id',
    externalUserId: 'user-123',
    getToken: async () => {
      // Return your app's auth token
      return await getAuthToken();
    }
  }
});
await coherence.init();
```

#### 3. Backend Authentication Mode  
```javascript
const coherence = new CoherenceSDK({
  chatEndpoint: '/api/chat',  // Your backend endpoint
  appBackendUrl: 'https://api.yourapp.com'  // Optional if different origin
});
await coherence.init();
```

### UI Display Modes

#### Floating Widget (Default)
```javascript
const coherence = new CoherenceSDK({
  demo: { enabled: true, appId: 'your-app-id' }
  // Chat appears as a floating widget
});
await coherence.init();
```

#### Inline Embedded
```javascript
const coherence = new CoherenceSDK({
  demo: { enabled: true, appId: 'your-app-id' },
  inline: true,
  containerElementId: 'chat-container'
});
await coherence.init();
```

## API Methods

### Sending Messages

```javascript
// Send a text message
await coherence.sendMessage('Hello, I need help!');

// Send with attachments
await coherence.sendMessage([
  { type: 'text', text: 'Please check this image' },
  { type: 'image', url: 'https://example.com/image.png' }
]);
```

### Managing Conversations

```javascript
// Get all conversations
const conversations = await coherence.getConversations();

// Get messages for a specific conversation
const messages = await coherence.getMessages(conversationId);
```

### UI Controls

```javascript
// Show the chat widget
coherence.show();

// Hide the chat widget
coherence.hide();

// Toggle visibility
coherence.toggle();
```

### Cleanup

```javascript
// Destroy the SDK instance and clean up resources
coherence.destroy();
```

## TypeScript Support

The SDK includes TypeScript definitions for all configuration options and methods.

```typescript
import CoherenceSDK, { CoherenceConfig, Message } from '@coherenceplatform/sdk';

const config: CoherenceConfig = {
  theme: {
    primary: '#007bff'
  }
};

const coherence = new CoherenceSDK(config);
await coherence.init();
```

## Browser Support

The SDK supports all modern browsers:
- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)

## Support

For support, please contact the Coherence team or visit the dashboard at [app.withcoherence.com](https://app.withcoherence.com)