@microsoft/agents-hosting-extensions-teams 1.1.4-geb1c05c291 → 1.2.0-alpha.19.g21cf68366a

package/src/errorHelper.ts

@@ -0,0 +1,177 @@
+// 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.ContextRequired
+ * );
+ * ```
+ */
+export const Errors: { [key: string]: AgentErrorDefinition } = {
+  // TeamsInfo Errors (-150000 to -150025)
+  /**
+   * Error thrown when context is required but not provided.
+   */
+  ContextRequired: {
+    code: -150000,
+    description: 'context is required.'
+  },
+
+  /**
+   * Error thrown when meetingId is required but not provided.
+   */
+  MeetingIdRequired: {
+    code: -150001,
+    description: 'meetingId is required.'
+  },
+
+  /**
+   * Error thrown when participantId is required but not provided.
+   */
+  ParticipantIdRequired: {
+    code: -150002,
+    description: 'participantId is required.'
+  },
+
+  /**
+   * Error thrown when teamId is required but not provided.
+   */
+  TeamIdRequired: {
+    code: -150003,
+    description: 'teamId is required.'
+  },
+
+  /**
+   * Error thrown when TurnContext cannot be null.
+   */
+  TurnContextCannotBeNull: {
+    code: -150004,
+    description: 'TurnContext cannot be null'
+  },
+
+  /**
+   * Error thrown when Activity cannot be null.
+   */
+  ActivityCannotBeNull: {
+    code: -150005,
+    description: 'Activity cannot be null'
+  },
+
+  /**
+   * Error thrown when teamsChannelId cannot be null or empty.
+   */
+  TeamsChannelIdRequired: {
+    code: -150006,
+    description: 'The teamsChannelId cannot be null or empty'
+  },
+
+  /**
+   * Error thrown when activity is required but not provided.
+   */
+  ActivityRequired: {
+    code: -150007,
+    description: 'activity is required.'
+  },
+
+  /**
+   * Error thrown when tenantId is required but not provided.
+   */
+  TenantIdRequired: {
+    code: -150008,
+    description: 'tenantId is required.'
+  },
+
+  /**
+   * Error thrown when members list is required but not provided.
+   */
+  MembersListRequired: {
+    code: -150009,
+    description: 'members list is required.'
+  },
+
+  /**
+   * Error thrown when operationId is required but not provided.
+   */
+  OperationIdRequired: {
+    code: -150010,
+    description: 'operationId is required.'
+  },
+
+  // TeamsConnectorClient Errors (-150011 to -150014)
+  /**
+   * Error thrown when activity parameter is missing.
+   */
+  MissingActivityParameter: {
+    code: -150011,
+    description: 'Missing activity parameter'
+  },
+
+  /**
+   * Error thrown when method is only valid within MS Teams Team scope.
+   */
+  OnlyValidInTeamsScope: {
+    code: -150012,
+    description: 'This method is only valid within the scope of a MS Teams Team.'
+  },
+
+  /**
+   * Error thrown when userId is required but not provided.
+   */
+  UserIdRequired: {
+    code: -150013,
+    description: 'userId is required'
+  },
+
+  /**
+   * Error thrown when conversationId is required but not provided.
+   */
+  ConversationIdRequired: {
+    code: -150014,
+    description: 'conversationId is required'
+  },
+
+  /**
+   * Error thrown when client is not available in the context.
+   */
+  ClientNotAvailable: {
+    code: -150015,
+    description: 'Client is not available in the context.'
+  },
+
+  // TaskModule Errors (-150016)
+  /**
+   * Error thrown when unexpected TaskModules.submit() is triggered.
+   */
+  UnexpectedTaskModuleSubmit: {
+    code: -150016,
+    description: 'Unexpected TaskModules.submit() triggered for activity type: {activityType}'
+  },
+
+  // TeamsActivityHandler Errors (-150017 to -150018)
+  /**
+   * Error thrown when method is not implemented.
+   */
+  NotImplemented: {
+    code: -150017,
+    description: 'NotImplemented'
+  },
+
+  /**
+   * Error thrown for bad request.
+   */
+  BadRequest: {
+    code: -150018,
+    description: 'BadRequest'
+  }
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './activity-extensions'
 export * from './client'
 export * from './compat/teamsActivityHandler'
+export { Errors as TeamsExtensionErrors } from './errorHelper'
 export * from './feedbackLoopData'
 export * from './meeting'
 export * from './meeting/meeting'

package/src/taskModule/taskModule.ts

@@ -1,5 +1,6 @@
-import { Activity, ActivityTypes, Channels } from '@microsoft/agents-activity'
+import { Activity, ActivityTypes, Channels, ExceptionHelper } from '@microsoft/agents-activity'
 import { AgentApplication, INVOKE_RESPONSE_KEY, InvokeResponse, RouteHandler, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { Errors } from '../errorHelper'
 import { TaskModuleTaskInfo } from './taskModuleTaskInfo'
 import { TaskModuleResponse } from './taskModuleResponse'
 
@@ -79,10 +80,8 @@ export class TaskModule<TState extends TurnState> {
         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}`
-              )
+              throw ExceptionHelper.generateException(Error, Errors.UnexpectedTaskModuleSubmit, undefined, { activityType: context?.activity?.type })
             }
-
             const result = await handler(context, state, (context.activity.value as any).data ?? {})
 
             if (!result) {

package/src/teamsAttachmentDownloader.ts

@@ -3,90 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { Attachment } from '@microsoft/agents-activity'
-import { ConnectorClient, InputFile, InputFileDownloader, TurnContext, TurnState } from '@microsoft/agents-hosting'
-import axios, { AxiosInstance } from 'axios'
-import { z } from 'zod'
+import { TeamsAttachmentDownloader as AppTeamsAttachmentDownloader } from '@microsoft/agents-hosting'
+
 /**
+ * @deprecated Use {@link TeamsAttachmentDownloader} from @microsoft/agents-hosting instead.
  * Downloads attachments from Teams using the bots access token.
  */
-export class TeamsAttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
-  private _httpClient: AxiosInstance
-  private _stateKey: string
-  public constructor (stateKey: string = 'inputFiles') {
-    this._httpClient = axios.create()
-    this._stateKey = stateKey
-  }
-
-  /**
-     * Download any files relative to the current user's input.
-     * @template TState - Type of the state object passed to the `TurnContext.turnState` method.
-     * @param {TurnContext} context Context for the current turn of conversation.
-     * @param {TState} state Application state for the current turn of conversation.
-     * @returns {Promise<InputFile[]>} Promise that resolves to an array of downloaded input files.
-     */
-  public async downloadFiles (context: TurnContext): Promise<InputFile[]> {
-    // Filter out HTML attachments
-    const attachments = context.activity.attachments?.filter((a) => !a.contentType.startsWith('text/html'))
-    if (!attachments || attachments.length === 0) {
-      return Promise.resolve([])
-    }
-
-    const connectorClient : ConnectorClient = context.turnState.get<ConnectorClient>('connectorClient')
-    this._httpClient.defaults.headers = connectorClient.axiosInstance.defaults.headers
-
-    const files: InputFile[] = []
-    for (const attachment of attachments) {
-      const file = await this.downloadFile(attachment)
-      if (file) {
-        files.push(file)
-      }
-    }
-
-    return files
-  }
-
-  /**
-     * @private
-     * @param {Attachment} attachment - Attachment to download.
-     * @param {string} accessToken - Access token to use for downloading.
-     * @returns {Promise<InputFile>} - Promise that resolves to the downloaded input file.
-     */
-  private async downloadFile (attachment: Attachment): Promise<InputFile | undefined> {
-    let inputFile: InputFile | undefined
-    if (attachment.contentType === 'application/vnd.microsoft.teams.file.download.info') {
-      const contentSchema = z.object({ downloadUrl: z.string() })
-      const contentValue = contentSchema.parse(attachment.content)
-      const response = await this._httpClient.get(contentValue.downloadUrl, { responseType: 'arraybuffer' })
-      const content = Buffer.from(response.data, 'binary')
-      let contentType = attachment.contentType
-      if (contentType === 'image/*') {
-        contentType = 'image/png'
-      }
-      inputFile = { content, contentType, contentUrl: attachment.contentUrl }
-    } else if (attachment.contentType === 'image/*') {
-      const response = await this._httpClient.get(attachment.contentUrl!, { responseType: 'arraybuffer' })
-      const content = Buffer.from(response.data, 'binary')
-      inputFile = { content, contentType: attachment.contentType, contentUrl: attachment.contentUrl }
-    } else {
-      inputFile = {
-        content: Buffer.from(attachment.content as ArrayBuffer),
-        contentType: attachment.contentType,
-        contentUrl: attachment.contentUrl
-      }
-    }
-    return inputFile
-  }
-
-  /**
-   * Downloads files from the attachments in the current turn context and stores them in state.
-   *
-   * @param context The turn context containing the activity with attachments.
-   * @param state The turn state to store the files in.
-   * @returns A promise that resolves when the downloaded files are stored.
-   */
-  public async downloadAndStoreFiles (context: TurnContext, state: TState): Promise<void> {
-    const files = await this.downloadFiles(context)
-    state.setValue(this._stateKey, files)
-  }
+export class TeamsAttachmentDownloader extends AppTeamsAttachmentDownloader {
 }

package/src/teamsInfo.ts

@@ -3,12 +3,13 @@
  * Licensed under the MIT License.
  */
 
+import { Activity, Channels, ConversationParameters, ConversationReference, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
 import { TeamsChannelAccount } from './activity-extensions/teamsChannelAccount'
 import { TeamsMeetingParticipant } from './meeting/teamsMeetingParticipant'
 import { MeetingInfo } from './meeting/meetingInfo'
 import { MeetingNotification } from './meeting/meetingNotification'
 import { MeetingNotificationResponse } from './meeting/meetingNotificationResponse'
-import { Activity, Channels, ConversationReference, ConversationParameters } from '@microsoft/agents-activity'
 import { TeamsConnectorClient } from './client/teamsConnectorClient'
 import { parseTeamsChannelData } from './activity-extensions/teamsChannelDataParser'
 import { CloudAdapter, ConnectorClient, TurnContext, TurnState } from '@microsoft/agents-hosting'
@@ -37,7 +38,7 @@ export class TeamsInfo {
     tenantId?: string
   ): Promise<TeamsMeetingParticipant<TurnState>> {
     if (!context) {
-      throw new Error('context is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ContextRequired)
     }
 
     const activity = context.activity
@@ -48,7 +49,7 @@ export class TeamsInfo {
     }
 
     if (!meetingId) {
-      throw new Error('meetingId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.MeetingIdRequired)
     }
 
     if (participantId == null) {
@@ -57,7 +58,7 @@ export class TeamsInfo {
     }
 
     if (!participantId) {
-      throw new Error('participantId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ParticipantIdRequired)
     }
 
     if (tenantId === undefined) {
@@ -99,7 +100,7 @@ export class TeamsInfo {
       teamId = teamsChannelData.team?.id
     }
     if (!teamId) {
-      throw new Error('teamId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TeamIdRequired)
     }
     const res = await this.getRestClient(context).fetchTeamDetails(teamId!)
     return res as TeamDetails
@@ -116,15 +117,15 @@ export class TeamsInfo {
    */
   static async sendMessageToTeamsChannel (context: TurnContext, activity: Activity, teamsChannelId: string, appId?: string): Promise<[ConversationReference, string]> {
     if (!context) {
-      throw new Error('TurnContext cannot be null')
+      throw ExceptionHelper.generateException(Error, Errors.TurnContextCannotBeNull)
     }
 
     if (!activity) {
-      throw new Error('Activity cannot be null')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityCannotBeNull)
     }
 
     if (!teamsChannelId) {
-      throw new Error('The teamsChannelId cannot be null or empty')
+      throw ExceptionHelper.generateException(Error, Errors.TeamsChannelIdRequired)
     }
     const convoParams = {
       isGroup: true,
@@ -179,7 +180,7 @@ export class TeamsInfo {
       teamId = teamsChannelData.team?.id
     }
     if (!teamId) {
-      throw new Error('teamId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TeamIdRequired)
     }
     return await this.getRestClient(context).fetchChannelList(teamId!)
   }
@@ -237,7 +238,7 @@ export class TeamsInfo {
       teamId = teamsChannelData.team?.id
     }
     if (!teamId) {
-      throw new Error('teamId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TeamIdRequired)
     }
     const pagedResults = await this.getRestClient(context).getConversationPagedMember(teamId, pageSize!, continuationToken!)
     do {
@@ -281,7 +282,7 @@ export class TeamsInfo {
     }
 
     if (!meetingId) {
-      throw new Error('meetingId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.MeetingIdRequired)
     }
 
     return await this.getRestClient(context).sendMeetingNotification(meetingId, notification)
@@ -298,13 +299,13 @@ export class TeamsInfo {
    */
   static async sendMessageToListOfUsers (context: TurnContext, activity: Activity, tenantId: string, members: TeamsMember[]): Promise<BatchOperationResponse> {
     if (!activity) {
-      throw new Error('activity is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityRequired)
     }
     if (!tenantId) {
-      throw new Error('tenantId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TenantIdRequired)
     }
     if (!members || members.length === 0) {
-      throw new Error('members list is required.')
+      throw ExceptionHelper.generateException(Error, Errors.MembersListRequired)
     }
 
     return await this.getRestClient(context).sendMessageToListOfUsers(activity, tenantId, members)
@@ -320,10 +321,10 @@ export class TeamsInfo {
    */
   static async sendMessageToAllUsersInTenant (context: TurnContext, activity: Activity, tenantId: string): Promise<BatchOperationResponse> {
     if (!activity) {
-      throw new Error('activity is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityRequired)
     }
     if (!tenantId) {
-      throw new Error('tenantId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TenantIdRequired)
     }
 
     return await this.getRestClient(context).sendMessageToAllUsersInTenant(activity, tenantId)
@@ -340,13 +341,13 @@ export class TeamsInfo {
    */
   static async sendMessageToAllUsersInTeam (context: TurnContext, activity: Activity, tenantId: string, teamId: string): Promise<BatchOperationResponse> {
     if (!activity) {
-      throw new Error('activity is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityRequired)
     }
     if (!tenantId) {
-      throw new Error('tenantId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TenantIdRequired)
     }
     if (!teamId) {
-      throw new Error('teamId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TeamIdRequired)
     }
     return await this.getRestClient(context).sendMessageToAllUsersInTeam(activity, tenantId, teamId)
   }
@@ -362,13 +363,13 @@ export class TeamsInfo {
    */
   static async sendMessageToListOfChannels (context: TurnContext, activity: Activity, tenantId: string, members: TeamsMember[]): Promise<BatchOperationResponse> {
     if (!activity) {
-      throw new Error('activity is required.')
+      throw ExceptionHelper.generateException(Error, Errors.ActivityRequired)
     }
     if (!tenantId) {
-      throw new Error('tenantId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.TenantIdRequired)
     }
     if (!members || members.length === 0) {
-      throw new Error('members list is required.')
+      throw ExceptionHelper.generateException(Error, Errors.MembersListRequired)
     }
     return this.getRestClient(context).sendMessageToListOfChannels(activity, tenantId, members)
   }
@@ -382,7 +383,7 @@ export class TeamsInfo {
    */
   static async getOperationState (context: TurnContext, operationId: string): Promise<BatchOperationStateResponse> {
     if (!operationId) {
-      throw new Error('operationId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.OperationIdRequired)
     }
 
     return await this.getRestClient(context).getOperationState(operationId)
@@ -397,7 +398,7 @@ export class TeamsInfo {
    */
   static async getFailedEntries (context: TurnContext, operationId: string): Promise<BatchFailedEntriesResponse> {
     if (!operationId) {
-      throw new Error('operationId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.OperationIdRequired)
     }
 
     return await this.getRestClient(context).getFailedEntries(operationId)
@@ -412,7 +413,7 @@ export class TeamsInfo {
    */
   static async cancelOperation (context: TurnContext, operationId: string): Promise<CancelOperationResponse> {
     if (!operationId) {
-      throw new Error('operationId is required.')
+      throw ExceptionHelper.generateException(Error, Errors.OperationIdRequired)
     }
 
     return await this.getRestClient(context).cancelOperation(operationId)