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

package/src/messageExtension/messageExtension.ts

@@ -0,0 +1,324 @@
+import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+import { AgentApplication, RouteHandler, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { z } from 'zod'
+import { TaskModuleResponse } from '../taskModule'
+import { MessagingExtensionActionResponse } from './messagingExtensionActionResponse'
+import { MessagingExtensionQuery, messagingExtensionQueryZodSchema } from './messagingExtensionQuery'
+import { MessagingExtensionResponse } from './messagingExtensionResponse'
+import { MessagingExtensionResult } from './messagingExtensionResult'
+import { MessagingExtensionAction } from './messagingExtensionAction'
+
+export type RouteQueryHandler<TState extends TurnState> = (context: TurnContext, state: TState, query: MessagingExtensionQuery) => Promise<MessagingExtensionResult>
+export type SelectItemHandler<TState extends TurnState> = (context: TurnContext, state: TState, item: unknown) => Promise<MessagingExtensionResult>
+export type QueryLinkHandler<TState extends TurnState> = (context: TurnContext, state: TState, url: string) => Promise<MessagingExtensionResult>
+export type FetchTaskHanlder<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<TaskModuleResponse>
+export type SubmitActionHanlder<TState extends TurnState> = (context: TurnContext, state: TState, data: unknown) => Promise<MessagingExtensionActionResponse>
+export type MessagePreviewEditHandler<TState extends TurnState> = (context: TurnContext, state: TState, activity: Activity) => Promise<MessagingExtensionActionResponse>
+export type MessagePreviewSendHandler<TState extends TurnState> = (context: TurnContext, state: TState, activity: Activity) => Promise<void>
+export type ConfigureSettingsHandler<TState extends TurnState> = (context: TurnContext, state: TState, settings: unknown) => Promise<void>
+export type CardButtonClickedHandler<TState extends TurnState> = (context: TurnContext, state: TState, cardData: unknown) => Promise<void>
+/**
+ * Class that exposes Teams messaging extension-related events.
+ * Provides an organized way to handle messaging extension operations in Microsoft Teams.
+ */
+export class MessageExtension<TState extends TurnState> {
+  _app: AgentApplication<TState>
+
+  /**
+   * Creates a new instance of the MessageExtension class.
+   * @param app - The agent application
+   */
+  constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Handles queries from messaging extensions.
+   * @param handler - The handler to call when a query is received
+   * @returns this (for method chaining)
+   */
+  onQuery (handler: RouteQueryHandler<TState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/query'
+      )
+    }
+    const routeHandler : RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const messageExtensionQuery: MessagingExtensionQuery = messagingExtensionQueryZodSchema.parse(context.activity.value)
+      const parameters: Record<string, unknown> = {}
+      messageExtensionQuery.parameters?.forEach((param) => {
+        parameters[param.name!] = param.value
+      })
+      const result : MessagingExtensionResult = await handler(context, state, messageExtensionQuery)
+      const response: MessagingExtensionResponse = { composeExtension: result }
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200,
+        body: response
+      }
+      context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true) // Invoke requires true
+    return this
+  }
+
+  onSelectItem (handler: SelectItemHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/selectItem'
+      )
+    }
+    const routeHandler : RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const result : MessagingExtensionResult = await handler(context, state, context.activity.value)
+      const response: MessagingExtensionResponse = { composeExtension: result }
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200,
+        body: response
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true) // Invoke requires true
+    return this
+  }
+
+  /**
+   * Handles link queries from messaging extensions.
+   * @param handler - The handler to call when a link query is received
+   * @returns this (for method chaining)
+  */
+  onQueryLink (handler: QueryLinkHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+       context.activity.channelId === 'msteams' &&
+       context.activity.name === 'composeExtension/queryLink'
+      )
+    }
+    const routeHandler : RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const appBasedLinkQuerySchema = z.object({
+        url: z.string().url()
+      })
+      const query = appBasedLinkQuerySchema.parse(context.activity.value)
+      const res = await handler(context, state, query.url)
+      const response: MessagingExtensionResponse = { composeExtension: res }
+      const invokeResponse = Activity.fromObject({ type: ActivityTypes.InvokeResponse, value: { status: 200, body: response } })
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles anonymous link queries (for public access) from messaging extensions.
+   * @param handler - The handler to call when an anonymous link query is received
+   * @returns this (for method chaining)
+  */
+  onAnonymousQueryLink (handler: QueryLinkHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/anonymousQueryLink'
+      )
+    }
+    const routeHandler : RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const appBasedLinkQuerySchema = z.object({
+        url: z.string().url()
+      })
+      const query = appBasedLinkQuerySchema.parse(context.activity.value)
+      const res = await handler(context, state, query.url)
+      const response: MessagingExtensionResponse = { composeExtension: res }
+      const invokeResponse = Activity.fromObject({ type: ActivityTypes.InvokeResponse, value: { status: 200, body: response } })
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles fetch task requests from messaging extensions.
+   * @param handler - The handler to call when a fetch task is requested
+   * @returns this (for method chaining)
+  */
+  onFetchTask (handler: FetchTaskHanlder<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/fetchTask'
+      )
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const taskModuleResponse: TaskModuleResponse = await handler(context, state)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200,
+        body: taskModuleResponse
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles action submissions from messaging extensions.
+   * @param handler - The handler to call when an action is submitted
+   * @returns this (for method chaining)
+   */
+  onSubmitAction (handler: SubmitActionHanlder<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/submitAction' // && TODO
+        // (!context.activity.value || !('botMessagePreviewAction' in context.activity.value.))
+      )
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const data = context.activity.value
+      const response: MessagingExtensionActionResponse = await handler(context, state, data)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200,
+        body: response
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true) // Invoke requires true
+    return this
+  }
+
+  /**
+   * Handles message preview edit actions from messaging extensions.
+   * @param handler - The handler to call when a message preview edit action is received
+   * @returns this (for method chaining)
+   */
+  onMessagePreviewEdit (handler: MessagePreviewEditHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(!!(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/submitAction' &&
+        context.activity.value &&
+        // @ts-ignore
+        context.activity.value['botMessagePreviewAction'] === 'edit'))
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const activity = context.activity.value as Activity
+      const response: MessagingExtensionActionResponse = await handler(context, state, activity)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200,
+        body: response
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles message preview send actions from messaging extensions.
+   * @param handler - The handler to call when a message preview send action is received
+   * @returns this (for method chaining)
+   */
+  onMessagePreviewSend (handler: MessagePreviewSendHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(!!(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/submitAction' &&
+        context.activity.value &&
+        // @ts-ignore
+        context.activity.value['botMessagePreviewAction'] === 'send'))
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      const msgExtensionAction: MessagingExtensionAction = context.activity.value as MessagingExtensionAction
+      const activityPreview : Activity = msgExtensionAction.activityPreview?.length! > 0 ? Activity.fromObject(msgExtensionAction.activityPreview![0]) : new Activity(ActivityTypes.Message)
+      await handler(context, state, activityPreview)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles configuration query setting URL requests from messaging extensions.
+   * @param handler - The handler to call when a config query setting URL is requested
+   * @returns this (for method chaining)
+   */
+  onConfigurationQuerySettingUrl (handler: ConfigureSettingsHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/querySettingUrl'
+      )
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      await handler(context, state, context.activity.value)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles configuration setting updates from messaging extensions.
+   * @param handler - The handler to call when configuration settings are updated
+   * @returns this (for method chaining)
+   */
+  onConfigurationSetting (handler: ConfigureSettingsHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/setting'
+      )
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      await handler(context, state, context.activity.value)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+
+  /**
+   * Handles card button click events from messaging extensions.
+   * @param handler - The handler to call when a card button is clicked
+   * @returns this (for method chaining)
+   */
+  onCardButtonClicked (handler: CardButtonClickedHandler<TurnState>) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(
+        context.activity.type === ActivityTypes.Invoke &&
+        context.activity.channelId === 'msteams' &&
+        context.activity.name === 'composeExtension/onCardButtonClicked'
+      )
+    }
+    const routeHandler: RouteHandler<TurnState> = async (context: TurnContext, state: TurnState) => {
+      await handler(context, state, context.activity.value)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = {
+        status: 200
+      }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true)
+    return this
+  }
+}

package/src/messageExtension/messagingExtensionAction.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity } from '@microsoft/agents-activity'
+import { MessageActionsPayload } from '../message-actions-payload/messageActionsPayload'
+import { TaskModuleRequest } from '../taskModule'
+
+/**
+ * Contexts for messaging extension commands.
+ */
+export type CommandContext = 'message' | 'compose' | 'commandbox'
+
+/**
+ * Types of actions for message previews.
+ */
+export type MessagePreviewActionType = 'edit' | 'send'
+
+/**
+ * Represents an action for a messaging extension.
+ */
+export interface MessagingExtensionAction extends TaskModuleRequest {
+  /**
+   * The ID of the command.
+   */
+  commandId?: string
+  /**
+   * The context of the command.
+   */
+  commandContext?: CommandContext
+  /**
+   * The type of action for the agent message preview.
+   */
+  messagePreviewAction?: MessagePreviewActionType
+  /**
+   * A list of activities for the agent activity preview.
+   */
+  activityPreview?: Activity[]
+  /**
+   * The payload of the message actions.
+   */
+  messagePayload?: MessageActionsPayload
+}

package/src/messageExtension/messagingExtensionActionResponse.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TaskModuleContinueResponse, TaskModuleMessageResponse } from '../taskModule'
+import { MessagingExtensionResult } from './messagingExtensionResult'
+
+/**
+ * Represents the response of a messaging extension action.
+ */
+export interface MessagingExtensionActionResponse {
+  /**
+   * The task module response.
+   */
+  task?: TaskModuleContinueResponse | TaskModuleMessageResponse
+  /**
+   * The result of the compose extension.
+   */
+  composeExtension?: MessagingExtensionResult
+  /**
+   * Cache information for the response.
+   */
+  cacheInfo?: unknown // CacheInfo TODO: Define the type for CacheInfo
+}

package/src/messageExtension/messagingExtensionAttachment.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Attachment } from '@microsoft/agents-activity'
+
+/**
+ * Represents an attachment for a messaging extension.
+ */
+export interface MessagingExtensionAttachment extends Attachment {
+  /**
+   * A preview of the attachment.
+   */
+  preview?: Attachment
+}

package/src/messageExtension/messagingExtensionParameter.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Represents a parameter for a messaging extension query.
+ */
+export interface MessagingExtensionParameter {
+  /**
+   * The name of the parameter.
+   */
+  name?: string
+  /**
+   * The value of the parameter.
+   */
+  value?: any
+}
+
+/**
+ * Zod schema for validating MessagingExtensionParameter.
+ */
+export const messagingExtensionParameterZodSchema = z.object({
+  name: z.string().min(1).optional(),
+  value: z.any().optional()
+})

package/src/messageExtension/messagingExtensionQuery.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+import { MessagingExtensionParameter, messagingExtensionParameterZodSchema } from './messagingExtensionParameter'
+import { MessagingExtensionQueryOptions, messagingExtensionQueryOptionsZodSchema } from './messagingExtensionQueryOptions'
+
+/**
+ * Represents a query for a messaging extension.
+ */
+export interface MessagingExtensionQuery {
+  /**
+   * The ID of the command.
+   */
+  commandId?: string
+  /**
+   * A list of parameters for the query.
+   */
+  parameters?: MessagingExtensionParameter[]
+  /**
+   * Options for the query.
+   */
+  queryOptions?: MessagingExtensionQueryOptions
+  /**
+   * The state of the query.
+   */
+  state?: string
+}
+
+/**
+ * Zod schema for validating MessagingExtensionQuery.
+ */
+export const messagingExtensionQueryZodSchema = z.object({
+  commandId: z.string().min(1).optional(),
+  parameters: z.array(messagingExtensionParameterZodSchema).optional(),
+  queryOptions: messagingExtensionQueryOptionsZodSchema.optional(),
+  state: z.string().min(1).optional()
+})
+
+/**
+ * Parses the given value as a messaging extension query.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {MessagingExtensionQuery} - The parsed messaging extension query.
+ */
+export function parseValueMessagingExtensionQuery (value: unknown): MessagingExtensionQuery {
+  messagingExtensionQueryZodSchema.passthrough().parse(value)
+  return value as MessagingExtensionQuery
+}

package/src/messageExtension/messagingExtensionQueryOptions.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Represents query options for a messaging extension.
+ */
+export interface MessagingExtensionQueryOptions {
+  /**
+   * The number of items to skip.
+   */
+  skip?: number
+  /**
+   * The number of items to retrieve.
+   */
+  count?: number
+}
+
+/**
+ * Zod schema for validating MessagingExtensionQueryOptions.
+ */
+export const messagingExtensionQueryOptionsZodSchema = z.object({
+  skip: z.number().optional(),
+  count: z.number().optional()
+})

package/src/messageExtension/messagingExtensionResponse.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// import { CacheInfo } from '../agent-config/cacheInfo'
+import { MessagingExtensionResult } from './messagingExtensionResult'
+
+/**
+ * Represents the response of a messaging extension.
+ */
+export interface MessagingExtensionResponse {
+  /**
+   * The result of the compose extension.
+   */
+  composeExtension?: MessagingExtensionResult
+  /**
+   * Cache information for the response.
+   */
+  cacheInfo?: unknown // TODO: CacheInfo
+}

package/src/messageExtension/messagingExtensionResult.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity } from '@microsoft/agents-activity'
+import { MessagingExtensionAttachment } from './messagingExtensionAttachment'
+import { MessagingExtensionSuggestedAction } from './messagingExtensionSuggestedAction'
+
+/**
+ * Layout options for attachments.
+ */
+export type AttachmentLayout = 'list' | 'grid'
+
+/**
+ * Types of messaging extension results.
+ * - `result`: Represents a standard result.
+ * - `auth`: Represents an authentication request.
+ * - `config`: Represents a configuration request.
+ * - `message`: Represents a message result.
+ * - `botMessagePreview`: Represents a bot message preview.
+ * - `silentAuth`: Represents a silent authentication request.
+ */
+export type MessagingExtensionResultType =
+    | 'result'
+    | 'auth'
+    | 'config'
+    | 'message'
+    | 'botMessagePreview'
+    | 'silentAuth'
+
+/**
+ * Represents the result of a messaging extension.
+ */
+export interface MessagingExtensionResult {
+  /**
+   * The layout of the attachments.
+   */
+  attachmentLayout?: AttachmentLayout
+  /**
+   * The type of the result.
+   */
+  type?: MessagingExtensionResultType
+  /**
+   * A list of attachments.
+   */
+  attachments?: MessagingExtensionAttachment[]
+  /**
+   * Suggested actions for the result.
+   */
+  suggestedActions?: MessagingExtensionSuggestedAction
+  /**
+   * Text content of the result.
+   */
+  text?: string
+  /**
+   * Preview of the activity.
+   */
+  activityPreview?: Activity
+}

package/src/messageExtension/messagingExtensionSuggestedAction.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CardAction } from '@microsoft/agents-activity'
+
+/**
+ * Represents suggested actions for a messaging extension.
+ */
+export interface MessagingExtensionSuggestedAction {
+  /**
+   * A list of card actions.
+   */
+  actions?: CardAction[]
+}