@aligent/aws-wrappers 0.1.0 → 0.1.2

package/package.json

@@ -1,32 +1,50 @@
 {
   "name": "@aligent/aws-wrappers",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Opinionated AWS SDK wrappers with Powertools logging and X-Ray tracing",
-  "type": "commonjs",
-  "main": "./src/index.js",
-  "typings": "./src/index.d.ts",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "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-lambda-powertools/logger": "^2.33.1",
+    "@aws-sdk/client-dynamodb": "^3.1068.0",
+    "@aws-sdk/client-s3": "^3.1068.0",
+    "@aws-sdk/client-secrets-manager": "^3.1068.0",
+    "@aws-sdk/client-sfn": "^3.1068.0",
+    "@aws-sdk/client-sns": "^3.1068.0",
+    "@aws-sdk/client-sqs": "^3.1068.0",
+    "@aws-sdk/client-ssm": "^3.1068.0",
+    "@aws-sdk/lib-dynamodb": "^3.1068.0",
+    "@aws-sdk/s3-request-presigner": "^3.1068.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/CLAUDE.md

@@ -1,173 +0,0 @@
-# CLAUDE.md — @aligent/aws-wrappers
-
-Guidance for Claude Code when working in this package. Read alongside the repo-root `CLAUDE.md`.
-
-## Purpose
-
-Each `*Service` class wraps a single AWS SDK client. The wrapper bundles:
-
-- a Powertools `Logger` (one `logger.info` line at the start of every public method),
-- X-Ray tracing via `captureAWSv3Client`,
-- ergonomic helpers that smooth over recurring SDK quirks (auto-pagination, auto-chunking, JSON helpers, retry-on-`UnprocessedItems`, etc.).
-
-Callers who need raw SDK access drop down to the SDK client directly — the wrappers do not try to be a full SDK replacement.
-
-## Layout
-
-```
-packages/aws-wrappers/src/
-├── <service>/
-│   ├── <service>.ts        # the *Service class
-│   └── <service>.test.ts   # co-located tests
-└── index.ts                # named exports of every *Service class
-```
-
-One folder per service, lowercase. No barrel files inside service folders — `index.ts` imports the class directly from `<service>/<service>`.
-
-## Locked-in conventions
-
-These are non-negotiable across every service in the package — change them only with explicit user sign-off.
-
-### Constructor
-
-```ts
-constructor(opts?: { logger?: LoggerInterface; client?: <ServiceClient> })
-```
-
-- `logger` is typed as `LoggerInterface` (from `@aws-lambda-powertools/logger/types`), **not** the concrete `Logger` class. This avoids the dual-package hazard for ESM consumers — TS treats the ESM and CJS builds of the `Logger` class as nominally distinct (each has its own `#private` field), but `LoggerInterface` is a structural type alias so both builds are mutually assignable. The wrapper still defaults to `new Logger()` internally; only the public type widens.
-- `logger` defaults to `new Logger()`, which picks up `POWERTOOLS_SERVICE_NAME` from the environment. Do **not** pass `serviceName` in the default — env-driven service naming is the Powertools convention.
-- `client` defaults to `captureAWSv3Client(new <ServiceClient>())`. When the caller supplies a client, the wrapper does **not** apply X-Ray instrumentation — that's the caller's call.
-- No `clientConfig` / `region` / `endpoint` options. Callers needing those construct their own client and pass it via `client`.
-
-### Logging
-
-Every public method emits exactly one `logger.info('<verb> <noun>', { input })` line at the start. The shape of `input` is **level-driven**:
-
-- At `DEBUG` (e.g. `POWERTOOLS_LOG_LEVEL=DEBUG`), the full SDK input is logged. Operators have explicitly opted into seeing payloads, secret material, and PII.
-- At any other level, only a per-method **safe-fields allowlist** is logged.
-
-The mechanism is `filterFieldsForLogLevel(logger, input, SAFE_FIELDS)` in `src/util/redact.ts`. Internal-only helper, not exported from `src/index.ts`.
-
-#### Conventions for the allowlist
-
-- **Module-level constant per method**, typed as `ReadonlyArray<keyof CommandInput>`, named `<METHOD>_SAFE_FIELDS`. TSDoc explains what's omitted and why.
-- **Targeted application** — only methods where there's an actual omission use the helper. Methods whose input is already a tight `Required<Pick<...>>` or contains no sensitive fields (e.g. `S3.getObject`, `SFN.listExecutions`) keep their current `{ input }` shape.
-- **Maximal safe set** — include every field *except* known payload, secret, or PII carriers. The level-based design provides the safety valve; the INFO log should still be operationally useful.
-- **Batch methods stay bespoke** — methods that already compute a derived field (e.g. `entryCount`, `keyCount`, `tables`) inline the DEBUG check directly rather than using `filterFieldsForLogLevel`, since the helper only picks input keys and can't synthesise computed fields. A comment explains why.
-
-#### Currently redacted
-
-- **S3** — `putObject` / `putJsonObject` omit `Body`. Batch methods (`deleteObjects`, `emptyBucket`) log `{ bucket, keyCount }`.
-- **SNS** — `publish` omits `Message`, `Subject`, `MessageAttributes`, `PhoneNumber`. `publishBatch` logs `{ TopicArn, entryCount }`.
-- **SQS** — `sendMessage` omits `MessageBody`, `MessageAttributes`. Batch methods log `{ QueueUrl, entryCount }`.
-- **DynamoDB** — `getItem` / `deleteItem` omit `Key`. `putItem` omits `Item`. `updateItem` omits `Key` and `ExpressionAttributeValues`. `query` / `scan` / `paginateItems` / `paginateScan` omit `ExpressionAttributeValues`. `batchGet` / `batchWrite` log `{ tables: Object.keys(RequestItems) }` only.
-- **SecretsManager** — write methods omit `SecretString` / `SecretBinary`.
-- **SSM** — `putParameter` omits `Value`.
-- **SFN** — `startExecution` omits the execution `input` (often carries PII).
-
-Adding a new redacted method: define a `<METHOD>_SAFE_FIELDS` constant near the top of the service file with TSDoc, wire `filterFieldsForLogLevel(this.logger, input, FIELDS)` into the `logger.info` call, and add a single `expect(loggedInput).not.toHaveProperty('<sensitive>')` test against an INFO-level logger to lock in the security property.
-
-### Patterns
-
-- **Auto-pagination, flat array**: `S3.listObjects` / `getAllObjects` / `emptyBucket`, `SSM.getParametersByPath`, `SFN.listExecutions`. Used when the result set is bounded in practice.
-- **Generator pagination, yield items**: `DynamoDB.paginateItems` / `paginateScan`. Used when the result set is potentially unbounded — peak memory stays bounded by one page.
-- **Auto-chunking**: `S3.deleteObjects` / `emptyBucket` (1000), `SQS.sendMessageBatch` / `deleteMessageBatch` (10), `SNS.publishBatch` (10). Mirrors the SDK-enforced per-request cap so callers don't have to.
-
-### Opt-in payload truncation
-
-`SNS.publish` and `SQS.sendMessage` expose an opt-in truncation knob for callers who prefer data loss over SDK-level failure on oversize (e.g. notification flows where dropped detail beats a thrown error). The default is **off** — fail-fast at the SDK is the right behaviour for most code paths.
-
-- Constructor option `truncate?: boolean` sets the per-instance default.
-- Per-call option `{ truncate?: boolean }` overrides the instance default.
-- When enabled, the wrapper uses `truncateUtf8` for byte-bounded fields (256 KB for `Message` / `MessageBody`) and `truncateCodepoints` for char-bounded fields (100 chars for SNS `Subject`). Both helpers live in `src/util/truncate.ts` and respect codepoint boundaries (no half-emoji, no malformed UTF-8).
-- Each truncating call emits a single `logger.warn('Truncated <service> <op> input', { fields: [...] })` line listing what was modified.
-
-If you find yourself adding truncation to a third method, raise it with the user first — opt-out flags are the more conservative default.
-
-### DynamoDB specifics
-
-- Backed by `DynamoDBDocumentClient`. Always wrap the base `DynamoDBClient` with `captureAWSv3Client` **before** passing it to `DynamoDBDocumentClient.from(...)`, so X-Ray captures every command.
-- `marshallOptions: { removeUndefinedValues: true }`.
-- All commands and paginators come from `@aws-sdk/lib-dynamodb`. Never import marshaling helpers from `@aws-sdk/util-dynamodb` — that's what the doc client is for.
-- Generic typing convention:
-  - Methods that return a single item or yield items (`paginateItems`, `paginateScan`): `AsyncGenerator<T>`.
-  - Methods that return the full command output (`query`, `scan`): preserve the output and generically type only the data-bearing field (`Items?: T[]`).
-  - Key-bearing methods (`getItem`, `updateItem`, `deleteItem`) take two generics — `K extends Record<string, unknown>` for the partition / sort key shape, `R extends Record<string, unknown>` for the return type. The input is threaded through `WithTypedKey<TInput, K>` so the SDK input is preserved with the typed `Key` substituted.
-  - `batchGet` is intentionally **not** generic — multi-table `Responses` can't be soundly described by a single `T`. Document this in TSDoc whenever the method is touched.
-  - All generics default to `Record<string, unknown>` so callers can omit them.
-
-## Adding a new service
-
-Walk through these in order. Each step is small; nothing is automatable enough to be worth a generator.
-
-1. **Confirm scope with the user.** Run the questions in the next section before writing code. Don't infer the answers from the SDK.
-2. **Install the SDK client** as a runtime dependency of the package:
-   ```sh
-   npm install --workspace=@aligent/aws-wrappers @aws-sdk/client-<service>
-   ```
-   Never hand-edit `package.json`. ESLint's `@nx/dependency-checks` rule will flag unused deps via `--fix` if you install too early — install per-service as you implement.
-3. **Create the folder**: `packages/aws-wrappers/src/<service>/`, with `<service>.ts` and `<service>.test.ts`.
-4. **Implement the class** following the locked-in conventions above. Mirror the structure of an existing service of similar shape — `SecretsManagerService` is the simplest skeleton; `DynamoDBService` is the most complex.
-5. **Add tests with `aws-sdk-client-mock`**. Default-construction test (`expect(() => new XService()).not.toThrow()`) plus targeted coverage on non-trivial methods. For any method that uses an SDK paginator (`paginate*`), pass a real client instance via the constructor — see "Testing notes" below.
-6. **Add a named export to `src/index.ts`** in alphabetical order.
-7. **Run** `npx nx run aws-wrappers:lint --fix`, `:typecheck`, `:test --coverage`, `:typedoc`. The 80% workspace coverage threshold is enforced.
-8. **Update the package `README.md`** with a worked example under a new `## <Service Name>` section.
-9. **Commit** with the active ticket prefix.
-10. **Ask the user whether to run the `code-reviewer` sub-agent** over the change before opening the PR. The reviewer catches drift from the locked-in conventions (logging shape, generics, pagination/chunking patterns) and the kinds of defensive-coverage gaps the workspace gate doesn't enforce. Surface its punch list to the user — don't auto-apply fixes.
-
-## Questions to ask the user
-
-### When adding a new service
-
-Don't write code until each of these is answered. Defaults in **bold**.
-
-- **Method coverage**: which SDK operations should the wrapper expose? Default: only the ones with concrete near-term callers — every method is API surface area to maintain.
-- **Pagination**: for each `List*` / `Get*ByPath` / etc. operation:
-  - Auto-paginate and return a flat array? (**default** when result set is bounded by filters / retention)
-  - Expose as an `AsyncGenerator` that yields items? (**default** when result set is potentially unbounded)
-  - Pass-through, leave pagination to caller? (only when the caller usually wants pagination metadata)
-- **Chunking**: any operation with a per-request entry/key cap (e.g. SNS `PublishBatch` at 10) — auto-chunk to the cap (**default**) or pass-through?
-- **Generic typing**:
-  - For methods that return a single data-bearing item — return generic `T | undefined` (**default**).
-  - For methods that return command output with metadata — preserve the output, generic on the data-bearing field (`Items?: T[]`, `Attributes?: T`).
-  - For multi-shape responses (cf. DynamoDB `batchGet`) — **not generic**, document why in TSDoc.
-  - Default the generic to `T extends Record<string, unknown> = Record<string, unknown>` so callers can omit it.
-- **Logging shape**: does the input contain anything sensitive (credentials, large payloads, message bodies)? If yes, follow the documented exception pattern (`{ Bucket, Key }`, `{ entryCount, ... }`). Default to `{ input }`.
-- **Error semantics**: any operations where the wrapper should retry, swallow, or surface differently than the SDK? Capture the rationale in TSDoc. Examples already in this package: `batchWrite` (retry `UnprocessedItems`), `getSecret` (throw on missing `SecretString`).
-- **Input shape**: pass-through SDK input (**default**) or a tight `Required<Pick<...>>` projection (the S3 pattern)? Tight shape is appropriate when the SDK has many rarely-used optional fields and exposing them noises up TS errors.
-- **Defaults bakedin**: e.g. `SSM` bakes in `WithDecryption: true` with no opt-out. Capture every such "no opt-out" decision in the class-level TSDoc.
-
-### When changing an existing service
-
-- Is this change additive (new method) or modifying an existing public method?
-- If modifying: is the package already published? If yes, this is a SemVer-major change — flag it before implementing.
-- Does it touch any of the locked-in conventions above? If yes, surface to the user first.
-- Will any of the existing tests need to change? If yes, that's a load-bearing signal — verify whether the existing test behaviour was load-bearing for a downstream caller.
-
-Once the change is in and tests pass, ask the user whether to run the `code-reviewer` sub-agent over the diff before opening the PR — same rationale as step 10 of the new-service flow.
-
-## Testing notes
-
-- `aws-sdk-client-mock` patches the prototype `send` method of all instances of the SDK client class. The mock object itself is **not** a usable client — for paginators it fails `instanceof` checks. **For any method that uses an SDK paginator, pass a real client instance via the constructor:**
-
-  ```ts
-  const mock = mockClient(SSMClient);          // global intercept
-  const service = new SSMService({ client: new SSMClient({}) });  // real instance
-  ```
-
-  The mock still intercepts every `.send` call. The bare cast `mock as unknown as SSMClient` works for non-paginator methods but is brittle — prefer the real-instance pattern uniformly.
-
-- Error assertions: `await expect(fn()).rejects.toThrow(...)`. Do **not** use the `try / catch + // eslint-disable-next-line no-empty` pattern that exists in older `microservice-util-lib` tests.
-
-- Coverage gate is 80% workspace-global on lines / branches / functions / statements. For thin pass-through methods, a one-shot "verify the SDK command was sent" test is enough — these are visually verifiable but still need to keep the gate green.
-
-## Out of scope
-
-These came up during the initial design and were explicitly deferred:
-
-- Moving the existing AWS utilities (`S3Dao`, `fetchSsmParams`, `get-aws-id-from-arn`) out of `microservice-util-lib` into this package.
-- Deprecating those existing utilities or adding `@deprecated` tags.
-- Migration guide from the legacy utilities to the new wrappers.
-- Integration tests against LocalStack or real AWS.
-- CDK constructs in `nx-cdk` corresponding to these wrappers.
-- Wrappers for additional AWS services (EventBridge, Kinesis, etc.) — add them as separate tickets following the "Adding a new service" flow.

package/src/dynamodb/dynamodb.js

@@ -1,308 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDBService = void 0;
-const logger_1 = require("@aws-lambda-powertools/logger");
-const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
-const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
-const redact_1 = require("../util/redact");
-const BATCH_WRITE_MAX_ATTEMPTS = 5;
-const BATCH_WRITE_BASE_DELAY_MS = 200;
-/**
- * Fields safe to log at INFO. Omits `Key` (may carry customer IDs / tenant IDs).
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const GET_ITEM_SAFE_FIELDS = [
-    'TableName',
-    'ConsistentRead',
-    'ProjectionExpression',
-    'ReturnConsumedCapacity',
-    'ExpressionAttributeNames',
-];
-/**
- * Fields safe to log at INFO. Omits `Item` (the payload itself) and
- * `ExpressionAttributeValues` (values bound to ConditionExpression, often PII).
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const PUT_ITEM_SAFE_FIELDS = [
-    'TableName',
-    'ConditionExpression',
-    'ExpressionAttributeNames',
-    'ReturnValues',
-    'ReturnConsumedCapacity',
-    'ReturnItemCollectionMetrics',
-    'ReturnValuesOnConditionCheckFailure',
-];
-/**
- * Fields safe to log at INFO. Omits `Key` and `ExpressionAttributeValues`.
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const UPDATE_ITEM_SAFE_FIELDS = [
-    'TableName',
-    'UpdateExpression',
-    'ConditionExpression',
-    'ExpressionAttributeNames',
-    'ReturnValues',
-    'ReturnConsumedCapacity',
-    'ReturnItemCollectionMetrics',
-    'ReturnValuesOnConditionCheckFailure',
-];
-/**
- * Fields safe to log at INFO. Omits `Key` and `ExpressionAttributeValues`
- * (the latter binds to ConditionExpression and may carry PII).
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const DELETE_ITEM_SAFE_FIELDS = [
-    'TableName',
-    'ConditionExpression',
-    'ExpressionAttributeNames',
-    'ReturnValues',
-    'ReturnConsumedCapacity',
-    'ReturnItemCollectionMetrics',
-    'ReturnValuesOnConditionCheckFailure',
-];
-/**
- * Fields safe to log at INFO for `query` and `paginateItems`. Omits
- * `ExpressionAttributeValues` (values often carry PII) and `ExclusiveStartKey`
- * (pagination cursor includes Key shape). `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks
- * the full input.
- */
-const QUERY_SAFE_FIELDS = [
-    'TableName',
-    'IndexName',
-    'KeyConditionExpression',
-    'FilterExpression',
-    'ProjectionExpression',
-    'ExpressionAttributeNames',
-    'ConsistentRead',
-    'ScanIndexForward',
-    'Select',
-    'Limit',
-    'ReturnConsumedCapacity',
-];
-/**
- * Fields safe to log at INFO for `scan` and `paginateScan`. Omits
- * `ExpressionAttributeValues` and `ExclusiveStartKey`.
- * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
- */
-const SCAN_SAFE_FIELDS = [
-    'TableName',
-    'IndexName',
-    'FilterExpression',
-    'ProjectionExpression',
-    'ExpressionAttributeNames',
-    'ConsistentRead',
-    'Select',
-    'Limit',
-    'Segment',
-    'TotalSegments',
-    'ReturnConsumedCapacity',
-];
-const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-const backoffDelay = (attempt) => {
-    const exp = BATCH_WRITE_BASE_DELAY_MS * 2 ** attempt;
-    return exp + Math.random() * exp;
-};
-/**
- * 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.
- */
-class DynamoDBService {
-    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 `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) {
-        this.client =
-            opts?.client ??
-                lib_dynamodb_1.DynamoDBDocumentClient.from((0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_dynamodb_1.DynamoDBClient({})), {
-                    marshallOptions: { removeUndefinedValues: true },
-                });
-        this.logger = opts?.logger ?? new logger_1.Logger();
-    }
-    /**
-     * 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.
-     */
-    async getItem(input) {
-        this.logger.info('Getting DynamoDB item', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, GET_ITEM_SAFE_FIELDS),
-        });
-        const response = await this.client.send(new lib_dynamodb_1.GetCommand(input));
-        return response.Item;
-    }
-    /**
-     * 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.
-     */
-    async putItem(input) {
-        this.logger.info('Putting DynamoDB item', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_ITEM_SAFE_FIELDS),
-        });
-        return this.client.send(new lib_dynamodb_1.PutCommand(input));
-    }
-    /**
-     * 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`.
-     */
-    async updateItem(input) {
-        this.logger.info('Updating DynamoDB item', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, UPDATE_ITEM_SAFE_FIELDS),
-        });
-        const response = await this.client.send(new lib_dynamodb_1.UpdateCommand(input));
-        return response;
-    }
-    /**
-     * 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`.
-     */
-    async deleteItem(input) {
-        this.logger.info('Deleting DynamoDB item', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, DELETE_ITEM_SAFE_FIELDS),
-        });
-        const response = await this.client.send(new lib_dynamodb_1.DeleteCommand(input));
-        return response;
-    }
-    /**
-     * 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.
-     */
-    async query(input) {
-        this.logger.info('Querying DynamoDB', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, QUERY_SAFE_FIELDS),
-        });
-        const response = await this.client.send(new lib_dynamodb_1.QueryCommand(input));
-        return response;
-    }
-    /**
-     * 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.
-     */
-    async scan(input) {
-        this.logger.info('Scanning DynamoDB', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, SCAN_SAFE_FIELDS),
-        });
-        const response = await this.client.send(new lib_dynamodb_1.ScanCommand(input));
-        return response;
-    }
-    /**
-     * 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.
-     */
-    async batchGet(input) {
-        // Inline DEBUG check rather than `filterFieldsForLogLevel` because
-        // `RequestItems` is a `Record<tableName, KeysAndAttributes>` — the
-        // payload (`Keys[]`) lives inside the value, not as a top-level key
-        // the helper could pick or drop.
-        const isDebug = this.logger.getLevelName() === 'DEBUG';
-        this.logger.info('Batch getting DynamoDB items', {
-            input: isDebug ? input : { tables: Object.keys(input.RequestItems ?? {}) },
-        });
-        return this.client.send(new lib_dynamodb_1.BatchGetCommand(input));
-    }
-    /**
-     * 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.
-     */
-    async batchWrite(input) {
-        // Inline DEBUG check rather than `filterFieldsForLogLevel` because
-        // `RequestItems` is a `Record<tableName, WriteRequest[]>` — the
-        // payload (`PutRequest.Item` / `DeleteRequest.Key`) lives inside the
-        // value, not as a top-level key the helper could pick or drop.
-        const isDebug = this.logger.getLevelName() === 'DEBUG';
-        this.logger.info('Batch writing DynamoDB items', {
-            input: isDebug ? input : { tables: Object.keys(input.RequestItems ?? {}) },
-        });
-        let current = input;
-        for (let attempt = 0; attempt < BATCH_WRITE_MAX_ATTEMPTS; attempt++) {
-            const response = await this.client.send(new lib_dynamodb_1.BatchWriteCommand(current));
-            const unprocessed = response.UnprocessedItems;
-            if (!unprocessed || Object.keys(unprocessed).length === 0)
-                return response;
-            this.logger.warn('Retrying unprocessed DynamoDB items', {
-                attempt: attempt + 1,
-                tables: Object.keys(unprocessed),
-            });
-            if (attempt < BATCH_WRITE_MAX_ATTEMPTS - 1)
-                await sleep(backoffDelay(attempt));
-            current = { ...input, RequestItems: unprocessed };
-        }
-        throw new Error(`batchWrite failed after ${BATCH_WRITE_MAX_ATTEMPTS} attempts`);
-    }
-    /**
-     * Paginate over Query results, yielding one unmarshalled item at a time.
-     * @template T - Expected shape of each yielded item.
-     */
-    async *paginateItems(input) {
-        this.logger.info('Paginating DynamoDB query', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, QUERY_SAFE_FIELDS),
-        });
-        const paginator = (0, lib_dynamodb_1.paginateQuery)({ client: this.client }, input);
-        for await (const page of paginator) {
-            if (!page.Items)
-                continue;
-            for (const item of page.Items)
-                yield item;
-        }
-    }
-    /**
-     * Paginate over Scan results, yielding one unmarshalled item at a time.
-     * @template T - Expected shape of each yielded item.
-     */
-    async *paginateScan(input) {
-        this.logger.info('Paginating DynamoDB scan', {
-            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, SCAN_SAFE_FIELDS),
-        });
-        const paginator = (0, lib_dynamodb_1.paginateScan)({ client: this.client }, input);
-        for await (const page of paginator) {
-            if (!page.Items)
-                continue;
-            for (const item of page.Items)
-                yield item;
-        }
-    }
-}
-exports.DynamoDBService = DynamoDBService;

package/src/index.d.ts

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

package/src/index.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSMService = exports.SQSService = exports.SNSService = exports.StepFunctionsService = exports.SecretsManagerService = exports.S3Service = exports.DynamoDBService = void 0;
-var dynamodb_1 = require("./dynamodb/dynamodb");
-Object.defineProperty(exports, "DynamoDBService", { enumerable: true, get: function () { return dynamodb_1.DynamoDBService; } });
-var s3_1 = require("./s3/s3");
-Object.defineProperty(exports, "S3Service", { enumerable: true, get: function () { return s3_1.S3Service; } });
-var secrets_manager_1 = require("./secrets-manager/secrets-manager");
-Object.defineProperty(exports, "SecretsManagerService", { enumerable: true, get: function () { return secrets_manager_1.SecretsManagerService; } });
-var sfn_1 = require("./sfn/sfn");
-Object.defineProperty(exports, "StepFunctionsService", { enumerable: true, get: function () { return sfn_1.StepFunctionsService; } });
-var sns_1 = require("./sns/sns");
-Object.defineProperty(exports, "SNSService", { enumerable: true, get: function () { return sns_1.SNSService; } });
-var sqs_1 = require("./sqs/sqs");
-Object.defineProperty(exports, "SQSService", { enumerable: true, get: function () { return sqs_1.SQSService; } });
-var ssm_1 = require("./ssm/ssm");
-Object.defineProperty(exports, "SSMService", { enumerable: true, get: function () { return ssm_1.SSMService; } });