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

package/src/client/teamsConnectorClient.ts

@@ -0,0 +1,340 @@
+/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+import { Activity, ChannelAccount } from '@microsoft/agents-activity'
+import { TeamsChannelAccount } from '../activity-extensions/teamsChannelAccount'
+import { MeetingInfo } from '../meeting/meetingInfo'
+import { MeetingNotification } from '../meeting/meetingNotification'
+import { MeetingNotificationResponse } from '../meeting/meetingNotificationResponse'
+import { ChannelInfo } from '../activity-extensions/channelInfo'
+import { TeamsChannelData } from '../activity-extensions'
+import { BatchFailedEntriesResponse, BatchOperationStateResponse, CancelOperationResponse, TeamDetails, TeamsBatchOperationResponse, TeamsMember, TeamsPagedMembersResult } from './teamsConnectorClient.types'
+import { ConnectorClient } from '@microsoft/agents-hosting'
+
+/**
+ * A client for interacting with Microsoft Teams APIs.
+ * Extends the ConnectorClient class to provide Teams-specific functionalities.
+ */
+export class TeamsConnectorClient {
+  private axiosInstance: AxiosInstance
+  constructor (private client: ConnectorClient) {
+    this.axiosInstance = client.axiosInstance
+  }
+
+  /**
+   * Retrieves a member from a conversation or team.
+   * @param activity - The activity containing the context.
+   * @param userId - The ID of the user to retrieve.
+   * @returns A TeamsChannelAccount representing the member.
+   */
+  static async getMember (activity: Activity, userId: string): Promise<TeamsChannelAccount> {
+    const teamsChannelData = activity.channelData as TeamsChannelData
+    const teamId = teamsChannelData.team?.id
+    if (teamId) {
+      return await this.getTeamMember(activity, teamId, userId)
+    } else {
+      const conversationId = (activity.conversation != null) && activity.conversation.id ? activity.conversation.id : undefined
+      return await this.getMemberInternal(activity, conversationId, userId)
+    }
+  }
+
+  /**
+   * Retrieves the team ID from an activity.
+   * @param activity - The activity containing the context.
+   * @returns The team ID as a string.
+   * @throws Error if the activity is missing or invalid.
+   */
+  private static getTeamId (activity: any): string {
+    if (!activity) {
+      throw new Error('Missing activity parameter')
+    }
+    const channelData = activity.channelData as TeamsChannelData
+    const team = channelData && (channelData.team != null) ? channelData.team : undefined
+    const teamId = (team != null) && typeof team.id === 'string' ? team.id : undefined
+    return teamId as string
+  }
+
+  /**
+   * Retrieves a member from a team.
+   * @param activity - The activity containing the context.
+   * @param teamId - The ID of the team.
+   * @param userId - The ID of the user to retrieve.
+   * @returns A TeamsChannelAccount representing the team member.
+   * @throws Error if the teamId or userId is missing.
+   */
+  static async getTeamMember (activity: any, teamId?: string, userId?: string) {
+    const t = teamId || this.getTeamId(activity)
+    if (!t) {
+      throw new Error('This method is only valid within the scope of a MS Teams Team.')
+    }
+    if (!userId) {
+      throw new Error('userId is required')
+    }
+    return await this.getMemberInternal(activity, t, userId)
+  }
+
+  /**
+   * Retrieves a member from a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param userId - The ID of the user to retrieve.
+   * @returns A ChannelAccount representing the conversation member.
+   */
+  public async getConversationMember (conversationId: string, userId: string): Promise<ChannelAccount> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `/v3/conversations/${conversationId}/members/${userId}`,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response: AxiosResponse = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Retrieves a member from a conversation or team internally.
+   * @param activity - The activity containing the context.
+   * @param conversationId - The ID of the conversation.
+   * @param userId - The ID of the user to retrieve.
+   * @returns A ChannelAccount representing the member.
+   * @throws Error if the conversationId is missing or the client is unavailable.
+   */
+  static async getMemberInternal (
+    activity: any,
+    conversationId: string | undefined,
+    userId: string
+  ): Promise<ChannelAccount> {
+    if (!conversationId) {
+      throw new Error('conversationId is required')
+    }
+    const client : ConnectorClient = activity.turnState?.get(activity.adapter.ConnectorClientKey)
+    if (!client) {
+      throw new Error('Client is not available in the context.')
+    }
+    const teamMember: ChannelAccount = await client.getConversationMember(conversationId, userId)
+    return teamMember
+  }
+
+  /**
+   * Retrieves paged members of a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param pageSize - The number of members per page.
+   * @param continuationToken - The token for pagination.
+   * @returns A TeamsPagedMembersResult containing the paged members.
+   */
+  public async getConversationPagedMember (conversationId: string, pageSize: number, continuationToken: string): Promise<TeamsPagedMembersResult> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/conversations/${conversationId}/pagedMembers`,
+      params: {
+        pageSize,
+        continuationToken
+      }
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Fetches the list of channels in a team.
+   * @param teamId - The ID of the team.
+   * @returns An array of ChannelInfo objects representing the channels.
+   */
+  public async fetchChannelList (teamId: string): Promise<ChannelInfo[]> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/teams/${teamId}/conversations`
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Fetches the details of a team.
+   * @param teamId - The ID of the team.
+   * @returns A TeamDetails object containing the team details.
+   */
+  public async fetchTeamDetails (teamId: string): Promise<TeamDetails> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/teams/${teamId}`
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Fetches information about a meeting participant.
+   * @param meetingId - The ID of the meeting.
+   * @param participantId - The ID of the participant.
+   * @param tenantId - The tenant ID.
+   * @returns A string containing participant information.
+   */
+  public async fetchMeetingParticipant (meetingId: string, participantId: string, tenantId: string): Promise<string> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v1/meetings/${meetingId}/participants/${participantId}`,
+      params: { tenantId }
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Fetches information about a meeting.
+   * @param meetingId - The ID of the meeting.
+   * @returns A MeetingInfo object containing the meeting information.
+   */
+  public async fetchMeetingInfo (meetingId: string): Promise<MeetingInfo> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v1/meetings/${meetingId}`
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Sends a notification to a meeting.
+   * @param meetingId - The ID of the meeting.
+   * @param notification - The notification to send.
+   * @returns A MeetingNotificationResponse object containing the response.
+   */
+  public async sendMeetingNotification (meetingId: string, notification: MeetingNotification): Promise<MeetingNotificationResponse> {
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: `v1/meetings/${meetingId}/notification`,
+      data: notification
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Sends a message to a list of users.
+   * @param activity - The activity to send.
+   * @param tenantId - The tenant ID.
+   * @param members - The list of members to send the message to.
+   * @returns A TeamsBatchOperationResponse object containing the response.
+   */
+  public async sendMessageToListOfUsers (activity: Activity, tenantId: string, members: TeamsMember[]): Promise<TeamsBatchOperationResponse> {
+    const content = {
+      activity,
+      members,
+      tenantId
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: 'v3/batch/conversation/users',
+      data: content
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Sends a message to all users in a tenant.
+   * @param activity - The activity to send.
+   * @param tenandId - The tenant ID.
+   * @returns A TeamsBatchOperationResponse object containing the response.
+   */
+  public async sendMessageToAllUsersInTenant (activity: Activity, tenandId: string): Promise<TeamsBatchOperationResponse> {
+    const content = {
+      activity,
+      tenandId
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: 'v3/batch/conversation/tenant',
+      data: content
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Sends a message to all users in a team.
+   * @param activity - The activity to send.
+   * @param tenantId - The tenant ID.
+   * @param teamId - The team ID.
+   * @returns A TeamsBatchOperationResponse object containing the response.
+   */
+  public async sendMessageToAllUsersInTeam (activity: Activity, tenantId: string, teamId: string): Promise<TeamsBatchOperationResponse> {
+    const content = {
+      activity,
+      tenantId,
+      teamId
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: 'v3/batch/conversation/team',
+      data: content
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Sends a message to a list of channels.
+   * @param activity - The activity to send.
+   * @param tenantId - The tenant ID.
+   * @param members - The list of members to send the message to.
+   * @returns A TeamsBatchOperationResponse object containing the response.
+   */
+  public async sendMessageToListOfChannels (activity: Activity, tenantId: string, members: TeamsMember[]): Promise<TeamsBatchOperationResponse> {
+    const content = {
+      activity,
+      tenantId,
+      members
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: 'v3/batch/conversation/channels',
+      data: content
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Retrieves the state of a batch operation.
+   * @param operationId - The ID of the operation.
+   * @returns A BatchOperationStateResponse object containing the operation state.
+   */
+  public async getOperationState (operationId: string): Promise<BatchOperationStateResponse> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/batch/conversation/${operationId}`
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Retrieves the failed entries of a batch operation.
+   * @param operationId - The ID of the operation.
+   * @returns A BatchFailedEntriesResponse object containing the failed entries.
+   */
+  public async getFailedEntries (operationId: string): Promise<BatchFailedEntriesResponse> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/batch/conversation/failedentries/${operationId}`
+    }
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+
+  /**
+   * Cancels a batch operation.
+   * @param operationId - The ID of the operation.
+   * @returns A CancelOperationResponse object containing the response.
+   */
+  public async cancelOperation (operationId: string): Promise<CancelOperationResponse> {
+    const config: AxiosRequestConfig = {
+      method: 'delete',
+      url: `v3/batch/conversation/${operationId}`
+    }
+
+    const response = await this.axiosInstance(config)
+    return response.data
+  }
+}

package/src/client/teamsConnectorClient.types.ts

@@ -0,0 +1,168 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TeamsChannelAccount } from '../activity-extensions/teamsChannelAccount'
+
+/**
+ * Represents details of a Microsoft Teams team.
+ */
+export interface TeamDetails {
+  /**
+     * Unique identifier of the team.
+     */
+  id?: string;
+  /**
+     * Name of the team.
+     */
+  name?: string;
+  /**
+     * Azure Active Directory group ID of the team.
+     */
+  aadGroupId?: string;
+  /**
+     * Number of channels in the team.
+     */
+  channelCount?: number;
+  /**
+     * Number of members in the team.
+     */
+  memberCount?: number;
+  /**
+     * Type of the team.
+     */
+  type?: string;
+}
+
+/**
+ * Represents a member in a Microsoft Teams team.
+ */
+export type TeamsMember = {
+  /**
+     * Unique identifier of the member.
+     */
+  id: string;
+}
+
+/**
+ * Represents a paged result of Teams members.
+ */
+export interface TeamsPagedMembersResult {
+  /**
+   * Continuation token for fetching the next page of results.
+   */
+  continuationToken: string;
+  /**
+   * List of Teams channel accounts.
+   */
+  members: TeamsChannelAccount[];
+}
+
+/**
+ * Represents a failed entry in a batch operation.
+ */
+export interface BatchFailedEntry {
+  /**
+     * Unique identifier of the failed entry.
+     */
+  id: string;
+  /**
+     * Error message associated with the failed entry.
+     */
+  error: string;
+}
+
+/**
+ * Represents the response for failed entries in a batch operation.
+ */
+export interface BatchFailedEntriesResponse {
+  /**
+   * A token to retrieve the next page of results.
+   */
+  continuationToken: string;
+  /**
+   * A list of failed entry responses.
+   */
+  failedEntryResponses: BatchFailedEntry[];
+}
+
+/**
+ * Represents the response of a batch operation.
+ */
+export interface BatchOperationResponse {
+  /**
+     * Unique identifier of the batch operation.
+     */
+  operationId: string;
+}
+
+/**
+ * Represents the state of a batch operation.
+ */
+export interface BatchOperationStateResponse {
+  /**
+     * The state of the batch operation.
+     */
+  state: string;
+  /**
+     * A map of status codes to their counts.
+     */
+  statusMap: Record<number, number>;
+  /**
+     * The retry-after date for the batch operation.
+     */
+  retryAfter?: Date;
+  /**
+     * The total number of entries in the batch operation.
+     */
+  totalEntriesCount: number;
+}
+
+/**
+ * Represents the response from a cancel operation.
+ */
+export type CancelOperationResponse = {
+  /**
+     * The response object.
+     */
+  _response: Response & {
+    /**
+       * The response body as text.
+       */
+    bodyAsText: string;
+    /**
+       * The parsed response body.
+       */
+    parsedBody: {};
+  };
+}
+
+/**
+ * Represents a response containing a resource ID.
+ */
+export interface ResourceResponse {
+  /**
+     * Unique identifier of the resource.
+     */
+  id: string;
+}
+
+/**
+ * Represents a response from a batch operation in Teams.
+ */
+export type TeamsBatchOperationResponse = BatchOperationResponse & {
+  /**
+     * The raw response object.
+     */
+  _response: Response & {
+    /**
+       * The response body as text.
+       */
+    bodyAsText: string;
+    /**
+       * The parsed response body.
+       */
+    parsedBody: BatchOperationResponse | {};
+  }
+}

package/src/compat/readReceipInfo.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Class representing read receipt information.
+ */
+export class ReadReceiptInfo {
+  /**
+   * The ID of the last read message.
+   */
+  lastReadMessageId: string
+
+  /**
+   * Creates an instance of ReadReceiptInfo.
+   * @param {string} [lastReadMessageId=''] - The ID of the last read message.
+   */
+  constructor (lastReadMessageId: string = '') {
+    this.lastReadMessageId = lastReadMessageId
+  }
+
+  /**
+   * Checks if a message has been read.
+   * @param {string} compareMessageId - The ID of the message to compare.
+   * @param {string} lastReadMessageId - The ID of the last read message.
+   * @returns {boolean} True if the message has been read, false otherwise.
+   */
+  static isMessageRead (compareMessageId: string, lastReadMessageId: string): boolean {
+    if (
+      compareMessageId &&
+            compareMessageId.trim().length > 0 &&
+            lastReadMessageId &&
+            lastReadMessageId.trim().length > 0
+    ) {
+      const compareMessageIdNum = Number(compareMessageId)
+      const lastReadMessageIdNum = Number(lastReadMessageId)
+
+      if (compareMessageIdNum && lastReadMessageIdNum) {
+        return compareMessageIdNum <= lastReadMessageIdNum
+      }
+    }
+    return false
+  }
+
+  /**
+   * Checks if a message has been read using the instance's last read message ID.
+   * @param {string} compareMessageId - The ID of the message to compare.
+   * @returns {boolean} True if the message has been read, false otherwise.
+   */
+  isMessageRead (compareMessageId: string): boolean {
+    return ReadReceiptInfo.isMessageRead(compareMessageId, this.lastReadMessageId)
+  }
+}