primeorbit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# PrimeOrbit JavaScript SDK
+
+Track conversations, model responses, user feedback, and custom analytics
+through a simple event-based API.
+
+## Installation
+
+```bash
+npm install primeorbit
+```
+
+## Quick Start
+
+```javascript
+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:**
+
+```javascript
+const po = new PrimeOrbitClient('your-api-key', 'https://sdk.primeorbit.ai');
+```
+
+2. **Environment variables:**
+
+```bash
+PRIMEORBIT_API_KEY=your-api-key
+PRIMEORBIT_ENDPOINT=https://sdk.primeorbit.ai
+```
+
+```javascript
+const po = new PrimeOrbitClient(); // Uses env variables
+```
+
+### Logging
+
+Control SDK logging verbosity:
+
+```javascript
+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:
+
+```javascript
+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
+
+```javascript
+po.record_raw_event('user_message', {
+  content: 'Hello, I need help!',
+});
+```
+
+### Agent Response
+
+```javascript
+po.record_raw_event('agent_response', {
+  content: 'Sure! What can I help you with?',
+  model: 'gpt-4',
+});
+```
+
+### User Feedback
+
+```javascript
+po.record_raw_event('user_feedback', {
+  content: "The answer wasn't very helpful.",
+});
+```
+
+## Latency Tracking
+
+Wrap functions to automatically track execution time:
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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.
+
+```typescript
+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