@adobe-commerce/aio-toolkit 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -5,6 +5,111 @@ 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.8] - 2025-11-18
+
+### 🔒 Security Fixes
+
+- **OnboardCommerce & OnboardEvents** `[Security]` - Removed sensitive payload logging (#94)
+  - Eliminated all sensitive data exposure in debug logs across onboarding components
+  - Modified `OnboardCommerce.subscribeToEvents()` to log only event names instead of full payloads
+  - Updated `ConfigureProvider` to log only provider/merchant IDs instead of complete configuration objects
+  - Changed `CreateRegistrations` to log only registration names instead of input payloads
+  - Modified `CreateProviders` to log only provider labels instead of full input data
+  - Prevents exposure of API keys, access tokens, client secrets, and merchant credentials
+  - Reduces security risks in console output, CI/CD logs, and debug sessions
+  - Maintains useful debugging context while protecting sensitive information
+  - 100% test coverage maintained
+
+### 🐛 Bug Fixes
+
+- **FileRepository** `[Fixed]` - Preserve file timestamps in save() method (#93)
+  - Fixed `save()` method to preserve `createdAt` timestamp when updating existing files
+  - Removed unnecessary `filesLib.delete()` call that was resetting file creation timestamp
+  - Now relies on `filesLib.write()` to overwrite content while preserving file metadata
+  - Applies to both merge mode (default) and overwrite mode (`overwrite=true`)
+  - File system's native `createdAt` timestamp is now correctly maintained across updates
+  - Updated tests to verify `delete` is never called in either mode
+  - 100% test coverage maintained
+
+### ✨ Enhancements
+
+- **GitHub Issue Templates** `[Enhanced]` - Updated with comprehensive component list (#95)
+  - Added 32+ components organized by category across all three issue templates
+  - New category headers: Commerce, Integration, Framework, I/O Events, Experience, Other
+  - Added missing components:
+    - Commerce: BasicAuthConnection, Oauth1aConnection, ImsConnection, GenerateBasicAuthToken, ShippingCarrierMethod, ShippingCarrierResponse
+    - Integration: CreateEvents, CreateRegistrations, OnboardCommerce
+    - Framework: RuntimeActionResponse, WebhookAction, WebhookActionResponse, ImsToken, RuntimeApiGatewayService, Parameters/Validator
+    - I/O Events: EventMetadataManager, ProviderManager, RegistrationManager
+    - Experience: AdminUiSdk
+  - Improved user experience with visual category separation in dropdowns
+  - Better issue triaging and component-level tracking for maintainers
+  - All templates (bug_report.yml, feature_request.yml, question.yml) updated consistently
+
+### 📊 Statistics
+
+- **Total Components**: 32+ selectable options across 5 categories
+- **Test Coverage**: 100% maintained (1679 tests passing)
+- **Files Changed**: 7 files across 3 PRs
+
+## [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

@@ -553,7 +553,6 @@ var _FileRepository = class _FileRepository {
           const existingData = JSON.parse(buffer.toString());
           payload = { ...existingData, ...payload };
         }
-        await filesLib.delete(filepath);
       } else {
         payload = {
           id: fileId,
@@ -4434,9 +4433,7 @@ var _CreateProviders = class _CreateProviders {
     }
     try {
       const providerInput = this.preparePayload(providerData, enhancedLabel);
-      this.logger.debug(
-        `[NEW] Creating new provider with payload: ${JSON.stringify(providerInput)}`
-      );
+      this.logger.debug(`[NEW] Creating new provider: ${enhancedLabel}`);
       const createdProvider = await this.getProviderManager().create(providerInput);
       this.logger.debug(
         `[INFO] Provider created successfully! ID: ${createdProvider.id}, Instance ID: ${createdProvider.instance_id}`
@@ -4955,7 +4952,7 @@ var _CreateRegistrations = class _CreateRegistrations {
         registrationName,
         firstEvent
       );
-      this.logger.debug(`[INFO] Registration input: ${JSON.stringify(registrationInput, null, 2)}`);
+      this.logger.debug(`[INFO] Creating registration: ${registrationName}`);
       const registrationSDK = this.getRegistrationManager();
       const createdRegistration = await registrationSDK.create(registrationInput);
       this.logger.debug("[SUCCESS] Registration created successfully!");
@@ -5518,10 +5515,7 @@ var _ConfigureProvider = class _ConfigureProvider {
       description: provider.description,
       workspace_configuration: JSON.stringify(workspaceConfig)
     };
-    this.customLogger.debug(
-      `[DEBUG] Creating event provider:
-${JSON.stringify(providerData, null, 2)}`
-    );
+    this.customLogger.debug(`[DEBUG] Creating event provider: ${provider.label} (${provider.id})`);
     const createResult = await this.eventProviderService.create(providerData);
     if (!createResult.success) {
       const errorMsg = `Failed to create event provider: ${createResult.error}`;
@@ -5559,8 +5553,7 @@ ${JSON.stringify(providerData, null, 2)}`
         workspace_configuration: JSON.stringify(workspaceConfig)
       };
       this.customLogger.debug(
-        `[DEBUG] Updating configuration with payload:
-${JSON.stringify(updateConfigPayload, null, 2)}`
+        `[DEBUG] Updating workspace configuration for merchant: ${this.merchantId}`
       );
       const updateResult = await this.eventConfigurationService.update(updateConfigPayload);
       if (!updateResult.success) {
@@ -5619,6 +5612,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 +5625,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 +5638,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 +5695,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,
@@ -5727,10 +5728,7 @@ var _OnboardCommerce = class _OnboardCommerce {
         for (const commerceEvent of needsSubscription) {
           try {
             const preparedEvent = this.prepareEventPayload(commerceEvent, provider.id);
-            this.customLogger.debug(
-              `[DEBUG] Subscribing to event with payload:
-${JSON.stringify(preparedEvent.event, null, 2)}`
-            );
+            this.customLogger.debug(`[DEBUG] Subscribing to event: ${commerceEvent.event.name}`);
             const eventSubscribeResult = await this.eventSubscriptionService.create(
               preparedEvent.event
             );
@@ -5752,6 +5750,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 +5816,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 +5836,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;
   }
   /**