@adaptic/lumic-utils 1.0.6 → 1.0.8

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

@@ -0,0 +1,99 @@
+/**
+ * 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

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+/**
+ * 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

@@ -0,0 +1,51 @@
+/**
+ * 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;

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

@@ -0,0 +1,174 @@
+/**
+ * Usage record for a single LLM call
+ */
+export interface LLMUsageRecord {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheHitTokens: number;
+    cost: number;
+    timestamp: number;
+}
+/**
+ * Image generation usage record
+ */
+export interface ImageUsageRecord {
+    model: string;
+    imageCount: number;
+    cost: number;
+    timestamp: number;
+}
+/**
+ * Aggregated cost data for a single model
+ */
+export interface ModelCostSummary {
+    provider: string;
+    model: string;
+    totalCost: number;
+    callCount: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalReasoningTokens: number;
+    totalCacheHitTokens: number;
+}
+/**
+ * Aggregated cost data for image generation by model
+ */
+export interface ImageCostSummary {
+    model: string;
+    totalCost: number;
+    totalImages: number;
+    callCount: number;
+}
+/**
+ * Complete cost summary across all models and providers
+ */
+export interface CostSummary {
+    totalCost: number;
+    totalCalls: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalReasoningTokens: number;
+    byModel: Record<string, ModelCostSummary>;
+    images: Record<string, ImageCostSummary>;
+    startTime: number;
+    endTime: number;
+}
+/**
+ * Formatted cost summary for display
+ */
+export interface FormattedCostSummary {
+    totalCost: string;
+    totalCalls: number;
+    totalTokens: number;
+    duration: string;
+    models: Array<{
+        model: string;
+        provider: string;
+        cost: string;
+        calls: number;
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+    images: Array<{
+        model: string;
+        cost: string;
+        images: number;
+        calls: number;
+    }>;
+}
+/**
+ * Tracks and accumulates LLM usage costs across all providers and models.
+ *
+ * This class provides a centralized way to monitor LLM spending,
+ * aggregating costs by model and provider. It can be used by consumers
+ * (such as the engine) to build cost dashboards and spending reports.
+ *
+ * @example
+ * import { LLMCostTracker } from '@adaptic/lumic-utils';
+ *
+ * const tracker = getLLMCostTracker();
+ * // ... make LLM calls (cost tracking is automatic when wired in) ...
+ * const summary = tracker.getCostSummary();
+ * console.log(`Total cost: $${summary.totalCost}`);
+ */
+export declare class LLMCostTracker {
+    private usageRecords;
+    private imageRecords;
+    private startTime;
+    /**
+     * Records usage from an LLM call.
+     *
+     * @param provider - The LLM provider ('openai' or 'deepseek')
+     * @param model - The model name (e.g., 'gpt-5', 'deepseek-chat')
+     * @param inputTokens - Number of input/prompt tokens
+     * @param outputTokens - Number of output/completion tokens
+     * @param reasoningTokens - Number of reasoning tokens (default: 0)
+     * @param cacheHitTokens - Number of cache hit tokens (default: 0)
+     */
+    trackUsage(provider: string, model: string, inputTokens: number, outputTokens: number, reasoningTokens?: number, cacheHitTokens?: number): void;
+    /**
+     * Records usage from an image generation call.
+     *
+     * @param model - The image model name (e.g., 'gpt-image-1')
+     * @param imageCount - Number of images generated
+     */
+    trackImageUsage(model: string, imageCount: number): void;
+    /**
+     * Returns accumulated costs aggregated by model.
+     *
+     * @returns Record of model name to ModelCostSummary
+     */
+    getCosts(): Record<string, ModelCostSummary>;
+    /**
+     * Returns accumulated image generation costs aggregated by model.
+     *
+     * @returns Record of model name to ImageCostSummary
+     */
+    getImageCosts(): Record<string, ImageCostSummary>;
+    /**
+     * Returns a complete cost summary across all models and providers.
+     *
+     * @returns CostSummary with totals and per-model breakdowns
+     */
+    getCostSummary(): CostSummary;
+    /**
+     * Returns a human-readable formatted cost summary.
+     *
+     * @returns FormattedCostSummary with dollar amounts and readable durations
+     */
+    getFormattedCostSummary(): FormattedCostSummary;
+    /**
+     * Resets all accumulated cost data and restarts the tracking period.
+     */
+    resetCosts(): void;
+    /**
+     * Returns the total number of tracked LLM calls (not including images).
+     */
+    getCallCount(): number;
+    /**
+     * Returns the total number of tracked image generation calls.
+     */
+    getImageCallCount(): number;
+}
+/**
+ * Returns the global LLM cost tracker instance.
+ * Use this for application-wide cost tracking.
+ *
+ * @returns The global LLMCostTracker instance
+ */
+export declare function getLLMCostTracker(): LLMCostTracker;
+/**
+ * Replaces the global LLM cost tracker instance.
+ * Useful for testing or providing a custom implementation.
+ *
+ * @param tracker - The new LLMCostTracker instance to use
+ */
+export declare function setLLMCostTracker(tracker: LLMCostTracker): void;
+/**
+ * Resets the global LLM cost tracker to a fresh instance.
+ * Convenience function equivalent to `setLLMCostTracker(new LLMCostTracker())`.
+ */
+export declare function resetLLMCostTracker(): void;

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

@@ -0,0 +1,8 @@
+export interface LumicLogger {
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+}
+export declare function setLumicLogger(logger: LumicLogger): void;
+export declare function getLumicLogger(): LumicLogger;

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

@@ -0,0 +1,61 @@
+/**
+ * Interface for collecting metrics from lumic-utils operations.
+ * Consumers (e.g., engine) can inject a real implementation (Prometheus, etc.)
+ * while the default no-op implementation ensures zero overhead when not needed.
+ */
+export interface MetricsCollector {
+    /**
+     * Increment a counter for a given operation.
+     * @param service - The service name (e.g., 'slack', 'llm', 'aws-s3')
+     * @param operation - The operation name (e.g., 'sendMessage', 'createCompletion')
+     * @param labels - Additional labels (e.g., { status: 'success' })
+     */
+    incrementCounter(service: string, operation: string, labels?: Record<string, string>): void;
+    /**
+     * Record a latency measurement for a given operation.
+     * @param service - The service name
+     * @param operation - The operation name
+     * @param durationMs - Duration in milliseconds
+     * @param labels - Additional labels
+     */
+    recordLatency(service: string, operation: string, durationMs: number, labels?: Record<string, string>): void;
+    /**
+     * Increment the error counter for a given operation.
+     * @param service - The service name
+     * @param operation - The operation name
+     * @param errorType - The type/code of the error
+     */
+    incrementError(service: string, operation: string, errorType: string): void;
+    /**
+     * Increment the retry counter for a given operation.
+     * @param service - The service name
+     * @param operation - The operation name
+     */
+    incrementRetry(service: string, operation: string): void;
+}
+/**
+ * Sets the global metrics collector.
+ * Call this during application bootstrap to inject a real collector.
+ * @param collector - The MetricsCollector implementation to use
+ */
+export declare function setMetricsCollector(collector: MetricsCollector): void;
+/**
+ * Returns the current metrics collector.
+ * @returns The active MetricsCollector instance
+ */
+export declare function getMetricsCollector(): MetricsCollector;
+/**
+ * Resets the metrics collector to the default no-op implementation.
+ * Useful for testing.
+ */
+export declare function resetMetricsCollector(): void;
+/**
+ * Wraps an async function with automatic metrics collection.
+ * Records call count, latency, errors, and retries.
+ *
+ * @param service - The service name for metrics labels
+ * @param operation - The operation name for metrics labels
+ * @param fn - The async function to wrap
+ * @returns The result of the wrapped function
+ */
+export declare function withMetrics<T>(service: string, operation: string, fn: () => Promise<T>): Promise<T>;

package/dist/types/utils/rate-limiter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Token bucket rate limiter configuration.
+ */
+export interface RateLimiterConfig {
+    /** Maximum number of tokens in the bucket */
+    maxTokens: number;
+    /** Number of tokens refilled per interval */
+    refillRate: number;
+    /** Refill interval in milliseconds */
+    refillIntervalMs: number;
+}
+/**
+ * Pre-configured rate limit profiles for known external APIs.
+ * These defaults are conservative estimates based on published API rate limits.
+ * Consumers can override with custom configurations.
+ */
+export declare const RATE_LIMIT_PROFILES: Record<string, RateLimiterConfig>;
+/**
+ * Token bucket rate limiter.
+ *
+ * Implements the token bucket algorithm for client-side rate limiting.
+ * Each API call consumes one token. Tokens are refilled at a configurable rate.
+ * When the bucket is empty, callers must wait for tokens to become available.
+ *
+ * @example
+ * const limiter = new TokenBucketRateLimiter(RATE_LIMIT_PROFILES.openai);
+ * await limiter.acquire(); // Waits if necessary
+ * const result = await callOpenAI();
+ */
+export declare class TokenBucketRateLimiter {
+    private tokens;
+    private readonly maxTokens;
+    private readonly refillRate;
+    private readonly refillIntervalMs;
+    private lastRefillTime;
+    private readonly name;
+    constructor(config: RateLimiterConfig, name?: string);
+    /**
+     * Refills tokens based on elapsed time since last refill.
+     * Tokens accumulate proportionally to elapsed time.
+     */
+    private refill;
+    /**
+     * Attempts to acquire a token without waiting.
+     * @returns true if a token was acquired, false if the bucket is empty
+     */
+    tryAcquire(): boolean;
+    /**
+     * Acquires a token, waiting if necessary until one becomes available.
+     * Logs a warning when rate limiting is active.
+     *
+     * @param maxWaitMs - Maximum time to wait in milliseconds (default: 30000)
+     * @throws Error if the maximum wait time is exceeded
+     */
+    acquire(maxWaitMs?: number): Promise<void>;
+    /** Returns the current number of available tokens */
+    get availableTokens(): number;
+    /** Resets the bucket to full capacity */
+    reset(): void;
+}
+/**
+ * Returns the rate limiter for a given service.
+ * Creates one using the default profile if it doesn't exist.
+ *
+ * @param service - Service name (must match a key in RATE_LIMIT_PROFILES or custom config must be provided)
+ * @param config - Optional custom configuration (overrides the default profile)
+ * @returns The TokenBucketRateLimiter for the service
+ */
+export declare function getRateLimiter(service: string, config?: RateLimiterConfig): TokenBucketRateLimiter;
+/**
+ * Resets all rate limiters. Useful for testing.
+ */
+export declare function resetAllRateLimiters(): void;
+/**
+ * Wraps an async function with automatic rate limiting.
+ *
+ * @param service - Service name for rate limit lookup
+ * @param fn - The async function to rate-limit
+ * @param config - Optional custom rate limit configuration
+ * @returns The result of the wrapped function
+ *
+ * @example
+ * const result = await withRateLimit('openai', () => callOpenAI());
+ */
+export declare function withRateLimit<T>(service: string, fn: () => Promise<T>, config?: RateLimiterConfig): Promise<T>;

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

@@ -0,0 +1,58 @@
+import { CircuitBreaker } from './circuit-breaker';
+/**
+ * Configuration for retry mechanism with exponential backoff
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors?: (error: unknown) => boolean;
+    /** Optional circuit breaker to check before each attempt */
+    circuitBreaker?: CircuitBreaker;
+}
+/**
+ * Default retry configuration
+ * - 3 retries maximum
+ * - 1 second base delay
+ * - 30 second max delay
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Executes a function with retry logic using exponential backoff.
+ *
+ * This utility provides automatic retry handling for transient failures in external API calls.
+ * It implements exponential backoff with jitter to avoid thundering herd problems.
+ *
+ * @example
+ * // Basic usage
+ * const result = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   {},
+ *   'API Call'
+ * );
+ *
+ * @example
+ * // With custom retry logic
+ * const result = await withRetry(
+ *   () => makeApiCall(),
+ *   {
+ *     maxRetries: 5,
+ *     baseDelayMs: 2000,
+ *     retryableErrors: (error) => {
+ *       if (error instanceof Error) {
+ *         return error.message.includes('rate limit');
+ *       }
+ *       return false;
+ *     }
+ *   },
+ *   'Custom API'
+ * );
+ *
+ * @template T - The return type of the function being retried
+ * @param fn - The function to execute and retry if needed. Must return a Promise.
+ * @param config - Partial retry configuration to override defaults
+ * @param label - Descriptive label for logging purposes (default: 'unknown')
+ * @returns Promise<T> - Resolves with the result of the function if successful
+ * @throws The last error encountered if all retry attempts fail or if a non-retryable error occurs
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, label?: string): Promise<T>;

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

@@ -0,0 +1,30 @@
+/**
+ * Sanitizes sensitive values for logging by showing only a few visible characters
+ * @param value The sensitive value to sanitize
+ * @param visibleChars Number of characters to show before masking (default: 4)
+ * @returns A sanitized string safe for logging
+ */
+export declare function sanitizeForLog(value: string, visibleChars?: number): string;
+/**
+ * Sanitizes error messages by removing sensitive credentials and tokens
+ * @param error The error to sanitize
+ * @returns A sanitized error message safe for logging
+ */
+export declare function sanitizeError(error: unknown): string;
+/**
+ * Sanitizes AWS credentials for logging
+ * @param auth AWS auth object or null
+ * @returns Sanitized string representation safe for logging
+ */
+export declare function sanitizeAWSAuth(auth: {
+    AWS_ACCESS_KEY_ID?: string;
+    AWS_SECRET_ACCESS_KEY?: string;
+    AWS_REGION?: string;
+} | null): string;
+/**
+ * Sanitizes an object by removing or masking sensitive fields
+ * @param obj The object to sanitize
+ * @param sensitiveFields Array of field names to mask
+ * @returns A new sanitized object safe for logging
+ */
+export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T, sensitiveFields?: string[]): Record<string, unknown>;