@sentrial/sdk 0.4.5 → 0.6.0

package/dist/types-BEf8OATP.d.cts

@@ -0,0 +1,612 @@
+/**
+ * PII Redaction Module
+ *
+ * Automatically detects and redacts personally identifiable information (PII)
+ * from SDK payloads before they are sent to the Sentrial API.
+ */
+
+/** How redacted values are replaced */
+type PiiMode = 'label' | 'hash' | 'remove';
+/** Fields that can be redacted in SDK payloads */
+type PiiField = 'userInput' | 'assistantOutput' | 'toolInput' | 'toolOutput' | 'metadata' | 'reasoning' | 'name' | 'failureReason';
+/** A custom regex pattern with a human-readable label */
+interface PiiCustomPattern {
+    pattern: RegExp;
+    label: string;
+}
+/** Toggle individual builtin pattern categories */
+interface PiiBuiltinPatterns {
+    emails?: boolean;
+    phones?: boolean;
+    ssns?: boolean;
+    creditCards?: boolean;
+    ipAddresses?: boolean;
+}
+/** Full PII redaction configuration */
+interface PiiConfig {
+    /** Enable PII redaction (default: false) */
+    enabled: boolean;
+    /** Which payload fields to redact (default: DEFAULT_FIELDS) */
+    fields?: PiiField[];
+    /** Replacement mode (default: 'label') */
+    mode?: PiiMode;
+    /** Toggle builtin patterns (default: all enabled) */
+    builtinPatterns?: PiiBuiltinPatterns;
+    /** Additional custom patterns to apply */
+    customPatterns?: PiiCustomPattern[];
+}
+/**
+ * Hash a value using SHA-256 and return the first 6 hex characters.
+ * Used in 'hash' mode to produce a short, deterministic pseudonym.
+ */
+declare function hashValue(value: string): string;
+/**
+ * Produce the replacement string for a matched PII value.
+ *
+ * - 'label' mode:  [LABEL]
+ * - 'hash' mode:   [PII:abcdef]
+ * - 'remove' mode: '' (empty string)
+ */
+declare function replaceMatch(match: string, label: string, mode: PiiMode): string;
+/**
+ * Run all enabled builtin and custom patterns against a single string,
+ * replacing every match according to the specified mode.
+ */
+declare function redactString(value: string, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): string;
+/**
+ * Recursively redact PII from a value. Handles strings, arrays, plain objects,
+ * and passes through primitives (numbers, booleans, null, undefined) unchanged.
+ */
+declare function redactValue(value: unknown, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): unknown;
+/**
+ * Main entry point: redact configured fields in a payload object.
+ *
+ * Only fields listed in the PiiConfig (or DEFAULT_FIELDS) are redacted.
+ * Other fields are returned unchanged.
+ *
+ * @param payload - The data payload (e.g., session params, tool call params)
+ * @param config  - PII configuration from the client
+ * @returns A new payload object with PII redacted from the configured fields
+ */
+declare function redactPayload(payload: Record<string, unknown>, config: PiiConfig): Record<string, unknown>;
+
+/**
+ * EventBatcher — fire-and-forget event queue with periodic flushing.
+ *
+ * Buffers tracking events (tool calls, decisions, errors, generic events)
+ * and drains them off the caller's hot path. Each event is still delivered
+ * as its own HTTP request today (the drain loop sends per-event), so this
+ * trades caller latency for throughput, not request count. NOTE: the OTLP
+ * endpoint (/api/otel/v1/traces) is a batch protocol and the server accepts
+ * multi-span batches, so coalescing a flush's queued spans into ONE OTLP
+ * request (one round-trip + one advisory-lock ingest txn per session) is a
+ * viable follow-up — deferred, not blocked by a missing bulk endpoint.
+ * Session lifecycle calls (createSession, completeSession) bypass the batcher
+ * entirely because they need synchronous responses.
+ *
+ * Events are delivered in enqueue order so server-assigned sequence numbers
+ * match the order an agent actually executed steps.
+ *
+ * Flush triggers:
+ *  1. Timer — every `flushIntervalMs` (default 1 000 ms)
+ *  2. Queue size — when queue reaches `flushThreshold` (default 10)
+ *  3. Manual — `flush()` or `shutdown()`
+ *  4. Process exit — `beforeExit` handler
+ *
+ * Back-pressure: queue is capped at `maxQueueSize` (default 1 000).
+ * When full, oldest events are dropped and a warning is logged.
+ */
+interface BatcherConfig {
+    /** Whether batching is enabled (default: false — all calls are immediate) */
+    enabled?: boolean;
+    /** Milliseconds between automatic flushes (default: 1000) */
+    flushIntervalMs?: number;
+    /** Flush when the queue reaches this many items (default: 10) */
+    flushThreshold?: number;
+    /** Maximum queue size before dropping oldest events (default: 1000) */
+    maxQueueSize?: number;
+}
+/** Signature for the function that actually sends an event to the API. */
+type SendFn = (method: string, url: string, body: unknown) => Promise<unknown>;
+/** Request counts for this batcher instance, never a trace-completeness claim. */
+interface DeliveryDiagnostics {
+    enqueued: number;
+    delivered: number;
+    failed: number;
+    dropped: number;
+    rejectedAfterShutdown: number;
+    queued: number;
+    inFlight: number;
+}
+declare class EventBatcher {
+    private readonly queue;
+    private readonly flushIntervalMs;
+    private readonly flushThreshold;
+    private readonly maxQueueSize;
+    private timer;
+    private sendFn;
+    private flushPromise;
+    private shutdownCalled;
+    private counters;
+    private readonly exitHandler;
+    constructor(sendFn: SendFn, config?: BatcherConfig);
+    /**
+     * Enqueue an event for batched delivery.
+     *
+     * If the queue hits `flushThreshold`, an automatic flush is triggered.
+     * If the queue is full (`maxQueueSize`), the oldest event is dropped.
+     */
+    enqueue(method: string, url: string, body: unknown): void;
+    /**
+     * Flush all queued events to the API.
+     *
+     * Drains the queue and sends requests in enqueue order. Safe to call
+     * concurrently — only one flush runs at a time.
+     */
+    flush(): Promise<void>;
+    /** Drain the queue completely, including events enqueued while sending. */
+    private drainAll;
+    /**
+     * Stop the batcher: clear the timer, flush remaining events, remove exit handler.
+     */
+    shutdown(): Promise<void>;
+    /** Number of events currently queued. */
+    get size(): number;
+    get diagnostics(): Readonly<DeliveryDiagnostics>;
+}
+
+interface LargeToolContentConfig {
+    /** Explicit opt-in. The server and workspace must also enable uploads. */
+    enabled: boolean;
+    /** Identifies the caller's redaction policy, not proof that it was applied correctly. */
+    redactionRevision: string;
+    /** Per-field upload deadline, 1–60 seconds. Default: 20 seconds. */
+    timeoutMs?: number;
+}
+
+/**
+ * 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;
+    /**
+     * PII redaction configuration.
+     * - Pass a PiiConfig object for full control.
+     * - Pass `true` to fetch the org's PII config from the server automatically.
+     *   NOTE: the server-config auto-fetch requires an API key with the elevated
+     *   `pii-config:read` scope, which product-issued keys do NOT carry by default.
+     *   Without that scope the fetch returns 403 and the SDK falls back to the
+     *   built-in default (label-mode) redaction rather than the org's configured
+     *   policy. Pass an explicit PiiConfig object if you need guaranteed redaction.
+     */
+    pii?: PiiConfig | boolean;
+    /**
+     * Event batching configuration.
+     * When enabled, fire-and-forget tracking calls (trackToolCall, trackDecision,
+     * trackError, trackEvent) are queued and flushed periodically instead of
+     * being sent immediately. Session lifecycle calls (createSession,
+     * completeSession) always bypass the batcher.
+     */
+    batching?: BatcherConfig;
+    /** Opt-in bounded uploads of already-redacted tool input/output over 64 KiB.
+     * Requires an enabled server/workspace. Failures retain an explicit loss marker. */
+    largeToolContent?: LargeToolContentConfig;
+}
+/**
+ * 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 parent session ID for multi-agent hierarchies */
+    parentSessionId?: string;
+    /** Optional conversation ID to group related sessions into a thread */
+    convoId?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Production experiment assignment ids to link to this session */
+    experimentAssignmentIds?: string[];
+    /**
+     * Optional input captured at session creation. Emitted on the root span as the structured
+     * gen_ai.input.messages (this SDK is OTLP-only).
+     */
+    input?: string;
+    /** The (primary) requested model for the run, when known at creation (→ gen_ai.request.model). */
+    model?: string;
+}
+/**
+ * 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;
+    /** Alias for assistantOutput - the final output text */
+    output?: string;
+    /** The resolved model for the run, when only known at completion (overrides createSession's). */
+    model?: string;
+}
+/**
+ * Session data returned from the API
+ */
+interface Session {
+    id: string;
+    agentId?: string;
+    parentSessionId?: string;
+    convoId?: 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: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+/**
+ * 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. Recognized keys persisted under the OTLP transport:
+     * `message`, `type` (alias `name`), `stack_trace` (alias `stackTrace`) — other keys are
+     * not persisted.
+     */
+    toolError?: Record<string, unknown>;
+    /** Number of tokens used by this tool call (for LLM-based tools) */
+    tokenCount?: number;
+    /** Per-call prompt/completion token split (for LLM-based tools) — emitted as first-class fields. */
+    promptTokens?: number;
+    completionTokens?: number;
+    /** The model used for this call (for LLM-based tools) — emitted as gen_ai.request.model. */
+    model?: string;
+    /** Why generation stopped for this call (e.g. 'stop', 'length', 'tool_calls'). */
+    finishReason?: string;
+    /** How long the tool call took (ms). Sets the event span's real duration (otherwise the event
+     * is recorded as instantaneous). */
+    durationMs?: number;
+    /** When the tool call started (Date or ms epoch). Defaults to now − durationMs when only the
+     * duration is known. */
+    startedAt?: Date | number;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    traceId?: string;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    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;
+    /** How long the decision took (ms). Sets the event span's real duration. */
+    durationMs?: number;
+    /** When the decision started (Date or ms epoch). */
+    startedAt?: Date | number;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    traceId?: string;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    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;
+    /** How long the failed operation ran before erroring (ms). Sets the event span's real duration. */
+    durationMs?: number;
+    /** When the failed operation started (Date or ms epoch). */
+    startedAt?: Date | number;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    traceId?: string;
+    /** Deprecated: accepted for backward compatibility but ignored — this SDK is OTLP-only. */
+    spanId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event data returned from the API
+ */
+interface Event {
+    id: string;
+    sessionId: string;
+    eventType: EventType;
+    timestamp: string;
+    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;
+}
+/** A session object as returned by `GET /api/v1/sessions` (raw wire shape). */
+interface SessionResponse {
+    id: string;
+    name?: string | null;
+    agentName?: string | null;
+    agentSlug?: string | null;
+    convoId?: string | null;
+    userId?: string | null;
+    status?: string | null;
+    success?: boolean | null;
+    failureReason?: string | null;
+    totalEvents?: number | null;
+    durationMs?: number | null;
+    estimatedCost?: number | null;
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    totalTokens?: number | null;
+    score?: number | null;
+    metricScores?: unknown;
+    metricReasonings?: unknown;
+    customMetrics?: unknown;
+    userInput?: string | null;
+    assistantOutput?: string | null;
+    metadata?: unknown;
+    detectedIssues?: unknown;
+    createdAt?: string | null;
+    completedAt?: string | null;
+}
+/** An event object as returned by `GET /api/v1/sessions/:id/events` (raw wire shape). */
+interface EventResponse {
+    id: string;
+    sessionId: string;
+    eventType: string;
+    sequenceNumber?: number | null;
+    timestamp?: string | null;
+    toolName?: string | null;
+    toolInput?: unknown;
+    toolOutput?: unknown;
+    toolError?: unknown;
+    reasoning?: string | null;
+    alternativesConsidered?: unknown;
+    confidence?: number | null;
+    estimatedCost?: number | null;
+    tokenCount?: number | null;
+    metadata?: unknown;
+    traceId?: string | null;
+    spanId?: string | null;
+}
+/**
+ * Parameters for beginning an interaction
+ */
+interface BeginParams {
+    /** Parent session from a validated worker handoff. */
+    parentSessionId?: string;
+    /** 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>;
+    /**
+     * Optional session title override. Defaults to the auto-generated `{event}:{eventId[:8]}` when
+     * omitted. Redacted like the input before emission (→ sentrial.session.name).
+     */
+    name?: string;
+    /** The (primary) requested model for the run, when known at begin (→ gen_ai.request.model). */
+    model?: string;
+}
+/**
+ * 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;
+    /** Duration in milliseconds (auto-calculated from begin/finish if not provided) */
+    durationMs?: number;
+}
+interface ProductionVariantConfig {
+    name: string;
+    weight?: number;
+    prompt?: string;
+    systemPrompt?: string;
+    model?: string;
+    promptVersion?: string;
+    toolConfig?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface GetVariantParams {
+    /** Production experiment name configured in Sentrial */
+    experimentName: string;
+    /** Agent name this variant is for */
+    agentName?: string;
+    /** Required when the experiment assigns by user. Other IDs are not substitutes. */
+    userId?: string;
+    /** Required when the experiment assigns by conversation. */
+    convoId?: string;
+    /** Required when the experiment assigns by stable anonymous identity. */
+    anonymousId?: string;
+    /** Optional existing Sentrial session id */
+    sessionId?: string;
+    /** Variant to use when no active live experiment matches */
+    defaultVariant?: string;
+    /** Prompt version currently running in the customer app */
+    promptVersion?: string;
+    /** Model currently running in the customer app */
+    model?: string;
+    /** Extra assignment metadata */
+    metadata?: Record<string, unknown>;
+}
+interface VariantAssignment {
+    active: boolean;
+    reason: 'assigned' | 'holdout' | 'not_found' | 'missing_identity';
+    /** Declared unit, or the required unit when reason is missing_identity. */
+    assignmentUnit?: 'user' | 'convo' | 'anonymous';
+    /** Historical fallback identities remain unknown; retries do not certify them. */
+    identityProvenance?: 'declared' | 'legacy_unknown';
+    experimentId?: string;
+    assignmentId?: string;
+    /** Frozen configuration digest; absent on legacy assignments. */
+    configurationHash?: string;
+    variant: string;
+    variantConfig?: ProductionVariantConfig;
+    prompt?: string;
+    systemPrompt?: string;
+    model?: string;
+    promptVersion?: string;
+    toolConfig?: Record<string, unknown>;
+}
+/** Explicit application report after using the returned configuration. */
+interface RecordExperimentExposureParams {
+    assignmentId: string;
+    sessionId: string;
+    variant: string;
+    configurationHash: string;
+}
+interface ExperimentExposureReceipt extends RecordExperimentExposureParams {
+    /** Server arrival time, not provider invocation time. */
+    recordedAt: string;
+    source: 'sdk_reported';
+}
+/**
+ * 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>;
+    };
+}
+
+export { type ApiResponse as A, type BeginParams as B, type CostParams as C, type DeliveryDiagnostics as D, type EventResponse as E, type FinishParams as F, type GetVariantParams as G, type LargeToolContentConfig as L, type PiiBuiltinPatterns as P, type RecordExperimentExposureParams as R, type SessionResponse as S, type TrackToolCallParams as T, type VariantAssignment as V, type SentrialClientConfig as a, type CreateSessionParams as b, type ExperimentExposureReceipt as c, type Event as d, type TrackDecisionParams as e, type TrackErrorParams as f, type Session as g, type CompleteSessionParams as h, type BatcherConfig as i, EventBatcher as j, EventType as k, type PiiConfig as l, type PiiCustomPattern as m, type PiiField as n, type PiiMode as o, type ProductionVariantConfig as p, type SessionStatus as q, hashValue as r, redactPayload as s, redactString as t, redactValue as u, replaceMatch as v };