promptguard-sdk 1.8.0 → 1.10.0

package/README.md

@@ -1,4 +1,4 @@
-[![npm version](https://img.shields.io/npm/v/promptguard)](https://www.npmjs.com/package/promptguard)
+[![npm version](https://img.shields.io/npm/v/promptguard-sdk)](https://www.npmjs.com/package/promptguard-sdk)
 [![CI](https://github.com/acebot712/promptguard-node/actions/workflows/ci.yml/badge.svg)](https://github.com/acebot712/promptguard-node/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/acebot712/promptguard-node)](https://github.com/acebot712/promptguard-node/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
@@ -13,18 +13,36 @@ Drop-in security for AI applications. Secure any GenAI app - regardless of frame
 npm install promptguard-sdk
 ```
 
+> The npm package and the import specifier are both **`promptguard-sdk`** — no surprises:
+> ```typescript
+> import { init, PromptGuard } from 'promptguard-sdk';
+> ```
+
+Get a free API key at [app.promptguard.co](https://app.promptguard.co).
+
+> **The SDK reads `PROMPTGUARD_API_KEY` from the environment; it does not auto-load `.env`.** Use [dotenv](https://www.npmjs.com/package/dotenv) (call `import 'dotenv/config'` first) if you keep secrets in a `.env` file.
+
+> **PromptGuard fails open by default** — if the Guard API is unavailable, calls proceed *unscanned* so your app stays up. Set `failOpen: false` to block (fail closed) on a Guard outage instead.
+
+> **Module format:** the package currently ships **CommonJS** (`require`) builds. It works in ESM projects via Node's CJS interop (`import { init } from 'promptguard-sdk'` transpiles to a `require`), and in plain CommonJS via `const { init } = require('promptguard-sdk')`.
+>
+> **Running a native-ESM app?** Auto-instrumentation (`init()`) may not cover your LLM calls — see [Limitations: ESM apps](#limitations) before relying on enforce mode.
+
 ## Option 1: Auto-Instrumentation (Recommended)
 
 One line secures **every** LLM call in your application - no matter which framework you use.
 
 ```typescript
+// All imports first — ES module imports are hoisted and always run before
+// any other statement, regardless of their position in the file.
 import { init } from 'promptguard-sdk';
+import OpenAI from 'openai';
 
-// Call once at startup - before any LLM SDK usage.
-init({ apiKey: 'pg_xxx' });
+// init() runs as the first executed statement and patches the SDK prototypes.
+// Patching works regardless of import order, so you don't need to worry about
+// importing the LLM SDK "after" calling init().
+init({ apiKey: 'pg_live_xxx' });
 
-// Everything below is now secured transparently.
-import OpenAI from 'openai';
 const client = new OpenAI();
 
 // This call is automatically scanned by PromptGuard.
@@ -34,35 +52,51 @@ const response = await client.chat.completions.create({
 });
 ```
 
+> `init()` is intentionally quiet on success (SDK logging defaults to `warn`). To confirm which provider SDKs are actually being protected, read `getAppliedPatches()` — the source of truth for what got patched:
+> ```typescript
+> import { init, getAppliedPatches } from 'promptguard-sdk';
+> init({ apiKey: 'pg_live_xxx' });
+> console.log('PromptGuard protecting:', getAppliedPatches()); // e.g. ['openai']
+> ```
+> If this list is empty, nothing is being scanned (see [Limitations: ESM apps](#limitations)). Set `logLevel: 'info'` on `init()` to also emit a one-line confirmation banner.
+
 ### Supported SDKs
 
 Auto-instrumentation patches the `create` / `generateContent` / `chat` / `send` methods on:
 
 | SDK | npm Package | What Gets Patched |
 |-----|------------|-------------------|
-| OpenAI | `openai` | `chat.completions.create` |
+| OpenAI | `openai` | `chat.completions.create`, `responses.create` (string and message-item `input` forms) |
 | Anthropic | `@anthropic-ai/sdk` | `messages.create` |
 | Google Generative AI | `@google/generative-ai` | `generateContent` |
 | Cohere | `cohere-ai` | `Client.chat` / `ClientV2.chat` |
-| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | `BedrockRuntimeClient.send` (InvokeModel, Converse) |
+| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | `BedrockRuntimeClient.send` (InvokeModel, InvokeModelWithResponseStream, Converse, ConverseStream) |
 
 Any framework built on these SDKs is automatically covered: **LangChain.js**, **Vercel AI SDK**, **AutoGen**, **Semantic Kernel**, and more.
 
+> Patches attach to the modules resolved via CommonJS `require()`. If `init()` finds **no** patchable SDK it logs a warning (nothing would be scanned). You can also verify at runtime with `getAppliedPatches()`:
+> ```typescript
+> import { init, getAppliedPatches } from 'promptguard-sdk';
+> init({ apiKey: 'pg_live_xxx' });
+> console.log(getAppliedPatches()); // e.g. ['openai', 'anthropic']
+> ```
+> Native-ESM apps: see [Limitations: ESM apps](#limitations).
+
 ### Modes
 
 ```typescript
 // Enforce mode (default) - blocks policy violations.
-init({ apiKey: 'pg_xxx', mode: 'enforce' });
+init({ apiKey: 'pg_live_xxx', mode: 'enforce' });
 
 // Monitor mode - logs threats but never blocks. Good for shadow deployment.
-init({ apiKey: 'pg_xxx', mode: 'monitor' });
+init({ apiKey: 'pg_live_xxx', mode: 'monitor' });
 ```
 
 ### Options
 
 ```typescript
 init({
-  apiKey: 'pg_xxx',           // or set PROMPTGUARD_API_KEY env var
+  apiKey: 'pg_live_xxx',           // or set PROMPTGUARD_API_KEY env var
   baseUrl: 'https://...',     // or set PROMPTGUARD_BASE_URL env var
   mode: 'enforce',            // 'enforce' | 'monitor'
   failOpen: true,             // allow calls when Guard API is unreachable
@@ -87,7 +121,7 @@ Route LLM traffic through PromptGuard. Just swap your base URL.
 ```typescript
 import { PromptGuard } from 'promptguard-sdk';
 
-const pg = new PromptGuard({ apiKey: 'pg_xxx' });
+const pg = new PromptGuard({ apiKey: 'pg_live_xxx' });
 
 // Use exactly like the OpenAI client.
 const response = await pg.chat.completions.create({
@@ -123,7 +157,7 @@ import { PromptGuardCallbackHandler } from 'promptguard-sdk/integrations/langcha
 import { ChatOpenAI } from '@langchain/openai';
 
 const handler = new PromptGuardCallbackHandler({
-  apiKey: 'pg_xxx',
+  apiKey: 'pg_live_xxx',
   mode: 'enforce',
   scanResponses: true,
 });
@@ -143,6 +177,10 @@ const result = await chain.invoke(
 
 The callback handler provides rich context to PromptGuard - chain names, tool calls, agent steps - for more precise threat detection.
 
+> **Redact decisions block in enforce mode:** LangChain callbacks observe calls but cannot rewrite the inputs of the in-flight LLM call, so a `redact` decision cannot be honored — in enforce mode it is escalated to a block (`PromptGuardBlockedError`) rather than silently sending the content the Guard API asked to redact. Use auto-instrumentation or explicit `GuardClient.scan()` calls if you need actual redaction.
+>
+> `scanResponses` defaults to `false` (consistent with `init()` and the Vercel AI middleware) — pass `scanResponses: true` to opt in to output scanning.
+
 ### Vercel AI SDK
 
 ```typescript
@@ -153,7 +191,7 @@ import { promptGuardMiddleware } from 'promptguard-sdk/integrations/vercel-ai';
 const model = wrapLanguageModel({
   model: openai('gpt-5-nano'),
   middleware: promptGuardMiddleware({
-    apiKey: 'pg_xxx',
+    apiKey: 'pg_live_xxx',
     mode: 'enforce',
     scanResponses: true,
   }),
@@ -172,13 +210,12 @@ Use the Guard client directly for maximum control:
 ```typescript
 import { GuardClient } from 'promptguard-sdk';
 
-const guard = new GuardClient({ apiKey: 'pg_xxx' });
+const guard = new GuardClient({ apiKey: 'pg_live_xxx' });
 
-// Scan before sending to LLM
+// Scan before sending to LLM (options-object form, preferred)
 const decision = await guard.scan(
   [{ role: 'user', content: userInput }],
-  'input',
-  'gpt-5-nano',
+  { direction: 'input', model: 'gpt-5-nano' },
 );
 
 if (decision.blocked) {
@@ -191,23 +228,44 @@ if (decision.blocked) {
 // Scan LLM response
 const outputDecision = await guard.scan(
   [{ role: 'assistant', content: llmOutput }],
-  'output',
+  { direction: 'output' },
 );
+
+// The positional form still works for back-compat:
+// await guard.scan(messages, 'input', 'gpt-5-nano');
 ```
 
 ## Retry Logic
 
-Both `PromptGuard` and `GuardClient` support configurable retry behavior for transient failures:
+Both the proxy client (`PromptGuard`) and the Guard client (`GuardClient`) support configurable retry behavior for transient failures:
 
 ```typescript
+// Proxy client
 const pg = new PromptGuard({
-  apiKey: 'pg_xxx',
-  maxRetries: 3,      // Number of retry attempts (default: 2)
-  retryDelay: 500,     // Base delay in ms between retries (default: 250)
+  apiKey: 'pg_live_xxx',
+  maxRetries: 3,      // Number of retry attempts (default: 3)
+  retryDelay: 500,     // Base delay in ms between retries (default: 1000)
 });
+
+// Guard client (standalone scanning)
+const guard = new GuardClient({
+  apiKey: 'pg_live_xxx',
+  maxRetries: 3,      // default: 3
+  retryDelay: 500,     // default: 1000
+});
+```
+
+Because auto-instrumentation (`init()`) and the framework integrations all scan through `GuardClient`, they retry transient Guard API failures too — pass `maxRetries` / `retryDelay` to `init()`, `PromptGuardCallbackHandler`, or `promptGuardMiddleware`:
+
+```typescript
+init({ apiKey: 'pg_live_xxx', maxRetries: 3, retryDelay: 500 });
 ```
 
-Retries use exponential backoff starting from `retryDelay`. Only transient errors (network timeouts, 5xx responses) are retried; client errors (4xx) fail immediately.
+Retries use exponential backoff starting from `retryDelay`, with jitter so concurrent clients don't retry in lockstep. A server-provided `Retry-After` header is honored but clamped to 60 seconds. Only transient errors (network timeouts, 429/5xx responses) are retried; client errors (4xx) fail immediately.
+
+> **Enforcement is unchanged by retries.** Retrying only affects *transient* Guard failures (network errors, 429/5xx). A real `block` / `redact` decision is terminal and is never retried, and once retries are exhausted a `GuardApiError` is raised so your existing `failOpen` policy governs — exactly as it would with `maxRetries: 0`. Retries never turn a would-be error into an allow.
+
+> **Idempotency caveat:** all requests — including `POST`s — are retried on transient failure. If a request reached the server but the response was lost, the retry re-submits it. Chat/completion/scan calls are safe to re-submit, but each attempt may bill separately; set `maxRetries: 0` if you need strict at-most-once semantics.
 
 ## Embeddings
 
@@ -250,18 +308,18 @@ if (!validation.allowed) {
 ## Red Team Testing
 
 ```typescript
-const pg = new PromptGuard({ apiKey: 'pg_xxx' });
+const pg = new PromptGuard({ apiKey: 'pg_live_xxx' });
 
 // Run the autonomous red team agent (LLM-powered mutation)
 const report = await pg.redteam.runAutonomous({
   budget: 200,
-  target_preset: 'support_bot:strict',
+  targetPreset: 'support_bot:strict', // snake_case `target_preset` also accepted
 });
-console.log(`Grade: ${report.grade}, Bypass rate: ${(report.bypass_rate * 100).toFixed(0)}%`);
+console.log(`Grade: ${report.grade}, Bypass rate: ${(report.bypassRate * 100).toFixed(0)}%`);
 
 // Get Attack Intelligence stats
 const stats = await pg.redteam.intelligenceStats();
-console.log(`Total patterns: ${stats.total_patterns}`);
+console.log(`Total patterns: ${stats.totalPatterns}`);
 ```
 
 ## Configuration
@@ -274,6 +332,35 @@ console.log(`Total patterns: ${stats.total_patterns}`);
 | `failOpen` | - | `true` | Allow calls when Guard API is unreachable |
 | `scanResponses` | - | `false` | Also scan LLM responses |
 | `timeout` | - | `10000` | HTTP timeout in milliseconds |
+| `logLevel` | - | `"warn"` | SDK log verbosity: `"debug"`, `"info"`, `"warn"`, `"error"`, `"silent"` |
+| `silent` | - | `false` | Shorthand for `logLevel: "silent"` |
+
+> The proxy client (`PromptGuard`) talks to the `/api/v1/proxy` endpoints. If you set `baseUrl` / `PROMPTGUARD_BASE_URL` to `.../api/v1` (without `/proxy`), the SDK appends the `/proxy` suffix for you, so requests still land on the proxy.
+>
+> **Security:** the SDK sends your API key (and, in proxy mode, your prompt content) to whatever `PROMPTGUARD_BASE_URL` points at. Self-hosting is supported, so only point it at a host you trust.
+>
+> **Logging is process-global:** `logLevel` / `silent` set a single shared log level for the whole SDK. If several integrations or `init()` calls pass different values, the most recently constructed one wins. Use `setLogLevel()` directly for fine-grained control.
+
+## Limitations
+
+### ESM apps (auto-instrumentation)
+
+Auto-instrumentation (`init()`) patches the provider modules that Node resolves via **CommonJS `require()`**. If your application runs as **native ESM** (`"type": "module"` in package.json, or `.mjs` files) and a provider ships separate ESM builds, the module instances your code `import`s can be *different objects* from the ones the SDK patched — the **dual-package hazard**. In that case your LLM calls bypass the patches entirely and **enforce mode silently protects nothing**.
+
+What to do:
+
+- **Verify at runtime** with `getAppliedPatches()` after `init()` — and note that a patch being listed proves the CJS build was patched, not that your ESM imports go through it. `init()` also logs a warning when it applies zero patches.
+- **Prefer the ESM-safe APIs**, which don't rely on module patching:
+  - LangChain: `PromptGuardCallbackHandler` (`promptguard-sdk/integrations/langchain`)
+  - Vercel AI SDK: `promptGuardMiddleware` (`promptguard-sdk/integrations/vercel-ai`)
+  - Any framework: explicit `GuardClient.scan()` calls around your LLM invocations
+- Transpiled-to-CJS TypeScript apps (the common `tsc`/`ts-node` default) are **not** affected — their `import`s compile to `require()` and hit the patched modules.
+
+### Other limitations
+
+- **Streaming responses are not output-scanned.** With auto-instrumentation and `scanResponses: true`, streaming calls (`stream: true`, Bedrock `ConverseStreamCommand`, etc.) skip the output scan — the stream is consumed incrementally by your code and cannot be buffered without breaking stream semantics. Input scanning still applies. A `debug`-level log is emitted when the output scan is skipped. The same applies to the Vercel AI SDK middleware: `streamText()` outputs are not scanned (`wrapStream` logs the skip); `generateText()` outputs are.
+- **OpenAI `APIPromise` helpers are not preserved by auto-instrumentation.** Patched methods return a plain `Promise`, so `.withResponse()` / `.asResponse()` on `client.chat.completions.create(...)` are unavailable while `init()` is active. `await` the call and use the plain result instead.
+- **Proxy client streaming:** `pg.chat.completions.create({ stream: true })` is rejected with a clear error — streaming is not yet supported by the proxy client.
 
 ## Error Handling
 
@@ -314,6 +401,8 @@ import type {
 } from 'promptguard-sdk';
 ```
 
+> **Response fields are camelCase — with one deliberate exception.** The SDK's normalized response objects (the `security`, `redteam`, `agent`, `scrape`, and `guard` namespaces) use camelCase field names (e.g. `report.bypassRate`, `stats.totalPatterns`, `validation.riskScore`, `result.threatsDetected`) regardless of the snake_case wire format — consistent with `GuardDecision` and `SecurityScanResult`. The **OpenAI-compatible** responses (`chat.completions`, `completions`, `embeddings`, i.e. `ChatCompletionResponse`) are the exception: they intentionally preserve OpenAI's snake_case shape (`choices[].finish_reason`, `usage.prompt_tokens`, …) so they stay drop-in compatible with the `openai` client. Request options are camelCase throughout (`maxTokens`, `targetPreset`), including `GuardContext` (`chainName`, `agentId`, `sessionId`, `toolCalls`).
+
 ## Links
 
 - [Documentation](https://docs.promptguard.co)

package/dist/auto.d.ts

@@ -9,7 +9,7 @@
  * ```ts
  * import { init } from 'promptguard-sdk/auto';
  *
- * init({ apiKey: 'pg_xxx' });
+ * init({ apiKey: 'pg_live_xxx' });
  *
  * // Everything below is now secured transparently.
  * import OpenAI from 'openai';
@@ -18,6 +18,7 @@
  * ```
  */
 import { GuardClient } from "./guard";
+import { type LogLevel } from "./logger";
 export interface InitOptions {
     apiKey?: string;
     baseUrl?: string;
@@ -29,11 +30,68 @@ export interface InitOptions {
     scanResponses?: boolean;
     /** HTTP timeout in ms for Guard API calls (default: `10000`). */
     timeout?: number;
+    /**
+     * Retry attempts for transient Guard API failures (network errors and
+     * 429/5xx responses) before the `failOpen` policy governs. Default: `3`.
+     * Retries never change the eventual decision — see {@link GuardClientConfig}.
+     */
+    maxRetries?: number;
+    /** Base delay in ms between Guard API retries (exponential backoff). Default: `1000`. */
+    retryDelay?: number;
+    /**
+     * SDK log verbosity (default: `"warn"`). Set to `"silent"` to suppress all
+     * SDK logging, or `"info"`/`"debug"` for the init banner and more detail.
+     * NOTE: this sets the **process-global** SDK log level (shared with the
+     * framework integrations); the most recent setter wins.
+     */
+    logLevel?: LogLevel;
+    /** Convenience shorthand for `logLevel: "silent"`. */
+    silent?: boolean;
 }
+/**
+ * Initialise PromptGuard auto-instrumentation.
+ *
+ * Patches the provider SDKs (`openai`, `@anthropic-ai/sdk`,
+ * `@google/generative-ai`, `cohere-ai`, `@aws-sdk/client-bedrock-runtime`)
+ * so every LLM call they make is scanned by the Guard API.
+ *
+ * **Limitation — ESM apps (dual-package hazard):** patches are applied to the
+ * module instances resolved via CommonJS `require()`. If your application runs
+ * as native ESM (`"type": "module"` / `.mjs`) and the provider ships separate
+ * ESM builds, your `import`ed module instances can be *different objects* from
+ * the patched CJS ones — in that case auto-instrumentation silently protects
+ * nothing. Use {@link getAppliedPatches} as a runtime canary to verify the
+ * providers you use were actually patched, and prefer the ESM-safe
+ * alternatives: the LangChain callback handler
+ * (`promptguard-sdk/integrations/langchain`), the Vercel AI SDK middleware
+ * (`promptguard-sdk/integrations/vercel-ai`), or explicit `GuardClient.scan()`
+ * calls. See README "Limitations: ESM apps".
+ *
+ * When zero patches could be applied, a warning is logged so a
+ * misconfiguration never fails silently.
+ */
 export declare function init(options?: InitOptions): void;
 export declare function shutdown(): void;
 export declare function getGuardClient(): GuardClient | null;
 export declare function getMode(): "enforce" | "monitor";
 export declare function isFailOpen(): boolean;
 export declare function shouldScanResponses(): boolean;
+/**
+ * Runtime canary: the names of the auto-instrumentation patches that were
+ * actually applied by {@link init} (e.g. `["openai", "anthropic"]`).
+ *
+ * Because patches attach to the CJS-resolved provider modules, an ESM app can
+ * call `init()` successfully and still be unprotected (see the dual-package
+ * hazard note on {@link init}). Assert on this at startup when you rely on
+ * enforce mode:
+ *
+ * @example
+ * ```ts
+ * init({ apiKey: "pg_live_xxx" });
+ * if (!getAppliedPatches().includes("openai")) {
+ *   throw new Error("PromptGuard did not patch the openai SDK");
+ * }
+ * ```
+ */
+export declare function getAppliedPatches(): string[];
 //# sourceMappingURL=auto.d.ts.map

package/dist/auto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAkBrC,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kDAAkD;IAClD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CAuBpD;AAED,wBAAgB,QAAQ,IAAI,IAAI,CAU/B;AAMD,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAEnD;AAED,wBAAgB,OAAO,IAAI,SAAS,GAAG,SAAS,CAE/C;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,KAAK,QAAQ,EAAuB,MAAM,UAAU,CAAA;AAkB7D,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kDAAkD;IAClD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CAqCpD;AAED,wBAAgB,QAAQ,IAAI,IAAI,CAU/B;AAMD,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAEnD;AAED,wBAAgB,OAAO,IAAI,SAAS,GAAG,SAAS,CAE/C;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C"}

package/dist/auto.js

@@ -10,7 +10,7 @@
  * ```ts
  * import { init } from 'promptguard-sdk/auto';
  *
- * init({ apiKey: 'pg_xxx' });
+ * init({ apiKey: 'pg_live_xxx' });
  *
  * // Everything below is now secured transparently.
  * import OpenAI from 'openai';
@@ -25,7 +25,9 @@ exports.getGuardClient = getGuardClient;
 exports.getMode = getMode;
 exports.isFailOpen = isFailOpen;
 exports.shouldScanResponses = shouldScanResponses;
+exports.getAppliedPatches = getAppliedPatches;
 const guard_1 = require("./guard");
+const logger_1 = require("./logger");
 const resolve_1 = require("./resolve");
 // ---------------------------------------------------------------------------
 // Global state
@@ -35,22 +37,58 @@ let mode = "enforce";
 let failOpen = true;
 let scanResponses = false;
 const appliedPatches = [];
+/**
+ * Initialise PromptGuard auto-instrumentation.
+ *
+ * Patches the provider SDKs (`openai`, `@anthropic-ai/sdk`,
+ * `@google/generative-ai`, `cohere-ai`, `@aws-sdk/client-bedrock-runtime`)
+ * so every LLM call they make is scanned by the Guard API.
+ *
+ * **Limitation — ESM apps (dual-package hazard):** patches are applied to the
+ * module instances resolved via CommonJS `require()`. If your application runs
+ * as native ESM (`"type": "module"` / `.mjs`) and the provider ships separate
+ * ESM builds, your `import`ed module instances can be *different objects* from
+ * the patched CJS ones — in that case auto-instrumentation silently protects
+ * nothing. Use {@link getAppliedPatches} as a runtime canary to verify the
+ * providers you use were actually patched, and prefer the ESM-safe
+ * alternatives: the LangChain callback handler
+ * (`promptguard-sdk/integrations/langchain`), the Vercel AI SDK middleware
+ * (`promptguard-sdk/integrations/vercel-ai`), or explicit `GuardClient.scan()`
+ * calls. See README "Limitations: ESM apps".
+ *
+ * When zero patches could be applied, a warning is logged so a
+ * misconfiguration never fails silently.
+ */
 function init(options = {}) {
+    if (options.silent) {
+        (0, logger_1.setLogLevel)("silent");
+    }
+    else if (options.logLevel) {
+        (0, logger_1.setLogLevel)(options.logLevel);
+    }
     const { apiKey, baseUrl } = (0, resolve_1.resolveCredentials)(options.apiKey, options.baseUrl);
     const resolvedMode = options.mode ?? "enforce";
     if (resolvedMode !== "enforce" && resolvedMode !== "monitor") {
-        throw new Error("mode must be 'enforce' or 'monitor'");
+        throw new Error(`mode must be 'enforce' or 'monitor', got '${resolvedMode}'`);
     }
     guardClient = new guard_1.GuardClient({
         apiKey,
         baseUrl,
         timeout: options.timeout ?? 10000,
+        maxRetries: options.maxRetries,
+        retryDelay: options.retryDelay,
     });
     mode = resolvedMode;
     failOpen = options.failOpen ?? true;
     scanResponses = options.scanResponses ?? false;
     applyPatches();
-    console.log(`[promptguard] auto-instrumentation initialised (mode=${mode}, fail_open=${failOpen})`);
+    // One-line confirmation of which provider SDKs are actually protected.
+    // Suppressed by default (info level); set logLevel: "info" to see it, or
+    // read the same list programmatically via getAppliedPatches(). When ZERO
+    // patches applied, applyPatches() already logged a warn (visible by default).
+    const protecting = getAppliedPatches();
+    logger_1.logger.info(`auto-instrumentation initialised (mode=${mode}, fail_open=${failOpen}) — ` +
+        `protecting: ${protecting.length ? protecting.join(", ") : "none"}`);
 }
 function shutdown() {
     for (const patch of appliedPatches) {
@@ -79,6 +117,26 @@ function isFailOpen() {
 function shouldScanResponses() {
     return scanResponses;
 }
+/**
+ * Runtime canary: the names of the auto-instrumentation patches that were
+ * actually applied by {@link init} (e.g. `["openai", "anthropic"]`).
+ *
+ * Because patches attach to the CJS-resolved provider modules, an ESM app can
+ * call `init()` successfully and still be unprotected (see the dual-package
+ * hazard note on {@link init}). Assert on this at startup when you rely on
+ * enforce mode:
+ *
+ * @example
+ * ```ts
+ * init({ apiKey: "pg_live_xxx" });
+ * if (!getAppliedPatches().includes("openai")) {
+ *   throw new Error("PromptGuard did not patch the openai SDK");
+ * }
+ * ```
+ */
+function getAppliedPatches() {
+    return appliedPatches.map((p) => p.name);
+}
 // ---------------------------------------------------------------------------
 // Patch orchestration
 // ---------------------------------------------------------------------------
@@ -94,12 +152,32 @@ function applyPatches() {
         try {
             const patchModule = require(mod.path);
             if (patchModule.apply()) {
-                appliedPatches.push({ name: mod.name, revert: patchModule.revert });
+                // apply() is idempotent per patch module, so a second init() without
+                // shutdown() reports "already patched" success. Skip the push when
+                // the patch is already tracked — a duplicate entry would make the
+                // getAppliedPatches() canary lie and call revert() twice on
+                // shutdown().
+                if (!appliedPatches.some((p) => p.name === mod.name)) {
+                    appliedPatches.push({ name: mod.name, revert: patchModule.revert });
+                }
+            }
+            else {
+                logger_1.logger.debug(`${mod.name} patch not applied: SDK not resolvable via require() ` +
+                    `(not installed, or only reachable as ESM)`);
             }
         }
-        catch {
-            // SDK not installed or incompatible - skip silently
+        catch (err) {
+            logger_1.logger.debug(`${mod.name} patch not applied: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    if (appliedPatches.length === 0) {
+        logger_1.logger.warn("init() applied ZERO auto-instrumentation patches — no supported LLM SDK was " +
+            "resolvable via CommonJS require(), so NO calls are being scanned. If your app " +
+            'runs as native ESM ("type": "module" / .mjs), auto-instrumentation cannot see ' +
+            "the module instances your code imports (dual-package hazard). Use the ESM-safe " +
+            "integrations instead: the LangChain callback handler, the Vercel AI SDK " +
+            "middleware, or explicit GuardClient.scan() calls. " +
+            'See README "Limitations: ESM apps". Set logLevel: "debug" for per-SDK reasons.');
+    }
 }
 //# sourceMappingURL=auto.js.map

package/dist/auto.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto.js","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auto.js","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AAyEH,oBAqCC;AAED,4BAUC;AAMD,wCAEC;AAED,0BAEC;AAED,gCAEC;AAED,kDAEC;AAmBD,8CAEC;AAjKD,mCAAqC;AACrC,qCAA6D;AAC7D,uCAA8C;AAE9C,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,IAAI,WAAW,GAAuB,IAAI,CAAA;AAC1C,IAAI,IAAI,GAA0B,SAAS,CAAA;AAC3C,IAAI,QAAQ,GAAG,IAAI,CAAA;AACnB,IAAI,aAAa,GAAG,KAAK,CAAA;AAEzB,MAAM,cAAc,GAAgD,EAAE,CAAA;AAoCtE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,IAAI,CAAC,UAAuB,EAAE;IAC5C,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,IAAA,oBAAW,EAAC,QAAQ,CAAC,CAAA;IACvB,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC5B,IAAA,oBAAW,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC/B,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAA,4BAAkB,EAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAE/E,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAAA;IAC9C,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,6CAA6C,YAAY,GAAG,CAAC,CAAA;IAC/E,CAAC;IAED,WAAW,GAAG,IAAI,mBAAW,CAAC;QAC5B,MAAM;QACN,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAM;QAClC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC,CAAA;IAEF,IAAI,GAAG,YAAY,CAAA;IACnB,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;IACnC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,KAAK,CAAA;IAE9C,YAAY,EAAE,CAAA;IAEd,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,8EAA8E;IAC9E,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAA;IACtC,eAAM,CAAC,IAAI,CACT,0CAA0C,IAAI,eAAe,QAAQ,MAAM;QACzE,eAAe,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CACtE,CAAA;AACH,CAAC;AAED,SAAgB,QAAQ;IACtB,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,KAAK,CAAC,MAAM,EAAE,CAAA;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,cAAc,CAAC,MAAM,GAAG,CAAC,CAAA;IACzB,WAAW,GAAG,IAAI,CAAA;AACpB,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E,SAAgB,cAAc;IAC5B,OAAO,WAAW,CAAA;AACpB,CAAC;AAED,SAAgB,OAAO;IACrB,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAgB,UAAU;IACxB,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,SAAgB,mBAAmB;IACjC,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,iBAAiB;IAC/B,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,SAAS,YAAY;IACnB,MAAM,YAAY,GAAG;QACnB,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE;QAC5C,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,qBAAqB,EAAE;QAClD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE;QAC5C,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE;QAC5C,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,mBAAmB,EAAE;KAC/C,CAAA;IAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAGnC,CAAA;YACD,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;gBACxB,qEAAqE;gBACrE,mEAAmE;gBACnE,kEAAkE;gBAClE,4DAA4D;gBAC5D,cAAc;gBACd,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrD,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;gBACrE,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,eAAM,CAAC,KAAK,CACV,GAAG,GAAG,CAAC,IAAI,uDAAuD;oBAChE,2CAA2C,CAC9C,CAAA;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,eAAM,CAAC,KAAK,CACV,GAAG,GAAG,CAAC,IAAI,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACrF,CAAA;QACH,CAAC;IACH,CAAC;IAED,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,eAAM,CAAC,IAAI,CACT,8EAA8E;YAC5E,gFAAgF;YAChF,gFAAgF;YAChF,iFAAiF;YACjF,0EAA0E;YAC1E,oDAAoD;YACpD,gFAAgF,CACnF,CAAA;IACH,CAAC;AACH,CAAC"}