@aws-lambda-powertools/parameters/lib/cjs/ssm/SSMProvider.d.ts

The parameters package for the Powertools for AWS Lambda (TypeScript) library

import { SSMClient } from '@aws-sdk/client-ssm';
import type { GetParameterCommandInput, GetParametersByPathCommandInput, GetParametersCommandOutput } from '@aws-sdk/client-ssm';
import { BaseProvider } from '../base/BaseProvider.js';
import type { SSMGetMultipleOptions, SSMGetMultipleOutput, SSMGetOptions, SSMGetOutput, SSMGetParametersByNameFromCacheOutputType, SSMGetParametersByNameOptions, SSMGetParametersByNameOutput, SSMGetParametersByNameOutputInterface, SSMProviderOptions, SSMSetOptions, SSMSplitBatchAndDecryptParametersOutputType } from '../types/SSMProvider.js';
/**
 * ## Intro
 * The Parameters utility provides a SSMProvider that allows to retrieve parameters from AWS Systems Manager.
 *
 * ## Getting started
 *
 * This utility supports AWS SDK v3 for JavaScript only (`@aws-sdk/client-ssm`). This allows the utility to be modular, and you to install only
 * the SDK packages you need and keep your bundle size small.
 *
 * ## Basic usage
 *
 * Retrieve a parameter from SSM:
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter from SSM
 *   const parameter = await parametersProvider.get('/my-parameter');
 * };
 * ```
 *
 * If you want to retrieve a parameter without customizing the provider, you can use the {@link getParameter} function instead.
 *
 * You can also retrieve parameters at once. If you want to get multiple parameters under the same path, you can use the `getMultiple` method.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *  // Retrieve multiple parameters by path from SSM
 *  const parameters = await parametersProvider.getMultiple('/my-parameters-path');
 * };
 * ```
 *
 * If you don't need to customize the provider, you can also use the {@link getParameters} function instead.
 *
 * If instead you want to retrieve multiple parameters by name, you can use the `getParametersByName` method.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve multiple parameters by name from SSM
 *   const parameters = await parametersProvider.getParametersByName({
 *     '/my-parameter-1': {}, // Use default options
 *     '/my-parameter-2': { transform: 'json' }, // Parse the value as JSON
 *   });
 * };
 * ```
 *
 * If you don't need to customize the provider, you can also use the {@link getParametersByName} function instead.
 *
 * ## Advanced usage
 *
 * ### Caching
 *
 * By default, the provider will cache parameters retrieved in-memory for 5 seconds.
 * You can adjust how long values should be kept in cache by using the `maxAge` parameter.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter and cache it for 10 seconds
 *   const parameter = await parametersProvider.get('/my-parameter', { maxAge: 10 });
 *   // Retrieve multiple parameters by path and cache them for 20 seconds
 *   const parameters = await parametersProvider.getMultiple('/my-parameters-path', { maxAge: 20 });
 * };
 * ```
 *
 * When using the `getParametersByName` method, you can set a different `maxAge` for each parameter or set a default `maxAge` for all parameters.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve multiple parameters by name and cache them individually
 *   const parameters = await parametersProvider.getParametersByName({
 *     '/my-parameter-1': { maxAge: 10 }, // Cache for 10 seconds
 *     '/my-parameter-2': { maxAge: 20 }, // Cache for 20 seconds
 *   });
 *   // Retrieve multiple parameters by name and cache them all for 20 seconds
 *   const parameters = await parametersProvider.getParametersByName({
 *     '/my-parameter-1': {},
 *     '/my-parameter-2': {},
 *   }, { maxAge: 20 });
 * };
 * ```
 *
 * If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the `forceFetch` parameter.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter and skip cache
 *   const parameter = await parametersProvider.get('/my-parameter', { forceFetch: true });
 *   // Retrieve multiple parameters and skip cache
 *   const parameters = await parametersProvider.getMultiple('/my-parameters-path', { forceFetch: true });
 * };
 * ```
 *
 * Likewise, you can use the `forceFetch` parameter with the `getParametersByName` method both for individual parameters and for all parameters.
 *
 * ### Decryption
 *
 * If you want to retrieve a parameter that is encrypted, you can use the `decrypt` parameter. This parameter is compatible with `get`, `getMultiple` and `getParametersByName`.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter and decrypt it
 *   const parameter = await parametersProvider.get('/my-parameter', { decrypt: true });
 *   // Retrieve multiple parameters and decrypt them
 *   const parameters = await parametersProvider.getMultiple('/my-parameters-path', { decrypt: true });
 * };
 * ```
 *
 * ### Transformations
 *
 * For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter and parse it as JSON
 *   const parameter = await parametersProvider.get('/my-parameter', { transform: 'json' });
 *   // Retrieve multiple parameters and parse them as JSON
 *   const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'json' });
 * };
 * ```
 *
 * For parameters that are instead stored as base64-encoded binary data, you can use the transform argument set to `binary` for decoding. This will return a decoded string.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a base64-encoded string and decode it
 *   const parameter = await parametersProvider.get('/my-parameter', { transform: 'binary' });
 *   // Retrieve multiple base64-encoded strings and decode them
 *   const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'binary' });
 * };
 * ```
 *
 * Both type of transformations are compatible also with the `getParametersByName` method.
 *
 * ### Extra SDK options
 *
 * When retrieving parameters, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider();
 *
 * export const handler = async (): Promise<void> => {
 *   // Retrieve a parameter and pass extra options to the AWS SDK v3 for JavaScript client
 *   const parameter = await parametersProvider.get('/my-parameter', {
 *     sdkOptions: {
 *       WithDecryption: true,
 *     },
 *   });
 * };
 * ```
 *
 * The objects accept the same options as respectively the [AWS SDK v3 for JavaScript GetParameter command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/getparametercommand.html) and the [AWS SDK v3 for JavaScript GetParametersByPath command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/getparametersbypathcommand.html).
 *
 * ### Customize AWS SDK v3 for JavaScript client
 *
 * By default, the provider will create a new SSM client using the default configuration.
 *
 * You can customize the client by passing a custom configuration object to the provider.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 *
 * const parametersProvider = new SSMProvider({
 *   clientConfig: { region: 'eu-west-1' },
 * });
 * ```
 *
 * This object accepts the same options as the [AWS SDK v3 for JavaScript SSM client constructor](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/ssmclient.html#constructor).
 *
 * Otherwise, if you want to use a custom client altogether, you can pass it to the provider.
 *
 * @example
 * ```typescript
 * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 * import { SSMClient } from '@aws-sdk/client-ssm';
 *
 * const client = new SSMClient({ region: 'eu-west-1' });
 * const parametersProvider = new SSMProvider({
 *   awsSdkV3Client: client,
 * });
 * ```
 *
 * This object must be an instance of the [AWS SDK v3 for JavaScript SSM client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/ssmclient.html).
 *
 * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/).
 */
declare class SSMProvider extends BaseProvider {
    client: SSMClient;
    protected errorsKey: string;
    protected maxGetParametersItems: number;
    /**
     * It initializes the SSMProvider class.
     *
     * @param {SSMProviderOptions} config - The configuration object.
     */
    constructor(config?: SSMProviderOptions);
    /**
     * Retrieve a value from AWS Systems Manager.
     *
     * @example
     * ```typescript
     * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
     *
     * const parametersProvider = new SSMProvider();
     *
     * export const handler = async (): Promise<void> => {
     *   // Retrieve a parameter from SSM
     *   const parameter = await parametersProvider.get('/my-parameter');
     * };
     * ```
     *
     * You can customize the retrieval of the value by passing options to the function:
     * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
     * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
     * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
     * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
     * * `decrypt` - Whether to decrypt the value before returning it.
     *
     * For usage examples check {@link SSMProvider}.
     *
     * @param {string} name - The name of the value to retrieve (i.e. the partition key)
     * @param {SSMGetOptions} options - Options to configure the provider
     * @see https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/
     */
    get<ExplicitUserProvidedType = undefined, InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions>(name: string, options?: InferredFromOptionsType & SSMGetOptions): Promise<SSMGetOutput<ExplicitUserProvidedType, InferredFromOptionsType> | undefined>;
    /**
     * Sets a parameter in AWS Systems Manager (SSM).
     *
     * @example
     * ```typescript
     * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
     *
     * const parametersProvider = new SSMProvider();
     *
     * export const handler = async (): Promise<void> => {
     *   // Set a parameter in SSM
     *   const version = await parametersProvider.set('/my-parameter', { value: 'my-value' });
     *   console.log(`Parameter version: ${version}`);
     * };
     * ```
     *
     * You can customize the storage of the value by passing options to the function:
     * * `value` - The value of the parameter, which is a mandatory option.
     * * `overwrite` - Whether to overwrite the value if it already exists (default: `false`)
     * * `description` - The description of the parameter
     * * `parameterType` - The type of the parameter, can be one of `String`, `StringList`, or `SecureString` (default: `String`)
     * * `tier` - The parameter tier to use, can be one of `Standard`, `Advanced`, and `Intelligent-Tiering` (default: `Standard`)
     * * `kmsKeyId` - The KMS key id to use to encrypt the parameter
     * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
     *
     * @param {string} name - The name of the parameter
     * @param {SSMSetOptions} options - Options to configure the parameter
     * @returns {Promise<number>} The version of the parameter
     * @see https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/
     */
    set<InferredFromOptionsType extends SSMSetOptions | undefined = SSMSetOptions>(name: string, options: InferredFromOptionsType & SSMSetOptions): Promise<number>;
    /**
     * Retrieve multiple values from AWS Systems Manager.
     *
     * @example
     * ```typescript
     * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
     *
     * const parametersProvider = new SSMProvider();
     *
     * export const handler = async (): Promise<void> => {
     *   // Retrieve multiple parameters from SSM
     *   const parameters = await parametersProvider.getMultiple('/my-parameters-path');
     * };
     * ```
     *
     * You can customize the retrieval of the values by passing options to the function:
     * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
     * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
     * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
     * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
     * * `throwOnTransformError` - Whether to throw an error if the transform fails (default: `true`)
     * * `decrypt` - Whether to decrypt the value before returning it.
     * * `recursive` - Whether to recursively retrieve all parameters under the given path (default: `false`)
     *
     * For usage examples check {@link SSMProvider}.
     *
     * @param {string} path - The path of the parameters to retrieve
     * @param {SSMGetMultipleOptions} options - Options to configure the retrieval
     * @see https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/
     */
    getMultiple<ExplicitUserProvidedType = undefined, InferredFromOptionsType extends SSMGetMultipleOptions | undefined = undefined>(path: string, options?: InferredFromOptionsType & SSMGetMultipleOptions): Promise<SSMGetMultipleOutput<ExplicitUserProvidedType, InferredFromOptionsType> | undefined>;
    /**
     * Retrieve multiple parameters by name from AWS Systems Manager.
     *
     * @example
     * ```typescript
     * import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
     *
     * const parametersProvider = new SSMProvider();
     *
     * export const handler = async (): Promise<void> => {
     *   // Retrieve multiple parameters by name from SSM
     *   const parameters = await parametersProvider.getParametersByName({
     *     '/my-parameter-1': {}, // Use default options
     *     '/my-parameter-2': { transform: 'json' }, // Parse the value as JSON
     *   });
     * };
     * ```
     * You can customize the retrieval of the values by passing options to **both the function and the parameter**:
     * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
     * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
     * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
     * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
     * * `throwOnTransformError` - Whether to throw an error if the transform fails (default: `true`)
     * * `decrypt` - Whether to decrypt the value before returning it
     *
     * `throwOnError` decides whether to throw an error if a parameter is not found:
     * - A) Default fail-fast behavior: Throws a `GetParameterError` error upon any failure.
     * - B) Gracefully aggregate all parameters that failed under "_errors" key.
     *
     * It transparently uses GetParameter and/or GetParameters depending on decryption requirements.
     *
     * ```sh
     *                                ┌────────────────────────┐
     *                            ┌───▶  Decrypt entire batch  │─────┐
     *                            │   └────────────────────────┘     │     ┌────────────────────┐
     *                            │                                  ├─────▶ GetParameters API  │
     *    ┌──────────────────┐    │   ┌────────────────────────┐     │     └────────────────────┘
     *    │   Split batch    │─── ┼──▶│ No decryption required │─────┘
     *    └──────────────────┘    │   └────────────────────────┘
     *                            │                                        ┌────────────────────┐
     *                            │   ┌────────────────────────┐           │  GetParameter API  │
     *                            └──▶│Decrypt some but not all│───────────▶────────────────────┤
     *                                └────────────────────────┘           │ GetParameters API  │
     *                                                                     └────────────────────┘
     * ```
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - Object containing parameter names and any optional overrides
     * @param {SSMGetParametersByNameOptions} options - Options to configure the retrieval
     * @see https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/
     */
    getParametersByName<ExplicitUserProvidedType = undefined>(parameters: Record<string, SSMGetParametersByNameOptions>, options?: SSMGetParametersByNameOptions): Promise<SSMGetParametersByNameOutput<ExplicitUserProvidedType>>;
    /**
     * Retrieve a parameter from AWS Systems Manager.
     *
     * @param {string} name - Name of the parameter to retrieve
     * @param {SSMGetOptions} options - Options to customize the retrieval
     */
    protected _get(name: string, options?: SSMGetOptions): Promise<string | undefined>;
    /**
     * Retrieve multiple items from AWS Systems Manager.
     *
     * @param {string} path - The path of the parameters to retrieve
     * @param {SSMGetMultipleOptions} options - Options to configure the provider
     */
    protected _getMultiple(path: string, options?: SSMGetMultipleOptions): Promise<Record<string, string | undefined>>;
    /**
     * Retrieve multiple items by name from AWS Systems Manager.
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {throwOnError} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     * @param {boolean} decrypt - Whether to decrypt the parameters or not
     */
    protected _getParametersByName(parameters: Record<string, SSMGetParametersByNameOptions>, throwOnError: boolean, decrypt: boolean): Promise<SSMGetParametersByNameOutputInterface>;
    /**
     * Slice batch and fetch parameters using GetPrameters API by max permissible batch size
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {throwOnError} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     * @param {boolean} decrypt - Whether to decrypt the parameters or not
     */
    protected getParametersBatchByName(parameters: Record<string, SSMGetParametersByNameOptions>, throwOnError: boolean, decrypt: boolean): Promise<SSMGetParametersByNameOutputInterface>;
    /**
     * Fetch each parameter from batch that hasn't expired from cache
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     */
    protected getParametersByNameFromCache(parameters: Record<string, SSMGetParametersByNameOptions>): Promise<SSMGetParametersByNameFromCacheOutputType>;
    /**
     * Slice object into chunks of max permissible batch size and fetch parameters
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     * @param {boolean} decrypt - Whether to decrypt the parameters or not
     */
    protected getParametersByNameInChunks(parameters: Record<string, SSMGetParametersByNameOptions>, throwOnError: boolean, decrypt: boolean): Promise<SSMGetParametersByNameOutputInterface>;
    /**
     * Fetch parameters by name while also decrypting them
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     */
    protected getParametersByNameWithDecryptOption(parameters: Record<string, SSMGetParametersByNameOptions>, throwOnError: boolean): Promise<SSMGetParametersByNameOutputInterface>;
    /**
     * Handle any invalid parameters returned by GetParameters API
     * GetParameters is non-atomic. Failures don't always reflect in exceptions so we need to collect.
     *
     * @param {GetParametersCommandOutput} result - The result of the GetParameters API call
     * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     */
    protected static handleAnyInvalidGetParameterErrors(result: GetParametersCommandOutput, throwOnError: boolean): string[];
    protected resolveDecryptionConfigValue(options?: SSMGetOptions | SSMGetMultipleOptions, sdkOptions?: GetParameterCommandInput | GetParametersByPathCommandInput): boolean | undefined;
    /**
     * Split parameters that can be fetched by GetParameters vs GetParameter.
     *
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {SSMGetParametersByNameOptions} configs - The configs passed down
     */
    protected static splitBatchAndDecryptParameters(parameters: Record<string, SSMGetParametersByNameOptions>, configs: SSMGetParametersByNameOptions): SSMSplitBatchAndDecryptParametersOutputType;
    /**
     * Throw a GetParameterError if fail-fast is disabled and `_errors` key is in parameters list.
     *
     * @param {Record<string, unknown>} parameters
     * @param {string} reservedParameter
     * @param {boolean} throwOnError
     */
    protected static throwIfErrorsKeyIsPresent(parameters: Record<string, unknown>, reservedParameter: string, throwOnError: boolean): void;
    /**
     * Transform and cache the response from GetParameters API call
     *
     * @param {GetParametersCommandOutput} response - The response from the GetParameters API call
     * @param {Record<string, SSMGetParametersByNameOptions>} parameters - An object of parameter names and their options
     * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully
     */
    protected transformAndCacheGetParametersResponse(response: GetParametersCommandOutput, parameters: Record<string, SSMGetParametersByNameOptions>, throwOnError: boolean): Record<string, unknown>;
}
export { SSMProvider };
//# sourceMappingURL=SSMProvider.d.ts.map