@microsoft/teams-js 2.21.1-beta.1 → 2.22.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.21.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.22.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.21.0/js/MicrosoftTeams.min.js"
-  integrity="sha384-8IiFmUTxC/bV/D3X+IBPbfibh4oRJIbu7E14dqbrDjvMRs5JDg7p4sz0/JT74f2a"
+  src="https://res.cdn.office.net/teams-js/2.22.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-WSG/sWulIv7rel5TnFlH8JTpxl2OxzZh9Lux2mIzBFiTRLFvMBeFv9VURu/3vQdx"
   crossorigin="anonymous"
 ></script>
 
 <!-- Microsoft Teams JavaScript API (via npm) -->
-<script src="node_modules/@microsoft/teams-js@2.21.0/dist/MicrosoftTeams.min.js"></script>
+<script src="node_modules/@microsoft/teams-js@2.22.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/MicrosoftTeams.d.ts

@@ -61,7 +61,7 @@ export interface ThreadMember {
     * @internal
     * Limited to Microsoft-internal use
     */
-export enum NotificationTypes {
+export const enum NotificationTypes {
         fileDownloadStart = "fileDownloadStart",
         fileDownloadComplete = "fileDownloadComplete"
 }
@@ -81,7 +81,7 @@ export interface ShowNotificationParameters {
     * @internal
     * Limited to Microsoft-internal use
     */
-export enum ViewerActionTypes {
+export const enum ViewerActionTypes {
         view = "view",
         edit = "edit",
         editNew = "editNew"
@@ -91,7 +91,7 @@ export enum ViewerActionTypes {
     *
     * User setting changes that can be subscribed to
     */
-export enum UserSettingTypes {
+export const enum UserSettingTypes {
         /**
             * @hidden
             * Use this key to subscribe to changes in user's file open preference
@@ -502,6 +502,31 @@ export namespace externalAppAuthentication {
             * Limited to Microsoft-internal use
             */
         type IOriginalRequestInfo = IQueryMessageExtensionRequest | IActionExecuteInvokeRequest;
+        /**
+            * @hidden
+            * Parameters OauthWindow
+            * @internal
+            * Limited to Microsoft-internal use
+            */
+        type OauthWindowProperties = {
+                /**
+                    * The preferred width for the pop-up. This value can be ignored if outside the acceptable bounds.
+                    */
+                width?: number;
+                /**
+                    * The preferred height for the pop-up. This value can be ignored if outside the acceptable bounds.
+                    */
+                height?: number;
+                /**
+                    * Some identity providers restrict their authentication pages from being displayed in embedded browsers (e.g., a web view inside of a native application)
+                    * If the identity provider you are using prevents embedded browser usage, this flag should be set to `true` to enable the authentication page
+                    * to be opened in an external browser. If this flag is `false`, the page will be opened directly within the current hosting application.
+                    *
+                    * This flag is ignored when the host for the application is a web app (as opposed to a native application) as the behavior is unnecessary in a web-only
+                    * environment without an embedded browser.
+                    */
+                isExternal?: boolean;
+        };
         /**
             * @hidden
             * Parameters for the authentication pop-up. This interface is used exclusively with the externalAppAuthentication APIs
@@ -585,7 +610,7 @@ export namespace externalAppAuthentication {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum OriginalRequestType {
+        const enum OriginalRequestType {
                 ActionExecuteInvokeRequest = "ActionExecuteInvokeRequest",
                 QueryMessageExtensionRequest = "QueryMessageExtensionRequest"
         }
@@ -602,7 +627,7 @@ export namespace externalAppAuthentication {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum InvokeResponseType {
+        const enum InvokeResponseType {
                 ActionExecuteInvokeResponse = "ActionExecuteInvokeResponse",
                 QueryMessageExtensionResponse = "QueryMessageExtensionResponse"
         }
@@ -708,7 +733,7 @@ export namespace externalAppAuthentication {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum InvokeErrorCode {
+        const enum InvokeErrorCode {
                 INTERNAL_ERROR = "INTERNAL_ERROR"
         }
         /**
@@ -746,6 +771,18 @@ export namespace externalAppAuthentication {
             * @returns A promise that resolves to the IInvokeResponse from the application backend and rejects with InvokeError if the host encounters an error while authenticating or resending the request
             */
         function authenticateWithSSOAndResendRequest(appId: string, authTokenRequest: AuthTokenRequestParameters, originalRequestInfo: IOriginalRequestInfo): Promise<IInvokeResponse>;
+        /**
+            * @beta
+            * @hidden
+            * Signals to the host to perform Oauth2 authentication for the application specified by the title ID
+            * @internal
+            * Limited to Microsoft-internal use
+            * @param titleId ID of the acquisition
+            * @param oauthConfigId lookup ID in token store
+            * @param oauthWindowParameters parameters for the signIn window
+            * @returns A promise that resolves when authentication succeeds and rejects with InvokeError on failure
+            */
+        function authenticateWithOauth2(titleId: string, oauthConfigId: string, oauthWindowParameters: OauthWindowProperties): Promise<void>;
         /**
             * @hidden
             * Checks if the externalAppAuthentication capability is supported by the host
@@ -772,7 +809,7 @@ export namespace externalAppCardActions {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum ActionOpenUrlType {
+        const enum ActionOpenUrlType {
                 DeepLinkDialog = "DeepLinkDialog",
                 DeepLinkOther = "DeepLinkOther",
                 DeepLinkStageView = "DeepLinkStageView",
@@ -795,7 +832,7 @@ export namespace externalAppCardActions {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum ActionOpenUrlErrorCode {
+        const enum ActionOpenUrlErrorCode {
                 INTERNAL_ERROR = "INTERNAL_ERROR",
                 INVALID_LINK = "INVALID_LINK",
                 NOT_SUPPORTED = "NOT_SUPPORTED"
@@ -819,18 +856,9 @@ export namespace externalAppCardActions {
             * Limited to Microsoft-internal use
             */
         interface ActionSubmitError {
-                errorCode: ActionSubmitErrorCode;
+                errorCode: ExternalAppErrorCode;
                 message?: string;
         }
-        /**
-            * @hidden
-            * Error codes that can be thrown from IExternalAppCardActionService.handleActionSubmit
-            * @internal
-            * Limited to Microsoft-internal use
-            */
-        enum ActionSubmitErrorCode {
-                INTERNAL_ERROR = "INTERNAL_ERROR"
-        }
         /**
             * @beta
             * @hidden
@@ -846,14 +874,19 @@ export namespace externalAppCardActions {
         /**
             * @beta
             * @hidden
-            * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID
+            * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
+            * If `fromElement` is not provided, the information from the manifest is used to determine whether the URL can
+            * be processed by the host. Deep link URLs for plugins are not supported and will result in an error.
             * @internal
             * Limited to Microsoft-internal use
             * @param appId ID of the application the request is intended for. This must be a UUID
             * @param url The URL to open
+            * @param fromElement The element on behalf of which the M365 app is making the request.
             * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
             */
-        function processActionOpenUrl(appId: string, url: URL): Promise<ActionOpenUrlType>;
+        function processActionOpenUrl(appId: string, url: URL, fromElement?: {
+                name: 'composeExtensions' | 'plugins';
+        }): Promise<ActionOpenUrlType>;
         /**
             * @hidden
             * Checks if the externalAppCardActions capability is supported by the host
@@ -867,6 +900,128 @@ export namespace externalAppCardActions {
         function isSupported(): boolean;
 }
 
+/**
+    * @hidden
+    * Namespace to delegate the ActionCommand to the host
+    * @internal
+    * Limited to Microsoft-internal use
+    *
+    * @beta
+    */
+export namespace externalAppCommands {
+        /**
+            * @hidden
+            * The payload of IActionCommandResponse
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        type IActionCommandResponse = ITextActionCommandResponse | ICardActionCommandResponse;
+        /**
+            * @hidden
+            * The payload of IBaseActionCommandResponse
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface IBaseActionCommandResponse {
+                taskModuleClosedReason: TaskModuleClosedReason;
+        }
+        /**
+            * @hidden
+            * The text result type
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface ITextActionCommandResponse extends IBaseActionCommandResponse {
+                resultType: 'text';
+                text: string | undefined;
+        }
+        /**
+            * @hidden
+            * The card result type
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface ICardActionCommandResponse extends IBaseActionCommandResponse {
+                resultType: 'card';
+                attachmentLayout: externalAppAuthentication.AttachmentLayout;
+                attachments: externalAppAuthentication.QueryMessageExtensionAttachment[];
+        }
+        /**
+            * @hidden
+            * The result type for the ActionCommandResultType
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        type ActionCommandResultType = 'card' | 'text';
+        /**
+            * @hidden
+            * The reason for the TaskModuleClosedReason
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        type TaskModuleClosedReason = 'Done' | 'CancelledByUser';
+        /**
+            *
+            * @hidden
+            * Error that can be thrown from IExternalAppCommandsService.processActionCommand
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        interface ActionCommandError {
+                errorCode: ExternalAppErrorCode;
+                message?: string;
+        }
+        /**
+            * @internal
+            * Limited to Microsoft-internal use
+            * @hidden
+            * This API delegates an ActionCommand request to the host for the application with the provided following parameters:
+            *
+            * @param appId ID of the application the request is intended for. This must be a UUID
+            * @param commandId extensibilityProvider use this ID to look up the command declared by ActionME
+            * @param extractedParameters are the key-value pairs that the dialog will be prepopulated with
+            *
+            * @returns Promise that resolves with the {@link IActionCommandResponse} when the request is completed and rejects with {@link ActionCommandError} if the request fails
+            *
+            * @beta
+            */
+        function processActionCommand(appId: string, commandId: string, extractedParameters: Record<string, string>): Promise<IActionCommandResponse>;
+        /**
+            * @hidden
+            * Checks if the externalAppCommands capability is supported by the host
+            * @returns boolean to represent whether externalAppCommands capability is supported
+            *
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * @beta
+            */
+        function isSupported(): boolean;
+}
+
 export namespace files {
         /**
             * @hidden
@@ -876,7 +1031,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum CloudStorageProvider {
+        export const enum CloudStorageProvider {
                 Dropbox = "DROPBOX",
                 Box = "BOX",
                 Sharefile = "SHAREFILE",
@@ -913,7 +1068,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum CloudStorageProviderType {
+        export const enum CloudStorageProviderType {
                 Sharepoint = 0,
                 WopiIntegration = 1,
                 Google = 2,
@@ -1131,7 +1286,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum SpecialDocumentLibraryType {
+        export const enum SpecialDocumentLibraryType {
                 ClassMaterials = "classMaterials"
         }
         /**
@@ -1142,7 +1297,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum DocumentLibraryAccessType {
+        export const enum DocumentLibraryAccessType {
                 Readonly = "readonly"
         }
         /**
@@ -1184,7 +1339,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum FileDownloadStatus {
+        export const enum FileDownloadStatus {
                 Downloaded = "Downloaded",
                 Downloading = "Downloading",
                 Failed = "Failed"
@@ -1286,7 +1441,7 @@ export namespace files {
             * @internal
             * Limited to Microsoft-internal use
             */
-        export enum CloudStorageProviderFileAction {
+        export const enum CloudStorageProviderFileAction {
                 Download = "DOWNLOAD",
                 Upload = "UPLOAD",
                 Delete = "DELETE"
@@ -1906,6 +2061,88 @@ export namespace notifications {
         function isSupported(): boolean;
 }
 
+/**
+    * @hidden
+    * @internal
+    * @beta
+    * Limited to Microsoft-internal use
+    *
+    * This capability contains the APIs for handling events that happen to other applications on the host
+    * *while* the developer's application is running. For example, if the developer wants to be notified
+    * when another application has been installed.
+    */
+export namespace otherAppStateChange {
+        /**
+            * @hidden
+            * @beta
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * Represent an event that has happened with other number of applications installed on this host.
+            * (e.g. a new app has been installed)
+            */
+        interface OtherAppStateChangeEvent {
+                /** An array of app ids that this event applies to */
+                appIds: string[];
+        }
+        /**
+            * @hidden
+            * @beta
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * A function handler that will be called whenever an event happens with some number of applications installed on this host.
+            */
+        type OtherAppStateChangeEventHandler = (event: OtherAppStateChangeEvent) => void;
+        /**
+            * @hidden
+            * @beta
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * This function allows an app to register a handler that will receive whenever other applications are installed
+            * on the host while the developer's application is running.
+            *
+            * @param appInstallHandler - This handler will be called whenever apps are installed on the host.
+            *
+            * @throws Error if {@link app.initialize} has not successfully completed, if the platform
+            * does not support the otherAppStateChange capability, or if a valid handler is not passed to the function.
+            *
+            * @example
+            * ``` ts
+            * if (otherAppStateChange.isSupported()) {
+            *  otherAppStateChange.registerAppInstallationHandler((event: otherAppStateChange.OtherAppStateChangeEvent) => {
+            *    // code to handle the event goes here
+            *  });
+            * }
+            * ```
+            */
+        function registerAppInstallationHandler(appInstallHandler: OtherAppStateChangeEventHandler): void;
+        /**
+            * @hidden
+            * @beta
+            * @internal
+            * Limited to Microsoft-internal use
+            *
+            * This function can be called so that the handler passed to {@link registerAppInstallationHandler}
+            * will no longer receive app installation events. If this is called before registering a handler
+            * it will have no effect.
+            *
+            * @throws Error if {@link app.initialize} has not successfully completed or if the platform
+            * does not support the otherAppStateChange capability.
+            */
+        function unregisterAppInstallationHandler(): void;
+        /**
+            * Checks if the otherAppStateChange capability is supported by the host
+            * @returns boolean to represent whether the otherAppStateChange capability is supported
+            *
+            * @throws Error if {@link app.initialize} has not successfully completed
+            *
+            * @beta
+            */
+        function isSupported(): boolean;
+}
+
 export namespace remoteCamera {
         /**
             * @hidden
@@ -2043,7 +2280,7 @@ export namespace remoteCamera {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum ErrorReason {
+        const enum ErrorReason {
                 CommandResetError = 0,
                 CommandZoomInError = 1,
                 CommandZoomOutError = 2,
@@ -2085,7 +2322,7 @@ export namespace remoteCamera {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum SessionTerminatedReason {
+        const enum SessionTerminatedReason {
                 None = 0,
                 ControlDenied = 1,
                 ControlNoResponse = 2,
@@ -2294,7 +2531,7 @@ export namespace appEntity {
 }
 
 export namespace teams {
-        enum ChannelType {
+        const enum ChannelType {
                 Regular = 0,
                 Private = 1,
                 Shared = 2
@@ -2418,7 +2655,7 @@ export namespace videoEffectsEx {
             * @internal
             * Limited to Microsoft-internal use
             */
-        enum ErrorLevel {
+        const enum ErrorLevel {
                 Fatal = "fatal",
                 Warn = "warn"
         }
@@ -3867,6 +4104,15 @@ export interface Context {
             * The SharePoint relative path to the current users mysite
             */
         mySitePath?: string;
+        /**
+            * @deprecated
+            * As of 2.0.0, please use {@link app.Context.dialogParameters} instead
+            *
+            * When `processActionCommand` activates a dialog, this dialog should automatically fill in some fields with information. This information comes from M365 and is given to `processActionCommand` as `extractedParameters`.
+            * App developers need to use these `extractedParameters` in their dialog.
+            * They help pre-fill the dialog with necessary information (`dialogParameters`) along with other details.
+            */
+        dialogParameters?: Record<string, string>;
 }
 /** Represents the parameters used to share a deep link. */
 export interface ShareDeepLinkParameters {
@@ -4609,6 +4855,13 @@ export namespace app {
                     * Will be `undefined` when not running in Teams.
                     */
                 team?: TeamInfo;
+                /**
+                    * When `processActionCommand` activates a dialog, this dialog should automatically fill in some fields with information. This information comes from M365 and is given to `processActionCommand` as `extractedParameters`.
+                    * App developers need to use these `extractedParameters` in their dialog.
+                    * They help pre-fill the dialog with necessary information (`dialogParameters`) along with other details.
+                    * If there's no key/value pairs passed, the object will be empty in the case
+                    */
+                dialogParameters: Record<string, string>;
         }
         /**
             * This function is passed to registerOnThemeHandler. It is called every time the user changes their theme.
@@ -5204,6 +5457,22 @@ export namespace dialog {
         }
 }
 
+/**
+    * @beta
+    * Nested app auth capabilities
+    */
+export namespace nestedAppAuth {
+        /**
+            * Checks if MSAL-NAA channel recommended by the host
+            * @returns true if host is recommending NAA channel and false otherwise
+            *
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
+            *
+            * @beta
+            */
+        function isNAAChannelRecommended(): boolean;
+}
+
 /**
     * Namespace to interact with the geoLocation module-specific part of the SDK. This is the newer version of location module.
     *
@@ -8278,6 +8547,54 @@ export namespace sharing {
             * @throws Error if {@linkcode app.initialize} has not successfully completed
             */
         export function isSupported(): boolean;
+        /**
+            * Namespace to get the list of content shared in a Teams meeting
+            *
+            * @beta
+            */
+        export namespace history {
+                /**
+                    * Represents the data returned when calling {@link sharing.history.getContent}
+                    *
+                    * @beta
+                    */
+                interface IContentResponse {
+                        /** Id of the app where the content was shared from */
+                        appId: string;
+                        /** Title of the shared content */
+                        title: string;
+                        /** Reference of the shared content */
+                        contentReference: string;
+                        /** Id of the thread where the content was shared. This is a UUID */
+                        threadId: string;
+                        /** Id of the user who shared the content. This is a UUID */
+                        author: string;
+                        /** Type of the shared content.
+                            * For sharing to Teams stage scenarios, this value would be `ShareToStage`
+                            * Other `contentType` values will be added and documented here over time
+                            */
+                        contentType: string;
+                }
+                /**
+                    * Get the list of content shared in a Teams meeting
+                    *
+                    * @throws Error if call capability is not supported
+                    * @throws Error if returned content details are invalid
+                    * @returns Promise that will resolve with the {@link IContentResponse} objects array
+                    *
+                    * @beta
+                    */
+                function getContent(): Promise<IContentResponse[]>;
+                /**
+                    * Checks if sharing.history capability is supported by the host
+                    * @returns boolean to represent whether the sharing.history capability is supported
+                    *
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    *
+                    * @beta
+                    */
+                function isSupported(): boolean;
+        }
         export {};
 }
 
@@ -8340,8 +8657,6 @@ export namespace stageView {
                 popoutWithChat = "popoutWithChat"
         }
         /**
-            * @hidden
-            * Feature is under development
             *
             * Opens a stage view to display a Teams application
             * @beta
@@ -9774,6 +10089,16 @@ export namespace marketplace {
         export {};
 }
 
+/**
+  * @hidden
+  * Error codes that can be thrown from externalAppCommands and externalAppCardCommands Action Submit specifically
+  * @internal
+  * Limited to Microsoft-internal use
+  */
+export const enum ExternalAppErrorCode {
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+
 /**
     * @hidden
     * Create a MediaStreamTrack from the media stream with the given streamId and processed by videoFrameHandler.