@sentrial/sdk 0.4.4 → 0.4.5

package/dist/index.d.cts

@@ -270,6 +270,9 @@ declare function redactPayload(payload: Record<string, unknown>, config: PiiConf
  * 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)
@@ -312,7 +315,7 @@ declare class EventBatcher {
     /**
      * Flush all queued events to the API.
      *
-     * Drains the queue and fires all requests in parallel. Safe to call
+     * Drains the queue and sends requests in enqueue order. Safe to call
      * concurrently — only one flush runs at a time.
      */
     flush(): Promise<void>;
@@ -385,6 +388,8 @@ interface CreateSessionParams {
     convoId?: string;
     /** Optional metadata */
     metadata?: Record<string, unknown>;
+    /** Production experiment assignment ids to link to this session */
+    experimentAssignmentIds?: string[];
 }
 /**
  * Parameters for completing a session
@@ -582,6 +587,50 @@ interface FinishParams {
     /** 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;
+    /** External user id for sticky bucketing */
+    userId?: string;
+    /** Conversation id for sticky multi-turn bucketing */
+    convoId?: string;
+    /** Stable anonymous id if no user/conversation id exists */
+    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';
+    experimentId?: string;
+    assignmentId?: string;
+    variant: string;
+    variantConfig?: ProductionVariantConfig;
+    prompt?: string;
+    systemPrompt?: string;
+    model?: string;
+    promptVersion?: string;
+}
 /**
  * Parameters for cost calculation
  */
@@ -719,6 +768,7 @@ declare class SentrialClient {
     private piiHydrationPromise?;
     private readonly _stateVar;
     private readonly batcher?;
+    private pendingExperimentAssignmentIds;
     /** Per-session cost/token accumulator — populated by trackToolCall/trackDecision */
     private sessionAccumulators;
     private get currentState();
@@ -747,6 +797,13 @@ declare class SentrialClient {
      * @returns Session ID, or null if the request failed and failSilently is true
      */
     createSession(params: CreateSessionParams): Promise<string | null>;
+    /**
+     * Get a sticky production experiment variant for this user/conversation.
+     *
+     * The returned assignment id is automatically linked to the next session
+     * created by this client. You can also pass `sessionId` to link immediately.
+     */
+    getVariant(params: GetVariantParams): Promise<VariantAssignment>;
     /**
      * Track a tool call event
      *
@@ -986,6 +1043,7 @@ declare function configure(config: SentrialClientConfig): void;
  * ```
  */
 declare function begin(params: BeginParams): Promise<Interaction>;
+declare function getVariant(params: GetVariantParams): Promise<VariantAssignment>;
 /**
  * Simple API namespace for module-level usage
  */
@@ -994,6 +1052,7 @@ declare function shutdown(): Promise<void>;
 declare const sentrial: {
     configure: typeof configure;
     begin: typeof begin;
+    getVariant: typeof getVariant;
     flush: typeof flush;
     shutdown: typeof shutdown;
 };
@@ -1889,4 +1948,4 @@ declare class Experiment {
     getResults(): Promise<ExperimentResults | null>;
 }
 
-export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, 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, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };
+export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, type GetVariantParams, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, type ProductionVariantConfig, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, type VariantAssignment, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariant, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };

package/dist/index.d.ts

@@ -270,6 +270,9 @@ declare function redactPayload(payload: Record<string, unknown>, config: PiiConf
  * 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)
@@ -312,7 +315,7 @@ declare class EventBatcher {
     /**
      * Flush all queued events to the API.
      *
-     * Drains the queue and fires all requests in parallel. Safe to call
+     * Drains the queue and sends requests in enqueue order. Safe to call
      * concurrently — only one flush runs at a time.
      */
     flush(): Promise<void>;
@@ -385,6 +388,8 @@ interface CreateSessionParams {
     convoId?: string;
     /** Optional metadata */
     metadata?: Record<string, unknown>;
+    /** Production experiment assignment ids to link to this session */
+    experimentAssignmentIds?: string[];
 }
 /**
  * Parameters for completing a session
@@ -582,6 +587,50 @@ interface FinishParams {
     /** 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;
+    /** External user id for sticky bucketing */
+    userId?: string;
+    /** Conversation id for sticky multi-turn bucketing */
+    convoId?: string;
+    /** Stable anonymous id if no user/conversation id exists */
+    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';
+    experimentId?: string;
+    assignmentId?: string;
+    variant: string;
+    variantConfig?: ProductionVariantConfig;
+    prompt?: string;
+    systemPrompt?: string;
+    model?: string;
+    promptVersion?: string;
+}
 /**
  * Parameters for cost calculation
  */
@@ -719,6 +768,7 @@ declare class SentrialClient {
     private piiHydrationPromise?;
     private readonly _stateVar;
     private readonly batcher?;
+    private pendingExperimentAssignmentIds;
     /** Per-session cost/token accumulator — populated by trackToolCall/trackDecision */
     private sessionAccumulators;
     private get currentState();
@@ -747,6 +797,13 @@ declare class SentrialClient {
      * @returns Session ID, or null if the request failed and failSilently is true
      */
     createSession(params: CreateSessionParams): Promise<string | null>;
+    /**
+     * Get a sticky production experiment variant for this user/conversation.
+     *
+     * The returned assignment id is automatically linked to the next session
+     * created by this client. You can also pass `sessionId` to link immediately.
+     */
+    getVariant(params: GetVariantParams): Promise<VariantAssignment>;
     /**
      * Track a tool call event
      *
@@ -986,6 +1043,7 @@ declare function configure(config: SentrialClientConfig): void;
  * ```
  */
 declare function begin(params: BeginParams): Promise<Interaction>;
+declare function getVariant(params: GetVariantParams): Promise<VariantAssignment>;
 /**
  * Simple API namespace for module-level usage
  */
@@ -994,6 +1052,7 @@ declare function shutdown(): Promise<void>;
 declare const sentrial: {
     configure: typeof configure;
     begin: typeof begin;
+    getVariant: typeof getVariant;
     flush: typeof flush;
     shutdown: typeof shutdown;
 };
@@ -1889,4 +1948,4 @@ declare class Experiment {
     getResults(): Promise<ExperimentResults | null>;
 }
 
-export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, 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, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };
+export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, type GetVariantParams, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, type ProductionVariantConfig, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, type VariantAssignment, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariant, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };

package/dist/index.js

@@ -70,7 +70,7 @@ var ValidationError = class extends SentrialError {
 // src/redact.ts
 var _createHash;
 try {
-  const mod = eval("require")("crypto");
+  const mod = new Function('return require("crypto")')();
   if (mod?.createHash) {
     _createHash = mod.createHash;
   }
@@ -175,7 +175,7 @@ function redactPayload(payload, config) {
 // src/async-context.ts
 var _AsyncLocalStorage = null;
 try {
-  const mod = eval("require")("node:async_hooks");
+  const mod = new Function('return require("node:async_hooks")')();
   if (mod?.AsyncLocalStorage) {
     _AsyncLocalStorage = mod.AsyncLocalStorage;
   }
@@ -325,6 +325,9 @@ function getSessionContext() {
 function setDefaultClient(client) {
   _defaultClient = client;
 }
+function getDefaultClient() {
+  return _defaultClient;
+}
 function _setSessionContextWithTokens(sessionId, client) {
   const _sessionToken = _currentSessionId.set(sessionId);
   const _clientToken = client ? _currentClient.set(client) : _currentClient.set(_currentClient.get());
@@ -882,7 +885,7 @@ var EventBatcher = class {
   /**
    * Flush all queued events to the API.
    *
-   * Drains the queue and fires all requests in parallel. Safe to call
+   * Drains the queue and sends requests in enqueue order. Safe to call
    * concurrently — only one flush runs at a time.
    */
   async flush() {
@@ -890,15 +893,15 @@ var EventBatcher = class {
     this.flushing = true;
     const batch = this.queue.splice(0, this.queue.length);
     try {
-      await Promise.all(
-        batch.map(
-          (event) => this.sendFn(event.method, event.url, event.body).catch((err) => {
-            if (typeof console !== "undefined") {
-              console.warn("Sentrial: Batched event failed:", err);
-            }
-          })
-        )
-      );
+      for (const event of batch) {
+        try {
+          await this.sendFn(event.method, event.url, event.body);
+        } catch (err) {
+          if (typeof console !== "undefined") {
+            console.warn("Sentrial: Batched event failed:", err);
+          }
+        }
+      }
     } finally {
       this.flushing = false;
     }
@@ -951,6 +954,7 @@ var SentrialClient = class {
   piiHydrationPromise;
   _stateVar = createContextVar({});
   batcher;
+  pendingExperimentAssignmentIds = [];
   /** Per-session cost/token accumulator — populated by trackToolCall/trackDecision */
   sessionAccumulators = /* @__PURE__ */ new Map();
   get currentState() {
@@ -1101,12 +1105,12 @@ var SentrialClient = class {
         }
       }
     }
-    const networkError = new NetworkError(
-      lastError?.message ?? "Unknown network error",
-      lastError
-    );
+    const networkError = new NetworkError(lastError?.message ?? "Unknown network error", lastError);
     if (this.failSilently) {
-      console.warn(`Sentrial: Request failed after ${MAX_RETRIES + 1} attempts (${method} ${url}):`, networkError.message);
+      console.warn(
+        `Sentrial: Request failed after ${MAX_RETRIES + 1} attempts (${method} ${url}):`,
+        networkError.message
+      );
       return null;
     }
     throw networkError;
@@ -1149,13 +1153,53 @@ var SentrialClient = class {
     if (params.convoId) {
       payload.convoId = params.convoId;
     }
+    const experimentAssignmentIds = [
+      ...params.experimentAssignmentIds || [],
+      ...this.pendingExperimentAssignmentIds
+    ];
+    if (experimentAssignmentIds.length > 0) {
+      payload.experimentAssignmentIds = Array.from(new Set(experimentAssignmentIds));
+      payload.metadata = {
+        ...params.metadata || {},
+        sentrial_experiment_assignment_ids: payload.experimentAssignmentIds
+      };
+    }
     const response = await this.safeRequest(
       "POST",
       `${this.apiUrl}/api/sdk/sessions`,
       payload
     );
+    if (response?.id && experimentAssignmentIds.length > 0) {
+      this.pendingExperimentAssignmentIds = [];
+    }
     return response?.id ?? null;
   }
+  /**
+   * Get a sticky production experiment variant for this user/conversation.
+   *
+   * The returned assignment id is automatically linked to the next session
+   * created by this client. You can also pass `sessionId` to link immediately.
+   */
+  async getVariant(params) {
+    const fallback = {
+      active: false,
+      reason: "not_found",
+      variant: params.defaultVariant || "control"
+    };
+    const response = await this.safeRequest(
+      "POST",
+      `${this.apiUrl}/api/sdk/experiments/variant`,
+      {
+        ...params,
+        sdkName: "@sentrial/sdk"
+      }
+    );
+    if (!response) return fallback;
+    if (response.active && response.assignmentId && !params.sessionId) {
+      this.pendingExperimentAssignmentIds.push(response.assignmentId);
+    }
+    return response;
+  }
   /**
    * Track a tool call event
    *
@@ -1264,11 +1308,9 @@ var SentrialClient = class {
    * @returns Updated session or null on error
    */
   async setInput(sessionId, input) {
-    return this.safeRequest(
-      "PATCH",
-      `${this.apiUrl}/api/sdk/sessions/${sessionId}`,
-      { userInput: input }
-    );
+    return this.safeRequest("PATCH", `${this.apiUrl}/api/sdk/sessions/${sessionId}`, {
+      userInput: input
+    });
   }
   /**
    * Track a generic event
@@ -1328,10 +1370,14 @@ var SentrialClient = class {
     }
     const acc = this.sessionAccumulators.get(params.sessionId);
     if (acc) {
-      if (params.estimatedCost === void 0 && acc.cost > 0) params = { ...params, estimatedCost: acc.cost };
-      if (params.promptTokens === void 0 && acc.promptTokens > 0) params = { ...params, promptTokens: acc.promptTokens };
-      if (params.completionTokens === void 0 && acc.completionTokens > 0) params = { ...params, completionTokens: acc.completionTokens };
-      if (params.totalTokens === void 0 && acc.totalTokens > 0) params = { ...params, totalTokens: acc.totalTokens };
+      if (params.estimatedCost === void 0 && acc.cost > 0)
+        params = { ...params, estimatedCost: acc.cost };
+      if (params.promptTokens === void 0 && acc.promptTokens > 0)
+        params = { ...params, promptTokens: acc.promptTokens };
+      if (params.completionTokens === void 0 && acc.completionTokens > 0)
+        params = { ...params, completionTokens: acc.completionTokens };
+      if (params.totalTokens === void 0 && acc.totalTokens > 0)
+        params = { ...params, totalTokens: acc.totalTokens };
       this.sessionAccumulators.delete(params.sessionId);
     }
     const payload = {
@@ -1570,6 +1616,9 @@ function configure(config) {
 function begin(params) {
   return getClient().begin(params);
 }
+function getVariant(params) {
+  return getClient().getVariant(params);
+}
 async function flush() {
   if (defaultClient) await defaultClient.flush();
 }
@@ -1579,6 +1628,7 @@ async function shutdown() {
 var sentrial = {
   configure,
   begin,
+  getVariant,
   flush,
   shutdown
 };
@@ -2396,6 +2446,11 @@ function wrapClaudeAgent(queryFn, wrapOptions) {
 var _defaultClient3 = null;
 var _currentInteraction = createContextVar(null);
 function getClient3() {
+  const configuredClient = getDefaultClient();
+  if (configuredClient) {
+    _defaultClient3 = configuredClient;
+    return configuredClient;
+  }
   if (!_defaultClient3) {
     try {
       _defaultClient3 = new SentrialClient();
@@ -3163,6 +3218,7 @@ export {
   getExperimentId,
   getSessionContext,
   getSystemPrompt,
+  getVariant,
   getVariantName,
   hashValue,
   isExperimentMode,