@adobe-commerce/aio-toolkit 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.7] - 2025-11-12
+
+### 🚀 PaaS Support for Adobe Commerce Event Subscriptions
+
+This release adds comprehensive support for Adobe Commerce PaaS (Platform as a Service) instances with native event handling, allowing seamless integration with cloud-based Adobe Commerce deployments.
+
+#### 🛍️ Commerce Integration Enhancements
+
+- **OnboardCommerce** `[Enhanced]` - Added PaaS instance support
+  - New `isPaaS` constructor parameter (defaults to `false`)
+  - Automatic handling of native Adobe Commerce events (`observer.*`, `plugin.*`)
+  - Skip supported events validation for PaaS instances to improve performance
+  - Omits `parent` field for PaaS events to prevent invalid alias errors
+  - Ensures `rules` array exists in event payloads (required by Adobe Commerce API)
+  - Displays post-subscription instructions for PaaS instances with Magento CLI commands
+  - Full backward compatibility - existing code continues to work without changes
+  - Enhanced logging with `[SKIP]` and `[IMPORTANT]` prefixes for PaaS workflows
+  - 100% test coverage with comprehensive PaaS-specific test cases
+
+#### 📝 Post-Subscription Instructions for PaaS
+
+When `isPaaS` is enabled, the system automatically logs important post-subscription steps:
+
+```
+[IMPORTANT] ⚠️  Post-Subscription Steps for PaaS:
+[IMPORTANT] 1. Run: bin/magento events:generate:module to generate module after successful event subscription
+[IMPORTANT] 2. Run: bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush to install the generated module
+```
+
+#### 🔧 Technical Improvements
+
+- Enhanced event payload preparation logic to support native PaaS events
+- Improved validation workflow with conditional supported events check
+- Added rules array initialization for API compliance
+- Comprehensive test coverage for all PaaS-related functionality
+
+#### 📚 Usage Example
+
+```typescript
+import { OnboardCommerce } from '@adobe-commerce/aio-toolkit';
+
+// For PaaS instances
+const onboardCommerce = new OnboardCommerce(
+  adobeCommerceClient,
+  merchantId,
+  environmentId,
+  logger,
+  true // Enable PaaS mode
+);
+
+// PaaS mode automatically:
+// - Skips supported events validation
+// - Handles native events (observer.*, plugin.*)
+// - Displays post-subscription CLI commands
+```
+
+---
+
 ## [1.0.6] - 2025-11-11
 
 ### 🚀 New Integration Module & API Enhancements

package/README.md

@@ -752,7 +752,8 @@ const onboardCommerce = new OnboardCommerce(
   adobeCommerceClient,
   process.env.COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID || '',
   process.env.COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID || '',
-  logger
+  logger,
+  false // isPaaS: set to true for PaaS instances (defaults to false)
 );
 
 // Define commerce provider
@@ -815,11 +816,66 @@ if (result.success) {
 - Automated provider configuration with validation
 - Event subscription management with duplicate detection
 - Intelligent event metadata validation against supported Commerce events
-- Structured logging with prefixes: `[START]`, `[CREATE]`, `[SKIP]`, `[ERROR]`
+- **PaaS support** for Adobe Commerce Cloud instances with native event handling
+- Structured logging with prefixes: `[START]`, `[CREATE]`, `[SKIP]`, `[ERROR]`, `[IMPORTANT]`
 - Comprehensive summary reporting with event subscription statistics
 - Integration with Adobe Commerce API for event discovery
+- Automatic post-subscription CLI instructions for PaaS instances
 - 100% test coverage
 
+**PaaS Support:**
+
+For Adobe Commerce PaaS (Platform as a Service) instances, enable PaaS mode to support native events:
+
+```typescript
+// Initialize OnboardCommerce for PaaS instances
+const onboardCommercePaaS = new OnboardCommerce(
+  adobeCommerceClient,
+  merchantId,
+  environmentId,
+  logger,
+  true // Enable PaaS mode
+);
+
+// Define native PaaS events (observer.*, plugin.*)
+const paasEventsConfig = [
+  {
+    event: {
+      name: 'observer.catalog_product_save_after',
+      label: 'Product Saved',
+      description: 'Native observer event'
+    }
+  },
+  {
+    event: {
+      name: 'plugin.magento.catalog.model.product.save',
+      label: 'Product Save Plugin',
+      description: 'Native plugin event'
+    }
+  }
+];
+
+// Process PaaS events
+const result = await onboardCommercePaaS.process(
+  commerceProvider.raw,
+  workspaceConfig,
+  paasEventsConfig
+);
+
+// PaaS mode automatically:
+// - Skips supported events validation for better performance
+// - Handles native events without the 'parent' field
+// - Displays post-subscription Magento CLI commands
+```
+
+After successful event subscription on PaaS, the system displays:
+
+```
+[IMPORTANT] ⚠️  Post-Subscription Steps for PaaS:
+[IMPORTANT] 1. Run: bin/magento events:generate:module to generate module after successful event subscription
+[IMPORTANT] 2. Run: bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush to install the generated module
+```
+
 ### 🎨 Experience Components
 
 **Adobe Commerce Admin UI extension and user experience tools**

package/dist/index.d.mts

@@ -611,7 +611,8 @@ declare class OnboardCommerce {
     private readonly configureProvider;
     private readonly eventSubscriptionService;
     private readonly eventService;
-    constructor(adobeCommerceClient: AdobeCommerceClient, merchantId: string, environmentId: string, logger?: any);
+    private readonly isPaaS;
+    constructor(adobeCommerceClient: AdobeCommerceClient, merchantId: string, environmentId: string, logger?: any, isPaaS?: boolean);
     process(provider: Provider, workspaceConfig: WorkspaceConfig, commerceEventsConfig?: CommerceEventConfig[]): Promise<any>;
     private filterEventsBySubscriptionStatus;
     private prepareEventPayload;

package/dist/index.d.ts

@@ -611,7 +611,8 @@ declare class OnboardCommerce {
     private readonly configureProvider;
     private readonly eventSubscriptionService;
     private readonly eventService;
-    constructor(adobeCommerceClient: AdobeCommerceClient, merchantId: string, environmentId: string, logger?: any);
+    private readonly isPaaS;
+    constructor(adobeCommerceClient: AdobeCommerceClient, merchantId: string, environmentId: string, logger?: any, isPaaS?: boolean);
     process(provider: Provider, workspaceConfig: WorkspaceConfig, commerceEventsConfig?: CommerceEventConfig[]): Promise<any>;
     private filterEventsBySubscriptionStatus;
     private prepareEventPayload;

package/dist/index.js

@@ -5619,6 +5619,7 @@ var _OnboardCommerce = class _OnboardCommerce {
    * @param merchantId - Merchant ID for Adobe Commerce
    * @param environmentId - Environment ID for Adobe Commerce
    * @param logger - Optional logger instance for logging operations
+   * @param isPaaS - Flag to indicate if the Commerce instance is PaaS (defaults to false)
    * @throws {Error} When required parameters are missing or invalid
    * @example
    * ```typescript
@@ -5631,7 +5632,7 @@ var _OnboardCommerce = class _OnboardCommerce {
    * );
    * ```
    */
-  constructor(adobeCommerceClient, merchantId, environmentId, logger = null) {
+  constructor(adobeCommerceClient, merchantId, environmentId, logger = null, isPaaS = false) {
     if (!adobeCommerceClient) {
       throw new Error("Adobe Commerce client is required");
     }
@@ -5644,6 +5645,7 @@ var _OnboardCommerce = class _OnboardCommerce {
     this.adobeCommerceClient = adobeCommerceClient;
     this.merchantId = merchantId;
     this.environmentId = environmentId;
+    this.isPaaS = isPaaS;
     this.customLogger = new custom_logger_default(logger);
     this.configureProvider = new configure_provider_default(
       adobeCommerceClient,
@@ -5700,16 +5702,22 @@ var _OnboardCommerce = class _OnboardCommerce {
             `[FETCH] Retrieved ${existingSubscriptions.length} existing event subscription(s)`
           );
         }
-        this.customLogger.debug("[FETCH] Fetching supported events list...");
-        const supportedEventsResult = await this.eventService.supportedList();
         let supportedEvents = [];
-        if (!supportedEventsResult.success) {
-          this.customLogger.error(
-            `[ERROR] Failed to fetch supported events: ${supportedEventsResult.error}`
-          );
+        if (!this.isPaaS) {
+          this.customLogger.debug("[FETCH] Fetching supported events list...");
+          const supportedEventsResult = await this.eventService.supportedList();
+          if (!supportedEventsResult.success) {
+            this.customLogger.error(
+              `[ERROR] Failed to fetch supported events: ${supportedEventsResult.error}`
+            );
+          } else {
+            supportedEvents = Array.isArray(supportedEventsResult.data) ? supportedEventsResult.data : [];
+            this.customLogger.debug(
+              `[FETCH] Retrieved ${supportedEvents.length} supported event(s)`
+            );
+          }
         } else {
-          supportedEvents = Array.isArray(supportedEventsResult.data) ? supportedEventsResult.data : [];
-          this.customLogger.debug(`[FETCH] Retrieved ${supportedEvents.length} supported event(s)`);
+          this.customLogger.debug("[SKIP] Skipping supported events validation for PaaS instance");
         }
         const { alreadySubscribed, needsSubscription, unsupported } = this.filterEventsBySubscriptionStatus(
           commerceEventsConfig,
@@ -5752,6 +5760,15 @@ ${JSON.stringify(preparedEvent.event, null, 2)}`
           }
         }
         this.logEventSubscriptionSummary(result, provider.label);
+        if (this.isPaaS) {
+          this.customLogger.info("[IMPORTANT] \u26A0\uFE0F  Post-Subscription Steps for PaaS:");
+          this.customLogger.info(
+            "[IMPORTANT] 1. Run: bin/magento events:generate:module to generate module after successful event subscription"
+          );
+          this.customLogger.info(
+            "[IMPORTANT] 2. Run: bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush to install the generated module"
+          );
+        }
       }
       return {
         success: true,
@@ -5809,6 +5826,10 @@ ${JSON.stringify(preparedEvent.event, null, 2)}`
   /**
    * Prepares event payload by transforming event names and adding provider information
    *
+   * For PaaS instances, the parent field is omitted to support native events (observer.*, plugin.*)
+   * which would be rejected by Adobe Commerce as invalid aliases if parent is set to the same name.
+   * For non-PaaS instances, the parent field is set to the event name as usual.
+   *
    * @param eventSpec - Event specification object containing event details
    * @param providerId - Provider ID to assign to the event
    * @returns Modified event specification with updated event properties
@@ -5825,12 +5846,18 @@ ${JSON.stringify(preparedEvent.event, null, 2)}`
       throw new Error("Valid provider ID is required");
     }
     const modifiedEventSpec = JSON.parse(JSON.stringify(eventSpec));
-    modifiedEventSpec.event.parent = modifiedEventSpec.event.name;
+    const eventName = modifiedEventSpec.event.name;
+    if (!this.isPaaS) {
+      modifiedEventSpec.event.parent = eventName;
+    }
     modifiedEventSpec.event.provider_id = providerId;
     modifiedEventSpec.event.destination = "default";
     modifiedEventSpec.event.provider_id = providerId;
     modifiedEventSpec.event.priority = true;
     modifiedEventSpec.event.hipaa_audit_required = false;
+    if (!modifiedEventSpec.event.rules) {
+      modifiedEventSpec.event.rules = [];
+    }
     return modifiedEventSpec;
   }
   /**