@adobe-commerce/aio-toolkit 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.3] - 2025-10-23
+
+### 🎨 New Experience Module & Enhanced Framework Components
+
+This patch release introduces a comprehensive new Experience module with AdminUiSdk for Adobe Commerce Admin UI extensions, enhanced IMS token caching with State library integration, Adobe I/O event publishing capabilities with CloudEvents compliance, and critical bug fixes for authentication endpoints. All changes maintain backward compatibility while adding powerful new functionality.
+
+#### 🎨 Experience Components
+
+- **AdminUiSdk** `[New]` - Adobe Commerce Admin UI extension management
+  - Create and manage menu items, sections, and page configurations programmatically
+  - Full namespaced ID support (e.g., `dataMappingTool::appBuilderApplication`)
+  - Parent-child menu relationships with external references (`Magento_Backend::system`)
+  - Comprehensive validation and error handling with detailed error messages
+  - Type-safe TypeScript interfaces for MenuItem, Page, and AdminUiSdkRegistration
+  - **BREAKING CHANGE**: Accepts full IDs without automatic prefixing for real-world usage patterns
+
+#### 🔧 Framework Components
+
+- **CustomLogger** `[New]` - Centralized null-safe logging utility
+  - Consistent logging interface with debug, info, and error methods across all components
+  - Graceful handling of missing or null logger instances without throwing errors
+  - Seamless integration with Adobe I/O Runtime logger
+
+- **PublishEvent** `[New]` - Adobe I/O Event Publishing with CloudEvents compliance
+  - CloudEvents specification compliance with proper event structure
+  - UUID generation for unique event tracking and correlation
+  - Comprehensive validation for IMS organization ID, API keys, and access tokens
+  - Integration with CustomLogger for consistent error handling and debugging
+  - Support for custom event subjects and structured payload data
+
+#### 🛠️ Commerce Components
+
+- **GenerateImsToken** `[Enhanced]` - IMS token caching using Adobe I/O State library
+  - Automatic token caching and refresh using Adobe I/O State library for performance optimization
+  - Token validation and automatic renewal before expiration
+  - Enhanced error handling and logging for token operations
+  - **BREAKING CHANGE**: ImsConnection constructor simplified - no longer requires currentContext parameter
+
+#### 🐛 Critical Bug Fixes
+
+- **BasicAuthConnection Token Endpoint Construction** `[Resolved]`
+  - **Problem**: Duplicate `/rest/rest/` segments in token endpoints for base URLs ending with '/rest'
+  - **Root Cause**: Improper URL concatenation when base URL already contained REST endpoint path
+  - **Solution**: Enhanced createTokenEndpoint() method with intelligent URL parsing and construction
+  - **Impact**: Correct token endpoint generation for all base URL formats, maintaining backward compatibility
+
 ## [1.0.2] - 2025-09-30
 
 ### 🛠️ Framework Component Enhancements & Critical Bug Fixes

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage.
+A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage and enterprise-grade reliability.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install @adobe-commerce/aio-toolkit
 
 ## Usage
 
-The toolkit is organized into four main modules:
+The toolkit is organized into five main modules:
 
 ### 🛠️ Framework Components
 
@@ -91,6 +91,55 @@ const myEventConsumer = EventConsumerAction.execute(
 exports.main = myEventConsumer;
 ```
 
+#### `PublishEvent`
+Event publishing component for Adobe I/O Events with CloudEvents support.
+
+```typescript
+const { PublishEvent } = require('@adobe-commerce/aio-toolkit');
+
+// Initialize the publisher
+const publishEvent = new PublishEvent(
+  'your-ims-org-id@AdobeOrg',
+  'your-api-key',
+  'your-access-token',
+  logger // Optional custom logger
+);
+
+// Publish a simple event
+const result = await publishEvent.execute(
+  'your-provider-id',
+  'commerce.order.created',
+  {
+    orderId: 'ORD-123456',
+    customerId: 'CUST-789',
+    amount: 199.99,
+    currency: 'USD'
+  }
+);
+
+console.log(`Event published: ${result.eventId}, Status: ${result.status}`);
+
+// Publish an event with subject
+const orderResult = await publishEvent.execute(
+  'commerce-provider',
+  'com.adobe.commerce.order.shipped',
+  {
+    orderId: 'ORD-123456',
+    trackingNumber: 'TRK-789',
+    carrier: 'UPS',
+    estimatedDelivery: '2023-12-05T18:00:00Z'
+  },
+  'orders/ORD-123456'
+);
+
+// Handle publishing results
+if (orderResult.status === 'published') {
+  console.log(`Order shipped event published successfully: ${orderResult.eventId}`);
+} else {
+  console.error(`Failed to publish event: ${orderResult.error}`);
+}
+```
+
 #### `GraphQlAction`
 GraphQL server implementation with schema validation and introspection control.
 
@@ -336,24 +385,110 @@ console.log('Authentication token:', token);
 #### `AdobeCommerceClient`
 HTTP client for Adobe Commerce API integration with multiple authentication methods.
 
+**OAuth 1.0a Authentication**
 ```typescript
-const { AdobeCommerceClient } = require('@adobe-commerce/aio-toolkit');
-const { Oauth1aConnection } = require('@adobe-commerce/aio-toolkit');
+const { AdobeCommerceClient, Oauth1aConnection } = require('@adobe-commerce/aio-toolkit');
 
 const connection = new Oauth1aConnection(
   'consumer-key',
   'consumer-secret',
   'access-token',
   'access-token-secret',
-  logger? // Optional custom logger
+  logger // Optional custom logger
 );
 
 // Create client
+const client = new AdobeCommerceClient('https://your-commerce-store.com/rest', connection);
+
+// Make API calls
+const products = await client.get('V1/products');
+const newProduct = await client.post('V1/products', {}, productData);
+```
+
+**IMS (Identity Management System) Authentication**
+```typescript
+const { AdobeCommerceClient, ImsConnection } = require('@adobe-commerce/aio-toolkit');
+
+const connection = new ImsConnection(
+  'client-id',
+  'client-secret', 
+  'technical-account-id',
+  'technical-account-email',
+  'ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'], // Scopes array
+  logger // Optional custom logger
+);
+
+// Create client with IMS authentication
 const client = new AdobeCommerceClient('https://your-commerce-store.com', connection);
 
+// Make API calls - tokens are automatically cached and refreshed
+const products = await client.get('V1/products');
+const newProduct = await client.post('V1/products', {}, productData);
+```
+
+**Enhanced IMS Token Caching**
+
+```typescript
+const { GenerateImsToken } = require('@adobe-commerce/aio-toolkit');
+
+const tokenGenerator = new GenerateImsToken(
+  'client-id', 'client-secret', 'technical-account-id',
+  'technical-account-email', 'ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'], logger
+);
+
+const token = await tokenGenerator.execute();
+```
+
+**Basic Authentication**
+```typescript
+const { AdobeCommerceClient, BasicAuthConnection } = require('@adobe-commerce/aio-toolkit');
+
+const connection = new BasicAuthConnection(
+  'username',
+  'password',
+  logger // Optional custom logger
+);
+
+// Create client
+const client = new AdobeCommerceClient('https://your-commerce-store.com/rest', connection);
+
 // Make API calls
-const products = await client.get('rest/V1/products');
-const newProduct = await client.post('rest/V1/products', {}, productData);
+const products = await client.get('V1/products');
+```
+
+### 🎨 Experience Components
+
+**Adobe Commerce Admin UI extension and user experience tools**
+
+#### `AdminUiSdk`
+Create and manage Adobe Commerce Admin UI extensions with menu items, sections, and page configurations.
+
+```typescript
+const { AdminUiSdk } = require('@adobe-commerce/aio-toolkit');
+
+const sdk = new AdminUiSdk('dataMappingTool');
+
+// Add menu section with external parent
+sdk.addMenuSection(
+  'dataMappingTool::checkout_integration',
+  'Checkout Integration',
+  100,
+  'Magento_Backend::system'
+);
+
+// Add menu item
+sdk.addMenuItem(
+  'dataMappingTool::application',
+  'Application',
+  1,
+  'dataMappingTool::checkout_integration'
+);
+
+// Set page title and get registration
+sdk.addPage('Data Mapping Tool Dashboard');
+const registration = sdk.getRegistration();
 ```
 
 ### 🔗 Integration Components

package/dist/index.d.mts

@@ -139,6 +139,27 @@ declare class FileRepository {
     private getFiles;
 }
 
+interface EventData {
+    type: string;
+    data: any;
+    subject?: string;
+}
+interface PublishEventResult {
+    eventId: string;
+    status: 'published' | 'failed';
+    publishedAt: string;
+    error?: string;
+}
+
+declare class PublishEvent {
+    private readonly imsOrgId;
+    private readonly apiKey;
+    private readonly accessToken;
+    private readonly customLogger;
+    constructor(imsOrgId: string, apiKey: string, accessToken: string, logger?: any);
+    execute(providerId: string, eventCode: string, payload: any, subject?: string): Promise<PublishEventResult>;
+}
+
 interface BearerTokenInfo {
     token: string | null;
     tokenLength: number;
@@ -402,9 +423,8 @@ declare class ImsConnection implements Connection {
     private technicalAccountEmail;
     private imsOrgId;
     private scopes;
-    private logger;
-    private currentContext;
-    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, logger?: any, currentContext?: string);
+    private customLogger;
+    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, logger?: any);
     extend(commerceGot: any): Promise<any>;
 }
 
@@ -423,6 +443,7 @@ declare class GenerateBasicAuthToken {
     constructor(baseUrl: string, username: string, password: string, logger?: any);
     execute(): Promise<string | null>;
     getCommerceToken(): Promise<TokenResult | null>;
+    createTokenEndpoint(): string;
     createEndpoint(endpoint: string): string;
     setValue(result: TokenResult): Promise<boolean>;
     getValue(): Promise<string | null>;
@@ -632,4 +653,34 @@ interface GetRegistrationQueryParams {
     registrationId: string;
 }
 
-export { AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, 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, Oauth1aConnection, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, Openwhisk, OpenwhiskAction, Parameters, type Provider, type ProviderInputModel, ProviderManager, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, type SuccessResponse, type TokenResult, Validator };
+interface MenuItem {
+    id: string;
+    title: string;
+    sortOrder: number;
+    parent?: string;
+    isSection?: boolean;
+}
+interface Page {
+    title: string;
+}
+interface AdminUiSdkRegistration {
+    registration: {
+        menuItems?: MenuItem[];
+        page?: Page;
+    };
+}
+
+declare class AdminUiSdk {
+    private extensionId;
+    private menuItems;
+    private pageTitle?;
+    constructor(extensionId: string);
+    private isValidExtensionId;
+    private isValidMenuId;
+    addMenuItem(id: string, title: string, sortOrder: number, parent?: string): void;
+    addMenuSection(id: string, title: string, sortOrder: number, parent?: string): void;
+    addPage(title: string): void;
+    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 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, type SuccessResponse, type TokenResult, Validator };

package/dist/index.d.ts

@@ -139,6 +139,27 @@ declare class FileRepository {
     private getFiles;
 }
 
+interface EventData {
+    type: string;
+    data: any;
+    subject?: string;
+}
+interface PublishEventResult {
+    eventId: string;
+    status: 'published' | 'failed';
+    publishedAt: string;
+    error?: string;
+}
+
+declare class PublishEvent {
+    private readonly imsOrgId;
+    private readonly apiKey;
+    private readonly accessToken;
+    private readonly customLogger;
+    constructor(imsOrgId: string, apiKey: string, accessToken: string, logger?: any);
+    execute(providerId: string, eventCode: string, payload: any, subject?: string): Promise<PublishEventResult>;
+}
+
 interface BearerTokenInfo {
     token: string | null;
     tokenLength: number;
@@ -402,9 +423,8 @@ declare class ImsConnection implements Connection {
     private technicalAccountEmail;
     private imsOrgId;
     private scopes;
-    private logger;
-    private currentContext;
-    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, logger?: any, currentContext?: string);
+    private customLogger;
+    constructor(clientId: string, clientSecret: string, technicalAccountId: string, technicalAccountEmail: string, imsOrgId: string, scopes: Array<string>, logger?: any);
     extend(commerceGot: any): Promise<any>;
 }
 
@@ -423,6 +443,7 @@ declare class GenerateBasicAuthToken {
     constructor(baseUrl: string, username: string, password: string, logger?: any);
     execute(): Promise<string | null>;
     getCommerceToken(): Promise<TokenResult | null>;
+    createTokenEndpoint(): string;
     createEndpoint(endpoint: string): string;
     setValue(result: TokenResult): Promise<boolean>;
     getValue(): Promise<string | null>;
@@ -632,4 +653,34 @@ interface GetRegistrationQueryParams {
     registrationId: string;
 }
 
-export { AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, 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, Oauth1aConnection, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, Openwhisk, OpenwhiskAction, Parameters, type Provider, type ProviderInputModel, ProviderManager, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, type SuccessResponse, type TokenResult, Validator };
+interface MenuItem {
+    id: string;
+    title: string;
+    sortOrder: number;
+    parent?: string;
+    isSection?: boolean;
+}
+interface Page {
+    title: string;
+}
+interface AdminUiSdkRegistration {
+    registration: {
+        menuItems?: MenuItem[];
+        page?: Page;
+    };
+}
+
+declare class AdminUiSdk {
+    private extensionId;
+    private menuItems;
+    private pageTitle?;
+    constructor(extensionId: string);
+    private isValidExtensionId;
+    private isValidMenuId;
+    addMenuItem(id: string, title: string, sortOrder: number, parent?: string): void;
+    addMenuSection(id: string, title: string, sortOrder: number, parent?: string): void;
+    addPage(title: string): void;
+    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 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, type SuccessResponse, type TokenResult, Validator };