@microsoft/agents-hosting 0.1.49

package/src/connector-client/attachmentInfo.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AttachmentView } from './attachmentView'
+
+/**
+ * Represents information about an attachment.
+ */
+export interface AttachmentInfo {
+  /**
+   * The name of the attachment.
+   */
+  name: string;
+  /**
+   * The type of the attachment.
+   */
+  type: string;
+  /**
+   * The views of the attachment.
+   */
+  views: AttachmentView[];
+}

package/src/connector-client/attachmentView.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents a view of an attachment.
+ */
+export interface AttachmentView {
+  /**
+   * The ID of the view.
+   */
+  viewId: string;
+  /**
+   * The size of the view.
+   */
+  size: number;
+}

package/src/connector-client/connectorClient.ts

@@ -0,0 +1,295 @@
+/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+import { AuthConfiguration } from '../auth/authConfiguration'
+import { AuthProvider } from '../auth/authProvider'
+import { debug } from '../logger'
+import { Activity } from '@microsoft/agents-activity'
+import { ConversationsResult } from './conversationsResult'
+import { ConversationParameters } from './conversationParameters'
+import { ConversationResourceResponse } from './conversationResourceResponse'
+import { ResourceResponse } from './resourceResponse'
+import { AttachmentInfo } from './attachmentInfo'
+import { AttachmentData } from './attachmentData'
+
+const logger = debug('agents:connector-client')
+
+/**
+ * ConnectorClient is a client for interacting with the Microsoft Connector API.
+ */
+export class ConnectorClient {
+  protected readonly client: AxiosInstance
+
+  /**
+   * Private constructor for the ConnectorClient.
+   * @param client - The AxiosInstance to use for HTTP requests.
+   */
+  protected constructor (client: AxiosInstance) {
+    this.client = client
+    this.client.interceptors.response.use(
+      (config) => {
+        const { status, statusText, config: requestConfig } = config
+        logger.debug('Response: ', {
+          status,
+          statusText,
+          host: this.client.getUri(),
+          url: requestConfig?.url,
+          data: config.config.data,
+          method: requestConfig?.method,
+        })
+        return config
+      },
+      (error) => {
+        const { code, message, stack } = error
+        const errorDetails = {
+          code,
+          host: this.client.getUri(),
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message,
+          stack,
+        }
+        return Promise.reject(errorDetails)
+      }
+    )
+  }
+
+  /**
+   * Creates a new instance of ConnectorClient with authentication.
+   * @param baseURL - The base URL for the API.
+   * @param authConfig - The authentication configuration.
+   * @param authProvider - The authentication provider.
+   * @param scope - The scope for the authentication token.
+   * @returns A new instance of ConnectorClient.
+   */
+  static async createClientWithAuthAsync (
+    baseURL: string,
+    authConfig: AuthConfiguration,
+    authProvider: AuthProvider,
+    scope: string
+  ): Promise<ConnectorClient> {
+    const axiosInstance = axios.create({
+      baseURL,
+      headers: {
+        Accept: 'application/json'
+      }
+    })
+
+    const token = await authProvider.getAccessToken(authConfig, scope)
+    if (token.length > 1) {
+      axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
+    }
+    return new ConnectorClient(axiosInstance)
+  }
+
+  /**
+   * Retrieves a list of conversations.
+   * @param continuationToken - The continuation token for pagination.
+   * @returns A list of conversations.
+   */
+  public async getConversationsAsync (continuationToken?: string): Promise<ConversationsResult> {
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: '/v3/conversations',
+      params: continuationToken ? { continuationToken } : undefined
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Creates a new conversation.
+   * @param body - The conversation parameters.
+   * @returns The conversation resource response.
+   */
+  public async createConversationAsync (body: ConversationParameters): Promise<ConversationResourceResponse> {
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: '/v3/conversations',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: body
+    }
+    const response: AxiosResponse = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Replies to an activity in a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param activityId - The ID of the activity.
+   * @param body - The activity object.
+   * @returns The resource response.
+   */
+  public async replyToActivityAsync (
+    conversationId: string,
+    activityId: string,
+    body: Activity
+  ): Promise<ResourceResponse> {
+    if (!conversationId || !activityId) {
+      throw new Error('conversationId and activityId are required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: `v3/conversations/${conversationId}/activities/${encodeURIComponent(activityId)}`,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: body
+    }
+    const response = await this.client(config)
+    logger.info('Reply to conversation/activity: ', response.data.id!, activityId)
+    return response.data
+  }
+
+  /**
+   * Sends an activity to a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param body - The activity object.
+   * @returns The resource response.
+   */
+  public async sendToConversationAsync (
+    conversationId: string,
+    body: Activity
+  ): Promise<ResourceResponse> {
+    if (!conversationId) {
+      throw new Error('conversationId is required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: `v3/conversations/${conversationId}/activities`,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: body
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Updates an activity in a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param activityId - The ID of the activity.
+   * @param body - The activity object.
+   * @returns The resource response.
+   */
+  public async updateActivityAsync (
+    conversationId: string,
+    activityId: string,
+    body: Activity
+  ): Promise<ResourceResponse> {
+    if (!conversationId || !activityId) {
+      throw new Error('conversationId and activityId are required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'put',
+      url: `v3/conversations/${conversationId}/activities/${activityId}`,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: body
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Deletes an activity from a conversation.
+   * @param conversationId - The ID of the conversation.
+   * @param activityId - The ID of the activity.
+   * @returns A promise that resolves when the activity is deleted.
+   */
+  public async deleteActivityAsync (
+    conversationId: string,
+    activityId: string
+  ): Promise<void> {
+    if (!conversationId || !activityId) {
+      throw new Error('conversationId and activityId are required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'delete',
+      url: `v3/conversations/${conversationId}/activities/${activityId}`,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+     * Uploads an attachment to a conversation.
+     * @param conversationId - The ID of the conversation.
+     * @param body - The attachment data.
+     * @returns The resource response.
+     */
+  public async uploadAttachment (
+    conversationId: string,
+    body: AttachmentData
+  ): Promise<ResourceResponse> {
+    if (conversationId === undefined) {
+      throw new Error('conversationId is required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'post',
+      url: `v3/conversations/${conversationId}/attachments`,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: body
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Retrieves attachment information by attachment ID.
+   * @param attachmentId - The ID of the attachment.
+   * @returns The attachment information.
+   */
+  public async getAttachmentInfo (
+    attachmentId: string
+  ): Promise<AttachmentInfo> {
+    if (attachmentId === undefined) {
+      throw new Error('attachmentId is required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/attachments/${attachmentId}`,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+
+  /**
+   * Retrieves an attachment by attachment ID and view ID.
+   * @param attachmentId - The ID of the attachment.
+   * @param viewId - The ID of the view.
+   * @returns The attachment as a readable stream.
+   */
+  public async getAttachment (
+    attachmentId: string,
+    viewId: string
+  ): Promise<NodeJS.ReadableStream> {
+    if (attachmentId === undefined) {
+      throw new Error('attachmentId is required')
+    }
+    if (viewId === undefined) {
+      throw new Error('viewId is required')
+    }
+    const config: AxiosRequestConfig = {
+      method: 'get',
+      url: `v3/attachments/${attachmentId}/views/${viewId}`,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response = await this.client(config)
+    return response.data
+  }
+}

package/src/connector-client/conversationMembers.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ChannelAccount } from '@microsoft/agents-activity'
+
+/**
+ * Represents the members of a conversation.
+ */
+export interface ConversationMembers {
+  /**
+   * The ID of the conversation.
+   */
+  id: string;
+  /**
+   * The list of members in the conversation.
+   */
+  members: ChannelAccount[];
+}

package/src/connector-client/conversationParameters.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, ChannelAccount } from '@microsoft/agents-activity'
+
+/**
+ * Represents the parameters for creating a conversation.
+ */
+export interface ConversationParameters {
+  /**
+   * Indicates whether the conversation is a group conversation.
+   */
+  isGroup: boolean
+  /**
+   * The bot account initiating the conversation.
+   */
+  bot: ChannelAccount
+  /**
+   * The members to include in the conversation.
+   */
+  members?: ChannelAccount[]
+  /**
+   * The topic name of the conversation.
+   */
+  topicName?: string
+  /**
+   * The tenant ID of the conversation.
+   */
+  tenantId?: string
+  /**
+   * The initial activity to send to the conversation.
+   */
+  activity: Activity
+  /**
+   * Channel-specific data for the conversation.
+   */
+  channelData: unknown
+}

package/src/connector-client/conversationResourceResponse.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents the response from a conversation resource operation.
+ */
+export interface ConversationResourceResponse {
+  /**
+   * The ID of the activity.
+   */
+  activityId: string;
+  /**
+   * The service URL.
+   */
+  serviceUrl: string;
+  /**
+   * The ID of the conversation resource.
+   */
+  id: string;
+}

package/src/connector-client/conversationsResult.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ConversationMembers } from './conversationMembers'
+
+/**
+ * Represents the result of a conversation query.
+ */
+export interface ConversationsResult {
+  /**
+   * A token to retrieve the next page of results.
+   */
+  continuationToken: string;
+  /**
+   * A list of conversation members.
+   */
+  conversations: ConversationMembers[];
+}

package/src/connector-client/index.ts

@@ -0,0 +1,9 @@
+export * from './attachmentData'
+export * from './attachmentInfo'
+export * from './attachmentView'
+export * from './connectorClient'
+export * from './conversationMembers'
+export * from './conversationParameters'
+export * from './conversationResourceResponse'
+export * from './conversationsResult'
+export * from './resourceResponse'

package/src/connector-client/resourceResponse.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents a response containing a resource ID.
+ */
+export interface ResourceResponse {
+  /**
+   * Unique identifier of the resource.
+   */
+  id: string;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export * from './auth/'
+export { authorizeJWT } from './auth/jwt-middleware'
+
+export * from './app'
+export * from './cards'
+export * from './connector-client'
+export * from './invoke'
+export * from './oauth'
+export * from './state'
+export * from './storage'
+export * from './transcript'
+
+export * from './activityHandler'
+export * from './cloudAdapter'
+export * from './claimsIdentity'
+export * from './logger'
+export * from './messageFactory'
+export * from './statusCodes'
+export * from './turnContext'
+export * from './turnContextStateCollection'
+export * from './logger'
+export * from './storage/storage'
+
+export * from './agent-client'
+
+export * from '@microsoft/agents-activity'

package/src/invoke/adaptiveCardAuthentication.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TokenExchangeInvokeRequest } from './tokenExchangeInvokeRequest'
+
+/**
+ * Represents the authentication information for an adaptive card.
+ */
+export interface AdaptiveCardAuthentication extends TokenExchangeInvokeRequest {
+  // No-op. This interface was accidentally created as a duplicate of TokenExchangeInvokeRequest but must remain for backwards-compatibility.
+}

package/src/invoke/adaptiveCardInvokeResponse.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents the response of an adaptive card invoke request.
+ */
+export interface AdaptiveCardInvokeResponse {
+  /**
+   * The status code of the response.
+   */
+  statusCode: number
+  /**
+   * The type of the response.
+   */
+  type: string
+  /**
+   * The value of the response.
+   */
+  value: Record<string, unknown>
+}

package/src/invoke/adaptiveCardInvokeValue.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AdaptiveCardInvokeAction } from '@microsoft/agents-activity'
+import { AdaptiveCardAuthentication } from './adaptiveCardAuthentication'
+
+/**
+ * Represents the value of an adaptive card invoke request.
+ */
+export interface AdaptiveCardInvokeValue {
+  /**
+   * The action to be performed.
+   */
+  action: AdaptiveCardInvokeAction
+  /**
+   * The authentication information.
+   */
+  authentication: AdaptiveCardAuthentication
+  /**
+   * The state of the adaptive card.
+   */
+  state: string
+}

package/src/invoke/index.ts

@@ -0,0 +1,9 @@
+export * from './adaptiveCardAuthentication'
+export * from './adaptiveCardInvokeResponse'
+export * from './adaptiveCardInvokeValue'
+export * from './invokeException'
+export * from './invokeResponse'
+export * from './searchInvokeOptions'
+export * from './searchInvokeResponse'
+export * from './searchInvokeValue'
+export * from './tokenExchangeInvokeRequest'

package/src/invoke/invokeException.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { StatusCodes } from '../statusCodes'
+import { InvokeResponse } from './invokeResponse'
+
+/**
+ * Represents an exception that occurs during an invoke operation.
+ */
+export class InvokeException<T = unknown> extends Error {
+  /**
+   * Creates a new instance of InvokeException.
+   * @param status The status code of the exception.
+   * @param response The optional response body.
+   */
+  constructor (private readonly status: StatusCodes, private readonly response?: T) {
+    super()
+    this.name = 'InvokeException'
+  }
+
+  /**
+   * Creates an invoke response from the exception.
+   * @returns The invoke response.
+   */
+  createInvokeResponse (): InvokeResponse {
+    return {
+      status: this.status,
+      body: this.response
+    }
+  }
+}

package/src/invoke/invokeResponse.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents the response of an invoke request.
+ */
+export interface InvokeResponse<T = any> {
+  /**
+   * The status code of the response.
+   */
+  status: number
+  /**
+   * The optional body of the response.
+   */
+  body?: T
+}

package/src/invoke/searchInvokeOptions.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents the options for a search invoke request.
+ */
+export interface SearchInvokeOptions {
+  /**
+   * The number of items to skip.
+   */
+  skip: number
+  /**
+   * The number of items to retrieve.
+   */
+  top: number
+}

package/src/invoke/searchInvokeResponse.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AdaptiveCardInvokeResponse } from './adaptiveCardInvokeResponse'
+
+/**
+ * Represents the response of a search invoke request.
+ */
+export interface SearchInvokeResponse extends AdaptiveCardInvokeResponse {}

package/src/invoke/searchInvokeValue.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SearchInvokeOptions } from './searchInvokeOptions'
+
+/**
+ * Represents the value of a search invoke request.
+ */
+export interface SearchInvokeValue {
+  /**
+   * The kind of search.
+   */
+  kind: string
+  /**
+   * The text of the query.
+   */
+  queryText: string
+  /**
+   * The options for the search query.
+   */
+  queryOptions: SearchInvokeOptions
+  /**
+   * The context of the search.
+   */
+  context: any
+}