@sentrial/sdk 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,80 @@
+/**
+ * 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' | '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;
+    /** Enable enhanced detection heuristics (reserved for future use) */
+    enhancedDetection?: boolean;
+    /** 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>;
+
 /**
  * Type definitions for the Sentrial TypeScript SDK
  */
+
 /**
  * Event types that can be tracked in a session
  */
@@ -27,6 +101,12 @@ interface SentrialClientConfig {
      * 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.
+     */
+    pii?: PiiConfig | boolean;
 }
 /**
  * Parameters for creating a new session
@@ -40,6 +120,8 @@ interface CreateSessionParams {
     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>;
 }
@@ -79,6 +161,7 @@ interface Session {
     id: string;
     agentId?: string;
     parentSessionId?: string;
+    convoId?: string;
     name: string;
     agentName: string;
     userId: string;
@@ -368,8 +451,18 @@ declare class SentrialClient {
     private readonly apiUrl;
     private readonly apiKey?;
     private readonly failSilently;
+    private piiConfig?;
+    private piiConfigNeedsHydration;
+    private piiHydrationPromise?;
     private currentState;
     constructor(config?: SentrialClientConfig);
+    /**
+     * Fetch the organization's PII config from the server.
+     *
+     * Called lazily on the first request when `pii: true` was passed to the constructor.
+     * Uses a single shared promise so concurrent requests don't trigger duplicate fetches.
+     */
+    private hydratePiiConfig;
     /**
      * Make an HTTP request with retry logic and exponential backoff.
      *
@@ -678,11 +771,11 @@ declare class ValidationError extends SentrialError {
  *
  * @example Simple Usage
  * ```ts
- * import { configure, wrapAISDK } from '@sentrial/sdk';
+ * import { configureVercel, wrapAISDK } from '@sentrial/sdk';
  * import * as ai from 'ai';
  * import { openai } from '@ai-sdk/openai';
  *
- * configure({
+ * configureVercel({
  *   apiKey: process.env.SENTRIAL_API_KEY,
  *   defaultAgent: 'my-ai-agent',
  * });
@@ -696,29 +789,15 @@ declare class ValidationError extends SentrialError {
  * });
  * ```
  *
- * @example With Tools
+ * @example Multi-Turn Conversations
  * ```ts
- * import { configure, wrapAISDK } from '@sentrial/sdk';
- * import * as ai from 'ai';
- * import { openai } from '@ai-sdk/openai';
- * import { z } from 'zod';
- *
- * configure({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'tool-agent' });
- *
- * const { generateText } = wrapAISDK(ai);
+ * const { generateText } = wrapAISDK(ai, { convoId: 'convo_123' });
  *
+ * // All calls are linked to the same conversation thread
  * const { text } = await generateText({
- *   model: openai('gpt-4'),
- *   prompt: "What's the weather in San Francisco?",
- *   tools: {
- *     getWeather: {
- *       description: 'Get weather for a location',
- *       parameters: z.object({ location: z.string() }),
- *       execute: async ({ location }) => ({ temperature: 72, conditions: 'sunny' }),
- *     },
- *   },
+ *   model: openai('gpt-4o'),
+ *   messages: conversationHistory,
  * });
- * // Tool calls are automatically traced as child spans!
  * ```
  *
  * @packageDocumentation
@@ -740,23 +819,38 @@ type GenerateTextParams = {
     prompt?: string;
     messages?: Array<{
         role: string;
-        content: string;
+        content: string | unknown;
     }>;
     system?: string;
     tools?: Record<string, {
         execute?: Function;
     } & Record<string, unknown>>;
     maxTokens?: number;
+    maxSteps?: number;
     temperature?: number;
     [key: string]: unknown;
 };
+type UsageInfo = {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+};
+type StepResult = {
+    text?: string;
+    toolCalls?: Array<{
+        toolName: string;
+        args: unknown;
+    }>;
+    toolResults?: Array<{
+        toolName: string;
+        result: unknown;
+    }>;
+    usage?: UsageInfo;
+    finishReason?: string;
+};
 type GenerateTextResult = {
     text: string;
-    usage?: {
-        promptTokens?: number;
-        completionTokens?: number;
-        totalTokens?: number;
-    };
+    usage?: UsageInfo;
     finishReason?: string;
     toolCalls?: Array<{
         toolName: string;
@@ -768,16 +862,19 @@ type GenerateTextResult = {
     }>;
     response?: {
         modelId?: string;
+        id?: string;
     };
+    steps?: StepResult[];
+    reasoning?: unknown;
+    reasoningText?: string;
+    sources?: unknown[];
     [key: string]: unknown;
 };
 type StreamTextResult = {
     textStream: AsyncIterable<string>;
-    usage?: Promise<{
-        promptTokens?: number;
-        completionTokens?: number;
-        totalTokens?: number;
-    }>;
+    fullStream?: AsyncIterable<unknown>;
+    text?: string | Promise<string>;
+    usage?: Promise<UsageInfo>;
     finishReason?: Promise<string>;
     toolCalls?: Promise<Array<{
         toolName: string;
@@ -787,19 +884,30 @@ type StreamTextResult = {
         toolName: string;
         result: unknown;
     }>>;
+    steps?: Promise<StepResult[]>;
+    response?: Promise<{
+        modelId?: string;
+        id?: string;
+    }>;
     [key: string]: unknown;
 };
+/** Per-instance config passed through closures (not global) */
+type WrapperConfig = {
+    defaultAgent?: string;
+    userId?: string;
+    convoId?: string;
+};
 /**
  * Configure the Sentrial SDK for Vercel AI SDK integration.
  *
  * @example
  * ```ts
- * import { configure } from '@sentrial/sdk';
+ * import { configureVercel } from '@sentrial/sdk';
  *
- * configure({
+ * configureVercel({
  *   apiKey: process.env.SENTRIAL_API_KEY,
  *   defaultAgent: 'my-chatbot',
- *   userId: 'user_123', // Optional default user ID
+ *   userId: 'user_123',
  * });
  * ```
  */
@@ -808,48 +916,43 @@ declare function configureVercel(config: {
     apiUrl?: string;
     defaultAgent?: string;
     userId?: string;
+    convoId?: string;
     failSilently?: boolean;
 }): void;
-/**
- * Wrap generateText function
- */
-declare function wrapGenerateText(originalFn: Function, client: SentrialClient): (params: GenerateTextParams) => Promise<GenerateTextResult>;
-/**
- * Wrap streamText function
- */
-declare function wrapStreamText(originalFn: Function, client: SentrialClient): (params: GenerateTextParams) => StreamTextResult;
-/**
- * Wrap generateObject function (similar to generateText)
- */
-declare function wrapGenerateObject(originalFn: Function, client: SentrialClient): (params: GenerateTextParams) => Promise<unknown>;
-/**
- * Wrap streamObject function
- */
-declare function wrapStreamObject(originalFn: Function, client: SentrialClient): (params: GenerateTextParams) => unknown;
+declare function wrapGenerateText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<GenerateTextResult>;
+declare function wrapStreamText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => StreamTextResult;
+declare function wrapGenerateObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<unknown>;
+declare function wrapStreamObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => unknown;
 /**
  * Wrap the Vercel AI SDK to automatically trace all AI calls.
  *
  * @param ai - The imported `ai` module from the Vercel AI SDK
+ * @param options - Optional configuration (client, defaultAgent, userId, convoId)
  * @returns Wrapped versions of the AI SDK functions
  *
- * @example
+ * @example Using with configureVercel
  * ```ts
- * import { configure, wrapAISDK } from '@sentrial/sdk';
- * import * as ai from 'ai';
- * import { openai } from '@ai-sdk/openai';
- *
- * configure({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'my-agent' });
+ * configureVercel({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'my-agent' });
+ * const { generateText, streamText } = wrapAISDK(ai);
+ * ```
  *
- * const { generateText, streamText, generateObject, streamObject } = wrapAISDK(ai);
+ * @example Multi-turn conversations
+ * ```ts
+ * const { generateText } = wrapAISDK(ai, { convoId: 'convo_123' });
+ * ```
  *
- * // All calls are now automatically traced!
- * const { text } = await generateText({
- *   model: openai('gpt-4'),
- *   prompt: 'Hello!',
- * });
+ * @example Using with existing SentrialClient
+ * ```ts
+ * const client = new SentrialClient({ apiKey: process.env.SENTRIAL_API_KEY });
+ * const { generateText } = wrapAISDK(ai, { client, defaultAgent: 'my-agent' });
  * ```
  */
-declare function wrapAISDK(ai: AIModule): {
+declare function wrapAISDK(ai: AIModule, options?: {
+    client?: SentrialClient;
+    defaultAgent?: string;
+    userId?: string;
+    convoId?: string;
+}): {
     generateText: ReturnType<typeof wrapGenerateText>;
     streamText: ReturnType<typeof wrapStreamText>;
     generateObject: ReturnType<typeof wrapGenerateObject>;
@@ -1577,4 +1680,4 @@ declare class Experiment {
     getResults(): Promise<ExperimentResults | null>;
 }
 
-export { ApiError, type ApiResponse, type BeginParams, type CompleteSessionParams, type CostParams, type CreateSessionParams, type Event, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, Interaction, NetworkError, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, isExperimentMode, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapGoogle, wrapLLM, wrapOpenAI };
+export { ApiError, type ApiResponse, type BeginParams, type CompleteSessionParams, type CostParams, type CreateSessionParams, type Event, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapGoogle, wrapLLM, wrapOpenAI };