@signalvaultio/node 0.3.0 → 0.5.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

@@ -20,6 +20,18 @@ npm install @signalvaultio/node @anthropic-ai/sdk
 npm install @signalvaultio/node openai @anthropic-ai/sdk
 ```
 
+Supported provider SDKs: `openai` 4.4 through 7.x (openai 7 needs Node.js 22+) and `@anthropic-ai/sdk` 0.20 or later. Install only the one you use; the other is optional. TypeScript projects without `openai` need `skipLibCheck: true` (the default in most setups), because the SDK's type declarations refer to openai's types.
+
+The package works with both `import` and `require()`:
+
+```typescript
+import SignalVaultClient from '@signalvaultio/node';          // ESM, TypeScript
+import { SignalVaultClient } from '@signalvaultio/node';      // also works
+const { SignalVaultClient } = require('@signalvaultio/node'); // CommonJS
+```
+
+Server-side bundlers (webpack, esbuild) are supported. esbuild's ESM output needs its usual `createRequire` banner for CommonJS dependencies: `--banner:js="import { createRequire } from 'module'; const require = createRequire(import.meta.url);"`.
+
 ## Quick Start — OpenAI
 
 ```typescript
@@ -28,8 +40,6 @@ import SignalVaultClient from '@signalvaultio/node';
 const client = new SignalVaultClient({
   apiKey: 'sk_live_your_signalvault_key',
   openaiApiKey: process.env.OPENAI_API_KEY!,
-  baseUrl: 'https://api.signalvault.io',
-  environment: 'production',
 });
 
 // Use exactly like OpenAI SDK
@@ -62,7 +72,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
@@ -91,6 +101,8 @@ for await (const event of stream) {
 }
 ```
 
+For OpenAI streams, the SDK sets `stream_options: { include_usage: true }` so the response is logged with its token counts. OpenAI then sends one extra final chunk that carries only the usage and no choices; the SDK consumes that chunk rather than passing it to you, so the stream you receive looks the same as without usage reporting. If you set `stream_options.include_usage` yourself, your setting is kept: with `true` you receive the usage chunk as usual, with `false` the response is logged without token counts. If your OpenAI-compatible server rejects `stream_options`, pass `stream_options: null` and the SDK sends none.
+
 ## 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.
@@ -130,14 +142,15 @@ When you wrap a tool or call `tools.record()`, SignalVault captures:
 - `error.message` if the tool throws (truncated to 1900 bytes)
 - `duration_ms`, `started_at`, and any `metadata` you attach
 
-These fields are stored encrypted at rest server-side, but they go 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:
+`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.
+- 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.
 
@@ -173,19 +186,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:
 
-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:
+- `'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.
+
+`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:
@@ -201,7 +232,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
@@ -218,27 +250,48 @@ 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
 });
 ```
 
+`environment` does not choose which rules apply: SignalVault uses the environment of the API key you pass as `apiKey`. Use a key created for the environment you want.
+
 ## Error Handling
 
+When a guardrail rule blocks a request, `create()` throws `SignalVaultBlockedError` and the provider is never called. It carries:
+
+- `violations` — the rules that matched, each with `rule_id`, `type` (for example `contains_secret`), `severity`, `action` and `details`
+- `requestId` — the ID the SDK sent to SignalVault as `request_id` for this request
+- `dashboardUrl` — a link to the blocked request, when the API provides one
+
+The message lists only the violation types, never the matched content.
+
+`SignalVaultUnavailableError` (with `requestId` and the HTTP `status`, if any) is thrown only with `failMode: 'closed'`, when no decision could be obtained.
+
 ```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.mts

@@ -0,0 +1,4 @@
+// Types for the ESM entry point (see index.mjs).
+export * from './index.js';
+import { SignalVaultClient } from './index.js';
+export default SignalVaultClient;

package/dist/index.d.ts

@@ -1,20 +1,43 @@
-import OpenAI from 'openai';
+import type 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.5.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;
     /**
@@ -28,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.
  *
@@ -55,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
@@ -66,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 {
@@ -77,12 +118,27 @@ 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
@@ -150,11 +206,50 @@ 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. When the SDK added
+     * `include_usage` itself (`hideUsageChunk`), the usage-only final chunk is
+     * consumed here rather than passed on.
+     */
     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;