@microsoft/agents-hosting-extensions-teams 0.5.1-g2e246ff274

package/src/messages/messages.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, ActivityTypes, Channels } from '@microsoft/agents-activity'
+import { AgentApplication, INVOKE_RESPONSE_KEY, InvokeResponse, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { TaskModuleResponse, TaskModuleTaskInfo } from '../taskModule'
+
+/**
+ * Enum representing the names of message invoke actions.
+ *
+ * This enum is used to define the specific invoke actions that can be triggered
+ * in the context of message handling.
+ */
+export enum MessageInvokeNames {
+  /**
+   * Represents the action to fetch a task associated with a message.
+   */
+  FETCH_INVOKE_NAME = 'message/fetchTask'
+}
+
+/**
+ * Handles message-related operations for Teams applications.
+ * Provides methods for handling message fetch operations.
+ * @template TState Type extending TurnState to be used by the application
+ */
+export class Messages<TState extends TurnState> {
+  private readonly _app: AgentApplication<TState>
+
+  /**
+   * Creates a new Messages instance.
+   * @param app The TeamsApplication instance to associate with this Messages instance
+   */
+  public constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Handles fetch requests for messages in Teams, which typically occur when
+   * a message action is invoked.
+   *
+   * @template TData Type of data expected in the message fetch request
+   * @param handler Function to handle the message fetch request
+   * @returns The TeamsApplication instance for chaining
+   */
+  public fetch<TData extends Record<string, any> = Record<string, any>>(
+    handler: (context: TurnContext, state: TState, data: TData) => Promise<TaskModuleTaskInfo | string>
+  ): AgentApplication<TState> {
+    this._app.addRoute(
+      async (context) => {
+        return (
+          context?.activity?.type === ActivityTypes.Invoke &&
+                    context?.activity?.name === MessageInvokeNames.FETCH_INVOKE_NAME
+        )
+      },
+      async (context, state) => {
+        if (context?.activity?.channelId === Channels.Msteams) {
+          const result = await handler(context, state, (context.activity.value as TData)?.data ?? {} as TData)
+
+          if (!context.turnState.get(INVOKE_RESPONSE_KEY)) {
+            let response: TaskModuleResponse
+            if (typeof result === 'string') {
+              response = {
+                task: {
+                  type: 'message',
+                  value: result
+                }
+              }
+            } else {
+              response = {
+                task: {
+                  type: 'continue',
+                  value: result
+                }
+              }
+            }
+
+            await context.sendActivity({
+              value: { body: response, status: 200 } as InvokeResponse,
+              type: ActivityTypes.InvokeResponse
+            } as Activity)
+          }
+        }
+      },
+      true
+    )
+
+    return this._app
+  }
+}

package/src/taskModule/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export * from './taskModuleContinueResponse'
+export * from './taskModuleMessageResponse'
+export * from './taskModuleRequest'
+export * from './taskModuleRequestContext'
+export * from './taskModuleResponse'
+export * from './taskModuleResponseBase'
+export * from './taskModuleTaskInfo'

package/src/taskModule/taskModule.ts

@@ -0,0 +1,241 @@
+import { Activity, ActivityTypes, Channels } from '@microsoft/agents-activity'
+import { AgentApplication, INVOKE_RESPONSE_KEY, InvokeResponse, RouteHandler, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { TaskModuleTaskInfo } from './taskModuleTaskInfo'
+import { TaskModuleResponse } from './taskModuleResponse'
+
+export enum TaskModuleInvokeNames {
+  CONFIG_FETCH_INVOKE_NAME = 'config/fetch',
+  CONFIG_SUBMIT_INVOKE_NAME = 'config/submit',
+  FETCH_INVOKE_NAME = 'task/fetch',
+  SUBMIT_INVOKE_NAME = 'task/submit',
+  DEFAULT_TASK_DATA_FILTER = 'verb'
+}
+
+interface TaskModuleOptions {
+  taskDataFilter?: string
+}
+
+/**
+ * Class that exposes Teams task module-related events.
+ * Provides an organized way to handle task module operations in Microsoft Teams.
+ */
+export class TaskModule<TState extends TurnState> {
+  _app: AgentApplication<TState>
+  _options: TaskModuleOptions
+
+  /**
+   * Creates a new instance of the TaskModule class.
+   * @param app - The agent application
+   */
+  constructor (app: AgentApplication<TState>, options?: TaskModuleOptions) {
+    this._options = options ?? { taskDataFilter: TaskModuleInvokeNames.DEFAULT_TASK_DATA_FILTER }
+    this._app = app
+  }
+
+  /**
+   * Handles task module fetch events. These occur when a task module is requested to be displayed.
+   * @param handler - The handler to call when a task module fetch event occurs
+   * @returns this (for method chaining)
+   */
+  onFetch (handler: RouteHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'task/fetch'
+      )
+    }
+    this._app.addRoute(routeSel, handler, true) // Invoke requires true
+    return this
+  }
+
+  /**
+     * Registers a handler to process the submission of a task module.
+     * @remarks
+     * Handlers should respond with another TaskInfo object, message string, or `null` to indicate
+     * the task is completed.
+     * @template TData Optional. Type of the data object being passed to the handler.
+     * @param {string | RegExp | RouteSelector | string[] | RegExp[] | RouteSelector[]} verb - Name of the verb(s) to register the handler for.
+     * @param {(context: TurnContext, state: TState, data: TData) => Promise<TaskModuleTaskInfo | string | null | undefined>} handler - Function to call when the handler is triggered.
+     * @param {TurnContext} handler.context - Context for the current turn of conversation with the user.
+     * @param {TState} handler.state - Current state of the turn.
+     * @param {TData} handler.data - Data object passed to the handler.
+     * @returns {Application<TState>} The application for chaining purposes.
+     */
+  public submit<TData extends Record<string, any> = Record<string, any>>(
+    verb: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
+    handler: (
+      context: TurnContext,
+      state: TState,
+      data: TData
+    ) => Promise<TaskModuleTaskInfo | string | null | undefined>
+  ): AgentApplication<TState> {
+    (Array.isArray(verb) ? verb : [verb]).forEach((v) => {
+      const { DEFAULT_TASK_DATA_FILTER, SUBMIT_INVOKE_NAME } = TaskModuleInvokeNames
+      const filterField = this._options.taskDataFilter ?? DEFAULT_TASK_DATA_FILTER
+      const selector = createTaskSelector(v, filterField, SUBMIT_INVOKE_NAME)
+      this._app.addRoute(
+        selector,
+        async (context, state) => {
+          if (context?.activity?.channelId === Channels.Msteams) {
+            if (context?.activity?.type !== ActivityTypes.Invoke || context?.activity?.name !== SUBMIT_INVOKE_NAME) {
+              throw new Error(`Unexpected TaskModules.submit() triggered for activity type: ${context?.activity?.type}`
+              )
+            }
+
+            const result = await handler(context, state, (context.activity.value as any).data ?? {})
+
+            if (!result) {
+              await context.sendActivity(Activity.fromObject({
+                value: { status: 200 } as InvokeResponse,
+                type: ActivityTypes.InvokeResponse
+              }))
+            }
+            if (!context.turnState.get(INVOKE_RESPONSE_KEY)) {
+              let response: TaskModuleResponse | undefined
+              if (typeof result === 'string') {
+                response = {
+                  task: {
+                    type: 'message',
+                    value: result
+                  }
+                }
+              } else if (typeof result === 'object') {
+                // Return card
+                response = {
+                  task: {
+                    type: 'continue',
+                    value: result as TaskModuleTaskInfo
+                  }
+                }
+              }
+
+              // Queue up invoke response
+              await context.sendActivity(Activity.fromObject({
+                value: { body: response, status: 200 } as InvokeResponse,
+                type: ActivityTypes.InvokeResponse
+              }))
+            }
+          }
+        },
+        true
+      )
+    })
+    return this._app
+  }
+
+  /**
+   * Handles specific task module fetch events based on a verb/action.
+   * @param verb - The verb or action identifier to match against in the task module data
+   * @param handler - The handler to call when a matching task module fetch event occurs
+   * @returns this (for method chaining)
+   */
+  onFetchByVerb (verb: string, handler: RouteHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'task/fetch' &&
+        // @ts-ignore
+        context.activity.value?.data === verb
+      )
+    }
+    this._app.addRoute(routeSel, handler, true)
+    return this
+  }
+
+  /**
+   * Handles specific task module submit events based on a verb/action.
+   * @param verb - The verb or action identifier to match against in the task module data
+   * @param handler - The handler to call when a matching task module submit event occurs
+   * @returns this (for method chaining)
+   */
+  onSubmitByVerb (verb: string, handler: RouteHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'task/submit' &&
+        // @ts-ignore
+        context.activity.value?.data === verb
+      )
+    }
+    this._app.addRoute(routeSel, handler, true)
+    return this
+  }
+
+  /**
+   * Handles configuration fetch events. These occur when an agent configuration is requested.
+   * @param handler - The handler to call when a configuration fetch event occurs
+   * @returns this (for method chaining)
+   */
+  onConfigurationFetch (handler: RouteHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'config/fetch'
+      )
+    }
+    this._app.addRoute(routeSel, handler, true)
+    return this
+  }
+
+  /**
+   * Handles configuration submit events. These occur when an agent configuration is submitted.
+   * @param handler - The handler to call when a configuration submit event occurs
+   * @returns this (for method chaining)
+   */
+  onConfigurationSubmit (handler: RouteHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'config/submit'
+      )
+    }
+    this._app.addRoute(routeSel, handler, true)
+    return this
+  }
+}
+
+/**
+ * Creates a route selector function for a given verb, filter field, and invoke name.
+ * @param {string | RegExp | RouteSelector} verb - The verb to match.
+ * @param {string} filterField - The field to use for filtering.
+ * @param {string} invokeName - The name of the invoke action.
+ * @returns {RouteSelector} The route selector function.
+ * @private
+ * @remarks
+ * This function is used to create a route selector function for a given verb, filter field, and invoke name.
+ * The route selector function is used to match incoming requests to the appropriate handler function.
+ */
+function createTaskSelector (
+  verb: string | RegExp | RouteSelector,
+  filterField: string,
+  invokeName: string
+): RouteSelector {
+  if (typeof verb === 'function') {
+    // Return the passed in selector function
+    return verb
+  } else if (verb instanceof RegExp) {
+    // Return a function that matches the verb using a RegExp
+    return (context: TurnContext) => {
+      const isTeams = context.activity.channelId === Channels.Msteams
+      const isInvoke = context?.activity?.type === ActivityTypes.Invoke && context?.activity?.name === invokeName
+      const data = (context?.activity?.value as any).data
+      if (isInvoke && isTeams && typeof data === 'object' && typeof data[filterField] === 'string') {
+        return Promise.resolve(verb.test(data[filterField]))
+      } else {
+        return Promise.resolve(false)
+      }
+    }
+  } else {
+    // Return a function that attempts to match verb
+    return (context: TurnContext) => {
+      const isInvoke = context?.activity?.type === ActivityTypes.Invoke && context?.activity?.name === invokeName
+      const data = (context?.activity?.value as any).data
+      return Promise.resolve(isInvoke && typeof data === 'object' && data[filterField] === verb)
+    }
+  }
+}

package/src/taskModule/taskModuleContinueResponse.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TaskModuleResponseBase } from './taskModuleResponseBase'
+import { TaskModuleTaskInfo } from './taskModuleTaskInfo'
+
+/**
+ * Interface representing the continue response of a task module.
+ */
+export interface TaskModuleContinueResponse extends TaskModuleResponseBase {
+  /**
+   * The task module task information.
+   */
+  value?: TaskModuleTaskInfo
+}

package/src/taskModule/taskModuleMessageResponse.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TaskModuleResponseBase } from './taskModuleResponseBase'
+
+/**
+ * Interface representing the message response of a task module.
+ */
+export interface TaskModuleMessageResponse extends TaskModuleResponseBase {
+  /**
+   * The value of the task module message response.
+   */
+  value?: string
+}

package/src/taskModule/taskModuleRequest.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TaskModuleRequestContext } from './taskModuleRequestContext'
+
+/**
+ * Interface representing the request of a task module.
+ */
+export interface TaskModuleRequest {
+  /**
+   * The data of the task module request.
+   */
+  data?: any
+  /**
+   * The context of the task module request.
+   */
+  context?: TaskModuleRequestContext
+  /**
+   * The tab context of the task module request.
+   */
+  tabContext?: any // TODO TabEntityContext
+}

package/src/taskModule/taskModuleRequestContext.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface representing the context of a task module request.
+ */
+export interface TaskModuleRequestContext {
+  /**
+   * The theme of the task module request.
+   */
+  theme?: string
+}

package/src/taskModule/taskModuleResponse.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TaskModuleContinueResponse } from './taskModuleContinueResponse'
+import { TaskModuleMessageResponse } from './taskModuleMessageResponse'
+
+/**
+ * Interface representing the response of a task module.
+ */
+export interface TaskModuleResponse {
+  /**
+   * The task module continue or message response.
+   */
+  task?: TaskModuleContinueResponse | TaskModuleMessageResponse
+  /**
+   * The cache information.
+   */
+  cacheInfo?: any // TODO CacheInfo
+}

package/src/taskModule/taskModuleResponseBase.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Type representing the message preview type.
+ */
+export type MessagePreviewType = 'message' | 'continue'
+
+/**
+ * Interface representing the base response of a task module.
+ */
+export interface TaskModuleResponseBase {
+  /**
+   * The type of the message preview.
+   */
+  type?: MessagePreviewType
+}

package/src/taskModule/taskModuleTaskInfo.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Attachment } from '@microsoft/agents-activity'
+
+/**
+ * Interface representing the task module task information.
+ */
+export interface TaskModuleTaskInfo {
+  /**
+   * The title of the task module.
+   */
+  title?: string
+  /**
+   * The height of the task module.
+   */
+  height?: number | 'small' | 'medium' | 'large'
+  /**
+   * The width of the task module.
+   */
+  width?: number | 'small' | 'medium' | 'large'
+  /**
+   * The URL of the task module.
+   */
+  url?: string
+  /**
+   * The card attachment of the task module.
+   */
+  card?: Attachment
+  /**
+   * The fallback URL of the task module.
+   */
+  fallbackUrl?: string
+  /**
+   * The completion agent ID of the task module.
+   */
+  completionAgentId?: string
+}