@dyanet/config-aws 1.0.0

package/dist/esm/loaders/environment.loader.js

@@ -0,0 +1,79 @@
+/**
+ * Loader that reads configuration from process.env.
+ * Supports prefix filtering and exclusion lists.
+ *
+ * @example
+ * ```typescript
+ * // Load all environment variables
+ * const loader = new EnvironmentLoader();
+ *
+ * // Load only variables starting with 'APP_', stripping the prefix
+ * const loader = new EnvironmentLoader({ prefix: 'APP_' });
+ *
+ * // Load all except specific variables
+ * const loader = new EnvironmentLoader({ exclude: ['PATH', 'HOME'] });
+ *
+ * // Combine prefix and exclusion
+ * const loader = new EnvironmentLoader({
+ *   prefix: 'APP_',
+ *   exclude: ['APP_DEBUG']
+ * });
+ * ```
+ */
+export class EnvironmentLoader {
+    constructor(config = {}) {
+        this._config = config;
+    }
+    getName() {
+        return 'EnvironmentLoader';
+    }
+    async isAvailable() {
+        return true;
+    }
+    /**
+     * Load configuration from process.env.
+     *
+     * When a prefix is specified:
+     * - Only variables starting with the prefix are included
+     * - The prefix is stripped from the resulting key names
+     *
+     * When an exclusion list is specified:
+     * - Variables in the list are excluded from the result
+     * - Exclusion is checked against the original key (before prefix stripping)
+     *
+     * @returns Promise resolving to the loaded configuration
+     */
+    async load() {
+        const result = {};
+        const { prefix, exclude = [] } = this._config;
+        const excludeSet = new Set(exclude);
+        for (const [key, value] of Object.entries(process.env)) {
+            // Skip undefined values
+            if (value === undefined) {
+                continue;
+            }
+            // Check exclusion list (against original key)
+            if (excludeSet.has(key)) {
+                continue;
+            }
+            // Handle prefix filtering
+            if (prefix) {
+                if (key.startsWith(prefix)) {
+                    // Strip prefix from key
+                    const strippedKey = key.slice(prefix.length);
+                    // Only include if there's a key remaining after stripping
+                    if (strippedKey) {
+                        result[strippedKey] = value;
+                    }
+                }
+                // Skip keys that don't match the prefix
+            }
+            else {
+                // No prefix - include all non-excluded keys
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=environment.loader.js.map

package/dist/esm/loaders/environment.loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.loader.js","sourceRoot":"","sources":["../../../src/loaders/environment.loader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,iBAAiB;IAI5B,YAAY,SAAkC,EAAE;QAC9C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,OAAO;QACL,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAEpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,wBAAwB;YACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,SAAS;YACX,CAAC;YAED,8CAA8C;YAC9C,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,SAAS;YACX,CAAC;YAED,0BAA0B;YAC1B,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,wBAAwB;oBACxB,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC7C,0DAA0D;oBAC1D,IAAI,WAAW,EAAE,CAAC;wBAChB,MAAM,CAAC,WAAW,CAAC,GAAG,KAAK,CAAC;oBAC9B,CAAC;gBACH,CAAC;gBACD,wCAAwC;YAC1C,CAAC;iBAAM,CAAC;gBACN,4CAA4C;gBAC5C,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/esm/loaders/index.js

@@ -0,0 +1,6 @@
+export { EnvironmentLoader } from './environment.loader';
+export { EnvFileLoader } from './env-file.loader';
+export { S3Loader } from './s3.loader';
+export { SecretsManagerLoader } from './secrets-manager.loader';
+export { SSMParameterStoreLoader } from './ssm-parameter-store.loader';
+//# sourceMappingURL=index.js.map

package/dist/esm/loaders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/loaders/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/esm/loaders/s3.loader.js

@@ -0,0 +1,137 @@
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { EnvFileParser } from '../utils/env-file-parser.util';
+import { AWSServiceError, ConfigurationLoadError } from '../errors';
+/**
+ * Loader that reads configuration from S3 buckets.
+ * Supports JSON and .env file formats with auto-detection.
+ *
+ * @example
+ * ```typescript
+ * // Load JSON config from S3
+ * const loader = new S3Loader({
+ *   bucket: 'my-config-bucket',
+ *   key: 'config/app.json',
+ *   format: 'json'
+ * });
+ *
+ * // Load .env file from S3 with auto-detection
+ * const loader = new S3Loader({
+ *   bucket: 'my-config-bucket',
+ *   key: 'config/.env'
+ * });
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/use-environment-file.html
+ */
+export class S3Loader {
+    constructor(config) {
+        this._config = {
+            bucket: config.bucket,
+            key: config.key,
+            region: config.region || process.env['AWS_REGION'] || 'us-east-1',
+            format: config.format || 'auto',
+        };
+        this._client = new S3Client({
+            credentials: fromNodeProviderChain(),
+            region: this._config.region,
+        });
+    }
+    getName() {
+        return `S3Loader(s3://${this._config.bucket}/${this._config.key})`;
+    }
+    /**
+     * Check if this loader is available by verifying AWS credentials.
+     * @returns Promise resolving to true if AWS credentials are available
+     */
+    async isAvailable() {
+        try {
+            await this._client.config.credentials();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load configuration from S3.
+     * @returns Promise resolving to configuration key-value pairs
+     * @throws AWSServiceError if S3 operation fails
+     * @throws ConfigurationLoadError if content cannot be parsed
+     */
+    async load() {
+        try {
+            const command = new GetObjectCommand({
+                Bucket: this._config.bucket,
+                Key: this._config.key,
+            });
+            const response = await this._client.send(command);
+            if (!response.Body) {
+                return {};
+            }
+            const content = await response.Body.transformToString();
+            if (!content || content.trim() === '') {
+                return {};
+            }
+            return this.parseContent(content);
+        }
+        catch (error) {
+            if (error instanceof ConfigurationLoadError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === 'NoSuchKey' || error.name === 'NoSuchBucket') {
+                    // Object or bucket doesn't exist - return empty config
+                    return {};
+                }
+                if (error.name === 'AccessDenied') {
+                    throw new AWSServiceError(`Access denied when retrieving s3://${this._config.bucket}/${this._config.key}. Check AWS credentials and permissions.`, 'S3', 'GetObject', error);
+                }
+            }
+            throw new AWSServiceError(`Failed to retrieve s3://${this._config.bucket}/${this._config.key}: ${error instanceof Error ? error.message : String(error)}`, 'S3', 'GetObject', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Parse content based on format setting or auto-detection.
+     * @internal
+     */
+    parseContent(content) {
+        const format = this._config.format === 'auto' ? this.detectFormat(content) : this._config.format;
+        if (format === 'json') {
+            return this.parseJson(content);
+        }
+        else {
+            return EnvFileParser.parse(content);
+        }
+    }
+    /**
+     * Detect content format based on structure.
+     * JSON content starts with '{' after trimming whitespace.
+     * @internal
+     */
+    detectFormat(content) {
+        const trimmed = content.trim();
+        if (trimmed.startsWith('{')) {
+            return 'json';
+        }
+        return 'env';
+    }
+    /**
+     * Parse JSON content.
+     * @internal
+     */
+    parseJson(content) {
+        try {
+            const parsed = JSON.parse(content);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            // If not an object, wrap it
+            return { CONFIG_VALUE: parsed };
+        }
+        catch (error) {
+            throw new ConfigurationLoadError(`Failed to parse JSON from s3://${this._config.bucket}/${this._config.key}: ${error instanceof Error ? error.message : String(error)}`, this.getName(), error instanceof Error ? error : undefined);
+        }
+    }
+}
+//# sourceMappingURL=s3.loader.js.map

package/dist/esm/loaders/s3.loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.loader.js","sourceRoot":"","sources":["../../../src/loaders/s3.loader.ts"],"names":[],"mappings":"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"}

package/dist/esm/loaders/secrets-manager.loader.js

@@ -0,0 +1,152 @@
+import { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AWSServiceError, ConfigurationLoadError } from '../errors';
+/**
+ * Loader that reads configuration from AWS Secrets Manager.
+ * Supports environment-aware path construction.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const loader = new SecretsManagerLoader({
+ *   secretName: '/my-app/config',
+ *   region: 'us-east-1'
+ * });
+ *
+ * // With environment mapping
+ * const loader = new SecretsManagerLoader({
+ *   secretName: '/my-app/config',
+ *   environmentMapping: {
+ *     development: 'dev',
+ *     staging: 'stg',
+ *     production: 'prod'
+ *   }
+ * });
+ * ```
+ */
+export class SecretsManagerLoader {
+    constructor(config = {}) {
+        this._appEnv = process.env['APP_ENV'] || process.env['NODE_ENV'] || 'local';
+        // Set default configuration
+        this._config = {
+            secretName: config.secretName || '/nestjs-config-aws',
+            region: config.region || process.env['AWS_REGION'] || 'us-east-1',
+            environmentMapping: config.environmentMapping || {
+                development: 'dev',
+                test: 'test',
+                production: 'production',
+            },
+        };
+        // Initialize AWS Secrets Manager client
+        this._client = new SecretsManagerClient({
+            credentials: fromNodeProviderChain(),
+            region: this._config.region,
+        });
+    }
+    /**
+     * Get the name of this loader for logging and debugging.
+     * @returns The loader name with secret path
+     */
+    getName() {
+        const secretName = this.buildSecretName();
+        return `SecretsManagerLoader(${secretName})`;
+    }
+    /**
+     * Check if this loader is available in the current environment.
+     * @returns Promise resolving to true if not in local environment and AWS credentials are available
+     */
+    async isAvailable() {
+        // Skip in local environment
+        if (this._appEnv === 'local') {
+            return false;
+        }
+        try {
+            // Test AWS credentials by attempting to get caller identity
+            await this._client.config.credentials();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load configuration from AWS Secrets Manager.
+     * @returns Promise resolving to configuration key-value pairs from the secret
+     * @throws AWSServiceError if AWS operation fails
+     * @throws ConfigurationLoadError if secret cannot be parsed
+     */
+    async load() {
+        // Skip loading in local environment
+        if (this._appEnv === 'local') {
+            return {};
+        }
+        const secretName = this.buildSecretName();
+        try {
+            const command = new GetSecretValueCommand({ SecretId: secretName });
+            const response = await this._client.send(command);
+            if (!response.SecretString) {
+                return {};
+            }
+            // Try to parse as JSON, fallback to string value
+            try {
+                const parsed = JSON.parse(response.SecretString);
+                // Ensure we return an object for configuration merging
+                if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                    return parsed;
+                }
+                else {
+                    // If it's not an object, wrap it in a configuration object
+                    return { SECRET_VALUE: parsed };
+                }
+            }
+            catch {
+                // If JSON parsing fails, treat as a single string value
+                return { SECRET_VALUE: response.SecretString };
+            }
+        }
+        catch (error) {
+            // Handle specific AWS errors
+            if (error instanceof Error) {
+                if (error.name === 'ResourceNotFoundException') {
+                    // Secret doesn't exist - this is not necessarily an error in all environments
+                    return {};
+                }
+                if (error.name === 'AccessDeniedException') {
+                    throw new AWSServiceError(`Access denied when retrieving secret '${secretName}'. Check AWS credentials and permissions.`, 'SecretsManager', 'GetSecretValue', error);
+                }
+                if (error.name === 'InvalidRequestException') {
+                    throw new AWSServiceError(`Invalid request when retrieving secret '${secretName}'. Check secret name format.`, 'SecretsManager', 'GetSecretValue', error);
+                }
+            }
+            // For other errors, wrap in AWSServiceError
+            throw new AWSServiceError(`Failed to retrieve secret '${secretName}' from AWS Secrets Manager: ${error instanceof Error ? error.message : String(error)}`, 'SecretsManager', 'GetSecretValue', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Build the environment-aware secret name/path.
+     * @returns The full secret name with environment prefix
+     */
+    buildSecretName() {
+        const envPrefix = this._config.environmentMapping[this._appEnv];
+        if (!envPrefix) {
+            throw new ConfigurationLoadError(`No environment mapping found for APP_ENV '${this._appEnv}'. ` +
+                `Available environments: ${Object.keys(this._config.environmentMapping).join(', ')}`, this.getName());
+        }
+        return `/${envPrefix}${this._config.secretName}`;
+    }
+    /**
+     * Get the current app environment.
+     * @returns The current APP_ENV or NODE_ENV value
+     */
+    getAppEnv() {
+        return this._appEnv;
+    }
+    /**
+     * Get the environment mapping configuration.
+     * @returns The environment mapping record
+     */
+    getEnvironmentMapping() {
+        return { ...this._config.environmentMapping };
+    }
+}
+//# sourceMappingURL=secrets-manager.loader.js.map

package/dist/esm/loaders/secrets-manager.loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets-manager.loader.js","sourceRoot":"","sources":["../../../src/loaders/secrets-manager.loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAItE,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,oBAAoB;IAQ/B,YAAY,SAAqC,EAAE;QACjD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC;QAE5E,4BAA4B;QAC5B,IAAI,CAAC,OAAO,GAAG;YACb,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,oBAAoB;YACrD,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,WAAW;YACjE,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI;gBAC/C,WAAW,EAAE,KAAK;gBAClB,IAAI,EAAE,MAAM;gBACZ,UAAU,EAAE,YAAY;aACzB;SACF,CAAC;QAEF,wCAAwC;QACxC,IAAI,CAAC,OAAO,GAAG,IAAI,oBAAoB,CAAC;YACtC,WAAW,EAAE,qBAAqB,EAAE;YACpC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;SAC5B,CAAC,CAAC;IACL,CAAC;IAGD;;;OAGG;IACH,OAAO;QACL,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1C,OAAO,wBAAwB,UAAU,GAAG,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW;QACf,4BAA4B;QAC5B,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,4DAA4D;YAC5D,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,oCAAoC;QACpC,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAE1C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,qBAAqB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;YACpE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAElD,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;gBAC3B,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,iDAAiD;YACjD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;gBAEjD,uDAAuD;gBACvD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5E,OAAO,MAAM,CAAC;gBAChB,CAAC;qBAAM,CAAC;oBACN,2DAA2D;oBAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;gBAClC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wDAAwD;gBACxD,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC;YACjD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,6BAA6B;YAC7B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,2BAA2B,EAAE,CAAC;oBAC/C,8EAA8E;oBAC9E,OAAO,EAAE,CAAC;gBACZ,CAAC;gBAED,IAAI,KAAK,CAAC,IAAI,KAAK,uBAAuB,EAAE,CAAC;oBAC3C,MAAM,IAAI,eAAe,CACvB,yCAAyC,UAAU,2CAA2C,EAC9F,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,CACN,CAAC;gBACJ,CAAC;gBAED,IAAI,KAAK,CAAC,IAAI,KAAK,yBAAyB,EAAE,CAAC;oBAC7C,MAAM,IAAI,eAAe,CACvB,2CAA2C,UAAU,8BAA8B,EACnF,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,4CAA4C;YAC5C,MAAM,IAAI,eAAe,CACvB,8BAA8B,UAAU,+BAA+B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC/H,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe;QACb,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEhE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,sBAAsB,CAC9B,6CAA6C,IAAI,CAAC,OAAO,KAAK;gBAC5D,2BAA2B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACtF,IAAI,CAAC,OAAO,EAAE,CACf,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACnB,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAChD,CAAC;CACF"}

package/dist/esm/loaders/ssm-parameter-store.loader.js

@@ -0,0 +1,189 @@
+import { GetParametersByPathCommand, SSMClient } from '@aws-sdk/client-ssm';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import { AWSServiceError, ConfigurationLoadError } from '../errors';
+/**
+ * Loader that reads configuration from AWS SSM Parameter Store.
+ * Supports environment-aware path construction, pagination, and decryption options.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const loader = new SSMParameterStoreLoader({
+ *   parameterPath: '/my-app/config',
+ *   region: 'us-east-1'
+ * });
+ *
+ * // With environment mapping
+ * const loader = new SSMParameterStoreLoader({
+ *   parameterPath: '/my-app/config',
+ *   environmentMapping: {
+ *     development: 'dev',
+ *     staging: 'stg',
+ *     production: 'prod'
+ *   }
+ * });
+ * ```
+ */
+export class SSMParameterStoreLoader {
+    constructor(config = {}) {
+        this._appEnv = process.env['APP_ENV'] || process.env['NODE_ENV'] || 'local';
+        // Set default configuration
+        this._config = {
+            parameterPath: config.parameterPath || '/config-aws',
+            region: config.region || process.env['AWS_REGION'] || 'us-east-1',
+            environmentMapping: config.environmentMapping || {
+                development: 'dev',
+                test: 'test',
+                production: 'production',
+            },
+            withDecryption: config.withDecryption ?? true,
+        };
+        // Initialize AWS SSM client
+        this._client = new SSMClient({
+            credentials: fromNodeProviderChain(),
+            region: this._config.region,
+        });
+    }
+    /**
+     * Get the name of this loader for logging and debugging.
+     * @returns The loader name with parameter path
+     */
+    getName() {
+        try {
+            const parameterPath = this.buildParameterPath();
+            return `SSMParameterStoreLoader(${parameterPath})`;
+        }
+        catch {
+            // Fallback if path construction fails (e.g., missing env mapping)
+            return `SSMParameterStoreLoader(${this._config.parameterPath})`;
+        }
+    }
+    /**
+     * Check if this loader is available in the current environment.
+     * @returns Promise resolving to true if not in local environment and AWS credentials are available
+     */
+    async isAvailable() {
+        // Skip in local environment
+        if (this._appEnv === 'local') {
+            return false;
+        }
+        try {
+            // Test AWS credentials by attempting to get caller identity
+            await this._client.config.credentials();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load configuration from AWS SSM Parameter Store.
+     * Implements recursive parameter fetching with NextToken handling for pagination.
+     * @returns Promise resolving to configuration key-value pairs from parameters
+     * @throws AWSServiceError if AWS operation fails
+     * @throws ConfigurationLoadError if parameter path cannot be constructed
+     */
+    async load() {
+        // Skip loading in local environment
+        if (this._appEnv === 'local') {
+            return {};
+        }
+        const parameterPath = this.buildParameterPath();
+        const result = {};
+        let nextToken;
+        try {
+            do {
+                const command = new GetParametersByPathCommand({
+                    Path: parameterPath,
+                    Recursive: true,
+                    WithDecryption: this._config.withDecryption,
+                    NextToken: nextToken,
+                });
+                const response = await this._client.send(command);
+                if (!response.Parameters) {
+                    // No parameters found - this is not necessarily an error
+                    break;
+                }
+                // Process each parameter
+                for (const param of response.Parameters) {
+                    const key = this.transformParameterName(param.Name, parameterPath);
+                    if (key && param.Value !== undefined) {
+                        result[key] = param.Value;
+                    }
+                }
+                nextToken = response.NextToken;
+            } while (nextToken);
+            return result;
+        }
+        catch (error) {
+            // Handle specific AWS errors
+            if (error instanceof Error) {
+                if (error.name === 'ResourceNotFoundException' || error.name === 'ParameterNotFound') {
+                    // No parameters found at path - this is not necessarily an error
+                    return {};
+                }
+                if (error.name === 'AccessDeniedException') {
+                    throw new AWSServiceError(`Access denied when retrieving parameters from path '${parameterPath}'. Check AWS credentials and permissions.`, 'SSM', 'GetParametersByPath', error);
+                }
+                if (error.name === 'InvalidFilterKey' || error.name === 'InvalidFilterValue') {
+                    throw new AWSServiceError(`Invalid parameter path '${parameterPath}'. Check path format.`, 'SSM', 'GetParametersByPath', error);
+                }
+            }
+            // For other errors, wrap in AWSServiceError
+            throw new AWSServiceError(`Failed to retrieve parameters from path '${parameterPath}' in AWS SSM Parameter Store: ${error instanceof Error ? error.message : String(error)}`, 'SSM', 'GetParametersByPath', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Build the environment-aware parameter path.
+     * @returns The full parameter path with environment prefix
+     * @throws ConfigurationLoadError if no environment mapping found
+     */
+    buildParameterPath() {
+        const envPrefix = this._config.environmentMapping[this._appEnv];
+        if (!envPrefix) {
+            throw new ConfigurationLoadError(`No environment mapping found for APP_ENV '${this._appEnv}'. ` +
+                `Available environments: ${Object.keys(this._config.environmentMapping).join(', ')}`, this.getName());
+        }
+        return `/${envPrefix}${this._config.parameterPath}`;
+    }
+    /**
+     * Transform parameter name by removing the prefix and converting to uppercase.
+     * Example: '/dev/config-aws/database/host' -> 'DATABASE_HOST'
+     * @param parameterName The full parameter name from AWS
+     * @param pathPrefix The path prefix to remove
+     * @returns The transformed parameter name or null if invalid
+     */
+    transformParameterName(parameterName, pathPrefix) {
+        if (!parameterName) {
+            return null;
+        }
+        // Remove the path prefix
+        let key = parameterName;
+        if (key.startsWith(pathPrefix)) {
+            key = key.substring(pathPrefix.length);
+        }
+        // Remove leading slash if present
+        if (key.startsWith('/')) {
+            key = key.substring(1);
+        }
+        // Convert slashes to underscores and uppercase
+        key = key.replace(/\//g, '_').toUpperCase();
+        // Return null for empty keys
+        return key || null;
+    }
+    /**
+     * Get the current app environment.
+     * @returns The current APP_ENV or NODE_ENV value
+     */
+    getAppEnv() {
+        return this._appEnv;
+    }
+    /**
+     * Get the environment mapping configuration.
+     * @returns The environment mapping record
+     */
+    getEnvironmentMapping() {
+        return { ...this._config.environmentMapping };
+    }
+}
+//# sourceMappingURL=ssm-parameter-store.loader.js.map

package/dist/esm/loaders/ssm-parameter-store.loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssm-parameter-store.loader.js","sourceRoot":"","sources":["../../../src/loaders/ssm-parameter-store.loader.ts"],"names":[],"mappings":"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"}