@microsoft/teams-js 2.26.0 → 2.27.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.27.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.27.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-QGb/h0ACuraFEnqrpkMcMBTU+baTLZy1Mh61IGbM206IPGRWiWCIL5dkLzG1RKZH"
   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.27.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/MicrosoftTeams.d.ts

@@ -488,6 +488,45 @@ export namespace conversations {
         function isSupported(): boolean;
 }
 
+/**
+    * @beta
+    * @hidden
+    * Namespace to delegate copilot app specific APIs
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export namespace copilot {
+        /**
+            * @beta
+            * @hidden
+            * User information required by specific apps
+            * @internal
+            * Limited to Microsoft-internal use
+            */
+        namespace eligibility {
+                /**
+                    * @hidden
+                    * @internal
+                    * Limited to Microsoft-internal use
+                    * @beta
+                    * @returns boolean to represent whether copilot.eligibility capability is supported
+                    *
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    */
+                function isSupported(): boolean;
+                /**
+                    * @hidden
+                    * @internal
+                    * Limited to Microsoft-internal use
+                    * @beta
+                    * @returns the copilot eligibility information about the user
+                    *
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    */
+                function getEligibilityInfo(): AppEligibilityInformation;
+        }
+}
+
 /**
     * @hidden
     * Namespace to delegate authentication and message extension requests to the host
@@ -2957,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
@@ -3613,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.
@@ -4501,6 +4724,7 @@ export enum DevicePermission {
 /** @hidden */
 export interface HostVersionsInfo {
         adaptiveCardSchemaVersion?: AdaptiveCardVersion;
+        appEligibilityInformation?: AppEligibilityInformation;
 }
 /**
     * Represents the major and minor versions of the Adaptive Card schema in the current host
@@ -4511,6 +4735,146 @@ export interface AdaptiveCardVersion {
         /** Represents the minor version number. */
         minorVersion: number;
 }
+/**
+    * @hidden
+    * Eligibility Information for the app user.
+    *
+    * @beta
+    */
+export interface AppEligibilityInformation {
+        /**
+            * Describes the user’s age group, which can have implications on which product they are able to use.
+            */
+        ageGroup: LegalAgeGroupClassification | null;
+        /**
+            * Describes the user’s chat experience based on their eligible licenses & their tenant’s eligible licenses.
+            * A user will be in at most one cohort.
+            */
+        cohort: Cohort | null;
+        /**
+            * Indicates that the user is eligible for Microsoft Entra ID Authenticated Copilot experience.
+            */
+        isCopilotEligible: boolean;
+        /**
+            * Implementation may change to be based on tenant-home region rather than IP.
+            */
+        isCopilotEnabledRegion: boolean;
+        /**
+            * Indicates if the tenant admin has opted the user out of Copilot.
+            */
+        isOptedOutByAdmin: boolean;
+        /**
+            * Education Eligibility Information for the app user
+            */
+        userClassification: UserClassification;
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export interface UserClassificationWithEduType {
+        /**
+            * For EDU tenants only. Indicates if the tenant is higher ed or K12.
+            */
+        eduType: EduType;
+        /**
+            * Describes additional traits of the user that contribute to FRE experience, etc.
+            */
+        persona: Persona.Faculty | Persona.Student;
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export interface UserClassificationWithOtherType {
+        persona: Persona.Other;
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export type UserClassification = UserClassificationWithEduType | UserClassificationWithOtherType;
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export enum Cohort {
+        BCAIS = "bcais",
+        BCWAF = "bcwaf",
+        BCWBF = "bcwbf"
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export enum Persona {
+        /**
+            * User has a faculty license
+            */
+        Faculty = "faculty",
+        /**
+            * User has a student license
+            */
+        Student = "student",
+        /**
+            * When user is not a faculty or student
+            */
+        Other = "other"
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export enum LegalAgeGroupClassification {
+        /**
+            * The user is considered an adult based on the age-related regulations of their country or region.
+            */
+        Adult = "adult",
+        /**
+            * The user is a minor but is from a country or region that has no age-related regulations.
+            */
+        MinorNoParentalConsentRequired = "minorNoParentalConsentRequired",
+        /**
+            * Reserved for future use
+            */
+        MinorWithoutParentalConsent = "minorWithoutParentalConsent",
+        /**
+            * The user is considered a minor based on the age-related regulations of their country or region, and the administrator
+            * of the account obtained appropriate consent from a parent or guardian.
+            */
+        MinorWithParentalConsent = "minorWithParentalConsent",
+        /**
+            * The user is from a country or region that has additional age-related regulations, such as the United States,
+            * United Kingdom, European Union, or South Korea, and the user's age is between a minor and an adult age
+            * (as stipulated based on country or region). Generally, this means that teenagers are considered as notAdult in regulated countries.
+            */
+        NonAdult = "nonAdult"
+}
+/**
+    * @hidden
+    *
+    * @beta
+    */
+export enum EduType {
+        /**
+            * User is from a tenant labeled as “HigherEd”
+            */
+        HigherEducation = "higherEducation",
+        /**
+            * User is from a tenant labeled as “K12”
+            */
+        K12 = "k12",
+        /**
+            * User is from a tenant labeled as “Others” (e.g. research institutions)
+            */
+        Other = "other"
+}
 /**
     * Currently supported Mime type
     */
@@ -5131,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 {
@@ -5724,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>;
@@ -5747,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
@@ -5754,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
             *
@@ -5766,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
             *
@@ -8807,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.
                     */
@@ -9111,6 +9559,7 @@ export namespace webStorage {
             */
         function isSupported(): boolean;
 }
+export function clearWebStorageCachedHostNameForTests(): void;
 
 /**
     * Used to interact with call functionality, including starting calls with other users.
@@ -9319,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