@happyvertical/utils 0.80.0 → 0.80.2

package/dist/chunks/universal-DOIuUel_.js

@@ -0,0 +1,1415 @@
+import { createId, isCuid } from "@paralleldrive/cuid2";
+import { add, format, isValid, parse, parseISO } from "date-fns";
+import pluralize from "pluralize";
+//#region src/config/env-config.ts
+/**
+* Convert snake_case to camelCase
+* @param str - Snake case string
+* @returns Camel case string
+* @example
+* toCamelCase('max_retries') → 'maxRetries'
+* toCamelCase('api_key') → 'apiKey'
+*/
+function toCamelCase(str) {
+	return str.toLowerCase().replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+* Convert camelCase to SCREAMING_SNAKE_CASE
+* @param str - Camel case string
+* @returns Screaming snake case string
+* @example
+* toScreamingSnakeCase('maxRetries') → 'MAX_RETRIES'
+* toScreamingSnakeCase('apiKey') → 'API_KEY'
+*/
+function toScreamingSnakeCase(str) {
+	return str.replace(/([A-Z])/g, "_$1").toUpperCase().replace(/^_/, "");
+}
+/**
+* Convert string value to specified type
+* @param value - String value from environment variable
+* @param type - Target type for conversion
+* @returns Converted value
+* @throws Error if JSON parsing fails
+*/
+function convertType(value, type) {
+	switch (type) {
+		case "number": {
+			const num = Number(value);
+			if (Number.isNaN(num)) throw new Error(`Cannot convert "${value}" to number: result is NaN`);
+			return num;
+		}
+		case "boolean": return value.toLowerCase() === "true" || value === "1" || value.toLowerCase() === "yes";
+		case "json": try {
+			return JSON.parse(value);
+		} catch (error) {
+			throw new Error(`Cannot parse "${value}" as JSON: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+		default: return value;
+	}
+}
+/**
+* Load configuration from environment variables
+*
+* Scans environment variables matching the specified pattern and merges them
+* with user-provided options. User options always take precedence over env vars.
+*
+* @template T - Type of configuration object
+* @param userOptions - User-provided configuration (takes precedence)
+* @param options - Configuration options for env loading
+* @returns Merged configuration with env vars and user options
+*
+* @example
+* ```typescript
+* // Load HAVE_AI_* variables
+* const config = loadEnvConfig({ provider: 'openai' }, {
+*   packageName: 'ai',
+*   schema: {
+*     provider: 'string',
+*     model: 'string',
+*     timeout: 'number',
+*     maxRetries: 'number'
+*   }
+* });
+* // Checks: HAVE_AI_PROVIDER, HAVE_AI_MODEL, HAVE_AI_TIMEOUT, HAVE_AI_MAX_RETRIES
+*
+* // Load SQLOO_* variables (backward compatibility)
+* const sqlConfig = loadEnvConfig({}, {
+*   prefix: 'SQLOO',
+*   schema: {
+*     database: 'string',
+*     host: 'string',
+*     port: 'number'
+*   }
+* });
+* // Checks: SQLOO_DATABASE, SQLOO_HOST, SQLOO_PORT
+*
+* // Load without prefix
+* const customConfig = loadEnvConfig({}, {
+*   prefix: '',
+*   schema: {
+*     OPENAI_API_KEY: 'string'
+*   }
+* });
+* // Checks: OPENAI_API_KEY
+* ```
+*/
+function loadEnvConfig(userOptions = {}, options = {}) {
+	const { prefix = "HAVE", packageName, schema = {}, transform = {}, allowUnknown = true } = options;
+	const envPrefix = packageName && prefix ? `${prefix}_${packageName.toUpperCase()}_` : prefix ? `${prefix}_` : "";
+	const config = { ...userOptions };
+	const fieldsToScan = allowUnknown ? /* @__PURE__ */ new Set([...Object.keys(schema), ...Object.keys(process.env).filter((key) => envPrefix && key.startsWith(envPrefix)).map((key) => {
+		return toCamelCase(key.slice(envPrefix.length));
+	})]) : new Set(Object.keys(schema));
+	for (const fieldName of fieldsToScan) {
+		if (fieldName in userOptions) continue;
+		const envVarName = envPrefix ? envPrefix + toScreamingSnakeCase(fieldName) : fieldName;
+		const envValue = process.env[envVarName];
+		if (envValue === void 0) continue;
+		const transformFn = transform[fieldName];
+		if (transformFn) {
+			try {
+				config[fieldName] = transformFn(envValue);
+			} catch (error) {
+				console.warn(`Failed to transform ${envVarName}="${envValue}":`, error instanceof Error ? error.message : error);
+			}
+			continue;
+		}
+		const fieldType = schema[fieldName];
+		if (fieldType) {
+			try {
+				config[fieldName] = convertType(envValue, fieldType);
+			} catch (error) {
+				console.warn(`Failed to convert ${envVarName}="${envValue}" to ${fieldType}:`, error instanceof Error ? error.message : error);
+			}
+			continue;
+		}
+		config[fieldName] = envValue;
+	}
+	return config;
+}
+//#endregion
+//#region src/shared/code/extraction.ts
+/**
+* Code extraction utilities for parsing code from text (e.g., AI responses)
+*
+* Provides functions to extract code blocks, JSON data, and function definitions
+* from markdown-formatted text or AI-generated responses.
+*/
+/**
+* Extracts a code block from markdown-formatted text
+*
+* @param text - The text containing markdown code blocks
+* @param language - Optional language specifier to match (e.g., 'javascript', 'typescript', 'json')
+* @returns The extracted code without markdown delimiters, or empty string if not found
+*
+* @example
+* ```typescript
+* const code = extractCodeBlock(`
+* Here's the function:
+* \`\`\`javascript
+* function hello() {
+*   return 'world';
+* }
+* \`\`\`
+* `, 'javascript');
+* // Returns: "function hello() {\n  return 'world';\n}"
+* ```
+*/
+function extractCodeBlock(text, language) {
+	if (!text) return "";
+	const langPattern = language ? `${language}\\s*` : "(?:\\w+\\s*)?";
+	const codeBlockRegex = new RegExp(`\`\`\`${langPattern}\\r?\\n([\\s\\S]*?)\\r?\\n\`\`\``, "i");
+	const match = text.match(codeBlockRegex);
+	if (match?.[1]) return match[1].trim();
+	const inlineMatch = text.match(/`([^`]+)`/);
+	if (inlineMatch?.[1]) return inlineMatch[1].trim();
+	return "";
+}
+/**
+* Extracts and parses JSON from text, handling markdown code blocks
+*
+* @param text - The text containing JSON data
+* @returns The parsed JSON object
+* @throws {SyntaxError} If the JSON is invalid
+*
+* @example
+* ```typescript
+* const data = extractJSON<{ name: string }>(`
+* The result is:
+* \`\`\`json
+* {
+*   "name": "example"
+* }
+* \`\`\`
+* `);
+* // Returns: { name: "example" }
+* ```
+*/
+function extractJSON(text) {
+	if (!text) throw new SyntaxError("Cannot extract JSON from empty text");
+	let jsonText = extractCodeBlock(text, "json");
+	if (!jsonText) jsonText = extractCodeBlock(text);
+	if (!jsonText) {
+		const jsonObjectMatch = text.match(/\{[\s\S]*\}/);
+		const jsonArrayMatch = text.match(/\[[\s\S]*\]/);
+		if (jsonObjectMatch) jsonText = jsonObjectMatch[0];
+		else if (jsonArrayMatch) jsonText = jsonArrayMatch[0];
+		else jsonText = text.trim();
+	}
+	try {
+		return JSON.parse(jsonText);
+	} catch (error) {
+		throw new SyntaxError(`Failed to parse JSON: ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+/**
+* Extracts all code blocks from markdown-formatted text
+*
+* @param text - The text containing markdown code blocks
+* @param language - Optional language specifier to filter by
+* @returns Array of extracted code blocks
+*
+* @example
+* ```typescript
+* const blocks = extractAllCodeBlocks(`
+* \`\`\`javascript
+* const a = 1;
+* \`\`\`
+*
+* \`\`\`typescript
+* const b: number = 2;
+* \`\`\`
+* `);
+* // Returns: ["const a = 1;", "const b: number = 2;"]
+* ```
+*/
+function extractAllCodeBlocks(text, language) {
+	if (!text) return [];
+	const langPattern = language ? `${language}\\s*` : "(?:\\w+\\s*)?";
+	const codeBlockRegex = new RegExp(`\`\`\`${langPattern}\\r?\\n([\\s\\S]*?)\\r?\\n\`\`\``, "gi");
+	const blocks = [];
+	const matches = text.matchAll(codeBlockRegex);
+	for (const match of matches) if (match[1]) blocks.push(match[1].trim());
+	return blocks;
+}
+/**
+* Extracts a specific function definition from code
+*
+* @param code - The code containing function definitions
+* @param functionName - The name of the function to extract
+* @returns The function definition, or empty string if not found
+*
+* @example
+* ```typescript
+* const code = `
+* function foo() { return 1; }
+* function bar() { return 2; }
+* `;
+*
+* const fooFunc = extractFunctionDefinition(code, 'foo');
+* // Returns: "function foo() { return 1; }"
+* ```
+*/
+function extractFunctionDefinition(code, functionName) {
+	if (!code || !functionName) return "";
+	const patterns = [
+		{
+			regex: new RegExp(`function\\s+${functionName}\\s*\\([^)]*\\)\\s*\\{`, "i"),
+			hasBraces: true
+		},
+		{
+			regex: new RegExp(`(?:const|let|var)\\s+${functionName}\\s*=\\s*function\\s*\\([^)]*\\)\\s*\\{`, "i"),
+			hasBraces: true
+		},
+		{
+			regex: new RegExp(`(?:const|let|var)\\s+${functionName}\\s*=\\s*\\([^)]*\\)\\s*=>\\s*\\{`, "i"),
+			hasBraces: true
+		},
+		{
+			regex: new RegExp(`(?:const|let|var)\\s+${functionName}\\s*=\\s*\\([^)]*\\)\\s*=>\\s*[^;]+;?`, "i"),
+			hasBraces: false
+		}
+	];
+	for (const { regex, hasBraces } of patterns) {
+		const match = code.match(regex);
+		if (match && match.index !== void 0) {
+			const startIdx = match.index;
+			if (!hasBraces) return match[0].trim();
+			const braceIdx = code.indexOf("{", startIdx);
+			if (braceIdx === -1) continue;
+			let idx = braceIdx;
+			let depth = 0;
+			let endIdx = -1;
+			while (idx < code.length) {
+				const char = code[idx];
+				if (char === "{") depth++;
+				else if (char === "}") {
+					depth--;
+					if (depth === 0) {
+						endIdx = idx;
+						break;
+					}
+				}
+				idx++;
+			}
+			if (endIdx !== -1) return code.slice(startIdx, endIdx + 1).trim();
+		}
+	}
+	return "";
+}
+//#endregion
+//#region src/shared/code/validation.ts
+/**
+* Default dangerous patterns that should be disallowed
+*/
+var DANGEROUS_PATTERNS = [
+	/require\s*\(/i,
+	/import\s+/i,
+	/eval\s*\(/i,
+	/Function\s*\(/i,
+	/process\./i,
+	/fs\./i,
+	/child_process/i,
+	/__dirname/i,
+	/__filename/i,
+	/global\./i
+];
+/**
+* Validates code before execution in a sandbox
+*
+* @param code - The code to validate
+* @param options - Validation options
+* @returns Validation result with errors and warnings
+*
+* @example
+* ```typescript
+* const result = validateCode(`
+*   function parse(data) {
+*     return JSON.parse(data);
+*   }
+* `, {
+*   allowedGlobals: ['JSON'],
+*   maxLength: 10000
+* });
+*
+* if (!result.valid) {
+*   console.error('Code validation failed:', result.errors);
+* }
+* ```
+*/
+function validateCode(code, options = {}) {
+	const { allowedGlobals, disallowedPatterns = DANGEROUS_PATTERNS, maxLength = 5e4, allowRequire = false, allowImport = false, allowEval = false, checkSyntax = true } = options;
+	const errors = [];
+	const warnings = [];
+	if (!code || code.trim().length === 0) {
+		errors.push("Code is empty");
+		return {
+			valid: false,
+			errors,
+			warnings
+		};
+	}
+	if (code.length > maxLength) errors.push(`Code exceeds maximum length (${code.length} > ${maxLength} characters)`);
+	const patternFlags = /* @__PURE__ */ new Map([
+		[DANGEROUS_PATTERNS[0], "require"],
+		[DANGEROUS_PATTERNS[1], "import"],
+		[DANGEROUS_PATTERNS[2], "eval"],
+		[DANGEROUS_PATTERNS[3], "eval"]
+	]);
+	const effectivePatterns = disallowedPatterns.filter((_pattern, index) => {
+		const patternType = patternFlags.get(DANGEROUS_PATTERNS[index]);
+		if (patternType === "require" && allowRequire) return false;
+		if (patternType === "import" && allowImport) return false;
+		if (patternType === "eval" && allowEval) return false;
+		return true;
+	});
+	for (const pattern of effectivePatterns) if (pattern.test(code)) errors.push(`Code contains disallowed pattern: ${pattern.source.replace(/\\/g, "")}`);
+	if (allowedGlobals) {
+		const undeclaredVars = findUndeclaredVariables(code, allowedGlobals);
+		if (undeclaredVars.length > 0) warnings.push(`Potentially undeclared variables: ${undeclaredVars.join(", ")}`);
+	}
+	if (checkSyntax) {
+		const syntaxErrors = checkCodeSyntax(code);
+		errors.push(...syntaxErrors);
+	}
+	const stats = {
+		length: code.length,
+		lines: code.split("\n").length,
+		hasAsync: /\basync\b\s*(function|\([\w\s,={}[\]]*\)\s*=>|\w+\s*\()/m.test(code),
+		hasArrowFunctions: /=>/.test(code),
+		hasClasses: /\bclass\s+\w+/.test(code)
+	};
+	if (stats.lines > 100) warnings.push(`Code is long (${stats.lines} lines) - consider breaking into smaller functions`);
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings,
+		stats
+	};
+}
+/**
+* Checks code syntax without executing it
+*
+* @param code - The code to check
+* @returns Array of syntax error messages (empty if valid)
+*/
+function checkCodeSyntax(code) {
+	const errors = [];
+	try {
+		new Function(code);
+	} catch (error) {
+		if (error instanceof SyntaxError) {
+			const message = error.message;
+			if (message.includes("await is only valid") && /\bawait\b/.test(code)) try {
+				new Function(`(async function() { ${code} })()`);
+				return errors;
+			} catch (asyncError) {
+				if (asyncError instanceof SyntaxError) errors.push(`Syntax error: ${asyncError.message}`);
+			}
+			else errors.push(`Syntax error: ${message}`);
+		}
+	}
+	return errors;
+}
+/**
+* Finds potentially undeclared variables in code
+*
+* **Important Limitations:**
+* This is a basic regex-based static analysis with known limitations:
+* - Cannot detect variables in destructuring assignments
+* - May miss variables declared in nested scopes
+* - Cannot handle dynamic variable access (e.g., obj[varName])
+* - Will have false positives for method calls and object properties
+* - Does not understand scope chains or closures
+*
+* For production use cases requiring accurate variable analysis, consider using
+* a proper AST parser like @babel/parser or acorn.
+*
+* @param code - The code to analyze
+* @param allowedGlobals - List of allowed global variables
+* @returns Array of potentially undeclared variable names (may include false positives)
+*/
+function findUndeclaredVariables(code, allowedGlobals) {
+	const undeclaredVars = /* @__PURE__ */ new Set();
+	const matches = code.matchAll(/\b([a-zA-Z_$][a-zA-Z0-9_$]*)\b/g);
+	const declaredVars = /* @__PURE__ */ new Set();
+	const declarations = code.matchAll(/\b(?:var|let|const|function)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g);
+	for (const match of declarations) if (match[1]) declaredVars.add(match[1]);
+	for (const match of matches) {
+		const identifier = match[1];
+		if (isJavaScriptKeyword(identifier)) continue;
+		if (declaredVars.has(identifier)) continue;
+		if (allowedGlobals.includes(identifier)) continue;
+		if (isCommonBuiltin(identifier)) continue;
+		undeclaredVars.add(identifier);
+	}
+	return Array.from(undeclaredVars);
+}
+/**
+* Checks if a word is a JavaScript keyword
+*/
+function isJavaScriptKeyword(word) {
+	return [
+		"break",
+		"case",
+		"catch",
+		"class",
+		"const",
+		"continue",
+		"debugger",
+		"default",
+		"delete",
+		"do",
+		"else",
+		"export",
+		"extends",
+		"finally",
+		"for",
+		"function",
+		"if",
+		"import",
+		"in",
+		"instanceof",
+		"let",
+		"new",
+		"return",
+		"super",
+		"switch",
+		"this",
+		"throw",
+		"try",
+		"typeof",
+		"var",
+		"void",
+		"while",
+		"with",
+		"yield",
+		"async",
+		"await"
+	].includes(word);
+}
+/**
+* Checks if a word is a common JavaScript built-in
+*/
+function isCommonBuiltin(word) {
+	return [
+		"Array",
+		"Object",
+		"String",
+		"Number",
+		"Boolean",
+		"Date",
+		"Math",
+		"JSON",
+		"RegExp",
+		"Error",
+		"Map",
+		"Set",
+		"Promise",
+		"Symbol",
+		"undefined",
+		"null",
+		"true",
+		"false",
+		"console",
+		"parseInt",
+		"parseFloat",
+		"isNaN",
+		"isFinite",
+		"decodeURI",
+		"decodeURIComponent",
+		"encodeURI",
+		"encodeURIComponent"
+	].includes(word);
+}
+/**
+* Quick validation to check if code is safe for execution
+* Returns true if code passes basic safety checks
+*
+* @param code - The code to check
+* @returns true if code is safe, false otherwise
+*
+* @example
+* ```typescript
+* if (isSafeCode('return x + y')) {
+*   // Safe to execute
+* }
+* ```
+*/
+function isSafeCode(code) {
+	return validateCode(code, {
+		maxLength: 5e4,
+		checkSyntax: true
+	}).valid;
+}
+//#endregion
+//#region src/shared/logger.ts
+/**
+* Console-based logger implementation
+*
+* Routes all log messages to the appropriate console methods with optional context.
+*/
+var ConsoleLogger = class {
+	debug(message, context) {
+		if (context) console.debug(message, context);
+		else console.debug(message);
+	}
+	info(message, context) {
+		if (context) console.info(message, context);
+		else console.info(message);
+	}
+	warn(message, context) {
+		if (context) console.warn(message, context);
+		else console.warn(message);
+	}
+	error(message, context) {
+		if (context) console.error(message, context);
+		else console.error(message);
+	}
+};
+/**
+* No-operation logger that discards all log messages
+*
+* Useful for disabling logging in production or testing environments.
+*/
+var NoOpLogger = class {
+	debug() {}
+	info() {}
+	warn() {}
+	error() {}
+};
+/** Global logger instance used throughout the SDK */
+var globalLogger = new ConsoleLogger();
+/**
+* Replace the global logger with a custom implementation
+*
+* @param logger - Custom logger implementation
+* @example
+* ```typescript
+* setLogger(new CustomLogger());
+* ```
+*/
+var setLogger = (logger) => {
+	globalLogger = logger;
+};
+/**
+* Get the current global logger instance
+*
+* @returns Current logger implementation
+* @example
+* ```typescript
+* const logger = getLogger();
+* logger.info('Application started');
+* ```
+*/
+var getLogger = () => {
+	return globalLogger;
+};
+/**
+* Disable all logging by switching to no-op logger
+*
+* @example
+* ```typescript
+* if (process.env.NODE_ENV === 'production') {
+*   disableLogging();
+* }
+* ```
+*/
+var disableLogging = () => {
+	globalLogger = new NoOpLogger();
+};
+/**
+* Enable console logging by switching to console logger
+*
+* @example
+* ```typescript
+* enableLogging(); // Re-enable after disabling
+* ```
+*/
+var enableLogging = () => {
+	globalLogger = new ConsoleLogger();
+};
+//#endregion
+//#region src/shared/types.ts
+/**
+* Shared type definitions and interfaces for universal use
+*
+* This module provides standardized error classes and logging interfaces
+* used throughout the HAVE SDK. All error classes extend BaseError to
+* provide consistent error handling with context and timestamps.
+*/
+/**
+* Standardized error codes used across the HAVE SDK
+*
+* These codes provide consistent error categorization for better error handling
+* and monitoring across all packages in the SDK.
+*/
+var ErrorCode = /* @__PURE__ */ function(ErrorCode) {
+	/** Input validation failed */
+	ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+	/** API request/response error */
+	ErrorCode["API_ERROR"] = "API_ERROR";
+	/** File system operation error */
+	ErrorCode["FILE_ERROR"] = "FILE_ERROR";
+	/** Network connectivity or HTTP error */
+	ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+	/** Database operation error */
+	ErrorCode["DATABASE_ERROR"] = "DATABASE_ERROR";
+	/** Data parsing or format error */
+	ErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
+	/** Operation timeout error */
+	ErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+	/** Unspecified or unexpected error */
+	ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+	return ErrorCode;
+}({});
+/**
+* Base error class providing standardized error handling across the HAVE SDK
+*
+* All custom errors extend this class to ensure consistent error structure,
+* context preservation, and debugging capabilities.
+*
+* @example
+* ```typescript
+* throw new BaseError('Something went wrong', ErrorCode.UNKNOWN_ERROR, {
+*   userId: 123,
+*   operation: 'processData'
+* });
+* ```
+*/
+var BaseError = class extends Error {
+	/** Error classification code */
+	code;
+	/** Additional context data for debugging */
+	context;
+	/** When the error occurred */
+	timestamp;
+	constructor(message, code = "UNKNOWN_ERROR", context) {
+		super(message);
+		this.name = this.constructor.name;
+		this.code = code;
+		this.context = context;
+		this.timestamp = /* @__PURE__ */ new Date();
+		Error.captureStackTrace?.(this, this.constructor);
+	}
+	/**
+	* Serializes the error to a JSON-compatible object
+	* @returns Object containing all error properties
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			context: this.context,
+			timestamp: this.timestamp.toISOString(),
+			stack: this.stack
+		};
+	}
+};
+/**
+* Error thrown when input validation fails
+*
+* @example
+* ```typescript
+* throw new ValidationError('Email format invalid', {
+*   email: 'invalid-email',
+*   field: 'userEmail'
+* });
+* ```
+*/
+var ValidationError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "VALIDATION_ERROR", context);
+	}
+};
+/**
+* Error thrown for API-related failures
+*
+* @example
+* ```typescript
+* throw new ApiError('HTTP 404 Not Found', {
+*   url: 'https://api.example.com/users/123',
+*   status: 404
+* });
+* ```
+*/
+var ApiError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "API_ERROR", context);
+	}
+};
+/**
+* Error thrown for file system operation failures
+*
+* @example
+* ```typescript
+* throw new FileError('File not found', {
+*   path: '/path/to/missing/file.txt',
+*   operation: 'read'
+* });
+* ```
+*/
+var FileError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "FILE_ERROR", context);
+	}
+};
+/**
+* Error thrown for network connectivity or HTTP failures
+*
+* @example
+* ```typescript
+* throw new NetworkError('Connection timeout', {
+*   host: 'example.com',
+*   timeout: 5000,
+*   attempt: 3
+* });
+* ```
+*/
+var NetworkError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "NETWORK_ERROR", context);
+	}
+};
+/**
+* Error thrown for database operation failures
+*
+* @example
+* ```typescript
+* throw new DatabaseError('Connection failed', {
+*   database: 'production',
+*   query: 'SELECT * FROM users',
+*   errorCode: 'ECONNREFUSED'
+* });
+* ```
+*/
+var DatabaseError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "DATABASE_ERROR", context);
+	}
+};
+/**
+* Error thrown for data parsing or format failures
+*
+* @example
+* ```typescript
+* throw new ParsingError('Invalid JSON format', {
+*   input: '{invalid json}',
+*   parser: 'JSON.parse',
+*   position: 1
+* });
+* ```
+*/
+var ParsingError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "PARSING_ERROR", context);
+	}
+};
+/**
+* Error thrown when operations exceed their timeout duration
+*
+* @example
+* ```typescript
+* throw new TimeoutError('Operation timed out', {
+*   timeout: 5000,
+*   operation: 'fetchData',
+*   elapsedTime: 5234
+* });
+* ```
+*/
+var TimeoutError = class extends BaseError {
+	constructor(message, context) {
+		super(message, "TIMEOUT_ERROR", context);
+	}
+};
+//#endregion
+//#region src/shared/universal.ts
+/**
+* Universal utilities that work in both browser and Node.js environments
+*/
+/**
+* Generates a unique identifier using CUID2 (preferred) or UUID fallback
+*
+* CUID2 is more secure and collision-resistant than UUIDs, but UUID is provided
+* as a fallback for RFC4122 compliance requirements.
+*
+* @param type - ID type: 'cuid2' (default) or 'uuid'
+* @returns A unique identifier string
+* @example
+* ```typescript
+* const id = makeId(); // CUID2: "ckx5f8h3z0000qzrmn831i7rn"
+* const uuid = makeId('uuid'); // UUID: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+* ```
+*/
+var makeId = (type = "cuid2") => {
+	if (type === "cuid2") return createId();
+	if (crypto?.randomUUID) return crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+};
+/**
+* Generates a CUID2 identifier (collision-resistant, more secure than UUID)
+*
+* CUID2 provides better entropy and security compared to UUID v4, making it
+* ideal for distributed systems and user-facing identifiers.
+*
+* @returns A CUID2 identifier string
+* @example
+* ```typescript
+* const id = createId(); // "ckx5f8h3z0000qzrmn831i7rn"
+* ```
+*/
+var createId$1 = createId;
+/**
+* Converts a string to a URL-friendly slug
+*
+* Handles international characters, removes special characters, and replaces
+* spaces with hyphens. Ampersands are converted to "-38-" for uniqueness.
+*
+* @param str - The string to convert to a slug
+* @returns A URL-friendly slug string
+* @example
+* ```typescript
+* makeSlug("My Example Title & Co."); // "my-example-title-38-co"
+* makeSlug("Café España"); // "cafe-espana"
+* ```
+*/
+var makeSlug = (str) => {
+	const from = "àáâäæãåāăąçćčđďèéêëēėęěğǵḧîïíīįìıİłḿñńǹňôöòóœøōõőṕŕřßśšşșťțûüùúūǘůűųẃẍÿýžźż+·/_,:;";
+	const to = "aaaaaaaaaacccddeeeeeeeegghiiiiiiiilmnnnnoooooooooprrsssssttuuuuuuuuuwxyyzzz--------------";
+	const textToCompare = new RegExp(from.split("").join("|").replace(/\+/g, "\\+"), "g");
+	return str.toString().toLowerCase().replace("&", "-38-").replace(/\s+/g, "-").replace(textToCompare, (c) => to.charAt(from.indexOf(c))).replace(/[&.]/g, "-").replace(/[^\w-º+]+/g, "").replace(/--+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
+};
+/**
+* Extracts the filename from a URL's pathname
+*
+* Returns the last segment of the URL path. If no filename is found,
+* defaults to 'index.html'.
+*
+* @param url - The URL to extract filename from
+* @returns The filename from the URL
+* @throws {TypeError} When URL is invalid
+* @example
+* ```typescript
+* urlFilename("https://example.com/path/file.pdf"); // "file.pdf"
+* urlFilename("https://example.com/path/"); // "index.html"
+* ```
+*/
+var urlFilename = (url) => {
+	const pathSegments = new URL(url).pathname.split("/");
+	return pathSegments[pathSegments.length - 1] || "index.html";
+};
+/**
+* Converts a URL to a file path by joining hostname and pathname
+*
+* Creates a file system compatible path from a URL by combining the hostname
+* with the pathname segments, useful for creating local file structures.
+*
+* @param url - The URL to convert to a path
+* @returns A file path string with hostname and path segments
+* @throws {TypeError} When URL is invalid
+* @example
+* ```typescript
+* urlPath("https://example.com/path/to/resource"); // "example.com/path/to/resource"
+* ```
+*/
+var urlPath = (url) => {
+	const parsedUrl = new URL(url);
+	return [parsedUrl.hostname, ...parsedUrl.pathname.split("/").filter(Boolean)].join("/");
+};
+/**
+* Creates a Promise that resolves after a specified duration
+*
+* Useful for adding delays in async functions or rate limiting operations.
+*
+* @param duration - Time to wait in milliseconds
+* @returns Promise that resolves after the specified duration
+* @example
+* ```typescript
+* await sleep(1000); // Wait 1 second
+* console.log('1 second has passed');
+* ```
+*/
+var sleep = (duration) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, duration);
+	});
+};
+/**
+* Repeatedly calls a function until it returns a defined value or times out
+*
+* Polls an async function at regular intervals until it returns a defined value
+* or the timeout is reached. Useful for waiting for conditions to be met.
+*
+* @param it - Async function to poll
+* @param options - Configuration options
+* @param options.timeout - Maximum time to wait in milliseconds (0 = no timeout)
+* @param options.delay - Time between polling attempts in milliseconds
+* @returns Promise that resolves with the function result or rejects on timeout
+* @throws {TimeoutError} When timeout is reached before function returns defined value
+* @example
+* ```typescript
+* // Wait for a file to exist
+* const fileExists = await waitFor(
+*   async () => {
+*     try {
+*       await fs.access('/path/to/file');
+*       return true;
+*     } catch {
+*       return undefined; // Keep polling
+*     }
+*   },
+*   { timeout: 10000, delay: 500 }
+* );
+* ```
+*/
+function waitFor(it, { timeout = 0, delay = 1e3 } = {}) {
+	return new Promise((resolve, reject) => {
+		const beginTime = Date.now();
+		(async function waitATick() {
+			try {
+				const result = await it();
+				if (typeof result !== "undefined") return resolve(result);
+				if (timeout > 0) {
+					if (Date.now() > beginTime + timeout) return reject(new TimeoutError("Function call timed out", {
+						timeout,
+						delay,
+						elapsedTime: Date.now() - beginTime
+					}));
+				}
+				setTimeout(waitATick, delay);
+			} catch (error) {
+				reject(error);
+			}
+		})();
+	});
+}
+/**
+* Type guard to check if a value is an array
+*
+* @param obj - Value to check
+* @returns True if value is an array, with TypeScript type narrowing
+* @example
+* ```typescript
+* if (isArray(data)) {
+*   // TypeScript knows data is unknown[]
+*   data.forEach(item => console.log(item));
+* }
+* ```
+*/
+var isArray = (obj) => {
+	return Array.isArray(obj);
+};
+/**
+* Type guard to check if a value is a plain object
+*
+* Checks for objects that are not null, arrays, or other non-plain object types.
+*
+* @param obj - Value to check
+* @returns True if value is a plain object, with TypeScript type narrowing
+* @example
+* ```typescript
+* if (isPlainObject(data)) {
+*   // TypeScript knows data is Record<string, unknown>
+*   Object.keys(data).forEach(key => console.log(key, data[key]));
+* }
+* ```
+*/
+var isPlainObject = (obj) => {
+	return typeof obj === "object" && obj !== null && !Array.isArray(obj);
+};
+/**
+* Checks if a string is a valid URL
+*
+* Uses the URL constructor to validate the string format. Returns false
+* for any string that cannot be parsed as a valid URL.
+*
+* @param url - String to validate as URL
+* @returns True if string is a valid URL
+* @example
+* ```typescript
+* isUrl("https://example.com"); // true
+* isUrl("not-a-url"); // false
+* ```
+*/
+var isUrl = (url) => {
+	try {
+		new URL(url);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/**
+* Converts a string to camelCase
+*
+* Handles kebab-case, snake_case, and space-separated strings.
+* Removes special characters and ensures proper camelCase formatting.
+*
+* @param str - String to convert
+* @returns camelCase formatted string
+* @example
+* ```typescript
+* camelCase("hello-world"); // "helloWorld"
+* camelCase("snake_case_string"); // "snakeCaseString"
+* camelCase("Some Title"); // "someTitle"
+* ```
+*/
+var camelCase = (str) => {
+	return str.toLowerCase().replace(/[-_]+/g, " ").replace(/[^\w\s]/g, "").replace(/\s(.)/g, (_, char) => char.toUpperCase()).replace(/\s/g, "").replace(/^(.)/, (_, char) => char.toLowerCase());
+};
+/**
+* Converts a string to snake_case
+*
+* Handles camelCase, kebab-case, and space-separated strings.
+* Converts to lowercase with underscore separators.
+*
+* @param str - String to convert
+* @returns snake_case formatted string
+* @example
+* ```typescript
+* snakeCase("helloWorld"); // "hello_world"
+* snakeCase("kebab-case-string"); // "kebab_case_string"
+* snakeCase("Some Title"); // "some_title"
+* ```
+*/
+var snakeCase = (str) => {
+	return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "").replace(/[-\s]+/g, "_");
+};
+/**
+* Recursively converts all object keys to camelCase
+*
+* Deeply traverses an object or array and converts all keys to camelCase.
+* Preserves the structure and values, only transforming key names.
+*
+* @param obj - Object or array to transform
+* @returns New object/array with camelCase keys
+* @example
+* ```typescript
+* keysToCamel({
+*   user_name: "john",
+*   user_details: { first_name: "John" }
+* }); // { userName: "john", userDetails: { firstName: "John" } }
+* ```
+*/
+var keysToCamel = (obj) => {
+	if (isPlainObject(obj)) {
+		const n = {};
+		Object.keys(obj).forEach((k) => {
+			n[camelCase(k)] = keysToCamel(obj[k]);
+		});
+		return n;
+	}
+	if (isArray(obj)) return obj.map((i) => keysToCamel(i));
+	return obj;
+};
+/**
+* Recursively converts all object keys to snake_case
+*
+* Deeply traverses an object or array and converts all keys to snake_case.
+* Preserves the structure and values, only transforming key names.
+*
+* @param obj - Object or array to transform
+* @returns New object/array with snake_case keys
+* @example
+* ```typescript
+* keysToSnake({
+*   userName: "john",
+*   userDetails: { firstName: "John" }
+* }); // { user_name: "john", user_details: { first_name: "John" } }
+* ```
+*/
+var keysToSnake = (obj) => {
+	if (isPlainObject(obj)) {
+		const n = {};
+		Object.keys(obj).forEach((k) => {
+			n[snakeCase(k)] = keysToSnake(obj[k]);
+		});
+		return n;
+	}
+	if (isArray(obj)) return obj.map((i) => keysToSnake(i));
+	return obj;
+};
+/**
+* Converts a domain string to camelCase
+*
+* Convenience function that applies camelCase conversion to domain strings.
+* Useful for converting API service names or domain identifiers.
+*
+* @param domain - Domain string to convert
+* @returns camelCase formatted domain string
+* @example
+* ```typescript
+* domainToCamel("api-service"); // "apiService"
+* domainToCamel("user_management"); // "userManagement"
+* ```
+*/
+var domainToCamel = (domain) => camelCase(domain);
+/**
+* Creates a visual progress indicator by cycling through a sequence of characters
+*
+* Useful for creating animated progress indicators in CLI applications.
+* Cycles through provided characters or defaults to dot sequences.
+*
+* @param tick - Current tick state (null to start)
+* @param options - Configuration options
+* @param options.chars - Array of characters to cycle through
+* @returns Next character in the sequence
+* @example
+* ```typescript
+* let tick = null;
+* setInterval(() => {
+*   tick = logTicker(tick);
+*   process.stdout.write(`\rProcessing ${tick}`);
+* }, 500);
+* // Outputs: "Processing ." → "Processing .." → "Processing ..."
+* ```
+*/
+var logTicker = (tick, options = {}) => {
+	const { chars = [
+		".",
+		"..",
+		"..."
+	] } = options;
+	if (tick) {
+		const index = chars.indexOf(tick);
+		return index + 1 >= chars.length ? chars[0] : chars[index + 1];
+	}
+	return chars[0];
+};
+/**
+* Parses an Amazon date string format (YYYYMMDDTHHMMSSZ) to a Date object
+*
+* Specifically handles the compact date format used by Amazon AWS services.
+* Validates the format and throws detailed errors for invalid inputs.
+*
+* @param dateStr - Amazon date string in format YYYYMMDDTHHMMSSZ
+* @returns Parsed Date object
+* @throws {ParsingError} When date string format is invalid
+* @example
+* ```typescript
+* parseAmazonDateString('20220223T215409Z');
+* // Returns: Date object for February 23, 2022, 21:54:09 UTC
+* ```
+*/
+var parseAmazonDateString = (dateStr) => {
+	const match = dateStr.match(/^([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2})([0-9]{2})([0-9]{2})([A-Z0-9]+)/);
+	if (!match) throw new ParsingError("Could not parse Amazon date string", {
+		dateString: dateStr,
+		expectedFormat: "YYYYMMDDTHHMMSSZ"
+	});
+	const [matched, year, month, day, hour, minutes, seconds, timezone] = match;
+	if (matched !== dateStr) throw new ParsingError("Invalid Amazon date string format", {
+		dateString: dateStr,
+		matched,
+		expectedFormat: "YYYYMMDDTHHMMSSZ"
+	});
+	return /* @__PURE__ */ new Date(`${year}-${month}-${day}T${hour}:${minutes}:${seconds}${timezone}`);
+};
+/**
+* Extracts and parses a date from a string
+*
+* Intelligently extracts dates from filenames or text strings by looking for
+* common date patterns. Supports multiple formats including:
+* - ISO dates (2023-01-15, 2023/01/15)
+* - US dates (01/15/2023, 01-15-2023)
+* - Natural language (January 15, 2023, Oct 14 2025)
+* - Filenames with dates (Report_January_15_2023.pdf)
+*
+* @param str - String containing date information (filename, title, or text)
+* @returns Parsed Date object or null if no valid date found
+* @example
+* ```typescript
+* dateInString("Report_January_15_2023.pdf"); // Date(2023, 0, 15)
+* dateInString("Regular Council Meeting October 14, 2025"); // Date(2025, 9, 14)
+* dateInString("financial-report-dec-2023.pdf"); // Date(2023, 11, 1)
+* dateInString("2023-01-15"); // Date(2023, 0, 15)
+* dateInString("no-date-here.pdf"); // null
+* ```
+*/
+var dateInString = (str) => {
+	const cleanStr = str.toLowerCase();
+	const underscoreMatch = str.match(/(\d{4})_(\d{1,2})_(\d{1,2})/);
+	if (underscoreMatch) {
+		const [, year, month, day] = underscoreMatch;
+		const date = new Date(Number.parseInt(year, 10), Number.parseInt(month, 10) - 1, Number.parseInt(day, 10));
+		if (!Number.isNaN(date.getTime())) return date;
+	}
+	const dotMatch = str.match(/(\d{1,2})\.(\d{1,2})\.(\d{4})/);
+	if (dotMatch) {
+		const [, month, day, year] = dotMatch;
+		const date = new Date(Number.parseInt(year, 10), Number.parseInt(month, 10) - 1, Number.parseInt(day, 10));
+		if (!Number.isNaN(date.getTime())) return date;
+	}
+	const isoMatch = cleanStr.match(/(\d{4})[-/](\d{1,2})[-/](\d{1,2})/);
+	if (isoMatch) {
+		const [, year, month, day] = isoMatch;
+		const date = new Date(Number.parseInt(year, 10), Number.parseInt(month, 10) - 1, Number.parseInt(day, 10));
+		if (!Number.isNaN(date.getTime())) return date;
+	}
+	const usMatch = cleanStr.match(/(\d{1,2})[-/](\d{1,2})[-/](\d{4})/);
+	if (usMatch) {
+		const [, month, day, year] = usMatch;
+		const date = new Date(Number.parseInt(year, 10), Number.parseInt(month, 10) - 1, Number.parseInt(day, 10));
+		if (!Number.isNaN(date.getTime())) return date;
+	}
+	const yearMatch = cleanStr.match(/20\d{2}/);
+	if (!yearMatch) return null;
+	const year = Number.parseInt(yearMatch[0], 10);
+	const monthPatterns = {
+		january: 1,
+		jan: 1,
+		february: 2,
+		feb: 2,
+		march: 3,
+		mar: 3,
+		april: 4,
+		apr: 4,
+		may: 5,
+		june: 6,
+		jun: 6,
+		july: 7,
+		jul: 7,
+		august: 8,
+		aug: 8,
+		september: 9,
+		sep: 9,
+		sept: 9,
+		october: 10,
+		oct: 10,
+		november: 11,
+		nov: 11,
+		december: 12,
+		dec: 12
+	};
+	let foundMonth = null;
+	let monthStart = -1;
+	let monthName = "";
+	for (const [name, monthNum] of Object.entries(monthPatterns)) {
+		const monthIndex = cleanStr.indexOf(name);
+		if (monthIndex !== -1) {
+			foundMonth = monthNum;
+			monthStart = monthIndex;
+			monthName = name;
+			break;
+		}
+	}
+	if (!foundMonth) return null;
+	const yearIndex = cleanStr.indexOf(yearMatch[0]);
+	const beforeMonth = cleanStr.substring(Math.max(0, monthStart - 15), monthStart);
+	const afterMonth = cleanStr.substring(monthStart + monthName.length, Math.min(cleanStr.length, monthStart + monthName.length + 15));
+	const beforeYear = cleanStr.substring(Math.max(0, yearIndex - 15), yearIndex);
+	const afterYear = cleanStr.substring(yearIndex + 4, Math.min(cleanStr.length, yearIndex + 19));
+	const dayMatch = beforeMonth.match(/(?<!\d)(\d{1,2})\s*$/) || afterMonth.match(/^\s*(\d{1,2})(?!\d)/) || beforeYear.match(/(?<!\d)(\d{1,2})\s*$/) || afterYear.match(/^\s*(\d{1,2})(?!\d)/) || afterMonth.match(/[^\d](\d{1,2})(?!\d)/);
+	const day = dayMatch ? Number.parseInt(dayMatch[1], 10) : 1;
+	if (day < 1 || day > 31) return null;
+	const date = new Date(year, foundMonth - 1, day);
+	return !Number.isNaN(date.getTime()) ? date : null;
+};
+/**
+* Formats a date string into a human-readable format using the system locale
+*
+* Uses the Intl.DateTimeFormat API to create localized, human-readable date strings.
+* Automatically adapts to the user's system locale settings.
+*
+* @param dateString - ISO date string or any valid date string
+* @returns Human-readable date string in system locale
+* @example
+* ```typescript
+* prettyDate("2023-01-15T12:00:00Z"); // "January 15, 2023" (in English locale)
+* ```
+*/
+var prettyDate = (dateString) => {
+	const date = new Date(dateString);
+	return new Intl.DateTimeFormat(void 0, {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	}).format(date);
+};
+/**
+* String pluralization utilities using the pluralize library
+*
+* Re-exports the pluralize library function for word pluralization.
+* Handles English pluralization rules including irregular forms.
+*
+* @example
+* ```typescript
+* pluralizeWord("cat"); // "cats"
+* pluralizeWord("mouse"); // "mice"
+* singularize("cats"); // "cat"
+* isPlural("cats"); // true
+* isSingular("cat"); // true
+* ```
+*/
+var pluralizeWord = pluralize;
+var singularize = pluralize.singular;
+var isPlural = pluralize.isPlural;
+var isSingular = pluralize.isSingular;
+/**
+* Enhanced date utilities using date-fns library
+*
+* Re-exports commonly used date-fns functions for date manipulation and formatting.
+* Provides more reliable date handling than native Date methods.
+*
+* @param date - Date object or ISO string to format
+* @param formatStr - Format string (defaults to 'yyyy-MM-dd')
+* @returns Formatted date string
+* @example
+* ```typescript
+* formatDate(new Date(), 'yyyy-MM-dd'); // "2023-01-15"
+* formatDate(new Date(), 'MM/dd/yyyy'); // "01/15/2023"
+* parseDate('2023-01-15'); // Date object
+* isValidDate(new Date()); // true
+* addInterval(new Date(), { days: 7 }); // Date 7 days from now
+* ```
+*/
+var formatDate = (date, formatStr = "yyyy-MM-dd") => {
+	return format(typeof date === "string" ? new Date(date) : date, formatStr);
+};
+/**
+* Parses a date string into a Date object
+*
+* When a format string is provided, uses date-fns `parse` with that format.
+* Otherwise falls back to `parseISO` for ISO 8601 strings.
+*
+* @param dateStr - The date string to parse
+* @param formatStr - Optional format pattern (e.g., 'MM/dd/yyyy', 'dd-MMM-yyyy')
+* @returns Parsed Date object
+* @example
+* ```typescript
+* parseDate('2023-01-15');                // ISO parse
+* parseDate('01/15/2023', 'MM/dd/yyyy');  // Custom format parse
+* ```
+*/
+var parseDate = (dateStr, formatStr) => {
+	if (formatStr) return parse(dateStr, formatStr, /* @__PURE__ */ new Date());
+	return parseISO(dateStr);
+};
+var isValidDate = isValid;
+var addInterval = add;
+/**
+* Gets a temporary directory path (cross-platform)
+*
+* Creates a platform-appropriate temporary directory path under the .have-sdk namespace.
+* Uses environment variables in Node.js or falls back to /tmp.
+*
+* @param subfolder - Optional subfolder name within the temp directory
+* @returns Cross-platform temporary directory path
+* @example
+* ```typescript
+* getTempDirectory(); // "/tmp/.have-sdk" (Unix) or equivalent
+* getTempDirectory("cache"); // "/tmp/.have-sdk/cache"
+* ```
+*/
+var getTempDirectory = (subfolder) => {
+	const basePath = `${process?.env ? process.env.TMPDIR || process.env.TMP || process.env.TEMP || "/tmp" : "/tmp"}/.have-sdk`;
+	return subfolder ? `${basePath}/${subfolder}` : basePath;
+};
+//#endregion
+export { ApiError as A, enableLogging as B, prettyDate as C, urlFilename as D, snakeCase as E, NetworkError as F, extractAllCodeBlocks as G, setLogger as H, ParsingError as I, extractJSON as J, extractCodeBlock as K, TimeoutError as L, DatabaseError as M, ErrorCode as N, urlPath as O, FileError as P, toScreamingSnakeCase as Q, ValidationError as R, pluralizeWord as S, sleep as T, isSafeCode as U, getLogger as V, validateCode as W, loadEnvConfig as X, convertType as Y, toCamelCase as Z, logTicker as _, domainToCamel as a, parseAmazonDateString as b, isArray as c, isPlural as d, isSingular as f, keysToSnake as g, keysToCamel as h, dateInString as i, BaseError as j, waitFor as k, isCuid as l, isValidDate as m, camelCase as n, formatDate as o, isUrl as p, extractFunctionDefinition as q, createId$1 as r, getTempDirectory as s, addInterval as t, isPlainObject as u, makeId as v, singularize as w, parseDate as x, makeSlug as y, disableLogging as z };
+
+//# sourceMappingURL=universal-DOIuUel_.js.map