@adobe-commerce/aio-toolkit 1.2.4 → 1.2.6

package/files/cursor-context/rules/aio-toolkit-use-runtime-api-gateway-service.mdc

@@ -0,0 +1,542 @@
+---
+description: Adding RuntimeApiGatewayService to Adobe I/O Runtime actions using @adobe-commerce/aio-toolkit
+globs: '**/{actions,lib}/**/*.{ts,js}'
+alwaysApply: false
+---
+
+# Using RuntimeApiGatewayService
+
+## Trigger Conditions
+
+This rule applies when the user requests to call a web-exposed Adobe I/O Runtime action from within another action using any of these phrases:
+
+- "Call a web action from another action"
+- "Invoke action via API Gateway"
+- "HTTP call to a Runtime action"
+- "Use RuntimeApiGatewayService"
+- "Call another action over HTTP"
+- "Orchestrate actions via API Gateway"
+- "Call [action-name] from [action-name]"
+- "Add API Gateway client to [action-name]"
+- "Invoke a web action with IMS auth"
+- "Call Runtime endpoint from my action"
+
+**Important**: This rule does NOT create new actions. It integrates `RuntimeApiGatewayService` into existing actions only.
+
+**Integration with Other Action Creation Rules:**
+
+When using action creation rules (RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction) and the developer mentions calling another web action or API Gateway endpoint in the business logic:
+
+- **Automatically trigger this rule** after the action is created
+- Examples: "call the product-service action", "invoke another web action", "call action via API Gateway", "HTTP request to runtime endpoint"
+- This rule handles service construction, token generation, response handling, and config wiring
+
+**RuntimeApiGatewayService vs the Openwhisk client:**
+
+Both call one action from another — choose based on what the target action looks like:
+
+| | `Openwhisk` client | `RuntimeApiGatewayService` |
+|---|---|---|
+| Protocol | OpenWhisk API (internal) | HTTP via API Gateway |
+| Target must be `web: 'yes'` | No | Yes |
+| Auth | `API_HOST` + `API_AUTH` (auto-injected) | IMS Bearer token (must be generated) |
+| Returns | Full activation result | Raw `node-fetch` Response |
+| Blocking / non-blocking | Configurable | Always async HTTP |
+| Token management | None needed | Must generate + optionally cache |
+| Best for | Internal sub-actions, fan-out pipelines | Web actions, HTTP-level response control |
+
+**Use `RuntimeApiGatewayService` when:**
+- The target action is `web: 'yes'`
+- You need full HTTP response control (`response.ok`, headers, status codes)
+- The target is in a different namespace
+- You need IMS-authenticated HTTP calls to public endpoints
+
+**Use `Openwhisk` client when:**
+- The target action is `web: 'no'` (internal)
+- You need blocking/non-blocking control
+- You're routing within the same namespace
+- Simplicity matters more than HTTP-level control
+
+---
+
+## Step 1: Verify Prerequisites
+
+Before proceeding, verify:
+
+1. **Toolkit installed**: Check `@adobe-commerce/aio-toolkit` in `package.json`
+   - If NOT installed: `npm install @adobe-commerce/aio-toolkit`
+
+2. **Detect Language (TypeScript vs JavaScript)**:
+
+   **Check for TypeScript indicators (check ALL of these)**:
+   1. **Package Dependencies**: Look for `typescript` in `package.json` dependencies or devDependencies
+   2. **Config File**: Check if `tsconfig.json` exists in project root
+   3. **TypeScript Loaders**: Look for `ts-loader`, `ts-node`, or `@types/*` packages
+   4. **Existing Files**: Check for `.ts` files in `actions/` or `lib/`
+
+   **Detection Logic**:
+   - **TypeScript** if: `typescript` + `tsconfig.json` exist, OR 2+ indicators found, OR `.ts` files in `actions/`/`lib/`
+   - **Otherwise**: JavaScript
+
+3. **Detect Project Structure**:
+   - Check `app.config.yaml` for `application:` (root actions) or `extensions:` (extension points)
+
+4. **Check Existing Actions**: List all actions from `actions/` and `[extension-path]/actions/`
+   - If NO actions exist: stop and recommend creating an action first
+
+5. Only proceed to Step 2 after confirming all prerequisites
+
+---
+
+## Step 2: Ask Required Questions
+
+Before generating any code, ask the user:
+
+**Important**: Do not make assumptions — clarify all details before writing code.
+
+1. **Target Action**: Which existing action should receive the `RuntimeApiGatewayService` integration?
+   - List discovered actions for the user to choose from
+
+2. **Endpoint(s) to Call**: What API Gateway endpoint(s) will this action call?
+   - Format: `v1/web/{package}/{action-name}` (e.g. `v1/web/my-package/process-order`)
+   - Note: The namespace is handled automatically — only provide the path after it
+
+3. **HTTP Method(s)**: Which HTTP methods are needed?
+   - GET (read data, no payload)
+   - POST (send payload, create/trigger)
+   - PUT (update with payload)
+   - DELETE (remove by path)
+   - Multiple methods if the action calls different endpoints differently
+
+4. **Payload Structure** (for POST / PUT only):
+   - What data is sent in the request body?
+   - Example: `{ orderId, customerId, action }`
+
+5. **Token Caching Strategy**: How should the IMS token be managed?
+   - **Simple** (default, recommended for low-volume actions): generate a fresh token on every invocation using `AdobeAuth.getToken()`
+   - **Cached** (recommended for high-frequency actions): check token validity with `BearerToken.info()` before generating; cache with a TTL in-memory or via an external store
+
+6. **Additional Headers** (optional): Does any call need custom headers beyond the defaults?
+   - Defaults: `Authorization`, `x-gw-ims-org-id`, `Content-Type: application/json`
+   - Examples: `x-request-id`, `x-correlation-id`, `x-custom-header`
+
+---
+
+## Step 3: Confirm Implementation Details
+
+After receiving answers to ALL questions, present a comprehensive summary and **wait for user confirmation** before proceeding to Step 4:
+
+---
+
+### 📋 RuntimeApiGatewayService Integration Summary
+
+**Target Action:** `[action-name]`
+**Action Path:** `[path to action file]`
+**Language:** [TypeScript/JavaScript] (auto-detected)
+
+**API Gateway Calls:**
+
+| Method | Endpoint | Payload |
+|---|---|---|
+| [GET/POST/PUT/DELETE] | `v1/web/[package]/[action]` | `{ [fields] }` or — |
+
+**Token Strategy:** [Simple (fresh per invocation) / Cached with BearerToken.info()]
+
+**URL Pattern:** `https://adobeioruntime.net/apis/{namespace}/v1/web/[package]/[action]`
+
+**Environment Variables:**
+
+```bash
+# RuntimeApiGatewayService — IMS credentials
+NAMESPACE=$AIO_runtime_namespace   # auto-available in App Builder
+IMS_ORG_ID=
+CLIENT_ID=
+CLIENT_SECRET=
+TECHNICAL_ACCOUNT_ID=
+TECHNICAL_ACCOUNT_EMAIL=
+```
+
+📍 **Source:** Adobe Developer Console → Your project → Credentials
+
+---
+
+### ✅ What Will Be Changed
+
+**1. Action Implementation**
+- ✏️ `[action-path]/index.[js/ts]`
+  - Import `RuntimeApiGatewayService`, `AdobeAuth` [, `BearerToken` if caching]
+  - Generate IMS token via `AdobeAuth.getToken()`
+  - Construct `new RuntimeApiGatewayService(params.NAMESPACE, params.IMS_ORG_ID, token, logger)`
+  - Call `service.[method](endpoint [, payload])` for each configured call
+  - Check `response.ok` and parse with `response.json()` / `response.text()`
+
+**2. Action Configuration**
+- ✏️ `app.config.yaml`, `ext.config.yaml`, or `actions.config.yaml`
+  - Add `NAMESPACE: $AIO_runtime_namespace`
+  - Add IMS credential inputs: `IMS_ORG_ID`, `CLIENT_ID`, `CLIENT_SECRET`, `TECHNICAL_ACCOUNT_ID`, `TECHNICAL_ACCOUNT_EMAIL`
+
+**3. Environment Variables**
+- 📄/✏️ `.env` (project root) — add placeholder variables if not already present
+
+---
+
+**Should I proceed with this implementation?**
+
+---
+
+## Step 4: Generate Implementation
+
+### Step 4.1: Update the Action Code
+
+#### Simple Pattern (fresh token per invocation)
+
+**JavaScript:**
+
+```javascript
+const {
+  RuntimeApiGatewayService,
+  AdobeAuth,
+} = require('@adobe-commerce/aio-toolkit');
+
+// Inside your action handler (params, ctx):
+const { logger } = ctx;
+
+// Step 1: Generate IMS access token
+const token = await AdobeAuth.getToken(
+  params.CLIENT_ID,
+  params.CLIENT_SECRET,
+  params.TECHNICAL_ACCOUNT_ID,
+  params.TECHNICAL_ACCOUNT_EMAIL,
+  params.IMS_ORG_ID,
+  ['openid', 'AdobeID', 'adobeio_api']
+);
+
+// Step 2: Construct the service
+const service = new RuntimeApiGatewayService(
+  params.NAMESPACE,
+  params.IMS_ORG_ID,
+  token,
+  logger   // optional: enables request/error logging
+);
+
+// Step 3: Make the call — method throws on network failure, so wrap in try/catch
+const response = await service.get('v1/web/[package]/[action]');
+
+// Step 4: Check HTTP result — response body is NOT auto-parsed
+if (!response.ok) {
+  const errorBody = await response.text();
+  logger.error({ message: '[action-name]-call-failed', status: response.status, errorBody });
+  return RuntimeActionResponse.error(response.status, `Downstream call failed: ${response.status}`);
+}
+
+const result = await response.json();
+logger.info({ message: '[action-name]-call-success' });
+```
+
+#### Simple Pattern — POST with payload
+
+```javascript
+const response = await service.post(
+  'v1/web/[package]/[action]',
+  { /* payload fields */ }
+);
+
+if (!response.ok) {
+  const errorBody = await response.text();
+  throw new Error(`POST failed ${response.status}: ${errorBody}`);
+}
+
+const result = await response.json();
+```
+
+#### Cached Token Pattern (recommended for high-frequency actions)
+
+```javascript
+const {
+  RuntimeApiGatewayService,
+  AdobeAuth,
+  BearerToken,
+} = require('@adobe-commerce/aio-toolkit');
+
+// Inside your action handler (params, ctx):
+const { logger } = ctx;
+
+// Check cache first (replace with your preferred cache — module-level Map, Redis, etc.)
+let token = tokenCache.get('ims_token');
+
+if (!token || !BearerToken.info(token).isValid) {
+  token = await AdobeAuth.getToken(
+    params.CLIENT_ID,
+    params.CLIENT_SECRET,
+    params.TECHNICAL_ACCOUNT_ID,
+    params.TECHNICAL_ACCOUNT_EMAIL,
+    params.IMS_ORG_ID,
+    ['openid', 'AdobeID', 'adobeio_api']
+  );
+
+  const tokenInfo = BearerToken.info(token);
+  if (tokenInfo.isValid && tokenInfo.timeUntilExpiry) {
+    // Cache with 10-minute safety buffer
+    const ttlMs = tokenInfo.timeUntilExpiry - 600_000;
+    tokenCache.set('ims_token', token, ttlMs);
+  }
+}
+
+const service = new RuntimeApiGatewayService(
+  params.NAMESPACE,
+  params.IMS_ORG_ID,
+  token,
+  logger
+);
+
+// Make calls as normal
+const response = await service.get('v1/web/[package]/[action]');
+```
+
+#### With additional headers
+
+```javascript
+// Override or extend default headers for a specific call
+const response = await service.get(
+  'v1/web/[package]/[action]',
+  { 'x-correlation-id': params.correlationId }
+);
+```
+
+**TypeScript:** Same with `import` syntax:
+```typescript
+import { RuntimeApiGatewayService, AdobeAuth, BearerToken } from '@adobe-commerce/aio-toolkit';
+```
+
+### Step 4.2: Update Action Configuration
+
+Add the required inputs to the action's YAML configuration:
+
+```yaml
+[action-name]:
+  function: [action-path]/index.[js/ts]
+  web: 'yes'  # or 'no' for event consumers / internal actions
+  runtime: nodejs:22
+  annotations:
+    require-adobe-auth: [true/false]
+    final: true
+  inputs:
+    LOG_LEVEL: debug
+    # RuntimeApiGatewayService inputs
+    NAMESPACE: $AIO_runtime_namespace   # auto-available — no .env entry needed
+    IMS_ORG_ID: $IMS_ORG_ID
+    CLIENT_ID: $CLIENT_ID
+    CLIENT_SECRET: $CLIENT_SECRET
+    TECHNICAL_ACCOUNT_ID: $TECHNICAL_ACCOUNT_ID
+    TECHNICAL_ACCOUNT_EMAIL: $TECHNICAL_ACCOUNT_EMAIL
+```
+
+> `$AIO_runtime_namespace` is automatically available in every App Builder project — it resolves to the current workspace namespace without any manual configuration. Do NOT add it to `.env`.
+
+### Step 4.3: Add Environment Variables
+
+Update the project root `.env` with credential placeholders (skip `NAMESPACE` — it's auto-provided):
+
+```bash
+# RuntimeApiGatewayService — IMS credentials
+IMS_ORG_ID=your-org@AdobeOrg
+CLIENT_ID=
+CLIENT_SECRET=
+TECHNICAL_ACCOUNT_ID=
+TECHNICAL_ACCOUNT_EMAIL=
+```
+
+**How to get credentials:**
+1. Log in to [Adobe Developer Console](https://developer.adobe.com/console)
+2. Open your App Builder project
+3. Go to **Credentials** → Service Account (OAuth S2S) or JWT
+4. Copy `Client ID` → `CLIENT_ID`, `Client Secret` → `CLIENT_SECRET`
+5. Copy `Technical Account ID` and `Technical Account Email`
+6. Copy `Organization ID` → `IMS_ORG_ID`
+
+**Security Notes:**
+- Never commit `.env` — confirm it is in `.gitignore`
+- `CLIENT_SECRET` is a secret — treat it with the same care as a password
+- Use different credentials per environment (dev / staging / production)
+
+---
+
+## Step 5: Recommendations
+
+### A. Response Handling Strategy
+
+`RuntimeApiGatewayService` methods throw on **network-level failure** but return normally for HTTP error status codes. Always check both:
+
+```javascript
+try {
+  const response = await service.post('v1/web/[package]/[action]', payload);
+
+  // HTTP-level check
+  if (!response.ok) {
+    const errorBody = await response.text();
+    logger.error({ message: '[action]-downstream-http-error', status: response.status, errorBody });
+    return RuntimeActionResponse.error(response.status, `Downstream action returned ${response.status}`);
+  }
+
+  const result = await response.json();
+  return RuntimeActionResponse.success(result);
+
+} catch (error) {
+  // Network/connection failure
+  logger.error({ message: '[action]-downstream-network-error', error: error.message });
+  return RuntimeActionResponse.error(HttpStatus.INTERNAL_ERROR, `Gateway call failed: ${error.message}`);
+}
+```
+
+### B. Token Caching Decision
+
+| Scenario | Strategy |
+|---|---|
+| Action invoked infrequently (< 1 req/min) | **Simple** — generate fresh token per invocation |
+| Action invoked frequently or in a loop | **Cached** — use `BearerToken.info()` + module-level cache |
+| Action runs in a stateful process | **Cached** — share token across invocations |
+
+> OpenWhisk actions are cold-started per request — module-level variables do NOT persist between invocations unless the same container is reused. For reliable caching, use an external store (`@adobe/aio-lib-state`, Redis, etc.).
+
+### C. No Retries or Timeouts
+
+`RuntimeApiGatewayService` has no built-in retry or timeout logic. For reliability-sensitive paths:
+
+```javascript
+// Simple retry with exponential backoff
+async function callWithRetry(service, endpoint, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const response = await service.get(endpoint);
+      if (response.ok) return response;
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      await new Promise(r => setTimeout(r, 2 ** i * 1000));
+    }
+  }
+}
+```
+
+### D. URL Construction
+
+Endpoint is appended as-is — no leading slash normalization:
+
+```javascript
+// ✅ Correct
+await service.get('v1/web/my-package/my-action');
+// → https://adobeioruntime.net/apis/{namespace}/v1/web/my-package/my-action
+
+// ⚠️ Extra leading slash produces double slash in URL
+await service.get('/v1/web/my-package/my-action');
+// → https://adobeioruntime.net/apis/{namespace}//v1/web/...
+```
+
+---
+
+## Key Components from @adobe-commerce/aio-toolkit
+
+### RuntimeApiGatewayService Constructor
+
+```typescript
+new RuntimeApiGatewayService(
+  namespace: string,   // Adobe I/O Runtime namespace — use params.NAMESPACE
+  imsOrgId: string,   // IMS Org ID — use params.IMS_ORG_ID
+  imsToken: string,   // Bearer token — from AdobeAuth.getToken()
+  logger?: any        // optional: enables request/error logging
+)
+```
+
+> **No constructor validation** — invalid credentials are only detected when the first request is made.
+
+### Methods (all return `Promise<Response>`)
+
+```typescript
+service.get(endpoint, additionalHeaders?)
+service.post(endpoint, payload, additionalHeaders?)
+service.put(endpoint, payload, additionalHeaders?)
+service.delete(endpoint, additionalHeaders?)
+```
+
+- All methods **throw** on network failure (after logging if a logger is provided)
+- All methods return the **raw `node-fetch` Response** — you must call `.json()` / `.text()` and check `response.ok`
+- `additionalHeaders` are merged after the defaults and can override `Authorization`, `x-gw-ims-org-id`, or `Content-Type`
+
+### Default Headers (sent on every request)
+
+```
+Authorization:    Bearer <imsToken>
+x-gw-ims-org-id: <imsOrgId>
+Content-Type:     application/json
+```
+
+### AdobeAuth.getToken() — generate IMS token
+
+```typescript
+const token = await AdobeAuth.getToken(
+  clientId,            // params.CLIENT_ID
+  clientSecret,        // params.CLIENT_SECRET
+  technicalAccountId,  // params.TECHNICAL_ACCOUNT_ID
+  technicalAccountEmail, // params.TECHNICAL_ACCOUNT_EMAIL
+  orgId,               // params.IMS_ORG_ID
+  scopes               // ['openid', 'AdobeID', 'adobeio_api']
+);
+```
+
+### BearerToken.info() — inspect token validity (for caching)
+
+```typescript
+const { isValid, timeUntilExpiry } = BearerToken.info(token);
+// isValid: boolean — false if expired or invalid
+// timeUntilExpiry: number (ms) — time until expiry; 0 or undefined if expired
+```
+
+---
+
+## Important Notes
+
+1. **No constructor validation**: Invalid credentials fail on first request, not at construction time — verify credentials are set before constructing
+2. **Raw Response returned**: Always call `.json()` or `.text()` and check `response.ok` — nothing is auto-parsed
+3. **Methods throw on network failure**: Wrap in try/catch to handle connection errors separately from HTTP errors
+4. **No built-in retries or timeouts**: Implement your own retry logic for reliability-sensitive paths
+5. **`NAMESPACE` is auto-provided**: `$AIO_runtime_namespace` is always available in App Builder — do not manually add it to `.env`
+6. **Token caching is application-level**: OpenWhisk containers may not persist module-level state — use external storage for reliable cross-invocation caching
+7. **Endpoint appended as-is**: No leading slash normalization — omit the leading `/` in endpoint strings
+8. **Additional headers override defaults**: Can override `Authorization`, `x-gw-ims-org-id`, and `Content-Type` per-request via `additionalHeaders`
+9. **vs Openwhisk client**: Use `RuntimeApiGatewayService` for `web: 'yes'` targets needing HTTP-level control; use `Openwhisk` client for `web: 'no'` internal actions
+10. **Works with any action type**: RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction
+
+## Integration with Action Creation Rules
+
+**This rule should be triggered when developers mention calling web actions in their business logic:**
+
+### Trigger Patterns in Other Rules
+
+When developers mention these phrases during action creation:
+
+- "Call the [action-name] action"
+- "Invoke web action from my action"
+- "HTTP request to another Runtime action"
+- "Call via API Gateway"
+- "Orchestrate actions with HTTP"
+- Any phrase involving "RuntimeApiGatewayService" or "API Gateway" + "call"/"invoke"/"request"
+
+**Action to take:**
+
+1. Complete the action creation first
+2. Inform the user: "I see you need to call a web action via API Gateway. Let me integrate RuntimeApiGatewayService."
+3. Trigger/reference the "Using RuntimeApiGatewayService" rule
+4. This rule handles token generation, service construction, response handling, and config wiring
+
+**Example Flow:**
+
+```
+User: "Create a runtime action that calls the product-service web action to fetch product data"
+AI: ✓ Detected TypeScript project
+AI: Creating runtime action... [generates .ts file]
+AI: I see you need to call a web action. Let me integrate RuntimeApiGatewayService.
+AI: [Adds token generation, service construction, GET call, response handling, and config inputs]
+```
+
+## Related Rules
+
+- **"Using AdobeAuth"** (`aio-toolkit-use-adobe-auth.mdc`) — primary reference for `AdobeAuth.getToken()` usage, caching patterns, scope selection, and error handling for the IMS token this service requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/aio-toolkit",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -22,7 +22,8 @@
   ],
   "bin": {
     "aio-toolkit-cursor-context": "dist/aio-toolkit-cursor-context/bin/cli.js",
-    "aio-toolkit-onboard-events": "dist/aio-toolkit-onboard-events/bin/cli.js"
+    "aio-toolkit-onboard-events": "dist/aio-toolkit-onboard-events/bin/cli.js",
+    "aio-toolkit-cli-workflow": "dist/aio-toolkit-cli-workflow/bin/cli.js"
   },
   "scripts": {
     "build": "tsup",
@@ -60,6 +61,7 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@adobe-commerce/aio-services-kit": "^1.0.0",
+    "@aws-sdk/client-sqs": "^3.1045.0",
     "amqplib": "^1.0.3",
     "cloudevents": "^8.0.2",
     "dotenv": "^17.3.1",