@microsoft/teams-js 2.0.0-beta.7-dev.6 → 2.0.0-beta.7-dev.9

package/README.md

@@ -1,6 +1,6 @@
 # Microsoft Teams JavaScript client SDK
 
-Welcome to the Teams JavaScript client SDK! For breaking changes, please refer to our [changelog](./CHANGELOG.md) in the current `<root>/packages/teams-js` directory of the `main` branch.
+Welcome to the Teams JavaScript client SDK! For breaking changes, please refer to our [changelog](./CHANGELOG.md) in the current `<root>/packages/teams-js` directory.
 
 This JavaScript library is part of the [Microsoft Teams developer platform](https://docs.microsoft.com/en-us/microsoftteams/platform/overview?view=msteams-client-js-beta). See full [SDK reference documentation](https://docs.microsoft.com/en-us/javascript/api/overview/msteams-client?view=msteams-client-js-beta).
 

package/dist/MicrosoftTeams.d.ts

@@ -200,7 +200,7 @@ export function uploadCustomApp(manifestBlob: Blob, onComplete?: (status: boolea
 /**
     * @hidden
     * Internal use only
-    * Sends a custom action MessageRequest to Teams or parent window
+    * Sends a custom action MessageRequest to host or parent window
     *
     * @param actionName - Specifies name of the custom action to be sent
     * @param args - Specifies additional arguments passed to the action
@@ -693,7 +693,7 @@ export namespace files {
             * Hide from docs
             * ------
             *
-            * Open a cloud storage file in teams
+            * Open a cloud storage file in Teams
             *
             * @param file - cloud storage file that should be opened
             * @param providerCode - Code of the cloud storage folder provider
@@ -735,45 +735,6 @@ export namespace files {
         export {};
 }
 
-/**
-    * @internal
-    */
-export namespace legacy {
-        namespace fullTrust {
-                namespace joinedTeams {
-                        /**
-                            * @hidden
-                            * Hide from docs
-                            * ------
-                            * Allows an app to retrieve information of all user joined teams
-                            *
-                            * @param teamInstanceParameters - OPTIONAL Flags that specify whether to scope call to favorite teams
-                            * @returns Promise resolved containing information about the user joined teams or rejected with error
-                            */
-                        function getUserJoinedTeams(teamInstanceParameters?: TeamInstanceParameters): Promise<UserJoinedTeamsInformation>;
-                        function isSupported(): boolean;
-                }
-                /**
-                    * @hidden
-                    * Hide from docs
-                    * ------
-                    * Allows an app to get the configuration setting value
-                    *
-                    * @param key - The key for the config setting
-                    * @returns Promise resolved containing the value for the provided config setting or rejected with error
-                    */
-                function getConfigSetting(key: string): Promise<string>;
-                /**
-                    * Checks if teams.fullTrust capability is supported currently
-                    */
-                function isSupported(): boolean;
-        }
-        /**
-            * Checks if teams capability is supported currently
-            */
-        function isSupported(): boolean;
-}
-
 export namespace meetingRoom {
         /**
             * @hidden
@@ -1183,7 +1144,7 @@ export namespace appEntity {
         interface AppEntity {
                 /**
                     * @hidden
-                    * App ID of the application
+                    * ID of the application
                     */
                 appId: string;
                 /**
@@ -1213,14 +1174,19 @@ export namespace appEntity {
             * --------
             * Open the Tab Gallery and retrieve the app entity
             * @param threadId ID of the thread where the app entity will be created
-            * @param categories A list of app categories that will be displayed in the opened tab gallery
+            * @param categories A list of application categories that will be displayed in the opened tab gallery
             * @param subEntityId An object that will be made available to the application being configured
-            *                      through the Teams Context's subEntityId field.
+            *                      through the Context's subEntityId field.
             * @param callback Callback that will be triggered once the app entity information is available.
             *                 The callback takes two arguments: an SdkError in case something happened (i.e.
             *                 no permissions to execute the API) and the app entity configuration, if available
             */
         function selectAppEntity(threadId: string, categories: string[], subEntityId: string, callback: (sdkError?: SdkError, appEntity?: AppEntity) => void): void;
+        /**
+            * Checks if appEntity capability is supported by the host
+            * @returns true if the appEntity capability is enabled in runtime.supports.appEntity and
+            * false if it is disabled
+            */
         function isSupported(): boolean;
 }
 
@@ -1263,7 +1229,64 @@ export namespace teams {
             * provided, the threadId from route params will be used.
             */
         function refreshSiteUrl(threadId: string, callback: (error: SdkError) => void): void;
+        /**
+            * @hidden
+            * Checks if teams capability is supported by the host
+            *
+            * @returns true if the teams capability is enabled in runtime.supports.teams and
+            * false if it is disabled
+            */
         function isSupported(): boolean;
+        /**
+            * @hidden
+            * Hide from docs
+            * ------
+            *
+            * @internal
+            */
+        namespace fullTrust {
+                namespace joinedTeams {
+                        /**
+                            * @hidden
+                            * Hide from docs
+                            * ------
+                            * Allows an app to retrieve information of all user joined teams
+                            *
+                            * @param teamInstanceParameters - Optional flags that specify whether to scope call to favorite teams
+                            * @returns Promise that resolves with information about the user joined teams or rejects with an error when the operation has completed
+                            */
+                        function getUserJoinedTeams(teamInstanceParameters?: TeamInstanceParameters): Promise<UserJoinedTeamsInformation>;
+                        /**
+                            * @hidden
+                            * Hide from docs
+                            * ------
+                            * Checks if teams.fullTrust.joinedTeams capability is supported by the host
+                            *
+                            * @returns true if the teams.fullTrust.joinedTeams capability is enabled in
+                            * runtime.supports.teams.fullTrust.joinedTeams and false if it is disabled
+                            */
+                        function isSupported(): boolean;
+                }
+                /**
+                    * @hidden
+                    * Hide from docs
+                    * ------
+                    * Allows an app to get the configuration setting value
+                    *
+                    * @param key - The key for the config setting
+                    * @returns Promise that resolves with the value for the provided configuration setting or rejects with an error when the operation has completed
+                    */
+                function getConfigSetting(key: string): Promise<string>;
+                /**
+                    * @hidden
+                    * Hide from docs
+                    * ------
+                    * Checks if teams.fullTrust capability is supported by the host
+                    * @returns true if the teams.fullTrust capability is enabled in runtime.supports.teams.fullTrust and
+                    * false if it is disabled
+                    */
+                function isSupported(): boolean;
+        }
 }
 
 /**
@@ -3012,17 +3035,17 @@ export namespace dialog {
     */
 export namespace pages {
         /**
-            * Return focus to the host. Will move focus forward or backward based on where the app container falls in
-            * the F6/Tab accessiblity loop in the host.
+            * Return focus to the host. Will move focus forward or backward based on where the application container falls in
+            * the F6/tab order in the host.
             * @param navigateForward - Determines the direction to focus in host.
             */
         function returnFocus(navigateForward?: boolean): void;
         /**
             * @hidden
             *
-            * Registers a handler when focus needs to be passed from teams to the place of choice on app.
+            * Registers a handler for specifying focus when it passes from the host to the application.
             *
-            * @param handler - The handler to invoked by the app when they want the focus to be in the place of their choice.
+            * @param handler - The handler for placing focus within the application.
             *
             * @internal
             */
@@ -3039,7 +3062,7 @@ export namespace pages {
             *
             * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
             *  user clicks 'Go To Website'
-            * @param callback - An optional user-set callback that is executed once the app has finished initialization.
+            * @param callback - An optional callback that is executed once the application has finished initialization.
             * @param validMessageOrigins - An optional list of cross-frame message origins. They must have
             * https: protocol otherwise they will be ignored. Example: https:www.example.com
             */
@@ -3079,19 +3102,19 @@ export namespace pages {
             * Navigates the frame to a new cross-domain URL. The domain of this URL must match at least one of the
             * valid domains specified in the validDomains block of the manifest; otherwise, an exception will be
             * thrown. This function needs to be used only when navigating the frame to a URL in a different domain
-            * than the current one in a way that keeps the app informed of the change and allows the SDK to
+            * than the current one in a way that keeps the application informed of the change and allows the SDK to
             * continue working.
             * @param url - The URL to navigate the frame to.
             * @returns Promise that resolves when the navigation has completed.
             */
         function navigateCrossDomain(url: string): Promise<void>;
         /**
-            * Navigate to the given App ID and Page ID, with optional parameters for a WebURL (if the app cannot
-            * be navigated to, such as if it is not installed), Channel ID (for apps installed as a channel tab), and
-            * Sub-page ID (for navigating to specific content within the page). This is equivalent to navigating to
-            * a deep link with the above data, but does not require the app to build a URL or worry about different
+            * Navigate to the given application ID and page ID, with optional parameters for a WebURL (if the application
+            * cannot be navigated to, such as if it is not installed), Channel ID (for applications installed as a channel tab),
+            * and sub-page ID (for navigating to specific content within the page). This is equivalent to navigating to
+            * a deep link with the above data, but does not require the application to build a URL or worry about different
             * deep link formats for different hosts.
-            * @param params Parameters for the navigation
+            * @param params - Parameters for the navigation
             * @returns a promise that will resolve if the navigation was successful
             */
         function navigateToApp(params: NavigateToAppParams): Promise<void>;
@@ -3108,7 +3131,7 @@ export namespace pages {
             */
         function registerFullScreenHandler(handler: (isFullScreen: boolean) => void): void;
         /**
-            * Checks if the current application host supports the pages capability
+            * Checks if the pages capability is supported by the host
             * @returns true if the pages capability is enabled in runtime.supports.pages and
             * false if it is disabled
             */
@@ -3118,11 +3141,11 @@ export namespace pages {
             */
         interface NavigateToAppParams {
                 /**
-                    * ID of the App to navigate to
+                    * ID of the application to navigate to
                     */
                 appId: string;
                 /**
-                    * Developer-defined ID of the Page to navigate to within the app (Formerly EntityID)
+                    * Developer-defined ID of the Page to navigate to within the application (Formerly EntityID)
                     */
                 pageId: string;
                 /**
@@ -3131,47 +3154,48 @@ export namespace pages {
                 webUrl?: string;
                 /**
                     * Optional developer-defined ID describing the content to navigate to within the Page. This will be passed
-                    * back to the App via the Context object.
+                    * back to the application via the Context object.
                     */
                 subPageId?: string;
                 /**
-                    * Optional ID of the Teams Channel where the app should be opened
+                    * Optional ID of the Teams Channel where the application should be opened
                     */
                 channelId?: string;
         }
         /**
-            * Namespace to interact with the teams specific part of the SDK.
+            * Provides APIs for querying and navigating between contextual tabs of an application. Unlike personal tabs,
+            * contextual tabs are pages associated with a specific context, such as channel or chat.
             */
         namespace tabs {
                 /**
-                    * Navigates the hosted app to the specified tab instance.
-                    * @param tabInstance The tab instance to navigate to.
+                    * Navigates the hosted application to the specified tab instance.
+                    * @param tabInstance - The destination tab instance.
                     * @returns Promise that resolves when the navigation has completed.
                     */
                 function navigateToTab(tabInstance: TabInstance): Promise<void>;
                 /**
-                    * Allows an app to retrieve for this user tabs that are owned by this app.
-                    * If no TabInstanceParameters are passed, the app defaults to favorite teams and favorite channels.
-                    * @param tabInstanceParameters OPTIONAL Flags that specify whether to scope call to favorite teams or channels.
+                    * Retrieves application tabs for the current user.
+                    * If no TabInstanceParameters are passed, the application defaults to favorite teams and favorite channels.
+                    * @param tabInstanceParameters - An optional set of flags that specify whether to scope call to favorite teams or channels.
                     * @returns Promise that resolves with the {@link TabInformation}. Contains information for the user's tabs that are owned by this application {@link TabInstance}.
                     */
                 function getTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
                 /**
-                    * Allows an app to retrieve the most recently used tabs for this user.
-                    * @param tabInstanceParameters OPTIONAL Ignored, kept for future use.
+                    * Retrieves the most recently used application tabs for the current user.
+                    * @param tabInstanceParameters - An optional set of flags. Note this is currently ignored and kept for future use.
                     * @returns Promise that resolves with the {@link TabInformation}. Contains information for the users' most recently used tabs {@link TabInstance}.
                     */
                 function getMruTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
                 /**
-                    * Checks if the current application host supports the pages.tab capability
+                    * Checks if the pages.tab capability is supported by the host
                     * @returns true if the pages.tabs capability is enabled in runtime.supports.pages.tabs and
                     * false if it is disabled
                     */
                 function isSupported(): boolean;
         }
         /**
-            * Namespace to interact with the config-specific part of the SDK.
-            * This object is usable only on the config frame.
+            * Provides APIs to interact with the configuration-specific part of the SDK.
+            * This object is usable only on the configuration frame.
             */
         namespace config {
                 /**
@@ -3183,24 +3207,24 @@ export namespace pages {
                     */
                 function initialize(): void;
                 /**
-                    * Sets the validity state for the config.
-                    * The initial value is false, so the user cannot save the config until this is called with true.
-                    * @param validityState Indicates whether the save or remove button is enabled for the user.
+                    * Sets the validity state for the configuration.
+                    * The initial value is false, so the user cannot save the configuration until this is called with true.
+                    * @param validityState - Indicates whether the save or remove button is enabled for the user.
                     */
                 function setValidityState(validityState: boolean): void;
                 /**
-                    * Sets the config for the current instance.
+                    * Sets the configuration for the current instance.
                     * This is an asynchronous operation; calls to getConfig are not guaranteed to reflect the changed state.
-                    * @param instanceConfig The desired config for this instance.
+                    * @param instanceConfig - The desired configuration for this instance.
                     * @returns Promise that resolves when the operation has completed.
                     */
                 function setConfig(instanceConfig: InstanceConfig): Promise<void>;
                 /**
-                    * Registers a handler for when the user attempts to save the settings. This handler should be used
+                    * Registers a handler for when the user attempts to save the configuration. This handler should be used
                     * to create or update the underlying resource powering the content.
                     * The object passed to the handler must be used to notify whether to proceed with the save.
                     * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-                    * @param handler The handler to invoke when the user selects the save button.
+                    * @param handler - The handler to invoke when the user selects the Save button.
                     */
                 function registerOnSaveHandler(handler: (evt: SaveEvent) => void): void;
                 /**
@@ -3208,12 +3232,12 @@ export namespace pages {
                     * to remove the underlying resource powering the content.
                     * The object passed to the handler must be used to indicate whether to proceed with the removal.
                     * Only one handler may be registered at a time. Subsequent registrations will override the first.
-                    * @param handler The handler to invoke when the user selects the remove button.
+                    * @param handler - The handler to invoke when the user selects the Remove button.
                     */
                 function registerOnRemoveHandler(handler: (evt: RemoveEvent) => void): void;
                 /**
                     * Registers a handler for when the tab configuration is changed by the user
-                    * @param handler The handler to invoke when the user click on Settings.
+                    * @param handler - The handler to invoke when the user clicks on Settings.
                     */
                 function registerChangeConfigHandler(handler: () => void): void;
                 /**
@@ -3231,7 +3255,7 @@ export namespace pages {
                         notifySuccess(): void;
                         /**
                             * Indicates that creation of the underlying resource failed and that the config cannot be saved.
-                            * @param reason Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
+                            * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
                             */
                         notifyFailure(reason?: string): void;
                 }
@@ -3246,7 +3270,7 @@ export namespace pages {
                         notifySuccess(): void;
                         /**
                             * Indicates that removal of the underlying resource failed and that the content cannot be removed.
-                            * @param reason Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
+                            * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
                             */
                         notifyFailure(reason?: string): void;
                 }
@@ -3260,33 +3284,32 @@ export namespace pages {
                         webhookUrl?: string;
                 }
                 /**
-                    * Checks if the current application host supports the pages.config capability
+                    * Checks if the pages.config capability is supported by the host
                     * @returns true if the pages.config capability is enabled in runtime.supports.pages.config and
                     * false if it is disabled
                     */
                 function isSupported(): boolean;
         }
         /**
-            * Namespace to interact with the back-stack part of the SDK.
+            * Provides APIs for handling the user's navigational history.
             */
         namespace backStack {
                 function _initialize(): void;
                 /**
-                    * Navigates back in the hosted app. See registerBackButtonHandler for more information on when
-                    * it's appropriate to use this method.
+                    * Navigates back in the hosted application. See {@link pages.backStack.registerBackButtonHandler} for notes on usage.
                     * @returns Promise that resolves when the navigation has completed.
                     */
                 function navigateBack(): Promise<void>;
                 /**
-                    * Registers a handler for user presses of the Team client's back button. Experiences that maintain an internal
-                    * navigation stack should use this handler to navigate the user back within their frame. If an app finds
+                    * Registers a handler for user presses of the host client's back button. Experiences that maintain an internal
+                    * navigation stack should use this handler to navigate the user back within their frame. If an application finds
                     * that after running its back button handler it cannot handle the event it should call the navigateBack
-                    * method to ask the Teams client to handle it instead.
-                    * @param handler The handler to invoke when the user presses their Team client's back button.
+                    * method to ask the host client to handle it instead.
+                    * @param handler - The handler to invoke when the user presses the host client's back button.
                     */
                 function registerBackButtonHandler(handler: () => boolean): void;
                 /**
-                    * Checks if the current application host supports the pages.backStack capability
+                    * Checks if the pages.backStack capability is supported by the host
                     * @returns true if the pages.backStack capability is enabled in runtime.supports.pages.backStack and
                     * false if it is disabled
                     */
@@ -3296,7 +3319,7 @@ export namespace pages {
             * @hidden
             * Hide from docs
             * ------
-            * Namespace to interact with the full-trust part of the SDK. Limited to 1P apps
+            * Provides APIs to interact with the full-trust part of the SDK. Limited to 1P applications
             */
         namespace fullTrust {
                 /**
@@ -3317,14 +3340,14 @@ export namespace pages {
                     * @hidden
                     * Hide from docs
                     * ------
-                    * Checks if the current application host supports the pages.fullTrust capability
+                    * Checks if the pages.fullTrust capability is supported by the host
                     * @returns true if the pages.fullTrust capability is enabled in runtime.supports.pages.fullTrust and
                     * false if it is disabled
                     */
                 function isSupported(): boolean;
         }
         /**
-            * Namespace to interact with the app button part of the SDK.
+            * Provides APIs to interact with the app button part of the SDK.
             */
         namespace appButton {
                 /**
@@ -3346,7 +3369,7 @@ export namespace pages {
                     */
                 function onHoverLeave(handler: () => void): void;
                 /**
-                    * Checks if pages.appButton capability is supported currently
+                    * Checks if pages.appButton capability is supported by the host
                     * @returns true if the pages.appButton capability is enabled in runtime.supports.pages.appButton and
                     * false if it is disabled
                     */
@@ -4401,6 +4424,11 @@ export namespace teamsCore {
             * @internal
             */
         function registerBeforeUnloadHandler(handler: (readyToUnload: () => void) => boolean): void;
+        /**
+            * Checks if teamsCore capability is supported by the host
+            * @returns true if the teamsCore capability is enabled in runtime.supports.teamsCore and
+            * false if it is disabled
+            */
         function isSupported(): boolean;
 }
 
@@ -4511,7 +4539,7 @@ export namespace video {
                 NV12 = 0
         }
         /**
-            * Video frame configuration supplied to Teams to customize the generated video frame parameters, like format
+            * Video frame configuration supplied to the host to customize the generated video frame parameters, like format
             */
         interface VideoFrameConfig {
                 /**
@@ -4542,21 +4570,29 @@ export namespace video {
         type VideoEffectCallBack = (effectId: string | undefined) => void;
         /**
             * Register to read the video frames in Permissions section
+            * @param frameCallback - The callback to invoke when registerForVideoFrame has completed
+            * @param config - VideoFrameConfig to customize generated video frame parameters
             */
         function registerForVideoFrame(frameCallback: VideoFrameCallback, config: VideoFrameConfig): void;
         /**
-            * video extension should call this to notify Teams Client current selected effect parameter changed.
-            * If it's pre-meeting, Teams client will call videoEffectCallback immediately then use the videoEffect.
-            * in-meeting scenario, we will call videoEffectCallback when apply button clicked.
+            * video extension should call this to notify host client that the current selected effect parameter changed.
+            * If it's pre-meeting, host client will call videoEffectCallback immediately then use the videoEffect.
+            * If it's the in-meeting scenario, we will call videoEffectCallback when apply button clicked.
             *
             * @param effectChangeType - the effect change type.
             * @param effectId - Newly selected effect id.
             */
         function notifySelectedVideoEffectChanged(effectChangeType: EffectChangeType, effectId: string | undefined): void;
         /**
-            * Register the video effect callback, Teams client uses this to notify the video extension the new video effect will by applied
+            * Register the video effect callback, host client uses this to notify the video extension the new video effect will by applied
+            * @param callback - The VideoEffectCallback to invoke when registerForVideoEffect has completed
             */
         function registerForVideoEffect(callback: VideoEffectCallBack): void;
+        /**
+            * Checks if video capability is supported by the host
+            * @returns true if the video capability is enabled in runtime.supports.video and
+            * false if it is disabled
+            */
         function isSupported(): boolean;
 }
 
@@ -4619,7 +4655,7 @@ export namespace stageView {
             */
         interface StageViewParams {
                 /**
-                    * The application ID of the Teams application to be opened.
+                    * The ID of the Teams application to be opened.
                     */
                 appId: string;
                 /**
@@ -4635,11 +4671,11 @@ export namespace stageView {
                     */
                 title: string;
                 /**
-                    * The Teams app website URL.
+                    * The Teams application website URL.
                     */
                 websiteUrl?: string;
                 /**
-                    * The entity ID of the Teams app content being opened.
+                    * The entity ID of the Teams application content being opened.
                     */
                 entityId?: string;
         }
@@ -4647,9 +4683,9 @@ export namespace stageView {
             * @hidden
             * Feature is under development
             *
-            * Opens a stage view to display a Teams app
-            * @param stageViewParams The parameters to pass into the stage view.
-            *
+            * Opens a stage view to display a Teams application
+            * @param stageViewParams - The parameters to pass into the stage view.
+            * @returns Promise that resolves once the stage view is closed.
             */
         function open(stageViewParams: StageViewParams): Promise<void>;
         /**
@@ -4659,9 +4695,9 @@ export namespace stageView {
             * @deprecated
             * As of 2.0.0, please use {@link stageView.open stageView.open(): Promise\<void\>} instead.
             *
-            * Opens a stage view to display a Teams app
-            * @param stageViewParams The parameters to pass into the stage view.
-            * Optional; @param callback Callback that will be triggered once the stage view is closed.
+            * Opens a stage view to display a Teams application
+            * @param stageViewParams - The parameters to pass into the stage view.
+            * @param callback - Optional callback that will be triggered once the stage view is closed.
             *                 The callback takes as an argument an SdkError in case something happened (i.e.
             *                 no permissions to execute the API)
             */