@plott-ai/sdk-core

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

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

Quick Start

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

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:

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:

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:

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:

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:

// 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

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:

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

Error Handling

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