# AWS SDK v3 — Advanced Patterns

> Lambda invocation, Secrets Manager, presigned URLs, middleware, and streaming. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [Core Patterns](core.md) — Client setup, S3, DynamoDB, error handling
- [Messaging](messaging.md) — SQS, SNS patterns

---

## Lambda — Synchronous Invocation

```typescript
import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";

const lambda = new LambdaClient({});

interface ProcessResult {
  status: string;
  processedAt: string;
}

export async function invokeProcessor(orderId: string): Promise<ProcessResult> {
  const response = await lambda.send(
    new InvokeCommand({
      FunctionName: "order-processor",
      InvocationType: "RequestResponse", // Synchronous — waits for result
      Payload: JSON.stringify({ orderId }),
    }),
  );

  if (response.FunctionError) {
    const errorPayload = JSON.parse(new TextDecoder().decode(response.Payload));
    throw new Error(`Lambda error: ${errorPayload.errorMessage}`);
  }

  return JSON.parse(
    new TextDecoder().decode(response.Payload),
  ) as ProcessResult;
}
```

**Why good:** checks `FunctionError` before parsing payload (Lambda sets this on unhandled exceptions), `TextDecoder` properly decodes the `Uint8Array` payload

**Gotcha:** `response.Payload` is a `Uint8Array`, not a string — always decode with `new TextDecoder().decode()` before `JSON.parse()`.

---

## Lambda — Asynchronous Invocation

```typescript
export async function triggerAsync(
  functionName: string,
  payload: unknown,
): Promise<void> {
  await lambda.send(
    new InvokeCommand({
      FunctionName: functionName,
      InvocationType: "Event", // Async — returns immediately, Lambda retries up to 2 times
      Payload: JSON.stringify(payload),
    }),
  );
  // Returns 202 Accepted — no response payload
}
```

**When to use:** fire-and-forget operations where you don't need the result (notifications, background processing, fan-out).

---

## Secrets Manager — Retrieve Secret

```typescript
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from "@aws-sdk/client-secrets-manager";

const secretsManager = new SecretsManagerClient({});

export async function getSecret(secretName: string): Promise<string> {
  const { SecretString } = await secretsManager.send(
    new GetSecretValueCommand({ SecretId: secretName }),
  );
  if (!SecretString) {
    throw new Error(`Secret "${secretName}" has no string value`);
  }
  return SecretString;
}

// For JSON secrets (common pattern: DB credentials, API keys)
interface DbCredentials {
  host: string;
  port: number;
  username: string;
  password: string;
}

export async function getDbCredentials(
  secretName: string,
): Promise<DbCredentials> {
  const secretString = await getSecret(secretName);
  return JSON.parse(secretString) as DbCredentials;
}
```

---

## Secrets Manager — Cached Secret

Secrets don't change frequently. Cache them to avoid API calls on every request.

```typescript
const SECRET_CACHE_TTL_MS = 300_000; // 5 minutes

interface CachedSecret {
  value: string;
  expiresAt: number;
}

const secretCache = new Map<string, CachedSecret>();

export async function getCachedSecret(secretName: string): Promise<string> {
  const cached = secretCache.get(secretName);
  if (cached && cached.expiresAt > Date.now()) {
    return cached.value;
  }

  const value = await getSecret(secretName);
  secretCache.set(secretName, {
    value,
    expiresAt: Date.now() + SECRET_CACHE_TTL_MS,
  });
  return value;
}
```

**Why good:** avoids Secrets Manager API call on every request, TTL ensures secrets refresh periodically, simple in-memory cache works well in Lambda (cache persists across warm invocations)

---

## S3 — Presigned URLs

Presigned URLs grant temporary access to S3 objects without exposing AWS credentials.

```typescript
import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3 } from "./lib/aws-clients.js";

const DOWNLOAD_EXPIRY_SECONDS = 3_600; // 1 hour
const UPLOAD_EXPIRY_SECONDS = 900; // 15 minutes
const MAX_UPLOAD_SIZE = 10 * 1024 * 1024; // 10 MB

// Generate a download URL
export async function getDownloadUrl(
  bucket: string,
  key: string,
): Promise<string> {
  return getSignedUrl(s3, new GetObjectCommand({ Bucket: bucket, Key: key }), {
    expiresIn: DOWNLOAD_EXPIRY_SECONDS,
  });
}

// Generate an upload URL with content-type restriction
export async function getUploadUrl(
  bucket: string,
  key: string,
  contentType: string,
): Promise<string> {
  return getSignedUrl(
    s3,
    new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      ContentType: contentType,
      ContentLength: MAX_UPLOAD_SIZE, // Enforces max file size
    }),
    { expiresIn: UPLOAD_EXPIRY_SECONDS },
  );
}
```

**Why good:** separate expiry times for download vs upload, `ContentType` on upload prevents wrong file types, named constants for all limits

**Gotcha:** Presigned URL expiry is capped at 7 days. If using temporary credentials (IAM role, STS), the URL stops working when the signing credentials expire — even if `expiresIn` is longer.

---

## S3 — Streaming Large Files

For large files, stream directly without buffering the entire content in memory.

```typescript
import { GetObjectCommand } from "@aws-sdk/client-s3";
import { createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";
import { Readable } from "node:stream";
import { s3 } from "./lib/aws-clients.js";

export async function downloadToFile(
  bucket: string,
  key: string,
  outputPath: string,
): Promise<void> {
  const response = await s3.send(
    new GetObjectCommand({ Bucket: bucket, Key: key }),
  );
  if (!response.Body) throw new Error(`Empty response for ${key}`);

  // Convert web ReadableStream to Node.js Readable
  const nodeStream = Readable.fromWeb(response.Body.transformToWebStream());
  await pipeline(nodeStream, createWriteStream(outputPath));
}
```

**Why good:** `pipeline` handles backpressure and cleanup, no memory buffering for large files, `Readable.fromWeb()` bridges web streams to Node.js streams

---

## Middleware — Custom Request Logging

The middleware stack lets you intercept and modify requests at various stages.

```typescript
import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });

s3.middlewareStack.add(
  (next, context) => async (args) => {
    const startTime = Date.now();
    const result = await next(args);
    const duration = Date.now() - startTime;

    console.log(
      JSON.stringify({
        service: "s3",
        operation: context.commandName,
        durationMs: duration,
        statusCode: result.response.statusCode,
      }),
    );

    return result;
  },
  {
    step: "deserialize", // Run after response is received
    name: "requestLogger",
    priority: "low",
  },
);
```

**Why good:** middleware runs for every request through this client, structured JSON logging, minimal overhead at the deserialize step

---

## Middleware — Add Custom Headers

```typescript
s3.middlewareStack.add(
  (next) => async (args: any) => {
    args.request.headers["x-correlation-id"] = getCorrelationId();
    return next(args);
  },
  {
    step: "build", // Run before request is signed
    name: "correlationId",
  },
);
```

**Why good:** adding headers at the `build` step means they get included in request signing, correlation ID enables request tracing across services

**Gotcha:** Adding headers at the `finalize` step (after signing) will cause signature mismatch errors for services that verify all headers.

---

## STS — Assume Role for Cross-Account Access

```typescript
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
import { S3Client } from "@aws-sdk/client-s3";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";

// Option 1: Using credential provider (recommended — auto-refreshes)
const crossAccountS3 = new S3Client({
  region: "us-east-1",
  credentials: fromTemporaryCredentials({
    params: {
      RoleArn: "arn:aws:iam::987654321098:role/data-reader",
      RoleSessionName: "my-app",
    },
  }),
});

// Option 2: Manual AssumeRole (when you need the credentials object)
const sts = new STSClient({});
const SESSION_DURATION_SECONDS = 3_600;

export async function assumeRole(roleArn: string) {
  const { Credentials } = await sts.send(
    new AssumeRoleCommand({
      RoleArn: roleArn,
      RoleSessionName: "my-app",
      DurationSeconds: SESSION_DURATION_SECONDS,
    }),
  );
  return {
    accessKeyId: Credentials!.AccessKeyId!,
    secretAccessKey: Credentials!.SecretAccessKey!,
    sessionToken: Credentials!.SessionToken!,
    expiration: Credentials!.Expiration!,
  };
}
```

**Why good:** `fromTemporaryCredentials` auto-refreshes when credentials expire, manual option available when you need to pass credentials to external systems

# AWS SDK v3 — Core Patterns

> Client setup, S3 operations, DynamoDB basics, credential providers, error handling, and pagination. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [Messaging](messaging.md) — SQS, SNS patterns
- [Advanced](advanced.md) — Lambda, Secrets Manager, presigned URLs, middleware

---

## Client Setup and Reuse

Create clients once at module scope and reuse them. Clients manage connection pooling internally.

```typescript
// lib/aws-clients.ts — shared client instances
import { S3Client } from "@aws-sdk/client-s3";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";

const REGION = process.env.AWS_REGION ?? "us-east-1";

export const s3 = new S3Client({ region: REGION });

const ddbClient = new DynamoDBClient({ region: REGION });
export const ddb = DynamoDBDocumentClient.from(ddbClient, {
  marshallOptions: { removeUndefinedValues: true },
});
```

**Why good:** single client instance reuses TCP connections, `removeUndefinedValues` avoids marshalling errors from optional fields, region from env var with fallback

```typescript
// BAD: Creating a new client per request
async function getUser(userId: string) {
  const client = new DynamoDBClient({ region: "us-east-1" }); // New connection per call
  const ddb = DynamoDBDocumentClient.from(client);
  // ...
}
```

**Why bad:** creates new TCP connections per request, wastes resources, slower due to connection setup overhead

---

## S3 Upload

```typescript
import { PutObjectCommand } from "@aws-sdk/client-s3";
import { s3 } from "./lib/aws-clients.js";

const CONTENT_TYPE_JSON = "application/json";

export async function uploadJson(
  bucket: string,
  key: string,
  data: unknown,
): Promise<void> {
  await s3.send(
    new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      Body: JSON.stringify(data),
      ContentType: CONTENT_TYPE_JSON,
    }),
  );
}
```

**Why good:** explicit `ContentType` prevents S3 defaulting to `application/octet-stream`, reuses shared client

---

## S3 Download

```typescript
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
import { s3 } from "./lib/aws-clients.js";

export async function downloadJson<T>(
  bucket: string,
  key: string,
): Promise<T | null> {
  try {
    const response = await s3.send(
      new GetObjectCommand({ Bucket: bucket, Key: key }),
    );
    const body = await response.Body?.transformToString();
    if (!body) return null;
    return JSON.parse(body) as T;
  } catch (error) {
    if (error instanceof NoSuchKey) return null;
    throw error;
  }
}
```

**Why good:** `transformToString()` properly consumes the stream, `instanceof NoSuchKey` gives typed error handling, returns `null` for missing keys instead of throwing

```typescript
// BAD: v2-style error handling
try {
  await s3.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
} catch (error: any) {
  if (error.code === "NoSuchKey") {
    // String comparison — fragile, no type narrowing
    return null;
  }
}
```

**Why bad:** `.code` is a v2 pattern, no TypeScript narrowing, `any` type loses safety

---

## S3 Delete

```typescript
import { DeleteObjectCommand } from "@aws-sdk/client-s3";
import { s3 } from "./lib/aws-clients.js";

export async function deleteObject(bucket: string, key: string): Promise<void> {
  await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
  // Note: DeleteObject succeeds even if the key doesn't exist (idempotent)
}
```

---

## S3 List with Pagination

```typescript
import { paginateListObjectsV2 } from "@aws-sdk/client-s3";
import { s3 } from "./lib/aws-clients.js";

const MAX_KEYS_PER_PAGE = 1_000;

export async function listAllKeys(
  bucket: string,
  prefix: string,
): Promise<string[]> {
  const paginator = paginateListObjectsV2(
    { client: s3, pageSize: MAX_KEYS_PER_PAGE },
    { Bucket: bucket, Prefix: prefix },
  );

  const keys: string[] = [];
  for await (const page of paginator) {
    const pageKeys = page.Contents?.map((obj) => obj.Key).filter(Boolean) ?? [];
    keys.push(...(pageKeys as string[]));
  }
  return keys;
}
```

**Why good:** built-in paginator handles continuation tokens automatically, `for await...of` is clean and readable, `pageSize` controls batch size

```typescript
// BAD: Manual pagination with token tracking
let token: string | undefined;
const keys: string[] = [];
do {
  const response = await s3.send(
    new ListObjectsV2Command({
      Bucket: bucket,
      Prefix: prefix,
      ContinuationToken: token,
    }),
  );
  keys.push(...(response.Contents?.map((o) => o.Key!).filter(Boolean) ?? []));
  token = response.NextContinuationToken;
} while (token);
```

**Why bad:** manual token tracking is error-prone and verbose, built-in paginators exist for this exact purpose

---

## DynamoDB Get

```typescript
import { GetCommand } from "@aws-sdk/lib-dynamodb";
import { ddb } from "./lib/aws-clients.js";

interface User {
  userId: string;
  email: string;
  name: string;
  createdAt: string;
}

export async function getUser(userId: string): Promise<User | null> {
  const { Item } = await ddb.send(
    new GetCommand({
      TableName: "users",
      Key: { userId },
    }),
  );
  return (Item as User) ?? null;
}
```

**Why good:** `GetCommand` from `@aws-sdk/lib-dynamodb` accepts native JS objects (no marshalling), returns native JS objects

---

## DynamoDB Put

```typescript
import { PutCommand } from "@aws-sdk/lib-dynamodb";
import { ddb } from "./lib/aws-clients.js";

export async function createUser(user: User): Promise<void> {
  await ddb.send(
    new PutCommand({
      TableName: "users",
      Item: user,
      ConditionExpression: "attribute_not_exists(userId)", // Prevent overwrite
    }),
  );
}
```

---

## DynamoDB Query

```typescript
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
import { ddb } from "./lib/aws-clients.js";

const DEFAULT_LIMIT = 20;

export async function getUserOrders(
  userId: string,
  limit = DEFAULT_LIMIT,
): Promise<Order[]> {
  const { Items } = await ddb.send(
    new QueryCommand({
      TableName: "orders",
      KeyConditionExpression: "userId = :userId",
      ExpressionAttributeValues: { ":userId": userId },
      ScanIndexForward: false, // newest first
      Limit: limit,
    }),
  );
  return (Items as Order[]) ?? [];
}
```

---

## DynamoDB Update

```typescript
import { UpdateCommand } from "@aws-sdk/lib-dynamodb";
import { ddb } from "./lib/aws-clients.js";

export async function updateUserName(
  userId: string,
  name: string,
): Promise<void> {
  await ddb.send(
    new UpdateCommand({
      TableName: "users",
      Key: { userId },
      UpdateExpression: "SET #name = :name, updatedAt = :now",
      ExpressionAttributeNames: { "#name": "name" }, // "name" is a DynamoDB reserved word
      ExpressionAttributeValues: {
        ":name": name,
        ":now": new Date().toISOString(),
      },
      ConditionExpression: "attribute_exists(userId)", // Fail if user doesn't exist
    }),
  );
}
```

**Why good:** `ExpressionAttributeNames` handles the reserved word "name", `ConditionExpression` prevents updating non-existent items, timestamps updated atomically

---

## DynamoDB Delete

```typescript
import { DeleteCommand } from "@aws-sdk/lib-dynamodb";
import { ddb } from "./lib/aws-clients.js";

export async function deleteUser(userId: string): Promise<void> {
  await ddb.send(
    new DeleteCommand({
      TableName: "users",
      Key: { userId },
      ConditionExpression: "attribute_exists(userId)", // Fail if already deleted
    }),
  );
}
```

---

## Credential Providers

```typescript
import { S3Client } from "@aws-sdk/client-s3";
import {
  fromIni,
  fromTemporaryCredentials,
} from "@aws-sdk/credential-providers";

// Local development — use a named AWS profile
const devClient = new S3Client({
  region: "us-east-1",
  credentials: fromIni({ profile: "my-dev-profile" }),
});

// Cross-account access — assume a role in another account
const crossAccountClient = new S3Client({
  region: "us-east-1",
  credentials: fromTemporaryCredentials({
    params: {
      RoleArn: "arn:aws:iam::123456789012:role/cross-account-role",
      RoleSessionName: "my-app-session",
    },
  }),
});
```

**Why good:** explicit credential providers for specific use cases, no hardcoded keys, `fromTemporaryCredentials` uses STS AssumeRole under the hood

**Note:** In Lambda, ECS, and EC2, don't configure credentials at all — the default chain picks up the IAM role automatically.

---

## Error Handling — Full Pattern

```typescript
import {
  GetObjectCommand,
  NoSuchKey,
  NoSuchBucket,
  S3ServiceException,
} from "@aws-sdk/client-s3";
import { s3 } from "./lib/aws-clients.js";

export async function safeGetObject(
  bucket: string,
  key: string,
): Promise<string | null> {
  try {
    const response = await s3.send(
      new GetObjectCommand({ Bucket: bucket, Key: key }),
    );
    return (await response.Body?.transformToString()) ?? null;
  } catch (error) {
    // 1. Check specific exception types first
    if (error instanceof NoSuchKey) {
      return null; // Expected — object doesn't exist
    }
    if (error instanceof NoSuchBucket) {
      throw new Error(`Bucket "${bucket}" does not exist`);
    }

    // 2. Check general service exception
    if (error instanceof S3ServiceException) {
      // Access $metadata for HTTP status and request ID
      const { httpStatusCode, requestId } = error.$metadata;
      throw new Error(
        `S3 error [${httpStatusCode}]: ${error.message} (requestId: ${requestId})`,
      );
    }

    // 3. Non-AWS error (network timeout, DNS failure, etc.)
    throw error;
  }
}
```

---

## Retry Configuration

```typescript
import { S3Client } from "@aws-sdk/client-s3";

const MAX_RETRY_ATTEMPTS = 5;

const s3 = new S3Client({
  region: "us-east-1",
  maxAttempts: MAX_RETRY_ATTEMPTS, // Default is 3
});
```

The SDK automatically retries throttling errors (429) and transient server errors (500, 502, 503) with exponential backoff. Increase `maxAttempts` for high-throughput workloads.

# AWS SDK v3 — Messaging Patterns (SQS & SNS)

> SQS send/receive/delete, SNS publish, FIFO queues, and dead-letter patterns. See [SKILL.md](../SKILL.md) for decision guidance.

**Related examples:**

- [Core Patterns](core.md) — Client setup, S3, DynamoDB, error handling
- [Advanced](advanced.md) — Lambda, Secrets Manager, presigned URLs, middleware

---

## SQS — Send Message

```typescript
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const sqs = new SQSClient({});

export async function enqueueOrder(
  queueUrl: string,
  order: OrderPayload,
): Promise<string> {
  const result = await sqs.send(
    new SendMessageCommand({
      QueueUrl: queueUrl,
      MessageBody: JSON.stringify(order),
      MessageAttributes: {
        eventType: { DataType: "String", StringValue: "order.created" },
      },
    }),
  );
  return result.MessageId!;
}
```

**Why good:** message attributes enable filtering at the subscription level, typed `SendMessageCommand` provides input validation

---

## SQS — Receive and Delete Messages

Always delete messages after successful processing. Undeleted messages reappear after the visibility timeout.

```typescript
import {
  ReceiveMessageCommand,
  DeleteMessageCommand,
} from "@aws-sdk/client-sqs";

const MAX_MESSAGES = 10;
const WAIT_TIME_SECONDS = 20; // Long polling — reduces empty responses and cost

export async function pollMessages(queueUrl: string): Promise<void> {
  const { Messages } = await sqs.send(
    new ReceiveMessageCommand({
      QueueUrl: queueUrl,
      MaxNumberOfMessages: MAX_MESSAGES,
      WaitTimeSeconds: WAIT_TIME_SECONDS,
      MessageAttributeNames: ["All"],
    }),
  );

  // IMPORTANT: Messages may be undefined (not empty array) when queue is empty
  for (const message of Messages ?? []) {
    try {
      const body = JSON.parse(message.Body!);
      await processMessage(body);

      // Delete only after successful processing
      await sqs.send(
        new DeleteMessageCommand({
          QueueUrl: queueUrl,
          ReceiptHandle: message.ReceiptHandle!,
        }),
      );
    } catch (error) {
      // Message stays in queue — will be retried after visibility timeout
      console.error(`Failed to process message ${message.MessageId}:`, error);
    }
  }
}
```

**Why good:** long polling (`WaitTimeSeconds: 20`) reduces empty responses and API costs, per-message try/catch prevents one failure from blocking the batch, delete-after-process ensures at-least-once delivery

```typescript
// BAD: Deleting before processing
for (const message of Messages ?? []) {
  await sqs.send(
    new DeleteMessageCommand({
      QueueUrl: queueUrl,
      ReceiptHandle: message.ReceiptHandle!,
    }),
  );
  await processMessage(JSON.parse(message.Body!)); // If this fails, message is lost
}
```

**Why bad:** deleting before processing means failed messages are lost permanently — they never return to the queue

---

## SQS — FIFO Queue

FIFO queues guarantee ordering and exactly-once processing within a message group.

```typescript
const FIFO_QUEUE_URL =
  "https://sqs.us-east-1.amazonaws.com/123456789012/orders.fifo";

export async function enqueueFifoMessage(
  orderId: string,
  payload: unknown,
): Promise<void> {
  await sqs.send(
    new SendMessageCommand({
      QueueUrl: FIFO_QUEUE_URL,
      MessageBody: JSON.stringify(payload),
      MessageGroupId: orderId, // Messages with same group ID are ordered
      MessageDeduplicationId: `${orderId}-${Date.now()}`, // Prevents duplicate processing
    }),
  );
}
```

**Why good:** `MessageGroupId` ensures all messages for the same order are processed in order, `MessageDeduplicationId` prevents duplicate delivery within the 5-minute deduplication window

**Gotcha:** FIFO queue URLs must end with `.fifo`. The `MessageGroupId` and `MessageDeduplicationId` are required for FIFO queues.

---

## SQS — Batch Send

Use `SendMessageBatchCommand` to send up to 10 messages in a single API call.

```typescript
import { SendMessageBatchCommand } from "@aws-sdk/client-sqs";

const MAX_BATCH_SIZE = 10;

export async function enqueueBatch(
  queueUrl: string,
  messages: OrderPayload[],
): Promise<void> {
  // Split into chunks of MAX_BATCH_SIZE
  for (let i = 0; i < messages.length; i += MAX_BATCH_SIZE) {
    const batch = messages.slice(i, i + MAX_BATCH_SIZE);
    await sqs.send(
      new SendMessageBatchCommand({
        QueueUrl: queueUrl,
        Entries: batch.map((msg, idx) => ({
          Id: String(idx),
          MessageBody: JSON.stringify(msg),
        })),
      }),
    );
  }
}
```

---

## SNS — Publish to Topic

```typescript
import { SNSClient, PublishCommand } from "@aws-sdk/client-sns";

const sns = new SNSClient({});

export async function publishEvent(
  topicArn: string,
  event: { type: string; payload: unknown },
): Promise<string> {
  const result = await sns.send(
    new PublishCommand({
      TopicArn: topicArn,
      Message: JSON.stringify(event.payload),
      MessageAttributes: {
        eventType: { DataType: "String", StringValue: event.type },
      },
    }),
  );
  return result.MessageId!;
}
```

**Why good:** message attributes enable SNS subscription filter policies — subscribers only receive events matching their filter

---

## SNS — Publish with Subject (for Email Subscriptions)

```typescript
export async function sendNotification(
  topicArn: string,
  subject: string,
  message: string,
): Promise<void> {
  await sns.send(
    new PublishCommand({
      TopicArn: topicArn,
      Subject: subject, // Used as email subject for email subscribers
      Message: message,
    }),
  );
}
```

---

## SNS — Publish to FIFO Topic

```typescript
const FIFO_TOPIC_ARN = "arn:aws:sns:us-east-1:123456789012:orders.fifo";

export async function publishFifoEvent(
  groupId: string,
  payload: unknown,
): Promise<void> {
  await sns.send(
    new PublishCommand({
      TopicArn: FIFO_TOPIC_ARN,
      Message: JSON.stringify(payload),
      MessageGroupId: groupId,
      MessageDeduplicationId: `${groupId}-${Date.now()}`,
    }),
  );
}
```

**Gotcha:** FIFO topic ARNs must end with `.fifo`. FIFO topics can only deliver to FIFO SQS queues, not standard queues or other endpoint types.