@adaptic/lumic-utils 1.0.5 → 1.0.8

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

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

@@ -0,0 +1,33 @@
+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/types/aws-types.d.ts

@@ -29,7 +29,7 @@ export interface SaveToS3Response {
 }
 export interface LoadFromS3Response {
     success: boolean;
-    content?: any;
+    content?: unknown;
     error?: string;
 }
 export interface CheckBucketResponse {

package/dist/types/types/google-types.d.ts

@@ -10,15 +10,17 @@ export interface GoogleSheetRange {
     startCell: GoogleSheetCell;
     endCell: GoogleSheetCell;
 }
+/** Represents a primitive value that can be stored in a Google Sheet cell */
+export type GoogleSheetCellValue = string | number | boolean | null;
 export interface GoogleSheetResponse {
     success: boolean;
     error?: string;
-    data?: any;
+    data?: unknown;
 }
 export interface GoogleSheetAddRowResponse extends GoogleSheetResponse {
     data?: {
         rowNumber: number;
-        values: any[];
+        values: GoogleSheetCellValue[];
     };
 }
 export interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
@@ -29,7 +31,7 @@ export interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
 }
 export interface GoogleSheetCellResponse extends GoogleSheetResponse {
     data?: {
-        value: any;
+        value: GoogleSheetCellValue;
     };
 }
 export interface GoogleSheetWriteArrayResponse extends GoogleSheetResponse {

package/dist/types/types/index.d.ts

@@ -20,7 +20,7 @@ export interface PerplexityResponse {
 export type InvocationType = 'RequestResponse' | 'Event' | 'DryRun';
 export interface LambdaResponse {
     statusCode: number;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface SlackApiResponse {
     ok: boolean;

package/dist/types/types/openai-types.d.ts

@@ -1,17 +1,158 @@
 import { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionMessageToolCall } from 'openai/resources/chat/completions';
 import { ImageGenerateParams } from 'openai/resources/images';
+/**
+ * Model capability configuration
+ */
+interface ModelCapabilities {
+    provider: 'openai' | 'deepseek';
+    supportsTools: boolean;
+    supportsJson: boolean;
+    supportsStructuredOutput: boolean;
+    supportsDeveloperPrompt: boolean;
+    supportsTemperature: boolean;
+    isReasoningModel: boolean;
+}
+/**
+ * Supported models with their capabilities
+ */
+export declare const SUPPORTED_MODELS: {
+    readonly 'gpt-5': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly 'gpt-5-mini': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly 'gpt-4.1': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly 'gpt-4.1-mini': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly 'gpt-4.1-nano': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly o1: {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: false;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: false;
+        readonly isReasoningModel: true;
+    };
+    readonly 'o1-mini': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: false;
+        readonly supportsStructuredOutput: false;
+        readonly supportsDeveloperPrompt: false;
+        readonly supportsTemperature: false;
+        readonly isReasoningModel: true;
+    };
+    readonly o3: {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: false;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: false;
+        readonly isReasoningModel: true;
+    };
+    readonly 'o3-mini': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: false;
+        readonly isReasoningModel: true;
+    };
+    readonly 'o4-mini': {
+        readonly provider: "openai";
+        readonly supportsTools: true;
+        readonly supportsJson: false;
+        readonly supportsStructuredOutput: true;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: false;
+        readonly isReasoningModel: true;
+    };
+    readonly 'deepseek-chat': {
+        readonly provider: "deepseek";
+        readonly supportsTools: true;
+        readonly supportsJson: true;
+        readonly supportsStructuredOutput: false;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: false;
+    };
+    readonly 'deepseek-reasoner': {
+        readonly provider: "deepseek";
+        readonly supportsTools: false;
+        readonly supportsJson: false;
+        readonly supportsStructuredOutput: false;
+        readonly supportsDeveloperPrompt: true;
+        readonly supportsTemperature: true;
+        readonly isReasoningModel: true;
+    };
+};
+/**
+ * Represents all supported LLM models
+ */
+export type SupportedModel = keyof typeof SUPPORTED_MODELS;
 /**
  * Represents OpenAI models
  */
-export type OpenAIModel = 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano';
+export type OpenAIModel = Extract<SupportedModel, 'gpt-5' | 'gpt-5-mini' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'o1' | 'o1-mini' | 'o3' | 'o3-mini' | 'o4-mini'>;
 /**
  * Represents Deepseek models
  */
-export type DeepseekModel = 'deepseek-chat' | 'deepseek-reasoner';
+export type DeepseekModel = Extract<SupportedModel, 'deepseek-chat' | 'deepseek-reasoner'>;
 /**
  * Represents all supported LLM models
  */
 export type LLMModel = OpenAIModel | DeepseekModel;
+/**
+ * Type guard to check if a string is a valid supported model
+ * @param model The model name to validate
+ * @returns True if the model is supported
+ */
+export declare function isValidModel(model: string): model is SupportedModel;
+/**
+ * Get capabilities for a supported model
+ * @param model The model to get capabilities for
+ * @returns Model capabilities object
+ */
+export declare function getModelCapabilities(model: SupportedModel): Readonly<ModelCapabilities>;
 /**
  * Represents the usage of the LLM.
  */
@@ -43,6 +184,11 @@ export interface LLMOptions {
     parallel_tool_calls?: boolean;
     service_tier?: 'auto' | 'default';
     apiKey?: string;
+    /**
+     * Request timeout in milliseconds. Overrides the default LLM_TIMEOUT_MS (120000ms).
+     * Applied to the OpenAI/Deepseek SDK client for the request.
+     */
+    timeout?: number;
 }
 /**
  * Represents the response from the LLM.
@@ -59,7 +205,7 @@ export type OpenAIResponseFormat = 'text' | 'json' | {
     type: 'json_schema';
     schema: {
         type: 'object';
-        properties: Record<string, any>;
+        properties: Record<string, unknown>;
         required?: string[];
     };
 };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/types/utils/aws-initialise.d.ts

@@ -18,4 +18,9 @@ interface AWSAuth {
 declare const validateEnvironmentVars: () => ValidationResult;
 declare const initialiseS3Client: (auth?: AWSAuth | null) => S3Client;
 declare const initialiseLambdaClient: (auth?: AWSAuth | null) => Lambda;
-export { validateEnvironmentVars, initialiseS3Client, initialiseLambdaClient, AWSAuth };
+/**
+ * Clears all cached AWS client instances.
+ * Useful for testing or when credentials need to be refreshed.
+ */
+declare const clearClientCache: () => void;
+export { validateEnvironmentVars, initialiseS3Client, initialiseLambdaClient, clearClientCache, AWSAuth };