@microsoft/teams-js 2.31.0-beta.1 → 2.31.0

package/dist/esm/packages/teams-js/dts/public/menus.d.ts

@@ -1,6 +1,7 @@
 /**
  * Module to interact with the menu-specific part of the SDK.
  * This object is used to show View Configuration, Action Menu and Navigation Bar Menu.
+ * @module
  */
 /**
  * @hidden

package/dist/esm/packages/teams-js/dts/public/monetization.d.ts

@@ -1,3 +1,11 @@
+/**
+ * @hidden
+ * Hidden from Docs
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ * @module
+ */
 import { SdkError } from './interfaces';
 /**
  * @hidden

package/dist/esm/packages/teams-js/dts/public/navigation.d.ts

@@ -1,7 +1,8 @@
-import { TabInstance } from './interfaces';
 /**
  * Navigation specific part of the SDK.
+ * @module
  */
+import { TabInstance } from './interfaces';
 /** Navigation on complete handler function type */
 export type onCompleteHandlerFunctionType = (status: boolean, reason?: string) => void;
 /**

package/dist/esm/packages/teams-js/dts/public/nestedAppAuth.d.ts

@@ -1,6 +1,7 @@
 /**
  * @beta
  * Nested app auth capabilities
+ * @module
  */
 /**
  * Checks if MSAL-NAA channel recommended by the host

package/dist/esm/packages/teams-js/dts/public/pages/appButton.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Provides APIs to interact with the app button part of the SDK.
+ * @module
+ */
+import { handlerFunctionType } from './pages';
+/**
+ * Registers a handler for clicking the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when the personal app button is clicked in the app bar.
+ */
+export declare function onClick(handler: handlerFunctionType): void;
+/**
+ * Registers a handler for entering hover of the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when entering hover of the personal app button in the app bar.
+ */
+export declare function onHoverEnter(handler: handlerFunctionType): void;
+/**
+ * Registers a handler for exiting hover of the app button.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when exiting hover of the personal app button in the app bar.
+ */
+export declare function onHoverLeave(handler: handlerFunctionType): void;
+/**
+ * Checks if pages.appButton capability is supported by the host
+ * @returns boolean to represent whether the pages.appButton capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/backStack.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Provides APIs for handling the user's navigational history.
+ * @module
+ */
+import { backButtonHandlerFunctionType } from './pages';
+/**
+ * @hidden
+ * Register backButtonPress handler.
+ *
+ * @internal
+ * Limited to Microsoft-internal use.
+ */
+export declare function _initialize(): void;
+/**
+ * Navigates back in the hosted application. See {@link pages.backStack.registerBackButtonHandler} for notes on usage.
+ * @returns Promise that resolves when the navigation has completed.
+ */
+export declare function navigateBack(): Promise<void>;
+/**
+ * Registers a handler for user presses of the host client's back button. Experiences that maintain an internal
+ * navigation stack should use this handler to navigate the user back within their frame. If an application finds
+ * that after running its back button handler it cannot handle the event it should call the navigateBack
+ * method to ask the host client to handle it instead.
+ * @param handler - The handler to invoke when the user presses the host client's back button.
+ */
+export declare function registerBackButtonHandler(handler: backButtonHandlerFunctionType): void;
+/**
+ * @hidden
+ * Undocumented helper function with shared code between deprecated version and current version of the registerBackButtonHandler API.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ * @param apiVersionTag - The tag indicating API version number with name
+ * @param handler - The handler to invoke when the user presses the host client's back button.
+ * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+ */
+export declare function registerBackButtonHandlerHelper(apiVersionTag: string, handler: () => boolean, versionSpecificHelper?: () => void): void;
+/**
+ * Checks if the pages.backStack capability is supported by the host
+ * @returns boolean to represent whether the pages.backStack capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/config.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Provides APIs to interact with the configuration-specific part of the SDK.
+ * This object is usable only on the configuration frame.
+ * @module
+ */
+import { handlerFunctionType, InstanceConfig, removeEventType, saveEventType } from './pages';
+/**
+ * @hidden
+ * Hide from docs because this function is only used during initialization
+ *
+ * Adds register handlers for settings.save and settings.remove upon initialization. Function is called in {@link app.initializeHelper}
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function initialize(): void;
+/**
+ * Sets the validity state for the configuration.
+ * The initial value is false, so the user cannot save the configuration until this is called with true.
+ * @param validityState - Indicates whether the save or remove button is enabled for the user.
+ */
+export declare function setValidityState(validityState: boolean): void;
+/**
+ * Sets the configuration for the current instance.
+ * This is an asynchronous operation; calls to getConfig are not guaranteed to reflect the changed state.
+ * @param instanceConfig - The desired configuration for this instance.
+ * @returns Promise that resolves when the operation has completed.
+ */
+export declare function setConfig(instanceConfig: InstanceConfig): Promise<void>;
+/**
+ * Registers a handler for when the user attempts to save the configuration. This handler should be used
+ * to create or update the underlying resource powering the content.
+ * The object passed to the handler must be used to notify whether to proceed with the save.
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ * @param handler - The handler to invoke when the user selects the Save button.
+ */
+export declare function registerOnSaveHandler(handler: saveEventType): void;
+/**
+ * @hidden
+ * Undocumented helper function with shared code between deprecated version and current version of the registerOnSaveHandler API.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ *
+ * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
+ * @param handler - The handler to invoke when the user selects the Save button.
+ * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+ */
+export declare function registerOnSaveHandlerHelper(apiVersionTag: string, handler: (evt: SaveEvent) => void, versionSpecificHelper?: () => void): void;
+/**
+ * Registers a handler for user attempts to remove content. This handler should be used
+ * to remove the underlying resource powering the content.
+ * The object passed to the handler must be used to indicate whether to proceed with the removal.
+ * Only one handler may be registered at a time. Subsequent registrations will override the first.
+ * @param handler - The handler to invoke when the user selects the Remove button.
+ */
+export declare function registerOnRemoveHandler(handler: removeEventType): void;
+/**
+ * @hidden
+ * Undocumented helper function with shared code between deprecated version and current version of the registerOnRemoveHandler API.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ *
+ * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
+ * @param handler - The handler to invoke when the user selects the Remove button.
+ * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+ */
+export declare function registerOnRemoveHandlerHelper(apiVersionTag: string, handler: (evt: RemoveEvent) => void, versionSpecificHelper?: () => void): void;
+/**
+ * Registers a handler for when the tab configuration is changed by the user
+ * @param handler - The handler to invoke when the user clicks on Settings.
+ */
+export declare function registerChangeConfigHandler(handler: handlerFunctionType): void;
+/**
+ * Describes the results of the settings.save event. Includes result, notifySuccess, and notifyFailure
+ * to indicate the return object (result) and the status of whether the settings.save call succeeded or not and why.
+ */
+export interface SaveEvent {
+    /**
+     * Object containing properties passed as arguments to the settings.save event.
+     */
+    result: SaveParameters;
+    /**
+     * Indicates that the underlying resource has been created and the config can be saved.
+     */
+    notifySuccess(): void;
+    /**
+     * Indicates that creation of the underlying resource failed and that the config cannot be saved.
+     * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
+     */
+    notifyFailure(reason?: string): void;
+}
+/**
+ * Describes the results of the settings.remove event. Includes notifySuccess, and notifyFailure
+ * to indicate the status of whether the settings.save call succeeded or not and why.
+ */
+export interface RemoveEvent {
+    /**
+     * Indicates that the underlying resource has been removed and the content can be removed.
+     */
+    notifySuccess(): void;
+    /**
+     * Indicates that removal of the underlying resource failed and that the content cannot be removed.
+     * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
+     */
+    notifyFailure(reason?: string): void;
+}
+/**
+ * Parameters used in the settings.save event
+ */
+export interface SaveParameters {
+    /**
+     * Connector's webhook Url returned as arguments to settings.save event as part of user clicking on Save
+     */
+    webhookUrl?: string;
+}
+/**
+ * Checks if the pages.config capability is supported by the host
+ * @returns boolean to represent whether the pages.config capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/currentApp.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Provides functions for navigating within your own app
+ *
+ * @remarks
+ * If you are looking to navigate to a different app, use {@link pages.navigateToApp}.
+ * @module
+ */
+/**
+ * Parameters provided to the {@link navigateTo} function
+ */
+export interface NavigateWithinAppParams {
+    /**
+     * The developer-defined unique ID for the page defined in the manifest or when first configuring
+     * the page. (Known as {@linkcode Context.entityId} prior to TeamsJS v2.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 app
+ *
+ * @remarks
+ * If you are looking to navigate to a different app, use {@link pages.navigateToApp}.
+ *
+ * @param params Parameters for the navigation
+ * @returns `Promise` that will resolve if the navigation was successful and reject if not
+ */
+export declare function navigateTo(params: NavigateWithinAppParams): Promise<void>;
+/**
+ * Navigate to the currently running app's first static page defined in the application
+ * manifest.
+ *
+ * @returns `Promise` that will resolve if the navigation was successful and reject if not
+ */
+export declare function navigateToDefaultPage(): Promise<void>;
+/**
+ * Checks if pages.currentApp capability is supported by the host
+ * @returns boolean to represent whether the pages.currentApp capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/fullTrust.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @hidden
+ * Hide from docs
+ * ------
+ * Provides APIs to interact with the full-trust part of the SDK. Limited to 1P applications
+ * @internal
+ * Limited to Microsoft-internal use
+ * @module
+ */
+/**
+ * @hidden
+ * Hide from docs
+ * ------
+ * Place the tab into full-screen mode.
+ *
+ */
+export declare function enterFullscreen(): void;
+/**
+ * @hidden
+ * Hide from docs
+ * ------
+ * Reverts the tab into normal-screen mode.
+ */
+export declare function exitFullscreen(): void;
+/**
+ * @hidden
+ *
+ * Checks if the pages.fullTrust capability is supported by the host
+ * @returns boolean to represent whether the pages.fullTrust capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;

package/dist/esm/packages/teams-js/dts/public/pages/pages.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Navigation-specific part of the SDK.
+ * @module
+ */
+import { AppId } from '../appId';
+import { FrameInfo, ShareDeepLinkParameters } from '../interfaces';
+import * as appButton from './appButton';
+import * as backStack from './backStack';
+import * as config from './config';
+import * as currentApp from './currentApp';
+import * as fullTrust from './fullTrust';
+import * as tabs from './tabs';
+/** Callback function */
+export type handlerFunctionType = () => void;
+/** Full screen function */
+export type fullScreenChangeFunctionType = (isFullScreen: boolean) => void;
+/** Back button handler function */
+export type backButtonHandlerFunctionType = () => boolean;
+/** Save event function */
+export type saveEventType = (evt: config.SaveEvent) => void;
+/** Remove event function */
+export type removeEventType = (evt: config.RemoveEvent) => void;
+/**
+ * @hidden
+ * List of enter focus action items
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare 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
+ */
+export declare 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
+ * effect and will be a no-op when called.
+ * @param navigateForward - Determines the direction to focus in host.
+ */
+export declare 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.
+ */
+export declare function returnFocus(returnFocusType: ReturnFocusType): void;
+/**
+ * @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.
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export declare function registerFocusEnterHandler(handler: (navigateForward: boolean, enterFocusType?: EnterFocusType) => void): void;
+/**
+ * Sets/Updates the current frame with new information
+ *
+ * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
+ * user clicks 'Go To Website'
+ */
+export declare function setCurrentFrame(frameInfo: FrameInfo): void;
+/**
+ * Initializes the library with context information for the frame
+ *
+ * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
+ *  user clicks 'Go To Website'
+ * @param callback - An optional callback that is executed once the application has finished initialization.
+ * @param validMessageOrigins - An optional list of cross-frame message origins. They must have
+ * https: protocol otherwise they will be ignored. Example: https:www.example.com
+ */
+export declare function initializeWithFrameContext(frameInfo: FrameInfo, callback?: handlerFunctionType, validMessageOrigins?: string[]): void;
+/**
+ * Defines the configuration of the current or desired instance
+ */
+export interface InstanceConfig {
+    /**
+     * A suggested display name for the new content.
+     * In the settings for an existing instance being updated, this call has no effect.
+     */
+    suggestedDisplayName?: string;
+    /**
+     * Sets the URL to use for the content of this instance.
+     */
+    contentUrl: string;
+    /**
+     * Sets the URL for the removal configuration experience.
+     */
+    removeUrl?: string;
+    /**
+     * Sets the URL to use for the external link to view the underlying resource in a browser.
+     */
+    websiteUrl?: string;
+    /**
+     * The developer-defined unique ID for the entity to which this content points.
+     */
+    entityId?: string;
+}
+/**
+ * Gets the config for the current instance.
+ * @returns Promise that resolves with the {@link InstanceConfig} object.
+ */
+export declare function getConfig(): Promise<InstanceConfig>;
+/**
+ * @deprecated
+ * As of 2.0.0, this API is deprecated and can be replaced by the standard JavaScript
+ * API, window.location.href, when navigating the app to a new cross-domain URL. Any URL
+ * that is redirected to must be listed in the validDomains block of the manifest. Please
+ * remove any calls to this API.
+ * @param url - The URL to navigate the frame to.
+ * @returns Promise that resolves when the navigation has completed.
+ */
+export declare function navigateCrossDomain(url: string): Promise<void>;
+/**
+ * Used to navigate to apps other than your own.
+ *
+ * If you are looking to navigate within your own app, use {@link pages.currentApp.navigateToDefaultPage} or {@link pages.currentApp.navigateTo}
+ *
+ * @param params Parameters for the navigation
+ * @returns a `Promise` that will resolve if the navigation was successful or reject if it was not
+ * @throws `Error` if the app ID is not valid or `params.webUrl` is defined but not a valid URL
+ */
+export declare function navigateToApp(params: AppNavigationParameters | 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 not yet work on mobile hosts.
+ *
+ * @param deepLinkParameters - ID and label for the link and fallback URL.
+ */
+export declare function shareDeepLink(deepLinkParameters: ShareDeepLinkParameters): void;
+/**
+ * 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.
+ */
+export declare function registerFullScreenHandler(handler: fullScreenChangeFunctionType): void;
+/**
+ * Checks if the pages 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
+ */
+export declare function isSupported(): boolean;
+/**
+ * @deprecated
+ * This interface has been deprecated in favor of a more type-safe interface using {@link AppNavigationParameters}
+ *
+ * Parameters for the {@link navigateToApp} function
+ */
+export interface NavigateToAppParams {
+    /**
+     * ID of the app to navigate to
+     */
+    appId: string;
+    /**
+     * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
+     */
+    pageId: string;
+    /**
+     * Fallback URL to open if the navigation cannot be completed within the host (e.g. if the target app is not installed)
+     */
+    webUrl?: string;
+    /**
+     * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
+     * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
+     */
+    subPageId?: string;
+    /**
+     * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
+     */
+    channelId?: string;
+    /**
+     * Optional ID of the chat or meeting where the app should be opened
+  
+     */
+    chatId?: string;
+}
+/**
+ * Type-safer version of parameters for the {@link navigateToApp} function
+ */
+export interface AppNavigationParameters {
+    /**
+     * ID of the app to navigate to
+     */
+    appId: AppId;
+    /**
+     * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
+     */
+    pageId: string;
+    /**
+     * Fallback URL to open if the navigation cannot be completed within the host (e.g., if the target app is not installed)
+     */
+    webUrl?: URL;
+    /**
+     * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
+     * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
+     */
+    subPageId?: string;
+    /**
+     * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
+     * This property has no effect in hosts where apps cannot be opened in channels
+     */
+    channelId?: string;
+    /**
+     * Optional ID of the chat or meeting where the app should be opened
+     * This property has no effect in hosts where apps cannot be opened in chats or meetings
+     */
+    chatId?: string;
+}
+export { appButton, backStack, config, currentApp, fullTrust, tabs };

package/dist/esm/packages/teams-js/dts/public/pages/tabs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Provides APIs for querying and navigating between contextual tabs of an application. Unlike personal tabs,
+ * contextual tabs are pages associated with a specific context, such as channel or chat.
+ * @module
+ */
+import { TabInformation, TabInstance, TabInstanceParameters } from '../interfaces';
+/**
+ * Navigates the hosted application to the specified tab instance.
+ * @param tabInstance - The destination tab instance.
+ * @returns Promise that resolves when the navigation has completed.
+ */
+export declare function navigateToTab(tabInstance: TabInstance): Promise<void>;
+/**
+ * Retrieves application tabs for the current user.
+ * If no TabInstanceParameters are passed, the application defaults to favorite teams and favorite channels.
+ * @param tabInstanceParameters - An optional set of flags that specify whether to scope call to favorite teams or channels.
+ * @returns Promise that resolves with the {@link TabInformation}. Contains information for the user's tabs that are owned by this application {@link TabInstance}.
+ */
+export declare function getTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
+/**
+ * Retrieves the most recently used application tabs for the current user.
+ * @param tabInstanceParameters - An optional set of flags. Note this is currently ignored and kept for future use.
+ * @returns Promise that resolves with the {@link TabInformation}. Contains information for the users' most recently used tabs {@link TabInstance}.
+ */
+export declare function getMruTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
+/**
+ * Checks if the pages.tab capability is supported by the host
+ * @returns boolean to represent whether the pages.tab capability is supported
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
+ */
+export declare function isSupported(): boolean;