@adobe-commerce/aio-toolkit 1.2.5 → 1.2.6

package/files/cursor-context/rules/aio-toolkit-use-amazon-sqs-publish.mdc

@@ -0,0 +1,397 @@
+---
+description: Adding Amazon SQS message publishing to Adobe I/O Runtime actions using @adobe-commerce/aio-toolkit
+globs: '**/{actions,lib}/**/*.{ts,js}'
+alwaysApply: false
+---
+
+# Using Amazon SQS — Publish
+
+## Trigger Conditions
+
+This rule applies when the user wants to publish (send) messages to an Amazon SQS queue from within an existing action using any of these phrases:
+
+- "Publish messages to SQS"
+- "Send messages to Amazon SQS"
+- "Queue work to SQS"
+- "Add SQS publishing to [action-name]"
+- "Write to SQS queue"
+- "Push payloads to SQS"
+- "Use AmazonSQSClient to publish"
+- "Fan-out via SQS"
+- "Queue [entity] for processing in SQS"
+
+**Important**: This rule does NOT create new actions. It integrates `AmazonSQSClient.publish()` into an **existing** action only.
+
+**Integration with Other Action Creation Rules:**
+
+When using action creation rules (RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction) and the developer mentions publishing to SQS in the business logic:
+
+- **Automatically trigger this rule** after the action is created
+- This rule handles client construction, payload serialisation, stats checking, config wiring, and env setup
+
+---
+
+## Step 1: Confirm Prerequisites
+
+Before generating code, confirm:
+
+1. **`@adobe-commerce/aio-toolkit` installed**: `AmazonSQSClient` is exported from it — check `package.json`
+   - If NOT installed: `npm install @adobe-commerce/aio-toolkit`
+
+2. **`@aws-sdk/client-sqs` installed** (peer dependency — required):
+   - Check `package.json` dependencies
+   - If NOT installed: `npm install @aws-sdk/client-sqs`
+
+3. **SQS queue already exists**: `AmazonSQSClient` does not create queues. The target queue must exist in AWS before the action runs.
+
+---
+
+## Step 2: Ask Clarifying Questions
+
+Ask the following before generating any code:
+
+1. **Which action file** should `publish()` be added to?
+
+2. **Payload structure** — what does each message body contain?
+   - Is it a JSON object? If so, what fields?
+   - Is there a type/event discriminator field?
+   - Example: `{ type: 'order.created', data: { orderId, ... } }`
+
+3. **FIFO queue?** — does the queue URL end in `.fifo`?
+   - If yes: ask for a `messageGroupId` (default `'default'`)
+
+4. **Single payload or array?** — does the action publish one message at a time or build an array first then publish in bulk?
+
+5. **Error handling preference** — what should happen when `stats.failed > 0`?
+   - Log and continue (soft failure)
+   - Return an error response (hard failure)
+   - Retry failed payloads (ask how many retries)
+
+---
+
+## Step 3: Confirm Plan
+
+Before writing code, confirm the implementation plan:
+
+```
+I'll make the following changes:
+
+1. Action file ([path/to/action/index.ts|js]):
+   - Import AmazonSQSClient from @adobe-commerce/aio-toolkit
+   - Construct sqs client from params (AWS_REGION, AWS_ACCESS_KEY_ID,
+     AWS_SECRET_ACCESS_KEY, AWS_SQS_URL)
+   - Build payloads array [JSON.stringify(...) per message]
+   - Call sqs.publish(payloads) and check stats
+   - Log stats.published / stats.failed
+   [If stats.failed > 0: log errors / return error response]
+
+2. app.config.yaml (or ext.config.yaml / actions.config.yaml):
+   - Add AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SQS_URL inputs
+
+3. .env:
+   - Add AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SQS_URL
+
+Shall I proceed?
+```
+
+---
+
+## Step 4: Generate Code
+
+Detect language (TypeScript or JavaScript) by checking the action file extension or `tsconfig.json`. Generate in the detected language.
+
+### A. Adding publish() to a RuntimeAction
+
+```javascript
+const {
+  AmazonSQSClient,
+  RuntimeAction,
+  RuntimeActionResponse,
+  HttpMethod,
+  HttpStatus,
+} = require('@adobe-commerce/aio-toolkit');
+
+const name = '[action-name]';
+
+exports.main = RuntimeAction.execute(
+  name,
+  [HttpMethod.POST],
+  ['AWS_REGION', 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SQS_URL'],
+  ['Authorization'],
+  async (params, ctx) => {
+    const { logger } = ctx;
+
+    logger.info({ message: `${name}-start` });
+
+    const sqs = new AmazonSQSClient({
+      region: params.AWS_REGION,
+      accessKeyId: params.AWS_ACCESS_KEY_ID,
+      secretAccessKey: params.AWS_SECRET_ACCESS_KEY,
+      queueUrl: params.AWS_SQS_URL,
+      // visibilityTimeout: 30,   // optional — only relevant for consumers
+      // messageGroupId: 'default', // optional — FIFO queues only
+    });
+
+    // Build payloads — each string becomes one SQS message
+    const payloads = [
+      JSON.stringify({ type: '[event-type]', data: { /* your fields */ } }),
+      // ... or build an array from your business data
+    ];
+
+    logger.info({ message: `${name}-publishing`, count: payloads.length });
+
+    const stats = await sqs.publish(payloads);
+
+    logger.info({
+      message: `${name}-published`,
+      published: stats.published,
+      failed: stats.failed,
+    });
+
+    if (stats.failed > 0) {
+      logger.error({
+        message: `${name}-publish-errors`,
+        failed: stats.failed,
+        first_error: stats.errors[0]?.error?.message,
+      });
+      // Decide: return error response, or continue with partial success
+    }
+
+    return RuntimeActionResponse.success({
+      success: true,
+      stats: { published: stats.published, failed: stats.failed },
+    });
+  }
+);
+```
+
+**TypeScript imports:**
+
+```typescript
+import { AmazonSQSClient } from '@adobe-commerce/aio-toolkit';
+import type { AmazonSQSPublishStats } from '@adobe-commerce/aio-toolkit';
+```
+
+### B. Adding publish() to an EventConsumerAction (fan-out pattern)
+
+A common pattern: receive an I/O Event, validate/transform the payload, then fan-out to SQS for downstream processing.
+
+```javascript
+const {
+  AmazonSQSClient,
+  EventConsumerAction,
+} = require('@adobe-commerce/aio-toolkit');
+
+exports.main = EventConsumerAction.execute(
+  '[action-name]',
+  ['AWS_REGION', 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SQS_URL'],
+  async (params, ctx) => {
+    const { logger } = ctx;
+
+    const sqs = new AmazonSQSClient({
+      region: params.AWS_REGION,
+      accessKeyId: params.AWS_ACCESS_KEY_ID,
+      secretAccessKey: params.AWS_SECRET_ACCESS_KEY,
+      queueUrl: params.AWS_SQS_URL,
+    });
+
+    // Transform I/O Event payload into SQS message(s)
+    const payload = JSON.stringify({
+      type: params.type,  // I/O Event type
+      data: params.data,  // I/O Event data
+    });
+
+    const stats = await sqs.publish([payload]);
+
+    logger.info({
+      message: '[action-name]-queued',
+      published: stats.published,
+      failed: stats.failed,
+    });
+
+    if (stats.failed > 0) {
+      logger.error({
+        message: '[action-name]-queue-failed',
+        error: stats.errors[0]?.error?.message,
+      });
+    }
+  }
+);
+```
+
+### C. Bulk publish (build array then publish once)
+
+```javascript
+// Build all payloads first, then publish in one call.
+// publish() handles the SQS 10-message batch limit automatically.
+
+const payloads = items.map(item =>
+  JSON.stringify({ type: '[event-type]', data: item })
+);
+
+logger.info({ message: `${name}-publishing`, count: payloads.length });
+
+const stats = await sqs.publish(payloads);
+
+logger.info({
+  message: `${name}-complete`,
+  published: stats.published,
+  failed: stats.failed,
+});
+
+if (stats.failed > 0) {
+  // Log each failed payload for investigation
+  for (const { payload, error } of stats.errors) {
+    logger.error({
+      message: `${name}-payload-failed`,
+      payload,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+```
+
+---
+
+### Step 4.1: Update Action Configuration
+
+Add AWS credentials to the action's YAML configuration:
+
+**In `app.config.yaml`, `ext.config.yaml`, or `actions.config.yaml`:**
+
+```yaml
+[action-name]:
+  function: actions/[action-name]/index.[js/ts]
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    AWS_REGION: $AWS_REGION
+    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
+    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
+    AWS_SQS_URL: $AWS_SQS_URL
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+### Step 4.2: Add Environment Variables
+
+```bash
+# Amazon SQS
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key-id
+AWS_SECRET_ACCESS_KEY=your-secret-access-key
+AWS_SQS_URL=https://sqs.us-east-1.amazonaws.com/123456789012/your-queue-name
+# For FIFO queues: https://sqs.us-east-1.amazonaws.com/123456789012/your-queue.fifo
+```
+
+**Where to find AWS credentials:**
+1. Open [AWS IAM Console](https://console.aws.amazon.com/iam/)
+2. Create or select an IAM user with `sqs:SendMessage` permission on the target queue
+3. Under **Security credentials** → **Access keys** → create an access key
+
+---
+
+## Key Components
+
+### `AmazonSQSClient` constructor
+
+```typescript
+new AmazonSQSClient({
+  region: string,              // AWS region — e.g. 'us-east-1'
+  accessKeyId: string,         // IAM access key ID
+  secretAccessKey: string,     // IAM secret access key
+  queueUrl: string,            // full SQS queue URL
+  visibilityTimeout?: number,  // default: 30s — only relevant for consumers
+  waitTimeSeconds?: number,    // default: 0 — only relevant for consumers
+  messageGroupId?: string,     // default: 'default' — FIFO queues only
+})
+```
+
+### `publish(payloads)` — send messages
+
+```typescript
+async publish(payloads: string[]): Promise<PublishStats>
+// payloads: array of raw string message bodies (JSON.stringify your objects)
+// Returns PublishStats — NEVER throws; all failures returned in stats.errors
+```
+
+**`PublishStats` shape:**
+```javascript
+{
+  published: number,   // messages successfully accepted by SQS
+  failed: number,      // messages rejected or that errored
+  errors: [
+    { payload: string, error: Error },  // one per failure
+    ...
+  ]
+}
+```
+
+**Key behaviours:**
+- Automatically chunks payloads into batches of ≤10 (SQS hard limit per `SendMessageBatch`)
+- FIFO: auto-stamps `MessageGroupId` + unique `MessageDeduplicationId` per entry when `queueUrl` ends in `.fifo`
+- Never throws — check `stats.failed > 0` after every call
+
+### Exports
+
+```javascript
+const { AmazonSQSClient } = require('@adobe-commerce/aio-toolkit');
+
+// TypeScript only
+import type {
+  AmazonSQSConfig,
+  AmazonSQSPublishStats,
+} from '@adobe-commerce/aio-toolkit';
+```
+
+---
+
+## Important Notes
+
+1. **`publish()` never throws**: All failures — including network/transport errors — are returned in `stats.errors`. Always check `stats.failed > 0` after calling publish.
+2. **Payloads must be strings**: Serialize objects with `JSON.stringify()` before passing to `publish()`. The consumer is responsible for `JSON.parse()`.
+3. **Batching is automatic**: Pass the full array at once — `publish()` handles the SQS 10-per-batch constraint internally. Do not pre-chunk manually.
+4. **FIFO deduplication is automatic**: Each entry gets a unique `MessageDeduplicationId` (randomUUID). No extra config needed — just use a `.fifo` queue URL.
+5. **`@aws-sdk/client-sqs` is a required peer dep**: Must be installed separately — it is not bundled with `@adobe-commerce/aio-toolkit`.
+6. **Queue must exist**: `AmazonSQSClient` never creates queues. Ensure the queue exists in AWS before deploying.
+7. **IAM permissions required**: The IAM user must have `sqs:SendMessage` (and `sqs:SendMessageBatch`) on the target queue.
+8. **Works with any action type**: RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction.
+
+---
+
+## Related Rules
+
+- **"Create Amazon SQS Consumer"** (`aio-toolkit-create-amazon-sqs-consumer.md`) — use when you also need to consume (pull + process) messages from the queue; creates the scheduler + worker pair
+
+## Integration with Action Creation Rules
+
+**This rule should be triggered when developers mention SQS message publishing during action creation:**
+
+### Trigger Patterns in Other Rules
+
+When developers mention these phrases during action creation:
+
+- "Publish to SQS after processing"
+- "Queue work to Amazon SQS"
+- "Fan-out to SQS queue"
+- "Send messages to SQS"
+- Any phrase containing "SQS" + "publish"/"send"/"queue"/"write"
+
+**Action to take:**
+
+1. Complete the action creation first
+2. Inform the user: "I see you need to publish messages to Amazon SQS. Let me integrate AmazonSQSClient.publish()."
+3. Trigger/reference the "Using Amazon SQS — Publish" rule
+4. This rule handles client construction, payload serialisation, stats checking, config wiring, and env setup
+
+**Example Flow:**
+
+```
+User: "Create an event consumer action that receives an order.created event and queues it to SQS"
+AI: ✓ Detected TypeScript project
+AI: Creating EventConsumerAction... [generates .ts file]
+AI: I see you need to publish messages to Amazon SQS. Let me integrate AmazonSQSClient.publish().
+AI: [Adds SQS client, payload building, publish call, stats check, config inputs, and .env entries]
+```