@microsoft/agents-hosting-extensions-msteams 1.7.2

package/src/errorHelper.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { AgentErrorDefinition } from '@microsoft/agents-activity'
+
+/**
+ * Error definitions for the Teams Extensions system.
+ * This contains localized error codes for the Teams Extensions subsystem of the AgentSDK.
+ *
+ * Each error definition includes an error code (starting from -150000), a description, and a help link
+ * pointing to an AKA link to get help for the given error.
+ *
+ * Usage example:
+ * ```
+ * throw ExceptionHelper.generateException(
+ *   Error,
+ *   Errors.TeamsApiClientNotAvailable
+ * );
+ * ```
+ */
+export const Errors: { [key: string]: AgentErrorDefinition } = {
+  // Teams Graph Errors (-150012 to -150015, -150017 to -150019)
+  /**
+   * Error thrown when a Graph authorization handler returns an empty token.
+   */
+  TeamsGraphTokenUnavailable: {
+    code: -150012,
+    description: 'Unable to acquire a Graph access token using authorization handler {handlerName}.'
+  },
+
+  /**
+   * Error thrown when no Graph authorization handlers are configured.
+   */
+  TeamsGraphAuthorizationHandlerRequired: {
+    code: -150013,
+    description: 'A Graph client requires at least one configured authorization handler.'
+  },
+
+  /**
+   * Error thrown when multiple Graph authorization handlers are configured and no handler name is provided.
+   */
+  TeamsGraphAuthorizationHandlerNameRequired: {
+    code: -150014,
+    description: 'A Graph client requires handlerName when multiple authorization handlers are configured.'
+  },
+
+  /**
+   * Error thrown when a required Graph client parameter is missing.
+   */
+  TeamsGraphParameterRequired: {
+    code: -150015,
+    description: 'The {parameterName} parameter is required to create a Graph client.'
+  },
+
+  /**
+   * Error thrown when the Graph base URL is invalid.
+   */
+  TeamsGraphInvalidBaseUrl: {
+    code: -150017,
+    description: 'The graphBaseUrl parameter must be a valid absolute URL.'
+  },
+
+  /**
+   * Error thrown when user authorization is unavailable from the current turn.
+   */
+  TeamsGraphUserAuthorizationNotConfigured: {
+    code: -150018,
+    description: 'User authorization is not configured on the AgentApplication. A delegated Graph client requires configured user authorization.'
+  },
+
+  /**
+   * Error thrown when token connections are unavailable.
+   */
+  TeamsGraphConnectionsNotConfigured: {
+    code: -150019,
+    description: 'Connections are not configured on the AgentApplication. An app-only Graph client requires a configured token connection.'
+  },
+
+  // TaskModule Errors (-150016)
+  /**
+   * Error thrown when unexpected TaskModules.submit() is triggered.
+   */
+  UnexpectedTaskModuleSubmit: {
+    code: -150016,
+    description: 'Unexpected TaskModules.submit() triggered for activity type: {activityType}'
+  },
+
+  // TeamsApiClient Errors (-150010 to -150011)
+  /**
+   * Error thrown when the Teams SDK client is not available in the context.
+   */
+  TeamsApiClientNotAvailable: {
+    code: -150010,
+    description: 'Teams API client is not available in the context. Add TeamsAgentExtension to populate it before use.'
+  },
+
+  /**
+   * Error thrown when Teams API client prerequisites are missing for Teams activities.
+   */
+  TeamsApiClientSetupFailed: {
+    code: -150011,
+    description: 'Teams API client setup failed: missing {missing}.'
+  }
+}

package/src/fileConsents/fileConsent.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+import { AgentApplication, RouteHandler, RouteRank, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import type { FileConsentCardResponse } from '@microsoft/teams.api'
+import { TeamsTurnContext } from '../teamsTurnContext'
+
+type FileConsentHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, response: FileConsentCardResponse) => Promise<void>
+
+function isFileConsentAction (context: TurnContext, action: 'accept' | 'decline'): boolean {
+  const activityAction = (context.activity.value as any)?.action
+  return (
+    context.activity.type === ActivityTypes.Invoke &&
+    context.activity.channelId === 'msteams' &&
+    typeof context.activity.name === 'string' &&
+    context.activity.name.toLowerCase() === 'fileconsent/invoke' &&
+    typeof activityAction === 'string' &&
+    activityAction.toLowerCase() === action
+  )
+}
+
+/**
+ * Registers handlers for Microsoft Teams file consent card actions.
+ *
+ * @typeParam TState - The turn state type used by the agent application.
+ */
+export class FileConsent<TState extends TurnState = TurnState> {
+  private _app: AgentApplication<TState>
+
+  /**
+   * Creates a Teams file consent route helper.
+   *
+   * @param app - The agent application that receives the registered routes.
+   */
+  constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Registers a handler for accepted file consent cards.
+   *
+   * @param handler - Handler invoked with the file consent card response.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This file consent helper for chaining.
+   */
+  onAccept (handler: FileConsentHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isFileConsentAction(context, 'accept'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const cardResponse = context.activity.value as FileConsentCardResponse
+      await handler(new TeamsTurnContext(context), state, cardResponse)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = { status: 200 }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for declined file consent cards.
+   *
+   * @param handler - Handler invoked with the file consent card response.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This file consent helper for chaining.
+   */
+  onDecline (handler: FileConsentHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isFileConsentAction(context, 'decline'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const cardResponse = context.activity.value as FileConsentCardResponse
+      await handler(new TeamsTurnContext(context), state, cardResponse)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = { status: 200 }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true, rank, authHandlers)
+    return this
+  }
+}

package/src/fileConsents/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './fileConsent'

package/src/graphClientFactory.ts

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { type AuthProvider, type Authorization, type TurnContext } from '@microsoft/agents-hosting'
+import { Client as GraphClient, type AuthenticationProvider, type ClientOptions } from '@microsoft/microsoft-graph-client'
+import { Errors } from './errorHelper'
+
+const DEFAULT_GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0'
+
+class UserTokenProvider implements AuthenticationProvider {
+  constructor (
+    private readonly authorization: Authorization,
+    private readonly context: TurnContext,
+    private readonly handlerName?: string
+  ) {}
+
+  async getAccessToken (): Promise<string> {
+    const handlerName = this.handlerName ?? this.getDefaultHandlerName()
+    const { token } = await this.authorization.getToken(this.context, handlerName)
+
+    if (!token?.trim()) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphTokenUnavailable, undefined, { handlerName })
+    }
+
+    return token
+  }
+
+  private getDefaultHandlerName (): string {
+    const authorization = this.authorization as unknown as {
+      manager?: { handlers?: Array<{ id: string }> }
+    }
+    const handlerIds = authorization.manager?.handlers?.map((handler) => handler.id) ?? []
+
+    if (handlerIds.length === 1) {
+      return handlerIds[0]
+    }
+
+    if (handlerIds.length === 0) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphAuthorizationHandlerRequired)
+    }
+
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphAuthorizationHandlerNameRequired)
+  }
+}
+
+class AppTokenProvider implements AuthenticationProvider {
+  constructor (
+    private readonly tokenProvider: AuthProvider,
+    private readonly scope: string
+  ) {}
+
+  async getAccessToken (): Promise<string> {
+    return await this.tokenProvider.getAccessToken(this.scope)
+  }
+}
+
+/**
+ * Creates a Microsoft Graph client authenticated with a delegated user token.
+ */
+export function createUserGraphClient (
+  authorization: Authorization,
+  context: TurnContext,
+  handlerName?: string,
+  graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL
+): GraphClient {
+  if (!authorization) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'authorization' })
+  }
+  if (!context) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'context' })
+  }
+  if (!graphBaseUrl) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'graphBaseUrl' })
+  }
+
+  let graphUrl: URL
+  try {
+    graphUrl = new URL(graphBaseUrl)
+  } catch {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphInvalidBaseUrl)
+  }
+
+  return GraphClient.initWithMiddleware(createGraphClientOptions(
+    new UserTokenProvider(authorization, context, handlerName),
+    graphBaseUrl,
+    graphUrl
+  ))
+}
+
+/**
+ * Creates a Microsoft Graph client authenticated with an app-only token.
+ */
+export function createAppGraphClient (
+  tokenProvider: AuthProvider,
+  graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL
+): GraphClient {
+  if (!tokenProvider) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'tokenProvider' })
+  }
+  if (!graphBaseUrl) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'graphBaseUrl' })
+  }
+
+  let graphUrl: URL
+  try {
+    graphUrl = new URL(graphBaseUrl)
+  } catch {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsGraphInvalidBaseUrl)
+  }
+  const scope = `${graphUrl.origin}/.default`
+
+  return GraphClient.initWithMiddleware(createGraphClientOptions(
+    new AppTokenProvider(tokenProvider, scope),
+    graphBaseUrl,
+    graphUrl
+  ))
+}
+
+function createGraphClientOptions (authProvider: AuthenticationProvider, graphBaseUrl: string, graphUrl: URL): ClientOptions {
+  return {
+    authProvider,
+    baseUrl: graphBaseUrl,
+    defaultVersion: '',
+    customHosts: new Set([graphUrl.hostname])
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './activity-extensions'
+export * from './app'
+export * from './channels'
+export * from './config'
+export { Errors as TeamsExtensionErrors } from './errorHelper'
+export * from './fileConsents'
+export * from './meetings'
+export * from './meetings/meeting'
+export * from './messageExtensions'
+export * from './messages'
+export * from './models'
+export * from './taskModules'
+export * from './teams'
+export type { TeamsActivity } from './teamsActivity'
+export * from './teamsActivityExtensions'
+export * from './teamsAgentExtension'
+export * from './teamsModelExtensions'
+export * from './teamsTurnContext'
+export { type TeamsRouteHandler } from './teamsRouteHandler'
+export * from './teamsProactiveServiceEndpoints'

package/src/meetings/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './meeting'

package/src/meetings/meeting.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ActivityTypes } from '@microsoft/agents-activity'
+import { AgentApplication, RouteHandler, RouteRank, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import type { MeetingDetails, TeamsChannelAccount } from '@microsoft/teams.api'
+import { TeamsTurnContext } from '../teamsTurnContext'
+
+/**
+ * Details provided by Teams meeting participant join and leave events.
+ */
+export interface MeetingParticipantsEventDetails {
+  /**
+   * Participants included in the meeting event.
+   */
+  members: {
+    /**
+     * The Teams user account for the participant.
+     */
+    user: TeamsChannelAccount
+    /**
+     * Meeting-specific participant state.
+     */
+    meeting: {
+      /**
+       * Indicates whether the participant is currently in the meeting.
+       */
+      inMeeting: boolean
+      /**
+       * Participant role in the meeting.
+       */
+      role: string
+    }
+  }[]
+}
+
+type MeetingStartHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, details: MeetingDetails) => Promise<void>
+type MeetingEndHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, details: MeetingDetails) => Promise<void>
+type MeetingParticipantsHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, details: MeetingParticipantsEventDetails) => Promise<void>
+
+function isMeetingEvent (context: TurnContext, eventName: string): boolean {
+  return (
+    context.activity.type === ActivityTypes.Event &&
+    context.activity.channelId === 'msteams' &&
+    typeof context.activity.name === 'string' &&
+    context.activity.name.toLowerCase() === eventName.toLowerCase()
+  )
+}
+
+/**
+ * Registers handlers for Microsoft Teams meeting events.
+ *
+ * @typeParam TState - The turn state type used by the agent application.
+ */
+export class Meeting<TState extends TurnState> {
+  private _app: AgentApplication<TState>
+
+  /**
+   * Creates a Teams meeting route helper.
+   *
+   * @param app - The agent application that receives the registered routes.
+   */
+  constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Registers a handler for Teams meeting start events.
+   *
+   * @param handler - Handler invoked with meeting details.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This meeting helper for chaining.
+   */
+  onStart (handler: MeetingStartHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isMeetingEvent(context, 'application/vnd.microsoft.meetingStart'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const details = context.activity.value as MeetingDetails
+      await handler(new TeamsTurnContext(context), state, details)
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams meeting end events.
+   *
+   * @param handler - Handler invoked with meeting details.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This meeting helper for chaining.
+   */
+  onEnd (handler: MeetingEndHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isMeetingEvent(context, 'application/vnd.microsoft.meetingEnd'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const details = context.activity.value as MeetingDetails
+      await handler(new TeamsTurnContext(context), state, details)
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams meeting participant join events.
+   *
+   * @param handler - Handler invoked with participant event details.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This meeting helper for chaining.
+   */
+  onParticipantsJoin (handler: MeetingParticipantsHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isMeetingEvent(context, 'application/vnd.microsoft.meetingParticipantJoin'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const details = context.activity.value as MeetingParticipantsEventDetails
+      await handler(new TeamsTurnContext(context), state, details)
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams meeting participant leave events.
+   *
+   * @param handler - Handler invoked with participant event details.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This meeting helper for chaining.
+   */
+  onParticipantsLeave (handler: MeetingParticipantsHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isMeetingEvent(context, 'application/vnd.microsoft.meetingParticipantLeave'))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const details = context.activity.value as MeetingParticipantsEventDetails
+      await handler(new TeamsTurnContext(context), state, details)
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+}

package/src/messageExtensions/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export { messagingExtensionQueryZodSchema, parseValueMessagingExtensionQuery } from './messagingExtensionQuery'
+export * from './messageExtension'