npm package: @onlive.ai/tracker
Description: > Official tracking library and data schemas for the Onlive platform.
Latest version: 1.0.48

# @onlive.ai/tracker

> Official tracking library and data schemas for the Onlive platform.

[![npm version](https://badge.fury.io/js/%40onlive.ai%2Ftracker.svg)](https://badge.fury.io/js/%40onlive.ai%2Ftracker)

## 🌟 Key Features

- **Type Safety**: Full TypeScript support with robust property autocomplete.
- **Schema Validation**: Uses Zod to strictly validate event payloads at runtime.
- **Modular Design**: Easily add, extend, and adapt new events and type schemas.
- **Reusable Property Sets**: Define and reuse common property sets across multiple events.

## 🚀 Quick Start

### Installation

Install the package via your preferred package manager:

```bash
npm install @onlive.ai/tracker
# or
pnpm add @onlive.ai/tracker
# or
yarn add @onlive.ai/tracker
```

### Basic Example (ESM)

Initialize the Tracker and send an event. 

```typescript
import { Tracker } from '@onlive.ai/tracker';

const tracker = new Tracker({ 
  apiUrl: 'https://srvless.onlive.site/tracking' // Note: Use https://lfhew0-srvless.onlive.site/tracking for staging
});

// Track an event
await tracker.send('impression', {
  organization_id: '123e4567-e89b-12d3-a456-426614174000',
  organization_name: 'Example Org',
  widget_id: '123e4567-e89b-12d3-a456-426614174002',
  widget_type: 'OnliveAppChatbot',
  page_url: window.location.href,
  // ... other required properties
});
```

*(Note: Provide all required schema properties according to the event definition).*

---

## 📖 Usage Options

The library is versatile and published in three standard module formats: **ESM**, **CommonJS**, and **UMD**.

### CommonJS

```javascript
const { Tracker } = require('@onlive.ai/tracker');

const tracker = new Tracker({ apiUrl: 'https://srvless.onlive.site/tracking' });
```

### CDN / UMD (Browser Script)

If you need to include the tracker directly into a browser environment without a build step:

```html
<script src="https://cdn.onlive.site/@onlive.site/tracker@latest/umd/tracker.js"></script>
<!-- Note: You can replace @latest with a specific version to pin a release, e.g., @1.0.45 -->
<script>
  const { Tracker } = window.OnliveTracker;
  const tracker = new Tracker({ apiUrl: 'https://srvless.onlive.site/tracking' });
  
  tracker.send('impression', {
    // ... payload
  });
</script>
```

### API Endpoints

- **Production**: `https://srvless.onlive.site/tracking`
- **Staging**: `https://lfhew0-srvless.onlive.site/tracking`

---

## 🏗️ Architecture & Extensibility

The core library is built to be scalable out-of-the-box. Events validate dynamically through definitions located at `src/tracker/events/` and partial common subsets under `src/tracker/data/`.

### Extending the Library: Adding a New Event Type

1. **Create the Event definition** (`src/tracker/events/my-event.ts`):
   ```typescript
   import { z } from 'zod';
   import { BaseEvent } from './event';
   import { OrganizationData } from '../data/organization.data';
   
   export const MyEvent = BaseEvent.extend({
     ...OrganizationData.shape,
     custom_property: z.string(),
   });
   
   export type MyEvent = z.infer<typeof MyEvent>;
   ```

2. **Register the Event** (`src/tracker/registry.ts`):
   ```typescript
   import { MyEvent } from './events/my-event';
   
   export const TrackRegistry = {
     // ...existing events
     my_event: MyEvent,
   } as const;
   ```

### Creating New Reusable Property Sets

1. **Define a Data Model** (`src/tracker/data/my-properties.data.ts`):
   ```typescript
   import { z } from 'zod';
   
   export const MyPropertiesData = z.object({
     property1: z.string(),
     property2: z.number().optional(),
   });
   ```

2. **Compose directly into an Event**:
   ```typescript
   import { MyPropertiesData } from '../data/my-properties.data';

   export const ExtendedEvent = BaseEvent.extend({
     ...MyPropertiesData.shape,
   });
   ```

---

## 👨‍💻 Development & Maintenance

### Setup Steps

```bash
# Install dependencies
pnpm install

# Build everything
pnpm build
```

### Documentation Generator

This repository includes a custom documentation pipeline that parses TypeScript files, JSDoc comments, and Zod schemas to build structured Markdown documentation (`docs/tracker-documentation.md`).

To generate the docs dynamically:

```bash
pnpm generate:docs
```

#### Formatting Requirement for JSDoc

For accurate markdown parsing, preserve this block structure spanning your events:

```typescript
/**
 * @name event_name
 * @description Detailed explanation of what triggers this event.
 *
 * @example
 * {
 *   "custom_property": "example value"
 * }
 */
```

For individual inner properties:

```typescript
/**
 * @description Text explaining this property.
 * @example "string-uuid", "custom_id"
 */
property: z.string();
```

### Publishing a New Release

This project uses modern semantic versioning through [Changesets](https://github.com/changesets/changesets). 

```bash
pnpm changeset         # Create a new changeset configuration
pnpm changeset version # Bump versions automatically
pnpm build             # Important: build the artifacts
pnpm publish           # Publish to npm registry
```

---
**Onlive Platform** – Internal Tracking and Data Models.