@lockllm/sdk 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,12 +1,153 @@
 # Changelog
 
-## [1.1.0] - 2026-01-16
+## [1.1.0] - 2026-02-18
+
+### Added
+
+#### Custom Content Policy Enforcement
+You can now enforce your own content rules on top of LockLLM's built-in security. Create custom policies in the [dashboard](https://www.lockllm.com/policies), and the SDK will automatically check prompts against them. When a policy is violated, you'll get a `PolicyViolationError` with the exact policy name, violated categories, and details.
+
+```typescript
+try {
+  await openai.chat.completions.create({ ... });
+} catch (error) {
+  if (error instanceof PolicyViolationError) {
+    console.log(error.violated_policies);
+    // [{ policy_name: "No competitor mentions", violated_categories: [...] }]
+  }
+}
+```
+
+#### AI Abuse Detection
+Protect your endpoints from automated misuse. When enabled, LockLLM detects bot-generated content, repetitive prompts, and resource exhaustion attacks. If abuse is detected, you'll get an `AbuseDetectedError` with confidence scores and detailed indicator breakdowns.
+
+```typescript
+const openai = createOpenAI({
+  apiKey: process.env.LOCKLLM_API_KEY,
+  proxyOptions: {
+    abuseAction: 'block'  // Opt-in: block abusive requests
+  }
+});
+```
+
+#### Credit Balance Awareness
+The SDK now returns a dedicated `InsufficientCreditsError` when your balance is too low for a request. The error includes your `current_balance` and the `estimated_cost`, so you can handle billing gracefully in your application.
+
+#### Scan Modes and Actions
+Control exactly what gets checked and what happens when threats are found:
+
+- **Scan modes** - Choose `normal` (core security only), `policy_only` (custom policies only), or `combined` (both)
+- **Actions per detection type** - Set `block` or `allow_with_warning` independently for core scans, custom policies, and abuse detection
+- **Abuse detection** is opt-in - disabled by default, enable it with `abuseAction`
+
+```typescript
+const result = await lockllm.scan(
+  { input: userPrompt, mode: 'combined', sensitivity: 'high' },
+  { scanAction: 'block', policyAction: 'allow_with_warning', abuseAction: 'block' }
+);
+```
+
+#### Proxy Options on All Wrappers
+All wrapper functions (`createOpenAI`, `createAnthropic`, `createGroq`, etc.) now accept a `proxyOptions` parameter so you can configure security behavior at initialization time instead of per-request:
+
+```typescript
+const openai = createOpenAI({
+  apiKey: process.env.LOCKLLM_API_KEY,
+  proxyOptions: {
+    scanMode: 'combined',
+    scanAction: 'block',
+    policyAction: 'block',
+    routeAction: 'auto',        // Enable intelligent routing
+    cacheResponse: true,         // Enable response caching
+    cacheTTL: 3600               // Cache for 1 hour
+  }
+});
+```
+
+#### Intelligent Routing
+Let LockLLM automatically select the best model for each request based on task type and complexity. Set `routeAction: 'auto'` to enable, or `routeAction: 'custom'` to use your own routing rules from the dashboard.
+
+#### Response Caching
+Reduce costs by caching identical LLM responses. Enabled by default in proxy mode - disable it with `cacheResponse: false` or customize the TTL with `cacheTTL`.
+
+#### Universal Proxy Mode
+Access 200+ models without configuring individual provider API keys using `getUniversalProxyURL()`. Uses LockLLM credits instead of BYOK.
+
+```typescript
+import { getUniversalProxyURL } from '@lockllm/sdk';
+const url = getUniversalProxyURL();
+// 'https://api.lockllm.com/v1/proxy/chat/completions'
+```
+
+#### Proxy Response Metadata
+New utilities to read detailed metadata from proxy responses - scan results, routing decisions, cache status, and credit usage:
+
+```typescript
+import { parseProxyMetadata } from '@lockllm/sdk';
+const metadata = parseProxyMetadata(response.headers);
+// metadata.safe, metadata.routing, metadata.cache_status, metadata.credits_deducted, etc.
+```
+
+#### Expanded Scan Response
+Scan responses now include richer data when using advanced features:
+- `policy_warnings` - Which custom policies were violated and why
+- `scan_warning` - Injection details when using `allow_with_warning`
+- `abuse_warnings` - Abuse indicators when abuse detection is enabled
+- `routing` - Task type, complexity score, and selected model when routing is enabled
+
+### Changed
+- The scan API is fully backward compatible - existing code works without changes. Internally, scan configuration is now sent via HTTP headers for better compatibility and caching behavior.
+
+### Notes
+- All new features are opt-in. Existing integrations continue to work without any changes.
+- Custom policies, abuse detection, and routing are configured in the [LockLLM dashboard](https://www.lockllm.com/dashboard).
+
+---
+
+## [1.0.1] - 2026-01-16
+
+### Changed
+
+#### Flexible SDK Installation
+- **Optional Provider SDKs**: Provider SDKs (OpenAI, Anthropic, Cohere, etc.) are no longer required dependencies. Install only what you need:
+  - Using OpenAI? Just install `openai` package
+  - Using Anthropic? Just install `@anthropic-ai/sdk` package
+  - Using Cohere? Just install `cohere-ai` package
+  - Mix and match any providers your application uses
+- **Smaller Bundle Sizes**: Your application only includes the provider SDKs you actually use, reducing package size and installation time
+- **Pay-As-You-Go Dependencies**: No need to install SDKs for providers you don't use
+
+### Benefits
+- Faster installation with fewer dependencies
+- Smaller `node_modules` folder
+- More control over your project dependencies
+- No unused packages taking up disk space
+
+### Migration Guide
+If you're upgrading from v1.0.0 and using provider wrappers, simply install the provider SDKs you need:
+
+```bash
+# For OpenAI (GPT models, DALL-E, etc.)
+npm install openai
+
+# For Anthropic (Claude models)
+npm install @anthropic-ai/sdk
+
+# For Cohere (Command, Embed models)
+npm install cohere-ai
+
+# Install only what you use!
+```
+
+The SDK will work out of the box once you install the provider packages you need.
+
+## [1.0.0] - 2026-01-16
 
 ### Added
 
 #### Universal Provider Support
-- **Generic Wrapper Factory**: Added `createClient()` function to create clients for any LLM provider using their official SDK
-- **OpenAI-Compatible Helper**: Added `createOpenAICompatible()` for easy integration with OpenAI-compatible providers
+- **Generic Wrapper Factory**: Added `createClient()` function to create clients for any of the 17 supported providers using their official SDK
+- **OpenAI-Compatible Helper**: Added `createOpenAICompatible()` for easy integration with the OpenAI-compatible providers (Groq, DeepSeek, Mistral, Perplexity, etc.)
 - **15 New Provider Wrappers**: Pre-configured factory functions for all remaining providers:
   - `createGroq()` - Groq (fast inference)
   - `createDeepSeek()` - DeepSeek (reasoning models)
@@ -30,7 +171,7 @@
 - **Type Export**: Added `ProviderName` type export for better TypeScript support
 
 #### Examples
-- **`examples/wrapper-generic.ts`**: Comprehensive example showing three ways to integrate with any provider
+- **`examples/wrapper-generic.ts`**: Comprehensive example showing three ways to integrate with any of the 17 supported providers
 - **`examples/wrapper-all-providers.ts`**: Complete example demonstrating all 17 providers
 
 #### Documentation
@@ -76,6 +217,6 @@ const client = new OpenAI({
 ```
 
 ### Notes
-- All 15+ providers are now fully supported with multiple integration options
+- All 17+ providers are now fully supported with multiple integration options
 - Zero breaking changes - existing code continues to work
 - Backward compatible with v1.0.0

package/README.md

@@ -10,7 +10,7 @@
 
 **All-in-One AI Security for LLM Applications**
 
-*Keep control of your AI. Detect prompt injection, jailbreaks, and adversarial attacks in real-time across 15+ providers with zero code changes.*
+*Keep control of your AI. Detect prompt injection, jailbreaks, and adversarial attacks in real-time across 17+ providers with zero code changes.*
 
 [Quick Start](#quick-start) · [Documentation](https://www.lockllm.com/docs) · [Examples](#examples) · [Benchmarks](https://www.lockllm.com) · [API Reference](#api-reference)
 
@@ -26,9 +26,9 @@ LockLLM is a state-of-the-art AI security ecosystem that detects prompt injectio
 
 - **Real-Time Security Scanning** - Analyze every LLM request before execution with minimal latency (<250ms)
 - **Advanced ML Detection** - Models trained on real-world attack patterns for prompt injection and jailbreaks
-- **15+ Provider Support** - Universal coverage across OpenAI, Anthropic, Azure, Bedrock, Gemini, and more
+- **17+ Provider Support** - Universal coverage across OpenAI, Anthropic, Azure, Bedrock, Gemini, and more
 - **Drop-in Integration** - Replace existing SDKs with zero code changes - just change one line
-- **Completely Free** - BYOK (Bring Your Own Key) model with unlimited usage and no rate limits
+- **Free Unlimited Scanning** - BYOK (Bring Your Own Key) model with free unlimited scanning
 - **Privacy by Default** - Your data is never stored, only scanned in-memory and discarded
 
 ## Why LockLLM
@@ -73,27 +73,53 @@ LockLLM provides production-ready AI security that integrates seamlessly into yo
 | **Evasion & Obfuscation Detection** | Catch sophisticated obfuscation including Unicode abuse, zero-width characters, and encoding-based attacks |
 | **Multi-Layer Context Analysis** | Analyze prompts across multiple context windows to detect attacks spanning conversation turns |
 | **Token-Level Threat Scoring** | Granular threat assessment identifying which specific parts of input contain malicious patterns |
-| **15+ Provider Support** | OpenAI, Anthropic, Gemini, Azure, Bedrock, Groq, DeepSeek, and more |
+| **17+ Provider Support** | OpenAI, Anthropic, Gemini, Azure, Bedrock, Groq, DeepSeek, and more |
 | **Drop-in Integration** | Replace `new OpenAI()` with `createOpenAI()` - no other changes needed |
 | **TypeScript Native** | Full type safety with comprehensive type definitions and IDE support |
 | **Streaming Compatible** | Works seamlessly with streaming responses from any provider |
 | **Configurable Sensitivity** | Adjust detection thresholds (low/medium/high) per use case |
-| **Custom Endpoints** | Support for self-hosted models, Azure resources, and private clouds |
+| **Custom Endpoints** | Configure custom URLs for any provider (self-hosted, Azure, private clouds) |
+| **Custom Content Policies** | Define your own content rules in the dashboard and enforce them automatically across all providers |
+| **AI Abuse Detection** | Detect bot-generated content, repetition attacks, and resource exhaustion from your end-users |
+| **Intelligent Routing** | Automatically select the optimal model for each request based on task type and complexity to save costs |
+| **Response Caching** | Cache identical LLM responses to reduce costs and latency on repeated queries |
 | **Enterprise Privacy** | Provider keys encrypted at rest, prompts never stored |
 | **Production Ready** | Battle-tested with automatic retries, timeouts, and error handling |
 
 ## Installation
 
+Choose your preferred package manager:
 ```bash
-# Install the SDK
+# npm
 npm install @lockllm/sdk
 
-# For wrapper functions, install relevant peer dependencies
-npm install openai              # For OpenAI, Groq, DeepSeek, Mistral, etc.
-npm install @anthropic-ai/sdk   # For Anthropic Claude
-npm install cohere-ai           # For Cohere (optional)
+# pnpm (faster, saves disk space)
+pnpm add @lockllm/sdk
+
+# yarn
+yarn add @lockllm/sdk
+```
+
+### Peer Dependencies
+
+For wrapper functions, install the relevant provider SDKs:
+
+```bash
+# npm
+npm install openai @anthropic-ai/sdk cohere-ai
+
+# pnpm
+pnpm add openai @anthropic-ai/sdk cohere-ai
+
+# yarn
+yarn add openai @anthropic-ai/sdk cohere-ai
 ```
 
+**Provider breakdown:**
+- `openai` - For OpenAI, Groq, DeepSeek, Mistral, etc.
+- `@anthropic-ai/sdk` - For Anthropic Claude
+- `cohere-ai` - For Cohere (optional)
+
 **Note:** Peer dependencies are optional and only required if you use the wrapper functions for those providers.
 
 ## Quick Start
@@ -222,7 +248,7 @@ Compare detection accuracy and performance metrics at [lockllm.com/benchmarks](h
 | **Real-Time Protection** | ✅ <250ms latency | ✅ Built-in | ✅ Yes | ❌ Too slow |
 | **Setup Time** | 5 minutes | Included | Days to weeks | N/A |
 | **Maintenance** | None | None | Constant updates | Constant |
-| **Multi-Provider Support** | ✅ 15+ providers | Single provider | Custom per provider | N/A |
+| **Multi-Provider Support** | ✅ 17+ providers | Single provider | Custom per provider | N/A |
 | **False Positives** | Low (~2-5%) | N/A | High (15-30%) | N/A |
 | **Cost** | Free (BYOK) | Free | Dev time + infrastructure | $$$ |
 | **Attack Coverage** | Comprehensive | Content policy only | Pattern-based only | Manual |
@@ -378,6 +404,9 @@ const highResult = await lockllm.scan({
 import {
   LockLLMError,
   PromptInjectionError,
+  PolicyViolationError,
+  AbuseDetectedError,
+  InsufficientCreditsError,
   AuthenticationError,
   RateLimitError,
   UpstreamError
@@ -395,13 +424,19 @@ try {
     console.log("Injection confidence:", error.scanResult.injection);
     console.log("Request ID:", error.requestId);
 
-    // Log to security monitoring system
-    await logSecurityIncident({
-      type: 'prompt_injection',
-      confidence: error.scanResult.injection,
-      requestId: error.requestId,
-      timestamp: new Date()
-    });
+  } else if (error instanceof PolicyViolationError) {
+    // Custom policy violation detected
+    console.log("Policy violation:", error.violated_policies);
+
+  } else if (error instanceof AbuseDetectedError) {
+    // AI abuse detected (bot content, repetition, etc.)
+    console.log("Abuse detected:", error.abuse_details.abuse_types);
+    console.log("Confidence:", error.abuse_details.confidence);
+
+  } else if (error instanceof InsufficientCreditsError) {
+    // Not enough credits
+    console.log("Balance:", error.current_balance);
+    console.log("Cost:", error.estimated_cost);
 
   } else if (error instanceof AuthenticationError) {
     console.log("Invalid LockLLM API key");
@@ -422,7 +457,7 @@ try {
 
 ## Supported Providers
 
-LockLLM supports 17 AI providers with three flexible integration methods:
+LockLLM supports 17+ AI providers with three flexible integration methods:
 
 ### Provider List
 
@@ -449,13 +484,16 @@ LockLLM supports 17 AI providers with three flexible integration methods:
 ### Custom Endpoints
 
 All providers support custom endpoint URLs for:
-- Self-hosted LLM deployments
-- Alternative API gateways
+- Self-hosted LLM deployments (OpenAI-compatible APIs)
+- Alternative API gateways and reverse proxies
 - Custom Azure OpenAI resources
-- Private cloud deployments
+- Private cloud or air-gapped deployments
 - Development and staging environments
 
-Configure custom endpoints in the [LockLLM dashboard](https://www.lockllm.com/dashboard) when adding provider API keys.
+**How it works:**
+Configure custom endpoints in the [LockLLM dashboard](https://www.lockllm.com/dashboard) when adding any provider API key. The SDK wrappers automatically use your custom endpoint instead of the default.
+
+**Example:** Use the OpenAI wrapper with your self-hosted Llama model by configuring a custom endpoint URL.
 
 ## How It Works
 
@@ -476,7 +514,7 @@ LockLLM uses a secure BYOK (Bring Your Own Key) model - you maintain control of
 
 - Use this single key in your SDK configuration
 - Authenticates requests to the LockLLM security gateway
-- Works across all 15+ providers with one key
+- Works across all 17+ providers with one key
 - **This is the only key that goes in your code**
 
 ### Request Flow
@@ -562,7 +600,7 @@ interface LockLLMConfig {
 Scan a prompt for security threats before sending to an LLM.
 
 ```typescript
-await lockllm.scan(request: ScanRequest): Promise<ScanResponse>
+await lockllm.scan(request: ScanRequest, options?: ScanOptions): Promise<ScanResponse>
 ```
 
 **Request Parameters:**
@@ -571,6 +609,14 @@ await lockllm.scan(request: ScanRequest): Promise<ScanResponse>
 interface ScanRequest {
   input: string;                           // Required: Text to scan
   sensitivity?: 'low' | 'medium' | 'high'; // Optional: Detection level (default: 'medium')
+  mode?: 'normal' | 'policy_only' | 'combined'; // Optional: Scan mode (default: 'combined')
+  chunk?: boolean;                         // Optional: Force chunking for long texts
+}
+
+interface ScanOptions {
+  scanAction?: 'block' | 'allow_with_warning';   // Core injection behavior
+  policyAction?: 'block' | 'allow_with_warning'; // Custom policy behavior
+  abuseAction?: 'block' | 'allow_with_warning';  // Abuse detection (opt-in)
 }
 ```
 
@@ -580,8 +626,9 @@ interface ScanRequest {
 interface ScanResponse {
   safe: boolean;             // Whether input is safe (true) or malicious (false)
   label: 0 | 1;             // Classification: 0=safe, 1=malicious
-  confidence: number;        // Confidence score (0-1)
-  injection: number;         // Injection risk score (0-1, higher=more risky)
+  confidence?: number;       // Core injection confidence score (0-1)
+  injection?: number;        // Injection risk score (0-1, higher=more risky)
+  policy_confidence?: number; // Policy check confidence (in combined/policy_only mode)
   sensitivity: Sensitivity;  // Sensitivity level used for scan
   request_id: string;        // Unique request identifier
 
@@ -590,11 +637,20 @@ interface ScanResponse {
     input_chars: number;     // Number of characters processed
   };
 
-  debug?: {                 // Only available with Pro plan
+  debug?: {
     duration_ms: number;    // Total processing time
     inference_ms: number;   // ML inference time
     mode: 'single' | 'chunked';
   };
+
+  // Present when using policy_only or combined mode with allow_with_warning
+  policy_warnings?: PolicyViolation[];
+  // Present when core injection detected with allow_with_warning
+  scan_warning?: ScanWarning;
+  // Present when abuse detection is enabled and abuse found
+  abuse_warnings?: AbuseWarning;
+  // Present when intelligent routing is enabled
+  routing?: { task_type: string; complexity: number; selected_model?: string; };
 }
 ```
 
@@ -615,6 +671,15 @@ createGroq(config: GenericClientConfig): OpenAI
 interface GenericClientConfig {
   apiKey: string;           // Required: Your LockLLM API key
   baseURL?: string;         // Optional: Override proxy URL
+  proxyOptions?: {          // Optional: Security and routing configuration
+    scanMode?: 'normal' | 'policy_only' | 'combined';
+    scanAction?: 'block' | 'allow_with_warning';
+    policyAction?: 'block' | 'allow_with_warning';
+    abuseAction?: 'block' | 'allow_with_warning' | null;
+    routeAction?: 'disabled' | 'auto' | 'custom';
+    cacheResponse?: boolean;
+    cacheTTL?: number;
+  };
   [key: string]: any;       // Optional: Provider-specific options
 }
 ```
@@ -631,6 +696,16 @@ const url = getProxyURL('openai');
 // Returns: 'https://api.lockllm.com/v1/proxy/openai'
 ```
 
+**Get universal proxy URL (non-BYOK, 200+ models):**
+
+```typescript
+function getUniversalProxyURL(): string
+
+// Example
+const url = getUniversalProxyURL();
+// Returns: 'https://api.lockllm.com/v1/proxy/chat/completions'
+```
+
 **Get all proxy URLs:**
 
 ```typescript
@@ -642,6 +717,34 @@ console.log(urls.openai);     // 'https://api.lockllm.com/v1/proxy/openai'
 console.log(urls.anthropic);  // 'https://api.lockllm.com/v1/proxy/anthropic'
 ```
 
+**Build LockLLM proxy headers:**
+
+```typescript
+import { buildLockLLMHeaders } from '@lockllm/sdk';
+
+const headers = buildLockLLMHeaders({
+  scanMode: 'combined',
+  scanAction: 'block',
+  policyAction: 'allow_with_warning',
+  abuseAction: 'block',
+  routeAction: 'auto'
+});
+// Returns: { 'x-lockllm-scan-mode': 'combined', ... }
+```
+
+**Parse proxy response metadata:**
+
+```typescript
+import { parseProxyMetadata } from '@lockllm/sdk';
+
+// Parse response headers from any proxy request
+const metadata = parseProxyMetadata(response.headers);
+console.log(metadata.safe);          // true/false
+console.log(metadata.scan_mode);     // 'combined'
+console.log(metadata.cache_status);  // 'HIT' or 'MISS'
+console.log(metadata.routing);       // { task_type, complexity, selected_model, ... }
+```
+
 ## Error Types
 
 LockLLM provides typed errors for comprehensive error handling:
@@ -653,6 +756,9 @@ LockLLMError (base)
 ├── AuthenticationError (401)
 ├── RateLimitError (429)
 ├── PromptInjectionError (400)
+├── PolicyViolationError (403)
+├── AbuseDetectedError (400)
+├── InsufficientCreditsError (402)
 ├── UpstreamError (502)
 ├── ConfigurationError (400)
 └── NetworkError (0)
@@ -676,6 +782,32 @@ class RateLimitError extends LockLLMError {
   retryAfter?: number;     // Milliseconds until retry allowed
 }
 
+class PolicyViolationError extends LockLLMError {
+  violated_policies: Array<{
+    policy_name: string;
+    violated_categories: Array<{ name: string }>;
+    violation_details?: string;
+  }>;
+}
+
+class AbuseDetectedError extends LockLLMError {
+  abuse_details: {
+    confidence: number;
+    abuse_types: string[];
+    indicators: {
+      bot_score: number;
+      repetition_score: number;
+      resource_score: number;
+      pattern_score: number;
+    };
+  };
+}
+
+class InsufficientCreditsError extends LockLLMError {
+  current_balance: number;  // Current credit balance
+  estimated_cost: number;   // Estimated cost of the request
+}
+
 class UpstreamError extends LockLLMError {
   provider?: string;       // Provider name
   upstreamStatus?: number; // Provider's status code
@@ -707,13 +839,22 @@ LockLLM adds minimal latency while providing comprehensive security protection.
 
 ## Rate Limits
 
-LockLLM provides generous rate limits for all users, with the Free tier supporting most production use cases.
+LockLLM uses a 10-tier progressive system based on monthly usage. Higher tiers unlock faster rate limits and free monthly credits.
+
+| Tier | Max RPM | Monthly Spending Requirement |
+|------|---------|----------------------------|
+| **Tier 1** (Free) | 30 RPM | $0 |
+| **Tier 2** | 50 RPM | $10/month |
+| **Tier 3** | 100 RPM | $50/month |
+| **Tier 4** | 200 RPM | $100/month |
+| **Tier 5** | 500 RPM | $250/month |
+| **Tier 6** | 1,000 RPM | $500/month |
+| **Tier 7** | 2,000 RPM | $1,000/month |
+| **Tier 8** | 5,000 RPM | $3,000/month |
+| **Tier 9** | 10,000 RPM | $5,000/month |
+| **Tier 10** | 20,000 RPM | $10,000/month |
 
-| Tier | Requests per Minute | Best For |
-|------|---------------------|----------|
-| **Free** | 1,000 RPM | Most applications, startups, side projects |
-| **Pro** | 10,000 RPM | High-traffic applications, enterprise pilots |
-| **Enterprise** | Custom | Large-scale deployments, custom SLAs |
+See [pricing](https://www.lockllm.com/pricing) for full tier details and free monthly credits.
 
 **Smart Rate Limit Handling:**
 
@@ -751,6 +892,64 @@ const lockllm = new LockLLM({
 });
 ```
 
+### Advanced Scan Options
+
+Control scan behavior with mode, sensitivity, and action headers:
+
+```typescript
+// Scan API with advanced options
+const result = await lockllm.scan(
+  {
+    input: userPrompt,
+    sensitivity: 'high',        // 'low' | 'medium' | 'high'
+    mode: 'combined',           // 'normal' | 'policy_only' | 'combined'
+    chunk: true                 // Force chunking for long texts
+  },
+  {
+    scanAction: 'block',        // Block core injection attacks
+    policyAction: 'allow_with_warning',  // Allow but warn on policy violations
+    abuseAction: 'block'        // Enable abuse detection (opt-in)
+  }
+);
+
+// Proxy mode with advanced options
+const openai = createOpenAI({
+  apiKey: process.env.LOCKLLM_API_KEY,
+  proxyOptions: {
+    scanMode: 'combined',           // Check both core + policies
+    scanAction: 'block',            // Block injection attacks
+    policyAction: 'block',          // Block policy violations
+    abuseAction: 'allow_with_warning',  // Detect abuse, don't block
+    routeAction: 'auto'             // Enable intelligent routing
+  }
+});
+```
+
+**Scan Modes:**
+- `normal` - Core security threats only (injection, jailbreaks, etc.)
+- `policy_only` - Custom policies only (skip core security)
+- `combined` (default) - Both core security AND custom policies
+
+**Sensitivity Levels:**
+- `low` - Fewer false positives, may miss sophisticated attacks
+- `medium` (default) - Balanced approach, recommended
+- `high` - Maximum protection, may have more false positives
+
+**Action Headers:**
+- `scanAction` - Controls core injection detection: `'block'` | `'allow_with_warning'`
+- `policyAction` - Controls custom policy violations: `'block'` | `'allow_with_warning'`
+- `abuseAction` - Controls abuse detection (opt-in): `'block'` | `'allow_with_warning'` | `null`
+- `routeAction` - Controls intelligent routing: `'disabled'` | `'auto'` | `'custom'`
+
+**Default Behavior (no headers):**
+- Scan Mode: `combined` (check both core + policies)
+- Scan Action: `allow_with_warning` (detect but don't block)
+- Policy Action: `allow_with_warning` (detect but don't block)
+- Abuse Action: `null` (disabled, opt-in only)
+- Route Action: `disabled` (no routing)
+
+See [examples/advanced-options.ts](examples/advanced-options.ts) for complete examples.
+
 ## Best Practices
 
 ### Security
@@ -841,17 +1040,17 @@ For non-JavaScript environments, use the REST API directly:
 
 **Scan Endpoint:**
 ```bash
-curl -X POST https://api.lockllm.com/scan \
-  -H "x-api-key: YOUR_LOCKLLM_API_KEY" \
+curl -X POST https://api.lockllm.com/v1/scan \
+  -H "Authorization: Bearer YOUR_LOCKLLM_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"prompt": "Your text to scan", "sensitivity": "medium"}'
+  -d '{"input": "Your text to scan", "sensitivity": "medium"}'
 ```
 
 **Proxy Endpoints:**
 ```bash
 # OpenAI-compatible proxy
 curl -X POST https://api.lockllm.com/v1/proxy/openai/chat/completions \
-  -H "x-api-key: YOUR_LOCKLLM_API_KEY" \
+  -H "Authorization: Bearer YOUR_LOCKLLM_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'
 ```
@@ -876,7 +1075,7 @@ import {
 
 // Type inference works automatically
 const config: LockLLMConfig = {
-  apiKey: 'llm_...',
+  apiKey: '...',
   timeout: 30000
 };
 

package/dist/client.d.ts

@@ -30,7 +30,7 @@ export declare class LockLLM {
      * });
      * ```
      */
-    get scan(): (request: import(".").ScanRequest, options?: import("./types/common").RequestOptions) => Promise<import(".").ScanResponse>;
+    get scan(): (request: import(".").ScanRequest, options?: import(".").ScanOptions) => Promise<import(".").ScanResponse>;
     /**
      * Get the current configuration
      */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;;;;;;OAWG;gBACS,MAAM,EAAE,aAAa;IA4BjC;;;;;;;;;;OAUG;IACH,IAAI,IAAI,+HAEP;IAED;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;CAG/C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;;;;;;OAWG;gBACS,MAAM,EAAE,aAAa;IA4BjC;;;;;;;;;;OAUG;IACH,IAAI,IAAI,+GAEP;IAED;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;CAG/C"}