@signalvaultio/node 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SignalVault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,11 @@
 
 AI audit logs and guardrails for your OpenAI and Anthropic applications.
 
+> **Server-side only.** This SDK uses Node APIs (`async_hooks`, `fetch`) and
+> requires Node.js **18+**. Do **not** bundle it for the browser — your
+> `apiKey`, `openaiApiKey`, and `anthropicApiKey` would be exposed to end
+> users. Always call SignalVault from your backend.
+
 ## Installation
 
 ```bash
@@ -57,7 +62,7 @@ console.log(response.content[0].text);
 
 ## Streaming
 
-Streaming is fully supported for both providers. SignalVault logs the complete response once the stream finishes:
+Streaming is fully supported for both providers. SignalVault logs the response when the stream ends — including a partial response if you stop iterating early or the stream fails. A stream you never iterate is not logged.
 
 ```typescript
 // OpenAI streaming
@@ -86,6 +91,72 @@ for await (const event of stream) {
 }
 ```
 
+For token counts on OpenAI streams, pass `stream_options: { include_usage: true }`. The SDK does not add it for you, because OpenAI then sends a final chunk with an empty `choices` array.
+
+## Agent Tool-Use Capture
+
+Log every tool invocation made by your agents — name, input, output, duration, and any error — as auditable events alongside your LLM calls.
+
+### Wrapper API (recommended)
+
+```typescript
+const fetchWeather = client.tool('fetch_weather', async (city: string) => {
+  const res = await fetch(`https://api.example.com/weather?city=${city}`);
+  return res.json();
+});
+
+// Call it like the original — SignalVault auto-times and audits
+const weather = await fetchWeather('London');
+```
+
+The wrapper records the call asynchronously (no impact on your tool's latency) and passes the result through unchanged. Errors are recorded and rethrown.
+
+### Manual API
+
+```typescript
+await client.tools.record({
+  toolName: 'fetch_weather',
+  toolInput: { city: 'London' },
+  toolOutput: { temp: 12.3 },
+  durationMs: 142,
+});
+```
+
+### What gets captured (and what to keep out)
+
+When you wrap a tool or call `tools.record()`, SignalVault captures:
+
+- `tool_name` (truncated to 200 bytes)
+- `tool_input` — the function arguments, JSON-serialized (capped at 256 KB; oversize values are truncated with a marker)
+- `tool_output` — the function return value, JSON-serialized (same 256 KB cap)
+- `error.message` if the tool throws (truncated to 1900 bytes)
+- `duration_ms`, `started_at`, and any `metadata` you attach
+
+`tool_input` and `tool_output` are encrypted at rest server-side. `tool_name`,
+`error`, `started_at` and `metadata` are stored as sent, **not encrypted**. All of
+it goes on the wire to SignalVault's API: **if you pass user PII, secrets, or API
+keys as tool arguments, those values will leave your process and be stored in
+SignalVault.** Recommendations:
+
+- Sanitize sensitive arguments before invoking the wrapped tool, or use the
+  manual `tools.record()` API and pass a redacted copy.
+- Don't put secrets in error messages — they end up in `error` verbatim and unencrypted.
+- Use `metadata` for non-sensitive identifiers (`user_id`, `feature`,
+  `workspace_id`); avoid putting raw user content in metadata.
+
+### Linking tool calls to a parent LLM turn
+
+Wrap your agent loop in `withContext` and tool calls inside auto-correlate to the given `requestId`:
+
+```typescript
+await client.withContext({ requestId: 'agent-turn-abc' }, async () => {
+  const llmResponse = await client.chat.completions.create({...});
+  await fetchWeather('London'); // auto-linked to 'agent-turn-abc'
+});
+```
+
+Without `withContext`, tool calls are recorded as orphans (no parent request).
+
 ## Metadata
 
 Attach contextual metadata to every event — perfect for audit trails, user attribution, and analytics:
@@ -105,19 +176,37 @@ const response = await client.chat.completions.create(
 );
 ```
 
-## Timeout Configuration
+## When SignalVault Is Unavailable
+
+The pre-flight guardrail check is in your request's critical path. If it cannot return a decision — timeout, network error, invalid or revoked API key (401), inactive subscription (402), access denied (403), rate or trial limit (429), server error, or an invalid response — `failMode` decides what happens:
+
+- `'open'` (default): the request goes to the provider **without** guardrails, and the SDK prints a warning (at most once a minute per cause, whether or not `debug` is on). If SignalVault was unreachable, timed out or errored, the request is still recorded in the background, marked `preflight_unavailable`, so it appears in your audit log.
+- `'closed'`: the SDK throws `SignalVaultUnavailableError` and the provider is never called. Use this if every request must be checked.
 
-The pre-flight guardrail check is in your request's critical path. SignalVaultClient uses a short timeout and **fails open** — your request always goes through even if the SignalVault API is slow or unreachable:
+`failMode` applies to the pre-flight check, so it has no effect in mirror mode.
+
+**Rate limit.** The ingest API allows 120 events per minute per app, and each call sends two (request and response), plus one per tool call. Above roughly 60 LLM calls a minute, pre-flight checks are rate limited: with `failMode: 'open'` those requests go through unchecked. If you run at that volume and need enforcement, use `failMode: 'closed'`.
 
 ```typescript
 const client = new SignalVaultClient({
   apiKey: 'sk_live_...',
   openaiApiKey: process.env.OPENAI_API_KEY!,
-  preflightTimeout: 2000,  // ms — pre-flight check timeout (fails open). Default: 2000
+  failMode: 'closed',      // 'open' | 'closed'. Default: 'open'
+  preflightTimeout: 2000,  // ms — pre-flight check timeout. Default: 2000
   timeout: 10000,          // ms — background/post-flight calls. Default: 10000
 });
 ```
 
+Audit events (responses, mirror-mode events, tool calls) are sent in the background. Each carries an `event_id`, so a retry is never double-counted. The SDK retries once on connection errors and 5xx (not on timeouts). A rate-limited (429) event is retried only if `Retry-After` is 5 seconds or less; the SignalVault API currently asks for 60, so in practice those events are dropped, with a warning. `tools.record()` does not retry.
+
+## Shutting Down
+
+Background events are queued in memory. Before a short-lived process exits (a script, a serverless handler), wait for them:
+
+```typescript
+await client.flush();   // or client.close(); both wait up to 5s by default
+```
+
 ## Mirror Mode
 
 In mirror mode, requests go directly to the AI provider first and SignalVault audits them asynchronously — no latency added, never blocks:
@@ -133,7 +222,8 @@ const client = new SignalVaultClient({
 ## Features
 
 - **Automatic Logging** — Every request and response is recorded in your SignalVault dashboard
-- **Pre-flight Guardrails** — Block or redact requests before they reach the AI provider
+- **Pre-flight Guardrails** — Block requests that break your rules before they reach the AI provider
+- **Redaction at rest** — Rules with the `redact` action remove matches from what SignalVault stores. The request sent to the AI provider is **not** modified.
 - **PII Detection** — Automatically detect emails, phone numbers, SSNs in prompts
 - **Secret Detection** — Block API keys and tokens in prompts
 - **Token Limits** — Enforce cost controls per request
@@ -150,10 +240,11 @@ const client = new SignalVaultClient({
   apiKey: 'sk_live_...',            // Your SignalVault API key (required)
   openaiApiKey: 'sk-...',           // OpenAI API key (required for chat.completions)
   anthropicApiKey: 'sk-ant-...',    // Anthropic API key (required for messages)
-  baseUrl: 'https://api.signalvault.io',
-  environment: 'production',        // 'development' | 'staging' | 'production'
+  baseUrl: 'https://api.signalvault.io', // default; plain http:// only allowed for localhost
+  environment: 'production',        // sent with events; the server uses the API key's environment
   debug: false,
   mirrorMode: false,
+  failMode: 'open',                 // 'open' | 'closed' — see "When SignalVault Is Unavailable"
   preflightTimeout: 2000,           // ms
   timeout: 10000,                   // ms
   metadata: {},                     // Default metadata for all events
@@ -163,14 +254,22 @@ const client = new SignalVaultClient({
 ## Error Handling
 
 ```typescript
+import { SignalVaultBlockedError, SignalVaultUnavailableError } from '@signalvaultio/node';
+
 try {
   const response = await client.chat.completions.create({
     model: 'gpt-4',
     messages: [{ role: 'user', content: 'my SSN is 123-45-6789' }],
   });
 } catch (error) {
-  if (error.message.includes('[SignalVault]')) {
-    console.log('Request blocked by guardrail');
+  if (error instanceof SignalVaultBlockedError) {
+    console.log('Blocked by guardrails:', error.violations.map((v) => v.type));
+    console.log('Details:', error.dashboardUrl);
+  } else if (error instanceof SignalVaultUnavailableError) {
+    // Only thrown with failMode: 'closed'
+    console.log('Guardrail check unavailable:', error.status);
+  } else {
+    throw error;
   }
 }
 ```

package/dist/index.d.ts

@@ -1,18 +1,43 @@
 import OpenAI from 'openai';
+import { ToolsAPI } from './tools';
+export type { ToolRecordOptions, ToolsAPI } from './tools';
+/** Kept in sync with package.json by a unit test. */
+export declare const SDK_VERSION = "0.4.0";
+/**
+ * Normalizes the base URL and refuses plaintext HTTP to anything but the local
+ * machine. The API key and full prompts travel in every request, so an
+ * `http://` URL would expose both before the server could redirect to HTTPS.
+ */
+export declare function normalizeBaseUrl(raw: string): string;
+/**
+ * What to do when SignalVault cannot return a guardrail decision (unreachable,
+ * timed out, rate limited, invalid key, inactive subscription, ...).
+ *
+ * - `'open'` (default): allow the request and print a warning.
+ * - `'closed'`: throw {@link SignalVaultUnavailableError} instead of calling
+ *   the provider unchecked.
+ */
+export type FailMode = 'open' | 'closed';
 export interface SignalVaultConfig {
     apiKey: string;
     /** Required for OpenAI (chat.completions). */
     openaiApiKey?: string;
     /** Required for Anthropic (messages). Install @anthropic-ai/sdk separately. */
     anthropicApiKey?: string;
+    /** Default: https://api.signalvault.io. Plain http:// is only accepted for localhost. */
     baseUrl?: string;
+    /**
+     * Sent with every event for backwards compatibility. The server takes the
+     * environment from the API key, so this value does not select rules.
+     */
     environment?: 'development' | 'staging' | 'production';
     debug?: boolean;
     mirrorMode?: boolean;
+    /** Behaviour when no guardrail decision can be obtained. Default: 'open'. */
+    failMode?: FailMode;
     /**
      * 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
+     * This is in the critical path. Default: 2000
      */
     preflightTimeout?: number;
     /**
@@ -26,25 +51,45 @@ export interface SignalVaultConfig {
      */
     metadata?: Record<string, unknown>;
 }
+export interface SignalVaultViolation {
+    rule_id?: string;
+    type: string;
+    severity: number;
+    action: string;
+    details: Record<string, unknown>;
+}
 export interface SignalVaultDecision {
     decision: 'allow' | 'warn' | 'block' | 'redact';
-    violations: Array<{
-        rule_id?: string;
-        type: string;
-        severity: number;
-        action: string;
-        details: Record<string, unknown>;
-    }>;
+    violations: SignalVaultViolation[];
+    /**
+     * Rule types whose redact action matched, with match counts. Redaction
+     * applies to what SignalVault stores; the request sent to the provider is
+     * not modified. Check `.length`, never truthiness.
+     */
     redactions: Array<{
-        start: number;
-        end: number;
-        replacement: string;
+        type: string;
+        count: number;
     }>;
+    /** Present on block decisions. */
+    dashboard_url?: string;
 }
 export interface CreateOptions {
     /** Per-call metadata, merged over config-level metadata. */
     metadata?: Record<string, unknown>;
 }
+/** Thrown when a guardrail rule blocks the request. */
+export declare class SignalVaultBlockedError extends Error {
+    readonly requestId: string;
+    readonly violations: SignalVaultViolation[];
+    readonly dashboardUrl?: string;
+    constructor(requestId: string, violations: SignalVaultViolation[], dashboardUrl?: string);
+}
+/** Thrown in `failMode: 'closed'` when no guardrail decision could be obtained. */
+export declare class SignalVaultUnavailableError extends Error {
+    readonly requestId: string;
+    readonly status?: number;
+    constructor(requestId: string, reason: string, status?: number);
+}
 /**
  * SignalVault Client — wraps OpenAI and/or Anthropic with guardrails and audit logging.
  *
@@ -53,10 +98,9 @@ export interface CreateOptions {
  * const client = new SignalVaultClient({
  *   apiKey: 'sk_live_...',
  *   openaiApiKey: process.env.OPENAI_API_KEY!,
- *   baseUrl: 'https://api.signalvault.io',
  *   metadata: { user_id: '123' },
  * });
- * const res = await client.chat.completions.create({ model: 'gpt-4', messages: [...] });
+ * const res = await client.chat.completions.create({ model: 'gpt-4o', messages: [...] });
  * ```
  *
  * @example Anthropic
@@ -64,9 +108,8 @@ export interface CreateOptions {
  * 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 });
+ * const res = await client.messages.create({ model: 'claude-sonnet-4-5', messages: [...], max_tokens: 1024 });
  * ```
  */
 export declare class SignalVaultClient {
@@ -75,12 +118,81 @@ export declare class SignalVaultClient {
     private readonly svEnvironment;
     private readonly debugMode;
     private readonly mirrorMode;
+    private readonly failMode;
     private readonly preflightTimeout;
     private readonly bgTimeout;
     private readonly defaultMetadata;
     private readonly openai;
     private readonly anthropic;
+    private readonly pending;
+    private readonly lastWarned;
     constructor(config: SignalVaultConfig);
+    /**
+     * Waits for in-flight audit events to finish sending, up to `timeoutMs`.
+     * Call before a short-lived process exits (scripts, serverless handlers),
+     * otherwise queued events are lost.
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    /** Flushes pending events. The client can still be used afterwards. */
+    close(timeoutMs?: number): Promise<void>;
+    /** Tracks a background promise so flush() can wait for it. Never rejects. */
+    private track;
+    /** Prints a warning, at most once per minute per key. Not gated on debug. */
+    private warn;
+    /**
+     * 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.ChatCompletionCreateParamsNonStreaming, options?: CreateOptions): Promise<OpenAI.Chat.ChatCompletion>;
@@ -94,11 +206,48 @@ export declare class SignalVaultClient {
     private handleOpenAINormal;
     private handleAnthropicMirror;
     private handleAnthropicNormal;
+    /**
+     * Yields chunks through unchanged and records the response when the stream
+     * ends — including when the consumer breaks out early or the stream throws,
+     * in which case the partial output is recorded.
+     */
     private wrapStream;
     private wrapAnthropicStream;
-    private authHeaders;
+    /** Runs the pre-flight check and throws if the request must not proceed. */
+    private enforce;
+    /**
+     * Called when no decision could be obtained. Throws in failMode 'closed';
+     * otherwise warns (never silently) and allows.
+     */
+    private unavailable;
+    /**
+     * The ai.request body to record in the background when the pre-flight got
+     * no decision, so an unchecked call is still in the audit log. Undefined
+     * when the pre-flight was recorded normally; null when the server refused
+     * it and no audit event should be sent.
+     */
+    private fallbackRequest;
+    private requestBody;
+    private describeFailure;
+    private headers;
+    /** Single POST. Never follows redirects, so the API key is never re-sent elsewhere. */
+    private post;
+    /**
+     * POST for background events. Adds an `event_id` so a retry is never
+     * double-counted, and retries once on connection errors, 5xx, and 429 with a
+     * short Retry-After. Timeouts are not retried: the server may be slow rather
+     * than down, and a retry would double the time the event is held. Returns
+     * the last response, or null if nothing was received.
+     */
+    private postBackground;
+    private logUndelivered;
     private sendRequest;
     private sendResponseEvent;
+    /**
+     * Mirror mode: records the request, then the response. Sequential on
+     * purpose — the server rejects an ai.response whose ai.request it has not
+     * stored yet, so sending both at once can lose the response.
+     */
     private sendAuditEvents;
 }
 export default SignalVaultClient;