@adaptic/lumic-utils 1.0.8 → 1.0.9

package/dist/types/schemas/perplexity-schemas.d.ts

@@ -1,338 +0,0 @@
-import { z } from 'zod';
-/**
- * Zod schema for a complete Perplexity API response.
- * Validates the core fields that lumic-utils depends on.
- * Uses .passthrough() to allow additional fields from newer API versions.
- */
-export declare const perplexityResponseSchema: z.ZodObject<{
-    id: z.ZodString;
-    model: z.ZodString;
-    object: z.ZodString;
-    created: z.ZodNumber;
-    choices: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        finish_reason: z.ZodNullable<z.ZodEnum<["stop", "length", "model_length"]>>;
-        message: z.ZodObject<{
-            role: z.ZodEnum<["assistant"]>;
-            content: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            role: "assistant";
-            content: string;
-        }, {
-            role: "assistant";
-            content: string;
-        }>;
-        delta: z.ZodOptional<z.ZodObject<{
-            role: z.ZodOptional<z.ZodString>;
-            content: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }>, "many">;
-    usage: z.ZodOptional<z.ZodObject<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">>>;
-    citations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    id: z.ZodString;
-    model: z.ZodString;
-    object: z.ZodString;
-    created: z.ZodNumber;
-    choices: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        finish_reason: z.ZodNullable<z.ZodEnum<["stop", "length", "model_length"]>>;
-        message: z.ZodObject<{
-            role: z.ZodEnum<["assistant"]>;
-            content: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            role: "assistant";
-            content: string;
-        }, {
-            role: "assistant";
-            content: string;
-        }>;
-        delta: z.ZodOptional<z.ZodObject<{
-            role: z.ZodOptional<z.ZodString>;
-            content: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }>, "many">;
-    usage: z.ZodOptional<z.ZodObject<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">>>;
-    citations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    id: z.ZodString;
-    model: z.ZodString;
-    object: z.ZodString;
-    created: z.ZodNumber;
-    choices: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        finish_reason: z.ZodNullable<z.ZodEnum<["stop", "length", "model_length"]>>;
-        message: z.ZodObject<{
-            role: z.ZodEnum<["assistant"]>;
-            content: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            role: "assistant";
-            content: string;
-        }, {
-            role: "assistant";
-            content: string;
-        }>;
-        delta: z.ZodOptional<z.ZodObject<{
-            role: z.ZodOptional<z.ZodString>;
-            content: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }>, "many">;
-    usage: z.ZodOptional<z.ZodObject<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">>>;
-    citations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
-/** Type inferred from the Perplexity response schema */
-export type PerplexityResponse = z.infer<typeof perplexityResponseSchema>;
-/** Strict validator for Perplexity API responses. Throws on failure. */
-export declare const validatePerplexityResponse: (data: unknown) => z.objectInputType<{
-    id: z.ZodString;
-    model: z.ZodString;
-    object: z.ZodString;
-    created: z.ZodNumber;
-    choices: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        finish_reason: z.ZodNullable<z.ZodEnum<["stop", "length", "model_length"]>>;
-        message: z.ZodObject<{
-            role: z.ZodEnum<["assistant"]>;
-            content: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            role: "assistant";
-            content: string;
-        }, {
-            role: "assistant";
-            content: string;
-        }>;
-        delta: z.ZodOptional<z.ZodObject<{
-            role: z.ZodOptional<z.ZodString>;
-            content: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }>, "many">;
-    usage: z.ZodOptional<z.ZodObject<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">>>;
-    citations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">;
-/** Safe validator for Perplexity API responses. Never throws. */
-export declare const safeValidatePerplexityResponse: (data: unknown) => import("./validation-helpers").ValidationResult<z.objectInputType<{
-    id: z.ZodString;
-    model: z.ZodString;
-    object: z.ZodString;
-    created: z.ZodNumber;
-    choices: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        finish_reason: z.ZodNullable<z.ZodEnum<["stop", "length", "model_length"]>>;
-        message: z.ZodObject<{
-            role: z.ZodEnum<["assistant"]>;
-            content: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            role: "assistant";
-            content: string;
-        }, {
-            role: "assistant";
-            content: string;
-        }>;
-        delta: z.ZodOptional<z.ZodObject<{
-            role: z.ZodOptional<z.ZodString>;
-            content: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }, {
-            role?: string | undefined;
-            content?: string | undefined;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }, {
-        message: {
-            role: "assistant";
-            content: string;
-        };
-        index: number;
-        finish_reason: "length" | "stop" | "model_length" | null;
-        delta?: {
-            role?: string | undefined;
-            content?: string | undefined;
-        } | undefined;
-    }>, "many">;
-    usage: z.ZodOptional<z.ZodObject<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        prompt_tokens: z.ZodNumber;
-        completion_tokens: z.ZodNumber;
-        total_tokens: z.ZodNumber;
-    }, z.ZodTypeAny, "passthrough">>>;
-    citations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, z.ZodTypeAny, "passthrough">>;

package/dist/types/schemas/validation-helpers.d.ts

@@ -1,33 +0,0 @@
-import { z } from 'zod';
-/**
- * Result of a safe validation attempt.
- * On success, contains the parsed data. On failure, contains the error details.
- */
-export interface ValidationResult<T> {
-    success: boolean;
-    data?: T;
-    error?: string;
-    issues?: Array<{
-        path: string;
-        message: string;
-    }>;
-}
-/**
- * Creates a strict validator function for a Zod schema.
- * Throws on validation failure with a descriptive error message.
- *
- * @param schema - The Zod schema to validate against
- * @param serviceName - Human-readable service name for error messages
- * @returns A validator function that parses and returns typed data
- */
-export declare function createValidator<T>(schema: z.ZodType<T>, serviceName: string): (data: unknown) => T;
-/**
- * Creates a safe validator function for a Zod schema.
- * Never throws; returns a ValidationResult with success/failure information.
- * On failure, logs a warning but does not throw.
- *
- * @param schema - The Zod schema to validate against
- * @param serviceName - Human-readable service name for log messages
- * @returns A safe validator function that returns a ValidationResult
- */
-export declare function createSafeValidator<T>(schema: z.ZodType<T>, serviceName: string): (data: unknown) => ValidationResult<T>;

package/dist/types/utils/__tests__/circuit-breaker.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/correlation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/input-validator.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/llm-cost-tracker.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/logger.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/metrics.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/retry.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/sanitizer.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/__tests__/timeouts.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/utils/circuit-breaker.d.ts

@@ -1,99 +0,0 @@
-/**
- * Possible states for a circuit breaker
- */
-export declare enum CircuitBreakerState {
-    CLOSED = "CLOSED",
-    OPEN = "OPEN",
-    HALF_OPEN = "HALF_OPEN"
-}
-/**
- * Configuration for the circuit breaker
- */
-export interface CircuitBreakerConfig {
-    /** Number of failures before the circuit opens (default: 5) */
-    failureThreshold: number;
-    /** Time in milliseconds before attempting recovery from OPEN state (default: 30000) */
-    resetTimeoutMs: number;
-    /** Number of consecutive successes in HALF_OPEN required to close the circuit (default: 3) */
-    successThreshold: number;
-}
-/**
- * Callback invoked when the circuit breaker changes state
- */
-export type CircuitBreakerStateChangeCallback = (from: CircuitBreakerState, to: CircuitBreakerState, serviceName: string) => void;
-/**
- * Default circuit breaker configuration
- */
-export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig;
-/**
- * Error thrown when a circuit breaker is open and rejecting calls
- */
-export declare class CircuitBreakerOpenError extends Error {
-    readonly serviceName: string;
-    readonly resetTimeoutMs: number;
-    constructor(serviceName: string, resetTimeoutMs: number);
-}
-/**
- * Generic circuit breaker implementation for external service calls.
- *
- * The circuit breaker monitors failures and transitions through three states:
- * - CLOSED: Normal operation. Calls pass through. Failures are counted.
- * - OPEN: Too many failures. Calls are rejected immediately without executing.
- * - HALF_OPEN: After a reset timeout, allows a limited number of trial calls
- *   to test whether the service has recovered.
- *
- * @example
- * const breaker = new CircuitBreaker('slack-api');
- * const result = await breaker.execute(() => sendSlackMessage(channel, msg));
- */
-export declare class CircuitBreaker {
-    readonly serviceName: string;
-    private state;
-    private failureCount;
-    private successCount;
-    private lastFailureTime;
-    private readonly config;
-    private onStateChange;
-    constructor(serviceName: string, config?: Partial<CircuitBreakerConfig>, onStateChange?: CircuitBreakerStateChangeCallback);
-    /**
-     * Returns the current state of the circuit breaker.
-     */
-    getState(): CircuitBreakerState;
-    /**
-     * Returns the current failure count.
-     */
-    getFailureCount(): number;
-    /**
-     * Returns the current success count (relevant in HALF_OPEN state).
-     */
-    getSuccessCount(): number;
-    /**
-     * Resets the circuit breaker to its initial CLOSED state.
-     */
-    reset(): void;
-    /**
-     * Executes the provided function through the circuit breaker.
-     *
-     * - In CLOSED state: executes normally, tracking failures.
-     * - In OPEN state: rejects immediately with CircuitBreakerOpenError
-     *   unless the reset timeout has elapsed, in which case it transitions to HALF_OPEN.
-     * - In HALF_OPEN state: allows trial calls, tracking successes to decide
-     *   whether to close or re-open the circuit.
-     *
-     * @template T - The return type of the wrapped function
-     * @param fn - The async function to execute
-     * @returns The result of the function call
-     * @throws CircuitBreakerOpenError if the circuit is open
-     * @throws The original error if the function call fails
-     */
-    execute<T>(fn: () => Promise<T>): Promise<T>;
-    /**
-     * Sets or replaces the state change callback.
-     */
-    setOnStateChange(callback: CircuitBreakerStateChangeCallback): void;
-    private shouldAttemptReset;
-    private onSuccess;
-    private onFailure;
-    private transitionTo;
-    private notifyStateChange;
-}

package/dist/types/utils/correlation.d.ts

@@ -1,43 +0,0 @@
-/**
- * Correlation context stored in AsyncLocalStorage.
- * Propagates automatically through async call chains.
- */
-export interface CorrelationContext {
-    /** Unique correlation ID for request tracing */
-    correlationId: string;
-    /** Additional metadata to propagate */
-    metadata?: Record<string, string>;
-}
-/**
- * Generates a new unique correlation ID.
- * Uses crypto.randomUUID for high-quality UUIDs.
- * @returns A new UUID string
- */
-export declare function generateCorrelationId(): string;
-/**
- * Returns the current correlation ID from AsyncLocalStorage, or undefined if none is set.
- * @returns The current correlation ID or undefined
- */
-export declare function getCorrelationId(): string | undefined;
-/**
- * Returns the full correlation context, or undefined if none is set.
- * @returns The current CorrelationContext or undefined
- */
-export declare function getCorrelationContext(): CorrelationContext | undefined;
-/**
- * Runs a function within a correlation context.
- * All async operations within the callback will have access to the correlation ID.
- *
- * @param fn - The function to run within the context
- * @param correlationId - Optional correlation ID. If not provided, one is generated.
- * @param metadata - Optional metadata to attach to the context
- * @returns The return value of the function
- */
-export declare function withCorrelationId<T>(fn: () => T, correlationId?: string, metadata?: Record<string, string>): T;
-/**
- * Returns headers object with the correlation ID for external HTTP calls.
- * Returns an empty object if no correlation context is active.
- * @param headerName - The header name to use (default: 'x-correlation-id')
- * @returns Headers object with correlation ID
- */
-export declare function getCorrelationHeaders(headerName?: string): Record<string, string>;

package/dist/types/utils/health-check.d.ts

@@ -1,50 +0,0 @@
-/**
- * Status of an individual integration health check.
- */
-export interface IntegrationHealthStatus {
-    /** Name of the integration being checked */
-    service: string;
-    /** Whether the integration is reachable */
-    healthy: boolean;
-    /** Human-readable status message */
-    message: string;
-    /** Time taken to check in milliseconds */
-    latencyMs: number;
-    /** Error details if unhealthy */
-    error?: string;
-}
-/**
- * Overall health check result for all configured integrations.
- */
-export interface HealthCheckResult {
-    /** Whether all checked integrations are healthy */
-    healthy: boolean;
-    /** Timestamp of the health check */
-    timestamp: string;
-    /** Individual integration statuses */
-    integrations: IntegrationHealthStatus[];
-    /** Total time taken for all checks in milliseconds */
-    totalLatencyMs: number;
-}
-/**
- * Runs health checks for all configured integrations.
- *
- * Checks credential configuration for each external service. Does not make
- * actual API calls (to avoid side effects and rate limit consumption).
- * For connectivity verification, consumers should use the individual service
- * functions with appropriate error handling.
- *
- * @param services - Optional list of service names to check. If omitted, checks all.
- * @returns Health check result with individual integration statuses
- *
- * @example
- * const result = await checkIntegrationHealth();
- * if (!result.healthy) {
- *   console.error('Unhealthy integrations:', result.integrations.filter(i => !i.healthy));
- * }
- *
- * @example
- * // Check specific services only
- * const result = await checkIntegrationHealth(['openai', 'slack']);
- */
-export declare function checkIntegrationHealth(services?: string[]): Promise<HealthCheckResult>;

package/dist/types/utils/input-validator.d.ts

@@ -1,51 +0,0 @@
-/**
- * Input validation utilities to prevent injection and traversal attacks
- * on external service inputs (Slack, S3, Google Sheets).
- */
-/**
- * Result of a validation check
- */
-export interface ValidationResult {
-    valid: boolean;
-    error?: string;
-}
-/**
- * Validates a Slack channel name format.
- *
- * Valid channel names:
- * - May optionally start with '#'
- * - Must start with a lowercase letter or number (after optional '#')
- * - May contain lowercase letters, numbers, hyphens, and underscores
- * - Must be between 1 and 80 characters (excluding optional '#' prefix)
- *
- * @param channel - The channel name to validate
- * @returns ValidationResult indicating whether the channel name is valid
- */
-export declare function validateSlackChannel(channel: string): ValidationResult;
-/**
- * Validates an S3 key to prevent directory traversal and other attacks.
- *
- * Invalid keys:
- * - Contain '..' (directory traversal)
- * - Start with '/' (absolute paths)
- * - Contain null bytes
- * - Are empty
- * - Exceed 1024 characters (S3 key limit)
- *
- * @param key - The S3 key to validate
- * @returns ValidationResult indicating whether the key is valid
- */
-export declare function validateS3Key(key: string): ValidationResult;
-/**
- * Validates a Google Sheets A1 notation range.
- *
- * Valid formats:
- * - Simple cell: 'A1', 'B2', 'AA100'
- * - Cell range: 'A1:B10', 'A1:Z999'
- * - With sheet name: 'Sheet1!A1', 'Sheet1!A1:B10'
- * - With quoted sheet name: "'My Sheet'!A1:B10"
- *
- * @param range - The A1 notation string to validate
- * @returns ValidationResult indicating whether the range is valid
- */
-export declare function validateGoogleSheetsRange(range: string): ValidationResult;