@microsoft/teams-js 2.28.1-beta.0 → 2.29.0-beta.0

package/dist/MicrosoftTeams.d.ts

@@ -275,6 +275,72 @@ export interface UserJoinedTeamsInformation {
             */
         userJoinedTeams: TeamInformation[];
 }
+/**
+    * @beta
+    * @hidden
+    * The types for ActionOpenUrl
+    *
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export enum ActionOpenUrlType {
+        DeepLinkDialog = "DeepLinkDialog",
+        DeepLinkOther = "DeepLinkOther",
+        DeepLinkStageView = "DeepLinkStageView",
+        GenericUrl = "GenericUrl"
+}
+/**
+    * @beta
+    * @hidden
+    * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
+    * and IExternalAppCardActionForCEAService.handleActionOpenUrl
+    *
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export interface ActionOpenUrlError {
+        errorCode: ActionOpenUrlErrorCode;
+        message?: string;
+}
+/**
+    * @beta
+    * @hidden
+    * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
+    * and IExternalAppCardActionForCEAService.handleActionOpenUrl
+    *
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export enum ActionOpenUrlErrorCode {
+        INTERNAL_ERROR = "INTERNAL_ERROR",
+        INVALID_LINK = "INVALID_LINK",
+        NOT_SUPPORTED = "NOT_SUPPORTED"
+}
+/**
+    * @beta
+    * @hidden
+    * The payload that is used when executing an Adaptive Card Action.Submit
+    *
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export interface IAdaptiveCardActionSubmit {
+        id: string;
+        data: string | Record<string, unknown>;
+}
+/**
+    * @beta
+    * @hidden
+    * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
+    * and IExternalAppCardActionForCEAService.handleActionSubmit
+    *
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export interface ActionSubmitError {
+        errorCode: ExternalAppErrorCode;
+        message?: string;
+}
 
 export function uploadCustomApp(manifestBlob: Blob, onComplete?: (status: boolean, reason?: string) => void): void;
 /**
@@ -867,80 +933,84 @@ export namespace externalAppCardActions {
                 GenericUrl = "GenericUrl"
         }
         /**
+            * @beta
             * @hidden
-            * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
-            *
+            * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
             * @internal
             * Limited to Microsoft-internal use
+            * @param appId ID of the application the request is intended for. This must be a UUID
+            * @param actionSubmitPayload The Adaptive Card Action.Submit payload
+            * @param cardActionsConfig The card actions configuration. This indicates which subtypes should be handled by this API
+            * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
             */
-        interface ActionOpenUrlError {
-                errorCode: ActionOpenUrlErrorCode;
-                message?: string;
-        }
+        function processActionSubmit(appId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
         /**
+            * @beta
             * @hidden
-            * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
+            * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
+            * If `fromElement` is not provided, the information from the manifest is used to determine whether the URL can
+            * be processed by the host. Deep link URLs for plugins are not supported and will result in an error.
             * @internal
             * Limited to Microsoft-internal use
+            * @param appId ID of the application the request is intended for. This must be a UUID
+            * @param url The URL to open
+            * @param fromElement The element on behalf of which the M365 app is making the request.
+            * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
             */
-        enum ActionOpenUrlErrorCode {
-                INTERNAL_ERROR = "INTERNAL_ERROR",
-                INVALID_LINK = "INVALID_LINK",
-                NOT_SUPPORTED = "NOT_SUPPORTED"
-        }
+        function processActionOpenUrl(appId: string, url: URL, fromElement?: {
+                name: 'composeExtensions' | 'plugins';
+        }): Promise<ActionOpenUrlType>;
         /**
             * @hidden
-            * The payload that is used when executing an Adaptive Card Action.Submit
-            * @internal
-            * Limited to Microsoft-internal use
-            */
-        interface IAdaptiveCardActionSubmit {
-                id: string;
-                data: string | Record<string, unknown>;
-        }
-        /**
+            * Checks if the externalAppCardActions capability is supported by the host
+            * @returns boolean to represent whether externalAppCardActions capability is supported
             *
-            * @hidden
-            * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
+            * @throws Error if {@linkcode app.initialize} has not successfully completed
             *
             * @internal
             * Limited to Microsoft-internal use
             */
-        interface ActionSubmitError {
-                errorCode: ExternalAppErrorCode;
-                message?: string;
-        }
+        function isSupported(): boolean;
+}
+
+/**
+    * @beta
+    * @hidden
+    * Namespace to delegate adaptive card action for Custom Engine Agent execution to the host
+    * @internal
+    * Limited to Microsoft-internal use
+    */
+export namespace externalAppCardActionsForCEA {
         /**
             * @beta
             * @hidden
-            * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
+            * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
             * @internal
             * Limited to Microsoft-internal use
             * @param appId ID of the application the request is intended for. This must be a UUID
-            * @param actionSubmitPayload The Adaptive Card Action.Submit payload
-            * @param cardActionsConfig The card actions configuration. This indicates which subtypes should be handled by this API
-            * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
+            * @param conversationId To tell the bot what conversation the calls are coming from
+            * @param url The URL to open
+            * @throws Error if the response has not successfully completed
+            * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
             */
-        function processActionSubmit(appId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
+        function processActionOpenUrl(appId: AppId, conversationId: string, url: URL): Promise<ActionOpenUrlType>;
         /**
             * @beta
             * @hidden
-            * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
-            * If `fromElement` is not provided, the information from the manifest is used to determine whether the URL can
-            * be processed by the host. Deep link URLs for plugins are not supported and will result in an error.
+            * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
             * @internal
             * Limited to Microsoft-internal use
             * @param appId ID of the application the request is intended for. This must be a UUID
-            * @param url The URL to open
-            * @param fromElement The element on behalf of which the M365 app is making the request.
-            * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
+            * @param conversationId To tell the bot what conversation the calls are coming from
+            * @param actionSubmitPayload The Adaptive Card Action.Submit payload
+            * @throws Error if host notifies of an error
+            * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
             */
-        function processActionOpenUrl(appId: string, url: URL, fromElement?: {
-                name: 'composeExtensions' | 'plugins';
-        }): Promise<ActionOpenUrlType>;
+        function processActionSubmit(appId: AppId, conversationId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
         /**
+            * @beta
             * @hidden
-            * Checks if the externalAppCardActions capability is supported by the host
+            * Checks if the externalAppCardActionsForCEA capability is supported by the host
             * @returns boolean to represent whether externalAppCardActions capability is supported
             *
             * @throws Error if {@linkcode app.initialize} has not successfully completed
@@ -5503,7 +5573,8 @@ export namespace app {
     * However, there are some older internal/hard-coded apps which violate this schema and use names like
     * com.microsoft.teamspace.tab.youtube. For compatibility with these legacy apps, we unfortunately cannot
     * securely and completely validate app ids as UUIDs. Based on this, the validation is limited to checking
-    * for script tags, length, and non-printable characters.
+    * for script tags, length, and non-printable characters. Validation will be updated in the future to ensure
+    * the app id is a valid UUID as legacy apps update.
     */
 export class AppId {
         /**
@@ -6276,8 +6347,9 @@ export namespace pages {
             *
             * @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
             */
-        function navigateToApp(params: NavigateToAppParams): Promise<void>;
+        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.
@@ -6301,7 +6373,10 @@ export namespace pages {
             */
         function isSupported(): boolean;
         /**
-            * Parameters for the NavigateToApp API
+            * @deprecated
+            * This interface has been deprecated in favor of a more type-safe interface using {@link pages.AppNavigationParameters}
+            *
+            * Parameters for the {@link pages.navigateToApp} function
             */
         interface NavigateToAppParams {
                 /**
@@ -6331,6 +6406,38 @@ export namespace pages {
                 */
                 chatId?: string;
         }
+        /**
+            * Type-safer version of parameters for the {@link pages.navigateToApp} function
+            */
+        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;
+        }
         /**
             * 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.
@@ -6642,6 +6749,9 @@ export namespace pages {
                 function isSupported(): boolean;
         }
 }
+export function isAppNavigationParametersObject(obj: pages.AppNavigationParameters | pages.NavigateToAppParams): obj is pages.AppNavigationParameters;
+export function convertNavigateToAppParamsToAppNavigationParameters(params: pages.NavigateToAppParams): pages.AppNavigationParameters;
+export function convertAppNavigationParametersToNavigateToAppParams(params: pages.AppNavigationParameters): pages.NavigateToAppParams;
 
 /** onComplete function type */
 export type onCompleteFunctionType = (status: boolean, reason?: string) => void;