npm package: @plott-ai/sdk-core
Description: Core SDK for Plott Analytics
Author: Plott Analytics
Latest version: 0.0.1-alpha.0

# @plott-ai/sdk-core

[![npm version](https://badge.fury.io/js/@plott-ai/sdk-core.svg)](https://badge.fury.io/js/@plott-ai/sdk-core)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@plott-ai/sdk-core)](https://bundlephobia.com/package/@plott-ai/sdk-core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Core SDK for Plott Analytics - A powerful, type-safe analytics library for tracking AI agent behavior and user interactions.

## Features

- 🚀 **Zero Configuration** - Works out of the box with sensible defaults
- 📊 **Type Safe** - Full TypeScript support with comprehensive type definitions
- 🌐 **Universal** - Works in Node.js, browsers, and edge environments
- 📦 **Tree Shakeable** - Optimized bundles with selective imports
- ⚡ **Performance** - Minimal overhead with efficient batching
- 🔄 **Dual Module** - ESM and CommonJS support

## Installation

```bash
npm install @plott/sdk-core
# or
pnpm add @plott/sdk-core
# or
yarn add @plott/sdk-core
```

## Quick Start

```typescript
import { PlottAnalytics } from '@plott-ai/sdk-core'

// Initialize the client
const plott = new PlottAnalytics({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.plott-analytics.com'
})

// Track a message event
await plott.track({
  type: 'MESSAGE',
  role: 'user',
  content: 'Hello, AI assistant!',
  context: {
    sessionId: 'session-123',
    userId: 'user-456'
  }
})

// Track a custom event
await plott.track({
  type: 'CUSTOM',
  value: { action: 'button_click', element: 'submit' },
  context: {
    userId: 'user-456'
  }
})
```

## Configuration

```typescript
interface PlottConfig {
  apiKey: string
  baseUrl?: string
  batchSize?: number
  flushInterval?: number
  retryAttempts?: number
  timeout?: number
  debug?: boolean
}

const plott = new PlottAnalytics({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.plott-analytics.com',
  batchSize: 50,        // Events per batch
  flushInterval: 5000,  // Auto-flush every 5 seconds
  retryAttempts: 3,     // Retry failed requests
  timeout: 10000,       // 10 second timeout
  debug: true           // Enable debug logging
})
```

## Event Types

### Message Events
Track conversations and AI interactions:

```typescript
await plott.track({
  type: 'MESSAGE',
  role: 'assistant',
  content: 'How can I help you today?',
  model: 'gpt-4',
  tokenCount: 150,
  context: {
    sessionId: 'session-123',
    turnId: 'turn-456'
  }
})
```

### UI Events
Track user interface interactions:

```typescript
await plott.track({
  type: 'UI',
  action: 'click',
  element: 'submit-button',
  coordinates: { x: 100, y: 200 },
  context: {
    userId: 'user-123'
  }
})
```

### Error Events
Track errors and exceptions:

```typescript
await plott.track({
  type: 'ERROR',
  error: {
    name: 'ValidationError',
    message: 'Invalid input provided',
    stack: error.stack
  },
  severity: 'medium',
  context: {
    userId: 'user-123'
  }
})
```

### Custom Events
Track application-specific events:

```typescript
await plott.track({
  type: 'CUSTOM',
  value: {
    feature: 'document_upload',
    fileSize: 1024000,
    fileType: 'pdf'
  },
  context: {
    userId: 'user-123'
  }
})
```

## Batching

Events are automatically batched for optimal performance:

```typescript
// Manual flush
await plott.flush()

// Batch multiple events
await plott.trackBatch([
  { type: 'MESSAGE', role: 'user', content: 'Hello' },
  { type: 'MESSAGE', role: 'assistant', content: 'Hi there!' }
])
```

## Utilities

```typescript
import { generateId, extractCustomerId, isBrowser } from '@plott-ai/sdk-core'

// Generate unique IDs
const eventId = generateId()

// Extract customer ID from context
const customerId = extractCustomerId(context)

// Environment detection
if (isBrowser()) {
  // Browser-specific code
}
```

## TypeScript

Full TypeScript support with exported types:

```typescript
import type {
  AnalyticsEvent,
  MessageEvent,
  UIEvent,
  ErrorEvent,
  CustomEvent,
  PlottConfig
} from '@plott-ai/sdk-core'
```

## Error Handling

```typescript
try {
  await plott.track(event)
} catch (error) {
  if (error instanceof PlottError) {
    console.error('Plott Error:', error.message)
  }
}
```

## Browser Support

- Chrome 63+
- Firefox 55+
- Safari 12+
- Edge 79+

## Node.js Support

- Node.js 16+

## License

MIT © Plott Analytics