promptguard-sdk 1.9.0 → 1.10.1

package/README.md

@@ -25,6 +25,8 @@ Get a free API key at [app.promptguard.co](https://app.promptguard.co).
 > **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)
 
@@ -50,20 +52,36 @@ 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
@@ -159,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
@@ -215,17 +237,35 @@ const outputDecision = await guard.scan(
 
 ## 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_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
+});
 ```
 
-Retries use exponential backoff starting from `retryDelay`. Only transient errors (network timeouts, 5xx responses) are retried; client errors (4xx) fail immediately.
+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`, 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
 
@@ -275,11 +315,11 @@ const report = await pg.redteam.runAutonomous({
   budget: 200,
   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
@@ -298,6 +338,29 @@ console.log(`Total patterns: ${stats.total_patterns}`);
 > 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
 
@@ -338,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

@@ -30,18 +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;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;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CA4BpD;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

@@ -25,6 +25,7 @@ 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");
@@ -36,6 +37,28 @@ 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");
@@ -52,13 +75,20 @@ function init(options = {}) {
         apiKey,
         baseUrl,
         timeout: options.timeout ?? 10000,
+        maxRetries: options.maxRetries,
+        retryDelay: options.retryDelay,
     });
     mode = resolvedMode;
     failOpen = options.failOpen ?? true;
     scanResponses = options.scanResponses ?? false;
     applyPatches();
-    // Suppressed by default (info level). Set logLevel: "info" to see this.
-    logger_1.logger.info(`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) {
@@ -87,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
 // ---------------------------------------------------------------------------
@@ -102,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":"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"}

package/dist/client.d.ts

@@ -2,26 +2,47 @@
  * PromptGuard proxy client — OpenAI-compatible API with built-in
  * security scanning, retry logic, and namespace helpers.
  */
-interface PromptGuardConfig {
+export interface PromptGuardConfig {
     apiKey: string;
+    /**
+     * API base URL. Defaults to the public PromptGuard proxy
+     * (`https://api.promptguard.co/api/v1/proxy`) or `PROMPTGUARD_BASE_URL`.
+     * The `/proxy` suffix is appended automatically when missing.
+     */
     baseUrl?: string;
+    /** HTTP timeout in milliseconds for each request attempt. Default: `30000`. */
     timeout?: number;
+    /**
+     * Number of retry attempts for transient failures (network errors and
+     * 429/5xx responses). Default: `3`. Set to `0` for strict at-most-once
+     * semantics. Negative values are clamped to `0`.
+     */
     maxRetries?: number;
+    /** Base delay in ms between retries (exponential backoff). Default: `1000`. */
     retryDelay?: number;
 }
-interface Message {
-    role: "system" | "user" | "assistant";
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool" | "function";
     content: string;
 }
-interface ChatCompletionRequest {
+export interface ChatCompletionRequest {
     model: string;
     messages: Message[];
     temperature?: number;
+    /** Maximum tokens to generate. Serialized to the wire as `max_tokens`. */
     maxTokens?: number;
-    stream?: boolean;
+    /**
+     * OpenAI-compatible escape hatch: any additional keys (e.g. `top_p`,
+     * `frequency_penalty`, `stop`, `tools`) are forwarded verbatim to the proxy.
+     * Because these keys are not type-checked, a misspelled parameter is silently
+     * passed through rather than flagged at compile time — double-check the
+     * spelling of options not listed above. (`stream: true` is the one key
+     * rejected: the client parses a single JSON response body, so it throws at
+     * runtime instead of forwarding.)
+     */
     [key: string]: unknown;
 }
-interface ChatCompletionResponse {
+export interface ChatCompletionResponse {
     id: string;
     object: string;
     created: number;
@@ -37,14 +58,22 @@ interface ChatCompletionResponse {
         total_tokens: number;
     };
 }
-interface CompletionRequest {
+export interface CompletionRequest {
     model: string;
     prompt: string;
     temperature?: number;
+    /** Maximum tokens to generate. Serialized to the wire as `max_tokens`. */
     maxTokens?: number;
+    /**
+     * OpenAI-compatible escape hatch: any additional keys are forwarded verbatim
+     * to the proxy. Because these keys are not type-checked, a misspelled
+     * parameter is silently passed through rather than flagged at compile time.
+     * (`stream: true` is rejected at runtime — the client parses a single JSON
+     * response body.)
+     */
     [key: string]: unknown;
 }
-interface CompletionResponse {
+export interface CompletionResponse {
     id: string;
     object: string;
     created: number;
@@ -60,12 +89,18 @@ interface CompletionResponse {
         total_tokens: number;
     };
 }
-interface EmbeddingRequest {
+export interface EmbeddingRequest {
     model: string;
     input: string | string[];
+    /**
+     * OpenAI-compatible escape hatch: any additional keys (e.g. `dimensions`,
+     * `encoding_format`, `user`) are forwarded verbatim to the proxy. Because
+     * these keys are not type-checked, a misspelled parameter is silently passed
+     * through rather than flagged at compile time.
+     */
     [key: string]: unknown;
 }
-interface EmbeddingResponse {
+export interface EmbeddingResponse {
     object: string;
     data: Array<{
         object: string;
@@ -78,51 +113,59 @@ interface EmbeddingResponse {
         total_tokens: number;
     };
 }
-interface SecurityScanResult {
+export interface SecurityScanResult {
     blocked: boolean;
     decision: "allow" | "block" | "redact";
     reason?: string;
     threatType?: string;
     confidence?: number;
 }
-interface RedactResult {
+export interface RedactResult {
     original: string;
     redacted: string;
     piiFound: string[];
 }
-interface ScrapeResult {
+export interface ScrapeResult {
     url: string;
     status: "safe" | "blocked";
     content: string;
-    threats_detected: string[];
+    /** Normalized from the wire field `threats_detected`. */
+    threatsDetected: string[];
     message?: string;
 }
-interface ToolValidationResult {
+export interface ToolValidationResult {
     allowed: boolean;
-    risk_score: number;
-    risk_level: string;
+    /** Normalized from the wire field `risk_score`. */
+    riskScore: number;
+    /** Normalized from the wire field `risk_level`. */
+    riskLevel: string;
     reason: string;
     warnings: string[];
-    blocked_reasons: string[];
+    /** Normalized from the wire field `blocked_reasons`. */
+    blockedReasons: string[];
 }
-interface RedTeamTestResult {
-    test_name: string;
+export interface RedTeamTestResult {
+    /** Normalized from the wire field `test_name`. */
+    testName: string;
     prompt: string;
     decision: string;
     reason: string;
-    threat_type?: string;
+    /** Normalized from the wire field `threat_type`. */
+    threatType?: string;
     confidence: number;
     blocked: boolean;
     details: Record<string, unknown>;
 }
-interface RedTeamSummary {
-    total_tests: number;
+export interface RedTeamSummary {
+    /** Normalized from the wire field `total_tests`. */
+    totalTests: number;
     blocked: number;
     allowed: number;
-    block_rate: number;
+    /** Normalized from the wire field `block_rate`. */
+    blockRate: number;
     results: RedTeamTestResult[];
 }
-interface AutonomousRedTeamRequest {
+export interface AutonomousRedTeamRequest {
     budget?: number;
     /** Target preset to attack (camelCase, preferred). */
     targetPreset?: string;
@@ -133,19 +176,26 @@ interface AutonomousRedTeamRequest {
     /** @deprecated snake_case alias for `enabledDetectors`; kept for back-compat. */
     enabled_detectors?: string[];
 }
-interface AutonomousRedTeamReport {
+export interface AutonomousRedTeamReport {
     grade: string;
-    bypass_rate: number;
-    total_attempts: number;
-    bypasses_found: number;
+    /** Normalized from the wire field `bypass_rate`. */
+    bypassRate: number;
+    /** Normalized from the wire field `total_attempts`. */
+    totalAttempts: number;
+    /** Normalized from the wire field `bypasses_found`. */
+    bypassesFound: number;
     bypasses: Array<Record<string, unknown>>;
     recommendations: string[];
 }
-interface IntelligenceStats {
-    total_patterns: number;
-    by_category: Record<string, number>;
-    by_severity: Record<string, number>;
-    recent_discoveries: number;
+export interface IntelligenceStats {
+    /** Normalized from the wire field `total_patterns`. */
+    totalPatterns: number;
+    /** Normalized from the wire field `by_category`. */
+    byCategory: Record<string, number>;
+    /** Normalized from the wire field `by_severity`. */
+    bySeverity: Record<string, number>;
+    /** Normalized from the wire field `recent_discoveries`. */
+    recentDiscoveries: number;
 }
 /**
  * Ensure the proxy base URL's path ends with `/proxy`.
@@ -159,6 +209,16 @@ interface IntelligenceStats {
  * correctly and the scheme/host/port/query/fragment are preserved exactly.
  */
 export declare function ensureProxySuffix(baseUrl: string): string;
+/**
+ * Join an endpoint path onto the configured base URL.
+ *
+ * Plain string concatenation broke base URLs carrying a query string or
+ * fragment (which `ensureProxySuffix` deliberately preserves): the endpoint
+ * path landed inside the query/fragment value and every namespaced call
+ * routed to the wrong endpoint. Splice the path onto the URL's pathname so
+ * the query/fragment stay where they belong.
+ */
+export declare function buildRequestUrl(baseUrl: string, path: string): string;
 declare class ChatCompletions {
     private client;
     constructor(client: PromptGuard);
@@ -193,7 +253,7 @@ declare class Scrape {
         timeout?: number;
     }): Promise<ScrapeResult>;
     batch(urls: string[], options?: Record<string, unknown>): Promise<{
-        job_id: string;
+        jobId: string;
     }>;
 }
 declare class Agent {
@@ -229,6 +289,12 @@ export declare class PromptGuard {
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
 }
 export declare class PromptGuardError extends Error {
+    /**
+     * Machine-readable error code. Server-forwarded codes pass through verbatim
+     * (their own casing). Codes minted by the SDK itself use lower_snake_case:
+     * `missing_api_key`, `streaming_not_supported`, `invalid_response_body`,
+     * `max_retries`, and the fallback `unknown`.
+     */
     code: string;
     statusCode: number;
     errorType?: string;
@@ -244,5 +310,5 @@ export declare class PromptGuardError extends Error {
         requestsLimit?: number;
     });
 }
-export default PromptGuard;
+export {};
 //# sourceMappingURL=client.d.ts.map