@microsoft/teams-js 2.8.0-beta.0 → 2.8.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.7.1/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.8.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.7.1/js/MicrosoftTeams.min.js"
-  integrity="sha384-4Gy2G+qxzDVdrdemcVqKVQvaSK1Ghg3x6xcsaMLPc/pw7KPtiogHGM97LTWF2PWg"
+  src="https://res.cdn.office.net/teams-js/2.8.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-/DJ9oJEFZSpGiUQx9Na5Yb5svOPPqSb3khKxJ/YgoZ2GtrkzWgSTBpESy3LvMPVk"
   crossorigin="anonymous"
 ></script>
 
 <!-- Microsoft Teams JavaScript API (via npm) -->
-<script src="node_modules/@microsoft/teams-js@2.7.1/dist/MicrosoftTeams.min.js"></script>
+<script src="node_modules/@microsoft/teams-js@2.8.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/MicrosoftTeams.d.ts

@@ -3367,7 +3367,7 @@ export interface UrlDialogInfo extends BaseDialogInfo {
             *
             * @remarks
             * The domain of the url must match at least one of the
-            * valid domains specified in the validDomains block of the manifest
+            * valid domains specified in the [validDomains block](https://learn.microsoft.com/microsoftteams/platform/resources/schema/manifest-schema#validdomains) of the app manifest
             */
         url: string;
         /**
@@ -3435,19 +3435,15 @@ export interface DialogSize {
         width: DialogDimension | number;
 }
 /**
-    * @hidden
-    *
-    * @internal
-    * Limited to Microsoft-internal use
+    * @beta
+    * Data structure to be used with the {@link teamsCore.registerOnLoadHandler teamsCore.registerOnLoadHandler(handler: (context: LoadContext) => void): void} to pass the context to the app.
     */
 export interface LoadContext {
         /**
-            * @hidden
             * The entity that is requested to be loaded
             */
         entityId: string;
         /**
-            * @hidden
             * The content URL that is requested to be loaded
             */
         contentUrl: string;
@@ -3850,7 +3846,8 @@ export namespace app {
                     */
                 isPSTNCallingAllowed?: boolean;
                 /**
-                    * The license type for the current user.
+                    * The license type for the current user. Possible values are:
+                    * "Unknown", "Teacher", "Student", "Free", "SmbBusinessVoice", "SmbNonVoice", "FrontlineWorker"
                     */
                 licenseType?: string;
                 /**
@@ -3950,7 +3947,7 @@ export namespace app {
                     */
                 meeting?: MeetingInfo;
                 /**
-                    * When hosted in SharePoint, this is the [SharePoint PageContext](https://learn.microsoft.com/en-us/javascript/api/sp-page-context/pagecontext?view=sp-typescript-latest), else `undefined`
+                    * When hosted in SharePoint, this is the [SharePoint PageContext](https://learn.microsoft.com/javascript/api/sp-page-context/pagecontext?view=sp-typescript-latest), else `undefined`
                     */
                 sharepoint?: any;
                 /**
@@ -4215,7 +4212,7 @@ export namespace dialog {
                     */
                 err?: string;
                 /**
-                    * Value provided in the `result` parameter by the dialog when the {@linkcode submit} function
+                    * Value provided in the `result` parameter by the dialog when the {@linkcode url.submit} function
                     * was called.
                     * If the dialog was closed by the user without submitting (e.g., using a control in the corner
                     * of the dialog), this value will be `undefined` here.
@@ -4228,7 +4225,7 @@ export namespace dialog {
             */
         type PostMessageChannel = (message: any) => void;
         /**
-            * Handler used for receiving results when a dialog closes, either the value passed by {@linkcode submit}
+            * Handler used for receiving results when a dialog closes, either the value passed by {@linkcode url.submit}
             * or an error if the dialog was closed by the user.
             * @beta
             */
@@ -4262,6 +4259,9 @@ export namespace dialog {
                 /**
                     * Submit the dialog module and close the dialog
                     *
+                    * @remarks
+                    * This function is only intended to be called from code running within the dialog. Calling it from outside the dialog will have no effect.
+                    *
                     * @param result - The result to be sent to the bot or the app. Typically a JSON object or a serialized version of it,
                     *  If this function is called from a dialog while {@link M365ContentAction} is set in the context object by the host, result will be ignored
                     *
@@ -4273,8 +4273,8 @@ export namespace dialog {
                 /**
                     *  Send message to the parent from dialog
                     *
-                    *  @remarks
-                    * This function is only called from inside of a dialog
+                    * @remarks
+                    * This function is only intended to be called from code running within the dialog. Calling it from outside the dialog will have no effect.
                     *
                     * @param message - The message to send to the parent
                     *
@@ -4293,7 +4293,7 @@ export namespace dialog {
                     * Register a listener that will be triggered when a message is received from the app that opened the dialog.
                     *
                     * @remarks
-                    * This function is only called from inside of a dialog.
+                    * This function is only intended to be called from code running within the dialog. Calling it from outside the dialog will have no effect.
                     *
                     * @param listener - The listener that will be triggered.
                     *
@@ -4405,7 +4405,7 @@ export namespace dialog {
                     * This function cannot be called from inside of a dialog
                     *
                     * @param adaptiveCardDialogInfo - An object containing the parameters of the dialog module {@link AdaptiveCardDialogInfo}.
-                    * @param submitHandler - Handler that triggers when a dialog calls the {@linkcode submit} function or when the user closes the dialog.
+                    * @param submitHandler - Handler that triggers when a dialog calls the {@linkcode url.submit} function or when the user closes the dialog.
                     *
                     * @beta
                     */
@@ -4583,7 +4583,7 @@ export namespace geoLocation {
 }
 
 /**
-  * @returns The {@linkcode: AdaptiveCardVersion} representing the Adaptive Card schema
+  * @returns The {@linkcode AdaptiveCardVersion} representing the Adaptive Card schema
   * version supported by the host, or undefined if the host does not support Adaptive Cards
   */
 export function getAdaptiveCardSchemaVersion(): AdaptiveCardVersion | undefined;
@@ -4994,7 +4994,7 @@ export namespace pages {
                 interface NavigateWithinAppParams {
                         /**
                             * The developer-defined unique ID for the page defined in the manifest or when first configuring
-                            * the page. (Known as {entityId} prior to TeamsJS v.2.0.0)
+                            * the page. (Known as {@linkcode Context.entityId} prior to TeamsJS v.2.0.0)
                             */
                         pageId: string;
                         /**
@@ -5850,45 +5850,126 @@ export namespace meeting {
         /**
             * Property bag for the meeting reaction received event
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         interface MeetingReactionReceivedEventData {
                 /**
                     * Indicates the type of meeting reaction received
+                    *
+                    * @hidden
+                    * Hide from docs.
                     */
                 meetingReactionType?: MeetingReactionType;
                 /**
                     * error object in case there is a failure
+                    *
+                    * @hidden
+                    * Hide from docs.
                     */
                 error?: SdkError;
         }
         /**
             * Interface for raiseHandState properties
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         interface IRaiseHandState {
-                /** Indicates whether the selfParticipant's hand is raised or not*/
+                /** Indicates whether the selfParticipant's hand is raised or not
+                    *
+                    * @hidden
+                    * Hide from docs.
+                    */
                 isHandRaised: boolean;
         }
         /**
             * Property bag for the raiseHandState changed event
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         interface RaiseHandStateChangedEventData {
                 /**
                     * entire raiseHandState object for the selfParticipant
+                    *
+                    * @hidden
+                    * Hide from docs.
                     */
                 raiseHandState: IRaiseHandState;
                 /**
                     * error object in case there is a failure
+                    *
+                    * @hidden
+                    * Hide from docs.
                     */
                 error?: SdkError;
         }
+        /**
+            * Interface for mic state change
+            *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface MicState {
+                /**
+                    * Indicates the mute status of the mic
+                    */
+                isMicMuted: boolean;
+        }
+        /**
+            * Interface for RequestAppAudioHandling properties
+            *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface RequestAppAudioHandlingParams {
+                /**
+                    * Indicates whether the app is requesting to start handling audio, or if
+                    * it's giving audio back to the host
+                    */
+                isAppHandlingAudio: boolean;
+                /**
+                    * Callback for the host to tell the app to change its microphone state
+                    * @param micState The microphone state for the app to use
+                    * @returns A promise with the updated microphone state
+                    */
+                micMuteStateChangedCallback: (micState: MicState) => Promise<MicState>;
+        }
         /**
             * Different types of meeting reactions that can be sent/received
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         enum MeetingReactionType {
@@ -6043,6 +6124,12 @@ export namespace meeting {
             *
             * @param handler The handler to invoke when the selfParticipant's (current user's) raiseHandState changes.
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         function registerRaiseHandStateChangedHandler(handler: (eventData: RaiseHandStateChangedEventData) => void): void;
@@ -6052,6 +6139,12 @@ export namespace meeting {
             *
             * @param handler The handler to invoke when the selfParticipant (current user) successfully sends a meeting reaction
             *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
             * @beta
             */
         function registerMeetingReactionReceivedHandler(handler: (eventData: MeetingReactionReceivedEventData) => void): void;
@@ -6088,6 +6181,46 @@ export namespace meeting {
                     */
                 function setOptions(shareInformation: ShareInformation): void;
         }
+        /**
+            * Have the app handle audio (mic & speaker) and turn off host audio.
+            *
+            * When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is true, the host will switch to audioless mode
+            *   Registers for mic mute status change events, which are events that the app can receive from the host asking the app to
+            *   mute or unmute the microphone.
+            *
+            * When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is false, the host will switch out of audioless mode
+            *   Unregisters the mic mute status change events so the app will no longer receive these events
+            *
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
+            * @throws Error if {@link RequestAppAudioHandlingParams.micMuteStateChangedCallback} parameter is not defined
+            *
+            * @param requestAppAudioHandlingParams - {@link RequestAppAudioHandlingParams} object with values for the audio switchover
+            * @param callback - Callback with one parameter, the result
+            * can either be true (the host is now in audioless mode) or false (the host is not in audioless mode)
+            *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        function requestAppAudioHandling(requestAppAudioHandlingParams: RequestAppAudioHandlingParams, callback: (isHostAudioless: boolean) => void): void;
+        /**
+            * Notifies the host that the microphone state has changed in the app.
+            * @param micState - The new state that the microphone is in
+            *   isMicMuted - Boolean to indicate the current mute status of the mic.
+            *
+            * @hidden
+            * Hide from docs.
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        function updateMicState(micState: MicState): void;
 }
 
 export namespace monetization {
@@ -6225,12 +6358,14 @@ export namespace teamsCore {
             */
         function print(): void;
         /**
-            * @hidden
             * Registers a handler to be called when the page has been requested to load.
             *
+            * @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/apps-in-teams-meetings/build-tabs-for-meeting?tabs=desktop%2Cmeeting-chat-view-desktop%2Cmeeting-stage-view-desktop%2Cchannel-meeting-desktop#app-caching)
+            * for a more detailed explanation about using this API.
+            *
             * @param handler - The handler to invoke when the page is loaded.
             *
-            * @internal
+            * @beta
             */
         function registerOnLoadHandler(handler: (context: LoadContext) => void): void;
         /**
@@ -6245,13 +6380,15 @@ export namespace teamsCore {
             */
         function registerOnLoadHandlerHelper(handler: (context: LoadContext) => void, versionSpecificHelper?: () => void): void;
         /**
-            * @hidden
             * Registers a handler to be called before the page is unloaded.
             *
+            * @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/apps-in-teams-meetings/build-tabs-for-meeting?tabs=desktop%2Cmeeting-chat-view-desktop%2Cmeeting-stage-view-desktop%2Cchannel-meeting-desktop#app-caching)
+            * for a more detailed explanation about using this API.
+            *
             * @param handler - The handler to invoke before the page is unloaded. If this handler returns true the page should
             * invoke the readyToUnload function provided to it once it's ready to be unloaded.
             *
-            * @internal
+            * @beta
             */
         function registerBeforeUnloadHandler(handler: (readyToUnload: () => void) => boolean): void;
         /**
@@ -6679,7 +6816,7 @@ export namespace search {
 
 /**
     * Namespace to open a share dialog for web content.
-    * For more info, see {@link https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/share-to-teams-from-personal-app-or-tab Share to Teams from personal app or tab}
+    * For more info, see [Share to Teams from personal app or tab](https://learn.microsoft.com/microsoftteams/platform/concepts/build-and-test/share-to-teams-from-personal-app-or-tab)
     */
 export namespace sharing {
         export const SharingAPIMessages: {
@@ -7269,7 +7406,7 @@ export namespace settings {
 export namespace tasks {
         /**
             * @deprecated
-            * As of 2.0.0, please use {@link dialog.url.open dialog.url.open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void} for url based dialogs
+            * As of 2.8.0, please use {@link dialog.url.open dialog.url.open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void} for url based dialogs
             * and {@link dialog.url.bot.open dialog.url.bot.open(botUrlDialogInfo: BotUrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void} for bot-based dialogs. In Teams,
             * this function can be used for Adaptive Card-based dialogs. Support for Adaptive Card-based dialogs is coming to other hosts in the future.
             *
@@ -7290,7 +7427,7 @@ export namespace tasks {
         function updateTask(taskInfo: TaskInfo): void;
         /**
             * @deprecated
-            * As of 2.0.0, please use {@link dialog.submit} instead.
+            * As of 2.8.0, please use {@link dialog.url.submit} instead.
             *
             * Submit the task module.
             *