@microsoft/teams-js 2.4.2 → 2.5.0-beta.1

package/README.md

@@ -1,14 +1,14 @@
-# Microsoft Teams JavaScript client SDK
+# Microsoft Teams JavaScript client library
 
-Welcome to the Teams JavaScript client SDK! For breaking changes, please refer to our [changelog](./CHANGELOG.md) in the current `<root>/packages/teams-js` directory.
+Welcome to the Teams JavaScript client library! For breaking changes, please refer to our [changelog](./CHANGELOG.md) in the current `<root>/packages/teams-js` directory.
 
-This JavaScript library is part of the [Microsoft Teams developer platform](https://learn.microsoft.com/microsoftteams/platform/). See full [SDK reference documentation](https://learn.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest).
+This JavaScript library is part of the [Microsoft Teams developer platform](https://learn.microsoft.com/microsoftteams/platform/). See full [library reference documentation](https://learn.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest).
 
 ## Getting Started
 
 See [instructions](../../README.md#Getting-Started) in the monorepo root for how to clone and build the repository.
 
-Whenever building or testing the Teams client SDK, you can run `yarn build` or `yarn test` from the packages/teams-js directory.
+Whenever building or testing the Teams client library, you can run `yarn build` or `yarn test` from the packages/teams-js directory.
 
 ## Installation
 
@@ -40,7 +40,7 @@ import { app } from '@microsoft/teams-js';
 
 ### As a script tag
 
-Reference the SDK inside of your `.html` page using:
+Reference the library inside of your `.html` page using:
 
 ```html
 <!-- Microsoft Teams JavaScript API (via CDN) -->
@@ -59,7 +59,7 @@ Reference the SDK inside of your `.html` page using:
 
 ### Dependencies
 
-Teams client SDK 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 SDK, you need to make sure the polyfill is included and initialized before the Teams client SDK is.
+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
 
@@ -67,7 +67,7 @@ Stay tuned for examples coming soon.
 
 ## Testing
 
-The [Teams Test App](https://aka.ms/teams-test-app) is used to validate the Teams client SDK APIs.
+The [Teams Test App](https://aka.ms/teams-test-app) is used to validate the Teams client library APIs.
 
 ## Troubleshooting
 

package/dist/MicrosoftTeams.d.ts

@@ -2159,8 +2159,6 @@ export namespace videoEx {
     * Namespace to interact with the authentication-specific part of the SDK.
     *
     * This object is used for starting or completing authentication flows.
-    *
-    * @beta
     */
 export namespace authentication {
         function initialize(): void;
@@ -3437,8 +3435,6 @@ export enum DevicePermission {
 
 /**
     * Namespace to interact with app initialization and lifecycle.
-    *
-    * @beta
     */
 export namespace app {
         const Messages: {
@@ -3499,7 +3495,7 @@ export namespace app {
                     */
                 reason: FailedReason;
                 /**
-                    * A message that describes the failure
+                    * This property is currently unused.
                     */
                 message?: string;
         }
@@ -4042,6 +4038,8 @@ export namespace chat {
             * @param openChatRequest: {@link OpenSingleChatRequest}- a request object that contains a user's email as well as an optional message parameter.
             *
             * @returns Promise resolved upon completion
+            *
+            * @beta
             */
         function openChat(openChatRequest: OpenSingleChatRequest): Promise<void>;
         /**
@@ -4052,8 +4050,17 @@ export namespace chat {
             * @param openChatRequest: {@link OpenGroupChatRequest} - a request object that contains a list of user emails as well as optional parameters for message and topic (display name for the group chat).
             *
             * @returns Promise resolved upon completion
+            *
+            * @beta
             */
         function openGroupChat(openChatRequest: OpenGroupChatRequest): Promise<void>;
+        /**
+            * Checks if chat capability is supported by the host
+            *
+            * @returns boolean to represent whether the chat capability is supported
+            *
+            * @beta
+            */
         function isSupported(): boolean;
 }
 export {};
@@ -4066,6 +4073,8 @@ export {};
 export namespace dialog {
         /**
             * Data Structure to represent the SDK response when dialog closes
+            *
+            * @beta
             */
         interface ISdkResponse {
                 /**
@@ -4073,12 +4082,23 @@ export namespace dialog {
                     */
                 err?: string;
                 /**
-                    * Result value that the dialog is submitted with using {@linkcode submit} function
-                    *
+                    * Value provided in the `result` parameter by the dialog when the {@linkcode submit} function
+                    * was called.
+                    * If the dialog was closed by the user without submitting (e.g., using a control in the corner
+                    * of the dialog), this value will be `undefined` here.
                     */
                 result?: string | object;
         }
+        /**
+            * Handler used to receive and process messages sent between a dialog and the app that launched it
+            * @beta
+            */
         type PostMessageChannel = (message: any) => void;
+        /**
+            * Handler used for receiving results when a dialog closes, either the value passed by {@linkcode submit}
+            * or an error if the dialog was closed by the user.
+            * @beta
+            */
         type DialogSubmitHandler = (result: ISdkResponse) => void;
         /**
             * @hidden
@@ -4088,6 +4108,8 @@ export namespace dialog {
             * Function is called during app initialization
             * @internal
             * Limited to Microsoft-internal use
+            *
+            * @beta
             */
         function initialize(): void;
         /**
@@ -4101,13 +4123,19 @@ export namespace 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
+            * @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;
         /**
@@ -4117,12 +4145,16 @@ export namespace dialog {
             * 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;
         /**
@@ -4132,33 +4164,45 @@ export namespace dialog {
             * 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 module is supported by the host
             *
             * @returns boolean to represent whether dialog module is supported
+            *
+            * @beta
             */
         function isSupported(): boolean;
         /**
             * Namespace to update the dialog
+            *
+            * @beta
             */
         namespace update {
                 /**
                     * Update dimensions - height/width of a dialog.
                     *
                     * @param dimensions - An object containing width and height properties.
+                    *
+                    * @beta
                     */
                 function resize(dimensions: DialogSize): void;
                 /**
                     * Checks if dialog.update capability is supported by the host
                     *
                     * @returns boolean to represent whether dialog.update is supported
+                    *
+                    * @beta
                     */
                 function isSupported(): boolean;
         }
         /**
             * Namespace to open a dialog that sends results to the bot framework
+            *
+            * @beta
             */
         namespace bot {
                 /**
@@ -4169,12 +4213,16 @@ export namespace 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(botUrlDialogInfo: BotUrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void;
                 /**
                     * Checks if dialog.bot capability is supported by the host
                     *
                     * @returns boolean to represent whether dialog.bot is supported
+                    *
+                    * @beta
                     */
                 function isSupported(): boolean;
         }
@@ -4185,6 +4233,8 @@ export namespace dialog {
             *
             * @internal
             * Limited to Microsoft-internal use
+            *
+            * @beta
             */
         function getDialogInfoFromUrlDialogInfo(urlDialogInfo: UrlDialogInfo): DialogInfo;
         /**
@@ -4194,6 +4244,8 @@ export namespace dialog {
             *
             * @internal
             * Limited to Microsoft-internal use
+            *
+            * @beta
             */
         function getDialogInfoFromBotUrlDialogInfo(botUrlDialogInfo: BotUrlDialogInfo): DialogInfo;
 }
@@ -4299,13 +4351,13 @@ export namespace geoLocation {
 
 /**
     * Navigation-specific part of the SDK.
-    *
-    * @beta
     */
 export namespace pages {
         /**
             * 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
+            * effect and will be a no-op when called.
             * @param navigateForward - Determines the direction to focus in host.
             */
         function returnFocus(navigateForward?: boolean): void;
@@ -4313,6 +4365,8 @@ export namespace pages {
             * @hidden
             *
             * Registers a handler for specifying focus when it passes from the host to the application.
+            * On mobile hosts or hosts where there is no UI notion of "focus" the handler registered with
+            * this function will never be called.
             *
             * @param handler - The handler for placing focus within the application.
             *
@@ -4390,6 +4444,7 @@ export namespace pages {
         function navigateToApp(params: NavigateToAppParams): Promise<void>;
         /**
             * Shares a deep link that a user can use to navigate back to a specific state in this page.
+            * Please note that this method does yet work on mobile hosts.
             *
             * @param deepLinkParameters - ID and label for the link and fallback URL.
             */
@@ -4397,6 +4452,8 @@ export namespace pages {
         /**
             * Registers a handler for changes from or to full-screen view for a tab.
             * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+            * On hosts where there is no support for making an app full screen, the handler registered
+            * with this function will never be called.
             * @param handler - The handler to invoke when the user toggles full-screen view for a tab.
             */
         function registerFullScreenHandler(handler: (isFullScreen: boolean) => void): void;
@@ -5988,27 +6045,34 @@ export namespace profile {
             * Opens a profile card at a specified position to show profile information about a persona.
             * @param showProfileRequest The parameters to position the card and identify the target user.
             * @returns Promise that will be fulfilled when the operation has completed
+            *
+            * @beta
             */
         function showProfile(showProfileRequest: ShowProfileRequest): Promise<void>;
         /**
             * The type of modalities that are supported when showing a profile.
             * Can be provided as an optional hint with the request and will be
             * respected if the hosting M365 application supports it.
+            *
+            * @beta
             */
         type Modality = 'Card' | 'Expanded';
         /**
             * The type of the profile trigger.
             *  - MouseHover: The user hovered a target.
-            *  - MouseClick: The user clicked a target.
-            *  - KeyboardPress: The user initiated the show profile request with their keyboard.
+            *  - Press: The target was pressed with either a mouse click or keyboard key press.
             *  - AppRequest: The show profile request is happening programmatically, without direct user interaction.
+            *
+            * @beta
             */
-        type TriggerType = 'MouseHover' | 'MouseClick' | 'KeyboardPress' | 'AppRequest';
+        type TriggerType = 'MouseHover' | 'Press' | 'AppRequest';
         /**
             * The set of identifiers that are supported for resolving the persona.
             *
             * At least one is required, and if multiple are provided then only the highest
             * priority one will be used (AadObjectId > Upn > Smtp).
+            *
+            * @beta
             */
         type PersonaIdentifiers = {
                 /**
@@ -6031,6 +6095,8 @@ export namespace profile {
         };
         /**
             * The persona to show the profile for.
+            *
+            * @beta
             */
         interface Persona {
                 /**
@@ -6044,6 +6110,8 @@ export namespace profile {
         }
         /**
             * Input parameters provided to the showProfile API.
+            *
+            * @beta
             */
         interface ShowProfileRequest {
                 /**
@@ -6063,8 +6131,30 @@ export namespace profile {
                     */
                 triggerType: TriggerType;
         }
+        /**
+            * Checks if the profile capability is supported by the host
+            *
+            * @returns boolean to represent whether the profile capability is supported
+            *
+            * @beta
+            */
         function isSupported(): boolean;
 }
+/**
+    * Internal representation of a DOMRect suitable for sending via postMessage.
+    */
+export type Rectangle = {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+};
+export interface ShowProfileRequestInternal {
+        modality?: profile.Modality;
+        persona: profile.Persona;
+        targetRectangle: Rectangle;
+        triggerType: profile.TriggerType;
+}
 
 /**
     * Namespace to video extensibility of the SDK
@@ -6366,7 +6456,7 @@ export namespace stageView {
         function isSupported(): boolean;
 }
 
-export const version: string;
+export const version = "ERROR: This value should be replaced by webpack!";
 
 /**
     * Contains functionality to allow web apps to store data in webview cache
@@ -6895,3 +6985,198 @@ export namespace tasks {
         function getDefaultSizeIfNotProvided(taskInfo: TaskInfo): TaskInfo;
 }
 
+/**
+    * @hidden
+    * Allowed roles during a meeting.
+    *
+    * @beta
+    */
+export enum UserMeetingRole {
+        guest = "Guest",
+        attendee = "Attendee",
+        presenter = "Presenter",
+        organizer = "Organizer"
+}
+/**
+    * @hidden
+    * State of the current Live Share sessions backing fluid container.
+    *
+    * @beta
+    */
+export enum ContainerState {
+        /**
+            * The call to `LiveShareHost.setContainerId()` successfully created the container mapping
+            * for the current Live Share session.
+            */
+        added = "Added",
+        /**
+            * A container mapping for the current Live Share Session already exists and should be used
+            * when joining the sessions Fluid container.
+            */
+        alreadyExists = "AlreadyExists",
+        /**
+            * The call to `LiveShareHost.setContainerId()` failed to create the container mapping due to
+            * another client having already set the container ID for the current Live Share session.
+            */
+        conflict = "Conflict",
+        /**
+            * A container mapping for the current Live Share session doesn't exist yet.
+            */
+        notFound = "NotFound"
+}
+/**
+    * @hidden
+    * Returned from `LiveShareHost.get/setFluidContainerId()` to specify the container mapping for the
+    * current Live Share session.
+    *
+    * @beta
+    */
+export interface IFluidContainerInfo {
+        /**
+            * State of the containerId mapping.
+            */
+        containerState: ContainerState;
+        /**
+            * ID of the container to join for the meeting. Undefined if the container hasn't been
+            * created yet.
+            */
+        containerId: string | undefined;
+        /**
+            * If true, the local client should create the container and then save the created containers
+            * ID to the mapping service.
+            */
+        shouldCreate: boolean;
+        /**
+            * If `containerId` is undefined and `shouldCreate` is false, the container isn't ready but
+            * another client is creating it. The local client should wait the specified amount of time and
+            * then ask for the container info again.
+            */
+        retryAfter: number;
+}
+/**
+    * @hidden
+    * Returned from `LiveShareHost.getNtpTime()` to specify the global timestamp for the current
+    * Live Share session.
+    *
+    * @beta
+    */
+export interface INtpTimeInfo {
+        /**
+            * ISO 8601 formatted server time. For example: '2019-09-07T15:50-04:00'
+            */
+        ntpTime: string;
+        /**
+            * Server time expressed as the number of milliseconds since the ECMAScript epoch.
+            */
+        ntpTimeInUTC: number;
+}
+/**
+    * @hidden
+    * Returned from `LiveShareHost.getFluidTenantInfo()` to specify the Fluid service to use for the
+    * current Live Share session.
+    *
+    * @beta
+    */
+export interface IFluidTenantInfo {
+        /**
+            * The Fluid Tenant ID Live Share should use.
+            */
+        tenantId: string;
+        /**
+            * The Fluid service endpoint Live Share should use.
+            */
+        serviceEndpoint?: string;
+        /**
+            * @deprecated
+            * As of Fluid 1.0 this configuration information has been deprecated in favor of
+            * `serviceEndpoint`.
+            */
+        ordererEndpoint: string;
+        /**
+            * @deprecated
+            * As of Fluid 1.0 this configuration information has been deprecated in favor of
+            * `serviceEndpoint`.
+            */
+        storageEndpoint: string;
+}
+/**
+    * Live Share host implementation for O365 and Teams clients.
+    *
+    * @beta
+    */
+export class LiveShareHost {
+        /**
+            * @hidden
+            * Returns the Fluid Tenant connection info for user's current context.
+            *
+            * @beta
+            */
+        getFluidTenantInfo(): Promise<IFluidTenantInfo>;
+        /**
+            * @hidden
+            * Returns the fluid access token for mapped container Id.
+            *
+            * @param containerId Fluid's container Id for the request. Undefined for new containers.
+            * @returns token for connecting to Fluid's session.
+            *
+            * @beta
+            */
+        getFluidToken(containerId?: string): Promise<string>;
+        /**
+            * @hidden
+            * Returns the ID of the fluid container associated with the user's current context.
+            *
+            * @beta
+            */
+        getFluidContainerId(): Promise<IFluidContainerInfo>;
+        /**
+            * @hidden
+            * Sets the ID of the fluid container associated with the current context.
+            *
+            * @remarks
+            * If this returns false, the client should delete the container they created and then call
+            * `getFluidContainerId()` to get the ID of the container being used.
+            * @param containerId ID of the fluid container the client created.
+            * @returns A data structure with a `containerState` indicating the success or failure of the request.
+            *
+            * @beta
+            */
+        setFluidContainerId(containerId: string): Promise<IFluidContainerInfo>;
+        /**
+            * @hidden
+            * Returns the shared clock server's current time.
+            *
+            * @beta
+            */
+        getNtpTime(): Promise<INtpTimeInfo>;
+        /**
+            * @hidden
+            * Associates the fluid client ID with a set of user roles.
+            *
+            * @param clientId The ID for the current user's Fluid client. Changes on reconnects.
+            * @returns The roles for the current user.
+            *
+            * @beta
+            */
+        registerClientId(clientId: string): Promise<UserMeetingRole[]>;
+        /**
+            * @hidden
+            * Returns the roles associated with a client ID.
+            *
+            * @param clientId The Client ID the message was received from.
+            * @returns The roles for a given client. Returns `undefined` if the client ID hasn't been registered yet.
+            *
+            * @beta
+            */
+        getClientRoles(clientId: string): Promise<UserMeetingRole[] | undefined>;
+        /**
+            * Returns a host instance for the client that can be passed to the `LiveShareClient` class.
+            *
+            * @remarks
+            * The application must first be initialized and may only be called from `meetingStage` or `sidePanel` contexts.
+            *
+            * @beta
+            */
+        static create(): LiveShareHost;
+}
+