@sentrial/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,595 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  EventType: () => EventType,
+  Interaction: () => Interaction,
+  NetworkError: () => NetworkError,
+  SentrialClient: () => SentrialClient,
+  SentrialError: () => SentrialError,
+  ValidationError: () => ValidationError,
+  begin: () => begin,
+  calculateAnthropicCost: () => calculateAnthropicCost,
+  calculateGoogleCost: () => calculateGoogleCost,
+  calculateOpenAICost: () => calculateOpenAICost,
+  configure: () => configure,
+  sentrial: () => sentrial
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var SentrialError = class _SentrialError extends Error {
+  /** HTTP status code (if applicable) */
+  status;
+  /** Error code from the API */
+  code;
+  /** Additional error details */
+  details;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "SentrialError";
+    this.status = options?.status;
+    this.code = options?.code;
+    this.details = options?.details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _SentrialError);
+    }
+  }
+  /**
+   * Check if the error is a rate limit error
+   */
+  isRateLimitError() {
+    return this.status === 429;
+  }
+  /**
+   * Check if the error is an authentication error
+   */
+  isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+  /**
+   * Check if the error is a network/connection error
+   */
+  isNetworkError() {
+    return this.code === "NETWORK_ERROR" || this.code === "ECONNREFUSED";
+  }
+  /**
+   * Convert to a plain object for logging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      details: this.details,
+      stack: this.stack
+    };
+  }
+};
+var ApiError = class extends SentrialError {
+  constructor(message, status, code, details) {
+    super(message, { status, code, details });
+    this.name = "ApiError";
+  }
+};
+var NetworkError = class extends SentrialError {
+  constructor(message, cause) {
+    super(message, { code: "NETWORK_ERROR", cause });
+    this.name = "NetworkError";
+  }
+};
+var ValidationError = class extends SentrialError {
+  constructor(message, details) {
+    super(message, { code: "VALIDATION_ERROR", details });
+    this.name = "ValidationError";
+  }
+};
+
+// src/cost.ts
+var OPENAI_PRICING = {
+  "gpt-5.2": { input: 5, output: 15 },
+  "gpt-5": { input: 4, output: 12 },
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+  "o3": { input: 10, output: 40 },
+  "o3-mini": { input: 3, output: 12 },
+  "o1-preview": { input: 15, output: 60 },
+  "o1-mini": { input: 3, output: 12 }
+};
+var ANTHROPIC_PRICING = {
+  "claude-4.5-opus": { input: 20, output: 100 },
+  "claude-4.5-sonnet": { input: 4, output: 20 },
+  "claude-4-opus": { input: 18, output: 90 },
+  "claude-4-sonnet": { input: 3.5, output: 17.5 },
+  "claude-3-5-sonnet": { input: 3, output: 15 },
+  "claude-3-opus": { input: 15, output: 75 },
+  "claude-3-sonnet": { input: 3, output: 15 },
+  "claude-3-haiku": { input: 0.25, output: 1.25 }
+};
+var GOOGLE_PRICING = {
+  // Gemini 3 - Preview (Jan 2026)
+  "gemini-3-pro": { input: 2, output: 12 },
+  "gemini-3-flash": { input: 0.5, output: 3 },
+  // Gemini 2.5
+  "gemini-2.5-pro": { input: 1.25, output: 5 },
+  "gemini-2.5-flash": { input: 0.15, output: 0.6 },
+  // Gemini 2.0
+  "gemini-2.0-flash": { input: 0.1, output: 0.4 },
+  "gemini-2.0-flash-lite": { input: 0.075, output: 0.3 },
+  // Gemini 1.5
+  "gemini-1.5-pro": { input: 1.25, output: 5 },
+  "gemini-1.5-flash": { input: 0.075, output: 0.3 },
+  // Gemini 1.0
+  "gemini-1.0-pro": { input: 0.5, output: 1.5 }
+};
+function findModelKey(model, pricing) {
+  for (const key of Object.keys(pricing)) {
+    if (model.startsWith(key)) {
+      return key;
+    }
+  }
+  return null;
+}
+function calculateCost(inputTokens, outputTokens, rates) {
+  const inputCost = inputTokens / 1e6 * rates.input;
+  const outputCost = outputTokens / 1e6 * rates.output;
+  return inputCost + outputCost;
+}
+function calculateOpenAICost(params) {
+  const { model, inputTokens, outputTokens } = params;
+  const modelKey = findModelKey(model, OPENAI_PRICING) ?? "gpt-4";
+  return calculateCost(inputTokens, outputTokens, OPENAI_PRICING[modelKey]);
+}
+function calculateAnthropicCost(params) {
+  const { model, inputTokens, outputTokens } = params;
+  const modelKey = findModelKey(model, ANTHROPIC_PRICING) ?? "claude-3-sonnet";
+  return calculateCost(inputTokens, outputTokens, ANTHROPIC_PRICING[modelKey]);
+}
+function calculateGoogleCost(params) {
+  const { model, inputTokens, outputTokens } = params;
+  const modelKey = findModelKey(model, GOOGLE_PRICING) ?? "gemini-2.0-flash";
+  return calculateCost(inputTokens, outputTokens, GOOGLE_PRICING[modelKey]);
+}
+
+// src/types.ts
+var EventType = /* @__PURE__ */ ((EventType2) => {
+  EventType2["TOOL_CALL"] = "tool_call";
+  EventType2["LLM_DECISION"] = "llm_decision";
+  EventType2["STATE_CHANGE"] = "state_change";
+  EventType2["ERROR"] = "error";
+  return EventType2;
+})(EventType || {});
+
+// src/client.ts
+var DEFAULT_API_URL = "https://api.sentrial.com";
+var SentrialClient = class {
+  apiUrl;
+  apiKey;
+  failSilently;
+  currentState = {};
+  constructor(config = {}) {
+    this.apiUrl = (config.apiUrl ?? (typeof process !== "undefined" ? process.env?.SENTRIAL_API_URL : void 0) ?? DEFAULT_API_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey ?? (typeof process !== "undefined" ? process.env?.SENTRIAL_API_KEY : void 0);
+    this.failSilently = config.failSilently ?? true;
+  }
+  /**
+   * Make an HTTP request with graceful error handling
+   */
+  async safeRequest(method, url, body) {
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        let errorData = {};
+        try {
+          errorData = JSON.parse(errorBody);
+        } catch {
+        }
+        const error = new ApiError(
+          errorData.error?.message || `HTTP ${response.status}: ${response.statusText}`,
+          response.status,
+          errorData.error?.code
+        );
+        if (this.failSilently) {
+          console.warn(`Sentrial: Request failed (${method} ${url}):`, error.message);
+          return null;
+        }
+        throw error;
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof SentrialError) {
+        throw error;
+      }
+      const networkError = new NetworkError(
+        error instanceof Error ? error.message : "Unknown network error",
+        error instanceof Error ? error : void 0
+      );
+      if (this.failSilently) {
+        console.warn(`Sentrial: Request failed (${method} ${url}):`, networkError.message);
+        return null;
+      }
+      throw networkError;
+    }
+  }
+  /**
+   * Create a new session
+   *
+   * @param params - Session creation parameters
+   * @returns Session ID, or null if the request failed and failSilently is true
+   */
+  async createSession(params) {
+    this.currentState = {};
+    const payload = {
+      name: params.name,
+      agentName: params.agentName,
+      userId: params.userId,
+      metadata: params.metadata
+    };
+    const response = await this.safeRequest(
+      "POST",
+      `${this.apiUrl}/api/sdk/sessions`,
+      payload
+    );
+    return response?.id ?? null;
+  }
+  /**
+   * Track a tool call event
+   *
+   * @param params - Tool call parameters
+   * @returns Event data
+   */
+  async trackToolCall(params) {
+    const stateBefore = { ...this.currentState };
+    this.currentState[`${params.toolName}_result`] = params.toolOutput;
+    const payload = {
+      sessionId: params.sessionId,
+      eventType: "tool_call",
+      toolName: params.toolName,
+      toolInput: params.toolInput,
+      toolOutput: params.toolOutput,
+      reasoning: params.reasoning,
+      stateBefore,
+      stateAfter: { ...this.currentState },
+      estimatedCost: params.estimatedCost ?? 0
+    };
+    if (params.toolError !== void 0) payload.toolError = params.toolError;
+    if (params.tokenCount !== void 0) payload.tokenCount = params.tokenCount;
+    if (params.traceId !== void 0) payload.traceId = params.traceId;
+    if (params.spanId !== void 0) payload.spanId = params.spanId;
+    if (params.metadata !== void 0) payload.metadata = params.metadata;
+    return this.safeRequest("POST", `${this.apiUrl}/api/sdk/events`, payload);
+  }
+  /**
+   * Track an LLM decision event
+   *
+   * @param params - Decision parameters
+   * @returns Event data
+   */
+  async trackDecision(params) {
+    const stateBefore = { ...this.currentState };
+    const payload = {
+      sessionId: params.sessionId,
+      eventType: "llm_decision",
+      reasoning: params.reasoning,
+      alternativesConsidered: params.alternatives,
+      confidence: params.confidence,
+      stateBefore,
+      stateAfter: { ...this.currentState },
+      estimatedCost: params.estimatedCost ?? 0
+    };
+    if (params.tokenCount !== void 0) payload.tokenCount = params.tokenCount;
+    if (params.traceId !== void 0) payload.traceId = params.traceId;
+    if (params.spanId !== void 0) payload.spanId = params.spanId;
+    if (params.metadata !== void 0) payload.metadata = params.metadata;
+    return this.safeRequest("POST", `${this.apiUrl}/api/sdk/events`, payload);
+  }
+  /**
+   * Track an error event
+   *
+   * @param params - Error parameters
+   * @returns Event data
+   */
+  async trackError(params) {
+    const stateBefore = { ...this.currentState };
+    const toolError = {
+      message: params.errorMessage
+    };
+    if (params.errorType) toolError.type = params.errorType;
+    if (params.stackTrace) toolError.stack_trace = params.stackTrace;
+    const payload = {
+      sessionId: params.sessionId,
+      eventType: "error",
+      toolError,
+      stateBefore,
+      stateAfter: { ...this.currentState }
+    };
+    if (params.toolName !== void 0) payload.toolName = params.toolName;
+    if (params.traceId !== void 0) payload.traceId = params.traceId;
+    if (params.spanId !== void 0) payload.spanId = params.spanId;
+    if (params.metadata !== void 0) payload.metadata = params.metadata;
+    return this.safeRequest("POST", `${this.apiUrl}/api/sdk/events`, payload);
+  }
+  /**
+   * Update the current state
+   *
+   * @param key - State key
+   * @param value - State value
+   */
+  updateState(key, value) {
+    this.currentState[key] = value;
+  }
+  /**
+   * Complete a session with performance metrics
+   *
+   * This is the recommended way to close sessions for performance monitoring.
+   *
+   * @param params - Session completion parameters
+   * @returns Updated session data
+   *
+   * @example
+   * ```ts
+   * await client.completeSession({
+   *   sessionId,
+   *   success: true,
+   *   estimatedCost: 0.023,
+   *   promptTokens: 1500,
+   *   completionTokens: 500,
+   *   totalTokens: 2000,
+   *   userInput: "What's the weather in San Francisco?",
+   *   assistantOutput: "The weather in San Francisco is 65°F and sunny.",
+   *   customMetrics: {
+   *     customer_satisfaction: 4.5,
+   *     order_value: 129.99,
+   *   },
+   * });
+   * ```
+   */
+  async completeSession(params) {
+    const payload = {
+      status: params.success !== false ? "completed" : "failed",
+      success: params.success ?? true
+    };
+    if (params.failureReason !== void 0) payload.failureReason = params.failureReason;
+    if (params.estimatedCost !== void 0) payload.estimatedCost = params.estimatedCost;
+    if (params.customMetrics !== void 0) payload.customMetrics = params.customMetrics;
+    if (params.durationMs !== void 0) payload.durationMs = params.durationMs;
+    if (params.promptTokens !== void 0) payload.promptTokens = params.promptTokens;
+    if (params.completionTokens !== void 0) payload.completionTokens = params.completionTokens;
+    if (params.totalTokens !== void 0) payload.totalTokens = params.totalTokens;
+    if (params.userInput !== void 0) payload.userInput = params.userInput;
+    if (params.assistantOutput !== void 0) payload.assistantOutput = params.assistantOutput;
+    return this.safeRequest(
+      "PATCH",
+      `${this.apiUrl}/api/sdk/sessions/${params.sessionId}`,
+      payload
+    );
+  }
+  /**
+   * Begin tracking an interaction (simplified API)
+   *
+   * @param params - Interaction parameters
+   * @returns Interaction object with finish() method
+   *
+   * @example
+   * ```ts
+   * const interaction = await client.begin({
+   *   userId: 'user_123',
+   *   event: 'chat_message',
+   *   input: message,
+   *   convoId: 'convo_456',
+   * });
+   *
+   * // ... do your agent work ...
+   *
+   * await interaction.finish({ output: responseText });
+   * ```
+   */
+  async begin(params) {
+    const eventId = params.eventId ?? crypto.randomUUID();
+    const fullMetadata = params.metadata ? { ...params.metadata } : {};
+    if (params.input) fullMetadata.input = params.input;
+    if (params.convoId) fullMetadata.convo_id = params.convoId;
+    fullMetadata.event_id = eventId;
+    const sessionId = await this.createSession({
+      name: `${params.event}:${eventId.slice(0, 8)}`,
+      agentName: params.event,
+      userId: params.userId,
+      metadata: fullMetadata
+    });
+    if (params.input) {
+      this.currentState.input = params.input;
+    }
+    return new Interaction({
+      client: this,
+      sessionId,
+      eventId,
+      userId: params.userId,
+      event: params.event
+    });
+  }
+  // Cost calculation static methods for convenience
+  static calculateOpenAICost = calculateOpenAICost;
+  static calculateAnthropicCost = calculateAnthropicCost;
+  static calculateGoogleCost = calculateGoogleCost;
+};
+var Interaction = class {
+  client;
+  sessionId;
+  /** Event ID for this interaction */
+  eventId;
+  /** User ID for this interaction */
+  userId;
+  /** Event name for this interaction */
+  event;
+  finished = false;
+  success = true;
+  failureReason;
+  output;
+  degraded;
+  constructor(config) {
+    this.client = config.client;
+    this.sessionId = config.sessionId;
+    this.eventId = config.eventId;
+    this.userId = config.userId;
+    this.event = config.event;
+    this.degraded = config.sessionId === null;
+  }
+  /**
+   * Set the output for this interaction
+   *
+   * This will be used when finish() is called.
+   * Useful when you want to set the output but call finish() later.
+   *
+   * @param output - The output/response text
+   */
+  setOutput(output) {
+    this.output = output;
+  }
+  /**
+   * Finish the interaction and record metrics
+   *
+   * @param params - Finish parameters
+   * @returns Updated session data, or null if degraded/already finished
+   *
+   * @example
+   * ```ts
+   * await interaction.finish({
+   *   output: "Here's the answer to your question...",
+   *   success: true,
+   *   customMetrics: { satisfaction: 4.5 },
+   * });
+   * ```
+   */
+  async finish(params = {}) {
+    if (this.finished) return null;
+    if (this.degraded) {
+      this.finished = true;
+      return null;
+    }
+    this.finished = true;
+    const finalOutput = params.output ?? this.output;
+    return this.client.completeSession({
+      sessionId: this.sessionId,
+      success: params.success ?? this.success,
+      failureReason: params.failureReason ?? this.failureReason,
+      estimatedCost: params.estimatedCost,
+      customMetrics: params.customMetrics,
+      promptTokens: params.promptTokens,
+      completionTokens: params.completionTokens,
+      totalTokens: params.totalTokens,
+      assistantOutput: finalOutput
+    });
+  }
+  /**
+   * Track a tool call within this interaction
+   */
+  async trackToolCall(params) {
+    if (this.degraded) return null;
+    return this.client.trackToolCall({
+      ...params,
+      sessionId: this.sessionId
+    });
+  }
+  /**
+   * Track an LLM decision within this interaction
+   */
+  async trackDecision(params) {
+    if (this.degraded) return null;
+    return this.client.trackDecision({
+      ...params,
+      sessionId: this.sessionId
+    });
+  }
+  /**
+   * Track an error within this interaction
+   */
+  async trackError(params) {
+    this.success = false;
+    this.failureReason = params.errorMessage;
+    if (this.degraded) return null;
+    return this.client.trackError({
+      ...params,
+      sessionId: this.sessionId
+    });
+  }
+  /**
+   * Get the session ID (null if session creation failed)
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Check if the interaction is in a degraded state (session creation failed)
+   */
+  isDegraded() {
+    return this.degraded;
+  }
+};
+var defaultClient = null;
+function getClient() {
+  if (!defaultClient) {
+    defaultClient = new SentrialClient();
+  }
+  return defaultClient;
+}
+function configure(config) {
+  defaultClient = new SentrialClient(config);
+}
+function begin(params) {
+  return getClient().begin(params);
+}
+var sentrial = {
+  configure,
+  begin
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  EventType,
+  Interaction,
+  NetworkError,
+  SentrialClient,
+  SentrialError,
+  ValidationError,
+  begin,
+  calculateAnthropicCost,
+  calculateGoogleCost,
+  calculateOpenAICost,
+  configure,
+  sentrial
+});
+//# sourceMappingURL=index.cjs.map