@microsoft/teams-js 2.31.0-beta.1 → 2.31.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.30.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.31.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.30.0/js/MicrosoftTeams.min.js"
-  integrity="sha384-8I0Bv4bWDPSX5ZYhJcChnvrBNoieX3zASTxmZ9URwnjEVx70hsrN0ZUy/C46u8dw"
+  src="https://res.cdn.office.net/teams-js/2.31.0/js/MicrosoftTeams.min.js"
+  integrity="sha384-A2y7iMKbK0AQrgKq1YKcLB8XgtyowB2MPzC40KFfA58nQObf6xU3C5NE0cTcis0V"
   crossorigin="anonymous"
 ></script>
 
 <!-- Microsoft Teams JavaScript API (via npm) -->
-<script src="node_modules/@microsoft/teams-js@2.30.0/dist/MicrosoftTeams.min.js"></script>
+<script src="node_modules/@microsoft/teams-js@2.31.0/dist/MicrosoftTeams.min.js"></script>
 
 <!-- Microsoft Teams JavaScript API (via local) -->
 <script src="MicrosoftTeams.min.js"></script>

package/dist/esm/packages/teams-js/dts/internal/appHelpers.d.ts

@@ -1,8 +1,18 @@
 import * as app from '../public/app/app';
+/**
+ * The response of the notify success callback.
+ */
+export interface NotifySuccessResponse {
+    /**
+     * It shows if the callback resolved successfully in the host. If the host does not support answering back to the callback, the result is unknown.
+     */
+    hasFinishedSuccessfully: true | 'unknown';
+}
 export declare function appInitializeHelper(apiVersionTag: string, validMessageOrigins?: string[]): Promise<void>;
 export declare function notifyAppLoadedHelper(apiVersionTag: string): void;
 export declare function notifyExpectedFailureHelper(apiVersionTag: string, expectedFailureRequest: app.IExpectedFailureRequest): void;
 export declare function notifyFailureHelper(apiVersiontag: string, appInitializationFailedRequest: app.IFailedRequest): void;
-export declare function notifySuccessHelper(apiVersionTag: string): void;
+export declare function notifySuccessHelper(apiVersionTag: string): Promise<NotifySuccessResponse>;
+export declare function callNotifySuccessInHost(apiVersionTag: string): Promise<NotifySuccessResponse>;
 export declare function registerOnThemeChangeHandlerHelper(apiVersionTag: string, handler: app.themeHandler): void;
 export declare function openLinkHelper(apiVersionTag: string, deepLink: string): Promise<void>;

package/dist/esm/packages/teams-js/dts/internal/appIdValidation.d.ts

@@ -1,3 +1,4 @@
+import { AppId } from '../public/appId';
 /**
  * This function can be used to validate if a string is a "valid" app id.
  * Valid is a relative term, in this case. Truly valid app ids are UUIDs as documented in the schema:
@@ -14,3 +15,12 @@ export declare const minimumValidAppIdLength = 4;
 export declare const maximumValidAppIdLength = 256;
 export declare function isStringWithinAppIdLengthLimits(potentialAppId: string): boolean;
 export declare function doesStringContainNonPrintableCharacters(str: string): boolean;
+/**
+ * @hidden
+ * Checks if the incoming app id is an instance of AppId
+ * @param potentialAppId An object to check if it's an instance of AppId
+ * @throws Error with a message describing the violation
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function validateAppIdInstance(potentialAppId: AppId): void;

package/dist/esm/packages/teams-js/dts/internal/handlers.d.ts

@@ -1,5 +1,5 @@
 import { FrameContexts } from '../public/constants';
-import { LoadContext, ResumeContext } from '../public/interfaces';
+import { HostToAppPerformanceMetrics, LoadContext, ResumeContext } from '../public/interfaces';
 /**
  * @internal
  * Limited to Microsoft-internal use
@@ -54,6 +54,16 @@ export declare function registerOnThemeChangeHandler(apiVersionTag: string, hand
  * Limited to Microsoft-internal use
  */
 export declare function handleThemeChange(theme: string): void;
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function registerHostToAppPerformanceMetricsHandler(handler: (metrics: HostToAppPerformanceMetrics) => void): void;
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function handleHostToAppPerformanceMetrics(metrics: HostToAppPerformanceMetrics): void;
 /**
  * @internal
  * Limited to Microsoft-internal use

package/dist/esm/packages/teams-js/dts/internal/hostToAppTelemetry.d.ts

@@ -0,0 +1,51 @@
+import { Debugger } from 'debug';
+import { CallbackInformation } from './interfaces';
+import { MessageRequest, MessageResponse } from './messageObjects';
+import { UUID as MessageUUID } from './uuidObject';
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export default class HostToAppMessageDelayTelemetry {
+    private static callbackInformation;
+    /**
+     * @internal
+     * Limited to Microsoft-internal use
+     *
+     * Store information about a particular message.
+     * @param messageUUID The message id for the request.
+     * @param callbackInformation The information of the callback.
+     */
+    static storeCallbackInformation(messageUUID: MessageUUID, callbackInformation: CallbackInformation): void;
+    /**
+     * @internal
+     * Limited to Microsoft-internal use
+     */
+    static clearMessages(): void;
+    /**
+     * @internal
+     * Limited to Microsoft-internal use
+     */
+    static deleteMessageInformation(callbackId: MessageUUID): void;
+    /**
+     * @internal
+     * Limited to Microsoft-internal use
+     *
+     * Executes telemetry actions related to host to app performance metrics where event is raised in the host.
+     * @param message The request from the host.
+     * @param logger The logger in case an error occurs.
+     * @param endTime The ending time for calculating the elapsed time
+     */
+    static handleOneWayPerformanceMetrics(message: MessageRequest, logger: Debugger, endTime?: number): void;
+    /**
+     * @internal
+     * Limited to Microsoft-internal use
+     *
+     * Executes telemetry actions related to host to app performance metrics.
+     * @param callbackId The message id for the request.
+     * @param message The response from the host.
+     * @param logger The logger in case an error occurs.
+     * @param endTime The ending time for calculating the elapsed time
+     */
+    static handlePerformanceMetrics(callbackID: MessageUUID, message: MessageResponse, logger: Debugger, endTime?: number): void;
+}

package/dist/esm/packages/teams-js/dts/internal/interfaces.d.ts

@@ -45,3 +45,14 @@ export interface DOMMessageEvent {
     func: string;
     args?: any[];
 }
+/**
+ * @hidden
+ * Meant for providing information related to certain callback context.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export interface CallbackInformation {
+    name: string;
+    calledAt: number;
+}

package/dist/esm/packages/teams-js/dts/internal/messageObjects.d.ts

@@ -15,6 +15,7 @@ export interface MessageRequest {
     uuid?: MessageUUID;
     func: string;
     timestamp?: number;
+    monotonicTimestamp?: number;
     args?: any[];
     apiVersionTag?: string;
     isPartialResponse?: boolean;
@@ -28,6 +29,7 @@ export interface SerializedMessageRequest {
     uuidAsString?: string;
     func: string;
     timestamp?: number;
+    monotonicTimestamp?: number;
     args?: any[];
     apiVersionTag?: string;
 }
@@ -39,6 +41,7 @@ export interface SerializedMessageResponse {
     id: MessageID;
     uuidAsString?: string;
     args?: any[];
+    monotonicTimestamp?: number;
     isPartialResponse?: boolean;
 }
 /**
@@ -49,6 +52,7 @@ export interface MessageResponse {
     id: MessageID;
     uuid?: MessageUUID;
     args?: any[];
+    monotonicTimestamp?: number;
     isPartialResponse?: boolean;
 }
 /**
@@ -65,6 +69,7 @@ export interface MessageResponse {
 export interface MessageRequestWithRequiredProperties extends MessageRequest {
     id: MessageID;
     uuid: MessageUUID;
+    /** Deprecated field, is still here for backwards compatibility */
     timestamp: number;
 }
 export declare const serializeMessageRequest: (message: MessageRequest) => SerializedMessageRequest;

package/dist/esm/packages/teams-js/dts/internal/pagesHelpers.d.ts

@@ -0,0 +1,24 @@
+import { FrameInfo, ShareDeepLinkParameters, TabInformation, TabInstance, TabInstanceParameters } from '../public/interfaces';
+import * as pages from '../public/pages/pages';
+import { ApiVersionNumber } from './telemetry';
+/**
+ * v2 APIs telemetry file: All of APIs in this capability file should send out API version v2 ONLY
+ */
+export declare const pagesTelemetryVersionNumber: ApiVersionNumber;
+export declare function navigateCrossDomainHelper(apiVersionTag: string, url: string): Promise<void>;
+export declare function backStackNavigateBackHelper(apiVersionTag: string): Promise<void>;
+export declare function tabsNavigateToTabHelper(apiVersionTag: string, tabInstance: TabInstance): Promise<void>;
+/**
+ * @hidden
+ */
+export declare function returnFocusHelper(apiVersionTag: string, navigateForward?: boolean): void;
+export declare function getTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
+export declare function getMruTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
+export declare function shareDeepLinkHelper(apiVersionTag: string, deepLinkParameters: ShareDeepLinkParameters): void;
+export declare function setCurrentFrameHelper(apiVersionTag: string, frameInfo: FrameInfo): void;
+export declare function configSetValidityStateHelper(apiVersionTag: string, validityState: boolean): void;
+export declare function getConfigHelper(apiVersionTag: string): Promise<pages.InstanceConfig>;
+export declare function configSetConfigHelper(apiVersionTag: string, instanceConfig: pages.InstanceConfig): Promise<void>;
+export declare function isAppNavigationParametersObject(obj: pages.AppNavigationParameters | pages.NavigateToAppParams): obj is pages.AppNavigationParameters;
+export declare function convertNavigateToAppParamsToAppNavigationParameters(params: pages.NavigateToAppParams): pages.AppNavigationParameters;
+export declare function convertAppNavigationParametersToNavigateToAppParams(params: pages.AppNavigationParameters): pages.NavigateToAppParams;

package/dist/esm/packages/teams-js/dts/internal/profileUtil.d.ts

@@ -1,4 +1,4 @@
-import { profile } from '../public/profile';
+import * as profile from '../public/profile';
 /**
  * @hidden
  * Validates the request parameters
@@ -9,3 +9,25 @@ import { profile } from '../public/profile';
  * Limited to Microsoft-internal use
  */
 export declare function validateShowProfileRequest(showProfileRequest: profile.ShowProfileRequest): [boolean, string | undefined];
+/**
+ * Internal representation of a DOMRect suitable for sending via postMessage.
+ */
+type Rectangle = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * @beta
+ * @hidden
+ * An internal representation of the showProfile parameters suitable for sending via postMessage.
+ * The hub expects to receive an object of this type.
+ */
+export interface ShowProfileRequestInternal {
+    modality?: profile.Modality;
+    persona: profile.Persona;
+    targetRectangle: Rectangle;
+    triggerType: profile.TriggerType;
+}
+export {};

package/dist/esm/packages/teams-js/dts/internal/uint8array-extras/uint8array-extras.d.ts

@@ -0,0 +1,6 @@
+export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export declare function isUint8Array(value: unknown): value is Uint8Array;
+export declare function base64ToUint8Array(base64String: string): Uint8Array;
+export declare function uint8ArrayToString(array: Uint8Array | ArrayBuffer, encoding?: string): string;
+export declare function base64ToString(base64String: string): string;
+export declare function assertUint8ArrayOrArrayBuffer(value: any): void;

package/dist/esm/packages/teams-js/dts/internal/utils.d.ts

@@ -1,5 +1,5 @@
 import { AdaptiveCardVersion, SdkError } from '../public/interfaces';
-import { pages } from '../public/pages';
+import * as pages from '../public/pages/pages';
 /**
  * @internal
  * Limited to Microsoft-internal use
@@ -198,3 +198,22 @@ export declare function hasScriptTags(input: string): boolean;
  * Limited to Microsoft-internal use
  */
 export declare function validateUuid(id: string | undefined | null): void;
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ * @returns current timestamp in milliseconds
+ */
+export declare function getCurrentTimestamp(): number | undefined;
+/**
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ *
+ * Function to check whether the data is a primitive type or a plain object.
+ * Recursion is limited to a maximum depth of 1000 to prevent excessive nesting and potential stack overflow.
+ *
+ * @param value The value to check
+ * @returns true if the value is a primitive type or a plain object, false otherwise
+ *
+ */
+export declare function isPrimitiveOrPlainObject(value: unknown, depth?: number): boolean;

package/dist/esm/packages/teams-js/dts/internal/videoEffectsUtils.d.ts

@@ -1,5 +1,5 @@
-import { videoEffectsEx } from '../private/videoEffectsEx';
-import { videoEffects } from '../public/videoEffects';
+import * as videoEffectsEx from '../private/videoEffectsEx';
+import * as videoEffects from '../public/videoEffects';
 import { VideoPerformanceMonitor } from './videoPerformanceMonitor';
 /**
  * @hidden

package/dist/esm/packages/teams-js/dts/internal/visualMediaHelpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @hidden
+ * All properties common to Image and Video Props
+ *
+ * @beta
+ */
+export interface VisualMediaProps {
+    /**
+     * @hidden
+     * The maximum number of media items that can be selected at once is limited to values that are less than or equal to the maximum visual media selection limit.
+     */
+    maxVisualMediaCount: number;
+}
+export declare const maxVisualMediaSelectionLimit = 10;

package/dist/esm/packages/teams-js/dts/internal/webStorageHelpers.d.ts

@@ -0,0 +1,4 @@
+import { HostName } from '../public/constants';
+export declare let cachedHostName: HostName | null;
+export declare function getCachedHostName(): Promise<HostName>;
+export declare function clearWebStorageCachedHostNameForTests(): void;

package/dist/esm/packages/teams-js/dts/private/appEntity.d.ts

@@ -1,89 +1,89 @@
+/**
+ * @hidden
+ * Module to interact with the application entities specific part of the SDK.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ *
+ * @module
+ */
 import { SdkError } from '../public/interfaces';
 /**
  * @hidden
- * Namespace to interact with the application entities specific part of the SDK.
+ *
+ * Information on an app entity
  *
  * @internal
  * Limited to Microsoft-internal use
  */
-export declare namespace appEntity {
+export interface AppEntity {
     /**
      * @hidden
-     *
-     * Information on an app entity
+     * ID of the application
      *
      * @internal
      * Limited to Microsoft-internal use
      */
-    interface AppEntity {
-        /**
-         * @hidden
-         * ID of the application
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        appId: string;
-        /**
-         * @hidden
-         * URL for the application's icon
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        appIconUrl: string;
-        /**
-         * @hidden
-         * Content URL for the app entity
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        contentUrl: string;
-        /**
-         * @hidden
-         * The display name for the app entity
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        displayName: string;
-        /**
-         * @hidden
-         * Website URL for the app entity. It is meant to be opened by the user in a browser.
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        websiteUrl: string;
-    }
+    appId: string;
     /**
      * @hidden
-     * Hide from docs
-     * --------
-     * Open the Tab Gallery and retrieve the app entity
-     * @param threadId ID of the thread where the app entity will be created
-     * @param categories A list of application categories that will be displayed in the opened tab gallery
-     * @param subEntityId An object that will be made available to the application being configured
-     *                      through the Context's subEntityId field.
-     * @param callback Callback that will be triggered once the app entity information is available.
-     *                 The callback takes two arguments: an SdkError in case something happened (i.e.
-     *                 no permissions to execute the API) and the app entity configuration, if available
+     * URL for the application's icon
      *
      * @internal
      * Limited to Microsoft-internal use
      */
-    function selectAppEntity(threadId: string, categories: string[], subEntityId: string, callback: (sdkError?: SdkError, appEntity?: AppEntity) => void): void;
+    appIconUrl: string;
     /**
      * @hidden
+     * Content URL for the app entity
      *
-     * Checks if the appEntity capability is supported by the host
-     * @returns boolean to represent whether the appEntity capability is supported
+     * @internal
+     * Limited to Microsoft-internal use
+     */
+    contentUrl: string;
+    /**
+     * @hidden
+     * The display name for the app entity
      *
-     * @throws Error if {@linkcode app.initialize} has not successfully completed
+     * @internal
+     * Limited to Microsoft-internal use
+     */
+    displayName: string;
+    /**
+     * @hidden
+     * Website URL for the app entity. It is meant to be opened by the user in a browser.
      *
      * @internal
      * Limited to Microsoft-internal use
      */
-    function isSupported(): boolean;
+    websiteUrl: string;
 }
+/**
+ * @hidden
+ * Hide from docs
+ * --------
+ * Open the Tab Gallery and retrieve the app entity
+ * @param threadId ID of the thread where the app entity will be created
+ * @param categories A list of application categories that will be displayed in the opened tab gallery
+ * @param subEntityId An object that will be made available to the application being configured
+ *                      through the Context's subEntityId field.
+ * @param callback Callback that will be triggered once the app entity information is available.
+ *                 The callback takes two arguments: an SdkError in case something happened (i.e.
+ *                 no permissions to execute the API) and the app entity configuration, if available
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function selectAppEntity(threadId: string, categories: string[], subEntityId: string, callback: (sdkError?: SdkError, appEntity?: AppEntity) => void): void;
+/**
+ * @hidden
+ *
+ * Checks if the appEntity capability is supported by the host
+ * @returns boolean to represent whether the appEntity capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/private/conversations.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @hidden
+ * Module to interact with the conversational subEntities inside the tab
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ *
+ * @module
+ */
 import { ChatMembersInformation } from './interfaces';
 export interface OpenConversationRequest {
     /**
@@ -98,55 +107,46 @@ export interface ConversationResponse {
 }
 /**
  * @hidden
- * Namespace to interact with the conversational subEntities inside the tab
+ * Hide from docs
+ * --------------
+ * Allows the user to start or continue a conversation with each subentity inside the tab
+ *
+ * @returns Promise resolved upon completion
  *
  * @internal
  * Limited to Microsoft-internal use
  */
-export declare namespace conversations {
-    /**
-     * @hidden
-     * Hide from docs
-     * --------------
-     * Allows the user to start or continue a conversation with each subentity inside the tab
-     *
-     * @returns Promise resolved upon completion
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    function openConversation(openConversationRequest: OpenConversationRequest): Promise<void>;
-    /**
-     * @hidden
-     *
-     * Allows the user to close the conversation in the right pane
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    function closeConversation(): void;
-    /**
-     * @hidden
-     * Hide from docs
-     * ------
-     * Allows retrieval of information for all chat members.
-     * NOTE: This value should be used only as a hint as to who the members are
-     * and never as proof of membership in case your app is being hosted by a malicious party.
-     *
-     * @returns Promise resolved with information on all chat members
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    function getChatMembers(): Promise<ChatMembersInformation>;
-    /**
-     * Checks if the conversations capability is supported by the host
-     * @returns boolean to represent whether conversations capability is supported
-     *
-     * @throws Error if {@linkcode app.initialize} has not successfully completed
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    function isSupported(): boolean;
-}
+export declare function openConversation(openConversationRequest: OpenConversationRequest): Promise<void>;
+/**
+ * @hidden
+ *
+ * Allows the user to close the conversation in the right pane
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function closeConversation(): void;
+/**
+ * @hidden
+ * Hide from docs
+ * ------
+ * Allows retrieval of information for all chat members.
+ * NOTE: This value should be used only as a hint as to who the members are
+ * and never as proof of membership in case your app is being hosted by a malicious party.
+ *
+ * @returns Promise resolved with information on all chat members
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function getChatMembers(): Promise<ChatMembersInformation>;
+/**
+ * Checks if the conversations capability is supported by the host
+ * @returns boolean to represent whether conversations capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/private/copilot/copilot.d.ts

@@ -0,0 +1,2 @@
+import * as eligibility from './eligibility';
+export { eligibility };

package/dist/esm/packages/teams-js/dts/private/copilot/eligibility.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @beta
+ * @hidden
+ * User information required by specific apps
+ * @internal
+ * Limited to Microsoft-internal use
+ * @module
+ */
+import { AppEligibilityInformation } from '../../public/interfaces';
+/**
+ * @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
+ */
+export declare 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
+ */
+export declare function getEligibilityInfo(): Promise<AppEligibilityInformation>;