open-index/open-npm huggingface dataset:
npm package: @plott-ai/sdk-react
Description: React SDK for Plott Analytics
Author: Plott Analytics
Latest version: 0.0.1-alpha.0

# @plott-ai/sdk-react

React SDK for Plott Analytics - easily track analytics events in your React applications.

## Installation

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

## Quick Start

### 1. Wrap your app with the provider

```tsx
import { PlottAnalyticsProvider } from "@plott-ai/sdk-react";

function App() {
  return (
    <PlottAnalyticsProvider config={{ apiKey: "cpk_your_api_key" }}>
      <YourApp />
    </PlottAnalyticsProvider>
  );
}
```

### 2. Track events using hooks

```tsx
import { useTrackMessage, useTrackEvent } from "@plott-ai/sdk-react";

function ChatComponent() {
  const trackMessage = useTrackMessage();

  const handleSend = (content: string) => {
    // Track user message
    trackMessage({
      role: "user",
      content,
      sessionId: "session-123",
    });
  };

  const handleAssistantResponse = (content: string) => {
    // Track assistant response
    trackMessage({
      role: "assistant",
      content,
      model: "gpt-4",
      tokenCount: 150,
    });
  };

  return <Chat onSend={handleSend} />;
}
```

## API Reference

### PlottAnalyticsProvider

Wrap your application with this provider to enable analytics tracking.

```tsx
<PlottAnalyticsProvider
  config={{
    apiKey: "cpk_...",
    debug: true, // Optional: enable debug logging
  }}
>
  <App />
</PlottAnalyticsProvider>
```

### usePlottAnalytics

Access the underlying PlottAnalytics client for advanced use cases.

```tsx
const { client, isReady } = usePlottAnalytics();
```

### useTrackEvent

Track any analytics event.

```tsx
const trackEvent = useTrackEvent();
trackEvent({ type: "CUSTOM", value: { action: "custom" } });
```

### useTrackMessage

Track message events (user, assistant, system messages).

```tsx
const trackMessage = useTrackMessage();
trackMessage({
  role: "user",
  content: "Hello!",
  sessionId: "session-123",
});
```

### useTrackUIEvent

Track UI interaction events.

```tsx
const trackUI = useTrackUIEvent();
trackUI({
  action: "click",
  element: "submit-button",
});
```

### useTrackErrorEvent

Track error events.

```tsx
const trackError = useTrackErrorEvent();
trackError({
  error: { name: "ValidationError", message: "Invalid input" },
  severity: "medium",
});
```

## License

MIT
npm package: @plott-ai/sdk-vercel-ai
Description: Vercel AI SDK integration for Plott Analytics
Author: Ran Shemtov
Latest version: 0.0.1-alpha.0

# @plott-ai/sdk-vercel-ai

Plott Analytics integration for the Vercel AI SDK. Track all your AI conversations, tool calls, and user behavior with a single line of code.

## Installation

```bash
npm install @plott/sdk-vercel-ai
# or
bun add @plott/sdk-vercel-ai
# or
pnpm add @plott/sdk-vercel-ai
```

## Quick Start

```typescript
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { withPlottCallbacks } from '@plott-ai/sdk-vercel-ai';

const result = await streamText({
  model: openai('gpt-4o'),
  messages,
  ...withPlottCallbacks({ sessionId: 'user-123' }),
});
```

That's it! All messages, tool calls, errors, and metrics are automatically tracked.

## Environment Variables

```bash
# Required
PLOTT_API_KEY=cpk_your_api_key

# Optional (defaults shown)
PLOTT_ENDPOINT=http://localhost:3001
```

## API

### `withPlottCallbacks(options?)`

Creates Plott tracking callbacks for `streamText` or `generateText`.

```typescript
import { withPlottCallbacks } from '@plott-ai/sdk-vercel-ai';

const callbacks = withPlottCallbacks({
  // Session tracking (recommended)
  sessionId: 'user-session-123',
  conversationId: 'conv-456', // optional

  // Plott config (optional, uses env vars by default)
  apiKey: 'cpk_...',
  baseUrl: 'http://localhost:3001',
  environment: 'production',

  // Debug mode (optional)
  debug: true,

  // Chain your own callbacks (optional)
  onChunk: (event) => { /* your handler */ },
  onFinish: (event) => { /* your handler */ },
  onStepFinish: (stepResult) => { /* your handler */ },
  onError: (event) => { /* your handler */ },

  // Custom metadata (optional)
  metadata: { userId: 'user-123', feature: 'chat' },
});
```

### `PlottAIClient`

For long-running services where you want to reuse the client:

```typescript
import { PlottAIClient } from '@plott-ai/sdk-vercel-ai';

// Create once at startup
const plott = new PlottAIClient({
  apiKey: 'cpk_...',
  debug: true,
});

// Use for each request
const result = await streamText({
  model,
  messages,
  ...plott.createCallbacks({ sessionId }),
});

// Graceful shutdown
await plott.shutdown();
```

## What Gets Tracked

| Event Type | Description |
|------------|-------------|
| `MESSAGE` | User and assistant messages with token counts |
| `CUSTOM` (tool-call) | Tool invocations with name, args, and timing |
| `CUSTOM` (tool-result) | Tool results and latency |
| `ERROR` | Errors during generation |
| `RUN_EVENT` | Start/end of each generation run |
| `STATE_SNAPSHOT` | Token usage, finish reasons, step details |
| `CHECKPOINT` | Automatic checkpoints every 5 turns |

## Works With

- `streamText()` - Streaming text generation
- `generateText()` - Non-streaming text generation
- Tools and multi-step generation
- All Vercel AI SDK providers (OpenAI, Anthropic, etc.)

## TypeScript

Full TypeScript support with exported types:

```typescript
import type {
  PlottCallbackOptions,
  PlottCallbacks,
  OnChunkCallback,
  OnFinishCallback,
} from '@plott-ai/sdk-vercel-ai';
```

## License

MIT