@signalvaultio/node 0.4.0 → 0.5.1

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
@@ -91,7 +101,7 @@ 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.
+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
 
@@ -251,8 +261,20 @@ const client = new SignalVaultClient({
 });
 ```
 
+`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';
 

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,8 +1,8 @@
-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.4.0";
+export declare const SDK_VERSION = "0.5.1";
 /**
  * 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
@@ -209,7 +209,9 @@ export declare class SignalVaultClient {
     /**
      * 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.
+     * 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;

package/dist/index.js

@@ -1,15 +1,11 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SignalVaultClient = exports.SignalVaultUnavailableError = exports.SignalVaultBlockedError = exports.SDK_VERSION = void 0;
 exports.normalizeBaseUrl = normalizeBaseUrl;
 const crypto_1 = require("crypto");
-const openai_1 = __importDefault(require("openai"));
 const tools_1 = require("./tools");
 /** Kept in sync with package.json by a unit test. */
-exports.SDK_VERSION = '0.4.0';
+exports.SDK_VERSION = '0.5.1';
 const DEFAULT_BASE_URL = 'https://api.signalvault.io';
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /** Longest Retry-After the SDK will wait out before retrying a background event once. */
@@ -42,25 +38,67 @@ function assertNodeEnvironment() {
  * `http://` URL would expose both before the server could redirect to HTTPS.
  */
 function normalizeBaseUrl(raw) {
+    // Errors never quote `raw`: it may contain credentials.
     let url;
     try {
         url = new URL(raw);
     }
     catch {
-        throw new Error(`[SignalVault] baseUrl is not a valid URL: ${raw}`);
+        throw new Error('[SignalVault] baseUrl is not a valid URL.');
+    }
+    if (url.username || url.password) {
+        throw new Error('[SignalVault] baseUrl must not contain credentials (user:password@). Pass the key as apiKey.');
     }
     if (url.protocol === 'http:' && !LOCAL_HOSTS.has(url.hostname)) {
         throw new Error('[SignalVault] baseUrl must use https:// (plain http:// is only allowed for localhost). ' +
             'Your API key and prompts would otherwise be sent unencrypted.');
     }
     if (url.search || url.hash) {
-        throw new Error(`[SignalVault] baseUrl must not contain a query or fragment: ${raw}`);
+        throw new Error('[SignalVault] baseUrl must not contain a query or fragment.');
     }
     if (url.protocol !== 'https:' && url.protocol !== 'http:') {
         throw new Error(`[SignalVault] baseUrl must be an https:// URL, got ${url.protocol}`);
     }
     return raw.replace(/\/+$/, '');
 }
+/**
+ * Strips surrounding whitespace and refuses keys that can't go in a header.
+ * A key read from a file or a secret often ends in a newline. Sent as is,
+ * every request fails before it leaves the process, so with failMode 'open'
+ * every call would go through unchecked. Errors never include the key.
+ */
+function normalizeApiKey(raw) {
+    if (typeof raw !== 'string') {
+        throw new TypeError(`[SignalVault] apiKey must be a string, got ${raw === null ? 'null' : typeof raw}.`);
+    }
+    const key = raw.trim();
+    if (!key) {
+        throw new Error('[SignalVault] apiKey is empty.');
+    }
+    if (/[^\x21-\x7e]/.test(key)) {
+        throw new Error('[SignalVault] apiKey contains whitespace, control or non-ASCII characters. Check how the key is loaded.');
+    }
+    return key;
+}
+/**
+ * One line describing an error and its causes, for debug output. Never
+ * includes `secret`, and never throws.
+ */
+function describeError(error, secret) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; current !== undefined && current !== null && depth < 5; depth++) {
+        try {
+            parts.push(current instanceof Error ? `${current.name}: ${current.message}` : String(current));
+            current = current instanceof Error ? current.cause : undefined;
+        }
+        catch {
+            parts.push('<unprintable error>');
+            break;
+        }
+    }
+    return parts.join(' <- ').split(secret).join('[redacted]');
+}
 /** Thrown when a guardrail rule blocks the request. */
 class SignalVaultBlockedError extends Error {
     constructor(requestId, violations, dashboardUrl) {
@@ -134,6 +172,76 @@ function parseRetryAfterMs(response) {
     return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * The provider SDKs are optional peers, loaded only when their API key is
+ * configured, so installing just the one you use is enough. The requires are
+ * literal strings inside try blocks on purpose: bundlers can only follow a
+ * literal require, and treat one inside a try as optional.
+ */
+function loadOpenAI(apiKey) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('openai');
+    }
+    catch (error) {
+        throw notInstalled(error, 'openai');
+    }
+    return construct(mod, apiKey);
+}
+function loadAnthropic(apiKey) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('@anthropic-ai/sdk');
+    }
+    catch (error) {
+        throw notInstalled(error, '@anthropic-ai/sdk');
+    }
+    return construct(mod, apiKey);
+}
+function construct(mod, apiKey) {
+    const Client = mod.default ?? mod;
+    return new Client({ apiKey });
+}
+/**
+ * Only a missing package is reported as "not installed"; anything else (a
+ * broken install, a missing transitive dependency) is returned unchanged.
+ */
+function notInstalled(error, pkg) {
+    // Read fields directly: `instanceof Error` fails across realms (e.g. under Jest).
+    const { code, message } = (error ?? {});
+    if (code === 'MODULE_NOT_FOUND' && String(message).includes(`'${pkg}'`)) {
+        return new Error(`[SignalVault] ${pkg} is not installed. Run: npm install ${pkg}`);
+    }
+    return error;
+}
+/**
+ * Asks OpenAI to report token usage on a stream, unless the caller already
+ * decided either way. OpenAI then sends one extra final chunk with an empty
+ * `choices` array; `injected` tells the stream wrapper to consume that chunk
+ * instead of passing it to a caller who never asked for it.
+ *
+ * `stream_options: null` opts out entirely: the key is removed, for
+ * OpenAI-compatible servers that reject `stream_options`. (The OpenAI API
+ * treats null and absent the same.)
+ */
+function withStreamUsage(params) {
+    if (!params.stream)
+        return { params, injected: false };
+    const options = params.stream_options;
+    if (options === null) {
+        const { stream_options: _omitted, ...rest } = params;
+        return { params: rest, injected: false };
+    }
+    if (options && options.include_usage !== undefined) {
+        return { params, injected: false };
+    }
+    return {
+        params: { ...params, stream_options: { ...(options ?? {}), include_usage: true } },
+        injected: true,
+    };
+}
 // ---------------------------------------------------------------------------
 // SignalVaultClient
 // ---------------------------------------------------------------------------
@@ -170,7 +278,7 @@ class SignalVaultClient {
         if (config.failMode !== undefined && config.failMode !== 'open' && config.failMode !== 'closed') {
             throw new Error("[SignalVault] failMode must be 'open' or 'closed'.");
         }
-        this.svApiKey = config.apiKey;
+        this.svApiKey = normalizeApiKey(config.apiKey);
         this.svBaseUrl = normalizeBaseUrl(config.baseUrl || DEFAULT_BASE_URL);
         this.svEnvironment = config.environment || 'production';
         this.debugMode = config.debug || false;
@@ -179,23 +287,8 @@ class SignalVaultClient {
         this.preflightTimeout = config.preflightTimeout ?? 2000;
         this.bgTimeout = config.timeout ?? 10000;
         this.defaultMetadata = config.metadata ?? {};
-        this.openai = config.openaiApiKey
-            ? new openai_1.default({ apiKey: config.openaiApiKey })
-            : null;
-        if (config.anthropicApiKey) {
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-var-requires
-                const mod = require('@anthropic-ai/sdk');
-                const Anthropic = mod.default ?? mod;
-                this.anthropic = new Anthropic({ apiKey: config.anthropicApiKey });
-            }
-            catch {
-                throw new Error('[SignalVault] @anthropic-ai/sdk is not installed. Run: npm install @anthropic-ai/sdk');
-            }
-        }
-        else {
-            this.anthropic = null;
-        }
+        this.openai = config.openaiApiKey ? loadOpenAI(config.openaiApiKey) : null;
+        this.anthropic = config.anthropicApiKey ? loadAnthropic(config.anthropicApiKey) : null;
     }
     // ---------------------------------------------------------------------------
     // Lifecycle
@@ -231,8 +324,9 @@ class SignalVaultClient {
     track(promise) {
         const tracked = promise
             .catch((err) => {
-            if (this.debugMode)
-                console.error('[SignalVault] Background event failed:', err);
+            if (this.debugMode) {
+                console.error('[SignalVault] Background event failed:', describeError(err, this.svApiKey));
+            }
         })
             .finally(() => this.pending.delete(tracked));
         this.pending.add(tracked);
@@ -406,11 +500,12 @@ class SignalVaultClient {
     // OpenAI — mirror mode
     // ---------------------------------------------------------------------------
     async handleOpenAIMirror(requestId, params, metadata) {
-        const response = await this.openai.chat.completions.create(params);
+        const usage = withStreamUsage(params);
+        const response = await this.openai.chat.completions.create(usage.params);
         const model = params.model;
         const messages = params.messages;
         if (params.stream) {
-            return this.wrapStream(response, (output, promptTokens, completionTokens) => this.sendAuditEvents(requestId, model, messages, output, promptTokens, completionTokens, metadata, 'openai'));
+            return this.wrapStream(response, usage.injected, (output, promptTokens, completionTokens) => this.sendAuditEvents(requestId, model, messages, output, promptTokens, completionTokens, metadata, 'openai'));
         }
         const completion = response;
         this.track(this.sendAuditEvents(requestId, model, messages, completion.choices[0]?.message?.content || '', completion.usage?.prompt_tokens || 0, completion.usage?.completion_tokens || 0, metadata, 'openai'));
@@ -424,9 +519,10 @@ class SignalVaultClient {
         const messages = params.messages;
         const decision = await this.enforce(requestId, model, messages, metadata, 'openai');
         const fallback = this.fallbackRequest(decision, requestId, model, messages, metadata, 'openai');
-        const response = await this.openai.chat.completions.create(params);
+        const usage = withStreamUsage(params);
+        const response = await this.openai.chat.completions.create(usage.params);
         if (params.stream) {
-            return this.wrapStream(response, (output, promptTokens, completionTokens) => this.sendResponseEvent(requestId, model, output, promptTokens, completionTokens, metadata, 'openai', fallback));
+            return this.wrapStream(response, usage.injected, (output, promptTokens, completionTokens) => this.sendResponseEvent(requestId, model, output, promptTokens, completionTokens, metadata, 'openai', fallback));
         }
         const completion = response;
         // Background: the audit of the response must not delay returning it.
@@ -465,9 +561,11 @@ class SignalVaultClient {
     /**
      * 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.
+     * 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.
      */
-    async *wrapStream(stream, onComplete) {
+    async *wrapStream(stream, hideUsageChunk, onComplete) {
         const chunks = [];
         let promptTokens = 0;
         let completionTokens = 0;
@@ -479,6 +577,9 @@ class SignalVaultClient {
                 if (chunk.usage) {
                     promptTokens = chunk.usage.prompt_tokens || 0;
                     completionTokens = chunk.usage.completion_tokens || 0;
+                    // Missing or empty `choices`: the usage-only chunk the caller didn't ask for.
+                    if (hideUsageChunk && !chunk.choices?.length)
+                        continue;
                 }
                 yield chunk;
             }
@@ -641,8 +742,9 @@ class SignalVaultClient {
             }
         }
         catch (error) {
-            if (this.debugMode)
-                console.error('[SignalVault] Event send failed:', error);
+            if (this.debugMode) {
+                console.error('[SignalVault] Event send failed:', describeError(error, this.svApiKey));
+            }
             if (!isTimeout(error))
                 retryDelayMs = 250 + Math.random() * 500;
         }
@@ -654,8 +756,9 @@ class SignalVaultClient {
                     return result;
             }
             catch (error) {
-                if (this.debugMode)
-                    console.error('[SignalVault] Event retry failed:', error);
+                if (this.debugMode) {
+                    console.error('[SignalVault] Event retry failed:', describeError(error, this.svApiKey));
+                }
             }
         }
         this.logUndelivered(result);
@@ -676,8 +779,9 @@ class SignalVaultClient {
         }
         catch (error) {
             const timedOut = isTimeout(error);
-            if (this.debugMode)
-                console.error('[SignalVault] Pre-flight failed:', error);
+            if (this.debugMode) {
+                console.error('[SignalVault] Pre-flight failed:', describeError(error, this.svApiKey));
+            }
             return this.unavailable(requestId, timedOut ? 'timeout' : 'network', timedOut
                 ? `SignalVault pre-flight check timed out after ${this.preflightTimeout}ms`
                 : 'SignalVault API is unreachable');

package/dist/index.mjs

@@ -0,0 +1,16 @@
+// ESM entry point. Re-exports the CommonJS build rather than shipping a
+// second copy of the SDK: two copies would each hold their own module state
+// (the AsyncLocalStorage behind withContext), so context set through `import`
+// would be invisible to code loaded through `require`. Named imports from
+// CommonJS keep default-export interop out of the picture for Node and
+// bundlers alike. Keep this list in sync with src/index.ts — the package test
+// fails if they differ.
+export {
+  SDK_VERSION,
+  SignalVaultBlockedError,
+  SignalVaultClient,
+  SignalVaultUnavailableError,
+  normalizeBaseUrl,
+} from './index.js';
+import { SignalVaultClient } from './index.js';
+export default SignalVaultClient;

package/package.json

@@ -1,16 +1,30 @@
 {
   "name": "@signalvaultio/node",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "SignalVault SDK - AI audit logs and guardrails for safe production AI",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "!dist/__tests__",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/build.mjs",
     "prepublishOnly": "npm run build",
     "test": "jest --passWithNoTests"
   },
@@ -41,7 +55,7 @@
   "homepage": "https://signalvault.io/docs",
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.20.0",
-    "openai": "^4.0.0"
+    "openai": "^4.4.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "peerDependenciesMeta": {
     "openai": {