@adobe-commerce/aio-toolkit 1.0.1 → 1.0.3

package/dist/index.mjs

@@ -423,39 +423,44 @@ var _FileRepository = class _FileRepository {
   /**
    * Saves a file record to the repository
    * @param payload - The data to save
-   * @returns Promise<boolean> True if save was successful, false otherwise
+   * @param id - Optional ID for the file (sanitized to alphanumeric + underscore, takes precedence over payload.id)
+   * @returns Promise<string | null> The filename on success, null on failure
    */
-  async save(payload = {}) {
+  async save(payload = {}, id) {
     try {
       const filesLib = await this.getFiles();
-      let requestFileId = (/* @__PURE__ */ new Date()).getTime();
-      if ("id" in payload && payload.id !== void 0) {
-        requestFileId = Number(payload.id);
+      let fileId;
+      if (id) {
+        fileId = this.sanitizeFileId(id);
+      } else if ("id" in payload && payload.id !== void 0) {
+        fileId = String(payload.id);
+      } else {
+        fileId = String((/* @__PURE__ */ new Date()).getTime());
       }
-      const filepath = `${this.filepath}/${requestFileId}.json`;
+      const filepath = `${this.filepath}/${fileId}.json`;
       const existingFile = await filesLib.list(filepath);
       if (existingFile.length) {
         const buffer = await filesLib.read(filepath);
         const existingData = JSON.parse(buffer.toString());
         payload = {
           ...payload,
-          updated_at: (/* @__PURE__ */ new Date()).toDateString()
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         };
         payload = { ...existingData, ...payload };
         await filesLib.delete(filepath);
       } else {
         payload = {
           ...payload,
-          id: requestFileId,
-          created_at: (/* @__PURE__ */ new Date()).toDateString(),
-          updated_at: (/* @__PURE__ */ new Date()).toDateString()
+          id: fileId,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         };
       }
       await filesLib.write(filepath, JSON.stringify(payload));
-      return true;
+      return fileId;
     } catch (error) {
       console.error("Error saving file:", error);
-      return false;
+      return null;
     }
   }
   /**
@@ -470,6 +475,21 @@ var _FileRepository = class _FileRepository {
     }
     return await this.list();
   }
+  /**
+   * Sanitizes the file ID to contain only alphanumeric characters and underscores
+   * @param id - The ID to sanitize
+   * @returns Sanitized ID with invalid characters replaced by underscores
+   */
+  sanitizeFileId(id) {
+    if (!id || typeof id !== "string") {
+      return String((/* @__PURE__ */ new Date()).getTime());
+    }
+    const sanitized = id.replace(/[^a-zA-Z0-9_]/g, "_");
+    if (!sanitized || /^_+$/.test(sanitized)) {
+      return String((/* @__PURE__ */ new Date()).getTime());
+    }
+    return sanitized;
+  }
   /**
    * Initializes and returns the Files library instance
    * @returns Promise<any> Initialized Files library instance
@@ -485,6 +505,143 @@ __name(_FileRepository, "FileRepository");
 var FileRepository = _FileRepository;
 var file_repository_default = FileRepository;
 
+// src/framework/publish-event/index.ts
+import { Events } from "@adobe/aio-sdk";
+import { CloudEvent } from "cloudevents";
+import { v4 as uuidv4 } from "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 = uuidv4();
+      const cloudEvent = new 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 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: uuidv4(),
+        // 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 {
   /**
@@ -647,13 +804,32 @@ var _RestClient = class _RestClient {
       headers
     };
     if (payload !== null) {
+      let body;
+      let contentType;
+      if (payload instanceof URLSearchParams) {
+        body = payload.toString();
+        contentType = headers["Content-Type"] || "application/x-www-form-urlencoded";
+      } else if (typeof FormData !== "undefined" && payload instanceof FormData) {
+        body = payload;
+        contentType = headers["Content-Type"];
+      } else if (typeof payload === "string") {
+        body = payload;
+        contentType = headers["Content-Type"] || "text/plain";
+      } else if (payload instanceof Buffer || payload instanceof ArrayBuffer || typeof Uint8Array !== "undefined" && payload instanceof Uint8Array) {
+        body = payload;
+        contentType = headers["Content-Type"] || "application/octet-stream";
+      } else {
+        body = JSON.stringify(payload);
+        contentType = headers["Content-Type"] || "application/json";
+      }
+      const requestHeaders = { ...headers };
+      if (contentType) {
+        requestHeaders["Content-Type"] = contentType;
+      }
       options = {
         ...options,
-        body: JSON.stringify(payload),
-        headers: {
-          ...headers,
-          "Content-Type": "application/json"
-        }
+        body,
+        headers: requestHeaders
       };
     }
     return await fetch(endpoint, options);
@@ -4625,7 +4801,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();
@@ -4671,6 +4847,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
@@ -4841,8 +5030,161 @@ __name(_Oauth1aConnection, "Oauth1aConnection");
 var Oauth1aConnection = _Oauth1aConnection;
 var oauth1a_connection_default = Oauth1aConnection;
 
+// src/commerce/adobe-commerce-client/ims-connection/generate-ims-token/index.ts
+import { State as State3 } from "@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 State3.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
-import { Core as Core10 } from "@adobe/aio-sdk";
 var _ImsConnection = class _ImsConnection {
   /**
    * @param clientId
@@ -4852,38 +5194,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 = Core10.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}`
@@ -4894,7 +5233,168 @@ 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;
 export {
+  AdminUiSdk,
   adobe_auth_default as AdobeAuth,
   adobe_commerce_client_default as AdobeCommerceClient,
   basic_auth_connection_default as BasicAuthConnection,
@@ -4918,6 +5418,7 @@ export {
   openwhisk_action_default as OpenwhiskAction,
   parameters_default as Parameters,
   provider_default as ProviderManager,
+  publish_event_default as PublishEvent,
   registration_default as RegistrationManager,
   rest_client_default as RestClient,
   runtime_action_default as RuntimeAction,