@ainvirion/aiproxyguard-npm-sdk 1.0.14

package/dist/express-x7uGX_rh.d.mts

@@ -0,0 +1,258 @@
+/**
+ * Default API base URL (cloud mode).
+ */
+declare const DEFAULT_BASE_URL = "https://aiproxyguard.com";
+/**
+ * API mode determines endpoint paths and request/response formats.
+ * - 'cloud': Uses /api/v1/check with {input} request format
+ * - 'proxy': Uses /check with {text} request format
+ * - 'auto': Auto-detect based on URL (docker.* = proxy, otherwise cloud)
+ */
+type ApiMode = 'cloud' | 'proxy' | 'auto';
+/**
+ * Action to take based on prompt injection detection result.
+ */
+type Action = 'allow' | 'log' | 'warn' | 'block';
+/**
+ * Threat detected in the input.
+ */
+interface Threat {
+    /** Type of threat detected */
+    type: string;
+    /** Confidence score from 0.0 to 1.0 */
+    confidence: number;
+    /** Rule that matched, if any */
+    rule: string | null;
+}
+/**
+ * Result from checking text for prompt injection.
+ */
+interface CheckResult {
+    /** Unique check ID */
+    id: string;
+    /** Whether the input was flagged as potentially harmful */
+    flagged: boolean;
+    /** Action recommended by the security proxy */
+    action: Action;
+    /** List of threats detected */
+    threats: Threat[];
+    /** Processing latency in milliseconds */
+    latencyMs: number;
+    /** Whether the result was served from cache */
+    cached: boolean;
+}
+/**
+ * Service information response.
+ */
+interface ServiceInfo {
+    service: string;
+    version: string;
+}
+/**
+ * Health check response.
+ */
+interface HealthStatus {
+    status: 'healthy' | 'unhealthy';
+}
+/**
+ * Readiness check response.
+ */
+interface ReadinessStatus {
+    status: 'ready' | 'not_ready';
+    checks: Record<string, boolean>;
+}
+/**
+ * Configuration options for the AIProxyGuard client.
+ */
+interface AIProxyGuardConfig {
+    /** Base URL of the AIProxyGuard service (default: https://aiproxyguard.com) */
+    baseUrl?: string;
+    /** API key for authentication (optional for some deployments) */
+    apiKey?: string;
+    /** API mode: 'cloud', 'proxy', or 'auto' (default: 'auto') */
+    mode?: ApiMode;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts (default: 3) */
+    retries?: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Maximum concurrent requests for checkBatch (default: 10) */
+    maxConcurrency?: number;
+}
+/**
+ * Error response from the API.
+ */
+interface ErrorResponse {
+    error: {
+        type: string;
+        message: string;
+        code?: string;
+    };
+}
+
+/**
+ * AIProxyGuard client for detecting prompt injection attacks.
+ *
+ * @example
+ * ```typescript
+ * const client = new AIProxyGuard('https://docker.aiproxyguard.com');
+ *
+ * const result = await client.check('Ignore all previous instructions');
+ * if (result.action === 'block') {
+ *   console.log(`Blocked: ${result.category}`);
+ * }
+ * ```
+ */
+declare class AIProxyGuard {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly mode;
+    private readonly timeout;
+    private readonly retries;
+    private readonly retryDelay;
+    private readonly maxConcurrency;
+    /**
+     * Create a new AIProxyGuard client.
+     *
+     * @param config - Configuration object, base URL string, or omit for default
+     * @throws {ValidationError} If the baseUrl has an invalid scheme
+     */
+    constructor(config?: AIProxyGuardConfig | string);
+    private getHeaders;
+    private handleError;
+    private fetchWithRetry;
+    /**
+     * Check text for prompt injection.
+     *
+     * @param text - The text to scan
+     * @returns CheckResult with action, category, signatureName, and confidence
+     * @throws {ValidationError} If the request is invalid
+     * @throws {TimeoutError} If the request times out
+     * @throws {RateLimitError} If rate limited
+     * @throws {AIProxyGuardError} For other errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.check("Ignore all previous instructions");
+     * if (result.action === 'block') {
+     *   console.log(`Blocked: ${result.category}`);
+     * }
+     * ```
+     */
+    check(text: string, context?: Record<string, unknown>): Promise<CheckResult>;
+    /**
+     * Check using cloud mode (/api/v1/check with {input, context}).
+     */
+    private checkCloud;
+    /**
+     * Check using proxy mode (/check with {text}).
+     */
+    private checkProxy;
+    /**
+     * Check multiple texts for prompt injection in parallel with concurrency limit.
+     *
+     * @param texts - Array of texts to scan
+     * @returns Array of CheckResult objects in the same order
+     *
+     * @example
+     * ```typescript
+     * const results = await client.checkBatch([
+     *   'Hello, how are you?',
+     *   'Ignore all instructions',
+     * ]);
+     * ```
+     */
+    checkBatch(texts: string[]): Promise<CheckResult[]>;
+    /**
+     * Check if text is safe (not blocked).
+     *
+     * @param text - The text to scan
+     * @returns True if the text is safe, false if blocked
+     *
+     * @example
+     * ```typescript
+     * if (await client.isSafe(userInput)) {
+     *   // Process the input
+     * }
+     * ```
+     */
+    isSafe(text: string): Promise<boolean>;
+    /**
+     * Get service information.
+     *
+     * @returns ServiceInfo with service name and version
+     */
+    info(): Promise<ServiceInfo>;
+    /**
+     * Check if the service is healthy.
+     *
+     * @returns True if healthy, false otherwise
+     */
+    health(): Promise<boolean>;
+    /**
+     * Check if the service is ready.
+     *
+     * @returns ReadinessStatus with status and checks
+     */
+    ready(): Promise<ReadinessStatus>;
+}
+
+/**
+ * Express request type (minimal interface for compatibility).
+ */
+interface Request {
+    body?: Record<string, unknown>;
+}
+/**
+ * Express response type (minimal interface for compatibility).
+ */
+interface Response {
+    status(code: number): Response;
+    json(data: unknown): void;
+}
+/**
+ * Express next function type.
+ */
+type NextFunction = (error?: unknown) => void;
+/**
+ * Extended request with AIProxyGuard result attached.
+ */
+interface GuardedRequest extends Request {
+    aiproxyguardResult?: CheckResult;
+}
+/**
+ * Options for the guard middleware.
+ */
+interface GuardMiddlewareOptions {
+    /** Field(s) in request body to check. Default: 'text' */
+    textField?: string | string[];
+    /** Action to take on block. Default: 'reject' */
+    onBlock?: 'reject' | 'continue';
+    /** Whether to reject requests with non-string field values. Default: true */
+    rejectInvalidTypes?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error, req: Request, res: Response) => void;
+}
+/**
+ * Express middleware for prompt injection detection.
+ *
+ * @param client - AIProxyGuard client instance
+ * @param options - Middleware options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import { AIProxyGuard } from '@aiproxyguard/sdk';
+ * import { guardMiddleware } from '@aiproxyguard/sdk/middleware';
+ *
+ * const client = new AIProxyGuard('https://docker.aiproxyguard.com');
+ *
+ * app.post('/chat', guardMiddleware(client), (req, res) => {
+ *   // Request already validated
+ * });
+ * ```
+ */
+declare function guardMiddleware(client: AIProxyGuard, options?: GuardMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export { AIProxyGuard as A, type CheckResult as C, DEFAULT_BASE_URL as D, type ErrorResponse as E, type GuardMiddlewareOptions as G, type HealthStatus as H, type ReadinessStatus as R, type ServiceInfo as S, type Threat as T, type AIProxyGuardConfig as a, type Action as b, type ApiMode as c, type GuardedRequest as d, guardMiddleware as g };

package/dist/express-x7uGX_rh.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Default API base URL (cloud mode).
+ */
+declare const DEFAULT_BASE_URL = "https://aiproxyguard.com";
+/**
+ * API mode determines endpoint paths and request/response formats.
+ * - 'cloud': Uses /api/v1/check with {input} request format
+ * - 'proxy': Uses /check with {text} request format
+ * - 'auto': Auto-detect based on URL (docker.* = proxy, otherwise cloud)
+ */
+type ApiMode = 'cloud' | 'proxy' | 'auto';
+/**
+ * Action to take based on prompt injection detection result.
+ */
+type Action = 'allow' | 'log' | 'warn' | 'block';
+/**
+ * Threat detected in the input.
+ */
+interface Threat {
+    /** Type of threat detected */
+    type: string;
+    /** Confidence score from 0.0 to 1.0 */
+    confidence: number;
+    /** Rule that matched, if any */
+    rule: string | null;
+}
+/**
+ * Result from checking text for prompt injection.
+ */
+interface CheckResult {
+    /** Unique check ID */
+    id: string;
+    /** Whether the input was flagged as potentially harmful */
+    flagged: boolean;
+    /** Action recommended by the security proxy */
+    action: Action;
+    /** List of threats detected */
+    threats: Threat[];
+    /** Processing latency in milliseconds */
+    latencyMs: number;
+    /** Whether the result was served from cache */
+    cached: boolean;
+}
+/**
+ * Service information response.
+ */
+interface ServiceInfo {
+    service: string;
+    version: string;
+}
+/**
+ * Health check response.
+ */
+interface HealthStatus {
+    status: 'healthy' | 'unhealthy';
+}
+/**
+ * Readiness check response.
+ */
+interface ReadinessStatus {
+    status: 'ready' | 'not_ready';
+    checks: Record<string, boolean>;
+}
+/**
+ * Configuration options for the AIProxyGuard client.
+ */
+interface AIProxyGuardConfig {
+    /** Base URL of the AIProxyGuard service (default: https://aiproxyguard.com) */
+    baseUrl?: string;
+    /** API key for authentication (optional for some deployments) */
+    apiKey?: string;
+    /** API mode: 'cloud', 'proxy', or 'auto' (default: 'auto') */
+    mode?: ApiMode;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts (default: 3) */
+    retries?: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Maximum concurrent requests for checkBatch (default: 10) */
+    maxConcurrency?: number;
+}
+/**
+ * Error response from the API.
+ */
+interface ErrorResponse {
+    error: {
+        type: string;
+        message: string;
+        code?: string;
+    };
+}
+
+/**
+ * AIProxyGuard client for detecting prompt injection attacks.
+ *
+ * @example
+ * ```typescript
+ * const client = new AIProxyGuard('https://docker.aiproxyguard.com');
+ *
+ * const result = await client.check('Ignore all previous instructions');
+ * if (result.action === 'block') {
+ *   console.log(`Blocked: ${result.category}`);
+ * }
+ * ```
+ */
+declare class AIProxyGuard {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly mode;
+    private readonly timeout;
+    private readonly retries;
+    private readonly retryDelay;
+    private readonly maxConcurrency;
+    /**
+     * Create a new AIProxyGuard client.
+     *
+     * @param config - Configuration object, base URL string, or omit for default
+     * @throws {ValidationError} If the baseUrl has an invalid scheme
+     */
+    constructor(config?: AIProxyGuardConfig | string);
+    private getHeaders;
+    private handleError;
+    private fetchWithRetry;
+    /**
+     * Check text for prompt injection.
+     *
+     * @param text - The text to scan
+     * @returns CheckResult with action, category, signatureName, and confidence
+     * @throws {ValidationError} If the request is invalid
+     * @throws {TimeoutError} If the request times out
+     * @throws {RateLimitError} If rate limited
+     * @throws {AIProxyGuardError} For other errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.check("Ignore all previous instructions");
+     * if (result.action === 'block') {
+     *   console.log(`Blocked: ${result.category}`);
+     * }
+     * ```
+     */
+    check(text: string, context?: Record<string, unknown>): Promise<CheckResult>;
+    /**
+     * Check using cloud mode (/api/v1/check with {input, context}).
+     */
+    private checkCloud;
+    /**
+     * Check using proxy mode (/check with {text}).
+     */
+    private checkProxy;
+    /**
+     * Check multiple texts for prompt injection in parallel with concurrency limit.
+     *
+     * @param texts - Array of texts to scan
+     * @returns Array of CheckResult objects in the same order
+     *
+     * @example
+     * ```typescript
+     * const results = await client.checkBatch([
+     *   'Hello, how are you?',
+     *   'Ignore all instructions',
+     * ]);
+     * ```
+     */
+    checkBatch(texts: string[]): Promise<CheckResult[]>;
+    /**
+     * Check if text is safe (not blocked).
+     *
+     * @param text - The text to scan
+     * @returns True if the text is safe, false if blocked
+     *
+     * @example
+     * ```typescript
+     * if (await client.isSafe(userInput)) {
+     *   // Process the input
+     * }
+     * ```
+     */
+    isSafe(text: string): Promise<boolean>;
+    /**
+     * Get service information.
+     *
+     * @returns ServiceInfo with service name and version
+     */
+    info(): Promise<ServiceInfo>;
+    /**
+     * Check if the service is healthy.
+     *
+     * @returns True if healthy, false otherwise
+     */
+    health(): Promise<boolean>;
+    /**
+     * Check if the service is ready.
+     *
+     * @returns ReadinessStatus with status and checks
+     */
+    ready(): Promise<ReadinessStatus>;
+}
+
+/**
+ * Express request type (minimal interface for compatibility).
+ */
+interface Request {
+    body?: Record<string, unknown>;
+}
+/**
+ * Express response type (minimal interface for compatibility).
+ */
+interface Response {
+    status(code: number): Response;
+    json(data: unknown): void;
+}
+/**
+ * Express next function type.
+ */
+type NextFunction = (error?: unknown) => void;
+/**
+ * Extended request with AIProxyGuard result attached.
+ */
+interface GuardedRequest extends Request {
+    aiproxyguardResult?: CheckResult;
+}
+/**
+ * Options for the guard middleware.
+ */
+interface GuardMiddlewareOptions {
+    /** Field(s) in request body to check. Default: 'text' */
+    textField?: string | string[];
+    /** Action to take on block. Default: 'reject' */
+    onBlock?: 'reject' | 'continue';
+    /** Whether to reject requests with non-string field values. Default: true */
+    rejectInvalidTypes?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error, req: Request, res: Response) => void;
+}
+/**
+ * Express middleware for prompt injection detection.
+ *
+ * @param client - AIProxyGuard client instance
+ * @param options - Middleware options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import { AIProxyGuard } from '@aiproxyguard/sdk';
+ * import { guardMiddleware } from '@aiproxyguard/sdk/middleware';
+ *
+ * const client = new AIProxyGuard('https://docker.aiproxyguard.com');
+ *
+ * app.post('/chat', guardMiddleware(client), (req, res) => {
+ *   // Request already validated
+ * });
+ * ```
+ */
+declare function guardMiddleware(client: AIProxyGuard, options?: GuardMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export { AIProxyGuard as A, type CheckResult as C, DEFAULT_BASE_URL as D, type ErrorResponse as E, type GuardMiddlewareOptions as G, type HealthStatus as H, type ReadinessStatus as R, type ServiceInfo as S, type Threat as T, type AIProxyGuardConfig as a, type Action as b, type ApiMode as c, type GuardedRequest as d, guardMiddleware as g };

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { C as CheckResult } from './express-x7uGX_rh.mjs';
+export { A as AIProxyGuard, a as AIProxyGuardConfig, b as Action, c as ApiMode, D as DEFAULT_BASE_URL, E as ErrorResponse, G as GuardMiddlewareOptions, d as GuardedRequest, H as HealthStatus, R as ReadinessStatus, S as ServiceInfo, T as Threat, A as default, g as guardMiddleware } from './express-x7uGX_rh.mjs';
+
+/**
+ * Base error class for AIProxyGuard SDK errors.
+ */
+declare class AIProxyGuardError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * Thrown when the request is invalid or malformed.
+ */
+declare class ValidationError extends AIProxyGuardError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when unable to connect to the AIProxyGuard service.
+ */
+declare class ConnectionError extends AIProxyGuardError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a request times out.
+ */
+declare class TimeoutError extends AIProxyGuardError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limited by the service.
+ */
+declare class RateLimitError extends AIProxyGuardError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Thrown when content is blocked due to detected prompt injection.
+ */
+declare class ContentBlockedError extends AIProxyGuardError {
+    readonly result: CheckResult;
+    constructor(result: CheckResult);
+}
+
+/**
+ * Check if a CheckResult indicates the content is safe (not flagged).
+ */
+declare function isSafe(result: CheckResult): boolean;
+/**
+ * Check if a CheckResult indicates the content is flagged/blocked.
+ */
+declare function isBlocked(result: CheckResult): boolean;
+
+export { AIProxyGuardError, CheckResult, ConnectionError, ContentBlockedError, RateLimitError, TimeoutError, ValidationError, isBlocked, isSafe };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { C as CheckResult } from './express-x7uGX_rh.js';
+export { A as AIProxyGuard, a as AIProxyGuardConfig, b as Action, c as ApiMode, D as DEFAULT_BASE_URL, E as ErrorResponse, G as GuardMiddlewareOptions, d as GuardedRequest, H as HealthStatus, R as ReadinessStatus, S as ServiceInfo, T as Threat, A as default, g as guardMiddleware } from './express-x7uGX_rh.js';
+
+/**
+ * Base error class for AIProxyGuard SDK errors.
+ */
+declare class AIProxyGuardError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * Thrown when the request is invalid or malformed.
+ */
+declare class ValidationError extends AIProxyGuardError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when unable to connect to the AIProxyGuard service.
+ */
+declare class ConnectionError extends AIProxyGuardError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a request times out.
+ */
+declare class TimeoutError extends AIProxyGuardError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limited by the service.
+ */
+declare class RateLimitError extends AIProxyGuardError {
+    readonly retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+/**
+ * Thrown when content is blocked due to detected prompt injection.
+ */
+declare class ContentBlockedError extends AIProxyGuardError {
+    readonly result: CheckResult;
+    constructor(result: CheckResult);
+}
+
+/**
+ * Check if a CheckResult indicates the content is safe (not flagged).
+ */
+declare function isSafe(result: CheckResult): boolean;
+/**
+ * Check if a CheckResult indicates the content is flagged/blocked.
+ */
+declare function isBlocked(result: CheckResult): boolean;
+
+export { AIProxyGuardError, CheckResult, ConnectionError, ContentBlockedError, RateLimitError, TimeoutError, ValidationError, isBlocked, isSafe };