@microsoft/teams-js 2.27.0-beta.0 → 2.28.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.26.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.28.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.26.0/js/MicrosoftTeams.min.js"
-  integrity="sha384-gqPg5qCjdUgTGRZ/stLskrnJllL5h5+f4kTqvxVqtl2FdT7PVRa9Q7zq4gFlZ7bO"
+  src="https://res.cdn.office.net/teams-js/2.28.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-gT2igbByugSUPXBgDA+rtfKk4JMSCfG+3DKSivyLqF2Riv4vTLqaC/tFpySw0eIM"
   crossorigin="anonymous"
 ></script>
 
 <!-- Microsoft Teams JavaScript API (via npm) -->
-<script src="node_modules/@microsoft/teams-js@2.26.0/dist/MicrosoftTeams.min.js"></script>
+<script src="node_modules/@microsoft/teams-js@2.28.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/MicrosoftTeams.d.ts

@@ -2996,6 +2996,182 @@ export namespace videoEffectsEx {
         function notifyFatalError(errorMessage: string): void;
 }
 
+/**
+    * @hidden
+    * @internal
+    * @beta
+    * Limited to Microsoft-internal use
+    *
+    * This capability allows an app to associate apps with a host entity, such as a Teams channel or chat, and configure them as needed.
+    */
+export namespace hostEntity {
+        export enum AppTypes {
+                edu = "EDU"
+        }
+        /**
+            * Id of the teams entity like channel, chat
+            */
+        interface TeamsEntityId {
+                threadId: string;
+        }
+        /**
+            * Id of message in which channel meeting is created
+            */
+        export interface TeamsChannelMeetingEntityIds extends TeamsEntityId {
+                parentMessageId: string;
+        }
+        /**
+            * Id of the host entity
+            */
+        export type HostEntityIds = TeamsEntityId | TeamsChannelMeetingEntityIds;
+        /**
+            * @hidden
+            * @internal
+            * @beta
+            * Limited to Microsoft-internal use
+            *
+            * CRUD operations for tabs associated with apps
+            */
+        export namespace tab {
+                /**
+                    * Represents information about a static tab instance
+                    */
+                interface StaticTabInstance extends TabInstance {
+                        tabType: 'StaticTab';
+                }
+                /**
+                    * Represents information about a configurable tab instance
+                    */
+                interface ConfigurableTabInstance extends TabInstance {
+                        tabType: 'ConfigurableTab';
+                }
+                /**
+                    * Represents information about a tab instance associated with a host entity like chat, channel or meeting. Cab be a configurable tab or static tab.
+                    */
+                type HostEntityTabInstance = StaticTabInstance | ConfigurableTabInstance;
+                /**
+                    * Represents all tabs associated with a host entity like chat, channel or meeting
+                    */
+                interface HostEntityTabInstances {
+                        allTabs: HostEntityTabInstance[];
+                }
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Launches host-owned UI that lets a user select an app, installs it if required,
+                    * runs through app configuration if required, and then associates the app with the threadId provided
+                    *
+                    * @param hostEntityIds Ids of the host entity like channel, chat or meeting
+                    *
+                    * @param appTypes What type of applications to show the user. If EDU is passed as appType, only apps supported by EDU tenant are shown.
+                    * If no value is passed, all apps are shown.
+                    *
+                    * @returns The HostEntityTabInstance of the newly associated app
+                    *
+                    * @throws Error if host does not support this capability, library as not been initialized successfully, input parameters are invalid, user cancels operation or installing
+                    * or configuring or adding tab fails
+                    */
+                function addAndConfigure(hostEntityIds: HostEntityIds, appTypes?: AppTypes[]): Promise<HostEntityTabInstance>;
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Returns all tab instances associated with a host entity
+                    *
+                    * @param hostEntityIds Ids of the host entity like channel, chat or meeting
+                    *
+                    * @returns Object with array of HostEntityTabInstance's associated with a host entity
+                    *
+                    * @throws Error if host does not support this capability, library as not been initialized successfully, input parameters are invalid or fetching tabs fails
+                    */
+                function getAll(hostEntityIds: HostEntityIds): Promise<HostEntityTabInstances>;
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Launches host-owned UI that lets a user re-configure the contentUrl of the tab
+                    *
+                    * @param tab Configurable tab instance that needs to be updated
+                    *
+                    * @param hostEntityIds Ids of the host entity like channel, chat or meeting
+                    *
+                    * @returns The HostEntityTabInstance of the updated tab
+                    *
+                    * @throws Error if host does not support this capability, library as not been initialized successfully, input parameters are invalid, user cancels operation,
+                    * re-configuring tab fails or if tab is a static tab
+                    */
+                function reconfigure(tab: ConfigurableTabInstance, hostEntityIds: HostEntityIds): Promise<ConfigurableTabInstance>;
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Launches host-owned UI that lets a user rename the tab
+                    *
+                    * @param tab Configurable tab instance that needs to be updated
+                    *
+                    * @param hostEntityIds Ids of the host entity like channel, chat or meeting
+                    *
+                    * @returns The HostEntityTabInstance of the updated tab
+                    *
+                    * @throws Error if host does not support this capability, library as not been initialized successfully, input parameters are invalid, user cancels operation,
+                    * re-naming tab fails or if tab is a static tab
+                    */
+                function rename(tab: ConfigurableTabInstance, hostEntityIds: HostEntityIds): Promise<ConfigurableTabInstance>;
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Launches host-owned UI that lets a user remove the tab
+                    *
+                    * @param tab tab instance that needs to be updated. Can be static tab or configurable tab.
+                    *
+                    * @param hostEntityIds Ids of the host entity like channel, chat or meeting
+                    *
+                    * @returns Boolean. Returns true if removing tab was successful
+                    *
+                    * @throws Error if host does not support this capability, library as not been initialized successfully, input parameters are invalid, user cancels operation or
+                    * removing tab fails
+                    */
+                function remove(tab: HostEntityTabInstance, hostEntityIds: HostEntityIds): Promise<boolean>;
+                /**
+                    * @hidden
+                    * @internal
+                    * @beta
+                    * Limited to Microsoft-internal use
+                    *
+                    * Checks if the hostEntity.tab capability is supported by the host
+                    * @returns boolean to represent whether the histEntity and hostEntity.tab capability is supported
+                    *
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    */
+                function isSupported(): boolean;
+        }
+        /**
+            * @hidden
+            * @internal
+            * @beta
+            * Limited to Microsoft-internal use
+            *
+            * Checks if the hostEntity capability is supported by the host
+            * @returns boolean to represent whether the hostEntity capability is supported
+            *
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
+            */
+        export function isSupported(): boolean;
+        export {};
+}
+
 export namespace authentication {
         /**
             * @hidden
@@ -3652,6 +3828,14 @@ export interface TabInstance {
             * Website URL of this tab
             */
         websiteUrl?: string;
+        /**
+            * AppId of this tab
+            */
+        appId?: string;
+        /**
+            * Order of this tab. Order is 1-indexed.
+            */
+        order?: number;
 }
 /**
     * Indicates information about the tab instance for filtering purposes.
@@ -4582,7 +4766,7 @@ export interface AppEligibilityInformation {
         /**
             * Education Eligibility Information for the app user
             */
-        userClassification: UserClassification;
+        userClassification: UserClassification | null;
 }
 /**
     * @hidden
@@ -5311,6 +5495,30 @@ export namespace app {
         }
 }
 
+/**
+    * A strongly-typed class used to represent a "valid" app id.
+    *
+    * Valid is a relative term, in this case. Truly valid app ids are UUIDs as documented in the schema:
+    * https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema#id
+    * However, there are some older internal/hard-coded apps which violate this schema and use names like
+    * com.microsoft.teamspace.tab.youtube. For compatibility with these legacy apps, we unfortunately cannot
+    * securely and completely validate app ids as UUIDs. Based on this, the validation is limited to checking
+    * for script tags, length, and non-printable characters.
+    */
+export class AppId {
+        /**
+            * Creates a strongly-typed AppId from a string
+            *
+            * @param appIdAsString An app id represented as a string
+            * @throws Error with a message describing the exact validation violation
+            */
+        constructor(appIdAsString: string);
+        /**
+            * Returns the app id as a string
+            */
+        toString(): string;
+}
+
 export namespace appInstallDialog {
         /** Represents set of parameters needed to open the appInstallDialog. */
         interface OpenAppInstallDialogParams {
@@ -5904,6 +6112,9 @@ export function getAdaptiveCardSchemaVersion(): AdaptiveCardVersion | undefined;
 export function navigateCrossDomainHelper(apiVersionTag: string, url: string): Promise<void>;
 export function backStackNavigateBackHelper(apiVersionTag: string): Promise<void>;
 export function tabsNavigateToTabHelper(apiVersionTag: string, tabInstance: TabInstance): Promise<void>;
+/**
+    * @hidden
+    */
 export function returnFocusHelper(apiVersionTag: string, navigateForward?: boolean): void;
 export function getTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
 export function getMruTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
@@ -5927,6 +6138,51 @@ export namespace pages {
         /** Remove event function */
         type removeEventType = (evt: pages.config.RemoveEvent) => void;
         /**
+            * @hidden
+            * List of enter focus action items
+            *
+            * @internal
+            * Limited to Microsoft-internal use
+            */
+        enum EnterFocusType {
+                /**
+                    * Determines the previous direction to focus in app when hot keys entered.
+                    */
+                PreviousLandmark = 0,
+                /**
+                    * Determines the next direction to focus in app when hot keys entered.
+                    */
+                NextLandmark = 1,
+                /**
+                    * Determines if the focus should go to the particular content of the app.
+                    * Read - Focus should go to the content of the app.
+                    */
+                Read = 2,
+                /**
+                    * Determines if the focus should go to the particular content of the app.
+                    * Compose - Focus should go to the compose area (such as textbox) of the app.
+                    */
+                Compose = 3
+        }
+        /**
+            * Return focus action items
+            */
+        enum ReturnFocusType {
+                /**
+                    * Determines the direction to focus in host for previous landmark.
+                    */
+                PreviousLandmark = 0,
+                /**
+                    * Determines the direction to focus in host for next landmark.
+                    */
+                NextLandmark = 1,
+                /**
+                    * Determines if the focus should go to the host's activity feed
+                    */
+                GoToActivityFeed = 2
+        }
+        /**
+            * @deprecated
             * 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.
             * On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no
@@ -5934,6 +6190,14 @@ export namespace pages {
             * @param navigateForward - Determines the direction to focus in host.
             */
         function returnFocus(navigateForward?: boolean): void;
+        /**
+            * Return focus to the host. Will attempt to send focus to the appropriate part of the host (as specified by returnFocusType) based on where the application container falls in
+            * the F6/tab order in the host.
+            * On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no
+            * effect and will be a no-op when called.
+            * @param returnFocusType - Determines the type of focus to return to in the host.
+            */
+        function returnFocus(returnFocusType: pages.ReturnFocusType): void;
         /**
             * @hidden
             *
@@ -5946,7 +6210,7 @@ export namespace pages {
             * @internal
             * Limited to Microsoft-internal use
             */
-        function registerFocusEnterHandler(handler: (navigateForward: boolean) => void): void;
+        function registerFocusEnterHandler(handler: (navigateForward: boolean, enterFocusType?: EnterFocusType) => void): void;
         /**
             * Sets/Updates the current frame with new information
             *
@@ -8932,9 +9196,9 @@ export namespace sharing {
                         title: string;
                         /** Reference of the shared content */
                         contentReference: string;
-                        /** Id of the thread where the content was shared. This is a UUID */
+                        /** Id of the thread where the content was shared. */
                         threadId: string;
-                        /** Id of the user who shared the content. This is a UUID */
+                        /** Id of the user who shared the content. */
                         author: string;
                         /** Type of the shared content.
                             * For sharing to Teams stage scenarios, this value would be `ShareToStage`
@@ -8987,6 +9251,10 @@ export namespace stageView {
                     * The chat or channel ID.
                     */
                 threadId: string;
+                /**
+                    * The messageId identifies a particular channel meeting within the channel as specified by the threadId above. This should be used only when trying to open the stage view for a channel meeting. It will be a no-op for other scenarios
+                    */
+                messageId?: string;
                 /**
                     * The title to give the stage view.
                     */
@@ -9500,13 +9768,18 @@ export namespace thirdPartyCloudStorage {
             * @beta
             */
         interface DragAndDropFileCallback {
-                /** Callback from third party app */
+                /**
+                    * Definition of the callback which is received from third party app when calling {@link thirdPartyCloudStorage.getDragAndDropFiles}
+                    * An array of drag and dropped files {@link thirdPartyCloudStorage.FilesFor3PStorage}
+                    * Error encountered during the API call {@link SdkError}
+                    */
                 (files: FilesFor3PStorage[], error?: SdkError): void;
         }
         /**
             * Get drag-and-drop files using a callback.
             *
-            * @param {string} dragAndDropInput - Teams thread id or Teams conversation id from a Teams chat/channel
+            * @param {string} dragAndDropInput - unique id which is a combination of replyToId + threadId of teams chat and channel.
+            *   Both replyToId and threadId can be fetched from application context.
             * @param {DragAndDropFileCallback} dragAndDropFileCallback - callback
             *   A callback function to handle the result of the operation
             * @beta