@aligent/aws-wrappers 0.0.1

package/src/sns/sns.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNSService = void 0;
+const logger_1 = require("@aws-lambda-powertools/logger");
+const client_sns_1 = require("@aws-sdk/client-sns");
+const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
+const redact_1 = require("../util/redact");
+const truncate_1 = require("../util/truncate");
+const PUBLISH_BATCH_LIMIT = 10;
+const SNS_MESSAGE_MAX_BYTES = 256 * 1024;
+const SNS_SUBJECT_MAX_CHARS = 100;
+/**
+ * Fields safe to log at INFO level for `publish`. Omits `Message`, `Subject`,
+ * `MessageAttributes`, and `PhoneNumber` — payloads, user-visible content
+ * (subjects often carry order numbers / customer names), and PII recipient
+ * identifiers. `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const PUBLISH_SAFE_FIELDS = [
+    'TopicArn',
+    'TargetArn',
+    'MessageStructure',
+    'MessageGroupId',
+    'MessageDeduplicationId',
+];
+/**
+ * Wrapper around the AWS SNS client providing structured Powertools logging
+ * and X-Ray tracing by default.
+ */
+class SNSService {
+    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 `SNSClient`. When supplied,
+     * the wrapper does not apply X-Ray instrumentation.
+     * @param opts.truncate - When `true`, oversized `Message` / `Subject` are
+     * truncated (byte-safe / codepoint-safe) before sending instead of failing
+     * at the SDK. Defaults to `false` — the SDK throws on oversize, which is
+     * usually the right failure mode. Each `publish` call can override via
+     * its own `truncate` option.
+     */
+    constructor(opts) {
+        this.client = opts?.client ?? (0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_sns_1.SNSClient());
+        this.logger = opts?.logger ?? new logger_1.Logger();
+        this.truncate = opts?.truncate ?? false;
+    }
+    /**
+     * Publish a single message to an SNS topic.
+     *
+     * At INFO level the log line includes only routing / dedup metadata; see
+     * `PUBLISH_SAFE_FIELDS` for the list. Setting `POWERTOOLS_LOG_LEVEL=DEBUG`
+     * unlocks the full input.
+     *
+     * @param input - PublishCommandInput including TopicArn and Message.
+     */
+    async publish(input, opts) {
+        const shouldTruncate = opts?.truncate ?? this.truncate;
+        const effective = shouldTruncate ? this.applyTruncation(input) : input;
+        this.logger.info('Publishing SNS message', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, effective, PUBLISH_SAFE_FIELDS),
+        });
+        return this.client.send(new client_sns_1.PublishCommand(effective));
+    }
+    applyTruncation(input) {
+        const truncated = [];
+        let Message = input.Message;
+        if (Message !== undefined && Buffer.byteLength(Message, 'utf8') > SNS_MESSAGE_MAX_BYTES) {
+            Message = (0, truncate_1.truncateUtf8)(Message, SNS_MESSAGE_MAX_BYTES);
+            truncated.push('Message');
+        }
+        let Subject = input.Subject;
+        if (Subject !== undefined && Array.from(Subject).length > SNS_SUBJECT_MAX_CHARS) {
+            Subject = (0, truncate_1.truncateCodepoints)(Subject, SNS_SUBJECT_MAX_CHARS);
+            truncated.push('Subject');
+        }
+        if (truncated.length > 0) {
+            this.logger.warn('Truncated SNS publish input', { fields: truncated });
+        }
+        return { ...input, Message, Subject };
+    }
+    /**
+     * Publish a batch of messages to an SNS topic. The SNS API caps
+     * PublishBatch at 10 entries per request, so this method auto-chunks
+     * the caller's `PublishBatchRequestEntries` and sends one request per
+     * chunk, returning the array of outputs.
+     * @param input - PublishBatchCommandInput including TopicArn and entries.
+     */
+    async publishBatch(input) {
+        const entries = input.PublishBatchRequestEntries ?? [];
+        // Inline DEBUG check rather than `filterFieldsForLogLevel` because the
+        // safe log shape includes the computed `entryCount`, which isn't a key
+        // on `PublishBatchCommandInput`.
+        const isDebug = this.logger.getLevelName() === 'DEBUG';
+        this.logger.info('Publishing SNS message batch', {
+            input: isDebug ? input : { TopicArn: input.TopicArn, entryCount: entries.length },
+        });
+        const results = [];
+        for (let i = 0; i < entries.length; i += PUBLISH_BATCH_LIMIT) {
+            const chunk = entries.slice(i, i + PUBLISH_BATCH_LIMIT);
+            results.push(await this.client.send(new client_sns_1.PublishBatchCommand({
+                ...input,
+                PublishBatchRequestEntries: chunk,
+            })));
+        }
+        return results;
+    }
+}
+exports.SNSService = SNSService;

package/src/sqs/sqs.d.ts

@@ -0,0 +1,60 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+import { DeleteMessageBatchCommandInput, DeleteMessageBatchCommandOutput, DeleteMessageCommandInput, DeleteMessageCommandOutput, Message, ReceiveMessageCommandInput, SendMessageBatchCommandInput, SendMessageBatchCommandOutput, SendMessageCommandInput, SendMessageCommandOutput, SQSClient } from '@aws-sdk/client-sqs';
+/**
+ * Wrapper around the AWS SQS client providing structured Powertools logging
+ * and X-Ray tracing by default.
+ */
+export declare class SQSService {
+    private readonly client;
+    private readonly logger;
+    private readonly 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?: {
+        logger?: Logger;
+        client?: SQSClient;
+        truncate?: boolean;
+    });
+    /**
+     * 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.
+     */
+    sendMessage(input: SendMessageCommandInput, opts?: {
+        truncate?: boolean;
+    }): Promise<SendMessageCommandOutput>;
+    private applyTruncation;
+    /**
+     * 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.
+     */
+    receiveMessages(input: ReceiveMessageCommandInput): Promise<Message[]>;
+    /**
+     * Delete a single message from an SQS queue.
+     */
+    deleteMessage(input: DeleteMessageCommandInput): Promise<DeleteMessageCommandOutput>;
+    /**
+     * 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.
+     */
+    sendMessageBatch(input: SendMessageBatchCommandInput): Promise<SendMessageBatchCommandOutput[]>;
+    /**
+     * 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.
+     */
+    deleteMessageBatch(input: DeleteMessageBatchCommandInput): Promise<DeleteMessageBatchCommandOutput[]>;
+}

package/src/sqs/sqs.js

@@ -0,0 +1,134 @@
+"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.d.ts

@@ -0,0 +1,84 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Parameter, PutParameterCommandInput, PutParameterCommandOutput, SSMClient } from '@aws-sdk/client-ssm';
+/**
+ * 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.
+ */
+export declare class SSMService {
+    private readonly client;
+    private readonly 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?: {
+        logger?: Logger;
+        client?: SSMClient;
+    });
+    /**
+     * 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.
+     */
+    getParameter(name: string): Promise<string | undefined>;
+    /**
+     * 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.
+     */
+    getParameters<K extends string>(aliases: Record<K, string>): Promise<Record<K, string | undefined>>;
+    /**
+     * 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.
+     */
+    putParameter(input: PutParameterCommandInput): Promise<PutParameterCommandOutput>;
+    /**
+     * Delete an SSM parameter by name.
+     *
+     * Prefer IaC (CDK / Terraform) for parameter lifecycle — use this for
+     * runtime cleanup only.
+     */
+    deleteParameter(name: string): Promise<void>;
+    /**
+     * 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.).
+     */
+    getParametersByPath(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<Parameter[]>;
+}

package/src/ssm/ssm.js

@@ -0,0 +1,144 @@
+"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/redact.d.ts

@@ -0,0 +1,18 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+/**
+ * Return a log-safe projection of `input` based on the logger's configured level.
+ *
+ * At `DEBUG`, the full input is returned unchanged — operators who set
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` (or call `logger.setLogLevel('DEBUG')`) have
+ * explicitly opted into seeing everything, including payloads, secret material
+ * and PII.
+ *
+ * At any other level, only the fields listed in `safeFields` are included.
+ * Missing fields are silently skipped — the result type narrows to
+ * `Pick<T, K>` accordingly.
+ *
+ * Used across the package so that the "what's safe to log at INFO" decision
+ * lives in one place. See `packages/aws-wrappers/CLAUDE.md` ("Logging") for
+ * the design rationale and conventions on building the safe-field lists.
+ */
+export declare function filterFieldsForLogLevel<T extends object, K extends keyof T>(logger: Logger, input: T, safeFields: readonly K[]): T | Pick<T, K>;

package/src/util/redact.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterFieldsForLogLevel = filterFieldsForLogLevel;
+/**
+ * Return a log-safe projection of `input` based on the logger's configured level.
+ *
+ * At `DEBUG`, the full input is returned unchanged — operators who set
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` (or call `logger.setLogLevel('DEBUG')`) have
+ * explicitly opted into seeing everything, including payloads, secret material
+ * and PII.
+ *
+ * At any other level, only the fields listed in `safeFields` are included.
+ * Missing fields are silently skipped — the result type narrows to
+ * `Pick<T, K>` accordingly.
+ *
+ * Used across the package so that the "what's safe to log at INFO" decision
+ * lives in one place. See `packages/aws-wrappers/CLAUDE.md` ("Logging") for
+ * the design rationale and conventions on building the safe-field lists.
+ */
+function filterFieldsForLogLevel(logger, input, safeFields) {
+    if (logger.getLevelName() === 'DEBUG')
+        return input;
+    const out = {};
+    for (const key of safeFields) {
+        if (key in input)
+            out[key] = input[key];
+    }
+    return out;
+}

package/src/util/truncate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export declare function truncateUtf8(str: string, maxBytes: number): string;
+/**
+ * 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.
+ */
+export declare function truncateCodepoints(str: string, maxChars: number): string;

package/src/util/truncate.js

@@ -0,0 +1,36 @@
+"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

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