@vpdeva/blackwall-llm-shield-js 0.1.5 → 0.1.6

package/README.md

@@ -32,7 +32,7 @@ npm install @xenova/transformers
 ## Fast Start
 
 ```js
-const { BlackwallShield } = require('blackwall-llm-shield-js');
+const { BlackwallShield } = require('@vpdeva/blackwall-llm-shield-js');
 
 const shield = new BlackwallShield({
   blockOnPromptInjection: true,
@@ -95,9 +95,9 @@ Use `createExpressMiddleware()`, `createLangChainCallbacks()`, or `createLlamaIn
 
 ### Subpath modules
 
-Use `require('blackwall-llm-shield-js/integrations')` for callback wrappers and `require('blackwall-llm-shield-js/semantic')` for optional local semantic scoring adapters.
+Use `require('@vpdeva/blackwall-llm-shield-js/integrations')` for callback wrappers and `require('@vpdeva/blackwall-llm-shield-js/semantic')` for optional local semantic scoring adapters.
 
-Use `require('blackwall-llm-shield-js/providers')` for provider adapter factories.
+Use `require('@vpdeva/blackwall-llm-shield-js/providers')` for provider adapter factories.
 
 ## Core Building Blocks
 
@@ -151,7 +151,7 @@ if (!guarded.allowed) {
 ### Wrap a provider call end to end
 
 ```js
-const { BlackwallShield, createOpenAIAdapter } = require('blackwall-llm-shield-js');
+const { BlackwallShield, createOpenAIAdapter } = require('@vpdeva/blackwall-llm-shield-js');
 
 const shield = new BlackwallShield({
   preset: 'shadowFirst',
@@ -234,15 +234,20 @@ const toolFirewall = new ToolPermissionFirewall({
 ### Operational telemetry summaries
 
 ```js
+const { summarizeOperationalTelemetry } = require('@vpdeva/blackwall-llm-shield-js');
 const summary = summarizeOperationalTelemetry(events);
 console.log(summary.byRoute);
 console.log(summary.highestSeverity);
 ```
 
+### TypeScript
+
+The package now ships first-class declaration files for the main entry point plus `integrations`, `providers`, and `semantic` subpaths, so local declaration shims should no longer be necessary in TypeScript apps.
+
 ### Inspect model output
 
 ```js
-const { OutputFirewall } = require('blackwall-llm-shield-js');
+const { OutputFirewall } = require('@vpdeva/blackwall-llm-shield-js');
 
 const firewall = new OutputFirewall({
   riskThreshold: 'high',
@@ -259,7 +264,7 @@ console.log(review.allowed);
 ### Gate tool execution
 
 ```js
-const { ToolPermissionFirewall } = require('blackwall-llm-shield-js');
+const { ToolPermissionFirewall } = require('@vpdeva/blackwall-llm-shield-js');
 
 const tools = new ToolPermissionFirewall({
   allowedTools: ['search', 'lookupCustomer'],
@@ -274,6 +279,8 @@ console.log(tools.inspectCall({ tool: 'lookupCustomer', args: { id: 'cus_123' }
 - [`examples/nextjs-app-router/app/api/chat/route.js`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/examples/nextjs-app-router/app/api/chat/route.js) shows guarded request handling in a Next.js route
 - [`examples/admin-dashboard/index.html`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/examples/admin-dashboard/index.html) shows a polished security command center demo
 
+For Next.js, the most production-real patterns are App Router route handlers, server actions for trusted internal mutations, and streaming endpoints that apply output review to assembled or final chunks instead of raw intermediate tokens.
+
 ## Release Commands
 
 - `npm run release:check` runs the JS test suite before release

package/index.d.ts

@@ -0,0 +1,92 @@
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+
+export interface MessagePart {
+  type: string;
+  text?: string;
+  image_url?: string;
+  file_id?: string;
+  [key: string]: unknown;
+}
+
+export interface ShieldMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string | MessagePart[] | Record<string, unknown>;
+  trusted?: boolean;
+  contentParts?: MessagePart[];
+}
+
+export interface GuardResult {
+  allowed: boolean;
+  blocked: boolean;
+  reason: string | null;
+  messages: Array<ShieldMessage & { content: string; contentParts?: MessagePart[] }>;
+  report: Record<string, unknown>;
+  vault: Record<string, string>;
+}
+
+export interface ReviewResult {
+  allowed: boolean;
+  severity: RiskLevel;
+  findings: Array<Record<string, unknown>>;
+  report: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProviderAdapter {
+  provider: string;
+  invoke(payload: { messages: ShieldMessage[]; metadata?: Record<string, unknown>; guard?: GuardResult }): Promise<unknown> | unknown;
+  extractOutput?(response: unknown, request?: GuardResult): unknown;
+}
+
+export interface ShieldOptions {
+  preset?: string | null;
+  policyPack?: string | null;
+  shadowMode?: boolean;
+  routePolicies?: Array<{ route: string | RegExp | ((route: string, metadata: Record<string, unknown>) => boolean); options: Record<string, unknown> }>;
+  customPromptDetectors?: Array<(payload: Record<string, unknown>) => Record<string, unknown> | Array<Record<string, unknown>> | null>;
+  onTelemetry?: (event: Record<string, unknown>) => void | Promise<void>;
+  [key: string]: unknown;
+}
+
+export class BlackwallShield {
+  constructor(options?: ShieldOptions);
+  inspectText(text: unknown): Record<string, unknown>;
+  guardModelRequest(input?: { messages?: ShieldMessage[]; metadata?: Record<string, unknown>; allowSystemMessages?: boolean; comparePolicyPacks?: string[] }): Promise<GuardResult>;
+  reviewModelResponse(input?: { output: unknown; metadata?: Record<string, unknown>; outputFirewall?: OutputFirewall | null; firewallOptions?: Record<string, unknown> }): Promise<ReviewResult>;
+  protectModelCall(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+  protectWithAdapter(input: { adapter: ProviderAdapter; messages?: ShieldMessage[]; metadata?: Record<string, unknown>; allowSystemMessages?: boolean; comparePolicyPacks?: string[]; outputFirewall?: OutputFirewall | null; firewallOptions?: Record<string, unknown> }): Promise<Record<string, unknown>>;
+}
+
+export class OutputFirewall {
+  constructor(options?: Record<string, unknown>);
+  inspect(output: unknown, options?: Record<string, unknown>): ReviewResult;
+}
+
+export class ToolPermissionFirewall {
+  constructor(options?: Record<string, unknown>);
+  inspectCall(input: Record<string, unknown>): Record<string, unknown>;
+  inspectCallAsync?(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+export class RetrievalSanitizer {
+  constructor(options?: Record<string, unknown>);
+  sanitizeDocuments(documents: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+}
+
+export class AuditTrail {
+  constructor(options?: Record<string, unknown>);
+  record(event?: Record<string, unknown>): Record<string, unknown>;
+  summarize(): Record<string, unknown>;
+}
+
+export const SHIELD_PRESETS: Record<string, Record<string, unknown>>;
+export const CORE_INTERFACES: Record<string, string>;
+export const POLICY_PACKS: Record<string, Record<string, unknown>>;
+
+export function buildShieldOptions(options?: Record<string, unknown>): Record<string, unknown>;
+export function summarizeOperationalTelemetry(events?: Array<Record<string, unknown>>): Record<string, unknown>;
+
+export function createOpenAIAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createAnthropicAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createGeminiAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createOpenRouterAdapter(input: Record<string, unknown>): ProviderAdapter;

package/integrations.d.ts

@@ -0,0 +1,18 @@
+export { BlackwallShield, OutputFirewall, type ProviderAdapter } from './index';
+
+export class BlackwallLangChainCallback {
+  constructor(options?: Record<string, unknown>);
+  handleLLMStart(llm: unknown, prompts?: string[]): Promise<unknown>;
+  guardMessages(messages: unknown, metadata?: Record<string, unknown>): Promise<unknown>;
+  handleLLMEnd(output: unknown): Promise<unknown>;
+}
+
+export class BlackwallLlamaIndexCallback {
+  constructor(options?: Record<string, unknown>);
+  onEventStart(event: unknown): Promise<unknown>;
+  onEventEnd(event: unknown): Promise<unknown>;
+}
+
+export function createExpressMiddleware(options?: Record<string, unknown>): (req: unknown, res: unknown, next: () => void) => Promise<void>;
+export function createLangChainCallbacks(options?: Record<string, unknown>): Record<string, unknown>;
+export function createLlamaIndexCallback(options?: Record<string, unknown>): Record<string, unknown>;

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Open-source JavaScript enterprise LLM protection toolkit for Node.js and Next.js",
   "license": "Apache-2.0",
   "author": "Vish <hello@vish.au> (https://vish.au)",
   "type": "commonjs",
   "main": "src/index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./integrations": "./src/integrations.js",
-    "./providers": "./src/providers.js",
-    "./semantic": "./src/semantic.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./integrations": {
+      "types": "./integrations.d.ts",
+      "default": "./src/integrations.js"
+    },
+    "./providers": {
+      "types": "./providers.d.ts",
+      "default": "./src/providers.js"
+    },
+    "./semantic": {
+      "types": "./semantic.d.ts",
+      "default": "./src/semantic.js"
+    }
   },
   "bin": {
     "blackwall-scorecard": "src/scorecard.js"
@@ -26,6 +39,10 @@
   },
   "files": [
     "src",
+    "index.d.ts",
+    "integrations.d.ts",
+    "providers.d.ts",
+    "semantic.d.ts",
     "README.md",
     "LICENSE",
     "NOTICE"

package/providers.d.ts

@@ -0,0 +1,6 @@
+export type { ProviderAdapter } from './index';
+
+export function createOpenAIAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createAnthropicAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createGeminiAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createOpenRouterAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;

package/semantic.d.ts

@@ -0,0 +1,4 @@
+export class LightweightIntentScorer {
+  constructor(options?: Record<string, unknown>);
+  score(text: unknown, options?: Record<string, unknown>): Record<string, unknown>;
+}

package/src/index.js

@@ -350,21 +350,46 @@ function summarizeOperationalTelemetry(events = []) {
     shadowModeEvents: 0,
     byType: {},
     byRoute: {},
+    byTenant: {},
+    byModel: {},
+    byPolicyOutcome: {
+      blocked: 0,
+      shadowBlocked: 0,
+      allowed: 0,
+    },
+    topRules: {},
     highestSeverity: 'low',
   };
   for (const event of Array.isArray(events) ? events : []) {
     const type = event && event.type ? event.type : 'unknown';
-    const route = event && event.metadata && (event.metadata.route || event.metadata.path) ? (event.metadata.route || event.metadata.path) : 'unknown';
+    const metadata = event && event.metadata ? event.metadata : {};
+    const route = metadata.route || metadata.path || 'unknown';
+    const tenant = metadata.tenantId || metadata.tenant_id || 'unknown';
+    const model = metadata.model || metadata.modelName || 'unknown';
     const severity = event && event.report && event.report.outputReview
       ? event.report.outputReview.severity
       : (event && event.report && event.report.promptInjection ? event.report.promptInjection.level : 'low');
     summary.totalEvents += 1;
     summary.byType[type] = (summary.byType[type] || 0) + 1;
     summary.byRoute[route] = (summary.byRoute[route] || 0) + 1;
+    summary.byTenant[tenant] = (summary.byTenant[tenant] || 0) + 1;
+    summary.byModel[model] = (summary.byModel[model] || 0) + 1;
     if (event && event.blocked) summary.blockedEvents += 1;
     if (event && event.shadowMode) summary.shadowModeEvents += 1;
+    if (event && event.blocked) summary.byPolicyOutcome.blocked += 1;
+    else if (event && event.shadowMode) summary.byPolicyOutcome.shadowBlocked += 1;
+    else summary.byPolicyOutcome.allowed += 1;
+    const rules = event && event.report && event.report.promptInjection && Array.isArray(event.report.promptInjection.matches)
+      ? event.report.promptInjection.matches.map((item) => item.id).filter(Boolean)
+      : [];
+    rules.forEach((rule) => {
+      summary.topRules[rule] = (summary.topRules[rule] || 0) + 1;
+    });
     if (severityWeight(severity) > severityWeight(summary.highestSeverity)) summary.highestSeverity = severity;
   }
+  summary.topRules = Object.fromEntries(
+    Object.entries(summary.topRules).sort((a, b) => b[1] - a[1]).slice(0, 10)
+  );
   return summary;
 }