@adobe-commerce/aio-toolkit 1.0.2 → 1.0.3

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AdminUiSdk: () => AdminUiSdk,
   AdobeAuth: () => adobe_auth_default,
   AdobeCommerceClient: () => adobe_commerce_client_default,
   BasicAuthConnection: () => basic_auth_connection_default,
@@ -54,6 +55,7 @@ __export(index_exports, {
   OpenwhiskAction: () => openwhisk_action_default,
   Parameters: () => parameters_default,
   ProviderManager: () => provider_default,
+  PublishEvent: () => publish_event_default,
   RegistrationManager: () => registration_default,
   RestClient: () => rest_client_default,
   RuntimeAction: () => runtime_action_default,
@@ -566,6 +568,143 @@ __name(_FileRepository, "FileRepository");
 var FileRepository = _FileRepository;
 var file_repository_default = FileRepository;
 
+// src/framework/publish-event/index.ts
+var import_aio_sdk5 = require("@adobe/aio-sdk");
+var import_cloudevents = require("cloudevents");
+var import_uuid = require("uuid");
+
+// src/framework/custom-logger/index.ts
+var _CustomLogger = class _CustomLogger {
+  /**
+   * @param logger - External logger instance (can be null)
+   */
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+  /**
+   * Log debug message if logger is available
+   * @param message - Debug message to log
+   */
+  debug(message) {
+    if (this.logger && typeof this.logger.debug === "function") {
+      this.logger.debug(message);
+    }
+  }
+  /**
+   * Log info message if logger is available
+   * @param message - Info message to log
+   */
+  info(message) {
+    if (this.logger && typeof this.logger.info === "function") {
+      this.logger.info(message);
+    }
+  }
+  /**
+   * Log error message if logger is available
+   * @param message - Error message to log
+   */
+  error(message) {
+    if (this.logger && typeof this.logger.error === "function") {
+      this.logger.error(message);
+    }
+  }
+  /**
+   * Get the underlying logger instance
+   * @returns the logger instance or null
+   */
+  getLogger() {
+    return this.logger;
+  }
+};
+__name(_CustomLogger, "CustomLogger");
+var CustomLogger = _CustomLogger;
+var custom_logger_default = CustomLogger;
+
+// src/framework/publish-event/index.ts
+var _PublishEvent = class _PublishEvent {
+  /**
+   * Creates a new PublishEvent instance
+   *
+   * @param imsOrgId - Adobe IMS Organization ID
+   * @param apiKey - Adobe API Key (Client ID)
+   * @param accessToken - Adobe Access Token
+   * @param logger - Optional logger instance
+   */
+  constructor(imsOrgId, apiKey, accessToken, logger = null) {
+    if (!imsOrgId?.trim()) {
+      throw new Error("imsOrgId is required and cannot be empty");
+    }
+    if (!apiKey?.trim()) {
+      throw new Error("apiKey is required and cannot be empty");
+    }
+    if (!accessToken?.trim()) {
+      throw new Error("accessToken is required and cannot be empty");
+    }
+    this.imsOrgId = imsOrgId;
+    this.apiKey = apiKey;
+    this.accessToken = accessToken;
+    this.customLogger = new custom_logger_default(logger);
+    this.customLogger.debug("PublishEvent initialized with valid configuration");
+  }
+  /**
+   * Publishes a CloudEvent to Adobe I/O Events
+   *
+   * @param providerId - The Adobe I/O Events provider ID
+   * @param eventCode - The event type identifier (e.g., 'commerce.order.created')
+   * @param payload - The event payload data
+   * @param subject - Optional subject for the event
+   * @returns Promise<PublishEventResult> - The publish result
+   *
+   * @throws Error when providerId or eventCode is invalid or publishing fails
+   */
+  async execute(providerId, eventCode, payload, subject) {
+    try {
+      if (!providerId?.trim()) {
+        throw new Error("providerId is required and cannot be empty");
+      }
+      if (!eventCode?.trim()) {
+        throw new Error("eventCode is required and cannot be empty");
+      }
+      if (payload === null || payload === void 0) {
+        throw new Error("payload is required");
+      }
+      this.customLogger.info(`Publishing event to provider: ${providerId}`);
+      const eventId = (0, import_uuid.v4)();
+      const cloudEvent = new import_cloudevents.CloudEvent({
+        id: eventId,
+        source: `urn:uuid:${providerId}`,
+        datacontenttype: "application/json",
+        type: eventCode,
+        data: payload,
+        ...subject && { subject }
+      });
+      this.customLogger.debug(`Constructed CloudEvent with ID: ${eventId}`);
+      const eventsClient = await import_aio_sdk5.Events.init(this.imsOrgId, this.apiKey, this.accessToken);
+      this.customLogger.debug("Adobe I/O Events client initialized successfully");
+      await eventsClient.publishEvent(cloudEvent);
+      const publishedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.customLogger.info(`Event published successfully with ID: ${eventId}`);
+      return {
+        eventId,
+        status: "published",
+        publishedAt
+      };
+    } catch (error) {
+      this.customLogger.error(`Failed to publish event: ${error.message}`);
+      return {
+        eventId: (0, import_uuid.v4)(),
+        // Generate ID for tracking even failed events
+        status: "failed",
+        publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        error: error.message
+      };
+    }
+  }
+};
+__name(_PublishEvent, "PublishEvent");
+var PublishEvent = _PublishEvent;
+var publish_event_default = PublishEvent;
+
 // src/integration/bearer-token/index.ts
 var _BearerToken = class _BearerToken {
   /**
@@ -883,7 +1022,7 @@ var RestClient = _RestClient;
 var rest_client_default = RestClient;
 
 // src/integration/onboard-events/index.ts
-var import_aio_sdk5 = require("@adobe/aio-sdk");
+var import_aio_sdk6 = require("@adobe/aio-sdk");
 
 // src/io-events/types.ts
 var IoEventsGlobals = {
@@ -4198,7 +4337,7 @@ var _OnboardEvents = class _OnboardEvents {
       throw new Error("Access token is required");
     }
     const loggerName = projectName.toLowerCase().replace(/[^a-z0-9\s-_]/g, "").replace(/\s+/g, "-").replace(/_{2,}/g, "_").replace(/-{2,}/g, "-").trim().concat("-onboard-events");
-    this.logger = import_aio_sdk5.Core.Logger(loggerName, { level: "debug" });
+    this.logger = import_aio_sdk6.Core.Logger(loggerName, { level: "debug" });
     this.createProviders = new create_providers_default(
       consumerId,
       projectId,
@@ -4394,7 +4533,7 @@ var OnboardEvents = _OnboardEvents;
 var onboard_events_default = OnboardEvents;
 
 // src/integration/infinite-loop-breaker/index.ts
-var import_aio_sdk6 = require("@adobe/aio-sdk");
+var import_aio_sdk7 = require("@adobe/aio-sdk");
 var import_crypto2 = __toESM(require("crypto"));
 var _InfiniteLoopBreaker = class _InfiniteLoopBreaker {
   // seconds
@@ -4412,7 +4551,7 @@ var _InfiniteLoopBreaker = class _InfiniteLoopBreaker {
     event
   }) {
     const logLevel = process.env.LOG_LEVEL || "info";
-    const logger = import_aio_sdk6.Core.Logger("infiniteLoopBreaker", { level: logLevel });
+    const logger = import_aio_sdk7.Core.Logger("infiniteLoopBreaker", { level: logLevel });
     logger.debug(`Checking for potential infinite loop for event: ${event}`);
     if (!eventTypes.includes(event)) {
       logger.debug(`Event type ${event} is not in the infinite loop event types list`);
@@ -4420,7 +4559,7 @@ var _InfiniteLoopBreaker = class _InfiniteLoopBreaker {
     }
     const key = typeof keyFn === "function" ? keyFn() : keyFn;
     const data = typeof fingerprintFn === "function" ? fingerprintFn() : fingerprintFn;
-    const state = await import_aio_sdk6.State.init();
+    const state = await import_aio_sdk7.State.init();
     const persistedFingerPrint = await state.get(key);
     if (!persistedFingerPrint) {
       logger.debug(`No persisted fingerprint found for key ${key}`);
@@ -4441,7 +4580,7 @@ var _InfiniteLoopBreaker = class _InfiniteLoopBreaker {
   static async storeFingerPrint(keyFn, fingerprintFn, ttl) {
     const key = typeof keyFn === "function" ? keyFn() : keyFn;
     const data = typeof fingerprintFn === "function" ? fingerprintFn() : fingerprintFn;
-    const state = await import_aio_sdk6.State.init();
+    const state = await import_aio_sdk7.State.init();
     await state.put(key, _InfiniteLoopBreaker.fingerPrint(data), {
       ttl: ttl !== void 0 ? ttl : _InfiniteLoopBreaker.DEFAULT_INFINITE_LOOP_BREAKER_TTL
     });
@@ -4534,7 +4673,7 @@ var AdobeAuth = _AdobeAuth;
 var adobe_auth_default = AdobeAuth;
 
 // src/commerce/adobe-commerce-client/index.ts
-var import_aio_sdk7 = require("@adobe/aio-sdk");
+var import_aio_sdk8 = require("@adobe/aio-sdk");
 var import_got = __toESM(require("got"));
 var _AdobeCommerceClient = class _AdobeCommerceClient {
   /**
@@ -4549,7 +4688,7 @@ var _AdobeCommerceClient = class _AdobeCommerceClient {
     this.baseUrl = baseUrl;
     this.connection = connection;
     if (logger === null) {
-      logger = import_aio_sdk7.Core.Logger("adobe-commerce-client", {
+      logger = import_aio_sdk8.Core.Logger("adobe-commerce-client", {
         level: "debug"
       });
     }
@@ -4676,10 +4815,10 @@ var AdobeCommerceClient = _AdobeCommerceClient;
 var adobe_commerce_client_default = AdobeCommerceClient;
 
 // src/commerce/adobe-commerce-client/basic-auth-connection/index.ts
-var import_aio_sdk9 = require("@adobe/aio-sdk");
+var import_aio_sdk10 = require("@adobe/aio-sdk");
 
 // src/commerce/adobe-commerce-client/basic-auth-connection/generate-basic-auth-token/index.ts
-var import_aio_sdk8 = require("@adobe/aio-sdk");
+var import_aio_sdk9 = require("@adobe/aio-sdk");
 var _GenerateBasicAuthToken = class _GenerateBasicAuthToken {
   /**
    * @param baseUrl
@@ -4693,7 +4832,7 @@ var _GenerateBasicAuthToken = class _GenerateBasicAuthToken {
     this.password = password;
     this.key = "adobe_commerce_basic_auth_token";
     if (logger === null) {
-      logger = import_aio_sdk8.Core.Logger("adobe-commerce-client", {
+      logger = import_aio_sdk9.Core.Logger("adobe-commerce-client", {
         level: "debug"
       });
     }
@@ -4725,7 +4864,7 @@ var _GenerateBasicAuthToken = class _GenerateBasicAuthToken {
    * @return TokenResult | null
    */
   async getCommerceToken() {
-    const endpoint = this.createEndpoint("rest/V1/integration/admin/token");
+    const endpoint = this.createTokenEndpoint();
     this.logger.debug(`Endpoint: ${endpoint}`);
     try {
       const restClient = new rest_client_default();
@@ -4771,6 +4910,19 @@ var _GenerateBasicAuthToken = class _GenerateBasicAuthToken {
       return null;
     }
   }
+  /**
+   * Create the Adobe Commerce integration admin token endpoint.
+   * Handles cases where baseUrl may or may not already include /rest.
+   * @return string
+   */
+  createTokenEndpoint() {
+    const normalizedBaseUrl = this.baseUrl.replace(/\/+$/, "");
+    if (normalizedBaseUrl.endsWith("/rest")) {
+      return `${normalizedBaseUrl}/V1/integration/admin/token`;
+    } else {
+      return `${normalizedBaseUrl}/rest/V1/integration/admin/token`;
+    }
+  }
   /**
    * @param endpoint
    * @return string
@@ -4821,7 +4973,7 @@ var _GenerateBasicAuthToken = class _GenerateBasicAuthToken {
   async getState() {
     if (this.state === void 0) {
       try {
-        this.state = await import_aio_sdk8.State.init();
+        this.state = await import_aio_sdk9.State.init();
       } catch (error) {
         this.logger.debug("State API initialization failed, running without caching");
         this.state = null;
@@ -4847,7 +4999,7 @@ var _BasicAuthConnection = class _BasicAuthConnection {
     this.username = username;
     this.password = password;
     if (logger === null) {
-      logger = import_aio_sdk9.Core.Logger("adobe-commerce-client", {
+      logger = import_aio_sdk10.Core.Logger("adobe-commerce-client", {
         level: "debug"
       });
     }
@@ -4877,7 +5029,7 @@ var BasicAuthConnection = _BasicAuthConnection;
 var basic_auth_connection_default = BasicAuthConnection;
 
 // src/commerce/adobe-commerce-client/oauth1a-connection/index.ts
-var import_aio_sdk10 = require("@adobe/aio-sdk");
+var import_aio_sdk11 = require("@adobe/aio-sdk");
 var import_oauth_1 = __toESM(require("oauth-1.0a"));
 var crypto2 = __toESM(require("crypto"));
 var _Oauth1aConnection = class _Oauth1aConnection {
@@ -4894,7 +5046,7 @@ var _Oauth1aConnection = class _Oauth1aConnection {
     this.accessToken = accessToken;
     this.accessTokenSecret = accessTokenSecret;
     if (logger === null) {
-      logger = import_aio_sdk10.Core.Logger("adobe-commerce-client", {
+      logger = import_aio_sdk11.Core.Logger("adobe-commerce-client", {
         level: "debug"
       });
     }
@@ -4941,8 +5093,161 @@ __name(_Oauth1aConnection, "Oauth1aConnection");
 var Oauth1aConnection = _Oauth1aConnection;
 var oauth1a_connection_default = Oauth1aConnection;
 
+// src/commerce/adobe-commerce-client/ims-connection/generate-ims-token/index.ts
+var import_aio_sdk12 = require("@adobe/aio-sdk");
+var _GenerateImsToken = class _GenerateImsToken {
+  /**
+   * @param clientId
+   * @param clientSecret
+   * @param technicalAccountId
+   * @param technicalAccountEmail
+   * @param imsOrgId
+   * @param scopes
+   * @param logger
+   */
+  constructor(clientId, clientSecret, technicalAccountId, technicalAccountEmail, imsOrgId, scopes, logger = null) {
+    this.key = "adobe_ims_auth_token";
+    this.tokenContext = "adobe-commerce-client";
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.technicalAccountId = technicalAccountId;
+    this.technicalAccountEmail = technicalAccountEmail;
+    this.imsOrgId = imsOrgId;
+    this.scopes = scopes;
+    this.customLogger = new custom_logger_default(logger);
+  }
+  /**
+   * @return string | null
+   */
+  async execute() {
+    try {
+      this.customLogger.info("Starting IMS token generation/retrieval process");
+      const currentValue = await this.getValue();
+      if (currentValue !== null) {
+        this.customLogger.info("Found cached IMS token, returning cached value");
+        return currentValue;
+      }
+      this.customLogger.info("No cached token found, generating new IMS token");
+      let result = {
+        token: null,
+        expire_in: 86399
+        // Default fallback, will be overridden by actual token expiry
+      };
+      const response = await this.getImsToken();
+      if (response !== null) {
+        result = response;
+      }
+      if (result.token !== null) {
+        this.customLogger.info(`Generated new IMS token, caching for ${result.expire_in} seconds`);
+        await this.setValue(result);
+      }
+      return result.token;
+    } catch (error) {
+      this.customLogger.error(`Failed to execute IMS token generation: ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * @return ImsTokenResult | null
+   */
+  async getImsToken() {
+    try {
+      this.customLogger.debug(`Calling AdobeAuth.getToken with context: ${this.tokenContext}`);
+      const token = await adobe_auth_default.getToken(
+        this.clientId,
+        this.clientSecret,
+        this.technicalAccountId,
+        this.technicalAccountEmail,
+        this.imsOrgId,
+        this.scopes,
+        this.tokenContext
+      );
+      if (token !== null && token !== void 0) {
+        this.customLogger.debug("Received token from AdobeAuth, parsing with BearerToken.info");
+        const tokenInfo = bearer_token_default.info(token);
+        if (!tokenInfo.isValid) {
+          this.customLogger.error("Received invalid or expired token from IMS");
+          return null;
+        }
+        const expireInSeconds = tokenInfo.timeUntilExpiry ? Math.floor(tokenInfo.timeUntilExpiry / 1e3) : 86399;
+        this.customLogger.debug(`Token expires in ${expireInSeconds} seconds`);
+        return {
+          token,
+          expire_in: expireInSeconds
+        };
+      }
+      this.customLogger.error("Received null or undefined token from IMS");
+      return null;
+    } catch (error) {
+      this.customLogger.error(`Failed to get IMS token: ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * @param result
+   * @return boolean
+   */
+  async setValue(result) {
+    try {
+      const state = await this.getState();
+      if (state === null) {
+        this.customLogger.info("State API not available, skipping token caching");
+        return true;
+      }
+      const ttlWithBuffer = Math.max(result.expire_in - 300, 60);
+      this.customLogger.debug(
+        `Caching IMS token with TTL: ${ttlWithBuffer} seconds (original: ${result.expire_in})`
+      );
+      await state.put(this.key, result.token, { ttl: ttlWithBuffer });
+      return true;
+    } catch (error) {
+      this.customLogger.error(`Failed to cache IMS token: ${error.message}`);
+      return true;
+    }
+  }
+  /**
+   * @return string | null
+   */
+  async getValue() {
+    try {
+      this.customLogger.debug("Checking for cached IMS token");
+      const state = await this.getState();
+      if (state === null) {
+        this.customLogger.debug("State API not available, cannot retrieve cached token");
+        return null;
+      }
+      const value = await state.get(this.key);
+      if (value !== void 0 && value.value) {
+        this.customLogger.debug("Found cached IMS token");
+        return value.value;
+      }
+      this.customLogger.debug("No cached IMS token found");
+    } catch (error) {
+      this.customLogger.error(`Failed to retrieve cached IMS token: ${error.message}`);
+    }
+    return null;
+  }
+  /**
+   * @return any
+   */
+  async getState() {
+    if (this.state === void 0) {
+      try {
+        this.customLogger.debug("Initializing State API for token caching");
+        this.state = await import_aio_sdk12.State.init();
+      } catch (error) {
+        this.customLogger.error(`Failed to initialize State API: ${error.message}`);
+        this.state = null;
+      }
+    }
+    return this.state;
+  }
+};
+__name(_GenerateImsToken, "GenerateImsToken");
+var GenerateImsToken = _GenerateImsToken;
+var generate_ims_token_default = GenerateImsToken;
+
 // src/commerce/adobe-commerce-client/ims-connection/index.ts
-var import_aio_sdk11 = require("@adobe/aio-sdk");
 var _ImsConnection = class _ImsConnection {
   /**
    * @param clientId
@@ -4952,38 +5257,35 @@ var _ImsConnection = class _ImsConnection {
    * @param imsOrgId
    * @param scopes
    * @param logger
-   * @param currentContext
    */
-  constructor(clientId, clientSecret, technicalAccountId, technicalAccountEmail, imsOrgId, scopes, logger = null, currentContext = "adobe-commerce-client") {
+  constructor(clientId, clientSecret, technicalAccountId, technicalAccountEmail, imsOrgId, scopes, logger = null) {
     this.clientId = clientId;
     this.clientSecret = clientSecret;
     this.technicalAccountId = technicalAccountId;
     this.technicalAccountEmail = technicalAccountEmail;
     this.imsOrgId = imsOrgId;
     this.scopes = scopes;
-    this.currentContext = currentContext;
-    if (logger === null) {
-      logger = import_aio_sdk11.Core.Logger(currentContext, {
-        level: "debug"
-      });
-    }
-    this.logger = logger;
+    this.customLogger = new custom_logger_default(logger);
   }
   /**
    * @param commerceGot
    */
   async extend(commerceGot) {
-    this.logger.debug("Using Commerce client with IMS authentication");
-    const token = await adobe_auth_default.getToken(
+    this.customLogger.info("Using Commerce client with IMS authentication");
+    const tokenGenerator = new generate_ims_token_default(
       this.clientId,
       this.clientSecret,
       this.technicalAccountId,
       this.technicalAccountEmail,
       this.imsOrgId,
       this.scopes,
-      this.currentContext
+      this.customLogger.getLogger()
     );
-    this.logger.debug(`IMS token being extended to header: ${token}`);
+    const token = await tokenGenerator.execute();
+    if (token === null) {
+      throw new Error("Failed to generate or retrieve IMS token");
+    }
+    this.customLogger.info(`IMS token being extended to header: ${token.substring(0, 10)}...`);
     return commerceGot.extend({
       headers: {
         Authorization: `Bearer ${token}`
@@ -4994,8 +5296,169 @@ var _ImsConnection = class _ImsConnection {
 __name(_ImsConnection, "ImsConnection");
 var ImsConnection = _ImsConnection;
 var ims_connection_default = ImsConnection;
+
+// src/experience/admin-ui-sdk/index.ts
+var _AdminUiSdk = class _AdminUiSdk {
+  /**
+   * Creates a new AdminUiSdk instance
+   * @param extensionId - Unique identifier for the extension
+   * @throws {Error} If extensionId is empty or invalid
+   */
+  constructor(extensionId) {
+    this.menuItems = [];
+    if (!extensionId?.trim()) {
+      throw new Error("Extension ID is required and cannot be empty");
+    }
+    const trimmedId = extensionId.trim();
+    if (!this.isValidExtensionId(trimmedId)) {
+      throw new Error(
+        "Extension ID must be alphanumeric with underscores only (no spaces, hyphens, or special characters)"
+      );
+    }
+    this.extensionId = trimmedId;
+  }
+  /**
+   * Validates that an extension ID contains only alphanumeric characters and underscores
+   * @param id - The extension ID to validate
+   * @returns true if valid, false otherwise
+   */
+  isValidExtensionId(id) {
+    return /^[a-zA-Z0-9_]+$/.test(id);
+  }
+  /**
+   * Validates that a menu ID is valid (can contain :: separator for namespacing)
+   * @param id - The menu ID to validate
+   * @returns true if valid, false otherwise
+   */
+  isValidMenuId(id) {
+    return /^[a-zA-Z0-9_:]+$/.test(id);
+  }
+  /**
+   * Adds a menu item to the extension
+   * @param id - Full identifier for the menu item (e.g., 'extensionId::menuItem')
+   * @param title - Display title for the menu item
+   * @param sortOrder - Sort order for menu positioning
+   * @param parent - Parent menu identifier (optional, full ID like 'extensionId::parent')
+   * @throws {Error} If parameters are invalid or ID already exists
+   */
+  addMenuItem(id, title, sortOrder, parent) {
+    if (!id?.trim()) {
+      throw new Error("Menu item ID is required and cannot be empty");
+    }
+    if (!this.isValidMenuId(id.trim())) {
+      throw new Error(
+        "Menu item ID must be alphanumeric with underscores and colons only (no spaces, hyphens, or other special characters)"
+      );
+    }
+    if (!title?.trim()) {
+      throw new Error("Menu item title is required and cannot be empty");
+    }
+    if (parent !== void 0 && !parent?.trim()) {
+      throw new Error("Menu item parent cannot be empty if provided");
+    }
+    if (parent !== void 0 && !this.isValidMenuId(parent.trim())) {
+      throw new Error(
+        "Menu item parent must be alphanumeric with underscores and colons only (no spaces, hyphens, or other special characters)"
+      );
+    }
+    if (typeof sortOrder !== "number" || sortOrder < 0) {
+      throw new Error("Menu item sortOrder must be a non-negative number");
+    }
+    const trimmedId = id.trim();
+    if (this.menuItems.some((item) => item.id === trimmedId)) {
+      throw new Error(`Menu item with ID '${trimmedId}' already exists`);
+    }
+    const menuItem = {
+      id: trimmedId,
+      title: title.trim(),
+      sortOrder
+    };
+    if (parent?.trim()) {
+      menuItem.parent = parent.trim();
+    }
+    this.menuItems.push(menuItem);
+  }
+  /**
+   * Adds a menu section to the extension
+   * @param id - Full identifier for the menu section (e.g., 'extensionId::section')
+   * @param title - Display title for the menu section
+   * @param sortOrder - Sort order for section positioning
+   * @param parent - Parent menu identifier (optional, full ID like 'Magento_Backend::system')
+   * @throws {Error} If parameters are invalid or ID already exists
+   */
+  addMenuSection(id, title, sortOrder, parent) {
+    if (!id?.trim()) {
+      throw new Error("Menu section ID is required and cannot be empty");
+    }
+    if (!this.isValidMenuId(id.trim())) {
+      throw new Error(
+        "Menu section ID must be alphanumeric with underscores and colons only (no spaces, hyphens, or other special characters)"
+      );
+    }
+    if (!title?.trim()) {
+      throw new Error("Menu section title is required and cannot be empty");
+    }
+    if (parent !== void 0 && !parent?.trim()) {
+      throw new Error("Menu section parent cannot be empty if provided");
+    }
+    if (parent !== void 0 && !this.isValidMenuId(parent.trim())) {
+      throw new Error(
+        "Menu section parent must be alphanumeric with underscores and colons only (no spaces, hyphens, or other special characters)"
+      );
+    }
+    if (typeof sortOrder !== "number" || sortOrder < 0) {
+      throw new Error("Menu section sortOrder must be a non-negative number");
+    }
+    const trimmedId = id.trim();
+    if (this.menuItems.some((item) => item.id === trimmedId)) {
+      throw new Error(`Menu item with ID '${trimmedId}' already exists`);
+    }
+    const menuSection = {
+      id: trimmedId,
+      title: title.trim(),
+      sortOrder,
+      isSection: true
+    };
+    if (parent?.trim()) {
+      menuSection.parent = parent.trim();
+    }
+    this.menuItems.push(menuSection);
+  }
+  /**
+   * Sets the page title for the extension
+   * @param title - The page title
+   * @throws {Error} If title is empty or invalid
+   */
+  addPage(title) {
+    if (!title?.trim()) {
+      throw new Error("Page title is required and cannot be empty");
+    }
+    this.pageTitle = title.trim();
+  }
+  /**
+   * Gets the complete registration object for the extension
+   * @returns The registration object with optional menu items and page configuration
+   */
+  getRegistration() {
+    const registration = {};
+    if (this.menuItems.length > 0) {
+      registration.menuItems = [...this.menuItems];
+    }
+    if (this.pageTitle) {
+      registration.page = {
+        title: this.pageTitle
+      };
+    }
+    return {
+      registration
+    };
+  }
+};
+__name(_AdminUiSdk, "AdminUiSdk");
+var AdminUiSdk = _AdminUiSdk;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AdminUiSdk,
   AdobeAuth,
   AdobeCommerceClient,
   BasicAuthConnection,
@@ -5019,6 +5482,7 @@ var ims_connection_default = ImsConnection;
   OpenwhiskAction,
   Parameters,
   ProviderManager,
+  PublishEvent,
   RegistrationManager,
   RestClient,
   RuntimeAction,