@microsoft/agents-hosting 0.4.3 → 0.5.4-ga4d0401645

package/src/app/adaptiveCards/activityValueParsers.ts

@@ -0,0 +1,249 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+import { activityZodSchema, AdaptiveCardInvokeAction, adaptiveCardInvokeActionZodSchema } from '@microsoft/agents-activity'
+// import { MessagingExtensionQuery, messagingExtensionQueryZodSchema } from '../messageExtension/messagingExtensionQuery'
+import { adaptiveCardsSearchParamsZodSchema } from './adaptiveCardsSearchParams'
+
+/**
+ * Parses the given value as a value action.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {string} - The parsed value action.
+ */
+export function parseValueAction (value: unknown): string {
+  const valueActionZodSchema = z.object({
+    action: z.string().min(1)
+  })
+  valueActionZodSchema.passthrough().parse(value)
+  return value as string
+}
+
+/**
+ * Parses the given value as a value action name.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {string} - The parsed value action name.
+ */
+export function parseValueActionName (value: unknown): string {
+  const valueActionNameZodSchema = z.object({
+    actionName: z.string().min(1),
+  })
+  valueActionNameZodSchema.passthrough().parse(value)
+  return value as string
+}
+
+/**
+ * Parses the given value as a value continuation.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {string} - The parsed value continuation.
+ */
+export function parseValueContinuation (value: unknown): string {
+  const valueContinuationZodSchema = z.object({
+    continuation: z.string().min(1)
+  })
+  valueContinuationZodSchema.passthrough().parse(value)
+  return value as string
+}
+
+export interface ValueAction {
+  action: {
+    type: string;
+    verb: string;
+  }
+}
+
+/**
+ * Parses the given value as a value action execute selector.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed value action execute selector.
+ */
+export function parseValueActionExecuteSelector (value: unknown): ValueAction | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+  const actionZodSchema = z.object({
+    type: z.string().min(1),
+    verb: z.string().min(1)
+  })
+  const actionValueExecuteSelector = z.object({
+    action: actionZodSchema
+  })
+  const safeParsedValue = actionValueExecuteSelector.passthrough().safeParse(value)
+  if (!safeParsedValue.success) {
+    throw new Error(`Invalid action value: ${safeParsedValue.error}`)
+  }
+  const parsedValue = safeParsedValue.data
+  return {
+    action: {
+      type: parsedValue.action.type,
+      verb: parsedValue.action.verb
+    }
+  }
+}
+
+/**
+ * Parses the given value as a dataset.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed dataset.
+ */
+export function parseValueDataset (value: unknown): {
+  dataset: string;
+} | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+  const datasetZodSchema = z.object({
+    dataset: z.string().min(1)
+  })
+  const parsedValue = datasetZodSchema.passthrough().parse(value)
+  return {
+    dataset: parsedValue.dataset
+  }
+}
+
+/**
+ * Parses the given value as action feedback loop data.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed action feedback loop data.
+ */
+export function parseValueActionFeedbackLoopData (value: unknown): {
+  actionValue: {
+    reaction: 'like' | 'dislike';
+    feedback: string | Record<string, any>;
+  }
+} {
+  const feedbackLoopDataActionValueZodSchema = z.object({
+    actionValue: z.object({
+      reaction: z.union([z.literal('like'), z.literal('dislike')]),
+      feedback: z.union([z.string().min(1), z.record(z.string(), z.any())])
+    })
+  })
+  const parsedValue = feedbackLoopDataActionValueZodSchema.passthrough().parse(value)
+  return {
+    actionValue: {
+      reaction: parsedValue.actionValue.reaction,
+      feedback: parsedValue.actionValue.feedback
+    }
+  }
+}
+
+/**
+ * Parses the given value as an adaptive card invoke action.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {AdaptiveCardInvokeAction} - The parsed adaptive card invoke action.
+ */
+export function parseAdaptiveCardInvokeAction (value: unknown): AdaptiveCardInvokeAction {
+  adaptiveCardInvokeActionZodSchema.passthrough().parse(value)
+  return value as AdaptiveCardInvokeAction
+}
+
+/**
+ * Parses the given value as a search query.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed search query.
+ */
+export function parseValueSearchQuery (value: unknown): {
+  queryOptions: {
+    top: number;
+    skip: number;
+  };
+  queryText: string;
+  dataset: string;
+} {
+  const queryOptionsZodSchema = z.object({
+    top: z.number(),
+    skip: z.number(),
+  })
+  const searchValueZodSchema = adaptiveCardsSearchParamsZodSchema.extend({
+    queryOptions: queryOptionsZodSchema
+  })
+  const validSearchValue = searchValueZodSchema.passthrough().parse(value)
+  return {
+    queryOptions: {
+      top: validSearchValue.queryOptions.top,
+      skip: validSearchValue.queryOptions.skip
+    },
+    queryText: validSearchValue.queryText,
+    dataset: validSearchValue.dataset
+  }
+}
+
+/**
+ * Parses the given value as a query.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed query.
+ */
+export function parseValueQuery (value: unknown): {
+  url: string;
+} {
+  const urlZodSchema = z.object({
+    url: z.string().min(1)
+  })
+  const parsedValue = urlZodSchema.passthrough().parse(value)
+  return {
+    url: parsedValue.url
+  }
+}
+
+/**
+ * Parses the given value as an activity message preview action.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed message preview action.
+ */
+export function parseValueAgentMessagePreviewAction (value: unknown): {
+  botMessagePreviewAction: string;
+} {
+  const botMessagePreviewActionZodSchema = z.object({
+    botMessagePreviewAction: z.string().min(1)
+  })
+  const parsedValue = botMessagePreviewActionZodSchema.passthrough().parse(value)
+  return {
+    botMessagePreviewAction: parsedValue.botMessagePreviewAction
+  }
+}
+
+/**
+ * Parses the given value as an activity preview.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed activity preview.
+ */
+export function parseValueAgentActivityPreview (value: unknown): object {
+  const botActivityPreviewZodSchema = z.object({
+    botActivityPreview: z.array(activityZodSchema.partial())
+  })
+  const parsedValue = botActivityPreviewZodSchema.passthrough().parse(value)
+  return {
+    botActivityPreview: parsedValue.botActivityPreview
+  }
+}
+
+/**
+ * Parses the given value as a command ID.
+ *
+ * @param {unknown} value - The value to parse.
+ * @returns {object} - The parsed command ID.
+ */
+export function parseValueCommandId (value: unknown): {
+  commandId: string;
+} {
+  const commandIdZodSchema = z.object({
+    commandId: z.string().min(1)
+  })
+  const parsedValue = commandIdZodSchema.passthrough().parse(value)
+  return {
+    commandId: parsedValue.commandId
+  }
+}

package/src/app/adaptiveCards/adaptiveCardActionExecuteResponseType.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Defines the types of responses that can be returned after executing an Adaptive Card action.
+ */
+export enum AdaptiveCardActionExecuteResponseType {
+  /**
+   * Replaces the Adaptive Card only for the user who interacted with it.
+   */
+  REPLACE_FOR_INTERACTOR,
+
+  /**
+   * Replaces the Adaptive Card for all users.
+   */
+  REPLACE_FOR_ALL,
+
+  /**
+   * Sends a new message containing an Adaptive Card to all users.
+   */
+  NEW_MESSAGE_FOR_ALL
+}

package/src/app/adaptiveCards/adaptiveCardsActions.ts

@@ -0,0 +1,320 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+import { AdaptiveCardInvokeResponse, AgentApplication, CardFactory, INVOKE_RESPONSE_KEY, InvokeResponse, MessageFactory, RouteSelector, TurnContext, TurnState } from '../../'
+import { AdaptiveCardActionExecuteResponseType } from './adaptiveCardActionExecuteResponseType'
+import { parseAdaptiveCardInvokeAction, parseValueActionExecuteSelector, parseValueDataset, parseValueSearchQuery } from './activityValueParsers'
+import { AdaptiveCardsSearchParams } from './adaptiveCardsSearchParams'
+import { AdaptiveCard } from '../../cards/adaptiveCard'
+import { Query } from './query'
+
+export const ACTION_INVOKE_NAME = 'adaptiveCard/action'
+const ACTION_EXECUTE_TYPE = 'Action.Execute'
+const DEFAULT_ACTION_SUBMIT_FILTER = 'verb'
+const SEARCH_INVOKE_NAME = 'application/search'
+
+enum AdaptiveCardInvokeResponseType {
+  /**
+   * Indicates a response containing an Adaptive Card.
+   */
+  ADAPTIVE = 'application/vnd.microsoft.card.adaptive',
+
+  /**
+   * Indicates a response containing a message activity.
+   */
+  MESSAGE = 'application/vnd.microsoft.activity.message',
+
+  /**
+   * Indicates a response containing a search result.
+   */
+  SEARCH = 'application/vnd.microsoft.search.searchResponse'
+}
+
+export interface AdaptiveCardSearchResult {
+  /**
+   * The title of the search result.
+   */
+  title: string;
+
+  /**
+   * The value associated with the search result.
+   */
+  value: string;
+}
+
+/**
+ * A class to handle Adaptive Card actions such as executing actions, submitting actions, and performing searches.
+ * @template TState - The type of the TurnState used in the application.
+ */
+export class AdaptiveCardsActions<TState extends TurnState> {
+  /**
+   * The Teams application instance associated with this class.
+   */
+  private readonly _app: AgentApplication<TState>
+
+  /**
+   * Constructs an instance of AdaptiveCardsActions.
+   * @param app - The Teams application instance.
+   */
+  public constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Registers a handler for the Action.Execute event.
+   * @template TData - The type of the data passed to the handler.
+   * @param verb - A string, RegExp, RouteSelector, or an array of these to match the action verb.
+   * @param handler - A function to handle the action execution.
+   * @returns The Teams application instance.
+   */
+  public actionExecute<TData = Record<string, any>>(
+    verb: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
+    handler: (context: TurnContext, state: TState, data: TData) => Promise<AdaptiveCard | string>
+  ): AgentApplication<TState> {
+    let actionExecuteResponseType = this._app.options.adaptiveCardsOptions?.actionExecuteResponseType ?? AdaptiveCardActionExecuteResponseType.REPLACE_FOR_INTERACTOR;
+    (Array.isArray(verb) ? verb : [verb]).forEach((v) => {
+      const selector = createActionExecuteSelector(v)
+      this._app.addRoute(
+        selector,
+        async (context, state) => {
+          const a = context?.activity
+          const invokeAction = parseValueActionExecuteSelector(a.value)
+          if (
+            a?.type !== ActivityTypes.Invoke ||
+                        a?.name !== ACTION_INVOKE_NAME ||
+                        (invokeAction?.action.type !== ACTION_EXECUTE_TYPE)
+          ) {
+            throw new Error(`Unexpected AdaptiveCards.actionExecute() triggered for activity type: ${invokeAction?.action.type}`
+            )
+          }
+
+          if (invokeAction.action.verb !== v) {
+            // TODO: add logger to this class
+            console.log(`AdaptiveCards.actionExecute() triggered for verb: ${invokeAction.action.verb} does not match expected verb: ${v}`)
+          }
+
+          // TODO: review any, and check verb
+          const result = await handler(context, state, ((a.value as any).action as TData) ?? {} as TData)
+          if (!context.turnState.get(INVOKE_RESPONSE_KEY)) {
+            let response: AdaptiveCardInvokeResponse
+            if (typeof result === 'string') {
+              response = {
+                statusCode: 200,
+                type: AdaptiveCardInvokeResponseType.MESSAGE,
+                value: result as any
+              }
+              await sendInvokeResponse(context, response)
+            } else {
+              if (
+                result.refresh &&
+                                actionExecuteResponseType !== AdaptiveCardActionExecuteResponseType.NEW_MESSAGE_FOR_ALL
+              ) {
+                actionExecuteResponseType = AdaptiveCardActionExecuteResponseType.REPLACE_FOR_ALL
+              }
+
+              const activity = MessageFactory.attachment(CardFactory.adaptiveCard(result))
+              response = {
+                statusCode: 200,
+                type: AdaptiveCardInvokeResponseType.ADAPTIVE,
+                value: result
+              }
+              if (
+                actionExecuteResponseType === AdaptiveCardActionExecuteResponseType.NEW_MESSAGE_FOR_ALL
+              ) {
+                await sendInvokeResponse(context, {
+                  statusCode: 200,
+                  type: AdaptiveCardInvokeResponseType.MESSAGE,
+                  value: 'Your response was sent to the app' as any
+                })
+                await context.sendActivity(activity)
+              } else if (
+                actionExecuteResponseType === AdaptiveCardActionExecuteResponseType.REPLACE_FOR_ALL
+              ) {
+                activity.id = context.activity.replyToId
+                await context.updateActivity(activity)
+                await sendInvokeResponse(context, response)
+              } else {
+                await sendInvokeResponse(context, response)
+              }
+            }
+          }
+        },
+        true
+      )
+    })
+    return this._app
+  }
+
+  /**
+   * Registers a handler for the Action.Submit event.
+   * @template TData - The type of the data passed to the handler.
+   * @param verb - A string, RegExp, RouteSelector, or an array of these to match the action verb.
+   * @param handler - A function to handle the action submission.
+   * @returns The Teams application instance.
+   */
+  public actionSubmit<TData = Record<string, any>>(
+    verb: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
+    handler: (context: TurnContext, state: TState, data: TData) => Promise<void>
+  ): AgentApplication<TState> {
+    const filter = this._app.options.adaptiveCardsOptions?.actionSubmitFilter ?? DEFAULT_ACTION_SUBMIT_FILTER;
+    (Array.isArray(verb) ? verb : [verb]).forEach((v) => {
+      const selector = createActionSubmitSelector(v, filter)
+      this._app.addRoute(selector, async (context, state) => {
+        const a = context?.activity
+        if (a?.type !== ActivityTypes.Message || a?.text || typeof a?.value !== 'object') {
+          throw new Error(`Unexpected AdaptiveCards.actionSubmit() triggered for activity type: ${a?.type}`)
+        }
+
+        await handler(context, state as TState, (parseAdaptiveCardInvokeAction(a.value)) as TData ?? {} as TData)
+      })
+    })
+    return this._app
+  }
+
+  /**
+   * Registers a handler for the search event.
+   * @param dataset - A string, RegExp, RouteSelector, or an array of these to match the dataset.
+   * @param handler - A function to handle the search query.
+   * @returns The Teams application instance.
+   */
+  public search (
+    dataset: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
+    handler: (
+      context: TurnContext,
+      state: TState,
+      query: Query<AdaptiveCardsSearchParams>
+    ) => Promise<AdaptiveCardSearchResult[]>
+  ): AgentApplication<TState> {
+    (Array.isArray(dataset) ? dataset : [dataset]).forEach((ds) => {
+      const selector = createSearchSelector(ds)
+      this._app.addRoute(
+        selector,
+        async (context, state) => {
+          const a = context?.activity
+          if (a?.type !== 'invoke' || a?.name !== SEARCH_INVOKE_NAME) {
+            throw new Error(`Unexpected AdaptiveCards.search() triggered for activity type: ${a?.type}`)
+          }
+
+          const parsedQuery = parseValueSearchQuery(a.value)
+          const query: Query<AdaptiveCardsSearchParams> = {
+            count: parsedQuery.queryOptions?.top ?? 25,
+            skip: parsedQuery.queryOptions?.skip ?? 0,
+
+            parameters: {
+              queryText: parsedQuery.queryText ?? '',
+              dataset: parsedQuery.dataset ?? ''
+
+            }
+          }
+
+          const results = await handler(context, state, query)
+          if (!context.turnState.get(INVOKE_RESPONSE_KEY)) {
+            const response = {
+              type: AdaptiveCardInvokeResponseType.SEARCH,
+              value: {
+                results
+              }
+            }
+
+            await context.sendActivity({
+              value: { body: response, status: 200 } as InvokeResponse,
+              type: ActivityTypes.InvokeResponse
+            } as Activity)
+          }
+        },
+        true
+      )
+    })
+    return this._app
+  }
+}
+
+function createActionExecuteSelector (verb: string | RegExp | RouteSelector): RouteSelector {
+  if (typeof verb === 'function') {
+    return verb
+  } else if (verb instanceof RegExp) {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      const valueAction = parseValueActionExecuteSelector(a.value)
+      const isInvoke =
+                a?.type === ActivityTypes.Invoke &&
+                a?.name === ACTION_INVOKE_NAME &&
+                valueAction?.action?.type === ACTION_EXECUTE_TYPE
+      if (isInvoke && typeof valueAction.action.verb === 'string') {
+        return Promise.resolve(verb.test(valueAction.action.verb))
+      } else {
+        return Promise.resolve(false)
+      }
+    }
+  } else {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      const valueAction = parseValueActionExecuteSelector(a.value)
+      const isInvoke =
+                a?.type === ActivityTypes.Invoke &&
+                a?.name === ACTION_INVOKE_NAME &&
+                valueAction?.action?.type === ACTION_EXECUTE_TYPE
+      if (isInvoke && valueAction.action?.verb === verb) {
+        return Promise.resolve(true)
+      } else {
+        return Promise.resolve(false)
+      }
+    }
+  }
+}
+
+function createActionSubmitSelector (verb: string | RegExp | RouteSelector, filter: string): RouteSelector {
+  if (typeof verb === 'function') {
+    return verb
+  } else if (verb instanceof RegExp) {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      const isSubmit = a?.type === ActivityTypes.Message && !a?.text && typeof a?.value === 'object'
+      if (isSubmit && typeof (a?.value as any)[filter] === 'string') {
+        return Promise.resolve(verb.test((a.value as any)[filter]))
+      } else {
+        return Promise.resolve(false)
+      }
+    }
+  } else {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      const isSubmit = a?.type === ActivityTypes.Message && !a?.text && typeof a?.value === 'object'
+      return Promise.resolve(isSubmit && (a?.value as any)[filter] === verb)
+    }
+  }
+}
+
+function createSearchSelector (dataset: string | RegExp | RouteSelector): RouteSelector {
+  if (typeof dataset === 'function') {
+    return dataset
+  } else if (dataset instanceof RegExp) {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      const valueDataset = parseValueDataset(a.value)
+      const isSearch = a?.type === ActivityTypes.Invoke && a?.name === SEARCH_INVOKE_NAME
+      if (isSearch && typeof valueDataset?.dataset === 'string') {
+        return Promise.resolve(dataset.test(valueDataset?.dataset))
+      } else {
+        return Promise.resolve(false)
+      }
+    }
+  } else {
+    return (context: TurnContext) => {
+      const a = context?.activity
+      // const valueDataset = parseAdaptiveCardInvokeAction(a.value)
+      const isSearch = a?.type === ActivityTypes.Invoke && a?.name === SEARCH_INVOKE_NAME
+      return Promise.resolve(isSearch)
+    }
+  }
+}
+
+async function sendInvokeResponse (context: TurnContext, response: AdaptiveCardInvokeResponse) {
+  await context.sendActivity({
+    value: { body: response, status: 200 } as InvokeResponse,
+    type: ActivityTypes.InvokeResponse
+  } as Activity)
+}

package/src/app/adaptiveCards/adaptiveCardsOptions.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AdaptiveCardActionExecuteResponseType } from './adaptiveCardActionExecuteResponseType'
+
+/**
+ * Configuration options for Adaptive Cards.
+ */
+export interface AdaptiveCardsOptions {
+  /**
+   * Specifies the filter key used for Action.Submit events.
+   * If not provided, a default filter key will be used.
+   */
+  actionSubmitFilter?: string;
+
+  /**
+   * Specifies the response type for Action.Execute events.
+   * Determines how the response is handled after an action is executed.
+   */
+  actionExecuteResponseType?: AdaptiveCardActionExecuteResponseType;
+}

package/src/app/adaptiveCards/adaptiveCardsSearchParams.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Interface representing the search parameters for adaptive cards.
+ */
+export interface AdaptiveCardsSearchParams {
+  /**
+   * The text query for the search.
+   */
+  queryText: string;
+  /**
+   * The dataset to search within.
+   */
+  dataset: string;
+}
+
+/**
+ * Zod schema for validating AdaptiveCardsSearchParams.
+ */
+export const adaptiveCardsSearchParamsZodSchema = z.object({
+  queryText: z.string(),
+  dataset: z.string(),
+})

package/src/app/adaptiveCards/index.ts

@@ -0,0 +1,3 @@
+export * from './adaptiveCardsActions'
+export * from './adaptiveCardsOptions'
+export * from './adaptiveCardActionExecuteResponseType'

package/src/app/adaptiveCards/query.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents a query with pagination and parameters.
+ * @template TParams - The type of the query parameters.
+ */
+export interface Query<TParams extends Record<string, any>> {
+  /**
+   * The number of items to retrieve.
+   */
+  count: number;
+
+  /**
+   * The number of items to skip.
+   */
+  skip: number;
+
+  /**
+   * The parameters for the query.
+   */
+  parameters: TParams;
+}