@onlive.ai/tracker

Official tracking library and data schemas for the Onlive platform.

🌟 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:

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.

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

const tracker = new Tracker({ 
  apiUrl: 'https://srvless.onlive.ai/tracking' // Note: Use https://lfhew0-srvless.onlive.ai/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

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

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

CDN / UMD (Browser Script)

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

<script src="https://cdn.onlive.ai/@onlive.ai/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.ai/tracking' });
  
  tracker.send('impression', {
    // ... payload
  });
</script>

API Endpoints

• Production: https://srvless.onlive.ai/tracking
• Staging: https://lfhew0-srvless.onlive.ai/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):

   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):

   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):

   import { z } from 'zod';
      
   export const MyPropertiesData = z.object({
     property1: z.string(),
     property2: z.number().optional(),
   });

2. Compose directly into an Event:

   import { MyPropertiesData } from '../data/my-properties.data';
   
   export const ExtendedEvent = BaseEvent.extend({
     ...MyPropertiesData.shape,
   });

👨‍💻 Development & Maintenance

Setup Steps

# 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:

pnpm generate:docs

Formatting Requirement for JSDoc

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

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

For individual inner properties:

/**
 * @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.

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.