primeorbit 0.1.1

package/build/index.js

@@ -0,0 +1,649 @@
+// 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",
+  "raw-events-batch": "/user-metrics/raw-events/batch"
+};
+
+// src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4
+};
+var currentLogLevel = "info";
+function setLogLevel(level) {
+  currentLogLevel = level;
+}
+function getLogLevel() {
+  return currentLogLevel;
+}
+function shouldLog(level) {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLogLevel];
+}
+function formatMessage(level, message) {
+  return `[PrimeOrbit ${level.toUpperCase()}] ${message}`;
+}
+var logger = {
+  /**
+   * Log a debug message. Only shown when log level is 'debug'.
+   */
+  debug(message, ...args) {
+    if (shouldLog("debug")) {
+      console.debug(formatMessage("debug", message), ...args);
+    }
+  },
+  /**
+   * Log an informational message.
+   */
+  info(message, ...args) {
+    if (shouldLog("info")) {
+      console.info(formatMessage("info", message), ...args);
+    }
+  },
+  /**
+   * Log a warning message.
+   */
+  warn(message, ...args) {
+    if (shouldLog("warn")) {
+      console.warn(formatMessage("warn", message), ...args);
+    }
+  },
+  /**
+   * Log an error message.
+   */
+  error(message, ...args) {
+    if (shouldLog("error")) {
+      console.error(formatMessage("error", message), ...args);
+    }
+  }
+};
+
+// 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
+  }).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`Failed to record latency: ${message}`);
+  });
+}
+function isPromise(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const obj = value;
+  return "then" in obj && typeof obj["then"] === "function";
+}
+function wrapSyncToRecordLatency(fn, agentId, actionId) {
+  const resolvedActionId = actionId ?? fn.name;
+  return function(...args) {
+    const start = performance.now();
+    let failed = true;
+    try {
+      const result = fn.apply(this, args);
+      failed = false;
+      recordLatency(start, agentId, resolvedActionId, failed);
+      return result;
+    } catch (err) {
+      recordLatency(start, agentId, resolvedActionId, failed);
+      throw err;
+    }
+  };
+}
+function wrapAsyncToRecordLatency(fn, agentId, actionId) {
+  const resolvedActionId = actionId ?? fn.name;
+  return async function(...args) {
+    const start = performance.now();
+    let failed = true;
+    try {
+      const result = await fn.apply(this, args);
+      failed = false;
+      recordLatency(start, agentId, resolvedActionId, failed);
+      return result;
+    } catch (err) {
+      recordLatency(start, agentId, resolvedActionId, failed);
+      throw err;
+    }
+  };
+}
+function wrapToRecordLatency(fn, agentId, actionId) {
+  const resolvedActionId = actionId ?? fn.name;
+  return function(...args) {
+    const start = performance.now();
+    let failed = true;
+    try {
+      const result = fn.apply(this, args);
+      if (isPromise(result)) {
+        return result.then((res) => {
+          failed = false;
+          recordLatency(start, agentId, resolvedActionId, failed);
+          return res;
+        }).catch((err) => {
+          recordLatency(start, agentId, resolvedActionId, failed);
+          throw err;
+        });
+      }
+      failed = false;
+      recordLatency(start, agentId, resolvedActionId, failed);
+      return result;
+    } catch (err) {
+      recordLatency(start, agentId, resolvedActionId, failed);
+      throw err;
+    }
+  };
+}
+
+// src/config.ts
+var baseApiUrl;
+function setPrimeOrbitApiUrl(url) {
+  baseApiUrl = url;
+}
+function getPrimeOrbitApiUrl() {
+  if (!baseApiUrl) {
+    throw new Error(
+      `PrimeOrbit API URL is not set. Please call 'setPrimeOrbitApiUrl(<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) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`recordData failed: ${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) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`Failed to record thumbs feedback: ${message}`);
+  }
+}
+
+// src/event_queue.ts
+var EventQueue = class {
+  queue = [];
+  batchSize;
+  flushIntervalMs;
+  maxConcurrentRequests;
+  maxRetries;
+  retryBaseDelayMs;
+  maxQueueSize;
+  onEventDropped;
+  onBatchFailed;
+  onBatchSuccess;
+  flushTimer = null;
+  activeBatches = [];
+  isShuttingDown = false;
+  isFlushing = false;
+  endpoint;
+  headers;
+  sendBatch;
+  constructor(endpoint, headers, options = {}) {
+    this.endpoint = endpoint;
+    this.headers = headers;
+    this.batchSize = options.batchSize ?? 100;
+    this.flushIntervalMs = options.flushIntervalMs ?? 5e3;
+    this.maxConcurrentRequests = options.maxConcurrentRequests ?? 5;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 1e3;
+    this.maxQueueSize = options.maxQueueSize ?? 1e5;
+    this.onEventDropped = options.onEventDropped;
+    this.onBatchFailed = options.onBatchFailed;
+    this.onBatchSuccess = options.onBatchSuccess;
+    this.sendBatch = this.createBatchSender();
+    this.startFlushTimer();
+  }
+  /**
+   * Add an event to the queue. Events are batched and sent automatically.
+   */
+  enqueue(payload) {
+    if (this.isShuttingDown) {
+      logger.warn("Cannot enqueue events after shutdown has started");
+      return false;
+    }
+    if (this.queue.length >= this.maxQueueSize) {
+      const droppedEvent = {
+        payload,
+        timestamp: Date.now(),
+        retryCount: 0
+      };
+      this.onEventDropped?.(droppedEvent, "Queue is full");
+      logger.warn(
+        `Event dropped: queue is full (max ${this.maxQueueSize} events)`
+      );
+      return false;
+    }
+    const event = {
+      payload,
+      timestamp: Date.now(),
+      retryCount: 0
+    };
+    this.queue.push(event);
+    if (this.queue.length >= this.batchSize) {
+      void this.flush();
+    }
+    return true;
+  }
+  /**
+   * Flush all pending events. Call this before your application exits.
+   */
+  async flush() {
+    if (this.isFlushing) {
+      await Promise.all(this.activeBatches.map((b) => b.promise));
+      return;
+    }
+    this.isFlushing = true;
+    try {
+      while (this.queue.length > 0) {
+        while (this.activeBatches.length >= this.maxConcurrentRequests) {
+          await Promise.race(this.activeBatches.map((b) => b.promise));
+          this.cleanupCompletedBatches();
+        }
+        const batch = this.queue.splice(0, this.batchSize);
+        if (batch.length > 0) {
+          const batchPromise = this.processBatch(batch);
+          const pendingBatch = {
+            events: batch,
+            promise: batchPromise
+          };
+          this.activeBatches.push(pendingBatch);
+        }
+      }
+      await Promise.all(this.activeBatches.map((b) => b.promise));
+      this.cleanupCompletedBatches();
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  /**
+   * Shutdown the queue gracefully. Flushes all pending events and stops the timer.
+   */
+  async shutdown() {
+    this.isShuttingDown = true;
+    this.stopFlushTimer();
+    await this.flush();
+  }
+  /**
+   * Get current queue statistics.
+   */
+  getStats() {
+    return {
+      queuedEvents: this.queue.length,
+      activeBatches: this.activeBatches.length,
+      isShuttingDown: this.isShuttingDown
+    };
+  }
+  startFlushTimer() {
+    if (this.flushTimer) return;
+    this.flushTimer = setInterval(() => {
+      if (this.queue.length > 0 && !this.isFlushing) {
+        void this.flush();
+      }
+    }, this.flushIntervalMs);
+    if (this.flushTimer.unref) {
+      this.flushTimer.unref();
+    }
+  }
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  cleanupCompletedBatches() {
+    this.activeBatches = [];
+  }
+  async processBatch(events) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await this.sendBatch(events);
+        this.onBatchSuccess?.(events, response);
+        return;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < this.maxRetries) {
+          const delay = this.retryBaseDelayMs * Math.pow(2, attempt) + Math.random() * 1e3;
+          await this.sleep(delay);
+        }
+      }
+    }
+    if (lastError) {
+      this.onBatchFailed?.(events, lastError);
+      logger.error(
+        `Batch of ${events.length} events failed after ${this.maxRetries + 1} attempts: ${lastError.message}`
+      );
+    }
+  }
+  createBatchSender() {
+    return async (events) => {
+      const payloads = events.map((e) => e.payload);
+      const response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({ events: payloads })
+      });
+      const text = await response.text();
+      let responseBody;
+      try {
+        responseBody = text ? JSON.parse(text) : null;
+      } catch {
+        responseBody = text;
+      }
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status} ${response.statusText}: ${text}`);
+      }
+      return responseBody;
+    };
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/user_metrics/record_user_event.ts
+import * as dotenv from "dotenv";
+dotenv.config();
+var PrimeOrbitClient = class {
+  apiKey;
+  baseUrl;
+  baseProperties = {};
+  verbose = false;
+  enableBatching = false;
+  eventQueue = null;
+  constructor(apiKeyOrOptions, endpoint) {
+    let apiKey;
+    let endpointUrl;
+    let options = {};
+    if (typeof apiKeyOrOptions === "object" && apiKeyOrOptions !== null) {
+      options = apiKeyOrOptions;
+      apiKey = options.apiKey;
+      endpointUrl = options.endpoint;
+      this.verbose = options.verbose ?? false;
+      this.enableBatching = options.enableBatching ?? false;
+    } else {
+      apiKey = apiKeyOrOptions;
+      endpointUrl = endpoint;
+    }
+    const envApiKey = process.env["PRIMEORBIT_API_KEY"];
+    const envEndpoint = process.env["PRIMEORBIT_ENDPOINT"];
+    if (apiKey) {
+      this.apiKey = apiKey;
+    } else if (envApiKey) {
+      this.apiKey = envApiKey;
+    } else {
+      throw new Error(
+        "API key not provided. Set the 'apiKey' parameter or the 'PRIMEORBIT_API_KEY' environment variable."
+      );
+    }
+    if (endpointUrl) {
+      this.baseUrl = endpointUrl;
+    } else if (envEndpoint) {
+      this.baseUrl = envEndpoint;
+    } else {
+      this.baseUrl = "https://sdk-dev.primeorbit.ai";
+    }
+    this.baseProperties = {};
+    if (this.enableBatching) {
+      this.initializeEventQueue(options.queueOptions);
+    }
+  }
+  initializeEventQueue(queueOptions) {
+    const batchEndpoint = `${this.baseUrl}${routes["raw-events-batch"]}`;
+    this.eventQueue = new EventQueue(batchEndpoint, this._headers(), {
+      batchSize: 100,
+      flushIntervalMs: 5e3,
+      maxConcurrentRequests: 5,
+      maxRetries: 3,
+      retryBaseDelayMs: 1e3,
+      maxQueueSize: 1e5,
+      ...queueOptions
+    });
+  }
+  add_properties(props) {
+    this.baseProperties = {
+      ...this.baseProperties,
+      ...props
+    };
+  }
+  _headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+  }
+  /**
+   * Enable or disable event batching at runtime.
+   * When enabled, events are queued and sent in batches.
+   * When disabled, events are sent immediately (original behavior).
+   *
+   * @param enable - Whether to enable batching
+   * @param queueOptions - Optional queue configuration (only used when enabling)
+   */
+  setBatching(enable, queueOptions) {
+    if (enable && !this.eventQueue) {
+      this.enableBatching = true;
+      this.initializeEventQueue(queueOptions);
+    } else if (!enable && this.eventQueue) {
+      void this.eventQueue.flush().then(() => {
+        this.enableBatching = false;
+        this.eventQueue = null;
+      });
+    }
+  }
+  /**
+   * Flush all queued events immediately.
+   * Call this before your application exits to ensure all events are sent.
+   * Only applicable when batching is enabled.
+   */
+  async flush() {
+    if (this.eventQueue) {
+      await this.eventQueue.flush();
+    }
+  }
+  /**
+   * Shutdown the client gracefully.
+   * Flushes all pending events and releases resources.
+   * Call this when your application is shutting down.
+   */
+  async shutdown() {
+    if (this.eventQueue) {
+      await this.eventQueue.shutdown();
+      this.eventQueue = null;
+    }
+  }
+  /**
+   * Get queue statistics.
+   * Only applicable when batching is enabled.
+   */
+  getQueueStats() {
+    if (this.eventQueue) {
+      return this.eventQueue.getStats();
+    }
+    return null;
+  }
+  /**
+   * Records any agent interaction event such as user_message, agent_response, or user_feedback.
+   *
+   * @param eventType - Type of event. Can be:
+   *   - 'user_message' – when the user sends a message
+   *   - '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 message, 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
+   *
+   * @returns Promise that resolves when the event is queued (batching) or sent (non-batching).
+   *          When batching is enabled, returns true if queued successfully, false if dropped.
+   */
+  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) {
+          logger.warn(
+            `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
+      };
+      if (this.enableBatching && this.eventQueue) {
+        const queued = this.eventQueue.enqueue(payload);
+        return queued;
+      } else {
+        logger.debug("Recording event:", payload);
+        await recordData(
+          `${this.baseUrl}${routes["raw-events"]}`,
+          payload,
+          this._headers()
+        );
+        return void 0;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`recording_event failed: ${message}`);
+      return void 0;
+    }
+  }
+};
+export {
+  EventQueue,
+  PrimeOrbitClient,
+  getLogLevel,
+  getPrimeOrbitApiUrl,
+  logger,
+  record_star_rating,
+  record_thumbs_feedback,
+  setLogLevel,
+  setPrimeOrbitApiUrl,
+  wrapAsyncToRecordLatency,
+  wrapSyncToRecordLatency,
+  wrapToRecordLatency
+};