CEC Card API changes

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

@@ -0,0 +1,85 @@
+import { externalAppCardActions } from '@microsoft/teams-js';
+import React from 'react';
+
+import { ApiWithoutInput, ApiWithTextInput } from '../utils';
+import { ModuleWrapper } from '../utils/ModuleWrapper';
+
+const CheckExternalAppCardActionsCapability = (): React.ReactElement =>
+  ApiWithoutInput({
+    name: 'checkExternalAppCardActionsCapability',
+    title: 'Check External App Card Actions Capability',
+    onClick: async () =>
+      `External App Card Actions module ${externalAppCardActions.isSupported() ? 'is' : 'is not'} supported`,
+  });
+
+const ProcessActionSubmit = (): React.ReactElement =>
+  ApiWithTextInput<{
+    appId: string;
+    actionSubmitPayload: externalAppCardActions.IAdaptiveCardActionSubmit;
+  }>({
+    name: 'processActionSubmit',
+    title: 'Process Action Submit',
+    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 ProcessActionOpenUrl = (): React.ReactElement =>
+  ApiWithTextInput<{
+    appId: string;
+    url: string;
+    fromElement?: { name: 'composeExtensions' | 'plugins' };
+  }>({
+    name: 'processActionOpenUrl',
+    title: 'Process Action Open Url',
+    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 ExternalAppCardActionsForCECAPIs = (): React.ReactElement => (
+  <ModuleWrapper title="External App Card Actions">
+    <CheckExternalAppCardActionsCapability />
+    <ProcessActionSubmit />
+    <ProcessActionOpenUrl />
+  </ModuleWrapper>
+);
+
+export default ExternalAppCardActionsForCECAPIs;

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

@@ -39,6 +39,7 @@ import PeopleAPIs from '../components/PeopleAPIs';
 import ChatAPIs from '../components/privateApis/ChatAPIs';
 import ExternalAppAuthenticationAPIs from '../components/privateApis/ExternalAppAuthenticationAPIs';
 import ExternalAppCardActionsAPIs from '../components/privateApis/ExternalAppCardActionsAPIs';
+import ExternalAppCardActionsForCECAPIs from '../components/privateApis/ExternalAppCardActionsForCECAPIs';
 import ExternalAppCommandsAPIs from '../components/privateApis/ExternalAppCommandsAPIs';
 import FilesAPIs from '../components/privateApis/FilesAPIs';
 import FullTrustAPIs from '../components/privateApis/FullTrustAPIs';
@@ -90,6 +91,7 @@ export const TestApp: React.FC = () => {
         <DialogUrlParentCommunicationAPIs childWindowRef={dialogWindowRef} />
         <ExternalAppAuthenticationAPIs />
         <ExternalAppCardActionsAPIs />
+        <ExternalAppCardActionsForCECAPIs />
         <ExternalAppCommandsAPIs />
         <FilesAPIs />
         <FullTrustAPIs />

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',
+  ExternalAppCardActionsForCEC_ProcessActionOpenUrl = 'externalAppCardActions.cec.processActionOpenUrl',
+  ExternalAppCardActionsForCEC_ProcessActionSubmit = 'externalAppCardActions.cec.processActionSubmit',
   ExternalAppCommands_ProcessActionCommands = 'externalAppCommands.processActionCommand',
   Files_AddCloudStorageFolder = 'files.addCloudStorageFolder',
   Files_AddCloudStorageProvider = 'files.addCloudStorageProvider',

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

@@ -0,0 +1,85 @@
+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 { externalAppCardActions } from './externalAppCardActions';
+
+/**
+ * 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 externalAppCardActionsForCEC {
+  export function processActionOpenUrl(
+    appId: string,
+    conversationId: string,
+    url: URL,
+  ): Promise<externalAppCardActions.ActionOpenUrlType> {
+    ensureInitialized(runtime, FrameContexts.content);
+
+    if (!isSupported()) {
+      throw errorNotSupportedOnPlatform;
+    }
+    validateId(appId, new Error('App id is not valid.'));
+    return sendMessageToParentAsync<
+      [externalAppCardActions.ActionOpenUrlError, externalAppCardActions.ActionOpenUrlType]
+    >(
+      getApiVersionTag(
+        externalAppCardActionsTelemetryVersionNumber,
+        ApiName.ExternalAppCardActions_ProcessActionOpenUrl,
+      ),
+      'externalAppCardActions.cec.processActionOpenUrl',
+      [appId, url.href, conversationId],
+    ).then(
+      ([error, response]: [externalAppCardActions.ActionOpenUrlError, externalAppCardActions.ActionOpenUrlType]) => {
+        if (error) {
+          throw error;
+        } else {
+          return response;
+        }
+      },
+    );
+  }
+
+  export function processActionSubmit(
+    appId: string,
+    conversationId: string,
+    actionSubmitPayload: externalAppCardActions.IAdaptiveCardActionSubmit, // alternatively, we can move IAdaptiveCardActionSubmit to interface
+  ): Promise<void> {
+    ensureInitialized(runtime, FrameContexts.content);
+
+    if (!isSupported()) {
+      throw errorNotSupportedOnPlatform;
+    }
+    validateId(appId, new Error('App id is not valid.'));
+
+    return sendMessageToParentAsync<[boolean, externalAppCardActions.ActionSubmitError]>(
+      getApiVersionTag(
+        externalAppCardActionsTelemetryVersionNumber,
+        ApiName.ExternalAppCardActions_ProcessActionSubmit,
+      ),
+      'externalAppCardActions.cec.processActionSubmit',
+      [appId, conversationId, actionSubmitPayload],
+    ).then(([wasSuccessful, error]: [boolean, externalAppCardActions.ActionSubmitError]) => {
+      if (!wasSuccessful) {
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * @hidden
+   * Checks if the externalAppCardActions 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.externalAppCardActionsForCEC ? true : false;
+  }
+}

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

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

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

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