@microsoft/teams-js 2.30.0 → 2.31.0-beta.0

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

@@ -0,0 +1,17 @@
+/**
+ * Interface for objects that can be serialized and passed to the host
+ */
+export interface ISerializable {
+    /**
+     * @returns A serializable representation of the object, used for passing objects to the host.
+     */
+    serialize(): string | object;
+}
+/**
+ * @hidden
+ * @internal
+ * Used by the communication layer to make sure that an argument being passed to the host is serializable.
+ * @param arg The argument to evaluate
+ * @returns Whether or not the argument is serializable.
+ */
+export declare function isSerializable(arg: unknown): arg is ISerializable;

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

@@ -0,0 +1,101 @@
+import { pages } from './pages';
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config} namespace instead.
+ *
+ * Namespace to interact with the settings-specific part of the SDK.
+ * This object is usable only on the settings frame.
+ */
+/** Register on remove handler function type */
+export type registerOnRemoveHandlerFunctionType = (evt: RemoveEvent) => void;
+/** Register on save handler function type */
+export type registerOnSaveHandlerFunctionType = (evt: SaveEvent) => void;
+/** Set settings on complete function type */
+export type setSettingsOnCompleteFunctionType = (status: boolean, reason?: string) => void;
+/** Get settings callback function type */
+export type getSettingsCallbackFunctionType = (instanceSettings: Settings) => void;
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config} instead.
+ * @remarks
+ * Renamed to config in pages.Config
+ */
+type Settings = pages.InstanceConfig;
+export { Settings };
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.SaveEvent} instead.
+ * @remarks
+ * See pages.SaveEvent
+ */
+type SaveEvent = pages.config.SaveEvent;
+export { SaveEvent };
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.RemoveEvent} instead.
+ * @remarks
+ * See pages.RemoveEvent
+ */
+type RemoveEvent = pages.config.RemoveEvent;
+export { RemoveEvent };
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.SaveParameters} instead.
+ * @remarks
+ * See pages.SaveParameters
+ */
+type SaveParameters = pages.config.SaveParameters;
+export { SaveParameters };
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.setValidityState pages.config.setValidityState(validityState: boolean): void} instead.
+ *
+ * Sets the validity state for the settings.
+ * The initial value is false, so the user cannot save the settings 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;
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.getConfig pages.getConfig(): Promise\<InstanceConfig\>} instead.
+ *
+ * Gets the settings for the current instance.
+ *
+ * @param callback - The callback to invoke when the {@link Settings} object is retrieved.
+ */
+export declare function getSettings(callback: getSettingsCallbackFunctionType): void;
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.setConfig pages.config.setConfig(instanceSettings: Config): Promise\<void\>} instead.
+ *
+ * Sets the settings for the current instance.
+ * This is an asynchronous operation; calls to getSettings are not guaranteed to reflect the changed state.
+ *
+ * @param - Set the desired settings for this instance.
+ */
+export declare function setSettings(instanceSettings: Settings, onComplete?: setSettingsOnCompleteFunctionType): void;
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.registerOnSaveHandler pages.config.registerOnSaveHandler(handler: registerOnSaveHandlerFunctionType): void} instead.
+ *
+ * Registers a handler for when the user attempts to save the settings. 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: registerOnSaveHandlerFunctionType): void;
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link pages.config.registerOnRemoveHandler pages.config.registerOnRemoveHandler(handler: registerOnRemoveHandlerFunctionType): void} instead.
+ *
+ * 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: registerOnRemoveHandlerFunctionType): void;

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

@@ -0,0 +1,124 @@
+import { SdkError } from './interfaces';
+/**
+ * Namespace to open a share dialog for web content.
+ * For more info, see [Share to Teams from personal app or tab](https://learn.microsoft.com/microsoftteams/platform/concepts/build-and-test/share-to-teams-from-personal-app-or-tab)
+ */
+export declare namespace sharing {
+    /** shareWebContent callback function type */
+    export type shareWebContentCallbackFunctionType = (err?: SdkError) => void;
+    /** Type of message that can be sent or received by the sharing APIs */
+    export const SharingAPIMessages: {
+        /**
+         * Share web content message.
+         * @internal
+         */
+        shareWebContent: string;
+    };
+    type ContentType = 'URL';
+    /** Represents parameters for base shared content. */
+    interface IBaseSharedContent {
+        /** Shared content type  */
+        type: ContentType;
+    }
+    /** IShareRequestContentType defines share request type. */
+    export type IShareRequestContentType = IURLContent;
+    /** Represents IShareRequest parameters interface.
+     * @typeparam T - The identity type
+     */
+    export interface IShareRequest<T> {
+        /** Content of the share request. */
+        content: T[];
+    }
+    /** Represents IURLContent parameters. */
+    export interface IURLContent extends IBaseSharedContent {
+        /** Type */
+        type: 'URL';
+        /**
+         * Required URL
+         */
+        url: string;
+        /**
+         * Default initial message text
+         */
+        message?: string;
+        /**
+         * Show URL preview, defaults to true
+         */
+        preview?: boolean;
+    }
+    /**
+     * Feature is under development
+     * Opens a share dialog for web content
+     *
+     * @param shareWebContentRequest - web content info
+     * @returns Promise that will be fulfilled when the operation has completed
+     */
+    export function shareWebContent(shareWebContentRequest: IShareRequest<IShareRequestContentType>): Promise<void>;
+    /**
+     * @deprecated
+     * As of TeamsJS v2.0.0, please use {@link sharing.shareWebContent sharing.shareWebContent(shareWebContentRequest: IShareRequest\<IShareRequestContentType\>): Promise\<void\>} instead.
+     *
+     * Feature is under development
+     * Opens a share dialog for web content
+     *
+     * @param shareWebContentRequest - web content info
+     * @param callback - optional callback
+     */
+    export function shareWebContent(shareWebContentRequest: IShareRequest<IShareRequestContentType>, callback: shareWebContentCallbackFunctionType): void;
+    /**
+     * Checks if the sharing capability is supported by the host
+     * @returns boolean to represent whether the sharing capability is supported
+     *
+     * @throws Error if {@linkcode app.initialize} has not successfully completed
+     */
+    export function isSupported(): boolean;
+    /**
+     * Namespace to get the list of content shared in a Teams meeting
+     *
+     * @beta
+     */
+    export namespace history {
+        /**
+         * Represents the data returned when calling {@link sharing.history.getContent}
+         *
+         * @beta
+         */
+        interface IContentResponse {
+            /** Id of the app where the content was shared from */
+            appId: string;
+            /** Title of the shared content */
+            title: string;
+            /** Reference of the shared content */
+            contentReference: string;
+            /** Id of the thread where the content was shared. */
+            threadId: string;
+            /** Id of the user who shared the content. */
+            author: string;
+            /** Type of the shared content.
+             * For sharing to Teams stage scenarios, this value would be `ShareToStage`
+             * Other `contentType` values will be added and documented here over time
+             */
+            contentType: string;
+        }
+        /**
+         * Get the list of content shared in a Teams meeting
+         *
+         * @throws Error if call capability is not supported
+         * @throws Error if returned content details are invalid
+         * @returns Promise that will resolve with the {@link IContentResponse} objects array
+         *
+         * @beta
+         */
+        function getContent(): Promise<IContentResponse[]>;
+        /**
+         * Checks if sharing.history capability is supported by the host
+         * @returns boolean to represent whether the sharing.history capability is supported
+         *
+         * @throws Error if {@linkcode app.initialize} has not successfully completed
+         *
+         * @beta
+         */
+        function isSupported(): boolean;
+    }
+    export {};
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Namespace to interact with the stage view specific part of the SDK.
+ *
+ *  @beta
+ */
+export declare namespace stageView {
+    /**
+     * Parameters to open a stage view.
+     */
+    interface StageViewParams {
+        /**
+         * The ID of the Teams application to be opened.
+         */
+        appId: string;
+        /**
+         * The URL of the content to display.
+         */
+        contentUrl: string;
+        /**
+         * The chat or channel ID.
+         */
+        threadId: string;
+        /**
+         * The messageId identifies a particular channel meeting within the channel as specified by the threadId above. This should be used only when trying to open the stage view for a channel meeting. It will be a no-op for other scenarios
+         */
+        messageId?: string;
+        /**
+         * The title to give the stage view.
+         */
+        title?: string;
+        /**
+         * The Teams application website URL.
+         */
+        websiteUrl?: string;
+        /**
+         * The entity ID of the Teams application content being opened.
+         */
+        entityId?: string;
+        /**
+         * The open mode for stage content.
+         * Optional param: if not passed, hosts can choose their default openMode.
+         * If a host does not support any specific openMode, It will fallback to StageViewOpenMode.modal.
+         */
+        openMode?: StageViewOpenMode;
+    }
+    /**
+     * The open mode for stage content.
+     */
+    enum StageViewOpenMode {
+        /**
+         * Open the content in a modal.
+         */
+        modal = "modal",
+        /**
+         * Open the content in a popped-out window.
+         */
+        popout = "popout",
+        /**
+         * Open the content in a popped-out window with chat collaboration.
+         */
+        popoutWithChat = "popoutWithChat"
+    }
+    /**
+     *
+     * Opens a stage view to display a Teams application
+     * @beta
+     * @param stageViewParams - The parameters to pass into the stage view.
+     * @returns Promise that resolves or rejects with an error once the stage view is closed.
+     */
+    function open(stageViewParams: StageViewParams): Promise<void>;
+    /**
+     * Checks if stageView capability is supported by the host
+     * @beta
+     * @returns boolean to represent whether the stageView capability is supported
+     *
+     * @throws Error if {@linkcode app.initialize} has not successfully completed
+     *
+     */
+    function isSupported(): boolean;
+    /**
+     * Namespace for actions that can be taken by the stage view itself.
+     *
+     * @beta
+     */
+    namespace self {
+        /**
+         * Closes the current stage view. This function will be a no-op if called from outside of a stage view.
+         * @returns Promise that resolves or rejects with an error once the stage view is closed.
+         *
+         * @beta
+         * @throws Error if stageView.self.close is not supported in the current context or if `app.initialize()` has not resolved successfully.
+         */
+        function close(): Promise<void>;
+        /**
+         * Checks if stageView.self capability is supported by the host
+         * @beta
+         * @returns boolean to represent whether the stageView.self capability is supported
+         *
+         * @throws Error if {@linkcode app.initialize} has not successfully completed
+         *
+         */
+        function isSupported(): boolean;
+    }
+}

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

@@ -0,0 +1,62 @@
+import { IAppWindow } from './appWindow';
+import { TaskInfo } from './interfaces';
+/**
+ * @deprecated
+ * As of TeamsJS v2.0.0, please use {@link dialog} namespace instead.
+ *
+ * Namespace to interact with the task module-specific part of the SDK.
+ * This object is usable only on the content frame.
+ * The tasks namespace will be deprecated. Please use dialog for future developments.
+ */
+export declare namespace tasks {
+    /**
+     * Function type that is used to receive the result when a task module is submitted by
+     * calling {@link tasks.submitTask tasks.submitTask(result?: string | object, appIds?: string | string[]): void}
+     *
+     * @param err - If the task module failed, this string contains the reason for failure. If the task module succeeded, this value is the empty string.
+     * @param result - On success, this is the value passed to the `result` parameter of {@link tasks.submitTask tasks.submitTask(result?: string | object, appIds?: string | string[]): void}. On failure, this is the empty string.
+     */
+    type startTaskSubmitHandlerFunctionType = (err: string, result: string | object) => void;
+    /**
+     * @deprecated
+     * As of 2.8.0:
+     * - For url-based dialogs, please use {@link dialog.url.open dialog.url.open(urlDialogInfo: UrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void} .
+     * - For url-based dialogs with bot interaction, please use {@link dialog.url.bot.open dialog.url.bot.open(botUrlDialogInfo: BotUrlDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void}
+     * - For Adaptive Card-based dialogs:
+     *   - In Teams, please continue to use this function until the new functions in {@link dialog.adaptiveCard} have been fully implemented. You can tell at runtime when they are implemented in Teams by checking
+     *     the return value of the {@link dialog.adaptiveCard.isSupported} function. This documentation line will also be removed once they have been fully implemented in Teams.
+     *   - In all other hosts, please use {@link dialog.adaptiveCard.open dialog.adaptiveCard.open(cardDialogInfo: CardDialogInfo, submitHandler?: DialogSubmitHandler, messageFromChildHandler?: PostMessageChannel): void}
+     *
+     * Allows an app to open the task module.
+     *
+     * @param taskInfo - An object containing the parameters of the task module
+     * @param submitHandler - Handler to call when the task module is completed
+     */
+    function startTask(taskInfo: TaskInfo, submitHandler?: startTaskSubmitHandlerFunctionType): IAppWindow;
+    /**
+     * @deprecated
+     * As of TeamsJS v2.0.0, please use {@link dialog.update.resize dialog.update.resize(dimensions: DialogSize): void} instead.
+     *
+     * Update height/width task info properties.
+     *
+     * @param taskInfo - An object containing width and height properties
+     */
+    function updateTask(taskInfo: TaskInfo): void;
+    /**
+     * @deprecated
+     * As of 2.8.0, please use {@link dialog.url.submit} instead.
+     *
+     * 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 - 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;
+    /**
+     * Sets the height and width of the {@link TaskInfo} object to the original height and width, if initially specified,
+     * otherwise uses the height and width values corresponding to {@link DialogDimension | TaskModuleDimension.Small}
+     * @param taskInfo TaskInfo object from which to extract size info, if specified
+     * @returns TaskInfo with height and width specified
+     */
+    function getDefaultSizeIfNotProvided(taskInfo: TaskInfo): TaskInfo;
+}

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

@@ -0,0 +1,77 @@
+import { LoadContext } from './interfaces';
+export declare namespace teamsCore {
+    /** Ready to unload function type */
+    type readyToUnloadFunctionType = () => void;
+    /** Register on load handler function type */
+    type registerOnLoadHandlerFunctionType = (context: LoadContext) => void;
+    /** Register before unload handler function type */
+    type registerBeforeUnloadHandlerFunctionType = (readyToUnload: readyToUnloadFunctionType) => boolean;
+    /**
+     * Enable print capability to support printing page using Ctrl+P and cmd+P
+     */
+    function enablePrintCapability(): void;
+    /**
+     * default print handler
+     */
+    function print(): void;
+    /**
+     * Registers a handler to be called when the page has been requested to load.
+     *
+     * @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/app-caching)
+     * for a more detailed explanation about using this API.
+     *
+     * @param handler - The handler to invoke when the page is loaded.
+     *
+     * @beta
+     */
+    function registerOnLoadHandler(handler: registerOnLoadHandlerFunctionType): void;
+    /**
+     * @hidden
+     * Undocumented helper function with shared code between deprecated version and current version of the registerOnLoadHandler 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 page is loaded.
+     * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+     *
+     * @deprecated
+     */
+    function registerOnLoadHandlerHelper(apiVersionTag: string, handler: registerOnLoadHandlerFunctionType, versionSpecificHelper?: () => void): void;
+    /**
+     * Registers a handler to be called before the page is unloaded.
+     *
+     * @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/app-caching)
+     * for a more detailed explanation about using this API.
+     *
+     * @param handler - The handler to invoke before the page is unloaded. If this handler returns true the page should
+     * invoke the readyToUnload function provided to it once it's ready to be unloaded.
+     *
+     * @beta
+     */
+    function registerBeforeUnloadHandler(handler: registerBeforeUnloadHandlerFunctionType): void;
+    /**
+     * @hidden
+     * Undocumented helper function with shared code between deprecated version and current version of the registerBeforeUnloadHandler API.
+     *
+     * @internal
+     * Limited to Microsoft-internal use
+     *
+     * @param handler - - The handler to invoke before the page is unloaded. If this handler returns true the page should
+     * invoke the readyToUnload function provided to it once it's ready to be unloaded.
+     * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+     *
+     * @deprecated
+     */
+    function registerBeforeUnloadHandlerHelper(apiVersionTag: string, handler: registerBeforeUnloadHandlerFunctionType, versionSpecificHelper?: () => void): void;
+    /**
+     * Checks if teamsCore capability is supported by the host
+     *
+     * @returns boolean to represent whether the teamsCore capability is supported
+     *
+     * @throws Error if {@linkcode app.initialize} has not successfully completed
+     *
+     */
+    function isSupported(): boolean;
+}

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

@@ -0,0 +1,119 @@
+import { SdkError } from './interfaces';
+/**
+ * Extended files API 3P storage providers, features like sending Blob from Teams to 3P app on user
+ * actions like drag and drop to compose
+ * @beta
+ */
+export declare namespace thirdPartyCloudStorage {
+    /**
+     * Interface to assemble file chunks
+     * @beta
+     */
+    interface AssembleAttachment {
+        /** A number representing the sequence of the attachment in the file chunks. */
+        sequence: number;
+        /** A Blob object representing the data of the file chunks. */
+        file: Blob;
+    }
+    /**
+     * Object used to represent a file
+     * @beta
+     *
+     */
+    interface FilesFor3PStorage extends Blob {
+        /**
+         * A number that represents the number of milliseconds since the Unix epoch
+         */
+        lastModified: number;
+        /**
+         * Name of the file
+         */
+        name: string;
+        /**
+         * file type
+         */
+        type: string;
+        /**
+         * A string containing the path of the file relative to the ancestor directory the user selected
+         */
+        webkitRelativePath?: string;
+    }
+    /**
+     * File chunks an output of getDragAndDropFiles API from platform
+     * @beta
+     */
+    interface FileChunk {
+        /**
+         * Base 64 data for the requested uri
+         */
+        chunk: string;
+        /**
+         * chunk sequence number
+         */
+        chunkSequence: number;
+        /**
+         * Indicates whether this chunk is the final segment of a file
+         */
+        endOfFile: boolean;
+    }
+    /**
+     * Output of getDragAndDropFiles API from platform
+     * @beta
+     */
+    interface FileResult {
+        /**
+         * Error encountered in getDragAndDropFiles API
+         */
+        error?: SdkError;
+        /**
+         * File chunk which will be assemebled and converted into a blob
+         */
+        fileChunk: FileChunk;
+        /**
+         * File index of the file for which chunk data is getting recieved
+         */
+        fileIndex: number;
+        /**
+         * File type/MIME type which is getting recieved
+         */
+        fileType: string;
+        /**
+         * Indicates whether this file is the last one in a sequence.
+         */
+        isLastFile: boolean;
+        /**
+         * The name of the file.
+         */
+        fileName: string;
+    }
+    /**
+     * Defines the callback function received from Third Party App
+     * @beta
+     */
+    interface DragAndDropFileCallback {
+        /**
+         * Definition of the callback which is received from third party app when calling {@link thirdPartyCloudStorage.getDragAndDropFiles}
+         * An array of drag and dropped files {@link thirdPartyCloudStorage.FilesFor3PStorage}
+         * Error encountered during the API call {@link SdkError}
+         */
+        (files: FilesFor3PStorage[], error?: SdkError): void;
+    }
+    /**
+     * Get drag-and-drop files using a callback.
+     *
+     * @param {string} dragAndDropInput - unique id which is a combination of replyToId + threadId of teams chat and channel.
+     *   Both replyToId and threadId can be fetched from application context.
+     * @param {DragAndDropFileCallback} dragAndDropFileCallback - callback
+     *   A callback function to handle the result of the operation
+     * @beta
+     */
+    function getDragAndDropFiles(dragAndDropInput: string, dragAndDropFileCallback: DragAndDropFileCallback): void;
+    /**
+     * Checks if the thirdPartyCloudStorage capability is supported by the host
+     * @returns boolean to represent whether the thirdPartyCloudStorage capability is supported
+     *
+     * @throws Error if {@linkcode app.initialize} has not successfully completed
+     * @beta
+     */
+    function isSupported(): boolean;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * @hidden
+ *  Package version.
+ */
+export declare const version = "ERROR: This value should be replaced by webpack!";