@aligent/aws-wrappers 0.0.1

package/src/s3/s3.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Service = void 0;
+const logger_1 = require("@aws-lambda-powertools/logger");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
+const redact_1 = require("../util/redact");
+const DEFAULT_PRESIGNED_URL_EXPIRES_IN_SECONDS = 3600;
+const DELETE_OBJECTS_BATCH_LIMIT = 1000;
+/**
+ * Fields safe to log at INFO for `putObject`. Omits `Body` (object payload).
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const PUT_OBJECT_SAFE_FIELDS = ['Bucket', 'Key'];
+/**
+ * Fields safe to log at INFO for `putJsonObject`. Omits `Body` (the
+ * unserialised JSON payload). `Metadata` is included (operational labels).
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const PUT_JSON_OBJECT_SAFE_FIELDS = [
+    'Bucket',
+    'Key',
+    'Metadata',
+];
+/**
+ * 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.
+ */
+class S3Service {
+    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 `S3Client`. 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_s3_1.S3Client());
+        this.logger = opts?.logger ?? new logger_1.Logger();
+    }
+    /**
+     * 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.
+     */
+    async putObject(input) {
+        this.logger.info('Putting S3 object', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_OBJECT_SAFE_FIELDS),
+        });
+        return this.client.send(new client_s3_1.PutObjectCommand(input));
+    }
+    /**
+     * 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.
+     */
+    async putJsonObject(input) {
+        this.logger.info('Putting S3 JSON object', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_JSON_OBJECT_SAFE_FIELDS),
+        });
+        return this.client.send(new client_s3_1.PutObjectCommand({
+            Bucket: input.Bucket,
+            Key: input.Key,
+            Body: JSON.stringify(input.Body),
+            Metadata: input.Metadata,
+        }));
+    }
+    /**
+     * Get an object from S3.
+     */
+    async getObject(input) {
+        this.logger.info('Getting S3 object', { input });
+        return this.client.send(new client_s3_1.GetObjectCommand(input));
+    }
+    /**
+     * 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.
+     */
+    async getObjectBody(input) {
+        this.logger.info('Getting S3 object body', { input });
+        const response = await this.client.send(new client_s3_1.GetObjectCommand(input));
+        return response.Body?.transformToString();
+    }
+    /**
+     * 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.
+     */
+    async getJsonObject(input) {
+        this.logger.info('Getting S3 JSON object', { input });
+        const response = await this.client.send(new client_s3_1.GetObjectCommand(input));
+        const body = await response.Body?.transformToString();
+        return body ? JSON.parse(body) : undefined;
+    }
+    /**
+     * Fetch the metadata for an S3 object without downloading its body.
+     */
+    async headObject(input) {
+        this.logger.info('Fetching S3 object metadata', { input });
+        return this.client.send(new client_s3_1.HeadObjectCommand(input));
+    }
+    /**
+     * Copy an object within S3.
+     */
+    async copyObject(input) {
+        this.logger.info('Copying S3 object', { input });
+        return this.client.send(new client_s3_1.CopyObjectCommand(input));
+    }
+    /**
+     * List object keys under a bucket and optional prefix, auto-paginating
+     * across all pages.
+     */
+    async listObjects(bucket, prefix) {
+        this.logger.info('Listing S3 objects', { input: { bucket, prefix } });
+        const paginator = (0, client_s3_1.paginateListObjectsV2)({ client: this.client }, { Bucket: bucket, Prefix: prefix });
+        const keys = [];
+        for await (const page of paginator) {
+            for (const object of page.Contents ?? []) {
+                if (object.Key)
+                    keys.push(object.Key);
+            }
+        }
+        return keys;
+    }
+    /**
+     * 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.
+     */
+    async getAllObjects(bucket, prefix) {
+        this.logger.info('Getting all S3 objects', { input: { bucket, prefix } });
+        const paginator = (0, client_s3_1.paginateListObjectsV2)({ client: this.client }, { Bucket: bucket, Prefix: prefix });
+        const bodies = [];
+        for await (const page of paginator) {
+            for (const object of page.Contents ?? []) {
+                if (!object.Key)
+                    continue;
+                const response = await this.client.send(new client_s3_1.GetObjectCommand({ Bucket: bucket, Key: object.Key }));
+                const body = await response.Body?.transformToString();
+                if (body)
+                    bodies.push(JSON.parse(body));
+            }
+        }
+        return bodies;
+    }
+    /**
+     * 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).
+     */
+    async getPresignedUrl(input) {
+        const expiresIn = input.expiresIn ?? DEFAULT_PRESIGNED_URL_EXPIRES_IN_SECONDS;
+        this.logger.info('Generating S3 presigned URL', {
+            input: { Bucket: input.Bucket, Key: input.Key, action: input.action, expiresIn },
+        });
+        const command = input.action === 'get'
+            ? new client_s3_1.GetObjectCommand({
+                Bucket: input.Bucket,
+                Key: input.Key,
+                ResponseContentDisposition: 'attachment',
+            })
+            : new client_s3_1.PutObjectCommand({ Bucket: input.Bucket, Key: input.Key });
+        return (0, s3_request_presigner_1.getSignedUrl)(this.client, command, { expiresIn });
+    }
+    /**
+     * Delete a single object from S3.
+     */
+    async deleteObject(input) {
+        this.logger.info('Deleting S3 object', { input });
+        return this.client.send(new client_s3_1.DeleteObjectCommand(input));
+    }
+    /**
+     * Delete multiple objects from S3, auto-chunking the request into batches
+     * of 1000 keys (the S3-enforced DeleteObjects limit). Returns one output
+     * per chunk.
+     */
+    async deleteObjects(bucket, keys) {
+        // Inline DEBUG check rather than `filterFieldsForLogLevel` because the
+        // safe log shape includes the computed `keyCount`, which isn't a key
+        // on any SDK input type.
+        const isDebug = this.logger.getLevelName() === 'DEBUG';
+        this.logger.info('Deleting S3 objects', {
+            input: isDebug ? { bucket, keys } : { bucket, keyCount: keys.length },
+        });
+        const results = [];
+        for (let i = 0; i < keys.length; i += DELETE_OBJECTS_BATCH_LIMIT) {
+            const batch = keys.slice(i, i + DELETE_OBJECTS_BATCH_LIMIT);
+            results.push(await this.client.send(new client_s3_1.DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: batch.map(Key => ({ Key })) },
+            })));
+        }
+        return results;
+    }
+    /**
+     * 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.
+     */
+    async emptyBucket(bucket) {
+        this.logger.info('Emptying S3 bucket', { input: { bucket } });
+        const paginator = (0, client_s3_1.paginateListObjectsV2)({ client: this.client }, { Bucket: bucket });
+        const deletedKeys = [];
+        for await (const page of paginator) {
+            const keys = (page.Contents ?? []).flatMap(o => (o.Key ? [o.Key] : []));
+            if (keys.length === 0)
+                continue;
+            await this.deleteObjects(bucket, keys);
+            deletedKeys.push(...keys);
+        }
+        return deletedKeys;
+    }
+}
+exports.S3Service = S3Service;

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

@@ -0,0 +1,78 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+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?: Logger;
+        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/src/secrets-manager/secrets-manager.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsManagerService = void 0;
+const logger_1 = require("@aws-lambda-powertools/logger");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
+const redact_1 = require("../util/redact");
+/**
+ * Fields safe to log at INFO level. Omits `SecretString` and `SecretBinary` —
+ * the secret material itself. `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full
+ * input.
+ */
+const CREATE_SECRET_SAFE_FIELDS = [
+    'Name',
+    'Description',
+    'KmsKeyId',
+    'Tags',
+    'ClientRequestToken',
+    'AddReplicaRegions',
+    'ForceOverwriteReplicaSecret',
+];
+const UPDATE_SECRET_SAFE_FIELDS = [
+    'SecretId',
+    'Description',
+    'KmsKeyId',
+    'ClientRequestToken',
+];
+const PUT_SECRET_VALUE_SAFE_FIELDS = [
+    'SecretId',
+    'VersionStages',
+    'ClientRequestToken',
+];
+/**
+ * `DeleteSecretCommandInput` carries no secret material today, but the
+ * explicit allowlist keeps the log shape consistent with the other write
+ * methods and protects against future field additions.
+ */
+const DELETE_SECRET_SAFE_FIELDS = [
+    'SecretId',
+    'RecoveryWindowInDays',
+    'ForceDeleteWithoutRecovery',
+];
+/**
+ * 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.
+ */
+class SecretsManagerService {
+    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 `SecretsManagerClient`. When
+     * supplied, the wrapper does not apply X-Ray instrumentation — the caller
+     * owns that decision.
+     */
+    constructor(opts) {
+        this.client = opts?.client ?? (0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_secrets_manager_1.SecretsManagerClient());
+        this.logger = opts?.logger ?? new logger_1.Logger();
+    }
+    /**
+     * 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).
+     */
+    async getSecret(secretId) {
+        this.logger.info('Fetching secret', { input: { secretId } });
+        return this.fetchSecretString(secretId);
+    }
+    /**
+     * 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.
+     */
+    async getJsonSecret(secretId) {
+        this.logger.info('Fetching JSON secret', { input: { secretId } });
+        const secretString = await this.fetchSecretString(secretId);
+        return JSON.parse(secretString);
+    }
+    /**
+     * 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.
+     */
+    async createSecret(input) {
+        this.logger.info('Creating secret', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, CREATE_SECRET_SAFE_FIELDS),
+        });
+        return this.client.send(new client_secrets_manager_1.CreateSecretCommand(input));
+    }
+    /**
+     * 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.
+     */
+    async updateSecret(input) {
+        this.logger.info('Updating secret', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, UPDATE_SECRET_SAFE_FIELDS),
+        });
+        return this.client.send(new client_secrets_manager_1.UpdateSecretCommand(input));
+    }
+    /**
+     * 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.
+     */
+    async putSecretValue(input) {
+        this.logger.info('Putting secret value', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_SECRET_VALUE_SAFE_FIELDS),
+        });
+        return this.client.send(new client_secrets_manager_1.PutSecretValueCommand(input));
+    }
+    /**
+     * Delete a secret. Pass `ForceDeleteWithoutRecovery: true` to bypass the
+     * default 7-30 day recovery window (irreversible).
+     *
+     * Prefer IaC (CDK / Terraform) for secret lifecycle.
+     */
+    async deleteSecret(input) {
+        this.logger.info('Deleting secret', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, DELETE_SECRET_SAFE_FIELDS),
+        });
+        return this.client.send(new client_secrets_manager_1.DeleteSecretCommand(input));
+    }
+    async fetchSecretString(secretId) {
+        const response = await this.client.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretId }));
+        if (response.SecretString === undefined) {
+            throw new Error(`Secret '${secretId}' does not contain a string value`);
+        }
+        return response.SecretString;
+    }
+}
+exports.SecretsManagerService = SecretsManagerService;

package/src/sfn/sfn.d.ts

@@ -0,0 +1,38 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+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?: Logger;
+        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/src/sfn/sfn.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StepFunctionsService = void 0;
+const logger_1 = require("@aws-lambda-powertools/logger");
+const client_sfn_1 = require("@aws-sdk/client-sfn");
+const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
+const redact_1 = require("../util/redact");
+/**
+ * Fields safe to log at INFO for `startExecution`. Omits `input` — the SFN
+ * execution payload, which routinely carries PII (customer IDs, addresses,
+ * order contents, etc.). `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const START_EXECUTION_SAFE_FIELDS = [
+    'stateMachineArn',
+    'name',
+    'traceHeader',
+];
+/**
+ * Wrapper around the AWS Step Functions client providing structured
+ * Powertools logging and X-Ray tracing by default.
+ */
+class StepFunctionsService {
+    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 `SFNClient`. 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_sfn_1.SFNClient());
+        this.logger = opts?.logger ?? new logger_1.Logger();
+    }
+    /**
+     * 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.
+     */
+    async listExecutions(input) {
+        this.logger.info('Listing Step Functions executions', { input });
+        const paginator = (0, client_sfn_1.paginateListExecutions)({ client: this.client }, input);
+        const executions = [];
+        for await (const page of paginator) {
+            if (page.executions)
+                executions.push(...page.executions);
+        }
+        return executions;
+    }
+    /**
+     * Start a new Step Functions execution.
+     */
+    async startExecution(input) {
+        this.logger.info('Starting Step Functions execution', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, START_EXECUTION_SAFE_FIELDS),
+        });
+        return this.client.send(new client_sfn_1.StartExecutionCommand(input));
+    }
+    /**
+     * Describe an existing Step Functions execution.
+     */
+    async describeExecution(input) {
+        this.logger.info('Describing Step Functions execution', { input });
+        return this.client.send(new client_sfn_1.DescribeExecutionCommand(input));
+    }
+    /**
+     * Stop an in-progress Step Functions execution.
+     */
+    async stopExecution(input) {
+        this.logger.info('Stopping Step Functions execution', { input });
+        return this.client.send(new client_sfn_1.StopExecutionCommand(input));
+    }
+}
+exports.StepFunctionsService = StepFunctionsService;

package/src/sns/sns.d.ts

@@ -0,0 +1,48 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+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?: Logger;
+        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[]>;
+}