@adobe-commerce/aio-toolkit 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,96 @@ 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
+
+This minor release introduces significant enhancements to core framework components, resolving critical issues and adding comprehensive new functionality. Both changes maintain full backward compatibility while substantially improving developer experience and API integration capabilities.
+
+#### 🔧 Framework Components
+
+- **FileRepository** `[Enhanced]` - Optional ID parameter support and standardized file management
+  - Optional ID parameter in save method: `save(payload, id?)` signature
+  - ID parameter takes precedence over payload.id property  
+  - Automatic ID sanitization (alphanumeric + underscore characters only)
+  - Fallback to timestamp-based ID generation for invalid inputs
+  - Enhanced return value: method now returns sanitized filename string instead of boolean
+  - Standardized date formatting with ISO 8601 format for all timestamps
+  - Property naming consistency: `created_at` → `createdAt`, `updated_at` → `updatedAt`
+  - String-only ID handling across all methods with comprehensive error handling
+  - Enhanced type safety with null return values on failures
+
+#### 🔗 Integration Components
+
+- **RestClient** `[Enhanced]` - Comprehensive payload type support resolving critical compatibility issues
+  - URLSearchParams support for form-encoded requests (resolves Issue #40)
+  - FormData support for file uploads and multipart request handling
+  - String payload support for text and XML request transmission  
+  - Binary data support for Buffer, ArrayBuffer, and Uint8Array objects
+  - Smart Content-Type management with user header preservation
+  - Intelligent Content-Type defaults per payload type when not specified
+  - Full backward compatibility maintained for existing JSON usage
+  - Enhanced OAuth2 authentication flow support and form-based API integrations
+
+#### 🐛 Critical Bug Fixes
+
+- **Issue #41 - FileRepository Save Method Enhancement** `[Resolved]`
+  - **Problem**: Missing ID parameter support, incorrect return type, inconsistent date formatting
+  - **Solution**: Complete method signature overhaul with flexible ID handling and proper return types
+  - **Impact**: Enables advanced file management workflows with explicit ID control
+
+- **Issue #40 - RestClient URLSearchParams Failure** `[Resolved]`  
+  - **Problem**: `makeRequest()` failed with 405 Method Not Allowed for form-encoded POST requests
+  - **Root Cause**: Always JSON.stringify() payloads and forced 'application/json' Content-Type
+  - **Solution**: Intelligent payload type detection with appropriate serialization and headers
+  - **Impact**: Enables OAuth2 authentication flows and form-based API integrations
+
 ## [1.0.1] - 2025-09-22
 
 ### 🚀 Enhanced Developer Experience & API Improvements

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.
 
@@ -180,7 +229,7 @@ exports.main = helloWorldAction;
 File-based storage with CRUD operations for Adobe I/O Runtime applications.
 
 **Key Methods:**
-- `save(payload)`: Saves data as a single object parameter. Include `id` in the payload for explicit ID, or omit it for auto-generated timestamp ID.
+- `save(payload, id?)`: Saves data with optional ID parameter. The `id` parameter takes precedence over `payload.id`. IDs are automatically sanitized to alphanumeric + underscore characters.
 - `load(id)`: Loads data by ID
 - `list()`: Lists all stored records
 - `delete(ids)`: Deletes records by ID array
@@ -244,7 +293,7 @@ exports.main = RuntimeAction.execute(
 ```
 
 ##### **4. Save Action**
-Save entity data with proper parameter handling:
+Save entity data with flexible ID handling using the new optional ID parameter:
 
 ```javascript
 const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
@@ -263,15 +312,22 @@ exports.main = RuntimeAction.execute(
     async (params) => {
         const entityRepository = new EntityRepository();
 
+        // Build payload with required fields
         let payload = {};
         for (const fieldName in requiredParams) {
             payload[requiredParams[fieldName]] = params[requiredParams[fieldName]];
         }
-        if (Object.prototype.hasOwnProperty.call(params, 'id')) {
-            payload['id'] = params['id'];
-        }
 
-        return RuntimeActionResponse.success((await entityRepository.save(payload)).toString());
+        // Extract ID parameter for prioritized handling
+        const explicitId = params.id || params.customId || null;
+        
+        // Save with optional ID parameter - it takes precedence over payload.id
+        const savedId = await entityRepository.save(payload, explicitId);
+
+        return RuntimeActionResponse.success({
+            id: savedId,
+            message: 'Entity saved successfully'
+        });
     }
 );
 ```
@@ -297,9 +353,11 @@ exports.main = RuntimeAction.execute(
 
 This approach provides:
 - **Separation of concerns**: Each CRUD operation has its own action file
-- **Reusable repository**: Custom repository can be shared across actions
+- **Reusable repository**: Custom repository can be shared across actions  
 - **Proper validation**: Required parameters and headers are enforced
 - **Consistent responses**: All actions use RuntimeActionResponse for standardized output
+- **Flexible ID management**: Support for explicit IDs, payload IDs, and auto-generation
+- **Automatic sanitization**: IDs are cleaned to ensure file system compatibility
 
 ### 🏪 Commerce Components  
 
@@ -327,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
@@ -352,16 +496,63 @@ const newProduct = await client.post('rest/V1/products', {}, productData);
 **External API integration and utility functions**
 
 #### `RestClient`
-HTTP client for external API integration.
+HTTP client for external API integration with support for various payload types.
 
+**Basic Usage**
 ```typescript
 const { RestClient } = require('@adobe-commerce/aio-toolkit');
 
 const client = new RestClient();
+
+// GET request
 const response = await client.get('https://api.example.com/data', {
-  'Authorization': 'Bearer token',
-  'Content-Type': 'application/json'
+  'Authorization': 'Bearer token'
+});
+```
+
+**JSON Payloads (default)**
+```typescript
+// POST with JSON (automatic Content-Type: application/json)
+const jsonData = { name: 'Product', price: 99.99 };
+const response = await client.post('https://api.example.com/products', {
+  'Authorization': 'Bearer token'
+}, jsonData);
+```
+
+**Form-Encoded Requests**
+```typescript
+// URLSearchParams for form-encoded data (automatic Content-Type: application/x-www-form-urlencoded)
+const formData = new URLSearchParams({
+  grant_type: 'client_credentials',
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret'
 });
+
+const tokenResponse = await client.post('https://auth.example.com/token', {
+  Accept: 'application/json'
+}, formData);
+```
+
+**File Upload**
+```typescript
+// FormData for file uploads (Content-Type boundary handled automatically)
+const uploadData = new FormData();
+uploadData.append('file', fileBuffer, 'document.pdf');
+uploadData.append('description', 'Important document');
+
+const uploadResponse = await client.post('https://api.example.com/upload', {
+  'Authorization': 'Bearer token'
+}, uploadData);
+```
+
+**Text/XML Payloads**
+```typescript
+// String payloads with custom content type
+const xmlData = '<?xml version="1.0"?><order><id>123</id></order>';
+const xmlResponse = await client.post('https://api.example.com/orders', {
+  'Authorization': 'Bearer token',
+  'Content-Type': 'application/xml'
+}, xmlData);
 ```
 
 #### `BearerToken`

package/dist/index.d.mts

@@ -121,9 +121,9 @@ declare class OpenwhiskAction {
 }
 
 interface FileRecord {
-    id: string | number;
-    created_at: string;
-    updated_at: string;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
     [key: string]: any;
 }
 
@@ -133,11 +133,33 @@ declare class FileRepository {
     constructor(filepath: string);
     list(): Promise<FileRecord[]>;
     load(id?: string): Promise<FileRecord>;
-    save(payload?: Partial<FileRecord>): Promise<boolean>;
-    delete(ids?: (string | number)[]): Promise<FileRecord[]>;
+    save(payload?: Partial<FileRecord>, id?: string | null): Promise<string | null>;
+    delete(ids?: string[]): Promise<FileRecord[]>;
+    private sanitizeFileId;
     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;
@@ -401,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>;
 }
 
@@ -422,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>;
@@ -631,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

@@ -121,9 +121,9 @@ declare class OpenwhiskAction {
 }
 
 interface FileRecord {
-    id: string | number;
-    created_at: string;
-    updated_at: string;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
     [key: string]: any;
 }
 
@@ -133,11 +133,33 @@ declare class FileRepository {
     constructor(filepath: string);
     list(): Promise<FileRecord[]>;
     load(id?: string): Promise<FileRecord>;
-    save(payload?: Partial<FileRecord>): Promise<boolean>;
-    delete(ids?: (string | number)[]): Promise<FileRecord[]>;
+    save(payload?: Partial<FileRecord>, id?: string | null): Promise<string | null>;
+    delete(ids?: string[]): Promise<FileRecord[]>;
+    private sanitizeFileId;
     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;
@@ -401,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>;
 }
 
@@ -422,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>;
@@ -631,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 };