@aligent/aws-wrappers 0.1.0 → 0.1.1

package/esm/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aligent/aws-wrappers",
+  "version": "0.1.1",
+  "description": "Opinionated AWS SDK wrappers with Powertools logging and X-Ray tracing",
+  "main": "./cjs/index.cjs",
+  "module": "./index.esm.js",
+  "types": "./cjs/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/src/index.d.ts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./cjs/src/index.d.ts",
+        "default": "./cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cjs",
+    "esm",
+    "README.md",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aligent/microservice-development-utilities.git",
+    "directory": "packages/aws-wrappers"
+  },
+  "dependencies": {
+    "@aws-lambda-powertools/logger": "^2.33.0",
+    "@aws-sdk/client-dynamodb": "^3.1045.0",
+    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/client-secrets-manager": "^3.1045.0",
+    "@aws-sdk/client-sfn": "^3.1045.0",
+    "@aws-sdk/client-sns": "^3.1045.0",
+    "@aws-sdk/client-sqs": "^3.1045.0",
+    "@aws-sdk/client-ssm": "^3.1045.0",
+    "@aws-sdk/lib-dynamodb": "^3.1045.0",
+    "@aws-sdk/s3-request-presigner": "^3.1045.0",
+    "aws-xray-sdk-core": "^3.12.0"
+  },
+  "author": "Aligent",
+  "license": "MIT",
+  "devDependencies": {
+    "aws-sdk-client-mock": "^4.1.0"
+  },
+  "type": "module"
+}

package/esm/src/dynamodb/dynamodb.d.ts

@@ -0,0 +1,127 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+import { BatchGetCommandInput, BatchGetCommandOutput, BatchWriteCommandInput, BatchWriteCommandOutput, DeleteCommandInput, DeleteCommandOutput, DynamoDBDocumentClient, GetCommandInput, PutCommandInput, PutCommandOutput, QueryCommandInput, QueryCommandOutput, ScanCommandInput, ScanCommandOutput, UpdateCommandInput, UpdateCommandOutput } from '@aws-sdk/lib-dynamodb';
+/**
+ * DynamoDB command input with a typed `Key`. Used to thread a caller-defined
+ * key shape through the SDK input shape while preserving every other field.
+ */
+type WithTypedKey<TInput, K extends Record<string, unknown>> = Omit<TInput, 'Key'> & {
+    Key: K;
+};
+/**
+ * Wrapper around the AWS DynamoDB Document client providing structured
+ * Powertools logging and X-Ray tracing by default.
+ *
+ * Items are automatically marshalled / unmarshalled via the document client —
+ * callers work with plain TypeScript objects in both directions.
+ */
+export declare class DynamoDBService {
+    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 `DynamoDBDocumentClient`.
+     * When supplied, the wrapper does not apply X-Ray instrumentation. When
+     * omitted, a default `DynamoDBClient` is wrapped with `captureAWSv3Client`
+     * *before* being passed to `DynamoDBDocumentClient.from`, so X-Ray
+     * tracing captures every DynamoDB call.
+     */
+    constructor(opts?: {
+        logger?: LoggerInterface;
+        client?: DynamoDBDocumentClient;
+    });
+    /**
+     * Get an item from DynamoDB.
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected unmarshalled item shape.
+     * @returns The item, or `undefined` if not found.
+     */
+    getItem<K extends Record<string, unknown> = Record<string, unknown>, R extends Record<string, unknown> = Record<string, unknown>>(input: WithTypedKey<GetCommandInput, K>): Promise<R | undefined>;
+    /**
+     * Put an item into DynamoDB. The caller's `Item` is typed as `T`, which
+     * the document client marshalls automatically.
+     * @template T - Type of the item being stored.
+     */
+    putItem<T>(input: Omit<PutCommandInput, 'Item'> & {
+        Item: T;
+    }): Promise<PutCommandOutput>;
+    /**
+     * Update an item in DynamoDB. The `Attributes` field on the response is
+     * typed as `R` — the caller should choose `R` to match their
+     * `ReturnValues` setting:
+     * - `NONE` (default): no `Attributes` returned.
+     * - `ALL_OLD` / `ALL_NEW`: full item.
+     * - `UPDATED_OLD` / `UPDATED_NEW`: only updated attributes (partial).
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected shape of the returned `Attributes`.
+     */
+    updateItem<K extends Record<string, unknown> = Record<string, unknown>, R extends Record<string, unknown> = Record<string, unknown>>(input: WithTypedKey<UpdateCommandInput, K>): Promise<Omit<UpdateCommandOutput, 'Attributes'> & {
+        Attributes?: R;
+    }>;
+    /**
+     * Delete an item from DynamoDB. The `Attributes` field on the response is
+     * typed as `R` — relevant when `ReturnValues: 'ALL_OLD'` is set.
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected shape of the returned `Attributes`.
+     */
+    deleteItem<K extends Record<string, unknown> = Record<string, unknown>, R extends Record<string, unknown> = Record<string, unknown>>(input: WithTypedKey<DeleteCommandInput, K>): Promise<Omit<DeleteCommandOutput, 'Attributes'> & {
+        Attributes?: R;
+    }>;
+    /**
+     * Execute a DynamoDB Query. The full `QueryCommandOutput` is returned with
+     * `Items` typed as `T[]` so callers retain pagination metadata
+     * (`LastEvaluatedKey`, `Count`, etc.).
+     * @template T - Expected shape of each unmarshalled item.
+     */
+    query<T extends Record<string, unknown> = Record<string, unknown>>(input: QueryCommandInput): Promise<Omit<QueryCommandOutput, 'Items'> & {
+        Items?: T[];
+    }>;
+    /**
+     * Scan a DynamoDB table. The full `ScanCommandOutput` is returned with
+     * `Items` typed as `T[]` so callers retain pagination metadata.
+     *
+     * Scan reads every item in the table, so cost and latency grow linearly
+     * with table size; it is rarely the right tool in a runtime service.
+     * Prefer, in order:
+     *
+     *   1. `query` with the table's partition key.
+     *   2. `query` against a GSI or LSI whose key matches your access pattern.
+     *   3. A sparse GSI populated only for the items you need to enumerate.
+     *   4. A denormalised lookup item or table maintained on write.
+     *
+     * Legitimate scan use cases are mostly one-off admin work (export,
+     * migration, audit). For those, prefer the AWS CLI or Console rather than
+     * embedding a scan in a Lambda.
+     *
+     * @template T - Expected shape of each unmarshalled item.
+     */
+    scan<T extends Record<string, unknown> = Record<string, unknown>>(input: ScanCommandInput): Promise<Omit<ScanCommandOutput, 'Items'> & {
+        Items?: T[];
+    }>;
+    /**
+     * Batch-get items from one or more DynamoDB tables.
+     *
+     * Note: this method is intentionally **not** generic. `BatchGet`'s
+     * `Responses` field is a multi-table `Record<string, item[]>` whose item
+     * shapes can differ per table — no single `T` can soundly describe it.
+     * Callers should narrow the result type at the call site.
+     */
+    batchGet(input: BatchGetCommandInput): Promise<BatchGetCommandOutput>;
+    /**
+     * Batch-write items to DynamoDB, retrying `UnprocessedItems` with jittered
+     * exponential backoff. Up to 5 attempts (200ms base delay). Throws when
+     * items remain unprocessed after the final attempt.
+     */
+    batchWrite(input: BatchWriteCommandInput): Promise<BatchWriteCommandOutput>;
+    /**
+     * Paginate over Query results, yielding one unmarshalled item at a time.
+     * @template T - Expected shape of each yielded item.
+     */
+    paginateItems<T extends Record<string, unknown> = Record<string, unknown>>(input: QueryCommandInput): AsyncGenerator<T>;
+    /**
+     * Paginate over Scan results, yielding one unmarshalled item at a time.
+     * @template T - Expected shape of each yielded item.
+     */
+    paginateScan<T extends Record<string, unknown> = Record<string, unknown>>(input: ScanCommandInput): AsyncGenerator<T>;
+}
+export {};

package/esm/src/index.d.ts

@@ -0,0 +1,7 @@
+export { DynamoDBService } from './dynamodb/dynamodb.js';
+export { S3Service } from './s3/s3.js';
+export { SecretsManagerService } from './secrets-manager/secrets-manager.js';
+export { StepFunctionsService } from './sfn/sfn.js';
+export { SNSService } from './sns/sns.js';
+export { SQSService } from './sqs/sqs.js';
+export { SSMService } from './ssm/ssm.js';

package/esm/src/s3/s3.d.ts

@@ -0,0 +1,131 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+import { CopyObjectCommandInput, CopyObjectCommandOutput, DeleteObjectCommandInput, DeleteObjectCommandOutput, DeleteObjectsCommandOutput, GetObjectCommandInput, GetObjectCommandOutput, HeadObjectCommandInput, HeadObjectCommandOutput, PutObjectCommandInput, PutObjectCommandOutput, S3Client } from '@aws-sdk/client-s3';
+/** Tight wrapper input type for `putObject`. */
+type PutObjectInput = Required<Pick<PutObjectCommandInput, 'Bucket' | 'Key' | 'Body'>>;
+/** Tight wrapper input type for `putJsonObject`. */
+type PutJsonObjectInput<T> = {
+    Bucket: string;
+    Key: string;
+    Body: T;
+    Metadata?: Record<string, string>;
+};
+/**
+ * Wrapper around the AWS S3 client providing structured Powertools logging
+ * and X-Ray tracing by default.
+ *
+ * Input shapes are intentionally tight (Bucket/Key/Body only). Callers
+ * needing SDK-level options not exposed here (server-side encryption,
+ * tagging, version IDs) should use `S3Client` directly.
+ */
+export declare class S3Service {
+    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 `S3Client`. When supplied,
+     * the wrapper does not apply X-Ray instrumentation.
+     */
+    constructor(opts?: {
+        logger?: LoggerInterface;
+        client?: S3Client;
+    });
+    /**
+     * Put an object into S3.
+     *
+     * Note: the structured log line only includes `Bucket` and `Key` —
+     * `Body` is omitted to avoid spilling large payloads or sensitive
+     * content into CloudWatch.
+     *
+     * @param input - Bucket, Key, and Body of the object to store.
+     */
+    putObject(input: PutObjectInput): Promise<PutObjectCommandOutput>;
+    /**
+     * Serialise a value to JSON and store it as an S3 object.
+     *
+     * Note: the structured log line only includes `Bucket` and `Key` —
+     * the JSON-encoded body is omitted to avoid spilling potentially
+     * large or sensitive content into CloudWatch.
+     *
+     * @template T - Type of the value being stored.
+     */
+    putJsonObject<T>(input: PutJsonObjectInput<T>): Promise<PutObjectCommandOutput>;
+    /**
+     * Get an object from S3.
+     */
+    getObject(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<GetObjectCommandOutput>;
+    /**
+     * Get an object from S3 and return its body as a string.
+     * @returns The object body as a string, or `undefined` if the response
+     * has no body.
+     */
+    getObjectBody(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<string | undefined>;
+    /**
+     * Get an object from S3 and parse it as JSON.
+     * @template T - Expected type of the parsed value.
+     * @returns The parsed value, or `undefined` if the response has no body.
+     * @throws If the body is non-empty and not valid JSON.
+     */
+    getJsonObject<T>(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<T | undefined>;
+    /**
+     * Fetch the metadata for an S3 object without downloading its body.
+     */
+    headObject(input: Required<Pick<HeadObjectCommandInput, 'Bucket' | 'Key'>>): Promise<HeadObjectCommandOutput>;
+    /**
+     * Copy an object within S3.
+     */
+    copyObject(input: Required<Pick<CopyObjectCommandInput, 'Bucket' | 'Key' | 'CopySource'>>): Promise<CopyObjectCommandOutput>;
+    /**
+     * List object keys under a bucket and optional prefix, auto-paginating
+     * across all pages.
+     */
+    listObjects(bucket: string, prefix?: string): Promise<string[]>;
+    /**
+     * List and JSON-parse every object under a bucket and optional prefix.
+     * Auto-paginated. Objects without a body are skipped.
+     * @template T - Expected type of each parsed object.
+     */
+    getAllObjects<T>(bucket: string, prefix?: string): Promise<T[]>;
+    /**
+     * Generate a presigned URL that callers can use to GET or PUT an S3 object
+     * directly, without going through the wrapper. The signing happens against
+     * the wrapper's `S3Client`, so callers do not need their own client.
+     *
+     * GET URLs are signed with `ResponseContentDisposition: 'attachment'` so
+     * browsers download the object rather than rendering it in-place.
+     *
+     * The input shape is an inline object (rather than the `Required<Pick<...>>`
+     * pattern used by other S3 methods) because this method wraps two SDK
+     * commands rather than one, and `action` / `expiresIn` are wrapper-level
+     * concerns with no SDK-input equivalent.
+     *
+     * @param input.Bucket - The S3 bucket name.
+     * @param input.Key - The S3 object key.
+     * @param input.action - `'get'` to download, `'put'` to upload.
+     * @param input.expiresIn - URL lifetime in seconds. Defaults to 3600 (1 hour).
+     */
+    getPresignedUrl(input: {
+        Bucket: string;
+        Key: string;
+        action: 'get' | 'put';
+        expiresIn?: number;
+    }): Promise<string>;
+    /**
+     * Delete a single object from S3.
+     */
+    deleteObject(input: Required<Pick<DeleteObjectCommandInput, 'Bucket' | 'Key'>>): Promise<DeleteObjectCommandOutput>;
+    /**
+     * Delete multiple objects from S3, auto-chunking the request into batches
+     * of 1000 keys (the S3-enforced DeleteObjects limit). Returns one output
+     * per chunk.
+     */
+    deleteObjects(bucket: string, keys: string[]): Promise<DeleteObjectsCommandOutput[]>;
+    /**
+     * Delete every object in a bucket. Streams the listing page-by-page and
+     * delegates each page's deletion to `deleteObjects`, so peak memory stays
+     * bounded by one page (~1000 keys) regardless of bucket size.
+     * @returns The keys of every deleted object.
+     */
+    emptyBucket(bucket: string): Promise<string[]>;
+}
+export {};

package/esm/src/secrets-manager/secrets-manager.d.ts

@@ -0,0 +1,78 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+import { CreateSecretCommandInput, CreateSecretCommandOutput, DeleteSecretCommandInput, DeleteSecretCommandOutput, PutSecretValueCommandInput, PutSecretValueCommandOutput, SecretsManagerClient, UpdateSecretCommandInput, UpdateSecretCommandOutput } from '@aws-sdk/client-secrets-manager';
+/**
+ * Wrapper around the AWS Secrets Manager client providing structured
+ * Powertools logging and X-Ray tracing by default.
+ *
+ * Write operations (`createSecret`, `updateSecret`, `putSecretValue`,
+ * `deleteSecret`) are exposed for convenience but should be used with care:
+ * secret lifecycle is usually managed by IaC (CDK / Terraform). Prefer IaC
+ * for anything that exists at deploy time; reserve runtime writes for
+ * dynamically-issued credentials, rotation flows, or other genuinely
+ * mutable values.
+ */
+export declare class SecretsManagerService {
+    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 `SecretsManagerClient`. When
+     * supplied, the wrapper does not apply X-Ray instrumentation — the caller
+     * owns that decision.
+     */
+    constructor(opts?: {
+        logger?: LoggerInterface;
+        client?: SecretsManagerClient;
+    });
+    /**
+     * Fetch a secret's string value from Secrets Manager.
+     * @param secretId - The ARN or friendly name of the secret.
+     * @returns The secret's `SecretString` value.
+     * @throws If the response does not contain a `SecretString` (e.g. the secret
+     * stores binary data).
+     */
+    getSecret(secretId: string): Promise<string>;
+    /**
+     * Fetch a secret and parse it as JSON.
+     * @param secretId - The ARN or friendly name of the secret.
+     * @template T - Expected shape of the parsed secret.
+     * @returns The parsed secret value.
+     * @throws If the secret has no `SecretString` or the value is not valid JSON.
+     */
+    getJsonSecret<T>(secretId: string): Promise<T>;
+    /**
+     * Create a new secret. At INFO level the log line includes only identity
+     * and non-secret metadata; `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full
+     * input (including `SecretString` / `SecretBinary`).
+     *
+     * Prefer IaC (CDK / Terraform) for secret lifecycle — use this for
+     * dynamically-issued credentials only.
+     */
+    createSecret(input: CreateSecretCommandInput): Promise<CreateSecretCommandOutput>;
+    /**
+     * Update an existing secret's metadata or value. At INFO level the log
+     * line omits `SecretString` / `SecretBinary`; `POWERTOOLS_LOG_LEVEL=DEBUG`
+     * unlocks the full input.
+     *
+     * Prefer IaC (CDK / Terraform) for secret lifecycle — use this for
+     * runtime metadata updates only.
+     */
+    updateSecret(input: UpdateSecretCommandInput): Promise<UpdateSecretCommandOutput>;
+    /**
+     * Store a new version of a secret's value. At INFO level the log line
+     * omits `SecretString` / `SecretBinary`; `POWERTOOLS_LOG_LEVEL=DEBUG`
+     * unlocks the full input.
+     *
+     * Typically used by rotation flows.
+     */
+    putSecretValue(input: PutSecretValueCommandInput): Promise<PutSecretValueCommandOutput>;
+    /**
+     * Delete a secret. Pass `ForceDeleteWithoutRecovery: true` to bypass the
+     * default 7-30 day recovery window (irreversible).
+     *
+     * Prefer IaC (CDK / Terraform) for secret lifecycle.
+     */
+    deleteSecret(input: DeleteSecretCommandInput): Promise<DeleteSecretCommandOutput>;
+    private fetchSecretString;
+}

package/esm/src/sfn/sfn.d.ts

@@ -0,0 +1,38 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+import { DescribeExecutionCommandInput, DescribeExecutionCommandOutput, ExecutionListItem, ListExecutionsCommandInput, SFNClient, StartExecutionCommandInput, StartExecutionCommandOutput, StopExecutionCommandInput, StopExecutionCommandOutput } from '@aws-sdk/client-sfn';
+/**
+ * Wrapper around the AWS Step Functions client providing structured
+ * Powertools logging and X-Ray tracing by default.
+ */
+export declare class StepFunctionsService {
+    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 `SFNClient`. When supplied,
+     * the wrapper does not apply X-Ray instrumentation.
+     */
+    constructor(opts?: {
+        logger?: LoggerInterface;
+        client?: SFNClient;
+    });
+    /**
+     * List all executions for a state machine, auto-paginating across all
+     * pages. Typically bounded by `statusFilter` and state-machine retention,
+     * so the flat-array shape is safe in practice.
+     */
+    listExecutions(input: ListExecutionsCommandInput): Promise<ExecutionListItem[]>;
+    /**
+     * Start a new Step Functions execution.
+     */
+    startExecution(input: StartExecutionCommandInput): Promise<StartExecutionCommandOutput>;
+    /**
+     * Describe an existing Step Functions execution.
+     */
+    describeExecution(input: DescribeExecutionCommandInput): Promise<DescribeExecutionCommandOutput>;
+    /**
+     * Stop an in-progress Step Functions execution.
+     */
+    stopExecution(input: StopExecutionCommandInput): Promise<StopExecutionCommandOutput>;
+}

package/esm/src/sns/sns.d.ts

@@ -0,0 +1,48 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+import { PublishBatchCommandInput, PublishBatchCommandOutput, PublishCommandInput, PublishCommandOutput, SNSClient } from '@aws-sdk/client-sns';
+/**
+ * Wrapper around the AWS SNS client providing structured Powertools logging
+ * and X-Ray tracing by default.
+ */
+export declare class SNSService {
+    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 `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?: {
+        logger?: LoggerInterface;
+        client?: SNSClient;
+        truncate?: boolean;
+    });
+    /**
+     * 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.
+     */
+    publish(input: PublishCommandInput, opts?: {
+        truncate?: boolean;
+    }): Promise<PublishCommandOutput>;
+    private applyTruncation;
+    /**
+     * 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.
+     */
+    publishBatch(input: PublishBatchCommandInput): Promise<PublishBatchCommandOutput[]>;
+}

package/esm/src/sqs/sqs.d.ts

@@ -0,0 +1,60 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+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?: LoggerInterface;
+        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/esm/src/ssm/ssm.d.ts

@@ -0,0 +1,84 @@
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
+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?: LoggerInterface;
+        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/util/redact.js → esm/src/util/redact.d.ts}

@@ -1,6 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.filterFieldsForLogLevel = filterFieldsForLogLevel;
+import type { LoggerInterface } from '@aws-lambda-powertools/logger/types';
 /**
  * Return a log-safe projection of `input` based on the logger's configured level.
  *
@@ -17,13 +15,4 @@ exports.filterFieldsForLogLevel = filterFieldsForLogLevel;
  * 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;
-}
+export declare function filterFieldsForLogLevel<T extends object, K extends keyof T>(logger: LoggerInterface, input: T, safeFields: readonly K[]): T | Pick<T, K>;

package/esm/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;