/infra-platform-aws-sdk

name: infra-platform-aws-sdk
description: AWS SDK v3 for TypeScript — modular clients, command pattern, S3, DynamoDB, SQS, Lambda, SNS, Secrets Manager

AWS SDK v3 Patterns

> **Quick Guide:** AWS SDK v3 for JavaScript/TypeScript uses modular packages (`@aws-sdk/client-*`) with a command pattern: create a client, instantiate a command, call `client.send(command)`. Import only the services you need for tree-shaking. Use `DynamoDBDocumentClient` for native JS types. Use `getSignedUrl` from `@aws-sdk/s3-request-presigner` for presigned URLs. Handle errors with `instanceof` specific exception classes. Use built-in paginators (`paginate*`) with `for await...of`.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use AWS SDK v3 modular packages (`@aws-sdk/client-*`) — NEVER the monolithic `aws-sdk` v2 package)**

**(You MUST use the command pattern: `client.send(new XxxCommand({...}))` — NEVER call methods directly on the client)**

**(You MUST use `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb` for DynamoDB — it auto-marshalls native JS types)**

**(You MUST handle errors with `instanceof` specific exception classes — NEVER catch generic `Error` and check `.code`)**

**(You MUST use built-in paginators (`paginate*` functions) for paginated APIs — NEVER manually track continuation tokens)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) — Client setup, S3 operations, DynamoDB basics, credential providers, error handling, pagination
• [Messaging](examples/messaging.md) — SQS send/receive/delete, SNS publish, FIFO queues, dead-letter patterns
• [Advanced](examples/advanced.md) — Lambda invocation, Secrets Manager, presigned URLs, middleware, streaming
• [Quick Reference](reference.md) — Package cheat sheet, import patterns, error handling decision tree, credential provider chain

---

**Auto-detection:** AWS SDK, @aws-sdk/client, S3Client, DynamoDBClient, DynamoDBDocumentClient, SQSClient, LambdaClient, SNSClient, SecretsManagerClient, PutObjectCommand, GetObjectCommand, GetCommand, PutCommand, QueryCommand, SendMessageCommand, InvokeCommand, GetSecretValueCommand, getSignedUrl, s3-request-presigner, credential-providers, fromEnv, fromIni, paginateListObjectsV2, aws-sdk-client-mock

**When to use:**

• Interacting with any AWS service from TypeScript/JavaScript
• S3 file operations (upload, download, presigned URLs, listings)
• DynamoDB CRUD operations and queries
• SQS message sending, receiving, and queue management
• Lambda function invocation from other services
• SNS topic publishing and notifications
• Secrets Manager secret retrieval
• Custom middleware for request/response modification

**When NOT to use:**

• Infrastructure provisioning (use an IaC tool)
• AWS console-only operations with no SDK equivalent
• Simple CLI-only tasks better served by the AWS CLI directly

**Key patterns covered:**

• Modular client setup with typed configuration
• Command pattern (`client.send(new Command({...}))`)
• S3: upload, download, delete, list, presigned URLs, streaming
• DynamoDB: `DynamoDBDocumentClient` with `Get`, `Put`, `Query`, `Update`, `Delete`
• SQS: send, receive, delete messages, long polling, FIFO
• SNS: publish to topics, message attributes
• Lambda: synchronous and asynchronous invocation
• Secrets Manager: secret retrieval with caching
• Credential provider chain and explicit providers
• Error handling with `instanceof` exception classes and `$metadata`
• Pagination with async iterators
• Middleware stack customization
• Retry configuration

---

<philosophy>

Philosophy

AWS SDK v3 is a ground-up rewrite of the v2 SDK for modern JavaScript/TypeScript. The core design principles:

1. **Modular packages** — Each service is a separate npm package (`@aws-sdk/client-s3`, `@aws-sdk/client-dynamodb`). Import only what you use. This reduces bundle size by up to 90% compared to the monolithic v2 `aws-sdk` package.

2. **Command pattern** — Every API call is a Command object sent through a Client. This enables middleware, type safety, and testability. The client handles serialization, signing, retries, and deserialization.

3. **First-class TypeScript** — Every command input and output is fully typed. Use the types to avoid runtime errors.

4. **Middleware stack** — Customize request/response handling at various stages (serialize, build, finalize, deserialize) without monkey-patching.

5. **Built-in pagination** — Paginator functions return async iterators, eliminating manual token tracking.

**When to use AWS SDK v3:**

• Any server-side or serverless TypeScript/JavaScript that interacts with AWS services
• Frontend applications that need direct AWS access (with appropriate auth)
• Lambda functions (SDK v3 is included in Node.js 18+ Lambda runtimes)

**When NOT to use:**

• Infrastructure provisioning and management (use an IaC tool)
• One-off tasks better served by the AWS CLI
• Languages other than JavaScript/TypeScript

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Setup and Command Pattern

Every AWS service follows the same pattern: import the client and command, create a client instance, send the command.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "data.json",
  Body: JSON.stringify({ hello: "world" }),
  ContentType: "application/json",
}));

**Why good:** modular import keeps bundle small, command pattern enables middleware and type safety, region is explicit

Create clients once and reuse them — they manage connection pooling internally. In Lambda, create clients outside the handler for connection reuse across invocations.

See [examples/core.md](examples/core.md) for client reuse patt