@monterosa/sdk-launcher-kit 2.0.0-rc.1 → 2.0.0-rc.2

package/dist/{index.esm.js → index.js}

@@ -1,6 +1,5 @@
 import { Logger, Sdk, getSdk, LogLevel, configure } from '@monterosa/sdk-core';
-import { createError, getGlobal, Emitter, getErrorMessage, subscribe, delay, throttle } from '@monterosa/sdk-util';
-import { v4 } from 'uuid';
+import { createError, getGlobal, Emitter, getErrorMessage, generateUUID, subscribe, delay, throttle } from '@monterosa/sdk-util';
 import { fetchListings } from '@monterosa/sdk-interact-interop';
 
 /**
@@ -77,6 +76,10 @@ var Action;
      * Notifies child Experience about the request to load more data
      */
     Action["OnMoreDataRequested"] = "onMoreDataRequested";
+    /**
+     * Notifies about a share request
+     */
+    Action["OnShare"] = "onShare";
 })(Action || (Action = {}));
 /**
  * @internal
@@ -106,13 +109,13 @@ var QueryParam;
      */
     QueryParam["Host"] = "h";
     /**
-     * Represents the Project Id of the application. This parameter is added by
+     * Represents the Project ID of the application. This parameter is added by
      * Studio and the embed URL already contains it.
      */
     QueryParam["Project"] = "p";
     /**
-     * Represents the Event Id of the application. This parameter is added to the
-     * experience URL when the eventId is provided in the experience config.
+     * Represents the Event ID of the application. This parameter is added to the
+     * Experience URL when the eventId is provided in the Experience config.
      */
     QueryParam["Event"] = "e";
     /**
@@ -200,8 +203,9 @@ const Config = {
     requestTimeout: 20000,
 };
 /**
- * Sets a new timeout value for requests (default is 20_000 mseconds).
+ * Sets a new timeout value for requests (default is 20,000 ms).
  *
+ * @remarks
  * This function updates the request timeout in the application's configuration.
  * It ensures that the new timeout value is a positive number, and throws
  * an error if the value is non-positive.
@@ -332,7 +336,7 @@ const globals = getGlobal();
  * @internal
  */
 class BridgeImpl extends Emitter {
-    constructor(id = v4()) {
+    constructor(id = generateUUID()) {
         super();
         this.id = id;
         this.recipientInitialised = false;
@@ -372,7 +376,7 @@ class BridgeImpl extends Emitter {
     }
     createMessage(action, payload, sourceName, respondingTo = null) {
         return {
-            id: v4(),
+            id: generateUUID(),
             respondingTo,
             action,
             sourceName,
@@ -520,9 +524,7 @@ function sendSdkMessage(bridged, action, payload = {}) {
     return bridged.bridge.send(action, payload, Source.Sdk);
 }
 /**
- * This function allows to send a simple message with action name and payload to
- * a recipient which can be either parent application (from Experience to parent
- * application) or child Experience (from parent page to Experience).
+ * Sends a message with an action name and payload to a parent application or child Experience.
  *
  * @remarks
  * Usage example in parent application:
@@ -575,14 +577,13 @@ function sendSdkRequest(bridged, action, payload = {}, timeout = Config.requestT
     return bridged.bridge.request(action, payload, timeout, Source.Sdk);
 }
 /**
- * This function allows to send a request with action name and payload to
- * a recipient which can be either parent application (from Experience to parent
- * application) or child Experience (from parent page to Experience). It is similar
- * to {@link sendMessage} with only one difference is that it returns a Promise which
- * resolves if the recipient response with {@link respondToMessage}. Otherwise it
- * will rejects after a certain timeout.
+ * Sends a request and returns a Promise that resolves when the recipient responds.
  *
  * @remarks
+ * Similar to {@link sendMessage} but returns a Promise which
+ * resolves if the recipient responds with {@link respondToMessage}. Otherwise it
+ * rejects after a certain timeout.
+ *
  * Usage example in parent application:
  *
  * @example
@@ -663,6 +664,8 @@ function onSdkMessage(bridged, callback) {
     return onMessageFunc(bridged, Source.Sdk, callback);
 }
 /**
+ * @internal
+ *
  * Adds an observer for when user message is received
  *
  * @param bridged - Instance of either {@link ParentApplication} or {@link Experience}
@@ -689,7 +692,7 @@ class ExperienceImpl {
     constructor(sdk, config) {
         this.sdk = sdk;
         this._parameters = {};
-        this.id = v4();
+        this.id = generateUUID();
         this.state = 'unmounted';
         this.customElement = null;
         this._config = config;
@@ -1061,7 +1064,7 @@ function unstashStyles(element) {
     element.removeAttribute('data-stash');
 }
 
-var version = "2.0.0-rc.1";
+var version = "2.0.0-rc.2";
 
 /**
  * @license
@@ -1190,10 +1193,12 @@ async function experienceReady(experience) {
     return eitherTimeoutOrFullyLoaded;
 }
 /**
- * Embeds web Experience app into iframe. There is only one app can be
- * associated with Experience and it is configured in
- * Monterosa / Interaction Cloud. Please refer the developer guide to get
- * more information on what is app and how to configure it:
+ * Embeds a web Experience app into an iframe.
+ *
+ * @remarks
+ * There is only one app that can be associated with an Experience and it is
+ * configured in Monterosa / Interaction Cloud. Please refer to the developer
+ * guide for more information:
  * {@link https://products.monterosa.co/mic/developer-guides/whats-an-app}
  *
  * @example
@@ -1202,8 +1207,8 @@ async function experienceReady(experience) {
  *
  * embed(experience, 'container-id');
  * ```
- * @param {Experience} - An instance of Experience
- * @param {HTMLElement | string} containerOrId - HTML element instance or
+ * @param experience - An instance of Experience
+ * @param containerOrId - HTML element instance or
  *     element id where iframe is embedded into.
  *
  * @public
@@ -1288,8 +1293,8 @@ async function embed(experience, containerOrId) {
 function unembed(experience) {
     const integration = getIntegration(experience);
     if (!integration) {
-        throw new Error('This experience is not currently embedded. ' +
-            'Please ensure the experience is embedded before calling unembed().');
+        throw new Error('This Experience is not currently embedded. ' +
+            'Please ensure the Experience is embedded before calling unembed().');
     }
     const { container } = integration;
     integration.controller.abort();
@@ -1327,8 +1332,8 @@ function unmount(containerOrId) {
     }
     const integration = getIntegration(container);
     if (!integration) {
-        throw new Error(`No experience found embedded in container "${containerOrId}". ` +
-            'Please ensure the experience is embedded before calling unmount().');
+        throw new Error(`No Experience found embedded in container "${containerOrId}". ` +
+            'Please ensure the Experience is embedded before calling unmount().');
     }
     integration.controller.abort();
     while (container.lastElementChild) {
@@ -1484,8 +1489,8 @@ if (!customElements.get(ELEMENT_NAME)) {
  *
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
-const unsubs = new Map();
-function handleExperienceEmbedded(experience) {
+const unsubs$1 = new Map();
+function handleExperienceEmbedded$1(experience) {
     if (!experience.config.autoresizesHeight) {
         return;
     }
@@ -1504,21 +1509,21 @@ function handleExperienceEmbedded(experience) {
             container.style.height = `${payload.height}px`;
         }
     });
-    unsubs.set(experience.id, unsub);
+    unsubs$1.set(experience.id, unsub);
 }
-function handleExperienceUnmounted(experience) {
-    const unsub = unsubs.get(experience.id);
+function handleExperienceUnmounted$1(experience) {
+    const unsub = unsubs$1.get(experience.id);
     if (unsub) {
         unsub();
-        unsubs.delete(experience.id);
+        unsubs$1.delete(experience.id);
     }
 }
 onStateChanged((experience, state) => {
     if (state === 'mounted') {
-        handleExperienceEmbedded(experience);
+        handleExperienceEmbedded$1(experience);
     }
     else if (state === 'unmounted') {
-        handleExperienceUnmounted(experience);
+        handleExperienceUnmounted$1(experience);
     }
 });
 
@@ -1584,12 +1589,13 @@ function getUrlParam(param) {
     return urlParams.get(param);
 }
 /**
+ * Returns whether the Experience should hide its header and footer.
+ *
+ * @remarks
  * The SDK on the parent application will by default request a child
  * Experience to hide its header and footer by setting a query parameter called
  * `micHideHeaderAndFooter` to `1`.
  *
- * This function will return true if that is the case, and false otherwise.
- *
  * When true, the developer of a child Experience is expected to hide it's headers
  * and footers as the parent application is actively providing them.
  *
@@ -1636,6 +1642,7 @@ function sendInitialised() {
  * Notifies the parent application that the Experience UI is fully loaded
  * and ready to be displayed. This triggers the `ready` lifecycle state.
  *
+ * @remarks
  * Call this method when your UI has completed loading and you are ready to
  * display data to the user. This can be when your network calls have successfully
  * requested data and you have updated the DOM, or when an error has occurred and
@@ -1729,10 +1736,10 @@ const sendExperienceSizeThrottled = throttle((width, height) => {
     trailing: true,
 });
 /**
- * Sends the experience size to the parent application.
+ * Sends the Experience size to the parent page.
  *
- * @param width - The width of the experience.
- * @param height - The height of the experience.
+ * @param width - The width of the Experience.
+ * @param height - The height of the Experience.
  */
 function sendExperienceSize(width, height) {
     sendExperienceSizeThrottled(width, height);
@@ -1755,5 +1762,134 @@ function reportExperienceSizeChanges(element) {
     return () => observer.unobserve(element);
 }
 
-export { Action, VERSION$1 as BRIDGE_VERSION, BridgeError, BridgeImpl, ExperienceImpl, ParentApplicationImpl, QueryParam, Source, VERSION, embed, enableLogging, getBridge, getExperience, getParentApplication, getParentBridge, isAutoresizesHeight, isInsideIframe, onMessage, onMoreDataRequested, onReady, onSdkMessage, onStateChanged, reportExperienceSizeChanges, requestMoreData, respondToMessage, respondToSdkMessage, sendExperienceSize, sendExperienceSizeThrottled, sendFinishedLoadingUI, sendInitialised, sendMessage, sendReady, sendRequest, sendSdkMessage, sendSdkRequest, setRequestTimeout, shouldHideHeaderAndFooter, stateEmitter, unembed, unmount, updateExperienceState };
-//# sourceMappingURL=index.esm.js.map
+/**
+ * @license
+ * share.ts
+ * launcher-kit
+ *
+ * Copyright © 2026 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * Share requests block on the native share tray which waits for user
+ * interaction (composing a message, picking a target app, etc.). The default
+ * bridge timeout of 20 seconds is too short for this. 5 minutes gives users
+ * ample time while still acting as a safety net against lost messages.
+ */
+const SHARE_REQUEST_TIMEOUT = 300000;
+var ShareError;
+(function (ShareError) {
+    ShareError["ParentAppError"] = "parent_app_error";
+    ShareError["ShareFailed"] = "share_failed";
+})(ShareError || (ShareError = {}));
+const ShareErrorMessages = {
+    [ShareError.ParentAppError]: (error) => `Parent application error: ${error}`,
+    [ShareError.ShareFailed]: (error) => `Share failed: ${error}`,
+};
+/**
+ * Executes share using the Web Share API.
+ *
+ * @internal
+ */
+async function executeShare(data) {
+    try {
+        await navigator.share({
+            url: data.url,
+            title: data.title,
+            text: data.description,
+        });
+        return 'success';
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return 'cancelled';
+        }
+        throw createError(ShareError.ShareFailed, ShareErrorMessages, getErrorMessage(err));
+    }
+}
+/**
+ * Initiates a share action. When running inside a parent application,
+ * the share request is sent to the parent via the communication bridge.
+ * When running standalone, `navigator.share()` is called directly.
+ *
+ * @param data - The data to share
+ */
+async function share(data) {
+    const parentApp = getParentApplication();
+    if (parentApp !== null) {
+        const response = await sendSdkRequest(parentApp, Action.OnShare, data, SHARE_REQUEST_TIMEOUT);
+        if (response.payload.result === 'failure') {
+            throw createError(ShareError.ParentAppError, ShareErrorMessages, response.payload.message);
+        }
+        // 'success' and 'cancelled' both resolve silently
+        return;
+    }
+    await executeShare(data);
+}
+/**
+ * Registers a callback to be called when a share request is received
+ * from a child Experience.
+ *
+ * @param experience - The Experience instance to listen on
+ * @param callback - Called with ShareData when a share request is received
+ * @returns Unsubscribe function
+ */
+function onShare(experience, callback) {
+    return onSdkMessage(experience, (message) => {
+        if (message.action === Action.OnShare) {
+            callback(message.payload);
+        }
+    });
+}
+const unsubs = new Map();
+function handleExperienceEmbedded(experience) {
+    const unsub = onSdkMessage(experience, async (message) => {
+        if (message.action !== Action.OnShare) {
+            return;
+        }
+        try {
+            const parentApp = getParentApplication();
+            let payload;
+            if (parentApp !== null) {
+                const response = await sendSdkRequest(parentApp, Action.OnShare, message.payload, SHARE_REQUEST_TIMEOUT);
+                payload = response.payload;
+            }
+            else {
+                const result = await executeShare(message.payload);
+                payload = {
+                    result,
+                    message: result === 'success' ? 'Share successful' : 'Share cancelled',
+                    data: {},
+                };
+            }
+            respondToSdkMessage(experience, message, payload);
+        }
+        catch (err) {
+            respondToSdkMessage(experience, message, {
+                result: 'failure',
+                message: getErrorMessage(err),
+                data: {},
+            });
+        }
+    });
+    unsubs.set(experience.id, unsub);
+}
+function handleExperienceUnmounted(experience) {
+    const unsub = unsubs.get(experience.id);
+    if (unsub) {
+        unsub();
+        unsubs.delete(experience.id);
+    }
+}
+onStateChanged((experience, state) => {
+    if (state === 'mounted') {
+        handleExperienceEmbedded(experience);
+    }
+    else if (state === 'unmounted') {
+        handleExperienceUnmounted(experience);
+    }
+});
+
+export { Action, VERSION$1 as BRIDGE_VERSION, BridgeError, BridgeImpl, ExperienceImpl, ParentApplicationImpl, QueryParam, ShareError, ShareErrorMessages, Source, VERSION, embed, enableLogging, executeShare, getBridge, getExperience, getParentApplication, getParentBridge, isAutoresizesHeight, isInsideIframe, onMessage, onMoreDataRequested, onReady, onSdkMessage, onShare, onStateChanged, reportExperienceSizeChanges, requestMoreData, respondToMessage, respondToSdkMessage, sendExperienceSize, sendExperienceSizeThrottled, sendFinishedLoadingUI, sendInitialised, sendMessage, sendReady, sendRequest, sendSdkMessage, sendSdkRequest, setRequestTimeout, share, shouldHideHeaderAndFooter, stateEmitter, unembed, unmount, updateExperienceState };
+//# sourceMappingURL=index.js.map