@konvo-ai/sdk-web/README.md

KonvoAI Conversational Ad SDK for Web Applications - Intelligent contextual advertising with AI-powered decision engine

# KonvoAI Web SDK

> Intelligent contextual advertising with AI-powered decision engine for web applications

## Installation

```bash
npm install @konvo-ai/sdk-web
```

## Quick Start

```typescript
import { KonvoAIAds } from '@konvo-ai/sdk-web';

// Initialize the SDK
KonvoAIAds.init({
  apiKey: 'your-api-key-here'
});

// Request an ad decision
const response = await KonvoAIAds.decide({
  context: {
    domain: 'tech',
    content: 'article-about-javascript',
    placement: 'sidebar'
  },
  user: {
    userId: 'user123',
    anonId: await KonvoAIAds.generateAnonId()
  },
  chat: {
    lastUserMsg: 'I love learning JavaScript!'
  }
});

// Display the ad if available
if (response.fill && response.render) {
  const adContainer = document.getElementById('ad-container');
  
  // Create ad element
  const adElement = document.createElement('div');
  adElement.innerHTML = `
    <div style="padding: 16px; border: 1px solid #ddd; border-radius: 8px;">
      <h3>${response.render.title}</h3>
      <p>${response.render.description}</p>
      <button onclick="handleAdClick()">${response.render.cta.label}</button>
    </div>
  `;
  
  adContainer.appendChild(adElement);
  
  // Track impression
  await KonvoAIAds.handleImpression(response);
  
  // Handle click
  window.handleAdClick = response.render.cta.handler;
}
```

## API Reference

### `KonvoAIAds.init(config)`

Initialize the SDK with your API configuration.

**Parameters:**
- `config.apiKey` (string, required): Your KonvoAI API key
- `config.baseUrl` (string, optional): Custom API base URL (defaults to production)

### `KonvoAIAds.decide(input)`

Request an ad decision from the KonvoAI engine.

**Parameters:**
- `input.context` (object): Context information about the placement
  - `domain` (string): Content domain/category
  - `content` (string): Content identifier
  - `placement` (string): Ad placement identifier
- `input.user` (object): User information
  - `userId` (string, optional): Authenticated user ID
  - `anonId` (string): Anonymous user identifier
- `input.chat` (object): Chat context
  - `lastUserMsg` (string): Most recent user message for context

**Returns:** Promise<DecideResponse>
- `decisionId` (string): Unique decision identifier
- `fill` (boolean): Whether an ad should be shown
- `render` (object, optional): Ad content when fill is true
  - `title` (string): Ad headline
  - `description` (string): Ad description
  - `cta` (object): Call-to-action
    - `label` (string): Button text
    - `handler` (function): Click handler function

### `KonvoAIAds.handleImpression(response)`

Track an ad impression. Call this when the ad is displayed to the user.

**Parameters:**
- `response` (DecideResponse): The response from `decide()`

### `KonvoAIAds.generateAnonId()`

Generate or retrieve a persistent anonymous user ID.

**Returns:** Promise<string> - Anonymous user identifier

## Privacy & Data Handling

The KonvoAI SDK includes automatic PII scrubbing for user messages:
- Names are replaced with `[NAME]`
- Phone numbers are replaced with `[PHONE]`
- Email addresses are replaced with `[EMAIL]`
- Social Security Numbers are replaced with `[SSN]`
- Credit card numbers are replaced with `[CARD]`
- ZIP codes are replaced with `[ZIP]`

## Support

- Documentation: https://docs.konvo.ai/web-sdk
- Issues: https://github.com/konvo-ai/sdk-web/issues
- Email: support@konvo.ai

## License

MIT License - see LICENSE file for details.