@sentrial/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,642 @@
+/**
+ * Type definitions for the Sentrial TypeScript SDK
+ */
+/**
+ * Event types that can be tracked in a session
+ */
+declare enum EventType {
+    TOOL_CALL = "tool_call",
+    LLM_DECISION = "llm_decision",
+    STATE_CHANGE = "state_change",
+    ERROR = "error"
+}
+/**
+ * Session status values
+ */
+type SessionStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Configuration options for SentrialClient
+ */
+interface SentrialClientConfig {
+    /** API key for authentication (defaults to SENTRIAL_API_KEY env var) */
+    apiKey?: string;
+    /** URL of the Sentrial API server (defaults to SENTRIAL_API_URL env var or production) */
+    apiUrl?: string;
+    /**
+     * If true (default), SDK errors are logged but won't crash your app.
+     * Set to false during development to see full errors.
+     */
+    failSilently?: boolean;
+}
+/**
+ * Parameters for creating a new session
+ */
+interface CreateSessionParams {
+    /** Name of the session */
+    name: string;
+    /** Identifier for the agent type (used for grouping) */
+    agentName: string;
+    /** External user ID (for grouping sessions by end-user) */
+    userId: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for completing a session
+ */
+interface CompleteSessionParams {
+    /** Session ID */
+    sessionId: string;
+    /** Whether the session successfully completed its goal (default: true) */
+    success?: boolean;
+    /** If success=false, why did it fail? */
+    failureReason?: string;
+    /** Total estimated cost in USD for this session */
+    estimatedCost?: number;
+    /** Custom metrics (e.g., { customer_satisfaction: 4.5, steps_taken: 3 }) */
+    customMetrics?: Record<string, number>;
+    /** Duration in milliseconds (auto-calculated if not provided) */
+    durationMs?: number;
+    /** Number of prompt/input tokens used */
+    promptTokens?: number;
+    /** Number of completion/output tokens used */
+    completionTokens?: number;
+    /** Total tokens used (prompt + completion) */
+    totalTokens?: number;
+    /** The user's original query/input for this session */
+    userInput?: string;
+    /** The final assistant response for this session */
+    assistantOutput?: string;
+}
+/**
+ * Session data returned from the API
+ */
+interface Session {
+    id: string;
+    agentId?: string;
+    name: string;
+    agentName: string;
+    userId: string;
+    status: SessionStatus;
+    totalEvents: number;
+    userInput?: string;
+    assistantOutput?: string;
+    success?: boolean;
+    failureReason?: string;
+    estimatedCost?: number;
+    customMetrics?: Record<string, unknown>;
+    score?: number;
+    metricScores?: Record<string, unknown>;
+    metricReasonings?: Record<string, string>;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+}
+/**
+ * Parameters for tracking a tool call event
+ */
+interface TrackToolCallParams {
+    /** Session ID */
+    sessionId: string;
+    /** Name of the tool */
+    toolName: string;
+    /** Tool input data */
+    toolInput: Record<string, unknown>;
+    /** Tool output data */
+    toolOutput: Record<string, unknown>;
+    /** Optional reasoning for why this tool was called */
+    reasoning?: string;
+    /** Estimated cost in USD for this tool call */
+    estimatedCost?: number;
+    /** Error details if the tool failed */
+    toolError?: Record<string, unknown>;
+    /** Number of tokens used by this tool call (for LLM-based tools) */
+    tokenCount?: number;
+    /** OpenTelemetry trace ID for distributed tracing */
+    traceId?: string;
+    /** OpenTelemetry span ID for distributed tracing */
+    spanId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for tracking an LLM decision event
+ */
+interface TrackDecisionParams {
+    /** Session ID */
+    sessionId: string;
+    /** Decision reasoning */
+    reasoning: string;
+    /** Alternative options considered */
+    alternatives?: string[];
+    /** Confidence score (0.0 to 1.0) */
+    confidence?: number;
+    /** Estimated cost in USD for this decision */
+    estimatedCost?: number;
+    /** Number of tokens used */
+    tokenCount?: number;
+    /** OpenTelemetry trace ID for distributed tracing */
+    traceId?: string;
+    /** OpenTelemetry span ID for distributed tracing */
+    spanId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for tracking an error event
+ */
+interface TrackErrorParams {
+    /** Session ID */
+    sessionId: string;
+    /** Error message */
+    errorMessage: string;
+    /** Type of error (e.g., "ValueError", "APIError") */
+    errorType?: string;
+    /** Name of the tool that caused the error (if applicable) */
+    toolName?: string;
+    /** Stack trace for debugging */
+    stackTrace?: string;
+    /** OpenTelemetry trace ID for distributed tracing */
+    traceId?: string;
+    /** OpenTelemetry span ID for distributed tracing */
+    spanId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event data returned from the API
+ */
+interface Event {
+    id: string;
+    sessionId: string;
+    eventType: EventType;
+    timestamp: Date;
+    sequenceNumber: number;
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    toolOutput?: Record<string, unknown>;
+    toolError?: Record<string, unknown>;
+    reasoning?: string;
+    alternativesConsidered?: string[];
+    confidence?: number;
+    stateBefore?: Record<string, unknown>;
+    stateAfter?: Record<string, unknown>;
+    stateDiff?: Record<string, unknown>;
+    estimatedCost?: number;
+    tokenCount?: number;
+    metadata?: Record<string, unknown>;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Parameters for beginning an interaction
+ */
+interface BeginParams {
+    /** External user ID for grouping sessions */
+    userId: string;
+    /** Event type/name (e.g., "chat_message", "search_query") */
+    event: string;
+    /** Optional input data for the interaction */
+    input?: string;
+    /** Optional custom event ID (auto-generated UUID if not provided) */
+    eventId?: string;
+    /** Optional conversation ID to group related interactions */
+    convoId?: string;
+    /** Optional additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for finishing an interaction
+ */
+interface FinishParams {
+    /** Output/response from the interaction */
+    output?: string;
+    /** Whether the interaction succeeded (default: true) */
+    success?: boolean;
+    /** Reason for failure if success=false */
+    failureReason?: string;
+    /** Total estimated cost in USD */
+    estimatedCost?: number;
+    /** Custom metrics */
+    customMetrics?: Record<string, number>;
+    /** Number of prompt/input tokens used */
+    promptTokens?: number;
+    /** Number of completion/output tokens used */
+    completionTokens?: number;
+    /** Total tokens used */
+    totalTokens?: number;
+}
+/**
+ * Parameters for cost calculation
+ */
+interface CostParams {
+    /** Model name (e.g., "gpt-4", "claude-3-sonnet") */
+    model: string;
+    /** Number of input tokens */
+    inputTokens: number;
+    /** Number of output tokens */
+    outputTokens: number;
+}
+/**
+ * Standard API response wrapper
+ */
+interface ApiResponse<T> {
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+
+/**
+ * Cost calculation utilities for various LLM providers
+ */
+
+/**
+ * Calculate cost for OpenAI API calls
+ *
+ * @param params - Cost calculation parameters
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```ts
+ * const cost = calculateOpenAICost({
+ *   model: 'gpt-4o',
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ * });
+ * console.log(`Cost: $${cost.toFixed(4)}`);
+ * ```
+ */
+declare function calculateOpenAICost(params: CostParams): number;
+/**
+ * Calculate cost for Anthropic API calls
+ *
+ * @param params - Cost calculation parameters
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```ts
+ * const cost = calculateAnthropicCost({
+ *   model: 'claude-3-5-sonnet',
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ * });
+ * console.log(`Cost: $${cost.toFixed(4)}`);
+ * ```
+ */
+declare function calculateAnthropicCost(params: CostParams): number;
+/**
+ * Calculate cost for Google/Gemini API calls
+ *
+ * @param params - Cost calculation parameters
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```ts
+ * const cost = calculateGoogleCost({
+ *   model: 'gemini-2.0-flash',
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ * });
+ * console.log(`Cost: $${cost.toFixed(4)}`);
+ * ```
+ */
+declare function calculateGoogleCost(params: CostParams): number;
+
+/**
+ * Sentrial Client - Main SDK interface
+ *
+ * Captures agent sessions, tool calls, and metrics. This data powers:
+ * - Signal detection (auto-detect patterns/anomalies)
+ * - Root cause analysis (understand WHY agents fail)
+ * - Code fixer (AI-suggested fixes with GitHub PRs)
+ */
+
+/**
+ * Sentrial Client for agent observability.
+ *
+ * Captures the data needed for automated root cause analysis and fix suggestions.
+ *
+ * @example
+ * ```ts
+ * const client = new SentrialClient({
+ *   apiKey: 'sentrial_live_xxx',
+ *   apiUrl: 'https://api.sentrial.com',
+ * });
+ *
+ * // Create a session for an agent run
+ * const sessionId = await client.createSession({
+ *   name: 'Support Request #123',
+ *   agentName: 'support-agent',
+ *   userId: 'user_123',
+ * });
+ *
+ * // Track events
+ * await client.trackToolCall({
+ *   sessionId,
+ *   toolName: 'search_kb',
+ *   toolInput: { query: 'password reset' },
+ *   toolOutput: { articles: ['KB-001'] },
+ * });
+ *
+ * // Complete session with metrics
+ * await client.completeSession({
+ *   sessionId,
+ *   success: true,
+ *   customMetrics: { customer_satisfaction: 90 },
+ * });
+ * ```
+ *
+ * @remarks
+ * By default, the SDK fails silently (failSilently=true) to ensure
+ * monitoring never crashes your application. Set failSilently=false
+ * during development to see errors.
+ */
+declare class SentrialClient {
+    private readonly apiUrl;
+    private readonly apiKey?;
+    private readonly failSilently;
+    private currentState;
+    constructor(config?: SentrialClientConfig);
+    /**
+     * Make an HTTP request with graceful error handling
+     */
+    private safeRequest;
+    /**
+     * Create a new session
+     *
+     * @param params - Session creation parameters
+     * @returns Session ID, or null if the request failed and failSilently is true
+     */
+    createSession(params: CreateSessionParams): Promise<string | null>;
+    /**
+     * Track a tool call event
+     *
+     * @param params - Tool call parameters
+     * @returns Event data
+     */
+    trackToolCall(params: TrackToolCallParams): Promise<Event | null>;
+    /**
+     * Track an LLM decision event
+     *
+     * @param params - Decision parameters
+     * @returns Event data
+     */
+    trackDecision(params: TrackDecisionParams): Promise<Event | null>;
+    /**
+     * Track an error event
+     *
+     * @param params - Error parameters
+     * @returns Event data
+     */
+    trackError(params: TrackErrorParams): Promise<Event | null>;
+    /**
+     * Update the current state
+     *
+     * @param key - State key
+     * @param value - State value
+     */
+    updateState(key: string, value: unknown): void;
+    /**
+     * 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,
+     *   },
+     * });
+     * ```
+     */
+    completeSession(params: CompleteSessionParams): Promise<Session | null>;
+    /**
+     * 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 });
+     * ```
+     */
+    begin(params: BeginParams): Promise<Interaction>;
+    static calculateOpenAICost: typeof calculateOpenAICost;
+    static calculateAnthropicCost: typeof calculateAnthropicCost;
+    static calculateGoogleCost: typeof calculateGoogleCost;
+}
+interface InteractionConfig {
+    client: SentrialClient;
+    sessionId: string | null;
+    eventId: string;
+    userId: string;
+    event: string;
+}
+/**
+ * Represents an in-progress interaction that can be finished.
+ *
+ * Created by SentrialClient.begin() - provides a clean begin/finish API pattern.
+ *
+ * @remarks
+ * If session creation failed (sessionId is null), all tracking methods
+ * become no-ops to ensure your application continues running.
+ */
+declare class Interaction {
+    private readonly client;
+    private readonly sessionId;
+    /** Event ID for this interaction */
+    readonly eventId: string;
+    /** User ID for this interaction */
+    readonly userId: string;
+    /** Event name for this interaction */
+    readonly event: string;
+    private finished;
+    private success;
+    private failureReason?;
+    private output?;
+    private readonly degraded;
+    constructor(config: InteractionConfig);
+    /**
+     * 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: string): void;
+    /**
+     * 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 },
+     * });
+     * ```
+     */
+    finish(params?: FinishParams): Promise<Session | null>;
+    /**
+     * Track a tool call within this interaction
+     */
+    trackToolCall(params: Omit<TrackToolCallParams, 'sessionId'>): Promise<Event | null>;
+    /**
+     * Track an LLM decision within this interaction
+     */
+    trackDecision(params: Omit<TrackDecisionParams, 'sessionId'>): Promise<Event | null>;
+    /**
+     * Track an error within this interaction
+     */
+    trackError(params: Omit<TrackErrorParams, 'sessionId'>): Promise<Event | null>;
+    /**
+     * Get the session ID (null if session creation failed)
+     */
+    getSessionId(): string | null;
+    /**
+     * Check if the interaction is in a degraded state (session creation failed)
+     */
+    isDegraded(): boolean;
+}
+/**
+ * Configure the default Sentrial client
+ *
+ * @param config - Client configuration
+ *
+ * @example
+ * ```ts
+ * import { sentrial } from '@sentrial/sdk';
+ *
+ * sentrial.configure({
+ *   apiKey: 'sentrial_live_xxx',
+ *   apiUrl: 'https://api.sentrial.com',
+ * });
+ * ```
+ */
+declare function configure(config: SentrialClientConfig): void;
+/**
+ * Begin tracking an interaction (module-level convenience function)
+ *
+ * This is a shorthand for new SentrialClient().begin(...).
+ * Configure the client first with sentrial.configure() or set SENTRIAL_API_KEY env var.
+ *
+ * @param params - Interaction parameters
+ * @returns Interaction object with finish() method
+ *
+ * @example
+ * ```ts
+ * import { sentrial } from '@sentrial/sdk';
+ *
+ * sentrial.configure({ apiKey: 'sentrial_live_xxx' });
+ *
+ * const interaction = await sentrial.begin({
+ *   userId: 'user_123',
+ *   event: 'chat_message',
+ *   input: message,
+ * });
+ *
+ * // ... do your agent work ...
+ *
+ * await interaction.finish({ output: responseText });
+ * ```
+ */
+declare function begin(params: BeginParams): Promise<Interaction>;
+/**
+ * Simple API namespace for module-level usage
+ */
+declare const sentrial: {
+    configure: typeof configure;
+    begin: typeof begin;
+};
+
+/**
+ * Error classes for the Sentrial SDK
+ */
+/**
+ * Base error class for all Sentrial SDK errors
+ */
+declare class SentrialError extends Error {
+    /** HTTP status code (if applicable) */
+    readonly status?: number;
+    /** Error code from the API */
+    readonly code?: string;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    });
+    /**
+     * Check if the error is a rate limit error
+     */
+    isRateLimitError(): boolean;
+    /**
+     * Check if the error is an authentication error
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if the error is a network/connection error
+     */
+    isNetworkError(): boolean;
+    /**
+     * Convert to a plain object for logging
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when the API returns an error response
+ */
+declare class ApiError extends SentrialError {
+    constructor(message: string, status: number, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * Error thrown when there's a network/connection issue
+ */
+declare class NetworkError extends SentrialError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when validation fails
+ */
+declare class ValidationError extends SentrialError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+export { ApiError, type ApiResponse, type BeginParams, type CompleteSessionParams, type CostParams, type CreateSessionParams, type Event, EventType, type FinishParams, Interaction, NetworkError, SentrialClient, type SentrialClientConfig, SentrialError, type Session, type SessionStatus, type TrackDecisionParams, type TrackErrorParams, type TrackToolCallParams, ValidationError, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, configure, sentrial };