@aligent/aws-wrappers 0.0.1

package/docs/classes/SSMService.md

@@ -0,0 +1,157 @@
+[**@aligent/aws-wrappers**](../modules.md)
+
+***
+
+[@aligent/aws-wrappers](../modules.md) / SSMService
+
+# Class: SSMService
+
+Defined in: [ssm/ssm.ts:17](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/ssm/ssm.ts#L17)
+
+Wrapper around the AWS SSM Parameter Store client providing structured
+Powertools logging and X-Ray tracing by default. All operations enable
+`WithDecryption` — callers needing plaintext should use `SSMClient`
+directly.
+
+## Constructors
+
+<a id="constructor"></a>
+
+### Constructor
+
+> **new SSMService**(`opts?`): `SSMService`
+
+Defined in: [ssm/ssm.ts:27](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/ssm/ssm.ts#L27)
+
+#### Parameters
+
+##### opts?
+
+###### client?
+
+`SSMClient`
+
+Optional pre-configured `SSMClient`. When supplied,
+the wrapper does not apply X-Ray instrumentation.
+
+###### logger?
+
+`Logger`
+
+Optional Powertools logger. Defaults to a logger with
+`serviceName: 'SSMService'`.
+
+#### Returns
+
+`SSMService`
+
+## Methods
+
+<a id="getparameter"></a>
+
+### getParameter()
+
+> **getParameter**(`name`): `Promise`\<`string` \| `undefined`\>
+
+Defined in: [ssm/ssm.ts:38](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/ssm/ssm.ts#L38)
+
+Fetch a single SSM parameter's value.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The parameter name (or ARN).
+
+#### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The parameter value, or `undefined` if the parameter has no
+value set.
+
+***
+
+<a id="getparameters"></a>
+
+### getParameters()
+
+> **getParameters**\<`K`\>(`aliases`): `Promise`\<`Record`\<`K`, `string` \| `undefined`\>\>
+
+Defined in: [ssm/ssm.ts:65](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/ssm/ssm.ts#L65)
+
+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',
+});
+```
+
+#### Type Parameters
+
+##### K
+
+`K` *extends* `string`
+
+#### Parameters
+
+##### aliases
+
+`Record`\<`K`, `string`\>
+
+Record mapping each desired local alias to its SSM
+parameter name (or ARN).
+
+#### Returns
+
+`Promise`\<`Record`\<`K`, `string` \| `undefined`\>\>
+
+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.
+
+***
+
+<a id="getparametersbypath"></a>
+
+### getParametersByPath()
+
+> **getParametersByPath**(`path`, `opts?`): `Promise`\<`Parameter`[]\>
+
+Defined in: [ssm/ssm.ts:97](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/ssm/ssm.ts#L97)
+
+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.
+
+#### Parameters
+
+##### path
+
+`string`
+
+The parameter path prefix (e.g. `/myapp/`).
+
+##### opts?
+
+###### recursive?
+
+`boolean`
+
+Whether to recurse into nested paths. Defaults
+to `true`.
+
+#### Returns
+
+`Promise`\<`Parameter`[]\>
+
+The full `Parameter` objects (including `Version`,
+`LastModifiedDate`, etc.).

package/docs/classes/SecretsManagerService.md

@@ -0,0 +1,114 @@
+[**@aligent/aws-wrappers**](../modules.md)
+
+***
+
+[@aligent/aws-wrappers](../modules.md) / SecretsManagerService
+
+# Class: SecretsManagerService
+
+Defined in: [secrets-manager/secrets-manager.ts:9](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/secrets-manager/secrets-manager.ts#L9)
+
+Wrapper around the AWS Secrets Manager client providing structured
+Powertools logging and X-Ray tracing by default.
+
+## Constructors
+
+<a id="constructor"></a>
+
+### Constructor
+
+> **new SecretsManagerService**(`opts?`): `SecretsManagerService`
+
+Defined in: [secrets-manager/secrets-manager.ts:20](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/secrets-manager/secrets-manager.ts#L20)
+
+#### Parameters
+
+##### opts?
+
+###### client?
+
+`SecretsManagerClient`
+
+Optional pre-configured `SecretsManagerClient`. When
+supplied, the wrapper does not apply X-Ray instrumentation — the caller
+owns that decision.
+
+###### logger?
+
+`Logger`
+
+Optional Powertools logger. Defaults to a logger with
+`serviceName: 'SecretsManagerService'`.
+
+#### Returns
+
+`SecretsManagerService`
+
+## Methods
+
+<a id="getjsonsecret"></a>
+
+### getJsonSecret()
+
+> **getJsonSecret**\<`T`\>(`secretId`): `Promise`\<`T`\>
+
+Defined in: [secrets-manager/secrets-manager.ts:44](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/secrets-manager/secrets-manager.ts#L44)
+
+Fetch a secret and parse it as JSON.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+Expected shape of the parsed secret.
+
+#### Parameters
+
+##### secretId
+
+`string`
+
+The ARN or friendly name of the secret.
+
+#### Returns
+
+`Promise`\<`T`\>
+
+The parsed secret value.
+
+#### Throws
+
+If the secret has no `SecretString` or the value is not valid JSON.
+
+***
+
+<a id="getsecret"></a>
+
+### getSecret()
+
+> **getSecret**(`secretId`): `Promise`\<`string`\>
+
+Defined in: [secrets-manager/secrets-manager.ts:32](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/secrets-manager/secrets-manager.ts#L32)
+
+Fetch a secret's string value from Secrets Manager.
+
+#### Parameters
+
+##### secretId
+
+`string`
+
+The ARN or friendly name of the secret.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The secret's `SecretString` value.
+
+#### Throws
+
+If the response does not contain a `SecretString` (e.g. the secret
+stores binary data).

package/docs/classes/StepFunctionsService.md

@@ -0,0 +1,134 @@
+[**@aligent/aws-wrappers**](../modules.md)
+
+***
+
+[@aligent/aws-wrappers](../modules.md) / StepFunctionsService
+
+# Class: StepFunctionsService
+
+Defined in: [sfn/sfn.ts:23](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L23)
+
+Wrapper around the AWS Step Functions client providing structured
+Powertools logging and X-Ray tracing by default.
+
+## Constructors
+
+<a id="constructor"></a>
+
+### Constructor
+
+> **new StepFunctionsService**(`opts?`): `StepFunctionsService`
+
+Defined in: [sfn/sfn.ts:33](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L33)
+
+#### Parameters
+
+##### opts?
+
+###### client?
+
+`SFNClient`
+
+Optional pre-configured `SFNClient`. When supplied,
+the wrapper does not apply X-Ray instrumentation.
+
+###### logger?
+
+`Logger`
+
+Optional Powertools logger. Defaults to a logger with
+`serviceName: 'StepFunctionsService'`.
+
+#### Returns
+
+`StepFunctionsService`
+
+## Methods
+
+<a id="describeexecution"></a>
+
+### describeExecution()
+
+> **describeExecution**(`input`): `Promise`\<`DescribeExecutionCommandOutput`\>
+
+Defined in: [sfn/sfn.ts:64](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L64)
+
+Describe an existing Step Functions execution.
+
+#### Parameters
+
+##### input
+
+`DescribeExecutionCommandInput`
+
+#### Returns
+
+`Promise`\<`DescribeExecutionCommandOutput`\>
+
+***
+
+<a id="listexecutions"></a>
+
+### listExecutions()
+
+> **listExecutions**(`input`): `Promise`\<`ExecutionListItem`[]\>
+
+Defined in: [sfn/sfn.ts:43](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L43)
+
+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.
+
+#### Parameters
+
+##### input
+
+`ListExecutionsCommandInput`
+
+#### Returns
+
+`Promise`\<`ExecutionListItem`[]\>
+
+***
+
+<a id="startexecution"></a>
+
+### startExecution()
+
+> **startExecution**(`input`): `Promise`\<`StartExecutionCommandOutput`\>
+
+Defined in: [sfn/sfn.ts:56](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L56)
+
+Start a new Step Functions execution.
+
+#### Parameters
+
+##### input
+
+`StartExecutionCommandInput`
+
+#### Returns
+
+`Promise`\<`StartExecutionCommandOutput`\>
+
+***
+
+<a id="stopexecution"></a>
+
+### stopExecution()
+
+> **stopExecution**(`input`): `Promise`\<`StopExecutionCommandOutput`\>
+
+Defined in: [sfn/sfn.ts:74](https://github.com/aligent/microservice-development-utilities/blob/30b581ee09ba114f98caadf97f423e40b9b4f410/packages/aws-wrappers/src/sfn/sfn.ts#L74)
+
+Stop an in-progress Step Functions execution.
+
+#### Parameters
+
+##### input
+
+`StopExecutionCommandInput`
+
+#### Returns
+
+`Promise`\<`StopExecutionCommandOutput`\>

package/docs/modules.md

@@ -0,0 +1,15 @@
+**@aligent/aws-wrappers**
+
+***
+
+# @aligent/aws-wrappers
+
+## Classes
+
+- [DynamoDBService](classes/DynamoDBService.md)
+- [S3Service](classes/S3Service.md)
+- [SecretsManagerService](classes/SecretsManagerService.md)
+- [SNSService](classes/SNSService.md)
+- [SQSService](classes/SQSService.md)
+- [SSMService](classes/SSMService.md)
+- [StepFunctionsService](classes/StepFunctionsService.md)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@aligent/aws-wrappers",
+  "version": "0.0.1",
+  "description": "Opinionated AWS SDK wrappers with Powertools logging and X-Ray tracing",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "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"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/dynamodb/dynamodb.d.ts

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