@sapui5/sap.ushell 1.139.0 → 1.140.0

package/src/main/js/sap/ushell/appIntegration/PostMessagePluginInterface.js

@@ -1,146 +1,300 @@
 // Copyright (c) 2009-2025 SAP SE, All Rights Reserved
 
 sap.ui.define([
-    "sap/base/util/deepExtend",
-    "sap/ui/thirdparty/jquery"
+    "sap/base/util/deepEqual",
+    "sap/ui/thirdparty/jquery",
+    "sap/ui/base/Object",
+    "sap/ushell/utils"
 ], (
-    deepExtend,
-    jQuery
+    deepEqual,
+    jQuery,
+    BaseObject,
+    ushellUtils
 ) => {
     "use strict";
 
     const USER_API_PREFIX = "user.postapi.";
 
     /**
-     * @private
+     * @typedef {string} ServiceName The name of the service.
+     * All service names must start with 'user.postapi.'.
+     * Only SAP internal APIs are exempt from this rule.
      */
-    function PostMessagePluginInterface () {
-        let _bRunsInOuterShell;
-        let _fnAddCommunicationObject;
-
-        /**
-         * @private
-         */
-        this.init = function (bRunsInOuterShell, fnAddCommunicationObject) {
-            _bRunsInOuterShell = bRunsInOuterShell;
-            _fnAddCommunicationObject = fnAddCommunicationObject;
-        };
 
-        /**
-         * @private
-         */
-        this.getInterface = function () {
-            const oInterface = {};
+    /**
+     * @typedef {string} ServiceInterface The interface of the service.
+     * The interface is used to identify the specific functionality within the service.
+     */
 
-            oInterface.registerPostMessageAPIs = addCommunicationObject.bind(null, _fnAddCommunicationObject);
-            oInterface.createPostMessageResult = createPostMessageResult;
+    /**
+     * @typedef {object} OutCallDefinition Defines the outgoing call interface.
+     * Needs to be defined otherwise those post messages might not be sent to applications.
+     * @property {boolean} [isActiveOnly=true]
+     * If true, the post message is sent to the current application. Any other inactive applications are ignored then.
+     * @property {string[]} [distributionType=["all"]]
+     * The distribution type of the post message.
+     * The value "all" is transformed to <code>ignoreCapabilities=true</code>.
+     * Any other value than "all" will cause errors.
+     */
 
-            if (_bRunsInOuterShell) {
-                oInterface.postMessageToApp = doPostMessage.bind(null, _bRunsInOuterShell);
-            } else {
-                oInterface.postMessageToFlp = doPostMessage.bind(null, _bRunsInOuterShell);
-            }
+    /**
+     * @typedef {object} InCallDefinition Defines the incoming call interface.
+     * This is the interface that defines the handler in case applications are sending post messages to the plugin.
+     * @property {function (): Promise<any>} [executeServiceCallFn]
+     * The function to execute the service call.
+     */
 
-            return oInterface;
-        };
-    }
+    /**
+     * @typedef {object} ServiceDefinition
+     * @property {Object<ServiceInterface, InCallDefinition>} [inCalls] - Contains the interfaces for incoming calls.
+     * @property {Object<ServiceInterface, OutCallDefinition>} [outCalls] - Contains the interfaces for outgoing calls.
+     */
+
+    /**
+     * @typedef {Object<ServiceName, ServiceDefinition>} CommunicationObject
+     *
+     * @example
+     * {
+     *   "user.postapi.myService": {
+     *     inCalls: {
+     *       "myInterface": {
+     *         executeServiceCallFn: async function () {
+     *           // Implementation of the service call
+     *         }
+     *       }
+     *     },
+     *     outCalls: {
+     *       "myInterface": {
+     *         isActiveOnly: true,
+     *         distributionType: ["all"] // obsolete, should not be set
+     *       }
+     *     }
+     *   }
+     */
 
     /**
+     * @alias sap.ushell.appIntegration.PostMessagePluginInterface
+     * @class
+     * @classdesc This class provides an interface independent of the runtime environment
+     *
      * @private
      */
-    function addCommunicationObject (fnAddCommunicationObject, oNewCommunicationObject, bSAPInternal) {
-        const oRes = {
+    const PostMessagePluginInterface = BaseObject.extend("sap.ushell.appIntegration.PostMessagePluginInterface", {
+        metadata: {
+            publicMethods: [
+                "registerPostMessageAPIs",
+                "createPostMessageResult",
+                "postMessageToApp", // only available in the outer shell
+                "postMessageToFlp" // only available in the inner shell
+            ]
+        }
+    });
+
+    /**
+     * Initializes the PostMessagePluginInterface.
+     * @param {function (): Promise<any>} fnSendPostMessage The function to send post messages.
+     * @param {function (string, function)} fnSetRequestHandler The function to add communication objects.
+     * @param {function} fnSetDistributionPolicy The function to set distribution policies.
+     * @param {boolean} bRunsInOuterShell Indicates if the interface runs in the outer shell.
+     */
+    PostMessagePluginInterface.prototype.init = function (fnSendPostMessage, fnSetRequestHandler, fnSetDistributionPolicy, bRunsInOuterShell) {
+        this._fnSendPostMessage = fnSendPostMessage;
+        this._fnSetRequestHandler = fnSetRequestHandler;
+        this._fnSetDistributionPolicy = fnSetDistributionPolicy;
+        this._bRunsInOuterShell = bRunsInOuterShell;
+    };
+
+    /**
+     * Overrides the getInterface method to return the interface object.
+     *
+     * Depending on the runtime environment, it either provides the postMessageToFlp or postMessageToApp method.
+     * @returns {object} - The interface object containing the methods for post message communication.
+     */
+    PostMessagePluginInterface.prototype.getInterface = function () {
+        const oInterface = BaseObject.prototype.getInterface.call(this);
+
+        if (this._bRunsInOuterShell) {
+            delete oInterface.postMessageToFlp;
+        } else {
+            delete oInterface.postMessageToApp;
+        }
+
+        return oInterface;
+    };
+
+    /**
+     * Registers new post message APIs.
+     *
+     * @param {CommunicationObject} oNewCommunicationObject - The new communication object containing the APIs to register.
+     * @param {boolean} [bSAPInternal=false] - If true, the APIs are considered as internal SAP APIs and do not require the prefix 'user.postapi.'.
+     * @returns {{ status: string, desc: string }} - The result of the registration. <code>status</code> can be "success" or "error", and <code>desc</code> provides a description of the result.
+     */
+    PostMessagePluginInterface.prototype.registerPostMessageAPIs = function (oNewCommunicationObject, bSAPInternal = false) {
+        const oResult = {
             status: "success",
             desc: ""
         };
-        const oDefaultInCallProps = {
-            isActiveOnly: true,
-            distributionType: ["all"]
-        };
 
-        if (oNewCommunicationObject === undefined || Object.keys(oNewCommunicationObject).length <= 0) {
-            oRes.status = "error";
-            oRes.desc = "no handler was found to register";
-            return oRes;
+        try {
+            this._validateCommunicationObject(oNewCommunicationObject, bSAPInternal);
+
+            this._fnAddCommunicationObject(oNewCommunicationObject);
+        } catch (oError) {
+            oResult.status = "error";
+            oResult.desc = oError.message;
         }
 
-        if (bSAPInternal === undefined) {
-            bSAPInternal = false;
+        return oResult;
+    };
+
+    /**
+     * Validates the communication object to ensure it contains the required structure and keys.
+     * Throws an error if the validation fails.
+     * @param {CommunicationObject} oCommunicationObject - The communication object to validate.
+     * @param {boolean} bSAPInternal - Indicates if the APIs are internal SAP APIs.
+     *
+     * @private
+     */
+    PostMessagePluginInterface.prototype._validateCommunicationObject = function (oCommunicationObject, bSAPInternal) {
+        /* eslint-disable padded-blocks */
+        if (oCommunicationObject === undefined || Object.keys(oCommunicationObject).length <= 0) {
+            throw new Error("No handler was found to register");
         }
-        Object.keys(oNewCommunicationObject).forEach((sService) => {
+
+        for (const [sService, oServiceDefinition] of Object.entries(oCommunicationObject)) {
             if (typeof sService !== "string") {
-                oRes.status = "error";
-                oRes.desc = "oPostMessageAPIs should contain only string keys";
-            } else if (bSAPInternal === false && sService.indexOf(USER_API_PREFIX) !== 0) {
-                oRes.status = "error";
-                oRes.desc = `all user custom Message APIs must start with '${USER_API_PREFIX}'`;
-            } else {
-                Object.keys(oNewCommunicationObject[sService]).forEach((sType) => {
+                throw new Error("oPostMessageAPIs should contain only string keys");
+            }
+
+            if (!bSAPInternal && !sService.startsWith(USER_API_PREFIX)) {
+                throw new Error(`all user custom Message APIs must start with '${USER_API_PREFIX}'`);
+            }
+
+            for (const [sType, oTypeDefinition] of Object.entries(oServiceDefinition)) {
+                if (!["inCalls", "outCalls"].includes(sType)) {
+                    throw new Error("api should contain either 'inCalls' or 'outCalls'");
+                }
+
+                for (const [sInterface, oInterfaceDefinition] of Object.entries(oTypeDefinition)) {
                     if (sType === "inCalls") {
-                        oNewCommunicationObject[sService].oServiceCalls = oNewCommunicationObject[sService][sType];
-                        delete oNewCommunicationObject[sService][sType];
+                        // executeServiceCallFn is required for inCalls
+                        if (typeof oInterfaceDefinition.executeServiceCallFn !== "function") {
+                            throw new Error(`executeServiceCallFn for '${sService}.${sInterface}' must be a function`);
+                        }
+
                     } else if (sType === "outCalls") {
-                        Object.keys(oNewCommunicationObject[sService][sType]).forEach((sMethod) => {
-                            oNewCommunicationObject[sService][sType][sMethod] = deepExtend({}, oDefaultInCallProps, oNewCommunicationObject[sService][sType][sMethod]);
-                        });
-                        oNewCommunicationObject[sService].oRequestCalls = oNewCommunicationObject[sService][sType];
-                        delete oNewCommunicationObject[sService][sType];
-                    } else {
-                        oRes.status = "error";
-                        oRes.desc = "api should contain either 'inCalls' or 'outCalls'";
+                        // distributionType should not be used at all
+                        if (Object.hasOwn(oInterfaceDefinition, "distributionType")) {
+                            if (!Array.isArray(oInterfaceDefinition.distributionType)) {
+                                throw new Error(`distributionType for '${sService}.${sInterface}' must be an array. Remove it from the definition to apply the default.`);
+                            }
+                            if (!deepEqual(oInterfaceDefinition.distributionType, ["all"])) {
+                                throw new Error(`distributionType for '${sService}.${sInterface}' must be 'all'. Remove it from the definition to apply the default.`);
+                            }
+                        }
                     }
-                });
+                }
             }
-        });
-
-        if (oRes.status === "success") {
-            fnAddCommunicationObject(oNewCommunicationObject);
         }
-
-        return oRes;
-    }
+        /* eslint-enable padded-blocks */
+    };
 
     /**
+     * Adds a communication object to the plugin interface.
+     * @param {CommunicationObject} oCommunicationObject - The communication object to add.
+     *
      * @private
      */
-    function doPostMessage (bRunsInOuterShell, sServiceName, sInterface, oParams) {
-        const oDeferred = new jQuery.Deferred();
+    PostMessagePluginInterface.prototype._fnAddCommunicationObject = function (oCommunicationObject) {
+        /* eslint-disable padded-blocks */
+        for (const [sService, oServiceDefinition] of Object.entries(oCommunicationObject)) {
+            for (const [sType, oTypeDefinition] of Object.entries(oServiceDefinition)) {
+                for (const [sInterface, oInterfaceDefinition] of Object.entries(oTypeDefinition)) {
+                    if (sType === "inCalls") {
+                        this._fnSetRequestHandler(
+                            `${sService}.${sInterface}`,
+                            async (oMessageBody, oMessageEvent) => {
+                                const oServiceParams = {
+                                    oMessageData: JSON.parse(oMessageEvent.data),
+                                    oMessage: oMessageEvent
+                                };
+
+                                return ushellUtils.promisify(oInterfaceDefinition.executeServiceCallFn(oServiceParams));
+                            }
+                        );
+
+                    } else if (sType === "outCalls") {
+                        // Defaults
+                        const oDistributionPolicy = {
+                            ignoreCapabilities: true,
+                            onlyCurrentApplication: true
+                        };
+
+                        if (Object.hasOwn(oInterfaceDefinition, "isActiveOnly")) {
+                            oDistributionPolicy.onlyCurrentApplication = !!oInterfaceDefinition.isActiveOnly;
+                        }
 
-        if (oParams === undefined) {
-            oParams = {};
+                        this._fnSetDistributionPolicy(
+                            `${sService}.${sInterface}`,
+                            oDistributionPolicy
+                        );
+                    }
+                }
+            }
         }
+        /* eslint-enable padded-blocks */
+    };
 
-        if (bRunsInOuterShell) {
-            // todo: [FLPCOREANDUX-10024] Resolve this
-            sap.ui.require(["sap/ushell/appIntegration/PostMessageManager"], (PostMessageManager) => {
-                const sServiceRequest = `${sServiceName}.${sInterface}`;
+    /**
+     * Posts a message to the application.
+     * @param {string} sServiceName - The name of the service.
+     * @param {string} sInterface - The interface to call.
+     * @param {any} oBody - The parameters to pass to the interface.
+     * @returns {jQuery.Promise} - A promise that resolves with the result of the post message.
+     */
+    PostMessagePluginInterface.prototype.postMessageToApp = function (sServiceName, sInterface, oBody) {
+        const oDeferred = new jQuery.Deferred();
 
-                PostMessageManager.sendRequestToAllApplications(sServiceRequest, oParams, true)
-                    .then((oMessageBodies) => {
-                        oDeferred.resolve(oMessageBodies[0]?.result);
-                    });
+        this._fnSendPostMessage(`${sServiceName}.${sInterface}`, oBody)
+            .then((oResult) => {
+                oDeferred.resolve(oResult);
+            })
+            .catch((oError) => {
+                oDeferred.reject(oError);
             });
-        } else {
-            sap.ui.require(["sap/ushell/appRuntime/ui5/AppRuntimeService"], (AppRuntimeService) => {
-                AppRuntimeService.sendMessageToOuterShell(`${sServiceName}.${sInterface}`, oParams)
-                    .done((oResult) => {
-                        oDeferred.resolve(oResult);
-                    });
+
+        return oDeferred.promise();
+    };
+
+    /**
+     * Posts a message to the FLP.
+     * @param {string} sServiceName - The name of the service.
+     * @param {string} sInterface - The interface to call.
+     * @param {any} oBody - The parameters to pass to the interface.
+     * @returns {jQuery.Promise} - A promise that resolves with the result of the post message.
+     */
+    PostMessagePluginInterface.prototype.postMessageToFlp = function (sServiceName, sInterface, oBody) {
+        const oDeferred = new jQuery.Deferred();
+
+        this._fnSendPostMessage(`${sServiceName}.${sInterface}`, oBody)
+            .then((oResult) => {
+                oDeferred.resolve(oResult);
+            })
+            .catch((oError) => {
+                oDeferred.reject(oError);
             });
-        }
 
         return oDeferred.promise();
-    }
+    };
 
     /**
-     * @private
+     * Sanitizes the result for the post message response.
+     * @param {any} [oResult] - The result object.
+     * @returns {jQuery.Promise} - A promise that resolves with the result object.
      */
-    function createPostMessageResult (oResult) {
-        if (oResult === undefined) {
-            oResult = {};
-        }
+    PostMessagePluginInterface.prototype.createPostMessageResult = function (oResult = {}) {
         return new jQuery.Deferred().resolve(oResult).promise();
-    }
+    };
 
     return new PostMessagePluginInterface();
 });

package/src/main/js/sap/ushell/appIntegration/contracts/EmbeddedUI5Handler.js

@@ -1,7 +1,7 @@
 // Copyright (c) 2009-2025 SAP SE, All Rights Reserved
 /**
  * @fileOverview handle all the resources for the different applications.
- * @version 1.139.0
+ * @version 1.140.0
  */
 sap.ui.define([
     "sap/base/Log",

package/src/main/js/sap/ushell/appIntegration/contracts/StatefulContainerV1Handler.js

@@ -52,7 +52,6 @@ sap.ui.define([
                     }
                 }
 
-
                 oPostParams["sap-flp-params"] = {
                     ...oFLPParams,
                     "sap-flp-url": Container.getFLPUrl(true),

package/src/main/js/sap/ushell/appIntegration/contracts/StatefulContainerV2Handler.js

@@ -1,7 +1,7 @@
 // Copyright (c) 2009-2025 SAP SE, All Rights Reserved
 /**
  * @fileOverview handle all the resources for the different applications.
- * @version 1.139.0
+ * @version 1.140.0
  */
 sap.ui.define([
     "sap/ushell/ApplicationType/UrlPostProcessing",