v3.0.0

What's Changed

Multi-event provider support

This release introduces support for multi-event providers. This enables multiple App Builder based Commerce extensions to connect to the same Adobe Commerce instance using isolated event providers. This isolation:

• Prevents one application from overriding the event provider registered by another application.
• Ensures that event subscriptions created by one application do not interfere with those created by another.

OpenTelemetry support

• Integrate observability into App Builder actions.
• Configure Grafana and New Relic with App Builder runtime actions.

Breaking Changes

• The onboard script will no longer set the created event provider as the default; it will add it as a non-default event provider in the commerce instance.
• The script now updates only the merchant_id, environment_id, and workspace_configuration in the commerce instance.
• It also updates the .env file with BACKOFFICE_PROVIDER_ID and COMMERCE_PROVIDER_ID.
• The EVENT_PREFIX environment variable needs to be updated.

Migration Guide

Users upgrading from v2.x should use the commerce-eventing 1.12.1 or higher

1. Code Changes

• Added APIs to add and get event providers from the commerce instance in scripts/lib/commerce-eventing-api-client.js.
• Enhanced the updateConfiguration API to update only merchant_id, environment_id, and workspace_configuration in the commerce instance. Previously, it also updated provider_id and instance_id, which is no longer supported.
• Updated scripts/lib/event-subscribe.js to include EVENT_PREFIX and COMMERCE_PROVIDER_ID for each event during subscription.

2. Testing and Validation

1. Event Testing

   • Test event generation and reception
   • Verify all subscribed events are being received
   • Check event payload structure matches expectations

2. API Testing

   • Test all API endpoints used by your integration
   • Verify response formats and error handling
   • Test rate limiting and retry mechanisms

3. Rollback Plan

1. Backup Configuration

   • Keep a backup of your current .env file
   • Save current API client configurations

2. Rollback Steps

   • Revert to previous .env configuration
   • Revert to previous version v2.0.0 of integration-starter-kit

Support

If you encounter any issues during the migration:

1. Check the documentation
2. Review the updated README.md for new configuration options.
3. Open an issue in the GitHub repository with detailed information about the problem
   For detailed migration instructions, please refer to the updated documentation in the README.md file.

Full Changelog: v2.0.0...v3.0.0

v2.0.0

What's Changed

ACCS Compatibility

This release introduces compatibility with Adobe Commerce Cloud Services (ACCS), bringing significant improvements to the integration capabilities:

• Added new authentication system with IMS integration
• Implemented new commerce-sdk-auth package for improved authentication handling
• Updated API clients to support ACCS authentication
• Enhanced security with improved OAuth1a implementation
• Added TypeScript support with new tsconfig configurations

Bug Fixes

• Fixed broken link to dev docs (#32)
• Resolved issue with missing COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID environment variable (#27)
• Added missing return statement in code (#22)
• Fixed shipment examples to use correct endpoint (POST /order/{orderId}/ship) (#18)

Breaking Changes

• This release requires updates to authentication configuration due to ACCS compatibility
• Environment variables may need to be updated to support new authentication methods
• Some API endpoints may have changed to align with ACCS standards

Migration Guide

Users upgrading from v1.x should:

1. Authentication System Update

For PaaS (On-Premise/Cloud) Users

1. Verify Existing OAuth1 Configuration
   • Ensure your existing OAuth1 credentials are still valid
   • Check that your COMMERCE_BASE_URL follows the correct format:

     https://[environment-name].us-4.magentosite.cloud/rest/
     

   • Verify these environment variables are set in your .env file:

     COMMERCE_CONSUMER_KEY=
     COMMERCE_CONSUMER_SECRET=
     COMMERCE_ACCESS_TOKEN=
     COMMERCE_ACCESS_TOKEN_SECRET=
     

For SaaS (ACCS) Users

1. Set Up IMS Authentication
   • Create a new OAuth Server-to-Server credential following the documentation
   • Update your .env file with the new IMS credentials:

     OAUTH_CLIENT_ID=<your-client-id>
     OAUTH_CLIENT_SECRET=<your-client-secret>
     OAUTH_TECHNICAL_ACCOUNT_ID=<your-technical-account-id>
     OAUTH_TECHNICAL_ACCOUNT_EMAIL=<your-technical-account-email>
     OAUTH_ORG_ID=<your-org-id>
     OAUTH_SCOPES=AdobeID,openid,read_organizations,additional_info.projectedProductContext,additional_info.roles,adobeio_api,read_client_secret,manage_client_secrets,event_receiver_api
     

   • Update your COMMERCE_BASE_URL to use the ACCS format:

     https://na1-sandbox.api.commerce.adobe.com/[tenant-id]/
     

   • Remove or comment out the OAuth1 variables from your .env file:

     #COMMERCE_CONSUMER_KEY=
     #COMMERCE_CONSUMER_SECRET=
     #COMMERCE_ACCESS_TOKEN=
     #COMMERCE_ACCESS_TOKEN_SECRET=
     

2. Code Updates

1. Update Dependencies

   • Run npm install to update to the latest dependencies
   • Verify the following packages are updated:
     • axios: 1.7.9
     • micromatch: 4.0.8
     • cross-spawn: 7.0.6
     • fast-xml-parser: 4.5.1

2. Review API Client Changes

   • Check the updated API clients in:
     • actions/customer/commerce-customer-api-client.js
     • actions/order/commerce-order-api-client.js
     • actions/product/commerce-product-api-client.js
     • actions/stock/commerce-stock-api-client.js
   • Update any custom implementations that extend these clients

3. Update TypeScript Configuration

   • If using TypeScript, review the new configuration files:
     • tsconfig.cjs.json
     • tsconfig.es.json
     • tsconfig.types.json
   • Update your project's TypeScript configuration accordingly

4. Testing and Validation

1. Authentication Testing

   • Test both read and write operations to verify authentication is working
   • For SaaS users, verify IMS token generation and usage
   • For PaaS users, verify OAuth1 authentication flow

2. Event Testing

   • Test event generation and reception
   • Verify all subscribed events are being received
   • Check event payload structure matches expectations

3. API Testing

   • Test all API endpoints used by your integration
   • Verify response formats and error handling
   • Test rate limiting and retry mechanisms

5. Rollback Plan

1. Backup Configuration

   • Keep a backup of your current .env file
   • Save current API client configurations

2. Rollback Steps

   • Revert to previous .env configuration
   • Revert to previous API client versions if needed

Support

If you encounter any issues during the migration:

1. Check the documentation
2. Review the updated README.md for new configuration options
3. Open an issue in the GitHub repository with detailed information about the problem
   For detailed migration instructions, please refer to the updated documentation in the README.md file.

Full Changelog: v1.0.2...v2.0.0

v1.0.2

First GA release