@microsoft/teams-js 2.17.0-beta.2 → 2.17.0

package/README.md

@@ -24,7 +24,7 @@ To install the stable [version](https://learn.microsoft.com/javascript/api/overv
 
 ### Production
 
-You can reference these files directly [from here](https://res.cdn.office.net/teams-js/2.16.0/js/MicrosoftTeams.min.js) or point your package manager at them.
+You can reference these files directly [from here](https://res.cdn.office.net/teams-js/2.17.0/js/MicrosoftTeams.min.js) or point your package manager at them.
 
 ## Usage
 
@@ -45,13 +45,13 @@ Reference the library inside of your `.html` page using:
 ```html
 <!-- Microsoft Teams JavaScript API (via CDN) -->
 <script
-  src="https://res.cdn.office.net/teams-js/2.16.0/js/MicrosoftTeams.min.js"
-  integrity="sha384-v6djPeImSC5Pb0IvhWyq/XY8It8EYt0U00nPlcodpX/RN5KgChhoqkKEZs5kX5hr"
+  src="https://res.cdn.office.net/teams-js/2.17.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-xp55t/129OsN192JZYLP0rGhzjCF9aYtjY0LVtXvolkDrBe4Jchylp56NrUYJ4S2"
   crossorigin="anonymous"
 ></script>
 
 <!-- Microsoft Teams JavaScript API (via npm) -->
-<script src="node_modules/@microsoft/teams-js@2.16.0/dist/MicrosoftTeams.min.js"></script>
+<script src="node_modules/@microsoft/teams-js@2.17.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/MicrosoftTeams.d.ts

@@ -6050,14 +6050,18 @@ export namespace media {
 }
 
 /**
-    * Namespace to power up the in-app browser experiences in the Host App.
-    * For e.g., opening a URL in the Host App inside a browser
+    * Namespace to power up the in-app browser experiences in the host app.
+    * For e.g., opening a URL in the host app inside a browser
     *
     * @beta
     */
 export namespace secondaryBrowser {
         /**
-            * Open a URL in the secondary browser aka in-app browser
+            * Open a URL in the secondary browser.
+            *
+            * On mobile, this is the in-app browser.
+            *
+            * On web and desktop, please use the `window.open()` method or other native external browser methods.
             *
             * @param url Url to open in the browser
             * @returns Promise that successfully resolves if the URL  opens in the secondaryBrowser
@@ -8512,7 +8516,13 @@ export namespace settings {
     * The tasks namespace will be deprecated. Please use dialog for future developments.
     */
 export namespace tasks {
-        /** Start task submit handler function type.  */
+        /**
+            * Function type that is used to receive the result when a task module is submitted by
+            * calling {@link tasks.submitTask tasks.submitTask(result?: string | object, appIds?: string | string[]): void}
+            *
+            * @param err - If the task module failed, this string contains the reason for failure. If the task module succeeded, this value is the empty string.
+            * @param result - On success, this is the value passed to the `result` parameter of {@link tasks.submitTask tasks.submitTask(result?: string | object, appIds?: string | string[]): void}. On failure, this is the empty string.
+            */
         type startTaskSubmitHandlerFunctionType = (err: string, result: string | object) => void;
         /**
             * @deprecated

package/dist/MicrosoftTeams.js

@@ -1956,6 +1956,15 @@ var __rest = (undefined && undefined.__rest) || function (s, e) {
         }
     return t;
 };
+var __spreadArray = (undefined && undefined.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 
 
 
@@ -1999,9 +2008,7 @@ var versionAndPlatformAgnosticTeamsRuntimeConfig = {
     isLegacyTeams: true,
     supports: {
         app: {
-            lifecycle: {
-                caching: {},
-            },
+            lifecycle: {},
         },
         appInstallDialog: {},
         appEntity: {},
@@ -2024,14 +2031,11 @@ var versionAndPlatformAgnosticTeamsRuntimeConfig = {
         monetization: {},
         notifications: {},
         pages: {
-            appButton: {},
-            tabs: {},
             config: {},
             backStack: {},
             fullTrust: {},
         },
         remoteCamera: {},
-        stageView: {},
         teams: {
             fullTrust: {},
         },
@@ -2041,11 +2045,9 @@ var versionAndPlatformAgnosticTeamsRuntimeConfig = {
         },
     },
 };
-var v1HostClientTypes = [
+var v1NonMobileHostClientTypes = [
     HostClientType.desktop,
     HostClientType.web,
-    HostClientType.android,
-    HostClientType.ios,
     HostClientType.rigel,
     HostClientType.surfaceHub,
     HostClientType.teamsRoomsWindows,
@@ -2053,6 +2055,8 @@ var v1HostClientTypes = [
     HostClientType.teamsPhones,
     HostClientType.teamsDisplays,
 ];
+var v1MobileHostClientTypes = [HostClientType.android, HostClientType.ios, HostClientType.ipados];
+var v1HostClientTypes = __spreadArray(__spreadArray([], v1NonMobileHostClientTypes, true), v1MobileHostClientTypes, true);
 /**
  * @hidden
  * Uses upgradeChain to transform an outdated runtime object to the latest format.
@@ -2116,6 +2120,15 @@ var upgradeChain = [
     },
 ];
 var mapTeamsVersionToSupportedCapabilities = {
+    // 1.0.0 just signifies "these capabilities have practically always been supported." For some of these
+    // we don't know what the real first version that supported them was -- but it was long enough ago that
+    // we can just effectively consider them always supported (on the specified platforms)
+    '1.0.0': [
+        {
+            capability: { pages: { appButton: {}, tabs: {} }, stageView: {} },
+            hostClientTypes: v1NonMobileHostClientTypes,
+        },
+    ],
     '1.9.0': [
         {
             capability: { location: {} },
@@ -2269,7 +2282,7 @@ var _minRuntimeConfigToUninitialize = {
  * @hidden
  *  Package version.
  */
-var version = "2.17.0-beta.2";
+var version = "2.17.0";
 
 ;// CONCATENATED MODULE: ./src/internal/internalAPIs.ts
 
@@ -2406,6 +2419,11 @@ function processAdditionalValidOrigins(validMessageOrigins) {
     GlobalVars.additionalValidOrigins = combinedOriginUrls;
 }
 
+;// CONCATENATED MODULE: ./src/internal/typeCheckUtilities.ts
+function isNullOrUndefined(value) {
+    return value === null || value === undefined;
+}
+
 ;// CONCATENATED MODULE: ./src/public/authentication.ts
 
 
@@ -3521,6 +3539,24 @@ var app;
      * Number of milliseconds we'll give the initialization call to return before timing it out
      */
     var initializationTimeoutInMs = 5000;
+    function logWhereTeamsJsIsBeingUsed() {
+        if (inServerSideRenderingEnvironment()) {
+            return;
+        }
+        var scripts = document.getElementsByTagName('script');
+        // This will always be the current script because browsers load and execute scripts in order.
+        // Whenever a script is executing for the first time it will be the last script in this array.
+        var currentScriptSrc = scripts && scripts[scripts.length - 1] && scripts[scripts.length - 1].src;
+        var scriptUsageWarning = 'Today, teamsjs can only be used from a single script or you may see undefined behavior. This log line is used to help detect cases where teamsjs is loaded multiple times -- it is always written. The presence of the log itself does not indicate a multi-load situation, but multiples of these log lines will. If you would like to use teamjs from more than one script at the same time, please open an issue at https://github.com/OfficeDev/microsoft-teams-library-js/issues';
+        if (!currentScriptSrc || currentScriptSrc.length === 0) {
+            appLogger('teamsjs is being used from a script tag embedded directly in your html. %s', scriptUsageWarning);
+        }
+        else {
+            appLogger('teamsjs is being used from %s. %s', currentScriptSrc, scriptUsageWarning);
+        }
+    }
+    // This is called right away to make sure that we capture which script is being executed correctly
+    logWhereTeamsJsIsBeingUsed();
     /**
      * Initializes the library.
      *
@@ -3906,6 +3942,7 @@ function transformLegacyContextToAppContext(legacyContext) {
 
 
 
+
 /**
  * Navigation-specific part of the SDK.
  */
@@ -4059,7 +4096,7 @@ var pages;
      */
     function registerFullScreenHandler(handler) {
         registerHandlerHelper('fullScreenChange', handler, [], function () {
-            if (handler && !isSupported()) {
+            if (!isNullOrUndefined(handler) && !isSupported()) {
                 throw errorNotSupportedOnPlatform;
             }
         });
@@ -4204,7 +4241,7 @@ var pages;
          */
         function registerOnSaveHandler(handler) {
             registerOnSaveHandlerHelper(handler, function () {
-                if (handler && !isSupported()) {
+                if (!isNullOrUndefined(handler) && !isSupported()) {
                     throw errorNotSupportedOnPlatform;
                 }
             });
@@ -4222,12 +4259,12 @@ var pages;
          */
         function registerOnSaveHandlerHelper(handler, versionSpecificHelper) {
             // allow for registration cleanup even when not finished initializing
-            handler && ensureInitialized(runtime, FrameContexts.settings);
+            !isNullOrUndefined(handler) && ensureInitialized(runtime, FrameContexts.settings);
             if (versionSpecificHelper) {
                 versionSpecificHelper();
             }
             saveHandler = handler;
-            handler && sendMessageToParent('registerHandler', ['save']);
+            !isNullOrUndefined(handler) && sendMessageToParent('registerHandler', ['save']);
         }
         config.registerOnSaveHandlerHelper = registerOnSaveHandlerHelper;
         /**
@@ -4239,7 +4276,7 @@ var pages;
          */
         function registerOnRemoveHandler(handler) {
             registerOnRemoveHandlerHelper(handler, function () {
-                if (handler && !isSupported()) {
+                if (!isNullOrUndefined(handler) && !isSupported()) {
                     throw errorNotSupportedOnPlatform;
                 }
             });
@@ -4257,12 +4294,12 @@ var pages;
          */
         function registerOnRemoveHandlerHelper(handler, versionSpecificHelper) {
             // allow for registration cleanup even when not finished initializing
-            handler && ensureInitialized(runtime, FrameContexts.remove, FrameContexts.settings);
+            !isNullOrUndefined(handler) && ensureInitialized(runtime, FrameContexts.remove, FrameContexts.settings);
             if (versionSpecificHelper) {
                 versionSpecificHelper();
             }
             removeHandler = handler;
-            handler && sendMessageToParent('registerHandler', ['remove']);
+            !isNullOrUndefined(handler) && sendMessageToParent('registerHandler', ['remove']);
         }
         config.registerOnRemoveHandlerHelper = registerOnRemoveHandlerHelper;
         function handleSave(result) {
@@ -4410,7 +4447,7 @@ var pages;
          */
         function registerBackButtonHandler(handler) {
             registerBackButtonHandlerHelper(handler, function () {
-                if (handler && !isSupported()) {
+                if (!isNullOrUndefined(handler) && !isSupported()) {
                     throw errorNotSupportedOnPlatform;
                 }
             });
@@ -4428,12 +4465,12 @@ var pages;
          */
         function registerBackButtonHandlerHelper(handler, versionSpecificHelper) {
             // allow for registration cleanup even when not finished initializing
-            handler && ensureInitialized(runtime);
+            !isNullOrUndefined(handler) && ensureInitialized(runtime);
             if (versionSpecificHelper) {
                 versionSpecificHelper();
             }
             backButtonPressHandler = handler;
-            handler && sendMessageToParent('registerHandler', ['backButton']);
+            !isNullOrUndefined(handler) && sendMessageToParent('registerHandler', ['backButton']);
         }
         backStack.registerBackButtonHandlerHelper = registerBackButtonHandlerHelper;
         function handleBackButtonPress() {
@@ -4635,7 +4672,7 @@ var pages;
 
 ;// CONCATENATED MODULE: ./src/internal/handlers.ts
 /* eslint-disable @typescript-eslint/ban-types */
-var __spreadArray = (undefined && undefined.__spreadArray) || function (to, from, pack) {
+var handlers_spreadArray = (undefined && undefined.__spreadArray) || function (to, from, pack) {
     if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
         if (ar || !(i in from)) {
             if (!ar) ar = Array.prototype.slice.call(from, 0, i);
@@ -4729,7 +4766,7 @@ function registerHandler(name, handler, sendMessage, args) {
     if (args === void 0) { args = []; }
     if (handler) {
         HandlersPrivate.handlers[name] = handler;
-        sendMessage && sendMessageToParent('registerHandler', __spreadArray([name], args, true));
+        sendMessage && sendMessageToParent('registerHandler', handlers_spreadArray([name], args, true));
     }
     else {
         delete HandlersPrivate.handlers[name];
@@ -4763,7 +4800,7 @@ function doesHandlerExist(name) {
  */
 function registerHandlerHelper(name, handler, contexts, registrationHelper) {
     // allow for registration cleanup even when not finished initializing
-    handler && ensureInitialized.apply(void 0, __spreadArray([runtime], contexts, false));
+    handler && ensureInitialized.apply(void 0, handlers_spreadArray([runtime], contexts, false));
     if (registrationHelper) {
         registrationHelper();
     }
@@ -7170,15 +7207,19 @@ var ParentAppWindow = /** @class */ (function () {
 
 
 /**
- * Namespace to power up the in-app browser experiences in the Host App.
- * For e.g., opening a URL in the Host App inside a browser
+ * Namespace to power up the in-app browser experiences in the host app.
+ * For e.g., opening a URL in the host app inside a browser
  *
  * @beta
  */
 var secondaryBrowser;
 (function (secondaryBrowser) {
     /**
-     * Open a URL in the secondary browser aka in-app browser
+     * Open a URL in the secondary browser.
+     *
+     * On mobile, this is the in-app browser.
+     *
+     * On web and desktop, please use the `window.open()` method or other native external browser methods.
      *
      * @param url Url to open in the browser
      * @returns Promise that successfully resolves if the URL  opens in the secondaryBrowser
@@ -7960,7 +8001,6 @@ var monetization;
      */
     function openPurchaseExperience(param1, param2) {
         var callback;
-        /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
         var planInfo;
         if (typeof param1 === 'function') {
             callback = param1;
@@ -7974,6 +8014,7 @@ var monetization;
                 if (!isSupported()) {
                     throw errorNotSupportedOnPlatform;
                 }
+                /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
                 resolve(sendAndHandleSdkError('monetization.openPurchaseExperience', planInfo));
             });
         };
@@ -8131,6 +8172,7 @@ var mail;
 
 
 
+
 /**
  * Namespace containing the set of APIs that support Teams-specific functionalities.
  */
@@ -8177,7 +8219,7 @@ var teamsCore;
      */
     function registerOnLoadHandler(handler) {
         registerOnLoadHandlerHelper(handler, function () {
-            if (handler && !isSupported()) {
+            if (!isNullOrUndefined(handler) && !isSupported()) {
                 throw errorNotSupportedOnPlatform;
             }
         });
@@ -8197,8 +8239,8 @@ var teamsCore;
      */
     function registerOnLoadHandlerHelper(handler, versionSpecificHelper) {
         // allow for registration cleanup even when not finished initializing
-        handler && ensureInitialized(runtime);
-        if (handler && versionSpecificHelper) {
+        !isNullOrUndefined(handler) && ensureInitialized(runtime);
+        if (!isNullOrUndefined(handler) && versionSpecificHelper) {
             versionSpecificHelper();
         }
         handlers_registerOnLoadHandler(handler);
@@ -8217,7 +8259,7 @@ var teamsCore;
      */
     function registerBeforeUnloadHandler(handler) {
         registerBeforeUnloadHandlerHelper(handler, function () {
-            if (handler && !isSupported()) {
+            if (!isNullOrUndefined(handler) && !isSupported()) {
                 throw errorNotSupportedOnPlatform;
             }
         });
@@ -8238,8 +8280,8 @@ var teamsCore;
      */
     function registerBeforeUnloadHandlerHelper(handler, versionSpecificHelper) {
         // allow for registration cleanup even when not finished initializing
-        handler && ensureInitialized(runtime);
-        if (handler && versionSpecificHelper) {
+        !isNullOrUndefined(handler) && ensureInitialized(runtime);
+        if (!isNullOrUndefined(handler) && versionSpecificHelper) {
             versionSpecificHelper();
         }
         handlers_registerBeforeUnloadHandler(handler);
@@ -8282,17 +8324,15 @@ var people;
     function selectPeople(param1, param2) {
         var _a;
         ensureInitialized(runtime, FrameContexts.content, FrameContexts.task, FrameContexts.settings);
-        /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
-        var callback;
-        /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
-        var peoplePickerInputs;
+        var callback = undefined;
+        var peoplePickerInputs = undefined;
         if (typeof param1 === 'function') {
             _a = [param1, param2], callback = _a[0], peoplePickerInputs = _a[1];
         }
         else {
             peoplePickerInputs = param1;
         }
-        return callCallbackWithErrorOrResultFromPromiseAndReturnPromise(selectPeopleHelper, callback, peoplePickerInputs);
+        return callCallbackWithErrorOrResultFromPromiseAndReturnPromise(selectPeopleHelper, callback /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */, peoplePickerInputs);
     }
     people_1.selectPeople = selectPeople;
     function selectPeopleHelper(peoplePickerInputs) {
@@ -8300,7 +8340,6 @@ var people;
             if (!isCurrentSDKVersionAtLeast(peoplePickerRequiredVersion)) {
                 throw { errorCode: ErrorCode.OLD_PLATFORM };
             }
-            /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
             if (!validatePeoplePickerInput(peoplePickerInputs)) {
                 throw { errorCode: ErrorCode.INVALID_ARGUMENTS };
             }
@@ -10448,14 +10487,14 @@ function shareDeepLink(deepLinkParameters) {
  */
 function executeDeepLink(deepLink, onComplete) {
     ensureInitialized(runtime, FrameContexts.content, FrameContexts.sidePanel, FrameContexts.settings, FrameContexts.task, FrameContexts.stage, FrameContexts.meetingStage);
-    onComplete = onComplete ? onComplete : getGenericOnCompleteHandler();
+    var completionHandler = onComplete !== null && onComplete !== void 0 ? onComplete : getGenericOnCompleteHandler();
     app
         .openLink(deepLink)
         .then(function () {
-        onComplete(true);
+        completionHandler(true);
     })
         .catch(function (err) {
-        onComplete(false, err.message);
+        completionHandler(false, err.message);
     });
 }
 /**
@@ -10512,14 +10551,14 @@ function returnFocus(navigateForward) {
  */
 function navigateToTab(tabInstance, onComplete) {
     ensureInitialized(runtime);
-    onComplete = onComplete ? onComplete : getGenericOnCompleteHandler();
+    var completionHandler = onComplete !== null && onComplete !== void 0 ? onComplete : getGenericOnCompleteHandler();
     pages.tabs
         .navigateToTab(tabInstance)
         .then(function () {
-        onComplete(true);
+        completionHandler(true);
     })
         .catch(function (error) {
-        onComplete(false, error.message);
+        completionHandler(false, error.message);
     });
 }
 /**
@@ -10537,14 +10576,14 @@ function navigateToTab(tabInstance, onComplete) {
  */
 function navigateCrossDomain(url, onComplete) {
     ensureInitialized(runtime, FrameContexts.content, FrameContexts.sidePanel, FrameContexts.settings, FrameContexts.remove, FrameContexts.task, FrameContexts.stage, FrameContexts.meetingStage);
-    onComplete = onComplete ? onComplete : getGenericOnCompleteHandler();
+    var completionHandler = onComplete !== null && onComplete !== void 0 ? onComplete : getGenericOnCompleteHandler();
     pages
         .navigateCrossDomain(url)
         .then(function () {
-        onComplete(true);
+        completionHandler(true);
     })
         .catch(function (error) {
-        onComplete(false, error.message);
+        completionHandler(false, error.message);
     });
 }
 /**
@@ -10558,14 +10597,14 @@ function navigateCrossDomain(url, onComplete) {
  */
 function navigateBack(onComplete) {
     ensureInitialized(runtime);
-    onComplete = onComplete ? onComplete : getGenericOnCompleteHandler();
+    var completionHandler = onComplete !== null && onComplete !== void 0 ? onComplete : getGenericOnCompleteHandler();
     pages.backStack
         .navigateBack()
         .then(function () {
-        onComplete(true);
+        completionHandler(true);
     })
         .catch(function (error) {
-        onComplete(false, error.message);
+        completionHandler(false, error.message);
     });
 }
 
@@ -10623,14 +10662,14 @@ var settings;
      */
     function setSettings(instanceSettings, onComplete) {
         ensureInitialized(runtime, FrameContexts.content, FrameContexts.settings, FrameContexts.sidePanel);
-        onComplete = onComplete ? onComplete : getGenericOnCompleteHandler();
+        var completionHandler = onComplete !== null && onComplete !== void 0 ? onComplete : getGenericOnCompleteHandler();
         pages.config
             .setConfig(instanceSettings)
             .then(function () {
-            onComplete(true);
+            completionHandler(true);
         })
             .catch(function (error) {
-            onComplete(false, error.message);
+            completionHandler(false, error.message);
         });
     }
     settings.setSettings = setSettings;
@@ -10712,8 +10751,7 @@ var tasks;
      */
     function startTask(taskInfo, submitHandler) {
         var dialogSubmitHandler = submitHandler
-            ? /* eslint-disable-next-line strict-null-checks/all */ /* fix tracked by 5730662 */
-                function (sdkResponse) { return submitHandler(sdkResponse.err, sdkResponse.result); }
+            ? function (sdkResponse) { var _a, _b; return submitHandler((_a = sdkResponse.err) !== null && _a !== void 0 ? _a : '', (_b = sdkResponse.result) !== null && _b !== void 0 ? _b : ''); }
             : undefined;
         if (taskInfo.card === undefined && taskInfo.url === undefined) {
             ensureInitialized(runtime, FrameContexts.content, FrameContexts.sidePanel, FrameContexts.meetingStage);
@@ -10769,7 +10807,9 @@ var tasks;
      * @returns - Converted UrlDialogInfo object
      */
     function getUrlDialogInfoFromTaskInfo(taskInfo) {
-        /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
+        if (taskInfo.url === undefined) {
+            throw new Error("url property of taskInfo object can't be undefined");
+        }
         var urldialogInfo = {
             url: taskInfo.url,
             size: {
@@ -10787,7 +10827,9 @@ var tasks;
      * @returns - converted BotUrlDialogInfo object
      */
     function getBotUrlDialogInfoFromTaskInfo(taskInfo) {
-        /* eslint-disable-next-line strict-null-checks/all */ /* Fix tracked by 5730662 */
+        if (taskInfo.url === undefined || taskInfo.completionBotId === undefined) {
+            throw new Error("Both url ".concat(taskInfo.url, " and completionBotId ").concat(taskInfo.completionBotId, " are required for bot url dialog. At least one is undefined."));
+        }
         var botUrldialogInfo = {
             url: taskInfo.url,
             size: {