vintasend-aws-sqs 0.9.0

package/README.md

@@ -0,0 +1,241 @@
+# VintaSend AWS SQS Queue Services
+
+AWS SQS queue services for VintaSend notification dispatch and replication workflows.
+
+## Installation
+
+```bash
+npm install vintasend-aws-sqs
+```
+
+## What this package provides
+
+- `AwsSqsNotificationQueueService`: enqueues notification IDs to a notifications queue
+- `AwsSqsReplicationQueueService`: enqueues notification IDs + backend identifiers to a replication queue
+
+Both services send JSON message bodies and are compatible with Lambda SQS triggers.
+
+## Message contracts
+
+### Notification queue message
+
+```json
+{
+  "notificationId": "notification-123"
+}
+```
+
+### Replication queue message
+
+```json
+{
+  "notificationId": "notification-123",
+  "backendIdentifier": "replica-backend"
+}
+```
+
+## Basic usage
+
+```typescript
+import {
+  AwsSqsNotificationQueueService,
+  AwsSqsReplicationQueueService,
+} from 'vintasend-aws-sqs';
+
+const notificationQueueService = new AwsSqsNotificationQueueService({
+  queueUrl: process.env.NOTIFICATION_QUEUE_URL!,
+  sqsClientConfig: { region: process.env.AWS_REGION ?? 'us-east-1' },
+});
+
+const replicationQueueService = new AwsSqsReplicationQueueService({
+  queueUrl: process.env.REPLICATION_QUEUE_URL!,
+  sqsClientConfig: { region: process.env.AWS_REGION ?? 'us-east-1' },
+});
+```
+
+## Terraform examples
+
+This package includes three Terraform examples:
+
+- `examples/terraform/notifications-queue.tf`
+- `examples/terraform/replication-queue.tf`
+- `examples/terraform/eventbridge-send-pending-notifications.tf`
+
+Each file creates:
+- Primary SQS queue
+- DLQ
+- Redrive policy with configurable retry attempts (`maxReceiveCount`)
+- Lambda event source mapping (`aws_lambda_event_source_mapping`)
+- Useful queue outputs
+
+### 1) Notifications queue + Lambda trigger
+
+Use `examples/terraform/notifications-queue.tf` and provide:
+
+- Optional `notification_lambda_function_name`: Lambda name that sends notifications
+- Optional queue tuning values (`notification_batch_size`, batching window)
+- Optional retry tuning with `notification_max_receive_count` (default: `5`)
+
+### 2) Replication queue + Lambda trigger
+
+Use `examples/terraform/replication-queue.tf` and provide:
+
+- Optional `replication_lambda_function_name`: Lambda name that performs replication to the target backend
+- Optional queue tuning values (`replication_batch_size`, batching window)
+- Optional retry tuning with `replication_max_receive_count` (default: `5`)
+
+### 3) EventBridge schedule for periodic `sendPendingNotifications`
+
+Use `examples/terraform/eventbridge-send-pending-notifications.tf` and provide:
+
+- `send_pending_notifications_lambda_function_name`: Lambda name that calls `sendPendingNotifications`
+- Optional `schedule_expression` (default: `rate(1 minute)`)
+- Optional EventBridge target retry tuning:
+  - `eventbridge_target_maximum_retry_attempts` (default: `5`)
+  - `eventbridge_target_maximum_event_age_in_seconds` (default: `3600`)
+
+### Example apply flow
+
+```bash
+cd examples/terraform
+terraform init
+
+# Create both queues only (no Lambda trigger wiring)
+terraform apply \
+  -var="project=my-app" \
+  -var="environment=prod"
+
+# Create queues and wire notification Lambda trigger
+terraform apply \
+  -var="notification_lambda_function_name=vintasend-notification-sender" \
+  -var="notification_max_receive_count=8" \
+  -var="project=my-app" \
+  -var="environment=prod"
+
+# Create queues and wire replication Lambda trigger
+terraform apply \
+  -var="replication_lambda_function_name=vintasend-replication-worker" \
+  -var="replication_max_receive_count=8" \
+  -var="project=my-app" \
+  -var="environment=prod"
+
+# Create EventBridge schedule to trigger sendPendingNotifications periodically
+terraform apply \
+  -var="send_pending_notifications_lambda_function_name=vintasend-send-pending-notifications" \
+  -var="schedule_expression=rate(5 minutes)" \
+  -var="eventbridge_target_maximum_retry_attempts=8" \
+  -var="project=my-app" \
+  -var="environment=prod"
+```
+
+## Lambda consumer setup
+
+You typically run two Lambda consumers:
+
+- Notification sender Lambda
+- Replication worker Lambda
+
+Both are triggered by SQS through event source mappings created in Terraform.
+
+### Notification sender Lambda (example)
+
+```typescript
+import type { SQSEvent, SQSBatchResponse } from 'aws-lambda';
+import { getNotificationService } from 'lib/notification-service';
+
+interface NotificationQueueMessage {
+  notificationId: string;
+}
+
+export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
+  const failures: { itemIdentifier: string }[] = [];
+
+  await Promise.all(
+    event.Records.map(async (record) => {
+      try {
+        const payload = JSON.parse(record.body) as NotificationQueueMessage;
+
+        // Call your VintaSend send operation here
+        const vintasend = getNotificationService();
+        const notification = vintaSend.getNotification(payload.notificationId);
+        await vintasend.send(notification);
+      } catch {
+        failures.push({ itemIdentifier: record.messageId });
+      }
+    }),
+  );
+
+  return { batchItemFailures: failures };
+};
+```
+
+### Replication worker Lambda (example)
+
+```typescript
+import type { SQSEvent, SQSBatchResponse } from 'aws-lambda';
+import { getNotificationService } from 'lib/notification-service';
+
+interface ReplicationQueueMessage {
+  notificationId: string;
+  backendIdentifier: string;
+}
+
+export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
+  const failures: { itemIdentifier: string }[] = [];
+
+  await Promise.all(
+    event.Records.map(async (record) => {
+      try {
+        const payload = JSON.parse(record.body) as ReplicationQueueMessage;
+
+        // Call your replication operation here
+        const vintasend = getNotificationService();
+        await vintasend.processReplication(payload.notificationId, payload.backendIdentifier);
+      } catch {
+        failures.push({ itemIdentifier: record.messageId });
+      }
+    }),
+  );
+
+  return { batchItemFailures: failures };
+};
+```
+
+### Periodic pending notifications Lambda (EventBridge example)
+
+```typescript
+import type { EventBridgeEvent } from 'aws-lambda';
+import { getNotificationService } from 'lib/notification-service';
+
+export const handler = async (
+  _event: EventBridgeEvent<string, unknown>,
+): Promise<{ ok: true }> => {
+  const vintasend = getNotificationService();
+  await vintasend.sendPendingNotifications();
+  return { ok: true };
+};
+```
+
+This Lambda is invoked by EventBridge and should call `sendPendingNotifications()` once per schedule tick.
+
+## Required Lambda IAM permissions
+
+Your Lambda execution roles need SQS consumer permissions for their respective queues:
+
+- `sqs:ReceiveMessage`
+- `sqs:DeleteMessage`
+- `sqs:ChangeMessageVisibility`
+- `sqs:GetQueueAttributes`
+- `sqs:GetQueueUrl`
+
+## Operational notes
+
+- Keep queue `visibility_timeout_seconds` greater than Lambda timeout.
+- Use DLQ monitoring and alarms for failed messages.
+- Use idempotent handlers to safely handle retries.
+- Keep batch size aligned with downstream throughput.
+- Tune retries with `notification_max_receive_count` and `replication_max_receive_count` based on transient failure patterns.
+
+## License
+
+MIT

package/dist/aws-sqs-notification-queue-service.d.ts

@@ -0,0 +1,15 @@
+import { SQSClient, type SQSClientConfig } from '@aws-sdk/client-sqs';
+import type { BaseNotificationQueueService } from 'vintasend/dist/services/notification-queue-service/base-notification-queue-service';
+import type { BaseNotificationTypeConfig } from 'vintasend/dist/types/notification-type-config';
+export interface AwsSqsNotificationQueueServiceConfig {
+    queueUrl: string;
+    sqsClient?: SQSClient;
+    sqsClientConfig?: SQSClientConfig;
+}
+export declare class AwsSqsNotificationQueueService<Config extends BaseNotificationTypeConfig> implements BaseNotificationQueueService<Config> {
+    private config;
+    private sqsClient;
+    constructor(config: AwsSqsNotificationQueueServiceConfig);
+    enqueueNotification(notificationId: Config['NotificationIdType']): Promise<void>;
+}
+//# sourceMappingURL=aws-sqs-notification-queue-service.d.ts.map

package/dist/aws-sqs-notification-queue-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-sqs-notification-queue-service.d.ts","sourceRoot":"","sources":["../src/aws-sqs-notification-queue-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oFAAoF,CAAC;AACvI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAEhG,MAAM,WAAW,oCAAoC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,qBAAa,8BAA8B,CAC1C,MAAM,SAAS,0BAA0B,CACxC,YAAW,4BAA4B,CAAC,MAAM,CAAC;IAIpC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,SAAS,CAAY;gBAET,MAAM,EAAE,oCAAoC;IAQ1D,mBAAmB,CAAC,cAAc,EAAE,MAAM,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAUtF"}

package/dist/aws-sqs-notification-queue-service.js

@@ -0,0 +1,19 @@
+import { SendMessageCommand, SQSClient } from '@aws-sdk/client-sqs';
+export class AwsSqsNotificationQueueService {
+    constructor(config) {
+        this.config = config;
+        this.sqsClient =
+            config.sqsClient ??
+                new SQSClient({
+                    ...config.sqsClientConfig,
+                });
+    }
+    async enqueueNotification(notificationId) {
+        await this.sqsClient.send(new SendMessageCommand({
+            QueueUrl: this.config.queueUrl,
+            MessageBody: JSON.stringify({
+                notificationId,
+            }),
+        }));
+    }
+}

package/dist/aws-sqs-replication-queue-service.d.ts

@@ -0,0 +1,15 @@
+import { SQSClient, type SQSClientConfig } from '@aws-sdk/client-sqs';
+import type { BaseNotificationReplicationQueueService } from 'vintasend/dist/services/notification-queue-service/base-notification-replication-queue-service';
+import type { BaseNotificationTypeConfig } from 'vintasend/dist/types/notification-type-config';
+export interface AwsSqsReplicationQueueServiceConfig {
+    queueUrl: string;
+    sqsClient?: SQSClient;
+    sqsClientConfig?: SQSClientConfig;
+}
+export declare class AwsSqsReplicationQueueService<Config extends BaseNotificationTypeConfig> implements BaseNotificationReplicationQueueService<Config> {
+    private config;
+    private sqsClient;
+    constructor(config: AwsSqsReplicationQueueServiceConfig);
+    enqueueReplication(notificationId: Config['NotificationIdType'], backendIdentifier: string): Promise<void>;
+}
+//# sourceMappingURL=aws-sqs-replication-queue-service.d.ts.map

package/dist/aws-sqs-replication-queue-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-sqs-replication-queue-service.d.ts","sourceRoot":"","sources":["../src/aws-sqs-replication-queue-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,gGAAgG,CAAC;AAC9J,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAEhG,MAAM,WAAW,mCAAmC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,qBAAa,6BAA6B,CACzC,MAAM,SAAS,0BAA0B,CACxC,YAAW,uCAAuC,CAAC,MAAM,CAAC;IAI/C,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,SAAS,CAAY;gBAET,MAAM,EAAE,mCAAmC;IAQzD,kBAAkB,CACvB,cAAc,EAAE,MAAM,CAAC,oBAAoB,CAAC,EAC5C,iBAAiB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC;CAWhB"}

package/dist/aws-sqs-replication-queue-service.js

@@ -0,0 +1,20 @@
+import { SendMessageCommand, SQSClient } from '@aws-sdk/client-sqs';
+export class AwsSqsReplicationQueueService {
+    constructor(config) {
+        this.config = config;
+        this.sqsClient =
+            config.sqsClient ??
+                new SQSClient({
+                    ...config.sqsClientConfig,
+                });
+    }
+    async enqueueReplication(notificationId, backendIdentifier) {
+        await this.sqsClient.send(new SendMessageCommand({
+            QueueUrl: this.config.queueUrl,
+            MessageBody: JSON.stringify({
+                notificationId,
+                backendIdentifier,
+            }),
+        }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AwsSqsNotificationQueueService, type AwsSqsNotificationQueueServiceConfig, } from './aws-sqs-notification-queue-service';
+export { AwsSqsReplicationQueueService, type AwsSqsReplicationQueueServiceConfig, } from './aws-sqs-replication-queue-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8BAA8B,EAC9B,KAAK,oCAAoC,GACzC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACN,6BAA6B,EAC7B,KAAK,mCAAmC,GACxC,MAAM,qCAAqC,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AwsSqsNotificationQueueService, } from './aws-sqs-notification-queue-service';
+export { AwsSqsReplicationQueueService, } from './aws-sqs-replication-queue-service';

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vintasend-aws-sqs",
+  "version": "0.9.0",
+  "description": "",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Hugo Bessa",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-sqs": "^3.1000.0",
+    "vintasend": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}