699 lines
No EOL
38 KiB
TypeScript
699 lines
No EOL
38 KiB
TypeScript
/**
|
|
* @module botbuilder
|
|
*/
|
|
/**
|
|
* Copyright (c) Microsoft Corporation. All rights reserved.
|
|
* Licensed under the MIT License.
|
|
*/
|
|
import { BotFrameworkHttpAdapter } from './botFrameworkHttpAdapter';
|
|
import { ConnectorClientBuilder, Request, Response, WebRequest, WebResponse } from './interfaces';
|
|
import { Activity, BotAdapter, ChannelAccount, ConversationParameters, ConversationReference, ConversationsResult, CoreAppCredentials, ExtendedUserTokenProvider, ResourceResponse, TokenResponse, TurnContext } from 'botbuilder-core';
|
|
import { AppCredentials, AuthenticationConfiguration, ClaimsIdentity, ConnectorClient, ConnectorClientOptions, SignInUrlResponse, SimpleCredentialProvider, TokenApiClient, TokenExchangeRequest, TokenStatus } from 'botframework-connector';
|
|
import { INodeBuffer, INodeSocket, IReceiveRequest, NodeWebSocketFactoryBase, RequestHandler, StreamingResponse } from 'botframework-streaming';
|
|
/**
|
|
* @deprecated Use `CloudAdapter` with `ConfigurationBotFrameworkAuthentication` instead to configure bot runtime.
|
|
* Contains settings used to configure a [BotFrameworkAdapter](xref:botbuilder.BotFrameworkAdapter) instance.
|
|
*/
|
|
export interface BotFrameworkAdapterSettings {
|
|
/**
|
|
* The ID assigned to your bot in the [Bot Framework Portal](https://dev.botframework.com/).
|
|
*/
|
|
appId: string;
|
|
/**
|
|
* The password assigned to your bot in the [Bot Framework Portal](https://dev.botframework.com/).
|
|
*/
|
|
appPassword: string;
|
|
/**
|
|
* Optional. The tenant to acquire the bot-to-channel token from.
|
|
*/
|
|
channelAuthTenant?: string;
|
|
/**
|
|
* Optional. The OAuth API endpoint for your bot to use.
|
|
*/
|
|
oAuthEndpoint?: string;
|
|
/**
|
|
* Optional. The OpenID Metadata endpoint for your bot to use.
|
|
*/
|
|
openIdMetadata?: string;
|
|
/**
|
|
* Optional. The channel service option for this bot to validate connections from Azure or other channel locations.
|
|
*/
|
|
channelService?: string;
|
|
/**
|
|
* Optional. Used to pass in a NodeWebSocketFactoryBase instance.
|
|
*/
|
|
webSocketFactory?: NodeWebSocketFactoryBase;
|
|
/**
|
|
* Optional. Certificate thumbprint to authenticate the appId against AAD.
|
|
*/
|
|
certificateThumbprint?: string;
|
|
/**
|
|
* Optional. Certificate key to authenticate the appId against AAD.
|
|
*/
|
|
certificatePrivateKey?: string;
|
|
/**
|
|
* Optional. Used to require specific endorsements and verify claims. Recommended for Skills.
|
|
*/
|
|
authConfig?: AuthenticationConfiguration;
|
|
/**
|
|
* Optional. Used when creating new ConnectorClients.
|
|
*/
|
|
clientOptions?: ConnectorClientOptions;
|
|
}
|
|
export declare const USER_AGENT: string;
|
|
/**
|
|
* A [BotAdapter](xref:botbuilder-core.BotAdapter) that can connect a bot to a service endpoint.
|
|
* Implements [IUserTokenProvider](xref:botbuilder-core.IUserTokenProvider).
|
|
*
|
|
* @remarks
|
|
* The bot adapter encapsulates authentication processes and sends activities to and receives
|
|
* activities from the Bot Connector Service. When your bot receives an activity, the adapter
|
|
* creates a turn context object, passes it to your bot application logic, and sends responses
|
|
* back to the user's channel.
|
|
*
|
|
* The adapter processes and directs incoming activities in through the bot middleware pipeline to
|
|
* your bot logic and then back out again. As each activity flows in and out of the bot, each
|
|
* piece of middleware can inspect or act upon the activity, both before and after the bot logic runs.
|
|
* Use the [use](xref:botbuilder-core.BotAdapter.use) method to add [Middleware](xref:botbuilder-core.Middleware)
|
|
* objects to your adapter's middleware collection.
|
|
*
|
|
* For more information, see the articles on
|
|
* [How bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
|
* [Middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware).
|
|
*
|
|
* For example:
|
|
* ```JavaScript
|
|
* const { BotFrameworkAdapter } = require('botbuilder');
|
|
*
|
|
* const adapter = new BotFrameworkAdapter({
|
|
* appId: process.env.MicrosoftAppId,
|
|
* appPassword: process.env.MicrosoftAppPassword
|
|
* });
|
|
*
|
|
* adapter.onTurnError = async (context, error) => {
|
|
* // Catch-all logic for errors.
|
|
* };
|
|
* ```
|
|
*/
|
|
/**
|
|
* @deprecated Use `CloudAdapter` instead.
|
|
*/
|
|
export declare class BotFrameworkAdapter extends BotAdapter implements BotFrameworkHttpAdapter, ConnectorClientBuilder, ExtendedUserTokenProvider, RequestHandler {
|
|
readonly TokenApiClientCredentialsKey: symbol;
|
|
protected readonly credentials: AppCredentials;
|
|
protected readonly credentialsProvider: SimpleCredentialProvider;
|
|
protected readonly settings: BotFrameworkAdapterSettings;
|
|
private isEmulatingOAuthCards;
|
|
private logic;
|
|
private streamingServer;
|
|
private webSocketFactory;
|
|
private authConfiguration;
|
|
private namedPipeName?;
|
|
/**
|
|
* Creates a new instance of the [BotFrameworkAdapter](xref:botbuilder.BotFrameworkAdapter) class.
|
|
*
|
|
* @param settings Optional. The settings to use for this adapter instance.
|
|
* @remarks
|
|
* If the `settings` parameter does not include
|
|
* [channelService](xref:botbuilder.BotFrameworkAdapterSettings.channelService) or
|
|
* [openIdMetadata](xref:botbuilder.BotFrameworkAdapterSettings.openIdMetadata) values, the
|
|
* constructor checks the process' environment variables for these values. These values may be
|
|
* set when a bot is provisioned on Azure and if so are required for the bot to work properly
|
|
* in the global cloud or in a national cloud.
|
|
*
|
|
* The [BotFrameworkAdapterSettings](xref:botbuilder.BotFrameworkAdapterSettings) class defines
|
|
* the available adapter settings.
|
|
*/
|
|
constructor(settings?: Partial<BotFrameworkAdapterSettings>);
|
|
/**
|
|
* Used in streaming contexts to check if the streaming connection is still open for the bot to send activities.
|
|
*
|
|
* @returns True if the streaming connection is open, otherwise false.
|
|
*/
|
|
get isStreamingConnectionOpen(): boolean;
|
|
/**
|
|
* Asynchronously resumes a conversation with a user, possibly after some time has gone by.
|
|
*
|
|
* @param reference A reference to the conversation to continue.
|
|
* @param oAuthScope The intended recipient of any sent activities.
|
|
* @param logic The asynchronous method to call after the adapter middleware runs.
|
|
* @remarks
|
|
* This is often referred to as a _proactive notification_, the bot can proactively
|
|
* send a message to a conversation or user without waiting for an incoming message.
|
|
* For example, a bot can use this method to send notifications or coupons to a user.
|
|
*
|
|
* To send a proactive message:
|
|
* 1. Save a copy of a [ConversationReference](xref:botframework-schema.ConversationReference)
|
|
* from an incoming activity. For example, you can store the conversation reference in a database.
|
|
* 1. Call this method to resume the conversation at a later time. Use the saved reference to access the conversation.
|
|
* 1. On success, the adapter generates a [TurnContext](xref:botbuilder-core.TurnContext) object and calls the `logic` function handler.
|
|
* Use the `logic` function to send the proactive message.
|
|
*
|
|
* To copy the reference from any incoming activity in the conversation, use the
|
|
* [TurnContext.getConversationReference](xref:botbuilder-core.TurnContext.getConversationReference) method.
|
|
*
|
|
* This method is similar to the [processActivity](xref:botbuilder.BotFrameworkAdapter.processActivity) method.
|
|
* The adapter creates a [TurnContext](xref:botbuilder-core.TurnContext) and routes it through
|
|
* its middleware before calling the `logic` handler. The created activity will have a
|
|
* [type](xref:botframework-schema.Activity.type) of 'event' and a
|
|
* [name](xref:botframework-schema.Activity.name) of 'continueConversation'.
|
|
*
|
|
* For example:
|
|
* ```JavaScript
|
|
* server.post('/api/notifyUser', async (req, res) => {
|
|
* // Lookup previously saved conversation reference.
|
|
* const reference = await findReference(req.body.refId);
|
|
*
|
|
* // Proactively notify the user.
|
|
* if (reference) {
|
|
* await adapter.continueConversation(reference, async (context) => {
|
|
* await context.sendActivity(req.body.message);
|
|
* });
|
|
* res.send(200);
|
|
* } else {
|
|
* res.send(404);
|
|
* }
|
|
* });
|
|
* ```
|
|
*/
|
|
continueConversation(reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Asynchronously resumes a conversation with a user, possibly after some time has gone by.
|
|
*
|
|
* @param reference [ConversationReference](xref:botframework-schema.ConversationReference) of the conversation to continue.
|
|
* @param oAuthScope The intended recipient of any sent activities or the function to call to continue the conversation.
|
|
* @param logic Optional. The asynchronous method to call after the adapter middleware runs.
|
|
*/
|
|
continueConversation(reference: Partial<ConversationReference>, oAuthScope: string, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Asynchronously creates and starts a conversation with a user on a channel.
|
|
*
|
|
* @param {Partial<ConversationReference>} reference A reference for the conversation to create.
|
|
* @param {(context: TurnContext) => Promise<void>} logic The asynchronous method to call after the adapter middleware runs.
|
|
* @returns {Promise<void>} a promise representing the asynchronous operation
|
|
* @summary
|
|
* To use this method, you need both the bot's and the user's account information on a channel.
|
|
* The Bot Connector service supports the creating of group conversations; however, this
|
|
* method and most channels only support initiating a direct message (non-group) conversation.
|
|
*
|
|
* To create and start a new conversation:
|
|
* 1. Get a copy of a [ConversationReference](xref:botframework-schema.ConversationReference) from an incoming activity.
|
|
* 1. Set the [user](xref:botframework-schema.ConversationReference.user) property to the
|
|
* [ChannelAccount](xref:botframework-schema.ChannelAccount) value for the intended recipient.
|
|
* 1. Call this method to request that the channel create a new conversation with the specified user.
|
|
* 1. On success, the adapter generates a turn context and calls the `logic` function handler.
|
|
*
|
|
* To get the initial reference, use the
|
|
* [TurnContext.getConversationReference](xref:botbuilder-core.TurnContext.getConversationReference)
|
|
* method on any incoming activity in the conversation.
|
|
*
|
|
* If the channel establishes the conversation, the generated event activity's
|
|
* [conversation](xref:botframework-schema.Activity.conversation) property will contain the
|
|
* ID of the new conversation.
|
|
*
|
|
* This method is similar to the [processActivity](xref:botbuilder.BotFrameworkAdapter.processActivity) method.
|
|
* The adapter creates a [TurnContext](xref:botbuilder-core.TurnContext) and routes it through
|
|
* middleware before calling the `logic` handler. The created activity will have a
|
|
* [type](xref:botframework-schema.Activity.type) of 'event' and a
|
|
* [name](xref:botframework-schema.Activity.name) of 'createConversation'.
|
|
*
|
|
* For example:
|
|
* ```JavaScript
|
|
* // Get group members conversation reference
|
|
* const reference = TurnContext.getConversationReference(context.activity);
|
|
*
|
|
* // ...
|
|
* // Start a new conversation with the user
|
|
* await adapter.createConversation(reference, async (ctx) => {
|
|
* await ctx.sendActivity(`Hi (in private)`);
|
|
* });
|
|
* ```
|
|
*/
|
|
createConversation(reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Asynchronously creates and starts a conversation with a user on a channel.
|
|
*
|
|
* @param {Partial<ConversationReference>} reference A reference for the conversation to create.
|
|
* @param {Partial<ConversationParameters>} parameters Parameters used when creating the conversation
|
|
* @param {(context: TurnContext) => Promise<void>} logic The asynchronous method to call after the adapter middleware runs.
|
|
* @returns {Promise<void>} a promise representing the asynchronous operation
|
|
*/
|
|
createConversation(reference: Partial<ConversationReference>, parameters: Partial<ConversationParameters>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Asynchronously deletes an existing activity.
|
|
*
|
|
* This interface supports the framework and is not intended to be called directly for your code.
|
|
* Use [TurnContext.deleteActivity](xref:botbuilder-core.TurnContext.deleteActivity) to delete
|
|
* an activity from your bot code.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param reference Conversation reference information for the activity to delete.
|
|
* @remarks
|
|
* Not all channels support this operation. For channels that don't, this call may throw an exception.
|
|
*/
|
|
deleteActivity(context: TurnContext, reference: Partial<ConversationReference>): Promise<void>;
|
|
/**
|
|
* Asynchronously removes a member from the current conversation.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param memberId The ID of the member to remove from the conversation.
|
|
* @remarks
|
|
* Remove a member's identity information from the conversation.
|
|
*
|
|
* Not all channels support this operation. For channels that don't, this call may throw an exception.
|
|
*/
|
|
deleteConversationMember(context: TurnContext, memberId: string): Promise<void>;
|
|
/**
|
|
* Asynchronously lists the members of a given activity.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param activityId Optional. The ID of the activity to get the members of. If not specified, the current activity ID is used.
|
|
* @returns An array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
|
* the users involved in a given activity.
|
|
* @remarks
|
|
* Returns an array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
|
* the users involved in a given activity.
|
|
*
|
|
* This is different from [getConversationMembers](xref:botbuilder.BotFrameworkAdapter.getConversationMembers)
|
|
* in that it will return only those users directly involved in the activity, not all members of the conversation.
|
|
*/
|
|
getActivityMembers(context: TurnContext, activityId?: string): Promise<ChannelAccount[]>;
|
|
/**
|
|
* Asynchronously lists the members of the current conversation.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @returns An array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
|
* all users currently involved in a conversation.
|
|
* @remarks
|
|
* Returns an array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
|
* all users currently involved in a conversation.
|
|
*
|
|
* This is different from [getActivityMembers](xref:botbuilder.BotFrameworkAdapter.getActivityMembers)
|
|
* in that it will return all members of the conversation, not just those directly involved in a specific activity.
|
|
*/
|
|
getConversationMembers(context: TurnContext): Promise<ChannelAccount[]>;
|
|
/**
|
|
* For the specified channel, asynchronously gets a page of the conversations in which this bot has participated.
|
|
*
|
|
* @param contextOrServiceUrl The URL of the channel server to query or a
|
|
* [TurnContext](xref:botbuilder-core.TurnContext) object from a conversation on the channel.
|
|
* @param continuationToken Optional. The continuation token from the previous page of results.
|
|
* Omit this parameter or use `undefined` to retrieve the first page of results.
|
|
* @returns A [ConversationsResult](xref:botframework-schema.ConversationsResult) object containing a page of results
|
|
* and a continuation token.
|
|
* @remarks
|
|
* The the return value's [conversations](xref:botframework-schema.ConversationsResult.conversations) property contains a page of
|
|
* [ConversationMembers](xref:botframework-schema.ConversationMembers) objects. Each object's
|
|
* [id](xref:botframework-schema.ConversationMembers.id) is the ID of a conversation in which the bot has participated on this channel.
|
|
* This method can be called from outside the context of a conversation, as only the bot's service URL and credentials are required.
|
|
*
|
|
* The channel batches results in pages. If the result's
|
|
* [continuationToken](xref:botframework-schema.ConversationsResult.continuationToken) property is not empty, then
|
|
* there are more pages to get. Use the returned token to get the next page of results.
|
|
* If the `contextOrServiceUrl` parameter is a [TurnContext](xref:botbuilder-core.TurnContext), the URL of the channel server is
|
|
* retrieved from
|
|
* `contextOrServiceUrl`.[activity](xref:botbuilder-core.TurnContext.activity).[serviceUrl](xref:botframework-schema.Activity.serviceUrl).
|
|
*/
|
|
getConversations(contextOrServiceUrl: TurnContext | string, continuationToken?: string): Promise<ConversationsResult>;
|
|
/**
|
|
* Asynchronously attempts to retrieve the token for a user that's in a login flow.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param connectionName The name of the auth connection to use.
|
|
* @param magicCode Optional. The validation code the user entered.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
* @returns A [TokenResponse](xref:botframework-schema.TokenResponse) object that contains the user token.
|
|
*/
|
|
getUserToken(context: TurnContext, connectionName: string, magicCode?: string): Promise<TokenResponse>;
|
|
getUserToken(context: TurnContext, connectionName: string, magicCode?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenResponse>;
|
|
/**
|
|
* Asynchronously signs out the user from the token server.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param connectionName The name of the auth connection to use.
|
|
* @param userId The ID of user to sign out.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
*/
|
|
signOutUser(context: TurnContext, connectionName?: string, userId?: string): Promise<void>;
|
|
signOutUser(context: TurnContext, connectionName?: string, userId?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<void>;
|
|
/**
|
|
* Asynchronously gets a sign-in link from the token server that can be sent as part
|
|
* of a [SigninCard](xref:botframework-schema.SigninCard).
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param connectionName The name of the auth connection to use.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
* @param userId The user id that will be associated with the token.
|
|
* @param finalRedirect The final URL that the OAuth flow will redirect to.
|
|
*/
|
|
getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: AppCredentials, userId?: string, finalRedirect?: string): Promise<string>;
|
|
getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: CoreAppCredentials, userId?: string, finalRedirect?: string): Promise<string>;
|
|
/**
|
|
* Asynchronously retrieves the token status for each configured connection for the given user.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param userId Optional. If present, the ID of the user to retrieve the token status for.
|
|
* Otherwise, the ID of the user who sent the current activity is used.
|
|
* @param includeFilter Optional. A comma-separated list of connection's to include. If present,
|
|
* the `includeFilter` parameter limits the tokens this method returns.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
* @returns The [TokenStatus](xref:botframework-connector.TokenStatus) objects retrieved.
|
|
*/
|
|
getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string): Promise<TokenStatus[]>;
|
|
getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenStatus[]>;
|
|
/**
|
|
* Asynchronously signs out the user from the token server.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param connectionName The name of the auth connection to use.
|
|
* @param resourceUrls The list of resource URLs to retrieve tokens for.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
* @returns A map of the [TokenResponse](xref:botframework-schema.TokenResponse) objects by resource URL.
|
|
*/
|
|
getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[]): Promise<{
|
|
[propertyName: string]: TokenResponse;
|
|
}>;
|
|
getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[], oAuthAppCredentials?: CoreAppCredentials): Promise<{
|
|
[propertyName: string]: TokenResponse;
|
|
}>;
|
|
/**
|
|
* Asynchronously Get the raw signin resource to be sent to the user for signin.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param connectionName The name of the auth connection to use.
|
|
* @param userId The user id that will be associated with the token.
|
|
* @param finalRedirect The final URL that the OAuth flow will redirect to.
|
|
* @param appCredentials Optional. The CoreAppCredentials for OAuth.
|
|
* @returns The [BotSignInGetSignInResourceResponse](xref:botframework-connector.BotSignInGetSignInResourceResponse) object.
|
|
*/
|
|
getSignInResource(context: TurnContext, connectionName: string, userId?: string, finalRedirect?: string, appCredentials?: CoreAppCredentials): Promise<SignInUrlResponse>;
|
|
/**
|
|
* Asynchronously Performs a token exchange operation such as for single sign-on.
|
|
*
|
|
* @param context Context for the current turn of conversation with the user.
|
|
* @param connectionName Name of the auth connection to use.
|
|
* @param userId The user id that will be associated with the token.
|
|
* @param tokenExchangeRequest The exchange request details, either a token to exchange or a uri to exchange.
|
|
* @param appCredentials Optional. The CoreAppCredentials for OAuth.
|
|
*/
|
|
exchangeToken(context: TurnContext, connectionName: string, userId: string, tokenExchangeRequest: TokenExchangeRequest, appCredentials?: CoreAppCredentials): Promise<TokenResponse>;
|
|
/**
|
|
* Asynchronously sends an emulated OAuth card for a channel.
|
|
*
|
|
* This method supports the framework and is not intended to be called directly for your code.
|
|
*
|
|
* @param contextOrServiceUrl The URL of the emulator.
|
|
* @param emulate `true` to send an emulated OAuth card to the emulator; or `false` to not send the card.
|
|
* @remarks
|
|
* When testing a bot in the Bot Framework Emulator, this method can emulate the OAuth card interaction.
|
|
*/
|
|
emulateOAuthCards(contextOrServiceUrl: TurnContext | string, emulate: boolean): Promise<void>;
|
|
/**
|
|
* Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.
|
|
*
|
|
* @param req An Express or Restify style request object.
|
|
* @param res An Express or Restify style response object.
|
|
* @param logic The function to call at the end of the middleware pipeline.
|
|
* @remarks
|
|
* This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:
|
|
*
|
|
* 1. Parses and authenticates an incoming request.
|
|
* - The activity is read from the body of the incoming request. An error will be returned
|
|
* if the activity can't be parsed.
|
|
* - The identity of the sender is authenticated as either the Emulator or a valid Microsoft
|
|
* server, using the bot's `appId` and `appPassword`. The request is rejected if the sender's
|
|
* identity is not verified.
|
|
* 1. Creates a [TurnContext](xref:botbuilder-core.TurnContext) object for the received activity.
|
|
* - This object is wrapped with a [revocable proxy](https://www.ecma-international.org/ecma-262/6.0/#sec-proxy.revocable).
|
|
* - When this method completes, the proxy is revoked.
|
|
* 1. Sends the turn context through the adapter's middleware pipeline.
|
|
* 1. Sends the turn context to the `logic` function.
|
|
* - The bot may perform additional routing or processing at this time.
|
|
* Returning a promise (or providing an `async` handler) will cause the adapter to wait for any asynchronous operations to complete.
|
|
* - After the `logic` function completes, the promise chain set up by the middleware is resolved.
|
|
*
|
|
* > [!TIP]
|
|
* > If you see the error `TypeError: Cannot perform 'set' on a proxy that has been revoked`
|
|
* > in your bot's console output, the likely cause is that an async function was used
|
|
* > without using the `await` keyword. Make sure all async functions use await!
|
|
*
|
|
* Middleware can _short circuit_ a turn. When this happens, subsequent middleware and the
|
|
* `logic` function is not called; however, all middleware prior to this point still run to completion.
|
|
* For more information about the middleware pipeline, see the
|
|
* [how bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
|
* [middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware) articles.
|
|
* Use the adapter's [use](xref:botbuilder-core.BotAdapter.use) method to add middleware to the adapter.
|
|
*
|
|
* For example:
|
|
* ```JavaScript
|
|
* server.post('/api/messages', (req, res) => {
|
|
* // Route received request to adapter for processing
|
|
* adapter.processActivity(req, res, async (context) => {
|
|
* // Process any messages received
|
|
* if (context.activity.type === ActivityTypes.Message) {
|
|
* await context.sendActivity(`Hello World`);
|
|
* }
|
|
* });
|
|
* });
|
|
* ```
|
|
*/
|
|
processActivity(req: WebRequest, res: WebResponse, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
|
/**
|
|
* Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.
|
|
*
|
|
* Use [CloudAdapter.processActivityDirect] instead.
|
|
*
|
|
* @param activity The activity to process.
|
|
* @param logic The function to call at the end of the middleware pipeline.
|
|
* @remarks
|
|
* This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:
|
|
*
|
|
* 1. Creates a [TurnContext](xref:botbuilder-core.TurnContext) object for the received activity.
|
|
* - This object is wrapped with a [revocable proxy](https://www.ecma-international.org/ecma-262/6.0/#sec-proxy.revocable).
|
|
* - When this method completes, the proxy is revoked.
|
|
* 1. Sends the turn context through the adapter's middleware pipeline.
|
|
* 1. Sends the turn context to the `logic` function.
|
|
* - The bot may perform additional routing or processing at this time.
|
|
* Returning a promise (or providing an `async` handler) will cause the adapter to wait for any asynchronous operations to complete.
|
|
* - After the `logic` function completes, the promise chain set up by the middleware is resolved.
|
|
*
|
|
* Middleware can _short circuit_ a turn. When this happens, subsequent middleware and the
|
|
* `logic` function is not called; however, all middleware prior to this point still run to completion.
|
|
* For more information about the middleware pipeline, see the
|
|
* [how bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
|
* [middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware) articles.
|
|
* Use the adapter's [use](xref:botbuilder-core.BotAdapter.use) method to add middleware to the adapter.
|
|
*/
|
|
processActivityDirect(activity: Activity, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
|
/**
|
|
* Asynchronously sends a set of outgoing activities to a channel server.
|
|
*
|
|
* This method supports the framework and is not intended to be called directly for your code.
|
|
* Use the turn context's [sendActivity](xref:botbuilder-core.TurnContext.sendActivity) or
|
|
* [sendActivities](xref:botbuilder-core.TurnContext.sendActivities) method from your bot code.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param activities The activities to send.
|
|
* @returns An array of [ResourceResponse](xref:)
|
|
* @remarks
|
|
* The activities will be sent one after another in the order in which they're received. A
|
|
* response object will be returned for each sent activity. For `message` activities this will
|
|
* contain the ID of the delivered message.
|
|
*/
|
|
sendActivities(context: TurnContext, activities: Partial<Activity>[]): Promise<ResourceResponse[]>;
|
|
/**
|
|
* Asynchronously replaces a previous activity with an updated version.
|
|
*
|
|
* This interface supports the framework and is not intended to be called directly for your code.
|
|
* Use [TurnContext.updateActivity](xref:botbuilder-core.TurnContext.updateActivity) to update
|
|
* an activity from your bot code.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @param activity The updated version of the activity to replace.
|
|
* @returns A `Promise` representing the [ResourceResponse](xref:botframework-schema.ResourceResponse) for the operation.
|
|
* @remarks
|
|
* Not all channels support this operation. For channels that don't, this call may throw an exception.
|
|
*/
|
|
updateActivity(context: TurnContext, activity: Partial<Activity>): Promise<ResourceResponse | void>;
|
|
/**
|
|
* Creates a connector client.
|
|
*
|
|
* @param serviceUrl The client's service URL.
|
|
* @returns The [ConnectorClient](xref:botbuilder-connector.ConnectorClient) instance.
|
|
* @remarks
|
|
* Override this in a derived class to create a mock connector client for unit testing.
|
|
*/
|
|
createConnectorClient(serviceUrl: string): ConnectorClient;
|
|
/**
|
|
* Create a ConnectorClient with a ClaimsIdentity.
|
|
*
|
|
* @remarks
|
|
* If the ClaimsIdentity contains the claims for a Skills request, create a ConnectorClient for use with Skills.
|
|
* Derives the correct audience from the ClaimsIdentity, or the instance's credentials property.
|
|
* @param serviceUrl The client's service URL.
|
|
* @param identity ClaimsIdentity
|
|
*/
|
|
createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity): Promise<ConnectorClient>;
|
|
/**
|
|
* Create a ConnectorClient with a ClaimsIdentity and an explicit audience.
|
|
*
|
|
* @remarks
|
|
* If the trimmed audience is not a non-zero length string, the audience will be derived from the ClaimsIdentity or
|
|
* the instance's credentials property.
|
|
* @param serviceUrl The client's service URL.
|
|
* @param identity ClaimsIdentity
|
|
* @param audience The recipient of the ConnectorClient's messages. Normally the Bot Framework Channel Service or the AppId of another bot.
|
|
*/
|
|
createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity, audience: string): Promise<ConnectorClient>;
|
|
private createConnectorClientInternal;
|
|
private getClientOptions;
|
|
private getOrCreateConnectorClient;
|
|
/**
|
|
* Returns the correct [OAuthScope](xref:botframework-connector.AppCredentials.OAuthScope) for [AppCredentials](xref:botframework-connector.AppCredentials).
|
|
*
|
|
* @param botAppId The bot's AppId.
|
|
* @param claims The [Claim](xref:botbuilder-connector.Claim) list to check.
|
|
* @returns The current credentials' OAuthScope.
|
|
*/
|
|
private getOAuthScope;
|
|
/**
|
|
*
|
|
* @remarks
|
|
* When building credentials for bot-to-bot communication, oAuthScope must be passed in.
|
|
* @param appId The application id.
|
|
* @param oAuthScope The optional OAuth scope.
|
|
* @returns The app credentials to be used to acquire tokens.
|
|
*/
|
|
protected buildCredentials(appId: string, oAuthScope?: string): Promise<AppCredentials>;
|
|
/**
|
|
* Creates an OAuth API client.
|
|
*
|
|
* @param serviceUrl The client's service URL.
|
|
* @param oAuthAppCredentials AppCredentials for OAuth.
|
|
* @remarks
|
|
* Override this in a derived class to create a mock OAuth API client for unit testing.
|
|
*/
|
|
protected createTokenApiClient(serviceUrl: string, oAuthAppCredentials?: CoreAppCredentials): TokenApiClient;
|
|
/**
|
|
* Allows for the overriding of authentication in unit tests.
|
|
*
|
|
* @param request Received request.
|
|
* @param authHeader Received authentication header.
|
|
*/
|
|
protected authenticateRequest(request: Partial<Activity>, authHeader: string): Promise<void>;
|
|
/**
|
|
* @ignore
|
|
* @private
|
|
* Returns the actual ClaimsIdentity from the JwtTokenValidation.authenticateRequest() call.
|
|
* @remarks
|
|
* This method is used instead of authenticateRequest() in processActivity() to obtain the ClaimsIdentity for caching in the TurnContext.turnState.
|
|
*
|
|
* @param request Received request.
|
|
* @param authHeader Received authentication header.
|
|
*/
|
|
private authenticateRequestInternal;
|
|
/**
|
|
* Generates the CallerId property for the activity based on
|
|
* https://github.com/microsoft/botframework-obi/blob/main/protocols/botframework-activity/botframework-activity.md#appendix-v---caller-id-values.
|
|
*
|
|
* @param identity The inbound claims.
|
|
* @returns {Promise<string>} a promise representing the generated callerId.
|
|
*/
|
|
private generateCallerId;
|
|
/**
|
|
* Gets the OAuth API endpoint.
|
|
*
|
|
* @param contextOrServiceUrl The URL of the channel server to query or
|
|
* a [TurnContext](xref:botbuilder-core.TurnContext). For a turn context, the context's
|
|
* [activity](xref:botbuilder-core.TurnContext.activity).[serviceUrl](xref:botframework-schema.Activity.serviceUrl)
|
|
* is used for the URL.
|
|
* @returns The endpoint used for the API requests.
|
|
* @remarks
|
|
* Override this in a derived class to create a mock OAuth API endpoint for unit testing.
|
|
*/
|
|
protected oauthApiUrl(contextOrServiceUrl: TurnContext | string): string;
|
|
/**
|
|
* Checks the environment and can set a flag to emulate OAuth cards.
|
|
*
|
|
* @param context The context object for the turn.
|
|
* @remarks
|
|
* Override this in a derived class to control how OAuth cards are emulated for unit testing.
|
|
*/
|
|
protected checkEmulatingOAuthCards(context: TurnContext): void;
|
|
/**
|
|
* Creates a turn context.
|
|
*
|
|
* @param request An incoming request body.
|
|
* @returns A new [TurnContext](xref:botbuilder-core.TurnContext) instance.
|
|
* @remarks
|
|
* Override this in a derived class to modify how the adapter creates a turn context.
|
|
*/
|
|
protected createContext(request: Partial<Activity>): TurnContext;
|
|
/**
|
|
* Checks the validity of the request and attempts to map it the correct virtual endpoint,
|
|
* then generates and returns a response if appropriate.
|
|
*
|
|
* @param request A ReceiveRequest from the connected channel.
|
|
* @returns A response created by the BotAdapter to be sent to the client that originated the request.
|
|
*/
|
|
processRequest(request: IReceiveRequest): Promise<StreamingResponse>;
|
|
/**
|
|
* Process a web request by applying a logic function.
|
|
*
|
|
* @param req An incoming HTTP [Request](xref:botbuilder.Request)
|
|
* @param res The corresponding HTTP [Response](xref:botbuilder.Response)
|
|
* @param logic The logic function to apply
|
|
* @returns a promise representing the asynchronous operation.
|
|
*/
|
|
process(req: Request, res: Response, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Handle a web socket connection by applying a logic function to
|
|
* each streaming request.
|
|
*
|
|
* @param req An incoming HTTP [Request](xref:botbuilder.Request)
|
|
* @param socket The corresponding [INodeSocket](xref:botframework-streaming.INodeSocket)
|
|
* @param head The corresponding [INodeBuffer](xref:botframework-streaming.INodeBuffer)
|
|
* @param logic The logic function to apply
|
|
* @returns a promise representing the asynchronous operation.
|
|
*/
|
|
process(req: Request, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
|
/**
|
|
* Connects the handler to a Named Pipe server and begins listening for incoming requests.
|
|
*
|
|
* @param logic The logic that will handle incoming requests.
|
|
* @param pipeName The name of the named pipe to use when creating the server.
|
|
* @param retryCount Number of times to attempt to bind incoming and outgoing pipe
|
|
* @param onListen Optional callback that fires once when server is listening on both incoming and outgoing pipe
|
|
*/
|
|
useNamedPipe(logic: (context: TurnContext) => Promise<any>, pipeName?: string, retryCount?: number, onListen?: () => void): Promise<void>;
|
|
/**
|
|
* Process the initial request to establish a long lived connection via a streaming server.
|
|
*
|
|
* @param req The connection request.
|
|
* @param socket The raw socket connection between the bot (server) and channel/caller (client).
|
|
* @param head The first packet of the upgraded stream.
|
|
* @param logic The logic that handles incoming streaming requests for the lifetime of the WebSocket connection.
|
|
*/
|
|
useWebSocket(req: WebRequest, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
|
private startNamedPipeServer;
|
|
private authenticateConnection;
|
|
/**
|
|
* Connects the handler to a WebSocket server and begins listening for incoming requests.
|
|
*
|
|
* @param socket The socket to use when creating the server.
|
|
*/
|
|
private startWebSocket;
|
|
private readRequestBodyAsString;
|
|
private handleVersionRequest;
|
|
/**
|
|
* Determine if the serviceUrl was sent via an Http/Https connection or Streaming
|
|
* This can be determined by looking at the ServiceUrl property:
|
|
* (1) All channels that send messages via http/https are not streaming
|
|
* (2) Channels that send messages via streaming have a ServiceUrl that does not begin with http/https.
|
|
*
|
|
* @param serviceUrl the serviceUrl provided in the resquest.
|
|
* @returns True if the serviceUrl is a streaming url, otherwise false.
|
|
*/
|
|
private static isStreamingServiceUrl;
|
|
}
|
|
//# sourceMappingURL=botFrameworkAdapter.d.ts.map
|