@adaptic/lumic-utils 1.0.1

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

@@ -0,0 +1,22 @@
+declare const LOG_TYPES: readonly ["info", "warn", "error", "debug", "trace"];
+type LogType = typeof LOG_TYPES[number];
+/**
+ * Debug logging utility that respects environment debug flags
+ * @param message - The message to log
+ * @param data - Optional data to log alongside the message
+ * @param type - Log level. One of: 'info' | 'warn' | 'error' | 'debug' | 'trace'
+ */
+export declare const logIfDebug: (message: string, data?: unknown, type?: LogType) => void;
+/**
+ * Fetches a URL with retry logic. If the response is not 2xx, it will retry up to `retries` times
+ * with an exponential backoff of `backoff` milliseconds between each attempt.
+ *
+ * @param url The URL to fetch
+ * @param options Optional `RequestInit` object to modify the request
+ * @param retries The number of times to retry the request (default: 3)
+ * @param backoff The initial backoff time in milliseconds (default: 300)
+ * @returns A `Response` object if the fetch is successful
+ * @throws An error if the fetch fails after all retries
+ */
+export declare function fetchWithRetry(url: string, options?: RequestInit, retries?: number, backoff?: number): Promise<Response>;
+export {};

package/dist/types/functions/zip-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Creates a zip file containing the contents of the provided directory.
+ * The zip file is created in the /tmp directory.
+ * The source directory must be located in the /tmp directory.
+ * The zip file name is the same as the source directory name with a .zip extension.
+ * If a node_modules directory exists in the source directory,
+ * it is added separately to ensure it is included in the zip file.
+ * The function logs the original directory size and file count,
+ * as well as the final zip size.
+ * @param sourceDir The path to the directory to zip.
+ * @returns The path to the created zip file.
+ */
+export declare function createZipFile(sourceDir: string): Promise<string>;
+/**
+ * Extracts a zip archive into a specified directory.
+ *
+ * Both the zip file path and destination path must start with /tmp/.
+ *
+ * @param zipPath The path of the zip file to extract. Must start with /tmp/.
+ * @param destPath The path of the directory to extract the zip file into. Must start with /tmp/.
+ * @returns The path of the extracted directory.
+ * @throws If the zip file or destination path does not start with /tmp/.
+ * @throws If there is an error extracting the zip file.
+ */
+export declare function extractZipFile(zipPath: string, destPath: string): Promise<string>;
+/**
+ * Adds a file or directory to an existing zip file.
+ *
+ * The zip file path and item path must start with /tmp/.
+ *
+ * @param zipFilePath The path of the zip file to add the item to. Must start with /tmp/.
+ * @param itemPath The path of the item to add to the zip file. Must start with /tmp/.
+ * @param destPath Optional. The destination path inside the zip file to add the item to. Defaults to the root of the zip file.
+ * @returns The path of the updated zip file.
+ * @throws If the zip file or item path does not start with /tmp/.
+ * @throws If there is an error adding the item to the zip file.
+ */
+export declare function addToZipFile(zipFilePath: string, itemPath: string, destPath?: string): Promise<string>;

package/dist/types/google-types.ts

@@ -0,0 +1,48 @@
+export interface GoogleSheetConfig {
+  spreadsheetId: string;
+  sheetName: string;
+}
+
+export interface GoogleSheetCell {
+  row: number;
+  column: number;
+}
+
+export interface GoogleSheetRange {
+  startCell: GoogleSheetCell;
+  endCell: GoogleSheetCell;
+}
+
+export interface GoogleSheetResponse {
+  success: boolean;
+  error?: string;
+  data?: any;
+}
+
+export interface GoogleSheetAddRowResponse extends GoogleSheetResponse {
+  data?: {
+    rowNumber: number;
+    values: any[];
+  };
+}
+
+export interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
+  data?: {
+    sheetId: number;
+    title: string;
+  };
+}
+
+export interface GoogleSheetCellResponse extends GoogleSheetResponse {
+  data?: {
+    value: any;
+  };
+}
+
+export interface GoogleSheetWriteArrayResponse extends GoogleSheetResponse {
+  data?: {
+    updatedRange: string;
+    updatedRows: number;
+    updatedColumns: number;
+  };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,72 @@
+import { makeLLMCall, makeResponsesCall } from './functions/llm-call';
+import { makeImagesCall } from './functions/llm-images';
+import { makeDeepseekCall } from './functions/llm-deepseek';
+import { callPerplexityAPI } from './functions/perplexity-api';
+import { invokeLambdaFunction } from './functions/aws-lambda';
+import { sendMessageToSlack } from './functions/slack-utils';
+import { createZipFile, extractZipFile, addToZipFile } from './functions/zip-utils';
+import { PerformanceTimer } from './functions/performance';
+import { generateBucketName, createS3, uploadToS3, readS3File, downloadFromS3, deleteS3FileFromUrl, destroyS3, saveToS3, loadFromS3, checkBucketForFileNamePart, ls } from './functions/aws-s3-utils';
+import { logIfDebug } from './functions/utils';
+import { fixBrokenJson, isValidJson } from './functions/json-tools';
+import { fixJsonWithAI } from './functions/json-llm-tools';
+import { createPDFFromMarkdown } from './functions/pdf-create';
+import { addRow, addSheet, writeCell, getCell, writeArray } from './functions/google-sheets';
+import { parseResponse } from './functions/llm-utils';
+import { tools } from './llm-tools';
+export * from './types';
+interface LumicUtilities {
+    llm: {
+        call: typeof makeLLMCall;
+        seek: typeof makeDeepseekCall;
+        responses: typeof makeResponsesCall;
+        image: typeof makeImagesCall;
+        callPerplexity: typeof callPerplexityAPI;
+        tools: typeof tools;
+    };
+    lambda: {
+        invoke: typeof invokeLambdaFunction;
+    };
+    slack: {
+        sendMessage: typeof sendMessageToSlack;
+    };
+    pdf: {
+        create: typeof createPDFFromMarkdown;
+    };
+    zip: {
+        create: typeof createZipFile;
+        extract: typeof extractZipFile;
+        addTo: typeof addToZipFile;
+    };
+    gs: {
+        addRow: typeof addRow;
+        addSheet: typeof addSheet;
+        writeCell: typeof writeCell;
+        getCell: typeof getCell;
+        writeArray: typeof writeArray;
+    };
+    s3: {
+        generateBucketName: typeof generateBucketName;
+        create: typeof createS3;
+        upload: typeof uploadToS3;
+        readFile: typeof readS3File;
+        download: typeof downloadFromS3;
+        deleteFile: typeof deleteS3FileFromUrl;
+        destroy: typeof destroyS3;
+        saveTo: typeof saveToS3;
+        loadFrom: typeof loadFromS3;
+        checkBucketForFileNamePart: typeof checkBucketForFileNamePart;
+        ls: typeof ls;
+    };
+    json: {
+        parse: typeof parseResponse;
+        fix: typeof fixBrokenJson;
+        fixWithAI: typeof fixJsonWithAI;
+        isValid: typeof isValidJson;
+    };
+    utils: {
+        logIfDebug: typeof logIfDebug;
+        Timer: typeof PerformanceTimer;
+    };
+}
+export declare const lumic: LumicUtilities;

package/dist/types/index.ts

@@ -0,0 +1,57 @@
+export * from './openai-types';
+export * from './aws-types';
+export * from './google-types';
+
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+export type JsonArray = JsonValue[];
+
+
+export interface PerplexityMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface PerplexityResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+  }>;
+}
+
+// Export types from invokeLambdaFunction
+export type InvocationType = 'RequestResponse' | 'Event' | 'DryRun';
+
+export interface LambdaResponse {
+  statusCode: number;
+  [key: string]: any;
+}
+
+// Export types from sendMessageToSlack
+export interface SlackApiResponse {
+  ok: boolean;
+  error?: string;
+}
+
+// Re-export AWSAuth type
+export { AWSAuth } from '../utils/aws-initialise';
+
+export interface CreatePDFOptions {
+  title?: string;
+  author?: string;
+  margins?: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+  };
+}
+
+export type WeatherReturnType = {
+  temperature: number;
+  description: string;
+  location: string;
+}

package/dist/types/llm-tools.d.ts

@@ -0,0 +1,2 @@
+import { ChatCompletionTool } from 'openai/resources/chat/completions';
+export declare const tools: ChatCompletionTool[];

package/dist/types/openai-types.ts

@@ -0,0 +1,92 @@
+// openai-types.ts
+import { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionMessageToolCall } from 'openai/resources/chat/completions';
+import { ImageGenerateParams, ImageModel } from 'openai/resources/images';
+
+/**
+ * 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'
+/**
+ * Represents Deepseek models
+ */
+export type DeepseekModel = 'deepseek-chat' | 'deepseek-reasoner';
+
+/**
+ * Represents all supported LLM models
+ */
+export type LLMModel = OpenAIModel | DeepseekModel;
+
+/**
+ * Represents the usage of the LLM.
+ */
+export interface LLMUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  reasoning_tokens?: number;
+  provider: string;
+  model: LLMModel;
+  cache_hit_tokens?: number;
+  cost: number;
+}
+
+/**
+ * Represents the options for the LLM.
+ */
+export interface LLMOptions {
+  model?: OpenAIModel | DeepseekModel;
+  temperature?: number;
+  top_p?: number;
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  max_completion_tokens?: number;
+  tools?: ChatCompletionTool[];
+  developerPrompt?: string;
+  context?: ChatCompletionMessageParam[];
+  store?: boolean;
+  reasoning_effort?: 'low' | 'medium' | 'high';
+  metadata?: Record<string, string>;
+  parallel_tool_calls?: boolean;
+  service_tier?: 'auto' | 'default';
+  apiKey?: string;
+}
+
+/**
+ * Represents the response from the LLM.
+ */
+export interface LLMResponse<T> {
+  response: T;
+  usage: LLMUsage;
+  tool_calls?: ChatCompletionMessageToolCall[];
+}
+
+/**
+ * Represents the format of the OpenAI response.
+ */
+export type OpenAIResponseFormat = 'text' | 'json' | { 
+  type: 'json_schema'; 
+  schema: {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+  }
+};
+
+/**
+ * Represents the options for the OpenAI Images API.
+ * Extends the official ImageGenerateParams but with more user-friendly option names.
+ */
+export interface ImageGenerationOptions {
+  size?: ImageGenerateParams['size'];
+  outputFormat?: 'jpeg' | 'png' | 'webp';
+  compression?: number;
+  quality?: ImageGenerateParams['quality'];
+  count?: number | null;
+  apiKey?: string;
+  background?: ImageGenerateParams['background'];
+  moderation?: ImageGenerateParams['moderation'];
+}
+
+// Re-export OpenAI types for convenience
+export type { ImageModel, ImageGenerateParams } from 'openai/resources/images';
+export type { ImagesResponse, Image } from 'openai/resources/images';

package/dist/types/test-data.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test data for the Responses API.
+ * This is a minute-based time series stock data (provided as CSV).
+ */
+export declare const testData: {
+    c: number;
+    h: number;
+    l: number;
+    n: number;
+    o: number;
+    t: string;
+    v: number;
+    vw: number;
+}[];

package/dist/types/test-llm-functions-archive.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';

package/dist/types/test.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';

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

@@ -0,0 +1,53 @@
+import { AWSAuth } from '../utils/aws-initialise';
+export interface AWSApiResponse {
+    statusCode: number;
+    body?: string;
+    error?: string;
+}
+export interface UploadResult {
+    fileCount: number;
+    totalSize: number;
+    s3Key: string;
+    VersionId?: string;
+}
+export type uploadToS3Response = {
+    statusCode: number;
+    body?: {
+        message: string;
+        s3Url: string;
+        s3Key: string;
+    };
+    error?: string;
+};
+export interface SaveToS3Response {
+    success: boolean;
+    filename?: string;
+    bucket?: string;
+    s3key?: string;
+    s3Path?: string;
+    error?: string;
+}
+export interface LoadFromS3Response {
+    success: boolean;
+    content?: any;
+    error?: string;
+}
+export interface CheckBucketResponse {
+    exists: boolean;
+    fileName: string;
+    lastModifiedDate: string;
+}
+export interface S3ObjectInfo {
+    key: string;
+    createdAt: number;
+}
+export interface ListS3Response {
+    success: boolean;
+    objects: S3ObjectInfo[];
+    error?: string;
+}
+export interface ListS3Options {
+    bucket?: string;
+    auth?: AWSAuth | null;
+    limit?: number;
+}

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

@@ -0,0 +1,41 @@
+export interface GoogleSheetConfig {
+    spreadsheetId: string;
+    sheetName: string;
+}
+export interface GoogleSheetCell {
+    row: number;
+    column: number;
+}
+export interface GoogleSheetRange {
+    startCell: GoogleSheetCell;
+    endCell: GoogleSheetCell;
+}
+export interface GoogleSheetResponse {
+    success: boolean;
+    error?: string;
+    data?: any;
+}
+export interface GoogleSheetAddRowResponse extends GoogleSheetResponse {
+    data?: {
+        rowNumber: number;
+        values: any[];
+    };
+}
+export interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
+    data?: {
+        sheetId: number;
+        title: string;
+    };
+}
+export interface GoogleSheetCellResponse extends GoogleSheetResponse {
+    data?: {
+        value: any;
+    };
+}
+export interface GoogleSheetWriteArrayResponse extends GoogleSheetResponse {
+    data?: {
+        updatedRange: string;
+        updatedRows: number;
+        updatedColumns: number;
+    };
+}

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

@@ -0,0 +1,44 @@
+export * from './openai-types';
+export * from './aws-types';
+export * from './google-types';
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type JsonArray = JsonValue[];
+export interface PerplexityMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface PerplexityResponse {
+    choices: Array<{
+        message: {
+            content: string;
+        };
+    }>;
+}
+export type InvocationType = 'RequestResponse' | 'Event' | 'DryRun';
+export interface LambdaResponse {
+    statusCode: number;
+    [key: string]: any;
+}
+export interface SlackApiResponse {
+    ok: boolean;
+    error?: string;
+}
+export { AWSAuth } from '../utils/aws-initialise';
+export interface CreatePDFOptions {
+    title?: string;
+    author?: string;
+    margins?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+}
+export type WeatherReturnType = {
+    temperature: number;
+    description: string;
+    location: string;
+};

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

@@ -0,0 +1,81 @@
+import { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionMessageToolCall } from 'openai/resources/chat/completions';
+import { ImageGenerateParams } from 'openai/resources/images';
+/**
+ * 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';
+/**
+ * Represents Deepseek models
+ */
+export type DeepseekModel = 'deepseek-chat' | 'deepseek-reasoner';
+/**
+ * Represents all supported LLM models
+ */
+export type LLMModel = OpenAIModel | DeepseekModel;
+/**
+ * Represents the usage of the LLM.
+ */
+export interface LLMUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    reasoning_tokens?: number;
+    provider: string;
+    model: LLMModel;
+    cache_hit_tokens?: number;
+    cost: number;
+}
+/**
+ * Represents the options for the LLM.
+ */
+export interface LLMOptions {
+    model?: OpenAIModel | DeepseekModel;
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    max_completion_tokens?: number;
+    tools?: ChatCompletionTool[];
+    developerPrompt?: string;
+    context?: ChatCompletionMessageParam[];
+    store?: boolean;
+    reasoning_effort?: 'low' | 'medium' | 'high';
+    metadata?: Record<string, string>;
+    parallel_tool_calls?: boolean;
+    service_tier?: 'auto' | 'default';
+    apiKey?: string;
+}
+/**
+ * Represents the response from the LLM.
+ */
+export interface LLMResponse<T> {
+    response: T;
+    usage: LLMUsage;
+    tool_calls?: ChatCompletionMessageToolCall[];
+}
+/**
+ * Represents the format of the OpenAI response.
+ */
+export type OpenAIResponseFormat = 'text' | 'json' | {
+    type: 'json_schema';
+    schema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+};
+/**
+ * Represents the options for the OpenAI Images API.
+ * Extends the official ImageGenerateParams but with more user-friendly option names.
+ */
+export interface ImageGenerationOptions {
+    size?: ImageGenerateParams['size'];
+    outputFormat?: 'jpeg' | 'png' | 'webp';
+    compression?: number;
+    quality?: ImageGenerateParams['quality'];
+    count?: number | null;
+    apiKey?: string;
+    background?: ImageGenerateParams['background'];
+    moderation?: ImageGenerateParams['moderation'];
+}
+export type { ImageModel, ImageGenerateParams } from 'openai/resources/images';
+export type { ImagesResponse, Image } from 'openai/resources/images';

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

@@ -0,0 +1,21 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { Lambda } from '@aws-sdk/client-lambda';
+interface ValidationResult {
+    isValid: boolean;
+    source: 'lambda' | 'my_prefix' | 'standard' | null;
+    vars?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        region: string;
+    };
+    missingVars?: string[];
+}
+interface AWSAuth {
+    AWS_ACCESS_KEY_ID: string;
+    AWS_SECRET_ACCESS_KEY: string;
+    AWS_REGION: string;
+}
+declare const validateEnvironmentVars: () => ValidationResult;
+declare const initialiseS3Client: (auth?: AWSAuth | null) => S3Client;
+declare const initialiseLambdaClient: (auth?: AWSAuth | null) => Lambda;
+export { validateEnvironmentVars, initialiseS3Client, initialiseLambdaClient, AWSAuth };

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

@@ -0,0 +1,32 @@
+import { S3Client } from "@aws-sdk/client-s3";
+interface DirectoryStats {
+    totalFiles: number;
+    totalFolders: number;
+    totalSize: number;
+    fileList: string[];
+}
+interface UploadResult {
+    fileCount: number;
+    totalSize: number;
+    s3Key: string;
+}
+interface DownloadResult {
+    fileCount: number;
+    folderCount: number;
+    totalSize: number;
+    fileList: string[];
+}
+export declare const generateRandomHash: (length: number) => string;
+export declare function generateDateTimeStamp(): string;
+export declare const isValidBucketName: (name: string) => boolean;
+export declare function uploadFile(s3Client: S3Client, bucketName: string, filePath: string, destinationPath: string, isPublic?: boolean): Promise<UploadResult>;
+export declare function uploadDirectory(s3Client: S3Client, bucketName: string, dirPath: string, destinationPath: string, isPublic?: boolean): Promise<UploadResult>;
+export declare function zipDirectory(sourceDir: string, outPath: string): Promise<number>;
+export declare function downloadFromS3Helper(s3Client: S3Client, bucketName: string, s3Path: string, localPath: string): Promise<DownloadResult>;
+export declare function downloadFile(s3Client: S3Client, bucketName: string, s3Key: string, localFilePath: string): Promise<void>;
+export declare function unzipFile(zipPath: string, destPath: string): Promise<DirectoryStats>;
+export declare function getDirectoryStats(dirPath: string): Promise<DirectoryStats>;
+export declare function emptyBucket(s3Client: S3Client, bucketName: string): Promise<void>;
+export declare function deleteBucket(s3Client: S3Client, bucketName: string): Promise<void>;
+export declare function formatSize(bytes: number): string;
+export {};

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

@@ -0,0 +1,11 @@
+import { OpenAIModel } from "../types";
+export declare const DEFAULT_MODEL: OpenAIModel;
+export declare const PERPLEXITY_MODEL: string;
+export declare const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
+export interface Config {
+    DEFAULT_MODEL: string;
+    PERPLEXITY_MODEL: string;
+    PERPLEXITY_API_URL: string;
+}
+declare const config: Config;
+export default config;