@aligent/aws-wrappers 0.1.0 → 0.1.1

package/src/sqs/sqs.js

@@ -1,134 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SQSService = void 0;
-const logger_1 = require("@aws-lambda-powertools/logger");
-const client_sqs_1 = require("@aws-sdk/client-sqs");
-const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
-const redact_1 = require("../util/redact");
-const truncate_1 = require("../util/truncate");
-const SQS_BATCH_LIMIT = 10;
-const SQS_MESSAGE_BODY_MAX_BYTES = 256 * 1024;
-/**
- * Fields safe to log at INFO level for `sendMessage`. Omits `MessageBody` and
- * `MessageAttributes` — both carry payload content.
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const SEND_MESSAGE_SAFE_FIELDS = [
-    'QueueUrl',
-    'DelaySeconds',
-    'MessageGroupId',
-    'MessageDeduplicationId',
-];
-/**
- * Wrapper around the AWS SQS client providing structured Powertools logging
- * and X-Ray tracing by default.
- */
-class SQSService {
-    client;
-    logger;
-    truncate;
-    /**
-     * @param opts.logger - Optional Powertools logger. Defaults to `new Logger()`,
-     * which picks up `POWERTOOLS_SERVICE_NAME` from the environment.
-     * @param opts.client - Optional pre-configured `SQSClient`. When supplied,
-     * the wrapper does not apply X-Ray instrumentation.
-     * @param opts.truncate - When `true`, oversized `MessageBody` is truncated
-     * (byte-safe) before sending instead of failing at the SDK. Defaults to
-     * `false`. Each `sendMessage` call can override via its own `truncate`
-     * option.
-     */
-    constructor(opts) {
-        this.client = opts?.client ?? (0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_sqs_1.SQSClient());
-        this.logger = opts?.logger ?? new logger_1.Logger();
-        this.truncate = opts?.truncate ?? false;
-    }
-    /**
-     * Send a single message to an SQS queue.
-     *
-     * At INFO level the log line includes only queue routing / FIFO metadata;
-     * see `SEND_MESSAGE_SAFE_FIELDS`. `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the
-     * full input.
-     */
-    async sendMessage(input, opts) {
-        const shouldTruncate = opts?.truncate ?? this.truncate;
-        const effective = shouldTruncate ? this.applyTruncation(input) : input;
-        this.logger.info('Sending SQS message', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, effective, SEND_MESSAGE_SAFE_FIELDS),
-        });
-        return this.client.send(new client_sqs_1.SendMessageCommand(effective));
-    }
-    applyTruncation(input) {
-        const truncated = [];
-        let MessageBody = input.MessageBody;
-        if (MessageBody !== undefined &&
-            Buffer.byteLength(MessageBody, 'utf8') > SQS_MESSAGE_BODY_MAX_BYTES) {
-            MessageBody = (0, truncate_1.truncateUtf8)(MessageBody, SQS_MESSAGE_BODY_MAX_BYTES);
-            truncated.push('MessageBody');
-        }
-        if (truncated.length > 0) {
-            this.logger.warn('Truncated SQS sendMessage input', { fields: truncated });
-        }
-        return { ...input, MessageBody };
-    }
-    /**
-     * Receive messages from an SQS queue. Returns an empty array when no
-     * messages are available. No automatic deletion is performed — visibility
-     * timeout semantics are the caller's responsibility.
-     * @returns The `Messages` array from the response, or `[]` if absent.
-     */
-    async receiveMessages(input) {
-        this.logger.info('Receiving SQS messages', { input });
-        const response = await this.client.send(new client_sqs_1.ReceiveMessageCommand(input));
-        return response.Messages ?? [];
-    }
-    /**
-     * Delete a single message from an SQS queue.
-     */
-    async deleteMessage(input) {
-        this.logger.info('Deleting SQS message', { input });
-        return this.client.send(new client_sqs_1.DeleteMessageCommand(input));
-    }
-    /**
-     * Send a batch of messages to an SQS queue. The SQS API caps
-     * SendMessageBatch at 10 entries per request, so this method auto-chunks
-     * the caller's entries and sends one request per chunk.
-     */
-    async sendMessageBatch(input) {
-        const entries = input.Entries ?? [];
-        // Inline DEBUG check rather than `filterFieldsForLogLevel` because the
-        // safe log shape includes the computed `entryCount`, which isn't a key
-        // on `SendMessageBatchCommandInput`.
-        const isDebug = this.logger.getLevelName() === 'DEBUG';
-        this.logger.info('Sending SQS message batch', {
-            input: isDebug ? input : { QueueUrl: input.QueueUrl, entryCount: entries.length },
-        });
-        const results = [];
-        for (let i = 0; i < entries.length; i += SQS_BATCH_LIMIT) {
-            const chunk = entries.slice(i, i + SQS_BATCH_LIMIT);
-            results.push(await this.client.send(new client_sqs_1.SendMessageBatchCommand({ ...input, Entries: chunk })));
-        }
-        return results;
-    }
-    /**
-     * Delete a batch of messages from an SQS queue. The SQS API caps
-     * DeleteMessageBatch at 10 entries per request, so this method auto-chunks
-     * the caller's entries and sends one request per chunk.
-     */
-    async deleteMessageBatch(input) {
-        const entries = input.Entries ?? [];
-        // Inline DEBUG check rather than `filterFieldsForLogLevel` because the
-        // safe log shape includes the computed `entryCount`, which isn't a key
-        // on `DeleteMessageBatchCommandInput`.
-        const isDebug = this.logger.getLevelName() === 'DEBUG';
-        this.logger.info('Deleting SQS message batch', {
-            input: isDebug ? input : { QueueUrl: input.QueueUrl, entryCount: entries.length },
-        });
-        const results = [];
-        for (let i = 0; i < entries.length; i += SQS_BATCH_LIMIT) {
-            const chunk = entries.slice(i, i + SQS_BATCH_LIMIT);
-            results.push(await this.client.send(new client_sqs_1.DeleteMessageBatchCommand({ ...input, Entries: chunk })));
-        }
-        return results;
-    }
-}
-exports.SQSService = SQSService;

package/src/ssm/ssm.js

@@ -1,144 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSMService = void 0;
-const logger_1 = require("@aws-lambda-powertools/logger");
-const client_ssm_1 = require("@aws-sdk/client-ssm");
-const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
-const redact_1 = require("../util/redact");
-/**
- * Fields safe to log at INFO level for `putParameter`. Omits `Value` (the
- * parameter content itself). `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full
- * input.
- */
-const PUT_PARAMETER_SAFE_FIELDS = [
-    'Name',
-    'Type',
-    'Description',
-    'KeyId',
-    'Overwrite',
-    'AllowedPattern',
-    'Tags',
-    'Tier',
-    'Policies',
-    'DataType',
-];
-/**
- * Wrapper around the AWS SSM Parameter Store client providing structured
- * Powertools logging and X-Ray tracing by default. All read operations enable
- * `WithDecryption` — callers needing plaintext should use `SSMClient`
- * directly.
- *
- * Write operations (`putParameter`, `deleteParameter`) are exposed for
- * convenience but should be used with care: parameter lifecycle is usually
- * managed by IaC (CDK / Terraform). Prefer IaC for anything that exists at
- * deploy time; reserve runtime writes for values that genuinely need to
- * mutate within the application.
- */
-class SSMService {
-    client;
-    logger;
-    /**
-     * @param opts.logger - Optional Powertools logger. Defaults to `new Logger()`,
-     * which picks up `POWERTOOLS_SERVICE_NAME` from the environment.
-     * @param opts.client - Optional pre-configured `SSMClient`. When supplied,
-     * the wrapper does not apply X-Ray instrumentation.
-     */
-    constructor(opts) {
-        this.client = opts?.client ?? (0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_ssm_1.SSMClient());
-        this.logger = opts?.logger ?? new logger_1.Logger();
-    }
-    /**
-     * Fetch a single SSM parameter's value.
-     * @param name - The parameter name (or ARN).
-     * @returns The parameter value, or `undefined` if the parameter has no
-     * value set.
-     */
-    async getParameter(name) {
-        this.logger.info('Fetching SSM parameter', { input: { name } });
-        const response = await this.client.send(new client_ssm_1.GetParameterCommand({ Name: name, WithDecryption: true }));
-        return response.Parameter?.Value;
-    }
-    /**
-     * Fetch multiple SSM parameters in a single request. Callers supply an
-     * alias-to-path record, and the returned record is keyed by the same
-     * aliases — so the SSM path is only mentioned at the call site and the
-     * destructured names are whatever the caller wants to use locally:
-     *
-     * ```ts
-     * const { username, password } = await ssm.getParameters({
-     *     username: '/myapp/db/username',
-     *     password: '/myapp/db/password',
-     * });
-     * ```
-     *
-     * @param aliases - Record mapping each desired local alias to its SSM
-     * parameter name (or ARN).
-     * @returns A record keyed by the same aliases, mapping each to the
-     * parameter's value, or `undefined` when the parameter is missing or has
-     * no value.
-     */
-    async getParameters(aliases) {
-        this.logger.info('Fetching SSM parameters', { input: { aliases } });
-        const response = await this.client.send(new client_ssm_1.GetParametersCommand({
-            Names: Object.values(aliases),
-            WithDecryption: true,
-        }));
-        const byPath = new Map();
-        for (const parameter of response.Parameters ?? []) {
-            if (parameter.Name !== undefined)
-                byPath.set(parameter.Name, parameter.Value);
-        }
-        const result = {};
-        for (const alias of Object.keys(aliases)) {
-            result[alias] = byPath.get(aliases[alias]);
-        }
-        return result;
-    }
-    /**
-     * Create or update an SSM parameter. The log line omits `Value` to avoid
-     * leaking secret material.
-     *
-     * Prefer IaC (CDK / Terraform) for parameter lifecycle — use this for
-     * runtime values only.
-     */
-    async putParameter(input) {
-        this.logger.info('Putting SSM parameter', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_PARAMETER_SAFE_FIELDS),
-        });
-        return this.client.send(new client_ssm_1.PutParameterCommand(input));
-    }
-    /**
-     * Delete an SSM parameter by name.
-     *
-     * Prefer IaC (CDK / Terraform) for parameter lifecycle — use this for
-     * runtime cleanup only.
-     */
-    async deleteParameter(name) {
-        this.logger.info('Deleting SSM parameter', { input: { name } });
-        await this.client.send(new client_ssm_1.DeleteParameterCommand({ Name: name }));
-    }
-    /**
-     * Fetch all parameters under an SSM hierarchy path, auto-paginating across
-     * all pages. `Recursive` defaults to `true` (overriding the AWS SDK
-     * default of `false`) to match the typical "load all config under
-     * `/myapp/`" use case.
-     * @param path - The parameter path prefix (e.g. `/myapp/`).
-     * @param opts.recursive - Whether to recurse into nested paths. Defaults
-     * to `true`.
-     * @returns The full `Parameter` objects (including `Version`,
-     * `LastModifiedDate`, etc.).
-     */
-    async getParametersByPath(path, opts) {
-        const recursive = opts?.recursive ?? true;
-        this.logger.info('Fetching SSM parameters by path', {
-            input: { path, recursive },
-        });
-        const paginator = (0, client_ssm_1.paginateGetParametersByPath)({ client: this.client }, { Path: path, Recursive: recursive, WithDecryption: true });
-        const parameters = [];
-        for await (const page of paginator) {
-            parameters.push(...(page.Parameters ?? []));
-        }
-        return parameters;
-    }
-}
-exports.SSMService = SSMService;

package/src/util/truncate.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.truncateUtf8 = truncateUtf8;
-exports.truncateCodepoints = truncateCodepoints;
-/**
- * Truncate a UTF-8 string to fit within `maxBytes` when encoded as UTF-8.
- *
- * Walks back from the cut point to the start of the previous codepoint, so the
- * result is never a malformed UTF-8 sequence. Returns the input unchanged when
- * it already fits.
- */
-function truncateUtf8(str, maxBytes) {
-    const buf = Buffer.from(str, 'utf8');
-    if (buf.length <= maxBytes)
-        return str;
-    let end = maxBytes;
-    while (end > 0) {
-        const byte = buf[end];
-        if (byte === undefined || (byte & 0xc0) !== 0x80)
-            break;
-        end--;
-    }
-    return buf.toString('utf8', 0, end);
-}
-/**
- * Truncate a string to at most `maxChars` Unicode codepoints. Splits the
- * string via `Array.from` so surrogate pairs (emoji, supplementary-plane
- * characters) are not split in the middle. Returns the input unchanged when
- * it already fits.
- */
-function truncateCodepoints(str, maxChars) {
-    const codepoints = Array.from(str);
-    if (codepoints.length <= maxChars)
-        return str;
-    return codepoints.slice(0, maxChars).join('');
-}

package/tsconfig.lib.tsbuildinfo

@@ -1 +0,0 @@
-{"version":"5.9.3"}