@kumix/storage 0.1.0

package/dist/config-t-NVJICl.js

@@ -0,0 +1,410 @@
+//#region src/config.ts
+function getDefaultEnv() {
+	if (typeof process !== "undefined" && process?.env) return process.env;
+}
+function resolveEnv(env) {
+	return env ?? getDefaultEnv();
+}
+/**
+* Environment variable names for storage configuration
+* @public
+*
+* @example
+* ```typescript
+* import { ENV_VARS } from '@kumix/storage';
+*
+* // Check if specific env vars are set
+* console.log(process.env[ENV_VARS.KUMIX_S3_BUCKET]);
+* console.log(process.env[ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME]);
+* ```
+*/
+const ENV_VARS = {
+	KUMIX_S3_PROVIDER: "KUMIX_S3_PROVIDER",
+	KUMIX_S3_REGION: "KUMIX_S3_REGION",
+	KUMIX_S3_BUCKET: "KUMIX_S3_BUCKET",
+	KUMIX_S3_ACCESS_KEY_ID: "KUMIX_S3_ACCESS_KEY_ID",
+	KUMIX_S3_SECRET_ACCESS_KEY: "KUMIX_S3_SECRET_ACCESS_KEY",
+	KUMIX_S3_ENDPOINT: "KUMIX_S3_ENDPOINT",
+	KUMIX_S3_FORCE_PATH_STYLE: "KUMIX_S3_FORCE_PATH_STYLE",
+	KUMIX_S3_PUBLIC_URL: "KUMIX_S3_PUBLIC_URL",
+	KUMIX_CLOUDINARY_CLOUD_NAME: "KUMIX_CLOUDINARY_CLOUD_NAME",
+	KUMIX_CLOUDINARY_API_KEY: "KUMIX_CLOUDINARY_API_KEY",
+	KUMIX_CLOUDINARY_API_SECRET: "KUMIX_CLOUDINARY_API_SECRET",
+	KUMIX_CLOUDINARY_SECURE: "KUMIX_CLOUDINARY_SECURE",
+	KUMIX_CLOUDINARY_FOLDER: "KUMIX_CLOUDINARY_FOLDER"
+};
+/**
+* Get environment variable value
+* @param key - Environment variable name
+* @param env - Optional environment record
+* @internal
+*/
+function getEnvVar(key, env) {
+	const e = resolveEnv(env);
+	if (!e) return void 0;
+	return e[key];
+}
+/**
+* Get required environment variable value
+* @param key - Environment variable name
+* @param env - Optional environment record
+* @internal
+*/
+function getRequiredEnvVar(key, env) {
+	const value = getEnvVar(key, env);
+	if (!value) throw new Error(`Missing required environment variable: ${key}`);
+	return value;
+}
+/**
+* Get boolean environment variable value
+* @param key - Environment variable name
+* @param defaultValue - Default boolean value if not set
+* @param env - Optional environment record
+* @internal
+*/
+function getBooleanEnvVar(key, defaultValue = false, env) {
+	const value = getEnvVar(key, env);
+	if (!value) return defaultValue;
+	return value.toLowerCase() === "true" || value === "1";
+}
+/**
+* Load S3 configuration from environment variables
+* @param env - Optional environment record
+* @returns S3 configuration object
+* @throws Error if required environment variables are missing
+* @public
+*
+* @example
+* ```typescript
+* import { loadS3Config } from '@kumix/storage';
+*
+* // Set environment variables first:
+* // KUMIX_S3_PROVIDER=aws
+* // KUMIX_S3_REGION=us-east-1
+* // KUMIX_S3_BUCKET=my-bucket
+* // KUMIX_S3_ACCESS_KEY_ID=AKIA...
+* // KUMIX_S3_SECRET_ACCESS_KEY=secret...
+*
+* try {
+*   const config = loadS3Config();
+*   console.log(config);
+*   // Returns: {
+*   //   provider: 'aws',
+*   //   region: 'us-east-1',
+*   //   bucket: 'my-bucket',
+*   //   accessKeyId: 'AKIA...',
+*   //   secretAccessKey: 'secret...'
+*   // }
+* } catch (error) {
+*   console.error('Missing S3 configuration:', error.message);
+* }
+* ```
+*/
+function loadS3Config(env) {
+	const provider = getRequiredEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env);
+	const validProviders = [
+		"aws",
+		"cloudflare-r2",
+		"minio",
+		"digitalocean",
+		"supabase",
+		"custom"
+	];
+	if (!validProviders.includes(provider)) throw new Error(`Invalid S3 provider: ${provider}. Must be one of: ${validProviders.join(", ")}`);
+	return {
+		provider,
+		region: getRequiredEnvVar(ENV_VARS.KUMIX_S3_REGION, env),
+		bucket: getRequiredEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env),
+		accessKeyId: getRequiredEnvVar(ENV_VARS.KUMIX_S3_ACCESS_KEY_ID, env),
+		secretAccessKey: getRequiredEnvVar(ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY, env),
+		endpoint: getEnvVar(ENV_VARS.KUMIX_S3_ENDPOINT, env),
+		forcePathStyle: getBooleanEnvVar(ENV_VARS.KUMIX_S3_FORCE_PATH_STYLE, false, env),
+		publicUrl: getEnvVar(ENV_VARS.KUMIX_S3_PUBLIC_URL, env)
+	};
+}
+/**
+* Load Cloudinary configuration from environment variables
+* @param env - Optional environment record
+* @returns Cloudinary configuration object
+* @throws Error if required environment variables are missing
+* @public
+*
+* @example
+* ```typescript
+* import { loadCloudinaryConfig } from '@kumix/storage';
+*
+* // Set environment variables first:
+* // KUMIX_CLOUDINARY_CLOUD_NAME=my-cloud
+* // KUMIX_CLOUDINARY_API_KEY=123456789
+* // KUMIX_CLOUDINARY_API_SECRET=secret...
+* // KUMIX_CLOUDINARY_SECURE=true (optional)
+* // KUMIX_CLOUDINARY_FOLDER=uploads (optional)
+*
+* try {
+*   const config = loadCloudinaryConfig();
+*   console.log(config);
+*   // Returns: {
+*   //   provider: 'cloudinary',
+*   //   cloudName: 'my-cloud',
+*   //   apiKey: '123456789',
+*   //   apiSecret: 'secret...',
+*   //   secure: true,
+*   //   folder: 'uploads'
+*   // }
+* } catch (error) {
+*   console.error('Missing Cloudinary configuration:', error.message);
+* }
+* ```
+*/
+function loadCloudinaryConfig(env) {
+	return {
+		provider: "cloudinary",
+		cloudName: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env),
+		apiKey: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_KEY, env),
+		apiSecret: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_SECRET, env),
+		secure: getBooleanEnvVar(ENV_VARS.KUMIX_CLOUDINARY_SECURE, true, env),
+		folder: getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_FOLDER, env)
+	};
+}
+/**
+* Auto-detect and load storage configuration from environment variables
+* Determines the provider based on available environment variables
+* @param env - Optional environment record
+* @returns Storage configuration object (S3 or Cloudinary)
+* @throws Error if no valid configuration is found
+* @public
+*
+* @example
+* ```typescript
+* import { loadStorageConfig } from '@kumix/storage';
+*
+* // Auto-detection based on available env vars
+* try {
+*   const config = loadStorageConfig();
+*
+*   if (config.provider === 'cloudinary') {
+*     console.log('Using Cloudinary:', config.cloudName);
+*   } else {
+*     console.log('Using S3:', config.provider, config.bucket);
+*   }
+* } catch (error) {
+*   console.error('No storage configuration found:', error.message);
+* }
+*
+* // Explicit provider (set KUMIX_S3_PROVIDER=cloudinary)
+* // Will load Cloudinary config even if S3 vars are also present
+* ```
+*/
+function loadStorageConfig(env) {
+	const provider = getEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env);
+	if (provider) {
+		if (provider === "cloudinary") return loadCloudinaryConfig(env);
+		return loadS3Config(env);
+	}
+	const hasCloudinaryVars = getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env) && getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_KEY, env) && getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_SECRET, env);
+	const hasS3Vars = getEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env) && getEnvVar(ENV_VARS.KUMIX_S3_ACCESS_KEY_ID, env) && getEnvVar(ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY, env);
+	if (hasCloudinaryVars) return loadCloudinaryConfig(env);
+	if (hasS3Vars) {
+		const config = loadS3Config(env);
+		if (!config.provider) config.provider = "aws";
+		return config;
+	}
+	throw new Error("No storage configuration found. Please set either:\n- S3: KUMIX_S3_PROVIDER, KUMIX_S3_REGION, KUMIX_S3_BUCKET, KUMIX_S3_ACCESS_KEY_ID, KUMIX_S3_SECRET_ACCESS_KEY\n- Cloudinary: KUMIX_CLOUDINARY_CLOUD_NAME, KUMIX_CLOUDINARY_API_KEY, KUMIX_CLOUDINARY_API_SECRET");
+}
+/**
+* Check if storage configuration is available in environment variables
+* @param env - Optional environment record
+* @returns True if valid storage configuration is found
+* @public
+*
+* @example
+* ```typescript
+* import { hasStorageConfig, loadStorageConfig } from '@kumix/storage';
+*
+* if (hasStorageConfig()) {
+*   const config = loadStorageConfig();
+*   console.log('Storage configured:', config.provider);
+* } else {
+*   console.log('Please set storage environment variables');
+* }
+*
+* // Use in conditional initialization
+* const storage = hasStorageConfig() ? createStorage() : null;
+* ```
+*/
+function hasStorageConfig(env) {
+	try {
+		loadStorageConfig(env);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if storage configuration is available in environment variables
+* @param env - Optional environment record
+* @returns True if either S3 or Cloudinary configuration is available
+* @public
+*
+* @example
+* ```typescript
+* import { isStorageConfigured, createS3, createCloudinary } from '@kumix/storage';
+*
+* if (isStorageConfigured()) {
+*   // Choose your preferred provider
+*   const s3 = createS3();
+*   // OR
+*   const cloudinary = createCloudinary();
+*
+*   await s3.uploadFile('test.txt', 'Hello World');
+* } else {
+*   console.log('Storage not configured. Please set environment variables.');
+* }
+*
+* // Use in conditional initialization
+* const storage = isStorageConfigured() ? createS3() : null;
+* if (storage) {
+*   await storage.uploadFile('file.txt', content);
+* }
+* ```
+*/
+function isStorageConfigured(env) {
+	return hasStorageConfig(env);
+}
+/**
+* Get storage provider name from environment variables without loading full config
+* @param env - Optional environment record
+* @returns Provider name or undefined if not configured
+* @public
+*
+* @example
+* ```typescript
+* import { getStorageProvider } from '@kumix/storage';
+*
+* const provider = getStorageProvider();
+*
+* switch (provider) {
+*   case 'aws':
+*     console.log('Using AWS S3');
+*     break;
+*   case 'cloudinary':
+*     console.log('Using Cloudinary');
+*     break;
+*   case 'cloudflare-r2':
+*     console.log('Using Cloudflare R2');
+*     break;
+*   default:
+*     console.log('No storage provider configured');
+* }
+*
+* // Quick check without throwing errors
+* if (getStorageProvider()) {
+*   // Storage is configured
+* }
+* ```
+*/
+function getStorageProvider(env) {
+	const provider = getEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env);
+	if (provider) return provider;
+	const hasCloudinaryVars = getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env);
+	const hasS3Vars = getEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env);
+	if (hasCloudinaryVars) return "cloudinary";
+	if (hasS3Vars) return "aws";
+}
+/**
+* Validate if all required environment variables are set for S3
+* @param env - Optional environment record
+* @returns Validation result with missing variables
+* @public
+*
+* @example
+* ```typescript
+* import { validateS3EnvVars } from '@kumix/storage';
+*
+* const validation = validateS3EnvVars();
+*
+* if (validation.valid) {
+*   console.log('S3 configuration is complete');
+* } else {
+*   console.log('Missing S3 variables:', validation.missing);
+*   // Returns: ["KUMIX_S3_REGION", "KUMIX_S3_BUCKET"]
+* }
+* ```
+*/
+function validateS3EnvVars(env) {
+	const missing = [
+		ENV_VARS.KUMIX_S3_PROVIDER,
+		ENV_VARS.KUMIX_S3_REGION,
+		ENV_VARS.KUMIX_S3_BUCKET,
+		ENV_VARS.KUMIX_S3_ACCESS_KEY_ID,
+		ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY
+	].filter((key) => !getEnvVar(key, env));
+	return {
+		valid: missing.length === 0,
+		missing
+	};
+}
+/**
+* Validate if all required environment variables are set for Cloudinary
+* @param env - Optional environment record
+* @returns Validation result with missing variables
+* @public
+*
+* @example
+* ```typescript
+* import { validateCloudinaryEnvVars } from '@kumix/storage';
+*
+* const validation = validateCloudinaryEnvVars();
+*
+* if (validation.valid) {
+*   console.log('Cloudinary configuration is complete');
+* } else {
+*   console.log('Missing Cloudinary variables:', validation.missing);
+*   // Returns: ["KUMIX_CLOUDINARY_API_KEY"]
+* }
+* ```
+*/
+function validateCloudinaryEnvVars(env) {
+	const missing = [
+		ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME,
+		ENV_VARS.KUMIX_CLOUDINARY_API_KEY,
+		ENV_VARS.KUMIX_CLOUDINARY_API_SECRET
+	].filter((key) => !getEnvVar(key, env));
+	return {
+		valid: missing.length === 0,
+		missing
+	};
+}
+/**
+* Get all available environment variables for debugging
+* @param env - Optional environment record
+* @returns Object containing all storage-related env vars
+* @public
+*
+* @example
+* ```typescript
+* import { getStorageEnvVars } from '@kumix/storage';
+*
+* const envVars = getStorageEnvVars();
+* console.log('Storage environment variables:', envVars);
+* // Returns: {
+* //   KUMIX_S3_PROVIDER: 'aws',
+* //   KUMIX_S3_REGION: 'us-east-1',
+* //   KUMIX_S3_BUCKET: 'my-bucket',
+* //   // ... other set variables (secrets are masked)
+* // }
+* ```
+*/
+function getStorageEnvVars(env) {
+	const result = {};
+	Object.values(ENV_VARS).forEach((key) => {
+		const value = getEnvVar(key, env);
+		if (value) if (key.includes("SECRET") || key.includes("API_SECRET")) result[key] = `${value.substring(0, 4)}***`;
+		else result[key] = value;
+	});
+	return result;
+}
+//#endregion
+export { isStorageConfigured as a, loadStorageConfig as c, hasStorageConfig as i, validateCloudinaryEnvVars as l, getStorageEnvVars as n, loadCloudinaryConfig as o, getStorageProvider as r, loadS3Config as s, ENV_VARS as t, validateS3EnvVars as u };
+
+//# sourceMappingURL=config-t-NVJICl.js.map

package/dist/config-t-NVJICl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-t-NVJICl.js","names":[],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Storage configuration from environment variables\n * Provides automatic configuration loading from environment variables\n */\n\nimport type { CloudinaryConfig, S3Config, StorageConfig } from \"./types\";\n\n/**\n * Cross-runtime environment record.\n * Pass `process.env` on Node.js, `ctx.env` on Cloudflare Workers,\n * `Deno.env.toObject()` on Deno, or a plain object in the browser.\n */\nexport type EnvRecord = Record<string, string | undefined>;\n\nfunction getDefaultEnv(): EnvRecord | undefined {\n  if (typeof process !== \"undefined\" && process?.env) {\n    return process.env as EnvRecord;\n  }\n  return undefined;\n}\n\nfunction resolveEnv(env?: EnvRecord): EnvRecord | undefined {\n  return env ?? getDefaultEnv();\n}\n\n/**\n * Environment variable names for storage configuration\n * @public\n *\n * @example\n * ```typescript\n * import { ENV_VARS } from '@kumix/storage';\n *\n * // Check if specific env vars are set\n * console.log(process.env[ENV_VARS.KUMIX_S3_BUCKET]);\n * console.log(process.env[ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME]);\n * ```\n */\nexport const ENV_VARS = {\n  // S3 Configuration\n  KUMIX_S3_PROVIDER: \"KUMIX_S3_PROVIDER\",\n  KUMIX_S3_REGION: \"KUMIX_S3_REGION\",\n  KUMIX_S3_BUCKET: \"KUMIX_S3_BUCKET\",\n  KUMIX_S3_ACCESS_KEY_ID: \"KUMIX_S3_ACCESS_KEY_ID\",\n  KUMIX_S3_SECRET_ACCESS_KEY: \"KUMIX_S3_SECRET_ACCESS_KEY\",\n  KUMIX_S3_ENDPOINT: \"KUMIX_S3_ENDPOINT\",\n  KUMIX_S3_FORCE_PATH_STYLE: \"KUMIX_S3_FORCE_PATH_STYLE\",\n  KUMIX_S3_PUBLIC_URL: \"KUMIX_S3_PUBLIC_URL\",\n\n  // Cloudinary Configuration\n  KUMIX_CLOUDINARY_CLOUD_NAME: \"KUMIX_CLOUDINARY_CLOUD_NAME\",\n  KUMIX_CLOUDINARY_API_KEY: \"KUMIX_CLOUDINARY_API_KEY\",\n  KUMIX_CLOUDINARY_API_SECRET: \"KUMIX_CLOUDINARY_API_SECRET\",\n  KUMIX_CLOUDINARY_SECURE: \"KUMIX_CLOUDINARY_SECURE\",\n  KUMIX_CLOUDINARY_FOLDER: \"KUMIX_CLOUDINARY_FOLDER\",\n} as const;\n\n/**\n * Get environment variable value\n * @param key - Environment variable name\n * @param env - Optional environment record\n * @internal\n */\nfunction getEnvVar(key: string, env?: EnvRecord): string | undefined {\n  const e = resolveEnv(env);\n  if (!e) return undefined;\n  return e[key];\n}\n\n/**\n * Get required environment variable value\n * @param key - Environment variable name\n * @param env - Optional environment record\n * @internal\n */\nfunction getRequiredEnvVar(key: string, env?: EnvRecord): string {\n  const value = getEnvVar(key, env);\n  if (!value) {\n    throw new Error(`Missing required environment variable: ${key}`);\n  }\n  return value;\n}\n\n/**\n * Get boolean environment variable value\n * @param key - Environment variable name\n * @param defaultValue - Default boolean value if not set\n * @param env - Optional environment record\n * @internal\n */\nfunction getBooleanEnvVar(key: string, defaultValue = false, env?: EnvRecord): boolean {\n  const value = getEnvVar(key, env);\n  if (!value) return defaultValue;\n  return value.toLowerCase() === \"true\" || value === \"1\";\n}\n\n/**\n * Load S3 configuration from environment variables\n * @param env - Optional environment record\n * @returns S3 configuration object\n * @throws Error if required environment variables are missing\n * @public\n *\n * @example\n * ```typescript\n * import { loadS3Config } from '@kumix/storage';\n *\n * // Set environment variables first:\n * // KUMIX_S3_PROVIDER=aws\n * // KUMIX_S3_REGION=us-east-1\n * // KUMIX_S3_BUCKET=my-bucket\n * // KUMIX_S3_ACCESS_KEY_ID=AKIA...\n * // KUMIX_S3_SECRET_ACCESS_KEY=secret...\n *\n * try {\n *   const config = loadS3Config();\n *   console.log(config);\n *   // Returns: {\n *   //   provider: 'aws',\n *   //   region: 'us-east-1',\n *   //   bucket: 'my-bucket',\n *   //   accessKeyId: 'AKIA...',\n *   //   secretAccessKey: 'secret...'\n *   // }\n * } catch (error) {\n *   console.error('Missing S3 configuration:', error.message);\n * }\n * ```\n */\nexport function loadS3Config(env?: EnvRecord): S3Config {\n  const provider = getRequiredEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env) as S3Config[\"provider\"];\n\n  // Validate provider\n  const validProviders: S3Config[\"provider\"][] = [\n    \"aws\",\n    \"cloudflare-r2\",\n    \"minio\",\n    \"digitalocean\",\n    \"supabase\",\n    \"custom\",\n  ];\n  if (!validProviders.includes(provider)) {\n    throw new Error(\n      `Invalid S3 provider: ${provider}. Must be one of: ${validProviders.join(\", \")}`,\n    );\n  }\n\n  return {\n    provider,\n    region: getRequiredEnvVar(ENV_VARS.KUMIX_S3_REGION, env),\n    bucket: getRequiredEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env),\n    accessKeyId: getRequiredEnvVar(ENV_VARS.KUMIX_S3_ACCESS_KEY_ID, env),\n    secretAccessKey: getRequiredEnvVar(ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY, env),\n    endpoint: getEnvVar(ENV_VARS.KUMIX_S3_ENDPOINT, env),\n    forcePathStyle: getBooleanEnvVar(ENV_VARS.KUMIX_S3_FORCE_PATH_STYLE, false, env),\n    publicUrl: getEnvVar(ENV_VARS.KUMIX_S3_PUBLIC_URL, env),\n  };\n}\n\n/**\n * Load Cloudinary configuration from environment variables\n * @param env - Optional environment record\n * @returns Cloudinary configuration object\n * @throws Error if required environment variables are missing\n * @public\n *\n * @example\n * ```typescript\n * import { loadCloudinaryConfig } from '@kumix/storage';\n *\n * // Set environment variables first:\n * // KUMIX_CLOUDINARY_CLOUD_NAME=my-cloud\n * // KUMIX_CLOUDINARY_API_KEY=123456789\n * // KUMIX_CLOUDINARY_API_SECRET=secret...\n * // KUMIX_CLOUDINARY_SECURE=true (optional)\n * // KUMIX_CLOUDINARY_FOLDER=uploads (optional)\n *\n * try {\n *   const config = loadCloudinaryConfig();\n *   console.log(config);\n *   // Returns: {\n *   //   provider: 'cloudinary',\n *   //   cloudName: 'my-cloud',\n *   //   apiKey: '123456789',\n *   //   apiSecret: 'secret...',\n *   //   secure: true,\n *   //   folder: 'uploads'\n *   // }\n * } catch (error) {\n *   console.error('Missing Cloudinary configuration:', error.message);\n * }\n * ```\n */\nexport function loadCloudinaryConfig(env?: EnvRecord): CloudinaryConfig {\n  return {\n    provider: \"cloudinary\",\n    cloudName: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env),\n    apiKey: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_KEY, env),\n    apiSecret: getRequiredEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_SECRET, env),\n    secure: getBooleanEnvVar(ENV_VARS.KUMIX_CLOUDINARY_SECURE, true, env),\n    folder: getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_FOLDER, env),\n  };\n}\n\n/**\n * Auto-detect and load storage configuration from environment variables\n * Determines the provider based on available environment variables\n * @param env - Optional environment record\n * @returns Storage configuration object (S3 or Cloudinary)\n * @throws Error if no valid configuration is found\n * @public\n *\n * @example\n * ```typescript\n * import { loadStorageConfig } from '@kumix/storage';\n *\n * // Auto-detection based on available env vars\n * try {\n *   const config = loadStorageConfig();\n *\n *   if (config.provider === 'cloudinary') {\n *     console.log('Using Cloudinary:', config.cloudName);\n *   } else {\n *     console.log('Using S3:', config.provider, config.bucket);\n *   }\n * } catch (error) {\n *   console.error('No storage configuration found:', error.message);\n * }\n *\n * // Explicit provider (set KUMIX_S3_PROVIDER=cloudinary)\n * // Will load Cloudinary config even if S3 vars are also present\n * ```\n */\nexport function loadStorageConfig(env?: EnvRecord): StorageConfig {\n  const provider = getEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env);\n\n  // If provider is explicitly set, use it\n  if (provider) {\n    if (provider === \"cloudinary\") {\n      return loadCloudinaryConfig(env);\n    }\n    return loadS3Config(env);\n  }\n\n  // Auto-detect based on available environment variables\n  const hasCloudinaryVars =\n    getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env) &&\n    getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_KEY, env) &&\n    getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_API_SECRET, env);\n\n  const hasS3Vars =\n    getEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env) &&\n    getEnvVar(ENV_VARS.KUMIX_S3_ACCESS_KEY_ID, env) &&\n    getEnvVar(ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY, env);\n\n  if (hasCloudinaryVars) {\n    return loadCloudinaryConfig(env);\n  }\n  if (hasS3Vars) {\n    // Default to AWS if no provider specified\n    const config = loadS3Config(env);\n    if (!config.provider) {\n      config.provider = \"aws\";\n    }\n    return config;\n  }\n\n  throw new Error(\n    \"No storage configuration found. Please set either:\\n\" +\n      \"- S3: KUMIX_S3_PROVIDER, KUMIX_S3_REGION, KUMIX_S3_BUCKET, KUMIX_S3_ACCESS_KEY_ID, KUMIX_S3_SECRET_ACCESS_KEY\\n\" +\n      \"- Cloudinary: KUMIX_CLOUDINARY_CLOUD_NAME, KUMIX_CLOUDINARY_API_KEY, KUMIX_CLOUDINARY_API_SECRET\",\n  );\n}\n\n/**\n * Check if storage configuration is available in environment variables\n * @param env - Optional environment record\n * @returns True if valid storage configuration is found\n * @public\n *\n * @example\n * ```typescript\n * import { hasStorageConfig, loadStorageConfig } from '@kumix/storage';\n *\n * if (hasStorageConfig()) {\n *   const config = loadStorageConfig();\n *   console.log('Storage configured:', config.provider);\n * } else {\n *   console.log('Please set storage environment variables');\n * }\n *\n * // Use in conditional initialization\n * const storage = hasStorageConfig() ? createStorage() : null;\n * ```\n */\nexport function hasStorageConfig(env?: EnvRecord): boolean {\n  try {\n    loadStorageConfig(env);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Check if storage configuration is available in environment variables\n * @param env - Optional environment record\n * @returns True if either S3 or Cloudinary configuration is available\n * @public\n *\n * @example\n * ```typescript\n * import { isStorageConfigured, createS3, createCloudinary } from '@kumix/storage';\n *\n * if (isStorageConfigured()) {\n *   // Choose your preferred provider\n *   const s3 = createS3();\n *   // OR\n *   const cloudinary = createCloudinary();\n *\n *   await s3.uploadFile('test.txt', 'Hello World');\n * } else {\n *   console.log('Storage not configured. Please set environment variables.');\n * }\n *\n * // Use in conditional initialization\n * const storage = isStorageConfigured() ? createS3() : null;\n * if (storage) {\n *   await storage.uploadFile('file.txt', content);\n * }\n * ```\n */\nexport function isStorageConfigured(env?: EnvRecord): boolean {\n  return hasStorageConfig(env);\n}\n\n/**\n * Get storage provider name from environment variables without loading full config\n * @param env - Optional environment record\n * @returns Provider name or undefined if not configured\n * @public\n *\n * @example\n * ```typescript\n * import { getStorageProvider } from '@kumix/storage';\n *\n * const provider = getStorageProvider();\n *\n * switch (provider) {\n *   case 'aws':\n *     console.log('Using AWS S3');\n *     break;\n *   case 'cloudinary':\n *     console.log('Using Cloudinary');\n *     break;\n *   case 'cloudflare-r2':\n *     console.log('Using Cloudflare R2');\n *     break;\n *   default:\n *     console.log('No storage provider configured');\n * }\n *\n * // Quick check without throwing errors\n * if (getStorageProvider()) {\n *   // Storage is configured\n * }\n * ```\n */\nexport function getStorageProvider(env?: EnvRecord): string | undefined {\n  const provider = getEnvVar(ENV_VARS.KUMIX_S3_PROVIDER, env);\n  if (provider) return provider;\n\n  // Auto-detect\n  const hasCloudinaryVars = getEnvVar(ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME, env);\n  const hasS3Vars = getEnvVar(ENV_VARS.KUMIX_S3_BUCKET, env);\n\n  if (hasCloudinaryVars) return \"cloudinary\";\n  if (hasS3Vars) return \"aws\"; // Default S3 provider\n\n  return undefined;\n}\n\n/**\n * Validate if all required environment variables are set for S3\n * @param env - Optional environment record\n * @returns Validation result with missing variables\n * @public\n *\n * @example\n * ```typescript\n * import { validateS3EnvVars } from '@kumix/storage';\n *\n * const validation = validateS3EnvVars();\n *\n * if (validation.valid) {\n *   console.log('S3 configuration is complete');\n * } else {\n *   console.log('Missing S3 variables:', validation.missing);\n *   // Returns: [\"KUMIX_S3_REGION\", \"KUMIX_S3_BUCKET\"]\n * }\n * ```\n */\nexport function validateS3EnvVars(env?: EnvRecord): {\n  valid: boolean;\n  missing: string[];\n} {\n  const required = [\n    ENV_VARS.KUMIX_S3_PROVIDER,\n    ENV_VARS.KUMIX_S3_REGION,\n    ENV_VARS.KUMIX_S3_BUCKET,\n    ENV_VARS.KUMIX_S3_ACCESS_KEY_ID,\n    ENV_VARS.KUMIX_S3_SECRET_ACCESS_KEY,\n  ];\n\n  const missing = required.filter((key) => !getEnvVar(key, env));\n\n  return {\n    valid: missing.length === 0,\n    missing,\n  };\n}\n\n/**\n * Validate if all required environment variables are set for Cloudinary\n * @param env - Optional environment record\n * @returns Validation result with missing variables\n * @public\n *\n * @example\n * ```typescript\n * import { validateCloudinaryEnvVars } from '@kumix/storage';\n *\n * const validation = validateCloudinaryEnvVars();\n *\n * if (validation.valid) {\n *   console.log('Cloudinary configuration is complete');\n * } else {\n *   console.log('Missing Cloudinary variables:', validation.missing);\n *   // Returns: [\"KUMIX_CLOUDINARY_API_KEY\"]\n * }\n * ```\n */\nexport function validateCloudinaryEnvVars(env?: EnvRecord): {\n  valid: boolean;\n  missing: string[];\n} {\n  const required = [\n    ENV_VARS.KUMIX_CLOUDINARY_CLOUD_NAME,\n    ENV_VARS.KUMIX_CLOUDINARY_API_KEY,\n    ENV_VARS.KUMIX_CLOUDINARY_API_SECRET,\n  ];\n\n  const missing = required.filter((key) => !getEnvVar(key, env));\n\n  return {\n    valid: missing.length === 0,\n    missing,\n  };\n}\n\n/**\n * Get all available environment variables for debugging\n * @param env - Optional environment record\n * @returns Object containing all storage-related env vars\n * @public\n *\n * @example\n * ```typescript\n * import { getStorageEnvVars } from '@kumix/storage';\n *\n * const envVars = getStorageEnvVars();\n * console.log('Storage environment variables:', envVars);\n * // Returns: {\n * //   KUMIX_S3_PROVIDER: 'aws',\n * //   KUMIX_S3_REGION: 'us-east-1',\n * //   KUMIX_S3_BUCKET: 'my-bucket',\n * //   // ... other set variables (secrets are masked)\n * // }\n * ```\n */\nexport function getStorageEnvVars(env?: EnvRecord): Record<string, string | undefined> {\n  const result: Record<string, string | undefined> = {};\n\n  Object.values(ENV_VARS).forEach((key) => {\n    const value = getEnvVar(key, env);\n    if (value) {\n      // Mask sensitive values\n      if (key.includes(\"SECRET\") || key.includes(\"API_SECRET\")) {\n        result[key] = `${value.substring(0, 4)}***`;\n      } else {\n        result[key] = value;\n      }\n    }\n  });\n\n  return result;\n}\n"],"mappings":"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"}