primeorbit-sdk 0.1.0

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,201 @@
+# 📘 PrimeOrbit JavaScript Client — Complete Getting Started Guide
+
+# 🚀 Overview
+
+We can track conversations, model responses, user feedback, and custom analytics
+through a simple event-based API.
+
+# 📦 Installation
+
+Install the SDK using:
+
+```bash
+npm install primeorbit-sdk
+```
+
+🔧 Import & Initialize
+
+```javascript
+import { PrimeOrbitClient } from 'primeorbit-sdk';
+
+const po = new PrimeOrbitClient(
+  'np_live_abc123', // Your API Key
+  'http://localhost:8000', // Endpoint
+);
+```
+
+Note: You will receive your API key and the endpoint when you onboard with
+PrimeOrbit. Each API key is unique to your organization and should be kept
+confidential. Use this key to authenticate requests to the PrimeOrbit backend.
+
+You can either pass the api_key and endpoint parameter directly when creating
+the client, or set PRIMEORBIT_API_KEY and PRIMEORBIT_ENDPOINT in a .env file —
+the client will automatically use it if the parameter is not provided.
+
+🧩 Set Base Properties (Required Once)
+
+Call this once when your app loads or when the user session starts:
+
+```javacript
+po.add_properties({
+  agentId: "agent_456",
+  conversationId: "conv_789",
+  userId: "user_123",
+  sessionId: "sess_001",
+  platform: "web"
+});
+```
+
+These will be automatically included in every event.
+
+## 📝 Supported Event Types
+
+**Message Events:**
+
+- `user_message`
+- `agent_response`
+
+**Feedback Events:**
+
+- `user_feedback`
+- `star_rating`
+- `thumbs_feedback`
+
+## 🧱 Required Fields for Every Event
+
+Regardless of event type, the following fields must always be present:
+
+| Field            | Type   | Description                             |
+| ---------------- | ------ | --------------------------------------- |
+| `conversationId` | string | Unique ID representing the conversation |
+| `userId`         | string | ID of the end user                      |
+| `content`        | string | Message text or feedback content        |
+
+These four fields are mandatory for all events.
+
+Tip: To avoid repeating conversationId, agentId, and userId in every event, it’s
+better to configure them once using po.add_properties(). You can then pass only
+content and any event-specific fields in each record_raw_event() call. This
+keeps your code clean and consistent.
+
+## 🧩 Optional Supported Fields
+
+In addition to the required fields, you may send any of the following optional
+attributes:
+
+| Field                  | Type         | Description                                      |
+| ---------------------- | ------------ | ------------------------------------------------ |
+| `eventId`              | string       | Optional unique event identifier                 |
+| `agentId`              | string       | ID of the agent/app/model that handled the event |
+| `sessionId`            | string       | Session identifier                               |
+| `inputMode`            | string       | e.g., `"text"`, `"voice"`, `"button"`            |
+| `experimentId`         | string       | A/B test or experiment tracking                  |
+| `productId`            | string       | Product or feature identifier                    |
+| `errorMessage`         | string       | Error info for debugging                         |
+| `country`              | string       | User’s country                                   |
+| `device`               | string       | Device type (`mobile`, `desktop`)                |
+| `platform`             | string       | Platform (`web`, `ios`, `android`)               |
+| `timestamp`            | datetime ISO | Auto-generated if omitted                        |
+| `model`                | string       | Model name for `agent_response` events           |
+| `additionalProperties` | dict         | Automatically populated metadata bucket          |
+
+> Any unsupported fields you send will automatically be placed inside
+> `additionalProperties`.
+
+additionalProperties: { ... } No data is lost — PrimeOrbit captures everything.
+
+## 📤 Recording Events
+
+The primary method for sending events:
+
+```javascript
+po.record_raw_event(event_type, propertiesObject);
+```
+
+📚 Event Examples
+
+1️⃣ User Message Event
+
+```javascript
+po.record_raw_event('user_message', {
+  content: 'Hello, I need help!',
+});
+```
+
+2️⃣ Agent Response Event
+
+```javascript
+po.record_raw_event('agent_response', {
+  content: 'Sure! What can I help you with?',
+  model: 'gpt-5.1',
+});
+```
+
+3️⃣ User Feedback (Free Text)
+
+```javascript
+po.record_raw_event('user_feedback', {
+  content: "The answer wasn't very helpful.",
+});
+```
+
+4️⃣ Star Rating Event
+
+```javascript
+po.record_raw_event('star_rating', {
+  content: '4',
+});
+```
+
+5️⃣ Thumbs Feedback Event
+
+```javascript
+po.record_raw_event('thumbs_feedback', {
+  content: 'thumbs_down',
+});
+```
+
+6️⃣ Full example:
+
+```javascript
+import { PrimeOrbitClient } from 'primeorbit-sdk';
+
+// Initialize the client (endpoint from parameter or .env)
+const po = new PrimeOrbitClient('YOUR_API_KEY');
+
+// Add conversation metadata including agent_id
+po.add_properties({
+  userId: 'user_123',
+  agentId: 'agent_001',
+  conversationId: 'conv_456',
+  sessionId: 'session_789',
+});
+
+// Dummy function simulating sending a message to your bot/system
+async function sendMessageToBot(message) {
+  // Simulate processing delay
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  return { message: `Bot reply to: "${message}"` };
+}
+
+async function runConversation() {
+  const userMessage = 'Hello, I need help!';
+
+  // Record user message *before* sending to bot
+  po.record_raw_event('user_message', {
+    content: userMessage,
+  });
+
+  // Send the message to the bot
+  const botResponse = await sendMessageToBot(userMessage);
+
+  // Record bot response as agent_response
+  po.record_raw_event('agent_response', {
+    content: botResponse.message,
+  });
+
+  console.log('Bot response recorded:', botResponse.message);
+}
+
+runConversation();
+```

package/build/index.cjs

@@ -0,0 +1,320 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PrimeOrbitClient: () => PrimeOrbitClient,
+  getNovaPhaseApiUrl: () => getNovaPhaseApiUrl,
+  record_star_rating: () => record_star_rating,
+  record_thumbs_feedback: () => record_thumbs_feedback,
+  setNovaPhaseApiUrl: () => setNovaPhaseApiUrl,
+  wrapToRecordLatency: () => wrapToRecordLatency
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api_utils.ts
+async function recordData(endpoint, payload, headers = { "Content-Type": "application/json" }) {
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload)
+  });
+  const text = await res.text();
+  let responseBody;
+  try {
+    responseBody = text ? JSON.parse(text) : null;
+  } catch {
+    responseBody = text;
+  }
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
+  }
+  return responseBody;
+}
+
+// src/routes.ts
+var routes = {
+  latencies: "/system-metrics/latencies",
+  "star-ratings": "/user-metrics/star-ratings",
+  "thumbs-feedbacks": "/user-metrics/thumbs-feedbacks",
+  "raw-events": "/user-metrics/raw-events"
+};
+
+// src/system_metrics/measure_latency.ts
+function recordLatency(startTime, agentId, actionId, actionFailed) {
+  const endTime = performance.now();
+  const latency = Math.floor(endTime - startTime);
+  recordData(routes["latencies"], {
+    agent_id: agentId,
+    latency,
+    action_id: actionId,
+    action_failed: actionFailed
+  });
+}
+function wrapToRecordLatency(fn, agentId, actionId = "") {
+  return function(...args) {
+    const start = performance.now();
+    let failed = true;
+    const agentActionId = actionId || fn.name;
+    try {
+      const result = fn.apply(this, args);
+      if (result instanceof Promise) {
+        return result.then((res) => {
+          failed = false;
+          recordLatency(start, agentId, agentActionId, failed);
+          return res;
+        }).catch((err) => {
+          recordLatency(start, agentId, agentActionId, failed);
+          throw err;
+        });
+      } else {
+        failed = false;
+        recordLatency(start, agentId, agentActionId, failed);
+        return result;
+      }
+    } catch (err) {
+      recordLatency(start, agentId, agentActionId, failed);
+      throw err;
+    }
+  };
+}
+
+// src/config.ts
+var baseApiUrl;
+function setNovaPhaseApiUrl(url) {
+  baseApiUrl = url;
+}
+function getNovaPhaseApiUrl() {
+  if (!baseApiUrl) {
+    throw new Error(
+      `NovaPhase API URL is not set. Please call 'setNovaPhaseApiUrl(<url>)' before using the SDK.`
+    );
+  }
+  return baseApiUrl;
+}
+
+// src/user_metrics/record_star_rating.ts
+async function record_star_rating(agentId, rating, taskName, userId = "") {
+  try {
+    const payload = {
+      agent_id: agentId,
+      rating,
+      task_name: taskName
+    };
+    if (userId) {
+      payload.user_id = userId;
+    }
+    await recordData(routes["star-ratings"], payload);
+  } catch (err) {
+    console.error(
+      `[NovaPhase SDK] recordData failed: ${err.message}`
+    );
+  }
+}
+
+// src/user_metrics/record_thumbs_feedback.ts
+async function record_thumbs_feedback(agentId, isThumbsUp, taskName, userId = "") {
+  try {
+    const payload = {
+      agent_id: agentId,
+      is_thumbs_up: isThumbsUp,
+      task_name: taskName
+    };
+    if (userId) {
+      payload.user_id = userId;
+    }
+    await recordData(routes["thumbs-feedbacks"], payload);
+  } catch (err) {
+    console.error(
+      `[NovaPhase SDK] Failed to record thumbs feedback: ${err.message}`
+    );
+  }
+}
+
+// src/user_metrics/record_user_event.ts
+var dotenv = __toESM(require("dotenv"), 1);
+dotenv.config();
+var PrimeOrbitClient = class {
+  apiKey;
+  baseUrl;
+  baseProperties = {};
+  verbose = false;
+  /**
+   * @param {string} apiKey - Your PrimeOrbit API key
+   * @param {string} [endpoint] -  endpoint URL
+   */
+  constructor(apiKey, endpoint) {
+    if (apiKey) {
+      this.apiKey = apiKey;
+    } else if (process.env.PRIMEORBIT_API_KEY) {
+      this.apiKey = process.env.PRIMEORBIT_API_KEY;
+    } else {
+      throw new Error(
+        "API key not provided. Set the 'apiKey' parameter or the 'PRIMEORBIT_API_KEY' environment variable."
+      );
+    }
+    if (endpoint) {
+      this.baseUrl = endpoint;
+    } else if (process.env.PRIMEORBIT_ENDPOINT) {
+      this.baseUrl = process.env.PRIMEORBIT_ENDPOINT;
+    } else {
+      this.baseUrl = "https://sdk-dev.primeorbit.ai";
+    }
+    this.baseProperties = {};
+  }
+  add_properties(props) {
+    this.baseProperties = {
+      ...this.baseProperties,
+      ...props
+    };
+  }
+  _headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+  }
+  /**
+   * Records any agent interaction event such as user_question, agent_response, or user_feedback.
+   *
+   * @param eventType - Type of event. Can be:
+   *   - 'user_question' – when the user asks a question
+   *   - 'agent_response' – when the agent replies
+   *   - 'user_feedback' – when the user gives feedback
+   *
+   * @param params - Object containing event details:
+   *   - conversationId: string – Unique conversation identifier
+   *   - agentId: string – Agent ID
+   *   - userId: string – User ID
+   *   - productId?: string – Optional product ID
+   *   - content: string – Text content of the event (user question, agent reply, or feedback)
+   *   - sessionId?: string – Optional session ID
+   *   - messageId?: string – Optional message ID (for tracking within conversation)
+   *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+   *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+   *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+   *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+   *   - language?: string – Optional language of the user (e.g., 'en-US')
+   *   - Any additional properties will be captured in additional_properties
+   */
+  async record_raw_event(eventType, params) {
+    const finalParams = {
+      ...this.baseProperties,
+      ...params
+    };
+    try {
+      const {
+        conversationId,
+        messageId,
+        agentId,
+        userId,
+        appId,
+        content,
+        sessionId,
+        eventId,
+        inputMode,
+        device,
+        country,
+        platform,
+        experimentId,
+        ...extraProps
+      } = finalParams;
+      const requiredFields = ["conversationId", "userId", "content"];
+      const missingRequired = requiredFields.filter(
+        (field) => !(field in finalParams) || finalParams[field] === void 0
+      );
+      if (missingRequired.length > 0) {
+        throw new Error(
+          `Missing required fields: ${missingRequired.join(", ")}`
+        );
+      }
+      const optionalFields = [
+        "agentId",
+        "sessionId",
+        "eventId",
+        "messageId",
+        "experimentId",
+        "inputMode",
+        "device",
+        "country",
+        "platform",
+        "appId",
+        "model"
+      ];
+      const missingOptionals = optionalFields.filter(
+        (field) => !(field in finalParams) || finalParams[field] === void 0
+      );
+      if (missingOptionals.length > 0) {
+        if (this.verbose) {
+          console.warn(
+            `[PrimeOrbit Analytics Warning] Missing optional fields: ${missingOptionals.join(", ")}. Analytics may be less accurate or incomplete.`
+          );
+        }
+      }
+      const payload = {
+        event_type: eventType,
+        conversation_id: conversationId,
+        session_id: sessionId,
+        user_id: userId,
+        agent_id: agentId,
+        message_id: messageId,
+        event_id: eventId,
+        app_id: appId,
+        content,
+        input_mode: inputMode,
+        device,
+        country,
+        platform,
+        experiment_id: experimentId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        additional_properties: Object.keys(extraProps).length > 0 ? extraProps : void 0
+      };
+      console.log("[PrimeOrbit] Recording event:", payload);
+      await recordData(
+        `${this.baseUrl}${routes["raw-events"]}`,
+        payload,
+        this._headers()
+      );
+    } catch (err) {
+      console.error(
+        `[PrimeOrbit Error] recording_event failed}: ${err}`
+      );
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PrimeOrbitClient,
+  getNovaPhaseApiUrl,
+  record_star_rating,
+  record_thumbs_feedback,
+  setNovaPhaseApiUrl,
+  wrapToRecordLatency
+});

package/build/index.d.cts

@@ -0,0 +1,76 @@
+/**
+ * Wraps a synchronous or asynchronous function and logs its execution latency.
+ *
+ * @template T - A function type with any parameters and return type.
+ * @param {T} fn - The function to be wrapped.
+ * @param {string} agentId - Identifier for the agent.
+ * @param {string} actionId - Identifier for the action id. If not provided, defaults to the name of the function `fn`.
+ * @returns {(...args: Parameters<T>) => ReturnType<T>} A wrapped function that logs latency and returns the same result as `fn`.
+ */
+declare function wrapToRecordLatency<T extends (...args: unknown[]) => unknown>(fn: T, agentId: string, actionId?: string): (...args: Parameters<T>) => ReturnType<T>;
+
+declare function setNovaPhaseApiUrl(url: string): void;
+declare function getNovaPhaseApiUrl(): string;
+
+/**
+ * Records a star rating for an agent after task completion.
+ *
+ * @param agentId - Unique identifier for the agent
+ * @param rating - Star rating given (e.g. 1–5)
+ * @param taskName - Name of completed task
+ * @param userId - Optional ID of the user giving the rating
+ */
+declare function record_star_rating(agentId: string, rating: number, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * Sends thumbs-up/down feedback to the backend.
+ *
+ * @param agentId - ID of the agent being rated
+ * @param isThumbsUp - true if thumbs up, false if thumbs down
+ * @param taskName - summary of the task
+ * @param userId - ID of the user who provided the feedback; defaults to ''.
+ */
+declare function record_thumbs_feedback(agentId: string, isThumbsUp: boolean, taskName: string, userId?: string): Promise<void>;
+
+declare class PrimeOrbitClient {
+    private apiKey;
+    private baseUrl;
+    private baseProperties;
+    private verbose;
+    /**
+     * @param {string} apiKey - Your PrimeOrbit API key
+     * @param {string} [endpoint] -  endpoint URL
+     */
+    constructor(apiKey?: string, endpoint?: string);
+    add_properties(props: Record<string, unknown>): void;
+    _headers(): {
+        Authorization: string;
+        'Content-Type': string;
+    };
+    /**
+     * Records any agent interaction event such as user_question, agent_response, or user_feedback.
+     *
+     * @param eventType - Type of event. Can be:
+     *   - 'user_question' – when the user asks a question
+     *   - 'agent_response' – when the agent replies
+     *   - 'user_feedback' – when the user gives feedback
+     *
+     * @param params - Object containing event details:
+     *   - conversationId: string – Unique conversation identifier
+     *   - agentId: string – Agent ID
+     *   - userId: string – User ID
+     *   - productId?: string – Optional product ID
+     *   - content: string – Text content of the event (user question, agent reply, or feedback)
+     *   - sessionId?: string – Optional session ID
+     *   - messageId?: string – Optional message ID (for tracking within conversation)
+     *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+     *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+     *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+     *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+     *   - language?: string – Optional language of the user (e.g., 'en-US')
+     *   - Any additional properties will be captured in additional_properties
+     */
+    record_raw_event(eventType: 'user_question' | 'agent_response' | 'user_feedback', params: Record<string, unknown>): Promise<void>;
+}
+
+export { PrimeOrbitClient, getNovaPhaseApiUrl, record_star_rating, record_thumbs_feedback, setNovaPhaseApiUrl, wrapToRecordLatency };

package/build/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Wraps a synchronous or asynchronous function and logs its execution latency.
+ *
+ * @template T - A function type with any parameters and return type.
+ * @param {T} fn - The function to be wrapped.
+ * @param {string} agentId - Identifier for the agent.
+ * @param {string} actionId - Identifier for the action id. If not provided, defaults to the name of the function `fn`.
+ * @returns {(...args: Parameters<T>) => ReturnType<T>} A wrapped function that logs latency and returns the same result as `fn`.
+ */
+declare function wrapToRecordLatency<T extends (...args: unknown[]) => unknown>(fn: T, agentId: string, actionId?: string): (...args: Parameters<T>) => ReturnType<T>;
+
+declare function setNovaPhaseApiUrl(url: string): void;
+declare function getNovaPhaseApiUrl(): string;
+
+/**
+ * Records a star rating for an agent after task completion.
+ *
+ * @param agentId - Unique identifier for the agent
+ * @param rating - Star rating given (e.g. 1–5)
+ * @param taskName - Name of completed task
+ * @param userId - Optional ID of the user giving the rating
+ */
+declare function record_star_rating(agentId: string, rating: number, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * Sends thumbs-up/down feedback to the backend.
+ *
+ * @param agentId - ID of the agent being rated
+ * @param isThumbsUp - true if thumbs up, false if thumbs down
+ * @param taskName - summary of the task
+ * @param userId - ID of the user who provided the feedback; defaults to ''.
+ */
+declare function record_thumbs_feedback(agentId: string, isThumbsUp: boolean, taskName: string, userId?: string): Promise<void>;
+
+declare class PrimeOrbitClient {
+    private apiKey;
+    private baseUrl;
+    private baseProperties;
+    private verbose;
+    /**
+     * @param {string} apiKey - Your PrimeOrbit API key
+     * @param {string} [endpoint] -  endpoint URL
+     */
+    constructor(apiKey?: string, endpoint?: string);
+    add_properties(props: Record<string, unknown>): void;
+    _headers(): {
+        Authorization: string;
+        'Content-Type': string;
+    };
+    /**
+     * Records any agent interaction event such as user_question, agent_response, or user_feedback.
+     *
+     * @param eventType - Type of event. Can be:
+     *   - 'user_question' – when the user asks a question
+     *   - 'agent_response' – when the agent replies
+     *   - 'user_feedback' – when the user gives feedback
+     *
+     * @param params - Object containing event details:
+     *   - conversationId: string – Unique conversation identifier
+     *   - agentId: string – Agent ID
+     *   - userId: string – User ID
+     *   - productId?: string – Optional product ID
+     *   - content: string – Text content of the event (user question, agent reply, or feedback)
+     *   - sessionId?: string – Optional session ID
+     *   - messageId?: string – Optional message ID (for tracking within conversation)
+     *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+     *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+     *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+     *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+     *   - language?: string – Optional language of the user (e.g., 'en-US')
+     *   - Any additional properties will be captured in additional_properties
+     */
+    record_raw_event(eventType: 'user_question' | 'agent_response' | 'user_feedback', params: Record<string, unknown>): Promise<void>;
+}
+
+export { PrimeOrbitClient, getNovaPhaseApiUrl, record_star_rating, record_thumbs_feedback, setNovaPhaseApiUrl, wrapToRecordLatency };

package/build/index.js

@@ -0,0 +1,278 @@
+// src/api_utils.ts
+async function recordData(endpoint, payload, headers = { "Content-Type": "application/json" }) {
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload)
+  });
+  const text = await res.text();
+  let responseBody;
+  try {
+    responseBody = text ? JSON.parse(text) : null;
+  } catch {
+    responseBody = text;
+  }
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
+  }
+  return responseBody;
+}
+
+// src/routes.ts
+var routes = {
+  latencies: "/system-metrics/latencies",
+  "star-ratings": "/user-metrics/star-ratings",
+  "thumbs-feedbacks": "/user-metrics/thumbs-feedbacks",
+  "raw-events": "/user-metrics/raw-events"
+};
+
+// src/system_metrics/measure_latency.ts
+function recordLatency(startTime, agentId, actionId, actionFailed) {
+  const endTime = performance.now();
+  const latency = Math.floor(endTime - startTime);
+  recordData(routes["latencies"], {
+    agent_id: agentId,
+    latency,
+    action_id: actionId,
+    action_failed: actionFailed
+  });
+}
+function wrapToRecordLatency(fn, agentId, actionId = "") {
+  return function(...args) {
+    const start = performance.now();
+    let failed = true;
+    const agentActionId = actionId || fn.name;
+    try {
+      const result = fn.apply(this, args);
+      if (result instanceof Promise) {
+        return result.then((res) => {
+          failed = false;
+          recordLatency(start, agentId, agentActionId, failed);
+          return res;
+        }).catch((err) => {
+          recordLatency(start, agentId, agentActionId, failed);
+          throw err;
+        });
+      } else {
+        failed = false;
+        recordLatency(start, agentId, agentActionId, failed);
+        return result;
+      }
+    } catch (err) {
+      recordLatency(start, agentId, agentActionId, failed);
+      throw err;
+    }
+  };
+}
+
+// src/config.ts
+var baseApiUrl;
+function setNovaPhaseApiUrl(url) {
+  baseApiUrl = url;
+}
+function getNovaPhaseApiUrl() {
+  if (!baseApiUrl) {
+    throw new Error(
+      `NovaPhase API URL is not set. Please call 'setNovaPhaseApiUrl(<url>)' before using the SDK.`
+    );
+  }
+  return baseApiUrl;
+}
+
+// src/user_metrics/record_star_rating.ts
+async function record_star_rating(agentId, rating, taskName, userId = "") {
+  try {
+    const payload = {
+      agent_id: agentId,
+      rating,
+      task_name: taskName
+    };
+    if (userId) {
+      payload.user_id = userId;
+    }
+    await recordData(routes["star-ratings"], payload);
+  } catch (err) {
+    console.error(
+      `[NovaPhase SDK] recordData failed: ${err.message}`
+    );
+  }
+}
+
+// src/user_metrics/record_thumbs_feedback.ts
+async function record_thumbs_feedback(agentId, isThumbsUp, taskName, userId = "") {
+  try {
+    const payload = {
+      agent_id: agentId,
+      is_thumbs_up: isThumbsUp,
+      task_name: taskName
+    };
+    if (userId) {
+      payload.user_id = userId;
+    }
+    await recordData(routes["thumbs-feedbacks"], payload);
+  } catch (err) {
+    console.error(
+      `[NovaPhase SDK] Failed to record thumbs feedback: ${err.message}`
+    );
+  }
+}
+
+// src/user_metrics/record_user_event.ts
+import * as dotenv from "dotenv";
+dotenv.config();
+var PrimeOrbitClient = class {
+  apiKey;
+  baseUrl;
+  baseProperties = {};
+  verbose = false;
+  /**
+   * @param {string} apiKey - Your PrimeOrbit API key
+   * @param {string} [endpoint] -  endpoint URL
+   */
+  constructor(apiKey, endpoint) {
+    if (apiKey) {
+      this.apiKey = apiKey;
+    } else if (process.env.PRIMEORBIT_API_KEY) {
+      this.apiKey = process.env.PRIMEORBIT_API_KEY;
+    } else {
+      throw new Error(
+        "API key not provided. Set the 'apiKey' parameter or the 'PRIMEORBIT_API_KEY' environment variable."
+      );
+    }
+    if (endpoint) {
+      this.baseUrl = endpoint;
+    } else if (process.env.PRIMEORBIT_ENDPOINT) {
+      this.baseUrl = process.env.PRIMEORBIT_ENDPOINT;
+    } else {
+      this.baseUrl = "https://sdk-dev.primeorbit.ai";
+    }
+    this.baseProperties = {};
+  }
+  add_properties(props) {
+    this.baseProperties = {
+      ...this.baseProperties,
+      ...props
+    };
+  }
+  _headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+  }
+  /**
+   * Records any agent interaction event such as user_question, agent_response, or user_feedback.
+   *
+   * @param eventType - Type of event. Can be:
+   *   - 'user_question' – when the user asks a question
+   *   - 'agent_response' – when the agent replies
+   *   - 'user_feedback' – when the user gives feedback
+   *
+   * @param params - Object containing event details:
+   *   - conversationId: string – Unique conversation identifier
+   *   - agentId: string – Agent ID
+   *   - userId: string – User ID
+   *   - productId?: string – Optional product ID
+   *   - content: string – Text content of the event (user question, agent reply, or feedback)
+   *   - sessionId?: string – Optional session ID
+   *   - messageId?: string – Optional message ID (for tracking within conversation)
+   *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+   *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+   *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+   *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+   *   - language?: string – Optional language of the user (e.g., 'en-US')
+   *   - Any additional properties will be captured in additional_properties
+   */
+  async record_raw_event(eventType, params) {
+    const finalParams = {
+      ...this.baseProperties,
+      ...params
+    };
+    try {
+      const {
+        conversationId,
+        messageId,
+        agentId,
+        userId,
+        appId,
+        content,
+        sessionId,
+        eventId,
+        inputMode,
+        device,
+        country,
+        platform,
+        experimentId,
+        ...extraProps
+      } = finalParams;
+      const requiredFields = ["conversationId", "userId", "content"];
+      const missingRequired = requiredFields.filter(
+        (field) => !(field in finalParams) || finalParams[field] === void 0
+      );
+      if (missingRequired.length > 0) {
+        throw new Error(
+          `Missing required fields: ${missingRequired.join(", ")}`
+        );
+      }
+      const optionalFields = [
+        "agentId",
+        "sessionId",
+        "eventId",
+        "messageId",
+        "experimentId",
+        "inputMode",
+        "device",
+        "country",
+        "platform",
+        "appId",
+        "model"
+      ];
+      const missingOptionals = optionalFields.filter(
+        (field) => !(field in finalParams) || finalParams[field] === void 0
+      );
+      if (missingOptionals.length > 0) {
+        if (this.verbose) {
+          console.warn(
+            `[PrimeOrbit Analytics Warning] Missing optional fields: ${missingOptionals.join(", ")}. Analytics may be less accurate or incomplete.`
+          );
+        }
+      }
+      const payload = {
+        event_type: eventType,
+        conversation_id: conversationId,
+        session_id: sessionId,
+        user_id: userId,
+        agent_id: agentId,
+        message_id: messageId,
+        event_id: eventId,
+        app_id: appId,
+        content,
+        input_mode: inputMode,
+        device,
+        country,
+        platform,
+        experiment_id: experimentId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        additional_properties: Object.keys(extraProps).length > 0 ? extraProps : void 0
+      };
+      console.log("[PrimeOrbit] Recording event:", payload);
+      await recordData(
+        `${this.baseUrl}${routes["raw-events"]}`,
+        payload,
+        this._headers()
+      );
+    } catch (err) {
+      console.error(
+        `[PrimeOrbit Error] recording_event failed}: ${err}`
+      );
+    }
+  }
+};
+export {
+  PrimeOrbitClient,
+  getNovaPhaseApiUrl,
+  record_star_rating,
+  record_thumbs_feedback,
+  setNovaPhaseApiUrl,
+  wrapToRecordLatency
+};

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "primeorbit-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "build"
+  ],
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "exports": {
+    "import": "./build/index.js",
+    "require": "./build/index.js"
+  },
+  "directories": {
+    "src": "src",
+    "tests": "tests"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir build",
+    "prepare": "husky",
+    "test": "jest",
+    "bundle": "npm run build && npm pack",
+    "prepublishOnly": "npm run test && npm run build",
+    "version:patch": "npm version patch --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version",
+    "version:major": "npm version major --no-git-tag-version",
+    "publish:latest": "npm run build && npm publish --tag latest",
+    "publish:patch": "npm run version:patch && npm run build && npm publish --tag latest",
+    "publish:minor": "npm run version:minor && npm run build && npm publish --tag latest",
+    "publish:major": "npm run version:major && npm run build && npm publish --tag latest",
+    "publish:beta": "npm run build && npm publish --tag beta",
+    "publish:beta:patch": "npm run version:patch && npm run build && npm publish --tag beta",
+    "publish:alpha": "npm run build && npm publish --tag alpha",
+    "publish:alpha:patch": "npm run version:patch && npm run build && npm publish --tag alpha",
+    "publish:next": "npm run build && npm publish --tag next",
+    "publish:next:patch": "npm run version:patch && npm run build && npm publish --tag next"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "{src,tests}/**/*.{js,jsx,ts,tsx}": [
+      "npx eslint --fix",
+      "npx prettier --write --ignore-unknown",
+      "npx jest --findRelatedTests"
+    ],
+    "docs/**/*.md": "mdformat --wrap 80 --number",
+    "scripts/**/*.sh": "shellcheck -x"
+  },
+  "prettier": {
+    "proseWrap": "always",
+    "singleQuote": true
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.34.0",
+    "@jest/globals": "^30.1.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.3.0",
+    "@types/supertest": "^6.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.41.0",
+    "@typescript-eslint/parser": "^8.41.0",
+    "eslint": "^9.34.0",
+    "eslint-config-love": "^122.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.21.3",
+    "eslint-plugin-promise": "^7.2.1",
+    "husky": "^9.1.7",
+    "jest": "^30.1.1",
+    "jest-fetch-mock": "^3.0.3",
+    "lint-staged": "^16.1.5",
+    "npm-check-updates": "^18.0.3",
+    "prettier": "^3.6.2",
+    "supertest": "^7.1.4",
+    "ts-jest": "^29.4.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.7",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.3"
+  }
+}