@microsoft/teams-js 2.7.2-beta.0 → 2.8.0-beta.0

package/README.md

@@ -61,9 +61,9 @@ Reference the library inside of your `.html` page using:
 
 Teams client library depends on [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) type. If you support older browsers and devices which may not yet provide it natively (e.g. IE 11), you need to provide a global polyfill, such as [es6-promise](https://www.npmjs.com/package/es6-promise), in your bundled application. If you're using a script tag to reference the Teams client library, you need to make sure the polyfill is included and initialized before the Teams client library is initialized.
 
-## Examples
+## Full Documentation and Examples
 
-Stay tuned for examples coming soon.
+While each interface, class, function, etc. includes compact developer documentation, full documentation about library usage, including examples, can be found [here](https://learn.microsoft.com/en-us/javascript/api/overview/msteams-client?view=msteams-client-js-latest).
 
 ## Testing
 

package/dist/MicrosoftTeams.d.ts

@@ -2220,6 +2220,9 @@ export namespace authentication {
         /**
             * Initiates an authentication request, which opens a new window with the specified settings.
             *
+            * @remarks
+            * The authentication flow must start and end from the same domain, otherwise success and failure messages won't be returned to the window that initiated the call.
+            *
             * @param authenticateParameters - The parameters for the authentication request. It is a required parameter since v2 upgrade
             *
             * @returns Promise that will be fulfilled with the result from the authentication pop-up if successful.
@@ -2234,6 +2237,9 @@ export namespace authentication {
             *
             * Initiates an authentication request, which opens a new window with the specified settings.
             *
+            * @remarks
+            * The authentication flow must start and end from the same domain, otherwise success and failure messages won't be returned to the window that initiated the call.
+            *
             * @param authenticateParameters - The parameters for the authentication request.
             *
             */
@@ -2647,6 +2653,12 @@ export enum ChannelType {
         Shared = "Shared"
 }
 export const errorNotSupportedOnPlatform: SdkError;
+/**
+    * @hidden
+    *
+    * Minimum Adaptive Card version supported by the host.
+    */
+export const minAdaptiveCardVersion: AdaptiveCardVersion;
 
 /**
     * Represents information about tabs for an app
@@ -3302,6 +3314,37 @@ export interface DeepLinkParameters {
             */
         subEntityWebUrl?: string;
 }
+/**
+    * @hidden
+    * Shared Dialog Properties
+    */
+export interface BaseDialogInfo {
+        size: DialogSize;
+        /**
+            * Title of the dialog module.
+            */
+        title?: string;
+}
+/**
+    * Data structure to describe dialog information needed to open an Adaptive Card-based dialog.
+    */
+export interface AdaptiveCardDialogInfo extends BaseDialogInfo {
+        /**
+            * JSON defining an Adaptive Card.
+            */
+        card: string;
+}
+/**
+    * Data structure to describe dialog information needed to open a bot-based Adaptive Card-based dialog.
+    */
+export interface BotAdaptiveCardDialogInfo extends AdaptiveCardDialogInfo {
+        /**
+            * Specifies a bot ID to send the result of the user's interaction with the dialog module.
+            * The bot will receive a task/complete invoke event with a JSON object
+            * in the event payload.
+            */
+        completionBotId: string;
+}
 /**
     * Data structure to represent the size of a dialog
     */
@@ -3316,9 +3359,9 @@ export interface DialogSize {
         width: DialogDimension | number;
 }
 /**
-    * Data structure to describe dialog information needed to open a url based dialog.
+    * Data structure to describe dialog information needed to open a url-based dialog.
     */
-export interface UrlDialogInfo {
+export interface UrlDialogInfo extends BaseDialogInfo {
         /**
             * The url to be rendered in the webview/iframe.
             *
@@ -3327,11 +3370,6 @@ export interface UrlDialogInfo {
             * valid domains specified in the validDomains block of the manifest
             */
         url: string;
-        size: DialogSize;
-        /**
-            * Title of the task module.
-            */
-        title?: string;
         /**
             * If client doesnt support the URL, the URL that needs to be opened in the browser.
             */
@@ -3508,6 +3546,17 @@ export enum DevicePermission {
         GeoLocation = "geolocation",
         Media = "media"
 }
+/** @hidden */
+export interface HostVersionsInfo {
+        adaptiveCardSchemaVersion?: AdaptiveCardVersion;
+}
+/**
+    * Represents the major and minor versions of the Adaptive Card schema in the current host
+    */
+export interface AdaptiveCardVersion {
+        majorVersion: number;
+        minorVersion: number;
+}
 
 /**
     * Namespace to interact with app initialization and lifecycle.
@@ -4196,68 +4245,127 @@ export namespace dialog {
             * @beta
             */
         function initialize(): void;
-        /**
-            * Allows app to open a url based dialog.
-            *
-            * @remarks
-            * This function cannot be called from inside of a dialog
-            *
-            * @param urlDialogInfo - An object containing the parameters of the dialog module.
-            * @param submitHandler - Handler that triggers when a dialog calls the {@linkcode submit} function or when the user closes the dialog.
-            * @param messageFromChildHandler - Handler that triggers if dialog sends a message to the app.
-            *
-            * @returns a function that can be used to send messages to the dialog.
-            *
-            * @beta
-            */
-        function open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void;
-        /**
-            * Submit the dialog module and close the dialog
-            *
-            * @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
-            *
-            * @param appIds - Valid application(s) that can receive the result of the submitted dialogs. Specifying this parameter helps prevent malicious apps from retrieving the dialog result. Multiple app IDs can be specified because a web app from a single underlying domain can power multiple apps across different environments and branding schemes.
-            *
-            * @beta
-            */
-        function submit(result?: string | object, appIds?: string | string[]): void;
-        /**
-            *  Send message to the parent from dialog
-            *
-            *  @remarks
-            * This function is only called from inside of a dialog
-            *
-            * @param message - The message to send to the parent
-            *
-            * @beta
-            */
-        function sendMessageToParentFromDialog(message: any): void;
-        /**
-            *  Send message to the dialog from the parent
-            *
-            * @param message - The message to send
-            *
-            * @beta
-            */
-        function sendMessageToDialog(message: any): void;
-        /**
-            * 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.
-            *
-            * @param listener - The listener that will be triggered.
-            *
-            * @beta
-            */
-        function registerOnMessageFromParent(listener: PostMessageChannel): void;
+        namespace url {
+                /**
+                    * Allows app to open a url based dialog.
+                    *
+                    * @remarks
+                    * This function cannot be called from inside of a dialog
+                    *
+                    * @param urlDialogInfo - An object containing the parameters of the dialog module.
+                    * @param submitHandler - Handler that triggers when a dialog calls the {@linkcode submit} function or when the user closes the dialog.
+                    * @param messageFromChildHandler - Handler that triggers if dialog sends a message to the app.
+                    *
+                    * @beta
+                    */
+                function open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void;
+                /**
+                    * Submit the dialog module and close the dialog
+                    *
+                    * @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
+                    *
+                    * @param appIds - Valid application(s) that can receive the result of the submitted dialogs. Specifying this parameter helps prevent malicious apps from retrieving the dialog result. Multiple app IDs can be specified because a web app from a single underlying domain can power multiple apps across different environments and branding schemes.
+                    *
+                    * @beta
+                    */
+                function submit(result?: string | object, appIds?: string | string[]): void;
+                /**
+                    *  Send message to the parent from dialog
+                    *
+                    *  @remarks
+                    * This function is only called from inside of a dialog
+                    *
+                    * @param message - The message to send to the parent
+                    *
+                    * @beta
+                    */
+                function sendMessageToParentFromDialog(message: any): void;
+                /**
+                    *  Send message to the dialog from the parent
+                    *
+                    * @param message - The message to send
+                    *
+                    * @beta
+                    */
+                function sendMessageToDialog(message: any): void;
+                /**
+                    * 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.
+                    *
+                    * @param listener - The listener that will be triggered.
+                    *
+                    * @beta
+                    */
+                function registerOnMessageFromParent(listener: PostMessageChannel): void;
+                /**
+                    * Checks if dialog.url module is supported by the host
+                    *
+                    * @returns boolean to represent whether dialog.url module is supported
+                    *
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    *
+                    * @beta
+                    */
+                function isSupported(): boolean;
+                /**
+                    * Namespace to open a dialog that sends results to the bot framework
+                    *
+                    * @beta
+                    */
+                namespace bot {
+                        /**
+                            * Allows an app to open the dialog module using bot.
+                            *
+                            * @param botUrlDialogInfo - An object containing the parameters of the dialog module including completionBotId.
+                            * @param submitHandler - Handler that triggers when the dialog has been submitted or closed.
+                            * @param messageFromChildHandler - Handler that triggers if dialog sends a message to the app.
+                            *
+                            * @returns a function that can be used to send messages to the dialog.
+                            *
+                            * @beta
+                            */
+                        function open(botUrlDialogInfo: BotUrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void;
+                        /**
+                            * Checks if dialog.url.bot capability is supported by the host
+                            *
+                            * @returns boolean to represent whether dialog.url.bot is supported
+                            *
+                            * @throws Error if {@linkcode app.initialize} has not successfully completed
+                            *
+                            * @beta
+                            */
+                        function isSupported(): boolean;
+                }
+                /**
+                    * @hidden
+                    *
+                    * Convert UrlDialogInfo to DialogInfo to send the information to host in {@linkcode open} API.
+                    *
+                    * @internal
+                    * Limited to Microsoft-internal use
+                    */
+                function getDialogInfoFromUrlDialogInfo(urlDialogInfo: UrlDialogInfo): DialogInfo;
+                /**
+                    * @hidden
+                    *
+                    * Convert BotUrlDialogInfo to DialogInfo to send the information to host in {@linkcode bot.open} API.
+                    *
+                    * @internal
+                    * Limited to Microsoft-internal use
+                    */
+                function getDialogInfoFromBotUrlDialogInfo(botUrlDialogInfo: BotUrlDialogInfo): DialogInfo;
+        }
         /**
             * Checks if dialog capability is supported by the host
             * @returns boolean to represent whether dialog capabilty is supported
             *
             * @throws Error if {@linkcode app.initialize} has not successfully completed
             *
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
+            *
             * @beta
             */
         function isSupported(): boolean;
@@ -4286,55 +4394,91 @@ export namespace dialog {
                 function isSupported(): boolean;
         }
         /**
-            * Namespace to open a dialog that sends results to the bot framework
-            *
+            * Subcapability for interacting with adaptive card dialogs
             * @beta
             */
-        namespace bot {
+        namespace adaptiveCard {
                 /**
-                    * Allows an app to open the dialog module using bot.
+                    * Allows app to open an adaptive card based dialog.
                     *
-                    * @param botUrlDialogInfo - An object containing the parameters of the dialog module including completionBotId.
-                    * @param submitHandler - Handler that triggers when the dialog has been submitted or closed.
-                    * @param messageFromChildHandler - Handler that triggers if dialog sends a message to the app.
+                    * @remarks
+                    * This function cannot be called from inside of a dialog
                     *
-                    * @returns a function that can be used to send messages to the 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.
                     *
                     * @beta
                     */
-                function open(botUrlDialogInfo: BotUrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void;
+                function open(adaptiveCardDialogInfo: AdaptiveCardDialogInfo, submitHandler?: DialogSubmitHandler): void;
                 /**
-                    * Checks if dialog.bot capability is supported by the host
-                    * @returns boolean to represent whether dialog.bot is supported
+                    * Checks if dialog.adaptiveCard module is supported by the host
+                    *
+                    * @returns boolean to represent whether dialog.adaptiveCard module is supported
                     *
                     * @throws Error if {@linkcode app.initialize} has not successfully completed
                     *
                     * @beta
                     */
                 function isSupported(): boolean;
+                /**
+                    * Namespace for interaction with adaptive card dialogs that need to communicate with the bot framework
+                    *
+                    * @beta
+                    */
+                namespace bot {
+                        /**
+                            * Allows an app to open an adaptive card-based dialog module using bot.
+                            *
+                            * @param botAdaptiveCardDialogInfo - An object containing the parameters of the dialog module including completionBotId.
+                            * @param submitHandler - Handler that triggers when the dialog has been submitted or closed.
+                            *
+                            * @beta
+                            */
+                        function open(botAdaptiveCardDialogInfo: BotAdaptiveCardDialogInfo, submitHandler?: DialogSubmitHandler): void;
+                        /**
+                            * Checks if dialog.adaptiveCard.bot capability is supported by the host
+                            *
+                            * @returns boolean to represent whether dialog.adaptiveCard.bot is supported
+                            *
+                            * @throws Error if {@linkcode app.initialize} has not successfully completed
+                            *
+                            * @beta
+                            */
+                        function isSupported(): boolean;
+                }
+                /**
+                    * @hidden
+                    * Hide from docs
+                    * --------
+                    * Convert AdaptiveCardDialogInfo to DialogInfo to send the information to host in {@linkcode adaptiveCard.open} API.
+                    *
+                    * @internal
+                    */
+                function getDialogInfoFromAdaptiveCardDialogInfo(adaptiveCardDialogInfo: AdaptiveCardDialogInfo): DialogInfo;
+                /**
+                    * @hidden
+                    * Hide from docs
+                    * --------
+                    * Convert BotAdaptiveCardDialogInfo to DialogInfo to send the information to host in {@linkcode adaptiveCard.open} API.
+                    *
+                    * @internal
+                    */
+                function getDialogInfoFromBotAdaptiveCardDialogInfo(botAdaptiveCardDialogInfo: BotAdaptiveCardDialogInfo): DialogInfo;
+                /**
+                    * @hidden
+                    * Converts {@link TaskInfo} to {@link AdaptiveCardDialogInfo}
+                    * @param taskInfo - TaskInfo object to convert
+                    * @returns - converted AdaptiveCardDialogInfo
+                    */
+                function getAdaptiveCardDialogInfoFromTaskInfo(taskInfo: TaskInfo): AdaptiveCardDialogInfo;
+                /**
+                    * @hidden
+                    * Converts {@link TaskInfo} to {@link BotAdaptiveCardDialogInfo}
+                    * @param taskInfo - TaskInfo object to convert
+                    * @returns - converted BotAdaptiveCardDialogInfo
+                    */
+                function getBotAdaptiveCardDialogInfoFromTaskInfo(taskInfo: TaskInfo): BotAdaptiveCardDialogInfo;
         }
-        /**
-            * @hidden
-            *
-            * Convert UrlDialogInfo to DialogInfo to send the information to host in {@linkcode open} API.
-            *
-            * @internal
-            * Limited to Microsoft-internal use
-            *
-            * @beta
-            */
-        function getDialogInfoFromUrlDialogInfo(urlDialogInfo: UrlDialogInfo): DialogInfo;
-        /**
-            * @hidden
-            *
-            * Convert BotUrlDialogInfo to DialogInfo to send the information to host in {@linkcode bot.open} API.
-            *
-            * @internal
-            * Limited to Microsoft-internal use
-            *
-            * @beta
-            */
-        function getDialogInfoFromBotUrlDialogInfo(botUrlDialogInfo: BotUrlDialogInfo): DialogInfo;
 }
 
 /**
@@ -4438,6 +4582,12 @@ export namespace geoLocation {
         }
 }
 
+/**
+  * @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;
+
 /**
     * Navigation-specific part of the SDK.
     */
@@ -7119,9 +7269,9 @@ export namespace settings {
 export namespace tasks {
         /**
             * @deprecated
-            * As of 2.0.0, please use {@link dialog.open dialog.open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void} for url based dialogs
-            * and {@link dialog.bot.open dialog.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.
+            * 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
+            * 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.
             *
             * Allows an app to open the task module.
             *