@adobe-commerce/aio-toolkit 1.2.4 → 1.2.6

package/files/cursor-context/rules/aio-toolkit-use-adobe-auth.mdc

@@ -0,0 +1,442 @@
+---
+description: Using AdobeAuth to generate IMS bearer tokens in Adobe I/O Runtime actions using @adobe-commerce/aio-toolkit
+globs: '**/{actions,lib}/**/*.{ts,js}'
+alwaysApply: false
+---
+
+# Using AdobeAuth
+
+## Trigger Conditions
+
+This rule applies when the user needs to generate an IMS bearer token using explicit OAuth Server-to-Server credentials with any of these phrases:
+
+- "Get IMS token"
+- "Generate IMS bearer token"
+- "Use AdobeAuth"
+- "OAuth S2S authentication"
+- "S2S token for [service]"
+- "Technical account credentials"
+- "Service account token"
+- "IMS credentials for [action-name]"
+- "Authenticate with Adobe IMS"
+- "Generate access token for Commerce / PublishEvent / API Gateway"
+- "AdobeAuth.getToken"
+
+**Important**: This rule integrates `AdobeAuth` into an existing action. It does NOT create new actions.
+
+**When to use `AdobeAuth` vs `Core.AuthClient`**:
+
+| Scenario | Use |
+|---|---|
+| Action already has `include-ims-credentials: true` and only needs its own App Builder token | `Core.AuthClient.generateAccessToken(params)` — simpler, no extra env vars |
+| Action needs a token from **separate, explicitly stored** S2S credentials (dedicated technical account per integration) | `AdobeAuth.getToken()` — reads credentials from `params` env vars |
+| Multiple actions share a single dedicated technical account | `AdobeAuth.getToken()` — credentials stored once in `.env`, injected via `inputs` |
+| Calling `ImsConnection` for `AdobeCommerceClient` with a dedicated Commerce technical account | `AdobeAuth.getToken()` |
+| Calling `PublishEvent` with a dedicated Events technical account | `AdobeAuth.getToken()` |
+| Calling `RuntimeApiGatewayService` with a shared org-level account | `AdobeAuth.getToken()` |
+
+**Integration with Other Rules:**
+
+When using action creation rules (RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction) and the developer mentions needing S2S authentication or explicit IMS credentials:
+
+- **Automatically trigger this rule** after the action is created
+- This rule handles credential injection, scope selection, error handling, and caching guidance
+
+---
+
+## Step 1: Confirm Prerequisites
+
+Before generating code, confirm:
+
+1. **`@adobe-commerce/aio-toolkit` installed**: Check `package.json` — `AdobeAuth` is exported from it
+   - If NOT installed: `npm install @adobe-commerce/aio-toolkit`
+
+2. **Credentials available**: The user must have an **OAuth Server-to-Server** credential in Adobe Developer Console with the required scopes already granted
+   - Scopes are configured when the credential is created — `AdobeAuth.getToken()` cannot request scopes that were not granted
+
+---
+
+## Step 2: Ask Clarifying Questions
+
+Ask the following before generating any code:
+
+1. **What consumes the token?**
+   - [ ] `ImsConnection` for `AdobeCommerceClient`
+   - [ ] `PublishEvent` for Adobe I/O Events
+   - [ ] `RuntimeApiGatewayService` for web action calls
+   - [ ] A custom Adobe API call (specify which)
+
+2. **Do you already have separate IMS credentials (Client ID, Client Secret, Technical Account ID/Email, IMS Org ID)?**
+   - If NO: suggest using `Core.AuthClient.generateAccessToken(params)` with `include-ims-credentials: true` instead (no extra credentials needed)
+   - If YES: proceed with `AdobeAuth.getToken()`
+
+3. **Which OAuth scopes are needed?** (see scope reference below — suggest based on the consumer)
+   - `ImsConnection` / Commerce → `['AdobeID', 'openid', 'adobeio_api']`
+   - `PublishEvent` → `['AdobeID', 'openid', 'adobeio_api', 'event_receiver_api']`
+   - `RuntimeApiGatewayService` → `['openid', 'AdobeID', 'adobeio_api']`
+
+4. **High-frequency action?** If the action is invoked frequently (>10x/min), recommend caching the token using AIO State — `AdobeAuth.getToken()` makes a live IMS network call every invocation.
+
+5. **Which action file(s) should `AdobeAuth` be added to?** (if not already clear from context)
+
+---
+
+## 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 AdobeAuth from @adobe-commerce/aio-toolkit
+   - Add AdobeAuth.getToken() call [with try/catch for error handling]
+   - [Pass token to: ImsConnection / PublishEvent / RuntimeApiGatewayService / custom]
+   [If caching: Import BearerToken and add TTL-based cache check]
+
+2. app.config.yaml (or ext.config.yaml / actions.config.yaml):
+   - Add IMS credential inputs: IMS_CLIENT_ID, IMS_CLIENT_SECRET,
+     IMS_TECHNICAL_ACCOUNT_ID, IMS_TECHNICAL_ACCOUNT_EMAIL, IMS_ORG_ID
+
+3. .env:
+   - Add IMS_CLIENT_ID, IMS_CLIENT_SECRET, IMS_TECHNICAL_ACCOUNT_ID,
+     IMS_TECHNICAL_ACCOUNT_EMAIL, IMS_ORG_ID
+
+Scopes to request: [list based on consumer]
+
+Shall I proceed?
+```
+
+---
+
+## Step 4: Generate Code
+
+### Step 4.1: Action Code
+
+Detect language (TypeScript or JavaScript) by checking the action file extension or `tsconfig.json`. Generate in the detected language.
+
+#### A. Basic usage — with error handling (recommended)
+
+```javascript
+const {
+  AdobeAuth,
+  // ... other imports
+} = require('@adobe-commerce/aio-toolkit');
+
+// Inside your action handler (params, ctx):
+const { logger, telemetry } = ctx;
+
+let imsToken;
+
+try {
+  imsToken = await AdobeAuth.getToken(
+    params.IMS_CLIENT_ID,
+    params.IMS_CLIENT_SECRET,
+    params.IMS_TECHNICAL_ACCOUNT_ID,
+    params.IMS_TECHNICAL_ACCOUNT_EMAIL,
+    params.IMS_ORG_ID,
+    ['AdobeID', 'openid', 'adobeio_api']  // adjust scopes to your integration
+  );
+} catch (error) {
+  logger.error({
+    message: '[action-name]-ims-token-failed',
+    ...telemetry.formatError(error),
+  });
+  return RuntimeActionResponse.error(401, 'Failed to generate IMS token');
+}
+
+// Pass imsToken to your consumer:
+// const connection = new ImsConnection(imsToken, logger);
+// const publisher = new PublishEvent(params.IMS_ORG_ID, params.API_KEY, imsToken, logger);
+// const service = new RuntimeApiGatewayService(params.NAMESPACE, params.IMS_ORG_ID, imsToken, logger);
+```
+
+**TypeScript imports:**
+
+```typescript
+import { AdobeAuth } from '@adobe-commerce/aio-toolkit';
+```
+
+#### B. With ImsConnection for AdobeCommerceClient
+
+```javascript
+const {
+  AdobeAuth,
+  AdobeCommerceClient,
+  ImsConnection,
+} = require('@adobe-commerce/aio-toolkit');
+
+let imsToken;
+
+try {
+  imsToken = await AdobeAuth.getToken(
+    params.IMS_CLIENT_ID,
+    params.IMS_CLIENT_SECRET,
+    params.IMS_TECHNICAL_ACCOUNT_ID,
+    params.IMS_TECHNICAL_ACCOUNT_EMAIL,
+    params.IMS_ORG_ID,
+    ['AdobeID', 'openid', 'adobeio_api']
+  );
+} catch (error) {
+  logger.error({ message: '[action-name]-ims-token-failed', ...telemetry.formatError(error) });
+  return RuntimeActionResponse.error(401, 'Failed to generate IMS token');
+}
+
+const client = new AdobeCommerceClient(
+  params.COMMERCE_BASE_URL,
+  new ImsConnection(imsToken, logger),
+  logger
+);
+```
+
+#### C. With PublishEvent for Adobe I/O Events
+
+```javascript
+const {
+  AdobeAuth,
+  PublishEvent,
+} = require('@adobe-commerce/aio-toolkit');
+
+let imsToken;
+
+try {
+  imsToken = await AdobeAuth.getToken(
+    params.IMS_CLIENT_ID,
+    params.IMS_CLIENT_SECRET,
+    params.IMS_TECHNICAL_ACCOUNT_ID,
+    params.IMS_TECHNICAL_ACCOUNT_EMAIL,
+    params.IMS_ORG_ID,
+    ['AdobeID', 'openid', 'adobeio_api', 'event_receiver_api']
+  );
+} catch (error) {
+  logger.error({ message: '[action-name]-ims-token-failed', ...telemetry.formatError(error) });
+  return RuntimeActionResponse.error(401, 'Failed to generate IMS token');
+}
+
+const publisher = new PublishEvent(
+  params.IMS_ORG_ID,
+  params.API_KEY,
+  imsToken,
+  logger
+);
+```
+
+#### D. With token caching (high-frequency actions)
+
+Use this pattern when the action is invoked frequently and you want to avoid a live IMS call every invocation. Cache the token in Adobe I/O State with a TTL matching the token's expiry.
+
+```javascript
+const {
+  AdobeAuth,
+  BearerToken,
+} = require('@adobe-commerce/aio-toolkit');
+const { Files, State } = require('@adobe/aio-sdk');
+
+// Module-level cache (valid for container lifetime only — not reliable across invocations)
+let cachedToken = null;
+
+// Inside your action handler:
+let imsToken;
+
+// Check in-memory cache first (fast path for warm containers)
+if (cachedToken && BearerToken.info(cachedToken).isValid) {
+  imsToken = cachedToken;
+} else {
+  // Fall back to AIO State for cross-invocation persistence
+  const state = await State.init();
+  const cached = await state.get('ims-token');
+
+  if (cached && BearerToken.info(cached.value).isValid) {
+    imsToken = cached.value;
+    cachedToken = imsToken;
+  } else {
+    try {
+      imsToken = await AdobeAuth.getToken(
+        params.IMS_CLIENT_ID,
+        params.IMS_CLIENT_SECRET,
+        params.IMS_TECHNICAL_ACCOUNT_ID,
+        params.IMS_TECHNICAL_ACCOUNT_EMAIL,
+        params.IMS_ORG_ID,
+        ['AdobeID', 'openid', 'adobeio_api']
+      );
+    } catch (error) {
+      logger.error({ message: '[action-name]-ims-token-failed', ...telemetry.formatError(error) });
+      return RuntimeActionResponse.error(401, 'Failed to generate IMS token');
+    }
+
+    const { timeUntilExpiry } = BearerToken.info(imsToken);
+    const ttl = timeUntilExpiry ? Math.floor(timeUntilExpiry / 1000) - 60 : 3000; // 60s safety margin
+
+    await state.put('ims-token', imsToken, { ttl });
+    cachedToken = imsToken;
+  }
+}
+```
+
+> **Caching note:** `AdobeAuth.getToken()` makes a **live IMS network call every invocation** — it has no built-in caching. If your action is called frequently, use the pattern above or implement your own TTL-based cache using Adobe I/O State.
+
+---
+
+### Step 4.2: Update Action Configuration
+
+Add IMS credential inputs 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
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    # IMS S2S credentials
+    IMS_CLIENT_ID: $IMS_CLIENT_ID
+    IMS_CLIENT_SECRET: $IMS_CLIENT_SECRET
+    IMS_TECHNICAL_ACCOUNT_ID: $IMS_TECHNICAL_ACCOUNT_ID
+    IMS_TECHNICAL_ACCOUNT_EMAIL: $IMS_TECHNICAL_ACCOUNT_EMAIL
+    IMS_ORG_ID: $IMS_ORG_ID
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+> **Note:** `include-ims-credentials: true` is **NOT required** when using `AdobeAuth.getToken()`. That annotation is only needed for `Core.AuthClient.generateAccessToken(params)`. `AdobeAuth` reads credentials from the standard `inputs` you define above.
+
+---
+
+### Step 4.3: Add Environment Variables
+
+Add to the project's `.env` file:
+
+```bash
+# IMS OAuth S2S credentials — from Adobe Developer Console → OAuth Server-to-Server
+IMS_CLIENT_ID=your-client-id
+IMS_CLIENT_SECRET=your-client-secret
+IMS_TECHNICAL_ACCOUNT_ID=XXXXXXXXXXXXXXXX@techacct.adobe.com
+IMS_TECHNICAL_ACCOUNT_EMAIL=techacct@your-org.adobe.com
+IMS_ORG_ID=XXXXXXXXXXXXXXXX@AdobeOrg
+```
+
+**Where to find credentials:**
+1. Open [Adobe Developer Console](https://developer.adobe.com/console)
+2. Select your **Project** → **Workspace** (e.g. Production, Stage)
+3. Go to **OAuth Server-to-Server** under the credentials section
+4. Copy: **Client ID**, **Client Secret**, **Technical Account ID**, **Technical Account Email**, **IMS Org ID**
+5. Verify the listed **Scopes** include everything you intend to request
+
+---
+
+## OAuth Scopes Reference
+
+Request only the scopes your integration actually needs. Scopes must be a subset of those granted to the credential in Adobe Developer Console.
+
+| Scope | Purpose |
+|---|---|
+| `AdobeID` | Basic Adobe identity — required for most integrations |
+| `openid` | OpenID Connect identity token |
+| `adobeio_api` | Access to Adobe I/O APIs |
+| `event_receiver_api` | Publish and consume Adobe I/O Events (required for `PublishEvent`) |
+| `adobeio.appregistry.read` | Read App Registry entries |
+| `read_organizations` | Read IMS organization details |
+| `additional_info.projectedProductContext` | Access product context in the token |
+
+**Recommended scopes by consumer:**
+
+| Consumer | Minimum recommended scopes |
+|---|---|
+| `ImsConnection` (AdobeCommerceClient) | `['AdobeID', 'openid', 'adobeio_api']` |
+| `PublishEvent` | `['AdobeID', 'openid', 'adobeio_api', 'event_receiver_api']` |
+| `RuntimeApiGatewayService` | `['openid', 'AdobeID', 'adobeio_api']` |
+| Custom Adobe I/O API | `['AdobeID', 'openid', 'adobeio_api']` + any API-specific scope |
+
+---
+
+## Key Components
+
+### `AdobeAuth.getToken()` — generate IMS token
+
+```typescript
+static async getToken(
+  clientId: string,              // OAuth S2S Client ID
+  clientSecret: string,          // OAuth S2S Client Secret
+  technicalAccountId: string,    // Technical Account ID (XXXXXXXX@techacct.adobe.com)
+  technicalAccountEmail: string, // Technical Account Email
+  imsOrgId: string,              // IMS Org ID (XXXXXXXX@AdobeOrg)
+  scopes: string[],              // OAuth scopes — must be granted to the credential
+  currentContext?: string        // optional, default: 'onboarding-config'
+): Promise<string>               // returns raw IMS access token string
+```
+
+- **Throws** on invalid credentials, network failure, or unauthorized scopes — always wrap in `try/catch`
+- **No caching** — makes a live IMS network call every invocation
+- `currentContext` only needs to be overridden when managing multiple concurrent IMS contexts in the same process
+
+### `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
+```
+
+### Exports
+
+```javascript
+const { AdobeAuth, BearerToken } = require('@adobe-commerce/aio-toolkit');
+
+// TypeScript only
+import type { AdobeIMSConfig } from '@adobe-commerce/aio-toolkit';
+```
+
+---
+
+## Important Notes
+
+1. **`AdobeAuth.getToken()` throws — always use try/catch**: Invalid credentials, network failures, and unauthorized scopes all propagate directly. Return a clean error response rather than letting the action crash.
+2. **No built-in caching**: Every call makes a live round-trip to Adobe IMS. For high-frequency actions, implement TTL-based caching using AIO State + `BearerToken.info()`.
+3. **`include-ims-credentials: true` is NOT needed**: That annotation is for `Core.AuthClient.generateAccessToken(params)` only. `AdobeAuth` reads from standard `inputs` you define in YAML.
+4. **Scopes must be pre-granted**: You cannot request scopes at runtime that were not granted when the OAuth S2S credential was created in Adobe Developer Console.
+5. **`currentContext` param**: Only override the default `'onboarding-config'` context if you need to manage multiple concurrent IMS contexts in the same process (rare).
+6. **One token per consumer**: If an action uses both `ImsConnection` and `PublishEvent`, you may use the same token if the scopes cover both — or generate separate tokens if the credentials differ.
+7. **Credential security**: Never commit `.env` to version control — confirm `.env` is in `.gitignore`. `IMS_CLIENT_SECRET` is a secret and must be treated accordingly.
+8. **Works with any action type**: RuntimeAction, WebhookAction, EventConsumerAction, GraphQlAction, OpenwhiskAction.
+
+---
+
+## Related Rules
+
+- **"Creating Adobe Commerce Client Operations"** (`aio-toolkit-create-adobe-commerce-client.mdc`) — uses `AdobeAuth.getToken()` to obtain a token for `ImsConnection`
+- **"Using PublishEvent"** (`aio-toolkit-use-publish-event.mdc`) — uses `Core.AuthClient` by default; use `AdobeAuth.getToken()` instead when publishing with explicit S2S credentials
+- **"Using RuntimeApiGatewayService"** (`aio-toolkit-use-runtime-api-gateway-service.mdc`) — uses `AdobeAuth.getToken()` as the primary token source for API Gateway calls
+
+## Integration with Action Creation Rules
+
+**This rule should be triggered when developers mention needing IMS token generation with explicit S2S credentials:**
+
+### Trigger Patterns in Other Rules
+
+When developers mention these phrases during action creation:
+
+- "Generate an IMS token"
+- "Authenticate with Adobe IMS"
+- "Need an IMS bearer token for [service]"
+- "Use my technical account credentials"
+- "OAuth S2S token"
+- Any phrase containing "AdobeAuth" or "IMS token" + "S2S"/"technical account"/"credentials"
+
+**Action to take:**
+
+1. Determine if `Core.AuthClient.generateAccessToken(params)` covers the use case first
+2. If the user has explicit S2S credentials or needs a dedicated technical account: apply this rule
+3. This rule handles credential injection, scope selection, error handling, caching, and config wiring
+
+**Example Flow:**
+
+```
+User: "Create a runtime action that fetches products from Commerce using our technical account"
+AI: ✓ Detected TypeScript project
+AI: Creating runtime action... [generates .ts file]
+AI: I see you need IMS token generation with explicit S2S credentials. Let me integrate AdobeAuth.
+AI: [Adds AdobeAuth.getToken(), ImsConnection, config inputs, and .env entries]
+```