@adobe-commerce/aio-toolkit 1.0.5 → 1.0.6

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.6] - 2025-11-11
+
+### 🚀 New Integration Module & API Enhancements
+
+This release introduces the comprehensive OnboardCommerce integration module for Adobe Commerce I/O Events configuration, a new RuntimeApiGatewayService for flexible Runtime API endpoint management, structured logging system with prefixed messages, and the OnboardIOEvents alias with OnboardEvents deprecation for improved naming clarity. All changes maintain backward compatibility while adding powerful new functionality for Adobe Commerce integrations.
+
+#### 🛍️ Commerce Integration Components
+
+- **OnboardCommerce** `[New]` - Complete Adobe Commerce I/O Events configuration orchestration
+  - Automated provider configuration and validation
+  - Event subscription management with conflict detection
+  - Support for multiple commerce events with custom configurations
+  - Intelligent event metadata validation against supported events
+  - Skip duplicate subscriptions automatically
+  - Structured logging with visual indicators (`[START]`, `[CREATE]`, `[SKIP]`, `[ERROR]`)
+  - Comprehensive summary reporting with provider and event statistics
+  - Full TypeScript support with detailed type definitions
+  - 100% test coverage with 1,158+ test cases
+  - Integration with existing Adobe I/O Events infrastructure
+
+#### 🔧 Framework Components
+
+- **RuntimeApiGatewayService** `[New]` - Flexible Adobe I/O Runtime API Gateway client
+  - Centralized service for Runtime API Gateway endpoint management
+  - Automatic IMS token generation and authentication
+  - Built-in authentication headers with organization ID
+  - Support for all HTTP methods (GET, POST, PUT, DELETE)
+  - Flexible endpoint configuration without hardcoded paths
+  - Comprehensive error handling with detailed logging
+  - Integration with ImsToken for token management
+  - CustomLogger integration for consistent logging
+  - Type-safe TypeScript interfaces
+
+- **ImsToken** `[Enhanced]` - Context-specific token management
+  - New `tokenKey` and `tokenContext` constructor parameters
+  - Allows multiple ImsToken instances with different contexts
+  - Prevents token collision for different service integrations
+  - Enhanced caching strategy for multi-service applications
+  - Full backward compatibility maintained
+
+#### 🔗 Integration Components
+
+- **OnboardIOEvents** `[New]` - Renamed alias for OnboardEvents
+  - New recommended export name for improved clarity
+  - Better naming alignment with Adobe I/O Events terminology
+  - Full backward compatibility with OnboardEvents
+  - Identical functionality and API surface
+
+- **OnboardEvents** `[Deprecated]` - Original export marked for future removal
+  - **DEPRECATED**: Use OnboardIOEvents instead
+  - JSDoc `@deprecated` tag added for IDE warnings
+  - Will be removed in a future major version
+  - Migration path documented in README
+  - No breaking changes - both exports work identically
+
+---
+
+### 📚 **Migration Guide**
+
+#### OnboardEvents → OnboardIOEvents
+
+Update your imports to use the new OnboardIOEvents export:
+
+```typescript
+// ❌ Deprecated (will show IDE warning)
+import { OnboardEvents } from '@adobe-commerce/aio-toolkit';
+
+// ✅ Recommended
+import { OnboardIOEvents } from '@adobe-commerce/aio-toolkit';
+```
+
 ## [1.0.5] - 2025-11-03
 
 ### 🚀 API Enhancements, Security & Developer Experience Improvements

package/README.md

@@ -282,6 +282,53 @@ const helloWorldAction = OpenwhiskAction.execute('hello-world', async (params, c
 exports.main = helloWorldAction;
 ```
 
+#### `RuntimeApiGatewayService`
+Flexible Adobe I/O Runtime API Gateway client with automatic IMS token management and authentication.
+
+```typescript
+const { RuntimeApiGatewayService } = require('@adobe-commerce/aio-toolkit');
+
+// Initialize the service
+const apiGatewayService = new RuntimeApiGatewayService(
+  'your-client-id',
+  'your-client-secret',
+  'your-technical-account-id',
+  'your-technical-account-email@example.com',
+  'your-ims-org-id@AdobeOrg',
+  ['openid', 'AdobeID', 'adobeio_api'],
+  'your-namespace-12345',
+  logger // Optional custom logger
+);
+
+// GET request
+const data = await apiGatewayService.get('v1/web/my-package/my-action');
+console.log('Action response:', data);
+
+// POST request with payload
+const result = await apiGatewayService.post('v1/web/my-package/process', {
+  orderId: 'ORD-123',
+  action: 'process'
+});
+
+// PUT request
+const updateResult = await apiGatewayService.put('v1/web/my-package/update', {
+  id: '123',
+  status: 'completed'
+});
+
+// DELETE request
+const deleteResult = await apiGatewayService.delete('v1/web/my-package/remove/123');
+```
+
+**Key Features:**
+- Automatic IMS token generation and caching
+- Built-in authentication headers
+- Support for GET, POST, PUT, DELETE methods
+- Flexible endpoint configuration
+- Comprehensive error handling
+- Integration with ImsToken for token management
+- CustomLogger integration
+
 #### `FileRepository`
 File-based storage with CRUD operations for Adobe I/O Runtime applications.
 
@@ -669,6 +716,110 @@ const newCarrier = new ShippingCarrier('ups', (c) => {
 - Empty or whitespace-only codes throw errors
 - Code property cannot be changed after initialization
 
+#### `OnboardCommerce`
+Complete Adobe Commerce I/O Events configuration orchestration with automated provider setup and event subscription management.
+
+```typescript
+const { 
+  OnboardCommerce, 
+  AdobeCommerceClient, 
+  ImsConnection 
+} = require('@adobe-commerce/aio-toolkit');
+const Core = require('@adobe/aio-sdk').Core;
+
+// Initialize Adobe Commerce client
+const connection = new ImsConnection(
+  'client-id',
+  'client-secret',
+  'technical-account-id',
+  'technical-account-email',
+  'ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'],
+  logger
+);
+const adobeCommerceClient = new AdobeCommerceClient(
+  'https://your-commerce-store.com',
+  connection
+);
+
+// Initialize logger
+const logger = Core.Logger('onboard-client', {
+  level: 'debug'
+});
+
+// Initialize OnboardCommerce
+const onboardCommerce = new OnboardCommerce(
+  adobeCommerceClient,
+  process.env.COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID || '',
+  process.env.COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID || '',
+  logger
+);
+
+// Define commerce provider
+const commerceProvider = {
+  raw: {
+    id: 'commerce-provider-id',
+    label: 'Commerce Events Provider',
+    description: 'Provider for Adobe Commerce events',
+    docsUrl: 'https://developer.adobe.com/commerce/events'
+  }
+};
+
+// Define workspace configuration
+const workspaceConfig = {
+  project: {
+    id: process.env.ADOBE_PROJECT_ID,
+    name: 'My Commerce Project',
+    title: 'Commerce Integration'
+  },
+  workspace: {
+    id: process.env.ADOBE_WORKSPACE_ID,
+    name: 'Production'
+  }
+};
+
+// Define commerce events configuration
+const commerceEventsConfig = [
+  {
+    event: {
+      name: 'com.adobe.commerce.observer.catalog_product_save_after',
+      label: 'Product Saved',
+      description: 'Triggered when a product is saved'
+    }
+  },
+  {
+    event: {
+      name: 'com.adobe.commerce.observer.sales_order_save_after',
+      label: 'Order Saved',
+      description: 'Triggered when an order is saved'
+    }
+  }
+];
+
+// Execute configuration
+const result = await onboardCommerce.process(
+  commerceProvider.raw,
+  workspaceConfig,
+  commerceEventsConfig
+);
+
+if (result.success) {
+  console.log('✅ Commerce events configured successfully');
+  console.log(`Provider: ${result.provider?.label}`);
+} else {
+  console.error('❌ Configuration failed:', result.error);
+}
+```
+
+**Key Features:**
+- 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]`
+- Comprehensive summary reporting with event subscription statistics
+- Integration with Adobe Commerce API for event discovery
+- 100% test coverage
+
 ### 🎨 Experience Components
 
 **Adobe Commerce Admin UI extension and user experience tools**
@@ -837,13 +988,16 @@ await InfiniteLoopBreaker.storeFingerPrint(
 );
 ```
 
-#### `OnboardEvents`
+#### `OnboardIOEvents` (formerly `OnboardEvents`)
 Complete onboarding orchestration for Adobe I/O Events (providers, metadata, and registrations).
 
+> **Note**: `OnboardEvents` is deprecated and will be removed in v2.0.0. Please use `OnboardIOEvents` instead.
+
 ```typescript
-const { OnboardEvents } = require('@adobe-commerce/aio-toolkit');
+const { OnboardIOEvents } = require('@adobe-commerce/aio-toolkit');
 
-const onboardEvents = new OnboardEvents(
+// ✅ Recommended - Use OnboardIOEvents
+const onboardEvents = new OnboardIOEvents(
   'My E-commerce Store',
   process.env.ADOBE_CONSUMER_ID!,
   process.env.ADOBE_PROJECT_ID!,

package/dist/index.d.mts

@@ -231,6 +231,46 @@ declare class WebhookActionResponse {
     static remove(path: string): WebhookActionRemoveResponse;
 }
 
+interface ImsTokenResult {
+    token: string | null;
+    expire_in: number;
+}
+
+declare class ImsToken {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly technicalAccountId;
+    private readonly technicalAccountEmail;
+    private readonly imsOrgId;
+    private readonly scopes;
+    private readonly customLogger;
+    private state;
+    private readonly tokenContext;
+    private readonly key;
+    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, logger?: any, cacheKey?: string, tokenContext?: string);
+    execute(): Promise<string | null>;
+    getImsToken(): Promise<ImsTokenResult | null>;
+    setValue(result: ImsTokenResult): Promise<boolean>;
+    getValue(): Promise<string | null>;
+    getState(): Promise<any>;
+}
+
+declare class RuntimeApiGatewayService {
+    private static readonly BASE_URL;
+    private readonly namespace;
+    private readonly imsOrgId;
+    private readonly imsToken;
+    private readonly restClient;
+    private readonly customLogger;
+    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, namespace: string, logger?: any);
+    private buildEndpoint;
+    private getAuthenticatedHeaders;
+    get(endpoint: string, additionalHeaders?: Record<string, string>): Promise<any>;
+    post(endpoint: string, payload: any, additionalHeaders?: Record<string, string>): Promise<any>;
+    put(endpoint: string, payload: any, additionalHeaders?: Record<string, string>): Promise<any>;
+    delete(endpoint: string, additionalHeaders?: Record<string, string>): Promise<any>;
+}
+
 interface BearerTokenInfo {
     token: string | null;
     tokenLength: number;
@@ -443,10 +483,6 @@ declare class InfiniteLoopBreaker {
     private static fingerPrint;
 }
 
-declare class AdobeAuth {
-    static getToken(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: string[], currentContext?: string): Promise<string>;
-}
-
 interface Connection {
     extend: (client: Got) => Promise<Got>;
 }
@@ -472,6 +508,120 @@ declare class AdobeCommerceClient {
     private getHttpClient;
 }
 
+declare const IoEventsGlobals: {
+    readonly BASE_URL: "https://api.adobe.io";
+    readonly STATUS_CODES: {
+        readonly OK: 200;
+        readonly BAD_REQUEST: 400;
+        readonly UNAUTHORIZED: 401;
+        readonly FORBIDDEN: 403;
+        readonly NOT_FOUND: 404;
+        readonly REQUEST_TIMEOUT: 408;
+        readonly TIMEOUT: 408;
+        readonly CONFLICT: 409;
+        readonly INTERNAL_SERVER_ERROR: 500;
+    };
+    readonly HEADERS: {
+        readonly CONFLICTING_ID: "x-conflicting-id";
+    };
+};
+interface HALLink {
+    href: string;
+    templated?: boolean;
+    type?: string;
+    title?: string;
+}
+interface IOEventsError {
+    error?: string;
+    message?: string;
+    error_code?: string;
+    details?: string;
+}
+declare class IOEventsApiError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string | undefined;
+    readonly details: string | undefined;
+    constructor(message: string, statusCode: number, errorCode?: string, details?: string);
+}
+
+interface Provider {
+    id: string;
+    label: string;
+    description: string;
+    source: string;
+    docs_url?: string;
+    provider_metadata: string;
+    instance_id?: string;
+    event_delivery_format: string;
+    publisher: string;
+    _links?: {
+        'rel:eventmetadata'?: HALLink;
+        'rel:update'?: HALLink;
+        self?: HALLink;
+    };
+}
+
+interface OnboardCommerceConfig {
+    adobeCommerceClient: AdobeCommerceClient;
+    merchantId: string;
+    environmentId: string;
+    logger?: any;
+}
+interface CommerceEventField {
+    name: string;
+}
+interface CommerceEvent {
+    name: string;
+    fields: CommerceEventField[];
+}
+interface CommerceEventConfig {
+    event: CommerceEvent;
+}
+interface WorkspaceConfig {
+    project: {
+        id: string;
+        name: string;
+        title: string;
+        org: {
+            id: string;
+            name: string;
+            ims_org_id: string;
+        };
+        workspace: {
+            id: string;
+            name: string;
+            title: string;
+            action_url: string;
+            app_url: string;
+            details?: any;
+        };
+    };
+}
+interface OnboardCommerceResult {
+    success: boolean;
+    message: string;
+    error?: string;
+}
+
+declare class OnboardCommerce {
+    private readonly adobeCommerceClient;
+    private readonly merchantId;
+    private readonly environmentId;
+    private readonly customLogger;
+    private readonly configureProvider;
+    private readonly eventSubscriptionService;
+    private readonly eventService;
+    constructor(adobeCommerceClient: AdobeCommerceClient, merchantId: string, environmentId: string, logger?: any);
+    process(provider: Provider, workspaceConfig: WorkspaceConfig, commerceEventsConfig?: CommerceEventConfig[]): Promise<any>;
+    private filterEventsBySubscriptionStatus;
+    private prepareEventPayload;
+    private logEventSubscriptionSummary;
+}
+
+declare class AdobeAuth {
+    static getToken(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: string[], currentContext?: string): Promise<string>;
+}
+
 declare class BasicAuthConnection implements Connection {
     private baseUrl;
     private username;
@@ -597,59 +747,6 @@ interface AdobeIMSConfig {
     scopes: string[];
 }
 
-declare const IoEventsGlobals: {
-    readonly BASE_URL: "https://api.adobe.io";
-    readonly STATUS_CODES: {
-        readonly OK: 200;
-        readonly BAD_REQUEST: 400;
-        readonly UNAUTHORIZED: 401;
-        readonly FORBIDDEN: 403;
-        readonly NOT_FOUND: 404;
-        readonly REQUEST_TIMEOUT: 408;
-        readonly TIMEOUT: 408;
-        readonly CONFLICT: 409;
-        readonly INTERNAL_SERVER_ERROR: 500;
-    };
-    readonly HEADERS: {
-        readonly CONFLICTING_ID: "x-conflicting-id";
-    };
-};
-interface HALLink {
-    href: string;
-    templated?: boolean;
-    type?: string;
-    title?: string;
-}
-interface IOEventsError {
-    error?: string;
-    message?: string;
-    error_code?: string;
-    details?: string;
-}
-declare class IOEventsApiError extends Error {
-    readonly statusCode: number;
-    readonly errorCode: string | undefined;
-    readonly details: string | undefined;
-    constructor(message: string, statusCode: number, errorCode?: string, details?: string);
-}
-
-interface Provider {
-    id: string;
-    label: string;
-    description: string;
-    source: string;
-    docs_url?: string;
-    provider_metadata: string;
-    instance_id?: string;
-    event_delivery_format: string;
-    publisher: string;
-    _links?: {
-        'rel:eventmetadata'?: HALLink;
-        'rel:update'?: HALLink;
-        self?: HALLink;
-    };
-}
-
 interface GetProviderQueryParams {
     eventmetadata?: boolean;
 }
@@ -821,4 +918,4 @@ declare class AdminUiSdk {
     getRegistration(): AdminUiSdkRegistration;
 }
 
-export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, Openwhisk, OpenwhiskAction, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, type SuccessResponse, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse };
+export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type CommerceEvent, type CommerceEventConfig, type CommerceEventField, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, ImsToken, type ImsTokenResult, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardCommerce, type OnboardCommerceConfig, type OnboardCommerceResult, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, OnboardEvents as OnboardIOEvents, Openwhisk, OpenwhiskAction, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, RuntimeApiGatewayService, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, type SuccessResponse, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse, type WorkspaceConfig };