@aligent/aws-wrappers 0.0.1

package/CLAUDE.md

@@ -0,0 +1,172 @@
+# 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?: Logger; client?: <ServiceClient> })
+```
+
+- `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/README.md

@@ -0,0 +1,286 @@
+# @aligent/aws-wrappers
+
+Opinionated AWS SDK wrappers with Powertools logging and X-Ray tracing baked in. Each `*Service` class instantiates and instruments its underlying SDK client by default and emits a structured `logger.info` line on every operation, so consumers get a consistent, observable starting point without rewriting the same boilerplate per service.
+
+## Installation
+
+```sh
+npm install @aligent/aws-wrappers
+```
+
+## Conventions
+
+Every wrapper takes the same optional constructor options:
+
+```ts
+new XService({ logger?, client? })
+```
+
+- `logger` — a Powertools `Logger`. Defaults to `new Logger()`, which picks up `POWERTOOLS_SERVICE_NAME` from the environment (recommended) and otherwise falls back to Powertools' own default.
+- `client` — a pre-configured SDK client. When omitted, the wrapper instantiates the SDK client itself and wraps it with `captureAWSv3Client` for X-Ray tracing. When supplied, the wrapper passes it through unchanged — the caller is responsible for X-Ray instrumentation.
+
+### Log redaction
+
+Every wrapper emits one `logger.info` line per SDK call with a per-method safe-field allowlist (omitting payloads, secret material, and PII recipient identifiers). Set `POWERTOOLS_LOG_LEVEL=DEBUG` to unlock the full SDK input in those log lines — useful for local development and incident triage. See `packages/aws-wrappers/CLAUDE.md` for the per-method allowlists currently in force.
+
+### X-Ray outside Lambda
+
+X-Ray's middleware throws by default when no active segment exists, which is the case for CLI scripts and local development. Set the environment variable to silence the noise:
+
+```sh
+AWS_XRAY_CONTEXT_MISSING=IGNORE_ERROR
+```
+
+## S3
+
+```ts
+import { S3Service } from '@aligent/aws-wrappers';
+
+const s3 = new S3Service();
+
+await s3.putObject({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'hello' });
+
+await s3.putJsonObject({ Bucket: 'my-bucket', Key: 'data.json', Body: { foo: 'bar' } });
+const data = await s3.getJsonObject<MyType>({ Bucket: 'my-bucket', Key: 'data.json' });
+
+// getObject returns the raw GetObjectCommandOutput when you need metadata
+// (LastModified, ContentLength, …) alongside the body.
+const raw = await s3.getObject({ Bucket: 'my-bucket', Key: 'file.txt' });
+const body = await s3.getObjectBody({ Bucket: 'my-bucket', Key: 'file.txt' });
+
+const { LastModified } = await s3.headObject({ Bucket: 'my-bucket', Key: 'file.txt' });
+
+const keys = await s3.listObjects('my-bucket', 'prefix/');
+const items = await s3.getAllObjects<MyType>('my-bucket', 'prefix/');
+
+await s3.copyObject({ Bucket: 'dest', Key: 'dest-key', CopySource: 'src/src-key' });
+
+// Presigned URLs for direct browser-side download / upload.
+// expiresIn defaults to 3600 seconds.
+const downloadUrl = await s3.getPresignedUrl({
+    Bucket: 'my-bucket',
+    Key: 'file.txt',
+    action: 'get',
+});
+const uploadUrl = await s3.getPresignedUrl({
+    Bucket: 'my-bucket',
+    Key: 'file.txt',
+    action: 'put',
+    expiresIn: 600,
+});
+
+await s3.deleteObject({ Bucket: 'my-bucket', Key: 'file.txt' });
+await s3.deleteObjects('my-bucket', ['key1', 'key2']); // auto-chunked to 1000 keys per request
+await s3.emptyBucket('my-bucket');                     // streams the listing + delegates each page to deleteObjects
+```
+
+Input shapes are intentionally tight (`Bucket`, `Key`, `Body` and similar). Callers needing SDK-specific options like server-side encryption or tagging should use `S3Client` directly.
+
+## DynamoDB
+
+```ts
+import { DynamoDBService } from '@aligent/aws-wrappers';
+
+const ddb = new DynamoDBService();
+
+// Backed by DynamoDBDocumentClient — items are plain TS objects in both directions.
+await ddb.putItem({ TableName: 'my-table', Item: { pk: 'abc', value: 42 } });
+
+// Key-bearing methods take two generics: <K, R> for the key shape and the
+// return / Attributes shape. Both default to Record<string, unknown> so callers
+// can omit one or both when they don't care.
+type MyKey = { pk: string };
+type MyItem = { pk: string; value: number };
+
+const item = await ddb.getItem<MyKey, MyItem>({
+    TableName: 'my-table',
+    Key: { pk: 'abc' },
+});
+
+const { Items } = await ddb.query<MyItem>({
+    TableName: 'my-table',
+    KeyConditionExpression: 'pk = :pk',
+    ExpressionAttributeValues: { ':pk': 'abc' },
+});
+
+// scan returns the same shape as query — full output with Items typed as T[].
+const { Items: all } = await ddb.scan<{ pk: string }>({ TableName: 'my-table' });
+
+// updateItem / deleteItem mirror getItem's <K, R> generics.
+const { Attributes } = await ddb.updateItem<MyKey, { value: number }>({
+    TableName: 'my-table',
+    Key: { pk: 'abc' },
+    UpdateExpression: 'SET #v = :v',
+    ExpressionAttributeNames: { '#v': 'value' },
+    ExpressionAttributeValues: { ':v': 99 },
+    ReturnValues: 'ALL_NEW',
+});
+
+await ddb.deleteItem({ TableName: 'my-table', Key: { pk: 'abc' } });
+
+// batchWrite retries UnprocessedItems with jittered exponential backoff
+// (5 attempts, 200ms base) and throws if any remain after the final attempt.
+await ddb.batchWrite({
+    RequestItems: {
+        'my-table': [{ PutRequest: { Item: { pk: 'abc' } } }],
+    },
+});
+
+// paginateItems / paginateScan yield each item — use for potentially unbounded result sets.
+for await (const item of ddb.paginateItems<{ pk: string }>({
+    TableName: 'my-table',
+    KeyConditionExpression: 'pk = :pk',
+    ExpressionAttributeValues: { ':pk': 'abc' },
+})) {
+    console.log(item.pk);
+}
+
+for await (const item of ddb.paginateScan<{ pk: string }>({ TableName: 'my-table' })) {
+    console.log(item.pk);
+}
+```
+
+`batchGet` is **not** generic — its `Responses` field is a multi-table record whose item shapes can differ per table, so no single generic can soundly describe it. Callers should narrow the result type at the call site.
+
+## Secrets Manager
+
+```ts
+import { SecretsManagerService } from '@aligent/aws-wrappers';
+
+const secrets = new SecretsManagerService();
+
+const raw = await secrets.getSecret('my-secret-name');
+const config = await secrets.getJsonSecret<MySecretShape>('my-secret-name');
+```
+
+`getSecret` throws when the response has no `SecretString` (e.g. a binary-only secret). `getJsonSecret` additionally throws if the secret value is not valid JSON. `VersionId` / `VersionStage` aren't exposed — use `SecretsManagerClient` directly if you need version pinning.
+
+```ts
+// Write operations. Prefer IaC (CDK / Terraform) for secret lifecycle;
+// reserve these for rotation flows or dynamically-issued credentials.
+await secrets.createSecret({ Name: 'my-secret', SecretString: 'shh' });
+await secrets.updateSecret({ SecretId: 'my-secret', Description: 'updated' });
+await secrets.putSecretValue({ SecretId: 'my-secret', SecretString: 'new-shh' });
+await secrets.deleteSecret({ SecretId: 'my-secret', RecoveryWindowInDays: 7 });
+```
+
+## Step Functions
+
+```ts
+import { StepFunctionsService } from '@aligent/aws-wrappers';
+
+const sfn = new StepFunctionsService();
+
+// Auto-paginated — returns every execution across all pages.
+const executions = await sfn.listExecutions({
+    stateMachineArn: 'arn:aws:states:us-east-1:0:stateMachine:my-sfn',
+    statusFilter: 'RUNNING',
+});
+
+const { executionArn } = await sfn.startExecution({
+    stateMachineArn: 'arn:aws:states:us-east-1:0:stateMachine:my-sfn',
+    input: JSON.stringify({ foo: 'bar' }),
+});
+
+const description = await sfn.describeExecution({ executionArn });
+
+await sfn.stopExecution({ executionArn });
+```
+
+## SSM Parameter Store
+
+```ts
+import { SSMService } from '@aligent/aws-wrappers';
+
+const ssm = new SSMService();
+
+const apiKey = await ssm.getParameter('/myapp/api-key');
+
+// Supply an alias-to-path map — the result is keyed by the aliases so the
+// SSM path is only mentioned at the call site.
+const { host, port } = await ssm.getParameters({
+    host: '/myapp/host',
+    port: '/myapp/port',
+});
+
+// Auto-paginated, returns full Parameter[] (includes Version, LastModifiedDate).
+// Recursive defaults to true.
+const params = await ssm.getParametersByPath('/myapp/');
+const shallow = await ssm.getParametersByPath('/myapp/', { recursive: false });
+```
+
+All read operations enable `WithDecryption` automatically — there's no opt-out. Callers needing plaintext should use `SSMClient` directly.
+
+```ts
+// Write operations. Prefer IaC (CDK / Terraform) for parameter lifecycle;
+// reserve these for values that genuinely mutate at runtime.
+await ssm.putParameter({
+    Name: '/myapp/feature-flag',
+    Value: 'enabled',
+    Type: 'String',
+    Overwrite: true,
+});
+
+await ssm.deleteParameter('/myapp/feature-flag');
+```
+
+## SQS
+
+```ts
+import { SQSService } from '@aligent/aws-wrappers';
+
+const sqs = new SQSService();
+
+await sqs.sendMessage({ QueueUrl, MessageBody: 'hello' });
+
+// Returns Message[] — empty array when nothing's available.
+const messages = await sqs.receiveMessages({ QueueUrl, WaitTimeSeconds: 20 });
+
+for (const message of messages) {
+    if (message.ReceiptHandle) {
+        await sqs.deleteMessage({ QueueUrl, ReceiptHandle: message.ReceiptHandle });
+    }
+}
+
+// Batch methods auto-chunk Entries to the SQS-enforced 10-entry limit.
+await sqs.sendMessageBatch({ QueueUrl, Entries: bigEntryList });
+await sqs.deleteMessageBatch({ QueueUrl, Entries: receiptEntries });
+```
+
+`receiveMessages` does **not** auto-delete — visibility-timeout semantics are the caller's responsibility.
+
+```ts
+// Opt-in truncation for oversized payloads. Defaults to off (SDK throws on
+// oversize). Useful for fire-and-forget flows where dropped detail beats a
+// thrown error.
+const sqs = new SQSService({ truncate: true });            // per-instance default
+await sqs.sendMessage({ QueueUrl, MessageBody: huge });
+await sqs.sendMessage({ QueueUrl, MessageBody: huge }, { truncate: false }); // per-call override
+```
+
+## SNS
+
+```ts
+import { SNSService } from '@aligent/aws-wrappers';
+
+const sns = new SNSService();
+
+await sns.publish({ TopicArn, Message: 'hello' });
+
+// publishBatch auto-chunks PublishBatchRequestEntries to the SNS-enforced 10-entry limit.
+await sns.publishBatch({ TopicArn, PublishBatchRequestEntries: bigEntryList });
+
+// Opt-in truncation — same shape as SQS. Truncates Message (256 KB byte-safe)
+// and Subject (100 chars codepoint-safe) when enabled.
+const truncSns = new SNSService({ truncate: true });
+await truncSns.publish({ TopicArn, Message: huge, Subject: long });
+await truncSns.publish({ TopicArn, Message: huge }, { truncate: false });
+```
+
+## Build / test
+
+```sh
+npm run build       # affected only
+npm run test
+npm run lint
+```