@ethicalzen/sdk/dist/client.d.ts

Official EthicalZen SDK for Node.js - AI safety guardrails made simple

export interface EthicalZenConfig {
    apiKey: string;
    gatewayURL?: string;
    baseURL?: string;
    certificateId?: string;
    tenantId?: string;
    timeout?: number;
    mode?: 'explicit' | 'transparent';
}
export interface EnforcementRequest {
    contractId: string;
    payload: {
        input?: any;
        output?: any;
        context?: any;
    };
    metadata?: Record<string, any>;
}
export interface Violation {
    policyId: string;
    guardrail: string;
    message: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
    details?: Record<string, any>;
}
export interface EnforcementResponse {
    success: boolean;
    passed: boolean;
    contractId: string;
    tenantId: string;
    violations: Violation[];
    features?: Record<string, number>;
    extractionTimeMs?: number;
    validationTimeMs?: number;
    detectionMethod?: string;
    timestamp: string;
    latencyMs?: number;
    metadata?: Record<string, any>;
}
export interface ServiceRegistration {
    name: string;
    description: string;
    domain?: string;
    region?: string;
    endpoint?: string;
    policies?: Record<string, any>;
}
export interface RegistrationResponse {
    success: boolean;
    evaluationId: string;
    message: string;
}
/**
 * EthicalZen Client
 *
 * Core client for interacting with the EthicalZen API.
 * Supports two modes:
 * - **Explicit** (default): Uses custom headers (X-Certificate-ID, X-Tenant-ID, X-Target-Endpoint)
 * - **Transparent**: Acts as transparent proxy (certificate in path, no custom headers)
 *
 * @example Explicit Mode (Default)
 * ```typescript
 * const client = new EthicalZenClient({
 *   apiKey: process.env.ETHICALZEN_API_KEY,
 *   tenantId: 'demo',
 *   mode: 'explicit'
 * });
 *
 * const result = await client.enforce({
 *   contractId: 'my-service/general/us/v1.0',
 *   payload: { output: 'AI response here' }
 * });
 * ```
 *
 * @example Transparent Mode (Zero Custom Code)
 * ```typescript
 * const client = new EthicalZenClient({
 *   apiKey: process.env.ETHICALZEN_API_KEY,
 *   certificateId: 'hipaa-compliant-llm-v1',
 *   baseURL: 'http://gateway:8080',
 *   mode: 'transparent'
 * });
 *
 * // Get transparent proxy URL for OpenAI
 * const proxyURL = client.getTransparentProxyURL('https://api.openai.com/v1');
 *
 * // Use with standard OpenAI SDK
 * const openai = new OpenAI({
 *   apiKey: process.env.OPENAI_API_KEY,
 *   baseURL: proxyURL
 * });
 * ```
 */
export declare class EthicalZenClient {
    private client;
    private apiKey;
    private tenantId?;
    private certificateId?;
    private gatewayURL;
    private mode;
    constructor(config: EthicalZenConfig);
    /**
     * Get transparent proxy URL for a target service
     * Only works in transparent mode
     *
     * @param targetURL - Target service URL (e.g., https://api.openai.com/v1)
     * @returns Transparent proxy URL in format: {gateway}/proxy/{cert}/{target}
     *
     * @example
     * ```typescript
     * const client = new EthicalZenClient({
     *   apiKey: 'sk-...',
     *   certificateId: 'hipaa-compliant-llm-v1',
     *   baseURL: 'http://gateway:8080',
     *   mode: 'transparent'
     * });
     *
     * // Get proxy URL
     * const proxyURL = client.getTransparentProxyURL('https://api.openai.com/v1');
     * // Returns: http://gateway:8080/proxy/hipaa-compliant-llm-v1/https://api.openai.com/v1
     *
     * // Use with OpenAI SDK
     * const openai = new OpenAI({ apiKey: '...', baseURL: proxyURL });
     * ```
     */
    getTransparentProxyURL(targetURL: string): string;
    /**
     * Get current mode
     * @returns Current SDK mode ('explicit' or 'transparent')
     */
    getMode(): 'explicit' | 'transparent';
    /**
     * Get certificate ID (transparent mode only)
     * @returns Certificate ID or undefined
     */
    getCertificateId(): string | undefined;
    /**
     * Get tenant ID (explicit mode only)
     * @returns Tenant ID or undefined
     */
    getTenantId(): string | undefined;
    /**
     * Enforce contract guardrails on AI input/output
     * Works in both explicit and transparent modes
     *
     * @param request - Enforcement request with contractId and payload
     * @returns Enforcement result with violations (if any)
     *
     * @example Explicit Mode
     * ```typescript
     * const result = await client.enforce({
     *   contractId: 'chatbot/general/us/v1.0',
     *   payload: {
     *     output: 'Your AI response here'
     *   }
     * });
     * ```
     *
     * @example Transparent Mode
     * ```typescript
     * // Transparent mode typically doesn't use enforce() directly
     * // Instead, use getTransparentProxyURL() with standard SDKs
     * ```
     */
    enforce(request: EnforcementRequest): Promise<EnforcementResponse>;
    /**
     * Register a new AI service for safety certification
     *
     * @param service - Service details
     * @returns Registration response with evaluation ID
     *
     * @example
     * ```typescript
     * const result = await client.registerService({
     *   name: 'customer-support-bot',
     *   description: 'AI chatbot for customer support',
     *   domain: 'general',
     *   region: 'us'
     * });
     *
     * console.log('Evaluation ID:', result.evaluationId);
     * ```
     */
    registerService(service: ServiceRegistration): Promise<RegistrationResponse>;
    /**
     * Get evaluation results for a registered service
     *
     * @param evaluationId - Evaluation ID from registration
     * @returns Evaluation results
     */
    getEvaluationResults(evaluationId: string): Promise<any>;
    /**
     * Approve a certificate after reviewing evaluation results
     *
     * @param evaluationId - Evaluation ID to approve
     * @param notes - Optional approval notes
     * @returns Approval response with contract ID
     */
    approveCertificate(evaluationId: string, notes?: string): Promise<any>;
}
//# sourceMappingURL=client.d.ts.map