@microsoft/teams-js 2.4.0-beta.0 → 2.4.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-This JavaScript library is part of the [Microsoft Teams developer platform](https://docs.microsoft.com/en-us/microsoftteams/platform/). See full [SDK reference documentation](https://docs.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 [SDK reference documentation](https://learn.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest).
 
 ## Getting Started
 
@@ -12,7 +12,7 @@ Whenever building or testing the Teams client SDK, you can run `yarn build` or `
 
 ## Installation
 
-To install the stable [version](https://docs.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest):
+To install the stable [version](https://learn.microsoft.com/javascript/api/overview/msteams-client?view=msteams-client-js-latest):
 
 ### npm
 

package/dist/MicrosoftTeams.d.ts

@@ -1,4 +1,10 @@
 // Generated by dts-bundle v0.7.3
+// Dependencies for this module:
+//   ../@fluidframework/azure-client
+//   ../@fluidframework/fluid-static
+
+import type { AzureConnectionConfig, AzureContainerServices, ITelemetryBaseLogger } from '@fluidframework/azure-client';
+import type { ContainerSchema, IFluidContainer } from '@fluidframework/fluid-static';
 
 /**
     * @hidden
@@ -895,21 +901,22 @@ export namespace files {
         /**
             * @hidden
             * Object used to represent a file
+            * @beta
             *
             * @internal
             * Limited to Microsoft-internal use
             */
         export interface File extends Blob {
                 /**
-                    * Last modified timestamp
+                    * A number that represents the number of milliseconds since the Unix epoch
                     */
-                lastModified: Date;
+                lastModified: number;
                 /**
                     * Name of the file
                     */
                 name: string;
                 /**
-                    * The file path to uniquely identify it within the file hierarchy
+                    * A string containing the path of the file relative to the ancestor directory the user selected
                     */
                 webkitRelativePath?: string;
         }
@@ -2786,7 +2793,7 @@ export interface ActionInfo {
     *
     * @remarks
     * For more details about the updated {@link app.Context} interface, visit the
-    * [Teams JavaScript client SDK](https://docs.microsoft.com/microsoftteams/platform/tabs/how-to/using-teams-client-sdk#updates-to-the-context-interface)
+    * [Teams JavaScript client SDK](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/using-teams-client-sdk#updates-to-the-context-interface)
     * overview article.
     *
     * Represents the structure of the received context message.
@@ -3828,7 +3835,7 @@ export namespace app {
                     */
                 meeting?: MeetingInfo;
                 /**
-                    * SharePoint context. This is only available when hosted in SharePoint.
+                    * When hosted in SharePoint, this is the [SharePoint PageContext](https://learn.microsoft.com/en-us/javascript/api/sp-page-context/pagecontext?view=sp-typescript-latest), else `undefined`
                     */
                 sharepoint?: any;
                 /**
@@ -3856,8 +3863,7 @@ export namespace app {
             * Initializes the library.
             *
             * @remarks
-            * This must be called before any other SDK calls
-            * but after the frame is loaded successfully.
+            * Initialize must have completed successfully (as determined by the resolved Promise) before any other library calls are made
             *
             * @param validMessageOrigins - Optionally specify a list of cross frame message origins. They must have
             * https: protocol otherwise they will be ignored. Example: https:www.example.com
@@ -4107,7 +4113,7 @@ export namespace dialog {
             * 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 appIds - Helps to validate that the call originates from the same appId as the one that invoked the task module
+            * @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.
             */
         function submit(result?: string | object, appIds?: string | string[]): void;
         /**
@@ -4679,6 +4685,53 @@ export namespace pages {
                     */
                 function isSupported(): boolean;
         }
+        /**
+            * Provides functions for navigating without needing to specify your application ID.
+            *
+            * @beta
+            */
+        namespace currentApp {
+                /**
+                    * Parameters for the NavigateWithinApp
+                    *
+                    * @beta
+                    */
+                interface NavigateWithinAppParams {
+                        /**
+                            * The developer-defined unique ID for the page defined in the manifest or when first configuring
+                            * the page. (Known as {entityId} prior to TeamsJS v.2.0.0)
+                            */
+                        pageId: string;
+                        /**
+                            * Optional developer-defined unique ID describing the content to navigate to within the page. This
+                            * can be retrieved from the Context object {@link app.PageInfo.subPageId | app.Context.page.subPageId}
+                            */
+                        subPageId?: string;
+                }
+                /**
+                    * Navigate within the currently running application with page ID, and sub-page ID (for navigating to
+                    * specific content within the page).
+                    * @param params - Parameters for the navigation
+                    * @returns a promise that will resolve if the navigation was successful
+                    *
+                    * @beta
+                    */
+                function navigateTo(params: NavigateWithinAppParams): Promise<void>;
+                /**
+                    * Navigate to the currently running application's first static page defined in the application
+                    * manifest.
+                    * @beta
+                    */
+                function navigateToDefaultPage(): Promise<void>;
+                /**
+                    * Checks if pages.currentApp capability is supported by the host
+                    * @returns true if the pages.currentApp capability is enabled in runtime.supports.pages.currentApp and
+                    * false if it is disabled
+                    *
+                    * @beta
+                    */
+                function isSupported(): boolean;
+        }
 }
 
 export interface IAppWindow {
@@ -5969,7 +6022,7 @@ export namespace profile {
                     *
                     * This id is guaranteed to be unique for an object within a tenant,
                     * and so if provided will lead to a more performant lookup. It can
-                    * be resolved via MS Graph (see https://docs.microsoft.com/en-us/graph/api/resources/users
+                    * be resolved via MS Graph (see https://learn.microsoft.com/graph/api/resources/users
                     * for examples).
                     */
                 readonly AadObjectId?: string;
@@ -6836,7 +6889,7 @@ export namespace tasks {
             * Submit the task module.
             *
             * @param result - Contains the result to be sent to the bot or the app. Typically a JSON object or a serialized version of it
-            * @param appIds - Helps to validate that the call originates from the same appId as the one that invoked the task module
+            * @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.
             */
         function submitTask(result?: string | object, appIds?: string | string[]): void;
         /**
@@ -6848,3 +6901,281 @@ export namespace tasks {
         function getDefaultSizeIfNotProvided(taskInfo: TaskInfo): TaskInfo;
 }
 
+/**
+    * Namespace to interact with the Live Share module-specific part of the SDK.
+    *
+    * @beta
+    */
+export namespace liveShare {
+        /**
+            * Options used to configure the Live Share client.
+            *
+            * @beta
+            */
+        interface LiveShareOptions {
+                /**
+                    * Optional. Configuration to use when connecting to a custom Azure Fluid Relay instance.
+                    */
+                readonly connection?: AzureConnectionConfig;
+                /**
+                    * Optional. A logger instance to receive diagnostic messages.
+                    */
+                readonly logger?: ITelemetryBaseLogger;
+                /**
+                    * Optional. Function to lookup the ID of the container to use for local testing.
+                    *
+                    * @remarks
+                    * The default implementation attempts to retrieve the containerId from the `window.location.hash`.
+                    *
+                    * If the function returns 'undefined' a new container will be created.
+                    * @returns ID of the container to connect to or `undefined` if a new container should be created.
+                    */
+                readonly getLocalTestContainerId?: () => string | undefined;
+                /**
+                    * Optional. Function to save the ID of a newly created local test container.
+                    *
+                    * @remarks
+                    * The default implementation updates `window.location.hash` with the ID of the newly created
+                    * container.
+                    * @param containerId The ID of the container that was created.
+                    */
+                readonly setLocalTestContainerId?: (containerId: string) => void;
+        }
+        /**
+            * Initializes the Live Share client.
+            * @param options Optional. Configuration options passed to the Live Share client.
+            *
+            * @beta
+            */
+        function initialize(options?: LiveShareOptions): Promise<void>;
+        /**
+            * Connects to the fluid container for the current teams context.
+            *
+            * @remarks
+            * The first client joining the container will create the container resulting in the
+            * `onContainerFirstCreated` callback being called. This callback can be used to set the initial
+            * state of of the containers object prior to the container being attached.
+            * @param fluidContainerSchema Fluid objects to create.
+            * @param onContainerFirstCreated Optional. Callback that's called when the container is first created.
+            * @returns The fluid `container` and `services` objects to use along with a `created` flag that if true means the container had to be created.
+            *
+            * @beta
+            */
+        function joinContainer(fluidContainerSchema: ContainerSchema, onContainerFirstCreated?: (container: IFluidContainer) => void): Promise<{
+                container: IFluidContainer;
+                services: AzureContainerServices;
+                created: boolean;
+        }>;
+        /**
+            * @hidden
+            * Hide from docs
+            * ------
+            * Returns the LiveShareHost object. Called by existing apps that use the TeamsFluidClient
+            * directly. This prevents existing apps from breaking and will be removed when Live Share
+            * goes GA.
+            *
+            * @beta
+            */
+        function getHost(): LiveShareHost;
+}
+
+/**
+    * @hidden
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * Allowed roles during a meeting.
+    */
+export enum UserMeetingRole {
+        guest = "Guest",
+        attendee = "Attendee",
+        presenter = "Presenter",
+        organizer = "Organizer"
+}
+/**
+    * @hidden
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * State of the current Live Share sessions backing fluid container.
+    */
+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
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * Returned from `LiveShareHost.get/setFluidContainerId()` to specify the container mapping for the
+    * current Live Share session.
+    */
+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
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * Returned from `LiveShareHost.getNtpTime()` to specify the global timestamp for the current
+    * Live Share session.
+    */
+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
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * Returned from `LiveShareHost.getFluidTenantInfo()` to specify the Fluid service to use for the
+    * current Live Share session.
+    */
+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;
+}
+/**
+    * @hidden
+    * @internal
+    * Limited to Microsoft-internal use
+    * ------
+    * Interface for hosting a Live Share session within a client like Teams.
+    */
+export class LiveShareHost {
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * Returns the Fluid Tenant connection info for user's current context.
+            */
+        getFluidTenantInfo(): Promise<IFluidTenantInfo>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * 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.
+            */
+        getFluidToken(containerId?: string): Promise<string>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * Returns the ID of the fluid container associated with the user's current context.
+            */
+        getFluidContainerId(): Promise<IFluidContainerInfo>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * 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.
+            */
+        setFluidContainerId(containerId: string): Promise<IFluidContainerInfo>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * Returns the shared clock server's current time.
+            */
+        getNtpTime(): Promise<INtpTimeInfo>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * 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.
+            */
+        registerClientId(clientId: string): Promise<UserMeetingRole[]>;
+        /**
+            * @hidden
+            * @internal
+            * Limited to Microsoft-internal use
+            * ------
+            * 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.
+            */
+        getClientRoles(clientId: string): Promise<UserMeetingRole[] | undefined>;
+}
+