@adaptic/lumic-utils 1.0.8 → 1.0.10

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

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

@@ -1,8 +0,0 @@
-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

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

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

@@ -1,58 +0,0 @@
-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

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

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

@@ -1,44 +0,0 @@
-/**
- * Default timeout values (in milliseconds) for external service calls.
- * These values help prevent hanging requests and provide predictable failure behavior.
- */
-/**
- * Slack API timeout: 5 seconds
- * Used for Slack message posting operations
- */
-export declare const SLACK_TIMEOUT_MS = 5000;
-/**
- * Perplexity API timeout: 30 seconds
- * Used for Perplexity AI API completion requests
- */
-export declare const PERPLEXITY_TIMEOUT_MS = 30000;
-/**
- * Google Sheets API timeout: 15 seconds
- * Used for Google Sheets read/write operations
- */
-export declare const GOOGLE_SHEETS_TIMEOUT_MS = 15000;
-/**
- * LLM API timeout: 120 seconds (2 minutes)
- * Used for OpenAI and Deepseek completion requests
- */
-export declare const LLM_TIMEOUT_MS = 120000;
-/**
- * AWS Lambda timeout: 60 seconds (1 minute)
- * Used for Lambda function invocations
- */
-export declare const AWS_LAMBDA_TIMEOUT_MS = 60000;
-/**
- * AWS S3 timeout: 30 seconds
- * Used for S3 operations (upload, download, list, etc.)
- */
-export declare const AWS_S3_TIMEOUT_MS = 30000;
-/**
- * OpenWeather API timeout: 10 seconds
- * Used for weather data fetching
- */
-export declare const OPENWEATHER_TIMEOUT_MS = 10000;
-/**
- * Generic fetch timeout: 30 seconds
- * Used for generic HTTP fetch operations (e.g., PDF image fetching)
- */
-export declare const GENERIC_FETCH_TIMEOUT_MS = 30000;