@adobe-commerce/aio-toolkit 1.0.15 → 1.0.17

package/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.17] - 2026-02-25
+
+### ✨ Features
+
+- **feat(publish-event):** Add optional `eventId` parameter to `PublishEvent.execute()`
+  - Allows callers to supply custom event IDs for idempotency, correlation, or tracking
+  - Falls back to auto-generated UUID when not provided
+  - New signature: `execute(providerId, eventCode, payload, eventId?, subject?)`
+
+### ⚠️ Breaking Changes
+
+- **BREAKING(publish-event):** Parameter order changed for `PublishEvent.execute()`
+  - `subject` has moved from 4th to 5th position
+  - When passing subject without custom eventId, use: `execute(providerId, eventCode, payload, undefined, subject)`
+  - Previous call: `execute(providerId, eventCode, payload, subject)` → Update to: `execute(providerId, eventCode, payload, undefined, subject)`
+
+---
+
+## [1.0.16] - 2026-02-23
+
+### ✨ Features
+
+- **feat(cli):** New Adobe I/O Events Onboarding CLI (`aio-toolkit-onboard-events`)
+  - Command-line tool for managing Adobe I/O Events and Commerce event integrations
+  - Three sub-commands: `execute`, `cleanup`, and `help`
+  - Automated provider, registration, and event subscription management
+  - Support for both OAuth 1.0a and IMS authentication
+  - Configuration-driven approach using YAML files
+  - Comprehensive environment variable validation
+  - Structured logging with detailed progress tracking
+  - Cleanup command for removing test/development resources
+  - Respects dependency order during cleanup (registrations → metadata → providers)
+  - 100% test coverage with comprehensive test suites
+
+### 🔧 Refactoring
+
+- **refactor(commands):** Framework command architecture refactoring (#132)
+  - Abstract command base class for consistent CLI structure
+  - Command registry pattern for extensible command management
+  - AI-agent friendly base commands (base-apply, base-check)
+  - Standardized help command implementation
+  - Improved code organization and maintainability
+  - Enhanced type safety with TypeScript interfaces
+
+- **refactor(helpers):** New helper utilities for CLI commands
+  - `ApplicationName` helper for extracting app names from config
+  - `AdobeAuthToken` helper for centralized token generation
+  - `AdobeCommerceClient` helper for Commerce API integration
+  - IO Events authentication and environment helpers
+  - Commerce helper utilities following DRY principle
+  - 100% test coverage for all helper functions
+
+### 💡 Usage Examples
+
+**Execute Adobe I/O Events onboarding**:
+```bash
+npx aio-toolkit-onboard-events execute
+```
+
+**Cleanup development resources**:
+```bash
+npx aio-toolkit-onboard-events cleanup
+```
+
+**Display help**:
+```bash
+npx aio-toolkit-onboard-events help
+```
+
+---
+
 ## [1.0.15] - 2026-02-09
 
 ### ✨ Features

package/README.md

@@ -171,12 +171,13 @@ const result = await publishEvent.execute(
     customerId: 'CUST-789',
     amount: 199.99,
     currency: 'USD'
-  }
+  },
+  'eventId'
 );
 
 console.log(`Event published: ${result.eventId}, Status: ${result.status}`);
 
-// Publish an event with subject
+// Publish an event with subject (eventId is optional; pass undefined to use auto-generated ID)
 const orderResult = await publishEvent.execute(
   'commerce-provider',
   'com.adobe.commerce.order.shipped',
@@ -186,6 +187,7 @@ const orderResult = await publishEvent.execute(
     carrier: 'UPS',
     estimatedDelivery: '2023-12-05T18:00:00Z'
   },
+  undefined,
   'orders/ORD-123456'
 );
 
@@ -1581,30 +1583,111 @@ The CLI provides the following context files:
 3. **Verification**: Run `check` to ensure contexts are properly configured
 4. **Updates**: Run `apply -f` after toolkit updates to get latest contexts
 
+#### `aio-toolkit-onboard-events`
+
+Command-line tool for managing Adobe I/O Events and Commerce event integrations. This CLI automates the process of onboarding event providers, registrations, and subscriptions, as well as cleaning up resources from test/development environments.
+
+##### Commands
+
+###### `execute`
+Onboards Adobe I/O Events providers, registrations, and Commerce event subscriptions based on configuration file.
+
+```bash
+# Execute with default config (onboard.config.yaml)
+npx aio-toolkit-onboard-events execute
+```
+
+**Features:**
+- ✅ Creates Adobe I/O Events providers with automatic duplicate detection
+- ✅ Sets up event metadata for custom events
+- ✅ Configures event registrations with webhook or journal delivery
+- ✅ Subscribes to Adobe Commerce events (supports both OAuth and IMS authentication)
+- ✅ Validates environment variables upfront with clear error messages
+- ✅ Structured logging with detailed progress tracking
+
+###### `cleanup`
+Removes Adobe I/O Events resources and Commerce event subscriptions defined in configuration file.
+
+```bash
+# Cleanup with default config
+npx aio-toolkit-onboard-events cleanup
+```
+
+**Features:**
+- 🗑️ Deletes event registrations
+- 🗑️ Removes event metadata
+- 🗑️ Deletes event providers
+- 🗑️ Unsubscribes from Commerce events and removes providers
+- ⚡ Respects dependency order (registrations → metadata → providers)
+- 📊 Provides detailed cleanup summary
+
+###### `help`
+Displays help information for the CLI.
+
+```bash
+npx aio-toolkit-onboard-events help
+```
+
+##### Configuration File
+
+The CLI uses `onboard.config.yaml` to define resources. Default template:
+
+```yaml
+# Configuration file version
+version: "1.0"
+
+# Application metadata
+application:
+  name: "My App Builder Application"
+  # Description is optional
+  # description: "My App Builder Application for Adobe Commerce"
+
+# Events configuration
+events:
+  # Adobe I/O Events configuration
+  io:
+    config: io-events.json  # File path to I/O events configuration
+
+  # Adobe Commerce Events configuration
+  commerce:
+    providerKey: commerce
+    config: commerce-events.json  # File path to Commerce events configuration
+
+# Deployment settings
+deployment:
+  # Instance type: paas | cloud
+  # paas = Adobe Commerce Cloud/On-premise (OAuth)
+  # cloud = Adobe Commerce as Cloud Service (IMS)
+  type: paas
+  
+  # Authentication type (optional, auto-detected from type if not specified)
+  # Allowed values: oauth | ims
+  # Auto-detection: paas → oauth, cloud → ims
+  # authType: oauth
+```
+
+##### Use Cases
+
+1. **Development Onboarding**: Run `execute` to quickly set up event integrations
+2. **Environment Cleanup**: Run `cleanup` to remove test resources before production deployment
+3. **CI/CD Integration**: Automate event configuration in deployment pipelines
+4. **Multi-Environment Setup**: Use different config files for dev/staging/production environments
+
 ## Environment Variables
 
 Common environment variables used across components:
 
 ```bash
-# Adobe commerce credentials
-COMMERCE_BASE_URL=commerce-base-url
-COMMERCE_CONSUMER_KEY=commerce-consumer-key
-COMMERCE_CONSUMER_SECRET=commerce-consumer-secret
-COMMERCE_ACCESS_TOKEN=commerce-access-token
-COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
-# Environment from DIST file
-OAUTH_BASE_URL=https://ims-na1.adobelogin.com/ims/token/
-IO_MANAGEMENT_BASE_URL=https://api.adobe.io/events/
-# OAuth configs
+# Adobe I/O Events OAuth (Required for aio-toolkit-onboard-events)
 # The following values can be copied from the Credential details page in AppBuilder under Organization > Project > Workspace > OAuth Server-to-Server
 OAUTH_CLIENT_ID=client-id
 OAUTH_CLIENT_SECRET=client-secret
 OAUTH_TECHNICAL_ACCOUNT_ID=technical-account-id
 OAUTH_TECHNICAL_ACCOUNT_EMAIL=technical-account-email
 OAUTH_ORG_ID=org-id
-OAUTH_SCOPES=scopes
-# OAUTH_HOST=<string>
-# Workspace configs
+OAUTH_SCOPES=openid, AdobeID, adobeio_api
+
+# Adobe I/O Workspace (Required for aio-toolkit-onboard-events)
 # The following values can be copied from the JSON downloadable in AppBuilder from Organization > Project > Workspace
 # IO_CONSUMER corresponds to project.org.id
 # IO_PROJECT_ID corresponds to project.id
@@ -1612,6 +1695,36 @@ OAUTH_SCOPES=scopes
 IO_CONSUMER_ID=consumer-id
 IO_PROJECT_ID=project-id
 IO_WORKSPACE_ID=workspace-id
+
+# Workspace Configuration (Required for aio-toolkit-onboard-events)
+IO_WORKSPACE_CONFIG=path/to/onboard.config.yaml
+
+# Adobe Commerce Base Configuration (Required for Commerce events)
+COMMERCE_BASE_URL=https://your-commerce-store.com
+COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID=merchant-id
+COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID=environment-id
+
+# Commerce OAuth 1.0a Authentication (Use when authType is "oauth1a")
+COMMERCE_OAUTH_CONSUMER_KEY=consumer-key
+COMMERCE_OAUTH_CONSUMER_SECRET=consumer-secret
+COMMERCE_OAUTH_ACCESS_TOKEN=access-token
+COMMERCE_OAUTH_ACCESS_TOKEN_SECRET=access-token-secret
+
+# Commerce IMS Authentication (Use when authType is "ims")
+COMMERCE_IMS_CLIENT_ID=client-id
+COMMERCE_IMS_CLIENT_SECRET=client-secret
+COMMERCE_IMS_TECHNICAL_ACCOUNT_ID=tech-account-id
+COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL=tech-email
+COMMERCE_IMS_ORG_ID=org-id
+COMMERCE_IMS_SCOPES=openid, AdobeID, adobeio_api
+
+# Legacy Environment Variables (Still supported for backward compatibility)
+OAUTH_BASE_URL=https://ims-na1.adobelogin.com/ims/token/
+IO_MANAGEMENT_BASE_URL=https://api.adobe.io/events/
+COMMERCE_CONSUMER_KEY=commerce-consumer-key
+COMMERCE_CONSUMER_SECRET=commerce-consumer-secret
+COMMERCE_ACCESS_TOKEN=commerce-access-token
+COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
 ```
 
 ## License

package/dist/aio-toolkit-cursor-context/bin/cli.js

@@ -32,12 +32,54 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/commands/framework/command/base-context-help/index.ts
-var _BaseContextHelp, BaseContextHelp;
-var init_base_context_help = __esm({
-  "src/commands/framework/command/base-context-help/index.ts"() {
+// src/commands/framework/command/abstract/index.ts
+var _CommandAbstract, CommandAbstract;
+var init_abstract = __esm({
+  "src/commands/framework/command/abstract/index.ts"() {
     "use strict";
-    _BaseContextHelp = class _BaseContextHelp {
+    _CommandAbstract = class _CommandAbstract {
+      /**
+       * Method to get the name of the command
+       * @returns {string} The name of the command
+       */
+      static getName() {
+        throw new Error("getName() must be implemented by subclass");
+      }
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getDescription() {
+        throw new Error("getDescription() must be implemented by subclass");
+      }
+      /**
+       * Method to execute the command
+       * @param {...any} args - Command arguments
+       * @returns {Promise<CommandResult>} The execution result
+       */
+      static execute(...args2) {
+        throw new Error(`execute() must be implemented by subclass: ${args2.join(", ")}`);
+      }
+    };
+    __name(_CommandAbstract, "CommandAbstract");
+    CommandAbstract = _CommandAbstract;
+  }
+});
+
+// src/commands/framework/command/base-help/index.ts
+var _BaseHelpCommand, BaseHelpCommand;
+var init_base_help = __esm({
+  "src/commands/framework/command/base-help/index.ts"() {
+    "use strict";
+    init_abstract();
+    _BaseHelpCommand = class _BaseHelpCommand extends CommandAbstract {
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getName() {
+        return this.NAME;
+      }
       /**
        * Static method to get the commands - must be implemented by subclasses
        *
@@ -55,11 +97,11 @@ var init_base_context_help = __esm({
         throw new Error("getCommands() must be implemented by subclass");
       }
       /**
-       * Static execute method that returns the help text
-       *
-       * @returns {CommandResult} The command result with help text
+       * Method to execute the command
+       * @param {...any} _args - Command arguments (unused)
+       * @returns {Promise<CommandResult>} The execution result
        */
-      static execute() {
+      static execute(..._args) {
         const helpText = [
           this.getUsageSection(),
           this.getCommandsSection(),
@@ -116,20 +158,16 @@ For more information, visit:
 `;
       }
     };
-    __name(_BaseContextHelp, "BaseContextHelp");
+    __name(_BaseHelpCommand, "BaseHelpCommand");
     /**
      * Static command name
      */
-    _BaseContextHelp.NAME = "help";
-    /**
-     * Static command description
-     */
-    _BaseContextHelp.DESCRIPTION = "Show help for the rules commands";
+    _BaseHelpCommand.NAME = "help";
     /**
      * Static repository URL
      */
-    _BaseContextHelp.repositoryUrl = "https://github.com/adobe-commerce/aio-toolkit";
-    BaseContextHelp = _BaseContextHelp;
+    _BaseHelpCommand.repositoryUrl = "https://github.com/adobe-commerce/aio-toolkit";
+    BaseHelpCommand = _BaseHelpCommand;
   }
 });
 
@@ -138,8 +176,8 @@ var _CursorContextHelp, CursorContextHelp;
 var init_help = __esm({
   "src/commands/cursor-context/lib/help/index.ts"() {
     "use strict";
-    init_base_context_help();
-    _CursorContextHelp = class _CursorContextHelp extends BaseContextHelp {
+    init_base_help();
+    _CursorContextHelp = class _CursorContextHelp extends BaseHelpCommand {
       /**
        * Get the CLI name
        * This is used to display the correct help text for the CLI.
@@ -149,6 +187,13 @@ var init_help = __esm({
       static getCliName() {
         return "aio-toolkit-cursor-context";
       }
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getDescription() {
+        return this.DESCRIPTION;
+      }
       /**
        * Get commands dynamically to avoid circular dependency
        * This will be populated when CursorRules is initialized
@@ -161,6 +206,10 @@ var init_help = __esm({
       }
     };
     __name(_CursorContextHelp, "CursorContextHelp");
+    /**
+     * Static command description
+     */
+    _CursorContextHelp.DESCRIPTION = "Show help for the rules commands";
     CursorContextHelp = _CursorContextHelp;
   }
 });
@@ -550,14 +599,22 @@ var init_helpers = __esm({
   }
 });
 
-// src/commands/framework/command/base-context-check/index.ts
-var path4, _BaseContextCheck, BaseContextCheck;
-var init_base_context_check = __esm({
-  "src/commands/framework/command/base-context-check/index.ts"() {
+// src/commands/framework/command/ai-agent/base-check/index.ts
+var path4, _AIAgentBaseCheck, AIAgentBaseCheck;
+var init_base_check = __esm({
+  "src/commands/framework/command/ai-agent/base-check/index.ts"() {
     "use strict";
     path4 = __toESM(require("path"));
     init_helpers();
-    _BaseContextCheck = class _BaseContextCheck {
+    init_abstract();
+    _AIAgentBaseCheck = class _AIAgentBaseCheck extends CommandAbstract {
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getName() {
+        return this.NAME;
+      }
       /**
        * Get the directory paths to check
        * This is used to check if the context directories exist.
@@ -649,16 +706,12 @@ ${dir}:`);
         };
       }
     };
-    __name(_BaseContextCheck, "BaseContextCheck");
+    __name(_AIAgentBaseCheck, "AIAgentBaseCheck");
     /**
      * Static command name
      */
-    _BaseContextCheck.NAME = "check";
-    /**
-     * Static command description
-     */
-    _BaseContextCheck.DESCRIPTION = "Check contexts are applied to the project";
-    BaseContextCheck = _BaseContextCheck;
+    _AIAgentBaseCheck.NAME = "check";
+    AIAgentBaseCheck = _AIAgentBaseCheck;
   }
 });
 
@@ -668,8 +721,15 @@ var init_check = __esm({
   "src/commands/cursor-context/lib/check/index.ts"() {
     "use strict";
     path5 = __toESM(require("path"));
-    init_base_context_check();
-    _CursorContextCheck = class _CursorContextCheck extends BaseContextCheck {
+    init_base_check();
+    _CursorContextCheck = class _CursorContextCheck extends AIAgentBaseCheck {
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getDescription() {
+        return this.DESCRIPTION;
+      }
       /**
        * Get the directory paths to check
        * This is used to check if the context directories exist.
@@ -681,20 +741,32 @@ var init_check = __esm({
       }
     };
     __name(_CursorContextCheck, "CursorContextCheck");
+    /**
+     * Static command description
+     */
+    _CursorContextCheck.DESCRIPTION = "Check cursor context applied to the project";
     CursorContextCheck = _CursorContextCheck;
   }
 });
 
-// src/commands/framework/command/base-rule-apply/index.ts
-var fs6, path6, _BaseRuleApply, BaseRuleApply;
-var init_base_rule_apply = __esm({
-  "src/commands/framework/command/base-rule-apply/index.ts"() {
+// src/commands/framework/command/ai-agent/base-apply/index.ts
+var fs6, path6, _AIAgentBaseApply, AIAgentBaseApply;
+var init_base_apply = __esm({
+  "src/commands/framework/command/ai-agent/base-apply/index.ts"() {
     "use strict";
     fs6 = __toESM(require("fs"));
     path6 = __toESM(require("path"));
     init_format_messages();
     init_helpers();
-    _BaseRuleApply = class _BaseRuleApply {
+    init_abstract();
+    _AIAgentBaseApply = class _AIAgentBaseApply extends CommandAbstract {
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getName() {
+        return this.NAME;
+      }
       /**
        * Get the copy directories configuration
        * @returns {Record<string, { from: string; to: string }>} Object with directory pairs to copy
@@ -939,27 +1011,30 @@ ${dirKey.toUpperCase()}:`);
         }
       }
     };
-    __name(_BaseRuleApply, "BaseRuleApply");
+    __name(_AIAgentBaseApply, "AIAgentBaseApply");
     /**
      * Static command name
      */
-    _BaseRuleApply.NAME = "apply";
-    /**
-     * Static command description
-     */
-    _BaseRuleApply.DESCRIPTION = "Apply contexts to your project (use --force or -f to overwrite existing)";
-    BaseRuleApply = _BaseRuleApply;
+    _AIAgentBaseApply.NAME = "apply";
+    AIAgentBaseApply = _AIAgentBaseApply;
   }
 });
 
 // src/commands/cursor-context/lib/apply/index.ts
-var path7, _CursorRuleApply, CursorRuleApply;
+var path7, _CursorContextApply, CursorContextApply;
 var init_apply = __esm({
   "src/commands/cursor-context/lib/apply/index.ts"() {
     "use strict";
     path7 = __toESM(require("path"));
-    init_base_rule_apply();
-    _CursorRuleApply = class _CursorRuleApply extends BaseRuleApply {
+    init_base_apply();
+    _CursorContextApply = class _CursorContextApply extends AIAgentBaseApply {
+      /**
+       * Method to get the description of the command
+       * @returns {string} The description of the command
+       */
+      static getDescription() {
+        return this.DESCRIPTION;
+      }
       /**
        * Enable IDE detection for Cursor-specific contexts
        * @returns {boolean} True to enable IDE detection
@@ -984,17 +1059,21 @@ var init_apply = __esm({
         };
       }
     };
-    __name(_CursorRuleApply, "CursorRuleApply");
-    CursorRuleApply = _CursorRuleApply;
+    __name(_CursorContextApply, "CursorContextApply");
+    /**
+     * Static command description
+     */
+    _CursorContextApply.DESCRIPTION = "Apply contexts to your project (use --force or -f to overwrite existing)";
+    CursorContextApply = _CursorContextApply;
   }
 });
 
-// src/commands/framework/command/base-rules/index.ts
-var _BaseRules, BaseRules;
-var init_base_rules = __esm({
-  "src/commands/framework/command/base-rules/index.ts"() {
+// src/commands/framework/command/registry/index.ts
+var _CommandRegistry, CommandRegistry;
+var init_registry = __esm({
+  "src/commands/framework/command/registry/index.ts"() {
     "use strict";
-    _BaseRules = class _BaseRules {
+    _CommandRegistry = class _CommandRegistry {
       /**
        * Static method to get the commands - must be implemented by subclasses
        *
@@ -1021,8 +1100,8 @@ var init_base_rules = __esm({
         return await command2.execute(...args2);
       }
     };
-    __name(_BaseRules, "BaseRules");
-    BaseRules = _BaseRules;
+    __name(_CommandRegistry, "CommandRegistry");
+    CommandRegistry = _CommandRegistry;
   }
 });
 
@@ -1038,8 +1117,8 @@ var init_lib = __esm({
     init_help();
     init_check();
     init_apply();
-    init_base_rules();
-    _CursorRules = class _CursorRules extends BaseRules {
+    init_registry();
+    _CursorRules = class _CursorRules extends CommandRegistry {
       /**
        * Static commands array
        *
@@ -1048,19 +1127,19 @@ var init_lib = __esm({
       static getCommands() {
         return [
           {
-            name: CursorContextHelp.NAME,
-            description: CursorContextHelp.DESCRIPTION,
+            name: CursorContextHelp.getName(),
+            description: CursorContextHelp.getDescription(),
             execute: CursorContextHelp.execute.bind(CursorContextHelp)
           },
           {
-            name: CursorContextCheck.NAME,
-            description: CursorContextCheck.DESCRIPTION,
+            name: CursorContextCheck.getName(),
+            description: CursorContextCheck.getDescription(),
             execute: CursorContextCheck.execute.bind(CursorContextCheck)
           },
           {
-            name: CursorRuleApply.NAME,
-            description: CursorRuleApply.DESCRIPTION,
-            execute: CursorRuleApply.execute.bind(CursorRuleApply)
+            name: CursorContextApply.getName(),
+            description: CursorContextApply.getDescription(),
+            execute: CursorContextApply.execute.bind(CursorContextApply)
           }
         ];
       }