@signalvaultio/node 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,11 +1,32 @@
 import OpenAI from 'openai';
+import { ToolsAPI } from './tools';
+export type { ToolRecordOptions, ToolsAPI } from './tools';
 export interface SignalVaultConfig {
     apiKey: string;
-    openaiApiKey: string;
+    /** Required for OpenAI (chat.completions). */
+    openaiApiKey?: string;
+    /** Required for Anthropic (messages). Install @anthropic-ai/sdk separately. */
+    anthropicApiKey?: string;
     baseUrl?: string;
     environment?: 'development' | 'staging' | 'production';
     debug?: boolean;
     mirrorMode?: boolean;
+    /**
+     * Timeout (ms) for the pre-flight /v1/events call in normal mode.
+     * This is in the critical path — on timeout/error the SDK fails open (allows).
+     * Default: 2000
+     */
+    preflightTimeout?: number;
+    /**
+     * Timeout (ms) for all background / post-flight event calls.
+     * Default: 10000
+     */
+    timeout?: number;
+    /**
+     * Default metadata attached to every event. Can be overridden per-call.
+     * Use for user_id, feature, workspace_id, etc.
+     */
+    metadata?: Record<string, unknown>;
 }
 export interface SignalVaultDecision {
     decision: 'allow' | 'warn' | 'block' | 'redact';
@@ -22,50 +43,118 @@ export interface SignalVaultDecision {
         replacement: string;
     }>;
 }
+export interface CreateOptions {
+    /** Per-call metadata, merged over config-level metadata. */
+    metadata?: Record<string, unknown>;
+}
 /**
- * SignalVault Client — wraps OpenAI with guardrails and audit logging.
+ * SignalVault Client — wraps OpenAI and/or Anthropic with guardrails and audit logging.
  *
- * @example
+ * @example OpenAI
  * ```typescript
  * const client = new SignalVaultClient({
  *   apiKey: 'sk_live_...',
  *   openaiApiKey: process.env.OPENAI_API_KEY!,
  *   baseUrl: 'https://api.signalvault.io',
+ *   metadata: { user_id: '123' },
  * });
- *
- * // Non-streaming
  * const res = await client.chat.completions.create({ model: 'gpt-4', messages: [...] });
+ * ```
  *
- * // Streaming
- * const stream = await client.chat.completions.create({ model: 'gpt-4', messages: [...], stream: true });
- * for await (const chunk of stream) { ... }
+ * @example Anthropic
+ * ```typescript
+ * const client = new SignalVaultClient({
+ *   apiKey: 'sk_live_...',
+ *   anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
+ *   baseUrl: 'https://api.signalvault.io',
+ * });
+ * const res = await client.messages.create({ model: 'claude-3-5-sonnet-20241022', messages: [...], max_tokens: 1024 });
  * ```
  */
 export declare class SignalVaultClient {
-    private signalvaultApiKey;
-    private signalvaultBaseUrl;
-    private signalvaultEnvironment;
-    private debugMode;
-    private mirrorMode;
-    private openai;
+    private readonly svApiKey;
+    private readonly svBaseUrl;
+    private readonly svEnvironment;
+    private readonly debugMode;
+    private readonly mirrorMode;
+    private readonly preflightTimeout;
+    private readonly bgTimeout;
+    private readonly defaultMetadata;
+    private readonly openai;
+    private readonly anthropic;
     constructor(config: SignalVaultConfig);
     /**
-     * Chat completions with SignalVault guardrails.
-     * Supports both streaming and non-streaming.
+     * Wraps a function so every call records an `agent.tool_call` event with
+     * timing, input, output, and any error. The wrapper auto-times, runs the
+     * inner function, fires the audit event in the background, and returns the
+     * inner result (or rethrows the inner error).
+     *
+     * Tool calls invoked inside a `withContext({ requestId })` block auto-pick
+     * up the requestId for correlation with the parent ai.request.
+     *
+     * @example
+     * ```typescript
+     * const fetchWeather = signalvault.tool('fetch_weather', async (city: string) => {
+     *   const res = await fetch(`https://api.example.com/weather?city=${city}`);
+     *   return res.json();
+     * });
+     *
+     * const weather = await fetchWeather('London');
+     * ```
      */
+    tool<TArgs extends readonly unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: {
+        metadata?: Record<string, unknown>;
+    }): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * Manual tool recording API. Use when the wrapper isn't a fit (streaming
+     * tools, custom timing, post-hoc capture from logs).
+     *
+     * @example
+     * ```typescript
+     * await signalvault.tools.record({
+     *   toolName: 'fetch_weather',
+     *   toolInput: { city: 'London' },
+     *   toolOutput: { temp: 12.3 },
+     *   durationMs: 142,
+     * });
+     * ```
+     */
+    get tools(): ToolsAPI;
+    /**
+     * Runs the given async function inside a context where tool calls are
+     * automatically correlated to the provided `requestId`. Useful for grouping
+     * a multi-step agent loop under one logical turn.
+     *
+     * @example
+     * ```typescript
+     * await signalvault.withContext({ requestId: 'agent-turn-abc' }, async () => {
+     *   const llm = await signalvault.chat.completions.create({...});
+     *   await fetchWeather('London'); // tool call auto-linked to 'agent-turn-abc'
+     * });
+     * ```
+     */
+    withContext<T>(ctx: {
+        requestId?: string;
+    }, fn: () => Promise<T>): Promise<T>;
+    private sendToolCallEvent;
     get chat(): {
         completions: {
-            create: (params: OpenAI.Chat.ChatCompletionCreateParams) => Promise<any>;
+            create(params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, options?: CreateOptions): Promise<OpenAI.Chat.ChatCompletion>;
+            create(params: OpenAI.Chat.ChatCompletionCreateParamsStreaming, options?: CreateOptions): Promise<AsyncGenerator<OpenAI.Chat.Completions.ChatCompletionChunk>>;
         };
     };
-    private handleMirrorMode;
-    private handleNormalMode;
-    private wrapStreamForAudit;
-    private wrapStreamForPostFlight;
+    get messages(): {
+        create(params: any, options?: CreateOptions): Promise<any>;
+    };
+    private handleOpenAIMirror;
+    private handleOpenAINormal;
+    private handleAnthropicMirror;
+    private handleAnthropicNormal;
+    private wrapStream;
+    private wrapAnthropicStream;
+    private authHeaders;
     private sendRequest;
-    private sendResponse;
-    private sendStreamResponse;
-    private sendAudit;
-    private sendStreamAudit;
+    private sendResponseEvent;
+    private sendAuditEvents;
 }
 export default SignalVaultClient;