Updated documentation

Author: anthonyhalim150

CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## [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

README.md

@@ -28,7 +28,7 @@ LockLLM is a state-of-the-art AI security ecosystem that detects prompt injectio
 - **Advanced ML Detection** - Models trained on real-world attack patterns for prompt injection and jailbreaks
 - **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
@@ -79,6 +79,10 @@ LockLLM provides production-ready AI security that integrates seamlessly into yo
 | **Streaming Compatible** | Works seamlessly with streaming responses from any provider |
 | **Configurable Sensitivity** | Adjust detection thresholds (low/medium/high) per use case |
 | **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 |
 
@@ -400,6 +404,9 @@ const highResult = await lockllm.scan({
 import {
   LockLLMError,
   PromptInjectionError,
+  PolicyViolationError,
+  AbuseDetectedError,
+  InsufficientCreditsError,
   AuthenticationError,
   RateLimitError,
   UpstreamError
@@ -417,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");
@@ -587,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:**
@@ -596,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)
 }
 ```
 
@@ -605,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
 
@@ -615,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; };
 }
 ```
 
@@ -640,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
 }
 ```
@@ -656,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
@@ -667,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:
@@ -678,6 +756,9 @@ LockLLMError (base)
 ├── AuthenticationError (401)
 ├── RateLimitError (429)
 ├── PromptInjectionError (400)
+├── PolicyViolationError (403)
+├── AbuseDetectedError (400)
+├── InsufficientCreditsError (402)
 ├── UpstreamError (502)
 ├── ConfigurationError (400)
 └── NetworkError (0)
@@ -701,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
@@ -732,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:**
 
@@ -924,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"}]}'
 ```