PrimeOrbit JavaScript SDK

Track conversations, model responses, user feedback, and custom analytics through a simple event-based API.

Installation

npm install primeorbit

Quick Start

import { PrimeOrbitClient } from 'primeorbit';

const po = new PrimeOrbitClient(
  'np_live_abc123', // Your API Key
  'https://sdk.primeorbit.ai', // Endpoint
);

// Set base properties once
po.add_properties({
  agentId: 'agent_456',
  conversationId: 'conv_789',
  userId: 'user_123',
});

// Record events
po.record_raw_event('user_message', {
  content: 'Hello, I need help!',
});

Configuration

API Key and Endpoint

You can provide credentials in two ways:

1. Direct parameters:

const po = new PrimeOrbitClient('your-api-key', 'https://sdk.primeorbit.ai');

2. Environment variables:

PRIMEORBIT_API_KEY=your-api-key
PRIMEORBIT_ENDPOINT=https://sdk.primeorbit.ai

const po = new PrimeOrbitClient(); // Uses env variables

Logging

Control SDK logging verbosity:

import { setLogLevel } from 'primeorbit';

// Available levels: 'debug', 'info', 'warn', 'error', 'silent'
setLogLevel('debug'); // Show all logs including debug
setLogLevel('error'); // Only show errors
setLogLevel('silent'); // Disable all logging

Base Properties

Set properties once to include in all events:

po.add_properties({
  agentId: 'agent_456',
  conversationId: 'conv_789',
  userId: 'user_123',
  sessionId: 'sess_001',
  platform: 'web',
});

Event Types

Message Events

• user_message - User sends a message
• agent_response - Agent/bot responds

Feedback Events

• user_feedback - Free text feedback

Required Fields

| Field | Type | Description | | ---------------- | ------ | --------------------------------------- | | conversationId | string | Unique ID representing the conversation | | userId | string | ID of the end user | | content | string | Message text or feedback content |

Optional Fields

| Field | Type | Description | | -------------- | ------ | ------------------------------------------------ | | eventId | string | Unique event identifier | | agentId | string | ID of the agent/app/model that handled the event | | sessionId | string | Session identifier | | messageId | string | Message ID for tracking within conversation | | inputMode | string | e.g., "text", "voice", "button" | | experimentId | string | A/B test or experiment tracking | | appId | string | Application identifier | | device | string | Device type (mobile, desktop) | | country | string | User's country (ISO code) | | platform | string | Platform (web, ios, android) | | model | string | Model name for agent_response events |

Any additional fields are captured in additional_properties.

Event Examples

User Message

po.record_raw_event('user_message', {
  content: 'Hello, I need help!',
});

Agent Response

po.record_raw_event('agent_response', {
  content: 'Sure! What can I help you with?',
  model: 'gpt-4',
});

User Feedback

po.record_raw_event('user_feedback', {
  content: "The answer wasn't very helpful.",
});

Latency Tracking

Wrap functions to automatically track execution time:

import { wrapToRecordLatency } from 'primeorbit';

// Wrap any function
const wrappedFn = wrapToRecordLatency(myFunction, 'agent-id', 'action-name');

// For type-safe async/sync wrappers
import { wrapAsyncToRecordLatency, wrapSyncToRecordLatency } from 'primeorbit';

const wrappedAsync = wrapAsyncToRecordLatency(myAsyncFn, 'agent-id');
const wrappedSync = wrapSyncToRecordLatency(mySyncFn, 'agent-id');

Standalone Feedback Functions

import { record_star_rating, record_thumbs_feedback } from 'primeorbit';

// Star rating (1-5)
record_star_rating('agent-id', 5, 'task-name', 'user-id');

// Thumbs feedback
record_thumbs_feedback('agent-id', true, 'task-name', 'user-id'); // thumbs up
record_thumbs_feedback('agent-id', false, 'task-name', 'user-id'); // thumbs down

Complete Example

import { PrimeOrbitClient, setLogLevel } from 'primeorbit';

// Configure logging (optional)
setLogLevel('info');

// Initialize the client
const po = new PrimeOrbitClient('YOUR_API_KEY', 'https://sdk.primeorbit.ai');

// Set conversation metadata
po.add_properties({
  userId: 'user_123',
  agentId: 'agent_001',
  conversationId: 'conv_456',
  sessionId: 'session_789',
});

async function handleConversation() {
  const userMessage = 'Hello, I need help!';

  // Record user message
  await po.record_raw_event('user_message', {
    content: userMessage,
  });

  // Get bot response (your logic here)
  const botResponse = await getBotResponse(userMessage);

  // Record agent response
  await po.record_raw_event('agent_response', {
    content: botResponse,
    model: 'gpt-4',
  });
}

handleConversation();

TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

import { PrimeOrbitClient, LogLevel, setLogLevel } from 'primeorbit';

const level: LogLevel = 'debug';
setLogLevel(level);

const client = new PrimeOrbitClient('api-key');

API Reference

PrimeOrbitClient

• constructor(apiKey?: string, endpoint?: string) - Create a new client
• add_properties(props: Record<string, unknown>) - Set base properties
• record_raw_event(eventType, params) - Record an event

Logging

• setLogLevel(level: LogLevel) - Set log level
• getLogLevel(): LogLevel - Get current log level
• logger - Direct access to logger instance

Latency Tracking

• wrapToRecordLatency(fn, agentId, actionId?) - Wrap any function
• wrapSyncToRecordLatency(fn, agentId, actionId?) - Wrap sync function
• wrapAsyncToRecordLatency(fn, agentId, actionId?) - Wrap async function

Feedback

• record_star_rating(agentId, rating, taskName, userId?) - Record star rating
• record_thumbs_feedback(agentId, isThumbsUp, taskName, userId?) - Record thumbs

License

MIT