@adobe-commerce/aio-toolkit 1.2.5 → 1.2.7

package/files/cursor-context/commands/aio-toolkit-create-webhook-action.md

@@ -53,8 +53,7 @@ Ask the user:
 7. **Error Handling**
    - Specific error scenarios to handle
    - Example: Invalid signature, missing data, processing errors
-   - Note: WebhookActionResponse.exception() accepts optional message and exception class
-   - Default exception class (if not provided): `\\Magento\\Framework\\Exception\\LocalizedException`
+   - Note: WebhookActionResponse.exception() accepts optional message and exception type
 
 8. **Business Logic Description**
    - Brief description of what the webhook should do
@@ -141,7 +140,7 @@ exports.main = WebhookAction.execute(
       return WebhookActionResponse.success();
     } catch (error) {
       logger.error({ message: `${name}-error`, error: error.message, stack: error.stack });
-      // Optional parameters: message and exceptionClass
+      // Optional parameters: message and exceptionType
       return WebhookActionResponse.exception(
         `Failed: ${error.message}`,
         '\\Magento\\Framework\\Exception\\LocalizedException'
@@ -183,6 +182,8 @@ application:
             annotations:
               require-adobe-auth: [true/false]
               final: true
+              # Required when signature verification is enabled:
+              raw-http: true
         # If API Gateway requested:
         apis:
           [action-name]:
@@ -219,7 +220,12 @@ If signature verification enabled:
    PUBLIC_KEY_BASE64="[your base64 encoded key]"
    ```
 
-3. **Security Notes:**
+3. **Ensure `raw-http: true` is set in `app.config.yaml`:**
+   - `raw-http: true` is **required** for signature verification to work
+   - Without it, `__ow_body` is never populated and signature verification always fails
+   - The annotation must be under `annotations:` in the action configuration
+
+4. **Security Notes:**
    - Never commit `.env` to version control
    - Add `.env` to `.gitignore`
    - Regenerate keys regularly
@@ -307,16 +313,16 @@ Returns:
 { "op": "success" }
 ```
 
-#### **exception(message?, exceptionClass?)** - Terminate Process
+#### **exception(message?, exceptionType?)** - Terminate Process
 
 Causes Commerce to terminate the process that triggered the original event. The exception is logged in Commerce's system.log.
 
 **Parameters:**
-- `message` (optional): Exception message. If not set, uses fallbackErrorMessage from config or system default
-- `exceptionClass` (optional): Exception class path. Default: `\\Magento\\Framework\\Exception\\LocalizedException`
+- `message` (optional): Exception message shown to the end user
+- `exceptionType` (optional): Fully qualified Magento exception class name (e.g., `\\Magento\\Framework\\Exception\\LocalizedException`). Only fields that are provided are included in the response.
 
 ```javascript
-// With custom message and class
+// With custom message and exception type
 return WebhookActionResponse.exception(
   'The product cannot be added to the cart because it is out of stock',
   'Path\\To\\Exception\\Class'
@@ -330,7 +336,7 @@ Returns:
 ```json
 {
   "op": "exception",
-  "class": "Path\\To\\Exception\\Class",
+  "type": "Path\\To\\Exception\\Class",
   "message": "The product cannot be added to the cart because it is out of stock"
 }
 ```
@@ -436,4 +442,11 @@ Returns:
 ### Related Rules
 
 - **Setting up New Relic Telemetry**: Add observability to your webhook action
+- **Using PublishEvent**: Publish CloudEvents to Adobe I/O Events from your webhook action
+- **Using RuntimeApiGatewayService**: Call another web-exposed Runtime action via API Gateway from your webhook
+- **Using FileRepository**: Persist and retrieve records using Adobe I/O Files storage from your webhook action
+- **Using AbdbCollection**: Add MongoDB-backed App Builder Data storage with schema validation to your webhook action
+- **Using AbdbRepository**: Add full CRUD operations (insert, find, update, delete, pagination) on top of an AbdbCollection in your webhook action
+- **Create Shipping Carrier**: If this webhook action handles Adobe Commerce OOPE shipping rates, use the `aio-toolkit-create-shipping-carrier` command instead — it generates both the carrier class (`lib/shipping-carriers/`) and the webhook action together, including optional Commerce OOPE API management methods
+- **Using Amazon SQS — Publish**: Publish messages to an Amazon SQS queue from your webhook action
 

package/files/cursor-context/rules/aio-toolkit-create-adobe-commerce-client.mdc

@@ -1,7 +1,7 @@
 ---
 description: Creating Adobe Commerce Client Operations using @adobe-commerce/aio-toolkit
 globs: '**/{actions,lib}/**/*.{ts,js},.env'
-alwaysApply: true
+alwaysApply: false
 ---
 
 # Creating Adobe Commerce Client Operations
@@ -27,7 +27,7 @@ This rule applies when the user requests to integrate Adobe Commerce API into th
 
 **Integration with Other Action Creation Rules**:
 
-When using action creation rules (RuntimeAction, WebhookAction, GraphQLAction, EventConsumerAction) and the developer mentions Commerce operations in the business logic:
+When using action creation rules (RuntimeAction, WebhookAction, GraphQLAction, EventConsumerAction, OpenwhiskAction) and the developer mentions Commerce operations in the business logic:
 
 - **Automatically trigger this rule** after the action is created
 - Examples of Commerce operations: "create product", "get customer", "update order", "call Commerce API", "fetch products from Commerce"
@@ -235,7 +235,8 @@ After receiving answers to ALL questions, present a comprehensive summary and **
 
 ```bash
 # Adobe Commerce REST API Configuration (OAuth 1.0a)
-COMMERCE_BASE_URL=https://your-commerce-store.com/rest
+# COMMERCE_BASE_URL is the store root — do NOT include /rest or /V1
+COMMERCE_BASE_URL=https://your-commerce-store.com
 COMMERCE_CONSUMER_KEY=
 COMMERCE_CONSUMER_SECRET=
 COMMERCE_ACCESS_TOKEN=
@@ -248,12 +249,13 @@ COMMERCE_ACCESS_TOKEN_SECRET=
 
 ```bash
 # Adobe Commerce REST API Configuration (IMS)
-COMMERCE_BASE_URL=https://your-commerce-cloud.adobe.com/rest
+# COMMERCE_BASE_URL is the store root — do NOT include /rest or /V1
+COMMERCE_BASE_URL=https://your-commerce-cloud.adobe.com
 IMS_CLIENT_ID=
 IMS_CLIENT_SECRET=
 IMS_TECHNICAL_ACCOUNT_ID=
 IMS_TECHNICAL_ACCOUNT_EMAIL=
-IMS_ORD_ID=
+IMS_ORG_ID=
 IMS_SCOPES=openid,AdobeID,read_organizations
 ```
 
@@ -263,7 +265,8 @@ IMS_SCOPES=openid,AdobeID,read_organizations
 
 ```bash
 # Adobe Commerce REST API Configuration (Basic Auth)
-COMMERCE_BASE_URL=https://your-commerce-store.com/rest
+# COMMERCE_BASE_URL is the store root — do NOT include /rest or /V1
+COMMERCE_BASE_URL=https://your-commerce-store.com
 COMMERCE_USERNAME=
 COMMERCE_PASSWORD=
 ```
@@ -409,7 +412,7 @@ class AdobeCommerceClientBuilder {
   /**
    * Initialize the client builder with OAuth 1.0a credentials
    *
-   * @param {string} commerceBaseUrl - Commerce REST API base URL (e.g., https://your-store.com/rest/V1)
+   * @param {string} commerceBaseUrl - Commerce store root URL (e.g., https://your-store.com) — do NOT include /rest or /V1
    * @param {string} commerceConsumerKey - OAuth consumer key from Commerce Admin
    * @param {string} commerceConsumerSecret - OAuth consumer secret from Commerce Admin
    * @param {string} commerceAccessToken - OAuth access token from Commerce Admin
@@ -452,8 +455,8 @@ class AdobeCommerceClientBuilder {
       this.commerceAccessTokenSecret
     );
 
-    // Create and cache the Commerce client
-    this.client = new AdobeCommerceClient(this.commerceBaseUrl, connection);
+    // Pass logger to the client so HTTP-level debug logs flow into telemetry automatically
+    this.client = new AdobeCommerceClient(this.commerceBaseUrl, connection, this.params.logger || null);
     return this.client;
   }
 }
@@ -504,7 +507,7 @@ class AdobeCommerceClientBuilder {
   /**
    * Initialize the client builder with IMS credentials
    *
-   * @param {string} commerceBaseUrl - Commerce REST API base URL (e.g., https://your-store.com/rest/V1)
+   * @param {string} commerceBaseUrl - Commerce store root URL (e.g., https://your-store.com) — do NOT include /rest or /V1
    * @param {string} imsClientId - IMS client ID from Adobe Developer Console
    * @param {string} imsClientSecret - IMS client secret from Adobe Developer Console
    * @param {string} imsTechnicalAccountId - IMS technical account ID
@@ -609,7 +612,7 @@ class AdobeCommerceClientBuilder {
   /**
    * Initialize the client builder with Basic Auth credentials
    *
-   * @param {string} commerceBaseUrl - Commerce REST API base URL (e.g., https://your-store.com/rest/V1)
+   * @param {string} commerceBaseUrl - Commerce store root URL (e.g., https://your-store.com)
    * @param {string} commerceUsername - Commerce admin username
    * @param {string} commercePassword - Commerce admin password
    */
@@ -636,8 +639,8 @@ class AdobeCommerceClientBuilder {
       return this.client;
     }
 
-    // Create Basic Auth connection
-    const connection = new BasicAuthConnection(this.commerceUsername, this.commercePassword);
+    // BasicAuthConnection requires baseUrl as its first argument so it can fetch the admin token
+    const connection = new BasicAuthConnection(this.commerceBaseUrl, this.commerceUsername, this.commercePassword);
 
     // Create and cache the Commerce client
     this.client = new AdobeCommerceClient(this.commerceBaseUrl, connection);
@@ -655,6 +658,86 @@ module.exports = AdobeCommerceClientBuilder;
 - Add return type `: AdobeCommerceClient` to `getClient()`
 - Use `export default` instead of `module.exports`
 
+#### Step 4.2b: Create Entity Class (Recommended for Domain-Specific APIs)
+
+For each Commerce domain area (e.g. `Countries`, `Products`, `Orders`), create a dedicated entity class in `lib/adobe-commerce/[entity-name]/`. This keeps the action thin, encapsulates the API calls and lazy init, and makes the class reusable across multiple actions.
+
+```
+lib/
+└── adobe-commerce/
+    ├── client-builder/
+    │   └── index.[js/ts]        ← wraps AdobeCommerceClient construction
+    └── [entity-name]/
+        └── index.[js/ts]        ← entity class (API calls + lazy client init)
+```
+
+**JavaScript entity class template:**
+
+```javascript
+// lib/adobe-commerce/[entity-name]/index.js
+const { AdobeCommerceClientBuilder } = require('@lib/adobe-commerce/client-builder');
+
+class [EntityName] {
+  constructor(params) {
+    this.params = params;
+    this.client = null;
+    this.clientInitPromise = null;
+  }
+
+  // Lazy init with concurrent-call guard — both callers share the same promise
+  async getClient() {
+    if (this.client) return this.client;
+    if (this.clientInitPromise) return this.clientInitPromise;
+
+    this.clientInitPromise = AdobeCommerceClientBuilder.generate({
+      commerceBaseUrl:          this.params.COMMERCE_BASE_URL,
+      oauthConsumerKey:         this.params.COMMERCE_CONSUMER_KEY,
+      oauthConsumerSecret:      this.params.COMMERCE_CONSUMER_SECRET,
+      oauthAccessToken:         this.params.COMMERCE_ACCESS_TOKEN,
+      oauthAccessTokenSecret:   this.params.COMMERCE_ACCESS_TOKEN_SECRET,
+      logger:                   this.params.logger || null,
+    });
+
+    this.client = await this.clientInitPromise;
+    this.clientInitPromise = null;
+    return this.client;
+  }
+
+  async fetch[EntityName]() {
+    const client = await this.getClient();
+    const result = await client.get('rest/V1/[endpoint]');
+
+    if (!result.success) {
+      return result;
+    }
+
+    // Transform result.message as needed
+    return { success: true, data: result.message };
+  }
+}
+
+module.exports = { [EntityName] };
+```
+
+**In the action — keeps the action thin:**
+
+```javascript
+const { [EntityName] } = require('@lib/adobe-commerce/[entity-name]');
+
+// Inside handler:
+const entityClient = new [EntityName](params);
+const result = await entityClient.fetch[EntityName]();
+
+if (!result.success) {
+  return RuntimeActionResponse.error(result.statusCode, result.message);
+}
+return RuntimeActionResponse.success(result.data);
+```
+
+> The entity class pattern is optional but strongly recommended when an action calls multiple endpoints on the same domain, or when the same domain is used across multiple actions.
+
+---
+
 #### Step 4.3: Integrate Commerce Client into Existing Action
 
 **Update the selected action to use the client builder:**
@@ -707,7 +790,7 @@ const clientBuilder = new AdobeCommerceClientBuilder(
   params.IMS_CLIENT_SECRET,
   params.IMS_TECHNICAL_ACCOUNT_ID,
   params.IMS_TECHNICAL_ACCOUNT_EMAIL,
-  params.IMS_ORD_ID,
+  params.IMS_ORG_ID,
   params.IMS_SCOPES // Comma-separated scopes
 );
 
@@ -849,7 +932,7 @@ const token = await AdobeAuth.getToken(
   params.IMS_CLIENT_SECRET,
   params.IMS_TECHNICAL_ACCOUNT_ID,
   params.IMS_TECHNICAL_ACCOUNT_EMAIL,
-  params.IMS_ORD_ID,
+  params.IMS_ORG_ID,
   params.IMS_SCOPES.split(',')
 );
 
@@ -901,8 +984,8 @@ await client.delete('customers/123');
 ```javascript
 const { AdobeCommerceClient, BasicAuthConnection } = require('@adobe-commerce/aio-toolkit');
 
-// Create Basic Auth connection
-const connection = new BasicAuthConnection(params.COMMERCE_USERNAME, params.COMMERCE_PASSWORD);
+// BasicAuthConnection requires baseUrl as first argument — it uses it to fetch the admin token
+const connection = new BasicAuthConnection(params.COMMERCE_BASE_URL, params.COMMERCE_USERNAME, params.COMMERCE_PASSWORD);
 
 // Create Commerce client
 const client = new AdobeCommerceClient(params.COMMERCE_BASE_URL, connection);
@@ -962,7 +1045,8 @@ const updatedOrder = await client.put(
 
 ```bash
 # Adobe Commerce REST API Configuration (OAuth 1.0a)
-COMMERCE_BASE_URL=https://your-commerce-store.com/rest/V1
+# Store root URL — do NOT include /rest or /V1 here
+COMMERCE_BASE_URL=https://your-commerce-store.com
 COMMERCE_CONSUMER_KEY=
 COMMERCE_CONSUMER_SECRET=
 COMMERCE_ACCESS_TOKEN=
@@ -983,12 +1067,13 @@ COMMERCE_ACCESS_TOKEN_SECRET=
 
 ```bash
 # Adobe Commerce REST API Configuration (IMS)
-COMMERCE_BASE_URL=https://your-commerce-cloud.adobe.com/rest/V1
+# Store root URL — do NOT include /rest or /V1 here
+COMMERCE_BASE_URL=https://your-commerce-cloud.adobe.com
 IMS_CLIENT_ID=
 IMS_CLIENT_SECRET=
 IMS_TECHNICAL_ACCOUNT_ID=
 IMS_TECHNICAL_ACCOUNT_EMAIL=
-IMS_ORD_ID=
+IMS_ORG_ID=
 IMS_SCOPES=openid,AdobeID,read_organizations
 ```
 
@@ -1007,7 +1092,8 @@ IMS_SCOPES=openid,AdobeID,read_organizations
 
 ```bash
 # Adobe Commerce REST API Configuration (Basic Auth)
-COMMERCE_BASE_URL=https://your-commerce-store.com/rest/V1
+# Store root URL — do NOT include /rest or /V1 here
+COMMERCE_BASE_URL=https://your-commerce-store.com
 COMMERCE_USERNAME=
 COMMERCE_PASSWORD=
 ```
@@ -1039,7 +1125,7 @@ inputs:
   LOG_LEVEL: debug
   COMMERCE_BASE_URL: $COMMERCE_BASE_URL
   # For OAuth: Add COMMERCE_CONSUMER_KEY, COMMERCE_CONSUMER_SECRET, COMMERCE_ACCESS_TOKEN, COMMERCE_ACCESS_TOKEN_SECRET
-  # For IMS: Add IMS_CLIENT_ID, IMS_CLIENT_SECRET, IMS_TECHNICAL_ACCOUNT_ID, IMS_TECHNICAL_ACCOUNT_EMAIL, IMS_ORD_ID, IMS_SCOPES
+  # For IMS: Add IMS_CLIENT_ID, IMS_CLIENT_SECRET, IMS_TECHNICAL_ACCOUNT_ID, IMS_TECHNICAL_ACCOUNT_EMAIL, IMS_ORG_ID, IMS_SCOPES
   # For Basic Auth: Add COMMERCE_USERNAME, COMMERCE_PASSWORD
 ```
 
@@ -1060,89 +1146,94 @@ inputs:
 
 ### AdobeCommerceClient Class
 
-Main class for interacting with Adobe Commerce REST API
+Main class for interacting with Adobe Commerce REST API. **Never throws** — all outcomes are returned as `{ success, ... }` objects.
+
+- **Constructor**: `new AdobeCommerceClient(baseUrl, connection, logger?, httpsOptions?)`
+  - `baseUrl`: Commerce store root URL (e.g. `https://your-store.com`) — **do not include `/rest`**; it is passed as Got's `prefixUrl`
+  - `connection`: Connection instance (`Oauth1aConnection`, `ImsConnection`, or `BasicAuthConnection`)
+  - `logger`: Optional logger instance — pass `ctx.logger` to get automatic HTTP-level debug logs in telemetry
+  - `httpsOptions`: Optional Got `https` options — use `{ rejectUnauthorized: false }` for self-signed certs (never in production)
+
+**URL construction rule**: `baseUrl` + endpoint are concatenated by Got. Do **not** include a leading slash in the endpoint. Query parameters go directly in the endpoint string:
+
+```javascript
+// Correct
+await client.get('rest/V1/products');
+await client.get('rest/V1/orders?searchCriteria[pageSize]=10&searchCriteria[currentPage]=1');
+
+// Wrong — leading slash breaks Got's prefixUrl resolution
+await client.get('/rest/V1/products');
+```
+
+**Response shape** — every method resolves with one of:
+
+```javascript
+// Success
+{ success: true, message: any }       // message = parsed JSON response body
 
-- **Purpose**: Provides methods to interact with Adobe Commerce REST API
-- **Constructor**: `new AdobeCommerceClient(baseUrl, connection)`
-  - `baseUrl`: Commerce REST API base URL (e.g., `https://your-store.com/rest/V1`)
-  - `connection`: Connection instance (Oauth1aConnection, ImsConnection, or BasicAuthConnection)
+// Failure
+{ success: false, statusCode: number, message: string, body?: any }
+// statusCode 500 for network/DNS failures; HTTP status for 4xx/5xx
+```
+
+Always check `result.success` — never wrap calls in try/catch for HTTP errors.
 
 **Available Methods:**
 
-#### get(endpoint, queryParams?)
+#### get(endpoint, headers?)
 
-Perform GET request to Commerce API
+```javascript
+async get(endpoint, headers = {})
+```
 
-- **Parameters**:
-  - `endpoint` (string): API endpoint path (e.g., `'products'`, `'products/SKU123'`)
-  - `queryParams` (object, optional): Query parameters for the request
-- **Returns**: Promise with response data
-- **Example**:
-  ```javascript
-  const products = await client.get('products');
-  const product = await client.get('products/SKU123');
-  const searchResults = await client.get('products', { searchCriteria: { pageSize: 10 } });
-  ```
+- `endpoint`: REST path (e.g. `'rest/V1/products/24'`). Append query string directly here.
+- `headers`: Additional request headers merged on top of client defaults.
 
-#### post(endpoint, queryParams?, body?)
+```javascript
+const result = await client.get('rest/V1/directory/countries');
+if (result.success) { /* result.message = parsed JSON array */ }
 
-Perform POST request to Commerce API
+// Query parameters in the endpoint string
+const result = await client.get('rest/V1/products?searchCriteria[pageSize]=10');
+```
 
-- **Parameters**:
-  - `endpoint` (string): API endpoint path
-  - `queryParams` (object, optional): Query parameters
-  - `body` (object, optional): Request body
-- **Returns**: Promise with response data
-- **Example**:
-  ```javascript
-  const newProduct = await client.post(
-    'products',
-    {},
-    {
-      product: {
-        sku: 'NEW-SKU',
-        name: 'New Product',
-        price: 99.99,
-      },
-    }
-  );
-  ```
+#### post(endpoint, headers?, payload?)
 
-#### put(endpoint, queryParams?, body?)
+```javascript
+async post(endpoint, headers = {}, payload = null)
+```
 
-Perform PUT request to Commerce API
+- `payload`: Serialised as JSON. `Content-Type: application/json` set automatically.
 
-- **Parameters**:
-  - `endpoint` (string): API endpoint path
-  - `queryParams` (object, optional): Query parameters
-  - `body` (object, optional): Request body
-- **Returns**: Promise with response data
-- **Example**:
-  ```javascript
-  const updated = await client.put(
-    'products/SKU123',
-    {},
-    {
-      product: {
-        name: 'Updated Name',
-        price: 89.99,
-      },
-    }
-  );
-  ```
+```javascript
+const result = await client.post('rest/V1/products', {}, {
+  product: { sku: 'MY-SKU', name: 'My Product', price: 29.99, status: 1, type_id: 'simple', attribute_set_id: 4 },
+});
+if (!result.success) { /* result.statusCode, result.message, result.body */ }
+```
 
-#### delete(endpoint, queryParams?)
+#### put(endpoint, headers?, payload?)
 
-Perform DELETE request to Commerce API
+```javascript
+async put(endpoint, headers = {}, payload = null)
+```
 
-- **Parameters**:
-  - `endpoint` (string): API endpoint path
-  - `queryParams` (object, optional): Query parameters
-- **Returns**: Promise with response data
-- **Example**:
-  ```javascript
-  await client.delete('products/SKU123');
-  ```
+```javascript
+const result = await client.put('rest/V1/products/MY-SKU', {}, {
+  product: { price: 39.99 },
+});
+```
+
+#### delete(endpoint, headers?)
+
+```javascript
+async delete(endpoint, headers = {})
+```
+
+```javascript
+const result = await client.delete('rest/V1/products/MY-SKU');
+if (result.success) { /* result.message = true for Commerce DELETE responses */ }
+```
 
 ### Oauth1aConnection Class
 
@@ -1163,28 +1254,66 @@ OAuth 1.0a authentication for Commerce
 
 IMS (Identity Management Services) authentication
 
-- **Purpose**: Establishes connection using Adobe IMS token
-- **Use Case**: Adobe Commerce Cloud integration
-- **Constructor**: `new ImsConnection(token)`
-- **Required Credentials**:
-  - `token`: IMS access token (obtained via AdobeAuth.getToken())
-- **How to Get**: Adobe Developer Console > Service Account (JWT) credentials
-- **Security**: IMS is secure for production use
-- **Note**: Token must be fetched using `AdobeAuth.getToken()` before creating connection
+- **Purpose**: Sets `Authorization: Bearer <token>` as a static header on the client; same token applied to every request
+- **Use Case**: Adobe Commerce Cloud with Adobe Identity (IMS) enabled
+- **Constructor**: `new ImsConnection(imsToken, logger?)`
+  - `imsToken`: Pre-generated IMS bearer token — **throws** if blank/whitespace
+  - `logger`: Optional logger instance
+- **Security**: Secure for production use
+- **Token refresh**: Entirely the caller's responsibility — `ImsConnection` does not refresh tokens
+
+**Two ways to obtain the token:**
+
+**Option A — `Core.AuthClient.generateAccessToken(params)` (recommended for App Builder actions)**
+
+Uses the action's own injected IMS credentials. Requires `include-ims-credentials: true` in `app.config.yaml`:
+
+```javascript
+const { Core } = require('@adobe/aio-sdk');
+
+const tokenResponse = await Core.AuthClient.generateAccessToken(params);
+const imsToken = tokenResponse && tokenResponse.access_token;
+const connection = new ImsConnection(imsToken, logger);
+```
+
+YAML annotation required:
+```yaml
+annotations:
+  include-ims-credentials: true   # injects IMS credential params automatically
+```
+
+**Option B — `AdobeAuth.getToken()` (Service Account / OAuth S2S)**
+
+Fetches a token using explicit S2S credentials from environment variables:
+
+```javascript
+const { AdobeAuth } = require('@adobe-commerce/aio-toolkit');
+
+const 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,
+  params.IMS_SCOPES.split(',')
+);
+const connection = new ImsConnection(imsToken, logger);
+```
 
 ### BasicAuthConnection Class
 
 HTTP Basic Authentication for Commerce
 
-- **Purpose**: Establishes connection using username/password
-- **Use Case**: Development/testing environments (NOT recommended for production)
-- **Constructor**: `new BasicAuthConnection(username, password)`
-- **Required Credentials**:
-  - `username`: Commerce admin username or API user
-  - `password`: Commerce admin password or API user password
-- **How to Get**: Use Commerce admin credentials or create dedicated API user
-- **Security**: ⚠️ **NOT secure for production** - credentials sent with every request
-- **Recommendation**: Use OAuth 1.0a or IMS for production environments
+- **Purpose**: Exchanges username/password for a bearer token via `POST /rest/V1/integration/admin/token`, then caches the token in Adobe I/O State (1-hour TTL) so subsequent invocations reuse it without another round-trip
+- **Use Case**: Development/testing environments or PaaS instances without an Integration or IMS configured (NOT recommended for production)
+- **Constructor**: `new BasicAuthConnection(baseUrl, username, password, logger?)`
+  - `baseUrl`: Commerce store root URL — **same value as `AdobeCommerceClient` baseUrl**
+  - `username`: Commerce admin username
+  - `password`: Commerce admin password
+  - `logger`: Optional logger instance
+- **How to Get**: Use Commerce admin credentials or create a dedicated API user
+- **Security**: ⚠️ **NOT secure for production** — use OAuth 1.0a or IMS instead
+- **Token caching**: Tokens cached in Adobe I/O State with 1-hour TTL; if State is unavailable (e.g. local dev), a fresh token is fetched every invocation silently
 
 ### AdobeAuth Class
 
@@ -1212,7 +1341,7 @@ Fetch IMS access token using service account credentials
     params.IMS_CLIENT_SECRET,
     params.IMS_TECHNICAL_ACCOUNT_ID,
     params.IMS_TECHNICAL_ACCOUNT_EMAIL,
-    params.IMS_ORD_ID,
+    params.IMS_ORG_ID,
     params.IMS_SCOPES.split(',')
   );
   ```
@@ -1230,7 +1359,8 @@ Fetch IMS access token using service account credentials
 
 4. **Client Builder Reusability**: If in root `lib/`, usable by both root and extension actions. Only create once, reuse everywhere.
 
-5. **API Usage**: Use REST V1 endpoints (`/rest/V1/products`), wrap calls in try-catch, handle errors with `RuntimeActionResponse.error()`, respect rate limits
+5. **API Usage**: Use REST V1 endpoints (e.g. `rest/V1/products`) — include the full REST path in the endpoint argument, not in `COMMERCE_BASE_URL`. The client **never throws** on HTTP errors — always check `result.success` instead of wrapping calls in try/catch. `result.message` is the parsed JSON body on success; `result.statusCode`, `result.message`, and `result.body` describe the failure.
+5a. **URL construction**: `COMMERCE_BASE_URL` is the store root (e.g. `https://your-store.com`). Do NOT include `/rest` or `/V1` in the base URL. Do NOT use a leading slash in endpoint strings. Query params go directly in the endpoint string: `rest/V1/orders?searchCriteria[pageSize]=10`.
 
 6. **No New Actions Created**: This rule only integrates Commerce API into existing actions. Use "Create Runtime Action" rule first if needed.
 
@@ -1247,15 +1377,16 @@ Fetch IMS access token using service account credentials
    - **Detection Priority**: If `typescript` + `tsconfig.json` exist OR 2+ indicators found OR `.ts` files exist → TypeScript project
    - No need to ask developer. TypeScript provides type safety with interfaces (Product, Customer, Order) and generics: `client.get<Product[]>('products')`
 
-10. **Performance**: Centralized Client Builder caches instance (singleton), better for high-frequency/multiple actions. IMS tokens fetched fresh per `getClient()` call.
+10. **Performance**: Centralized Client Builder caches instance (singleton), better for high-frequency/multiple actions. IMS tokens fetched fresh per `getClient()` call. Entity classes add a second lazy-init layer — `clientInitPromise` guard prevents double-init when `getClient()` is called concurrently.
+10a. **Logger threading**: Always pass `ctx.logger` to connections and the client — e.g. `new Oauth1aConnection(..., logger)` and `new AdobeCommerceClient(baseUrl, connection, logger)`. This routes automatic HTTP-level debug logs (request, retry, response) into the action's telemetry pipeline.
 
 11. **Action Configuration**: Add Commerce env vars as action inputs using `$VARIABLE_NAME` syntax in `app.config.yaml` or `ext.config.yaml`
 
-12. **Compatibility**: Works with RuntimeAction, WebhookAction, EventConsumerAction, GraphQL resolvers, OpenwhiskAction. Supports root and extension points.
+12. **Compatibility**: Works with RuntimeAction, WebhookAction, EventConsumerAction, GraphQL resolvers, OpenwhiskAction (sub-actions and orchestrators). Supports root and extension points.
 
 13. **Telemetry**: Recommend enabling New Relic for Commerce API observability (traces, metrics, logs). Refer to New Relic telemetry setup rule.
 
-14. **Integration with Action Creation Rules**: This rule is designed to work seamlessly with RuntimeAction, WebhookAction, GraphQLAction, and EventConsumerAction rules. When developers mention Commerce operations during action creation, automatically suggest or trigger this rule for Commerce API integration.
+14. **Integration with Action Creation Rules**: This rule is designed to work seamlessly with RuntimeAction, WebhookAction, GraphQLAction, EventConsumerAction, and OpenwhiskAction rules. When developers mention Commerce operations during action creation, automatically suggest or trigger this rule for Commerce API integration.
 
 15. **Edge Case - Ambiguous Language Detection**: If language detection is uncertain (e.g., TypeScript configured but no existing TypeScript files):
 
@@ -1306,10 +1437,11 @@ AI: [Integrates Commerce API calls into the action]
 
 Add this note to the "Business Logic" question in:
 
-- `create-runtime-action.mdc`
-- `create-webhook-action.mdc`
-- `aio-toolkit-create-graphql-action.mdc`
-- `aio-toolkit-create-event-consumer-action.mdc`
+- `aio-toolkit-create-runtime-action.md`
+- `aio-toolkit-create-webhook-action.md`
+- `aio-toolkit-create-graphql-action.md`
+- `aio-toolkit-create-event-consumer-action.md`
+- `aio-toolkit-create-openwhisk-action.md`
 
 **Note to add:**
 
@@ -1319,3 +1451,7 @@ Add this note to the "Business Logic" question in:
 - Then use "Creating Adobe Commerce Client Operations" rule to integrate Commerce API
 - That rule handles connection setup, client builder, and API calls
 ```
+
+## Related Rules
+
+- **"Using AdobeAuth"** (`aio-toolkit-use-adobe-auth.mdc`) — primary reference for `AdobeAuth.getToken()` usage, caching patterns, scope selection, and error handling when using `ImsConnection` with explicit S2S credentials