Added externalAppCardActionsForCEA APIs

apps/teams-test-app/src/components/privateApis/ExternalAppCardActionsAPIs.tsx

@@ -1,4 +1,4 @@
-import { externalAppCardActions } from '@microsoft/teams-js';
+import { externalAppCardActions, IAdaptiveCardActionSubmit } from '@microsoft/teams-js';
 import React from 'react';
 
 import { ApiWithoutInput, ApiWithTextInput } from '../utils';
@@ -15,7 +15,7 @@ const CheckExternalAppCardActionsCapability = (): React.ReactElement =>
 const ProcessActionSubmit = (): React.ReactElement =>
   ApiWithTextInput<{
     appId: string;
-    actionSubmitPayload: externalAppCardActions.IAdaptiveCardActionSubmit;
+    actionSubmitPayload: IAdaptiveCardActionSubmit;
   }>({
     name: 'processActionSubmit',
     title: 'Process Action Submit',

apps/teams-test-app/src/components/privateApis/ExternalAppCardActionsForCEAAPIs.tsx

@@ -0,0 +1,85 @@
+import { externalAppCardActions, IAdaptiveCardActionSubmit } from '@microsoft/teams-js';
+import React from 'react';
+
+import { ApiWithoutInput, ApiWithTextInput } from '../utils';
+import { ModuleWrapper } from '../utils/ModuleWrapper';
+
+const CheckExternalAppCardActionsForCEACapability = (): React.ReactElement =>
+  ApiWithoutInput({
+    name: 'checkExternalAppCardActionsForCEACapability',
+    title: 'Check External App Card Actions For CEA Capability',
+    onClick: async () =>
+      `External App Card Actions For CEA module ${externalAppCardActions.isSupported() ? 'is' : 'is not'} supported`,
+  });
+
+const CECProcessActionSubmit = (): React.ReactElement =>
+  ApiWithTextInput<{
+    appId: string;
+    actionSubmitPayload: IAdaptiveCardActionSubmit;
+  }>({
+    name: 'processActionSubmitForCEA',
+    title: 'Process Action Submit For CEA',
+    onClick: {
+      validateInput: (input) => {
+        if (!input.appId) {
+          throw new Error('appId is required');
+        }
+        if (!input.actionSubmitPayload) {
+          throw new Error('actionSubmitPayload is required');
+        }
+      },
+      submit: async (input) => {
+        await externalAppCardActions.processActionSubmit(input.appId, input.actionSubmitPayload);
+        return 'Completed';
+      },
+    },
+    defaultInput: JSON.stringify({
+      appId: 'b7f8c0a0-6c1d-4a9a-9c0a-2c3f1c0a3b0a',
+      actionSubmitPayload: {
+        id: 'submitId',
+        data: 'data1',
+      },
+    }),
+  });
+
+const CECProcessActionOpenUrl = (): React.ReactElement =>
+  ApiWithTextInput<{
+    appId: string;
+    url: string;
+    fromElement?: { name: 'composeExtensions' | 'plugins' };
+  }>({
+    name: 'processActionOpenUrlForCEA',
+    title: 'Process Action Open Url For CEA',
+    onClick: {
+      validateInput: (input) => {
+        if (!input.appId) {
+          throw new Error('appId is required');
+        }
+        if (!input.url) {
+          throw new Error('url is required');
+        }
+      },
+      submit: async (input) => {
+        const result = await externalAppCardActions.processActionOpenUrl(
+          input.appId,
+          new URL(input.url),
+          input.fromElement,
+        );
+        return JSON.stringify(result);
+      },
+    },
+    defaultInput: JSON.stringify({
+      appId: 'b7f8c0a0-6c1d-4a9a-9c0a-2c3f1c0a3b0a',
+      url: 'https://www.example.com',
+    }),
+  });
+
+const ExternalAppCardActionsForCEAAPIs = (): React.ReactElement => (
+  <ModuleWrapper title="External App Card Actions For CEA">
+    <CheckExternalAppCardActionsForCEACapability />
+    <CECProcessActionSubmit />
+    <CECProcessActionOpenUrl />
+  </ModuleWrapper>
+);
+
+export default ExternalAppCardActionsForCEAAPIs;

apps/teams-test-app/src/pages/TestApp.tsx

@@ -41,6 +41,7 @@ import ChatAPIs from '../components/privateApis/ChatAPIs';
 import CopilotAPIs from '../components/privateApis/CopilotAPIs';
 import ExternalAppAuthenticationAPIs from '../components/privateApis/ExternalAppAuthenticationAPIs';
 import ExternalAppCardActionsAPIs from '../components/privateApis/ExternalAppCardActionsAPIs';
+import ExternalAppCardActionsForCEAAPIs from '../components/privateApis/ExternalAppCardActionsForCEAAPIs';
 import ExternalAppCommandsAPIs from '../components/privateApis/ExternalAppCommandsAPIs';
 import FilesAPIs from '../components/privateApis/FilesAPIs';
 import FullTrustAPIs from '../components/privateApis/FullTrustAPIs';
@@ -114,6 +115,7 @@ export const TestApp: React.FC = () => {
         <DialogUrlParentCommunicationAPIs childWindowRef={dialogWindowRef} />
         <ExternalAppAuthenticationAPIs />
         <ExternalAppCardActionsAPIs />
+        <ExternalAppCardActionsForCEAAPIs />
         <ExternalAppCommandsAPIs />
         <FilesAPIs />
         <FullTrustAPIs />

change/@microsoft-teams-js-75e3c524-ba26-4b6a-b01b-9a1f0e315d91.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Added APIs for externalAppCardActionForCEA capability.",
+  "packageName": "@microsoft/teams-js",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/teams-js/src/internal/telemetry.ts

@@ -113,6 +113,8 @@ export const enum ApiName {
   ExternalAppAuthentication_AuthenticateWithPowerPlatformConnectorPlugins = 'externalAppAuthentication.authenticateWithPowerPlatformConnectorPlugins',
   ExternalAppCardActions_ProcessActionOpenUrl = 'externalAppCardActions.processActionOpenUrl',
   ExternalAppCardActions_ProcessActionSubmit = 'externalAppCardActions.processActionSubmit',
+  ExternalAppCardActionsForCEA_ProcessActionOpenUrl = 'externalAppCardActionsForCEA.processActionOpenUrl',
+  ExternalAppCardActionsForCEA_ProcessActionSubmit = 'externalAppCardActionsForCEA.processActionSubmit',
   ExternalAppCommands_ProcessActionCommands = 'externalAppCommands.processActionCommand',
   Files_AddCloudStorageFolder = 'files.addCloudStorageFolder',
   Files_AddCloudStorageProvider = 'files.addCloudStorageProvider',

packages/teams-js/src/private/externalAppCardActions.ts

@@ -4,7 +4,7 @@ import { ApiName, ApiVersionNumber, getApiVersionTag } from '../internal/telemet
 import { validateId } from '../internal/utils';
 import { errorNotSupportedOnPlatform, FrameContexts } from '../public/constants';
 import { runtime } from '../public/runtime';
-import { ExternalAppErrorCode } from './constants';
+import { ActionOpenUrlError, ActionSubmitError, IAdaptiveCardActionSubmit } from './interfaces';
 
 /**
  * v2 APIs telemetry file: All of APIs in this capability file should send out API version v2 ONLY
@@ -31,54 +31,6 @@ export namespace externalAppCardActions {
     GenericUrl = 'GenericUrl',
   }
 
-  /**
-   * @hidden
-   * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
-   *
-   * @internal
-   * Limited to Microsoft-internal use
-   */
-  export interface ActionOpenUrlError {
-    errorCode: ActionOpenUrlErrorCode;
-    message?: string;
-  }
-
-  /**
-   * @hidden
-   * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
-   * @internal
-   * Limited to Microsoft-internal use
-   */
-  export enum ActionOpenUrlErrorCode {
-    INTERNAL_ERROR = 'INTERNAL_ERROR', // Generic error
-    INVALID_LINK = 'INVALID_LINK', // Deep link is invalid
-    NOT_SUPPORTED = 'NOT_SUPPORTED', // Deep link is not supported
-  }
-
-  /**
-   * @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>;
-  }
-
-  /**
-   *
-   * @hidden
-   * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
-   *
-   * @internal
-   * Limited to Microsoft-internal use
-   */
-  export interface ActionSubmitError {
-    errorCode: ExternalAppErrorCode;
-    message?: string;
-  }
-
   /**
    * @beta
    * @hidden

packages/teams-js/src/private/externalAppCardActionsForCEA.ts

@@ -0,0 +1,99 @@
+import { sendMessageToParentAsync } from '../internal/communication';
+import { ensureInitialized } from '../internal/internalAPIs';
+import { ApiName, ApiVersionNumber, getApiVersionTag } from '../internal/telemetry';
+import { validateId } from '../internal/utils';
+import { errorNotSupportedOnPlatform, FrameContexts } from '../public/constants';
+import { runtime } from '../public/runtime';
+import { ActionOpenUrlError, ActionOpenUrlType, ActionSubmitError, IAdaptiveCardActionSubmit } from './interfaces';
+
+/**
+ * Updated to constants file: v2 APIs telemetry file: All of APIs in this capability file should send out API version v2 ONLY
+ */
+const externalAppCardActionsTelemetryVersionNumber: ApiVersionNumber = ApiVersionNumber.V_2;
+export namespace externalAppCardActionsForCEA {
+  /**
+   * @beta
+   * @hidden
+   * 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 conversationId To tell the bot what conversation the calls are coming from
+   * @param url The URL to open
+   * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
+   */
+  export function processActionOpenUrl(appId: string, conversationId: string, url: URL): Promise<ActionOpenUrlType> {
+    ensureInitialized(runtime, FrameContexts.content);
+
+    if (!isSupported()) {
+      throw errorNotSupportedOnPlatform;
+    }
+    validateId(appId, new Error('App id is not valid.'));
+    validateId(conversationId, new Error('conversation id is not valid.'));
+    return sendMessageToParentAsync<[ActionOpenUrlError, ActionOpenUrlType]>(
+      getApiVersionTag(
+        externalAppCardActionsTelemetryVersionNumber,
+        ApiName.ExternalAppCardActionsForCEA_ProcessActionOpenUrl,
+      ),
+      'externalAppCardActionsForCEA.processActionOpenUrl',
+      [appId, url.href, conversationId],
+    ).then(([error, response]: [ActionOpenUrlError, ActionOpenUrlType]) => {
+      if (error) {
+        throw error;
+      } else {
+        return response;
+      }
+    });
+  }
+
+  /**
+   * @beta
+   * @hidden
+   * 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 conversationId To tell the bot what conversation the calls are coming from
+   * @param actionSubmitPayload The Adaptive Card Action.Submit payload
+   * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
+   */
+  export function processActionSubmit(
+    appId: string,
+    conversationId: string,
+    actionSubmitPayload: IAdaptiveCardActionSubmit,
+  ): Promise<void> {
+    ensureInitialized(runtime, FrameContexts.content);
+
+    if (!isSupported()) {
+      throw errorNotSupportedOnPlatform;
+    }
+    validateId(appId, new Error('App id is not valid.'));
+    validateId(conversationId, new Error('conversation id is not valid.'));
+    return sendMessageToParentAsync<[boolean, ActionSubmitError]>(
+      getApiVersionTag(
+        externalAppCardActionsTelemetryVersionNumber,
+        ApiName.ExternalAppCardActionsForCEA_ProcessActionSubmit,
+      ),
+      'externalAppCardActionsForCEA.processActionSubmit',
+      [appId, conversationId, actionSubmitPayload],
+    ).then(([wasSuccessful, error]: [boolean, ActionSubmitError]) => {
+      if (!wasSuccessful) {
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * @hidden
+   * 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
+   *
+   * @internal
+   * Limited to Microsoft-internal use
+   */
+  export function isSupported(): boolean {
+    return ensureInitialized(runtime) && runtime.supports.externalAppCardActionsForCEA ? true : false;
+  }
+}

packages/teams-js/src/private/index.ts

@@ -22,6 +22,7 @@ export { conversations } from './conversations';
 export { copilot } from './copilot';
 export { externalAppAuthentication } from './externalAppAuthentication';
 export { externalAppCardActions } from './externalAppCardActions';
+export { externalAppCardActionsForCEA } from './externalAppCardActionsForCEA';
 export { externalAppCommands } from './externalAppCommands';
 export { files } from './files';
 export { meetingRoom } from './meetingRoom';

packages/teams-js/src/private/interfaces.ts

@@ -1,4 +1,5 @@
 import { FileOpenPreference, TeamInformation } from '../public/interfaces';
+import { ExternalAppErrorCode } from './constants';
 
 /**
  * @hidden
@@ -271,3 +272,60 @@ export interface UserJoinedTeamsInformation {
    */
   userJoinedTeams: TeamInformation[];
 }
+
+// externalAppCardActionsInterfaces.ts
+
+export enum ActionOpenUrlType {
+  DeepLinkDialog = 'DeepLinkDialog',
+  DeepLinkOther = 'DeepLinkOther',
+  DeepLinkStageView = 'DeepLinkStageView',
+  GenericUrl = 'GenericUrl',
+}
+
+/**
+ * @hidden
+ * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export interface ActionOpenUrlError {
+  errorCode: ActionOpenUrlErrorCode;
+  message?: string;
+}
+
+/**
+ * @hidden
+ * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export enum ActionOpenUrlErrorCode {
+  INTERNAL_ERROR = 'INTERNAL_ERROR', // Generic error
+  INVALID_LINK = 'INVALID_LINK', // Deep link is invalid
+  NOT_SUPPORTED = 'NOT_SUPPORTED', // Deep link is not supported
+}
+
+/**
+ * @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>;
+}
+
+/**
+ *
+ * @hidden
+ * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
+ *
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export interface ActionSubmitError {
+  errorCode: ExternalAppErrorCode;
+  message?: string;
+}

packages/teams-js/src/public/runtime.ts

@@ -243,6 +243,7 @@ interface IRuntimeV4 extends IBaseRuntime {
     };
     readonly externalAppAuthentication?: {};
     readonly externalAppCardActions?: {};
+    readonly externalAppCardActionsForCEA?: {};
     readonly externalAppCommands?: {};
     readonly geoLocation?: {
       readonly map?: {};

packages/teams-js/test/private/externalAppCardActions.spec.ts

@@ -2,6 +2,7 @@ import { errorLibraryNotInitialized } from '../../src/internal/constants';
 import { GlobalVars } from '../../src/internal/globalVars';
 import { ExternalAppErrorCode } from '../../src/private/constants';
 import { externalAppCardActions } from '../../src/private/externalAppCardActions';
+import { ActionOpenUrlErrorCode } from '../../src/private/interfaces';
 import { FrameContexts } from '../../src/public';
 import { app } from '../../src/public/app';
 import { errorNotSupportedOnPlatform } from '../../src/public/constants';
@@ -133,7 +134,7 @@ describe('externalAppCardActions', () => {
     const allowedFrameContexts = [FrameContexts.content];
     const testUrl = new URL('https://example.com');
     const testError = {
-      errorCode: externalAppCardActions.ActionOpenUrlErrorCode.INTERNAL_ERROR,
+      errorCode: ActionOpenUrlErrorCode.INTERNAL_ERROR,
       message: 'testMessage',
     };
     const testResponse = externalAppCardActions.ActionOpenUrlType.DeepLinkDialog;