1 | /**
|
2 | * @module botbuilder
|
3 | */
|
4 | /**
|
5 | * Copyright (c) Microsoft Corporation. All rights reserved.
|
6 | * Licensed under the MIT License.
|
7 | */
|
8 | import { Activity, CoreAppCredentials, BotAdapter, ChannelAccount, ConversationReference, ConversationsResult, ExtendedUserTokenProvider, ResourceResponse, TokenResponse, TurnContext, HealthCheckResponse } from 'botbuilder-core';
|
9 | import { AuthenticationConfiguration, ClaimsIdentity, ConnectorClient, ConnectorClientOptions, AppCredentials, SimpleCredentialProvider, TokenApiClient, TokenStatus, SignInUrlResponse, TokenExchangeRequest } from 'botframework-connector';
|
10 | import { INodeBuffer, INodeSocket, IReceiveRequest, NodeWebSocketFactoryBase, RequestHandler, StreamingResponse } from 'botframework-streaming';
|
11 | import { ConnectorClientBuilder, WebRequest, WebResponse } from './interfaces';
|
12 | /**
|
13 | * Contains settings used to configure a [BotFrameworkAdapter](xref:botbuilder.BotFrameworkAdapter) instance.
|
14 | */
|
15 | export interface BotFrameworkAdapterSettings {
|
16 | /**
|
17 | * The ID assigned to your bot in the [Bot Framework Portal](https://dev.botframework.com/).
|
18 | */
|
19 | appId: string;
|
20 | /**
|
21 | * The password assigned to your bot in the [Bot Framework Portal](https://dev.botframework.com/).
|
22 | */
|
23 | appPassword: string;
|
24 | /**
|
25 | * Optional. The tenant to acquire the bot-to-channel token from.
|
26 | */
|
27 | channelAuthTenant?: string;
|
28 | /**
|
29 | * Optional. The OAuth API endpoint for your bot to use.
|
30 | */
|
31 | oAuthEndpoint?: string;
|
32 | /**
|
33 | * Optional. The OpenID Metadata endpoint for your bot to use.
|
34 | */
|
35 | openIdMetadata?: string;
|
36 | /**
|
37 | * Optional. The channel service option for this bot to validate connections from Azure or other channel locations.
|
38 | */
|
39 | channelService?: string;
|
40 | /**
|
41 | * Optional. Used to pass in a NodeWebSocketFactoryBase instance.
|
42 | */
|
43 | webSocketFactory?: NodeWebSocketFactoryBase;
|
44 | /**
|
45 | * Optional. Certificate thumbprint to authenticate the appId against AAD.
|
46 | */
|
47 | certificateThumbprint?: string;
|
48 | /**
|
49 | * Optional. Certificate key to authenticate the appId against AAD.
|
50 | */
|
51 | certificatePrivateKey?: string;
|
52 | /**
|
53 | * Optional. Used to require specific endorsements and verify claims. Recommended for Skills.
|
54 | */
|
55 | authConfig?: AuthenticationConfiguration;
|
56 | /**
|
57 | * Optional. Used when creating new ConnectorClients.
|
58 | */
|
59 | clientOptions?: ConnectorClientOptions;
|
60 | }
|
61 | export declare const USER_AGENT: string;
|
62 | /**
|
63 | * A [BotAdapter](xref:botbuilder-core.BotAdapter) that can connect a bot to a service endpoint.
|
64 | * Implements [IUserTokenProvider](xref:botbuilder-core.IUserTokenProvider).
|
65 | *
|
66 | * @remarks
|
67 | * The bot adapter encapsulates authentication processes and sends activities to and receives
|
68 | * activities from the Bot Connector Service. When your bot receives an activity, the adapter
|
69 | * creates a turn context object, passes it to your bot application logic, and sends responses
|
70 | * back to the user's channel.
|
71 | *
|
72 | * The adapter processes and directs incoming activities in through the bot middleware pipeline to
|
73 | * your bot logic and then back out again. As each activity flows in and out of the bot, each
|
74 | * piece of middleware can inspect or act upon the activity, both before and after the bot logic runs.
|
75 | * Use the [use](xref:botbuilder-core.BotAdapter.use) method to add [Middleware](xref:botbuilder-core.Middleware)
|
76 | * objects to your adapter's middleware collection.
|
77 | *
|
78 | * For more information, see the articles on
|
79 | * [How bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
80 | * [Middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware).
|
81 | *
|
82 | * For example:
|
83 | * ```JavaScript
|
84 | * const { BotFrameworkAdapter } = require('botbuilder');
|
85 | *
|
86 | * const adapter = new BotFrameworkAdapter({
|
87 | * appId: process.env.MicrosoftAppId,
|
88 | * appPassword: process.env.MicrosoftAppPassword
|
89 | * });
|
90 | *
|
91 | * adapter.onTurnError = async (context, error) => {
|
92 | * // Catch-all logic for errors.
|
93 | * };
|
94 | * ```
|
95 | */
|
96 | export declare class BotFrameworkAdapter extends BotAdapter implements ConnectorClientBuilder, ExtendedUserTokenProvider, RequestHandler {
|
97 | readonly ConnectorClientKey: Symbol;
|
98 | readonly TokenApiClientCredentialsKey: Symbol;
|
99 | protected readonly credentials: AppCredentials;
|
100 | protected readonly credentialsProvider: SimpleCredentialProvider;
|
101 | protected readonly settings: BotFrameworkAdapterSettings;
|
102 | private isEmulatingOAuthCards;
|
103 | private logic;
|
104 | private streamingServer;
|
105 | private webSocketFactory;
|
106 | private authConfiguration;
|
107 | /**
|
108 | * Creates a new instance of the [BotFrameworkAdapter](xref:botbuilder.BotFrameworkAdapter) class.
|
109 | *
|
110 | * @param settings Optional. The settings to use for this adapter instance.
|
111 | *
|
112 | * @remarks
|
113 | * If the `settings` parameter does not include
|
114 | * [channelService](xref:botbuilder.BotFrameworkAdapterSettings.channelService) or
|
115 | * [openIdMetadata](xref:botbuilder.BotFrameworkAdapterSettings.openIdMetadata) values, the
|
116 | * constructor checks the process' environment variables for these values. These values may be
|
117 | * set when a bot is provisioned on Azure and if so are required for the bot to work properly
|
118 | * in the global cloud or in a national cloud.
|
119 | *
|
120 | * The [BotFrameworkAdapterSettings](xref:botbuilder.BotFrameworkAdapterSettings) class defines
|
121 | * the available adapter settings.
|
122 | */
|
123 | constructor(settings?: Partial<BotFrameworkAdapterSettings>);
|
124 | /**
|
125 | * Used in streaming contexts to check if the streaming connection is still open for the bot to send activities.
|
126 | */
|
127 | readonly isStreamingConnectionOpen: boolean;
|
128 | /**
|
129 | * Asynchronously resumes a conversation with a user, possibly after some time has gone by.
|
130 | *
|
131 | * @param reference A reference to the conversation to continue.
|
132 | * @param oAuthScope The intended recipient of any sent activities.
|
133 | * @param logic The asynchronous method to call after the adapter middleware runs.
|
134 | *
|
135 | * @remarks
|
136 | * This is often referred to as a _proactive notification_, the bot can proactively
|
137 | * send a message to a conversation or user without waiting for an incoming message.
|
138 | * For example, a bot can use this method to send notifications or coupons to a user.
|
139 | *
|
140 | * To send a proactive message:
|
141 | * 1. Save a copy of a [ConversationReference](xref:botframework-schema.ConversationReference)
|
142 | * from an incoming activity. For example, you can store the conversation reference in a database.
|
143 | * 1. Call this method to resume the conversation at a later time. Use the saved reference to access the conversation.
|
144 | * 1. On success, the adapter generates a [TurnContext](xref:botbuilder-core.TurnContext) object and calls the `logic` function handler.
|
145 | * Use the `logic` function to send the proactive message.
|
146 | *
|
147 | * To copy the reference from any incoming activity in the conversation, use the
|
148 | * [TurnContext.getConversationReference](xref:botbuilder-core.TurnContext.getConversationReference) method.
|
149 | *
|
150 | * This method is similar to the [processActivity](xref:botbuilder.BotFrameworkAdapter.processActivity) method.
|
151 | * The adapter creates a [TurnContext](xref:botbuilder-core.TurnContext) and routes it through
|
152 | * its middleware before calling the `logic` handler. The created activity will have a
|
153 | * [type](xref:botframework-schema.Activity.type) of 'event' and a
|
154 | * [name](xref:botframework-schema.Activity.name) of 'continueConversation'.
|
155 | *
|
156 | * For example:
|
157 | * ```JavaScript
|
158 | * server.post('/api/notifyUser', async (req, res) => {
|
159 | * // Lookup previously saved conversation reference.
|
160 | * const reference = await findReference(req.body.refId);
|
161 | *
|
162 | * // Proactively notify the user.
|
163 | * if (reference) {
|
164 | * await adapter.continueConversation(reference, async (context) => {
|
165 | * await context.sendActivity(req.body.message);
|
166 | * });
|
167 | * res.send(200);
|
168 | * } else {
|
169 | * res.send(404);
|
170 | * }
|
171 | * });
|
172 | * ```
|
173 | */
|
174 | continueConversation(reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
175 | continueConversation(reference: Partial<ConversationReference>, oAuthScope: string, logic: (context: TurnContext) => Promise<void>): Promise<void>;
|
176 | /**
|
177 | * Asynchronously creates and starts a conversation with a user on a channel.
|
178 | *
|
179 | * @param reference A reference for the conversation to create.
|
180 | * @param logic The asynchronous method to call after the adapter middleware runs.
|
181 | *
|
182 | * @remarks
|
183 | * To use this method, you need both the bot's and the user's account information on a channel.
|
184 | * The Bot Connector service supports the creating of group conversations; however, this
|
185 | * method and most channels only support initiating a direct message (non-group) conversation.
|
186 | *
|
187 | * To create and start a new conversation:
|
188 | * 1. Get a copy of a [ConversationReference](xref:botframework-schema.ConversationReference) from an incoming activity.
|
189 | * 1. Set the [user](xref:botframework-schema.ConversationReference.user) property to the
|
190 | * [ChannelAccount](xref:botframework-schema.ChannelAccount) value for the intended recipient.
|
191 | * 1. Call this method to request that the channel create a new conversation with the specified user.
|
192 | * 1. On success, the adapter generates a turn context and calls the `logic` function handler.
|
193 | *
|
194 | * To get the initial reference, use the
|
195 | * [TurnContext.getConversationReference](xref:botbuilder-core.TurnContext.getConversationReference)
|
196 | * method on any incoming activity in the conversation.
|
197 | *
|
198 | * If the channel establishes the conversation, the generated event activity's
|
199 | * [conversation](xref:botframework-schema.Activity.conversation) property will contain the
|
200 | * ID of the new conversation.
|
201 | *
|
202 | * This method is similar to the [processActivity](xref:botbuilder.BotFrameworkAdapter.processActivity) method.
|
203 | * The adapter creates a [TurnContext](xref:botbuilder-core.TurnContext) and routes it through
|
204 | * middleware before calling the `logic` handler. The created activity will have a
|
205 | * [type](xref:botframework-schema.Activity.type) of 'event' and a
|
206 | * [name](xref:botframework-schema.Activity.name) of 'createConversation'.
|
207 | *
|
208 | * For example:
|
209 | * ```JavaScript
|
210 | * // Get group members conversation reference
|
211 | * const reference = TurnContext.getConversationReference(context.activity);
|
212 | *
|
213 | * // ...
|
214 | * // Start a new conversation with the user
|
215 | * await adapter.createConversation(reference, async (ctx) => {
|
216 | * await ctx.sendActivity(`Hi (in private)`);
|
217 | * });
|
218 | * ```
|
219 | */
|
220 | createConversation(reference: Partial<ConversationReference>, logic?: (context: TurnContext) => Promise<void>): Promise<void>;
|
221 | /**
|
222 | * Asynchronously deletes an existing activity.
|
223 | *
|
224 | * This interface supports the framework and is not intended to be called directly for your code.
|
225 | * Use [TurnContext.deleteActivity](xref:botbuilder-core.TurnContext.deleteActivity) to delete
|
226 | * an activity from your bot code.
|
227 | *
|
228 | * @param context The context object for the turn.
|
229 | * @param reference Conversation reference information for the activity to delete.
|
230 | *
|
231 | * @remarks
|
232 | * Not all channels support this operation. For channels that don't, this call may throw an exception.
|
233 | */
|
234 | deleteActivity(context: TurnContext, reference: Partial<ConversationReference>): Promise<void>;
|
235 | /**
|
236 | * Asynchronously removes a member from the current conversation.
|
237 | *
|
238 | * @param context The context object for the turn.
|
239 | * @param memberId The ID of the member to remove from the conversation.
|
240 | *
|
241 | * @remarks
|
242 | * Remove a member's identity information from the conversation.
|
243 | *
|
244 | * Not all channels support this operation. For channels that don't, this call may throw an exception.
|
245 | */
|
246 | deleteConversationMember(context: TurnContext, memberId: string): Promise<void>;
|
247 | /**
|
248 | * Asynchronously lists the members of a given activity.
|
249 | *
|
250 | * @param context The context object for the turn.
|
251 | * @param activityId Optional. The ID of the activity to get the members of. If not specified, the current activity ID is used.
|
252 | *
|
253 | * @returns An array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
254 | * the users involved in a given activity.
|
255 | *
|
256 | * @remarks
|
257 | * Returns an array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
258 | * the users involved in a given activity.
|
259 | *
|
260 | * This is different from [getConversationMembers](xref:botbuilder.BotFrameworkAdapter.getConversationMembers)
|
261 | * in that it will return only those users directly involved in the activity, not all members of the conversation.
|
262 | */
|
263 | getActivityMembers(context: TurnContext, activityId?: string): Promise<ChannelAccount[]>;
|
264 | /**
|
265 | * Asynchronously lists the members of the current conversation.
|
266 | *
|
267 | * @param context The context object for the turn.
|
268 | *
|
269 | * @returns An array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
270 | * all users currently involved in a conversation.
|
271 | *
|
272 | * @remarks
|
273 | * Returns an array of [ChannelAccount](xref:botframework-schema.ChannelAccount) objects for
|
274 | * all users currently involved in a conversation.
|
275 | *
|
276 | * This is different from [getActivityMembers](xref:botbuilder.BotFrameworkAdapter.getActivityMembers)
|
277 | * in that it will return all members of the conversation, not just those directly involved in a specific activity.
|
278 | */
|
279 | getConversationMembers(context: TurnContext): Promise<ChannelAccount[]>;
|
280 | /**
|
281 | * For the specified channel, asynchronously gets a page of the conversations in which this bot has participated.
|
282 | *
|
283 | * @param contextOrServiceUrl The URL of the channel server to query or a
|
284 | * [TurnContext](xref:botbuilder-core.TurnContext) object from a conversation on the channel.
|
285 | * @param continuationToken Optional. The continuation token from the previous page of results.
|
286 | * Omit this parameter or use `undefined` to retrieve the first page of results.
|
287 | *
|
288 | * @returns A [ConversationsResult](xref:botframework-schema.ConversationsResult) object containing a page of results
|
289 | * and a continuation token.
|
290 | *
|
291 | * @remarks
|
292 | * The the return value's [conversations](xref:botframework-schema.ConversationsResult.conversations) property contains a page of
|
293 | * [ConversationMembers](xref:botframework-schema.ConversationMembers) objects. Each object's
|
294 | * [id](xref:botframework-schema.ConversationMembers.id) is the ID of a conversation in which the bot has participated on this channel.
|
295 | * This method can be called from outside the context of a conversation, as only the bot's service URL and credentials are required.
|
296 | *
|
297 | * The channel batches results in pages. If the result's
|
298 | * [continuationToken](xref:botframework-schema.ConversationsResult.continuationToken) property is not empty, then
|
299 | * there are more pages to get. Use the returned token to get the next page of results.
|
300 | * If the `contextOrServiceUrl` parameter is a [TurnContext](xref:botbuilder-core.TurnContext), the URL of the channel server is
|
301 | * retrieved from
|
302 | * `contextOrServiceUrl`.[activity](xref:botbuilder-core.TurnContext.activity).[serviceUrl](xref:botframework-schema.Activity.serviceUrl).
|
303 | */
|
304 | getConversations(contextOrServiceUrl: TurnContext | string, continuationToken?: string): Promise<ConversationsResult>;
|
305 | /**
|
306 | * Asynchronously attempts to retrieve the token for a user that's in a login flow.
|
307 | *
|
308 | * @param context The context object for the turn.
|
309 | * @param connectionName The name of the auth connection to use.
|
310 | * @param magicCode Optional. The validation code the user entered.
|
311 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
312 | *
|
313 | * @returns A [TokenResponse](xref:botframework-schema.TokenResponse) object that contains the user token.
|
314 | */
|
315 | getUserToken(context: TurnContext, connectionName: string, magicCode?: string): Promise<TokenResponse>;
|
316 | getUserToken(context: TurnContext, connectionName: string, magicCode?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenResponse>;
|
317 | /**
|
318 | * Asynchronously signs out the user from the token server.
|
319 | *
|
320 | * @param context The context object for the turn.
|
321 | * @param connectionName The name of the auth connection to use.
|
322 | * @param userId The ID of user to sign out.
|
323 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
324 | */
|
325 | signOutUser(context: TurnContext, connectionName?: string, userId?: string): Promise<void>;
|
326 | signOutUser(context: TurnContext, connectionName?: string, userId?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<void>;
|
327 | /**
|
328 | * Asynchronously gets a sign-in link from the token server that can be sent as part
|
329 | * of a [SigninCard](xref:botframework-schema.SigninCard).
|
330 | *
|
331 | * @param context The context object for the turn.
|
332 | * @param connectionName The name of the auth connection to use.
|
333 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
334 | * @param userId The user id that will be associated with the token.
|
335 | * @param finalRedirect The final URL that the OAuth flow will redirect to.
|
336 | */
|
337 | getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: AppCredentials, userId?: string, finalRedirect?: string): Promise<string>;
|
338 | getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: CoreAppCredentials, userId?: string, finalRedirect?: string): Promise<string>;
|
339 | /**
|
340 | * Asynchronously retrieves the token status for each configured connection for the given user.
|
341 | *
|
342 | * @param context The context object for the turn.
|
343 | * @param userId Optional. If present, the ID of the user to retrieve the token status for.
|
344 | * Otherwise, the ID of the user who sent the current activity is used.
|
345 | * @param includeFilter Optional. A comma-separated list of connection's to include. If present,
|
346 | * the `includeFilter` parameter limits the tokens this method returns.
|
347 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
348 | *
|
349 | * @returns The [TokenStatus](xref:botframework-connector.TokenStatus) objects retrieved.
|
350 | */
|
351 | getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string): Promise<TokenStatus[]>;
|
352 | getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenStatus[]>;
|
353 | /**
|
354 | * Asynchronously signs out the user from the token server.
|
355 | *
|
356 | * @param context The context object for the turn.
|
357 | * @param connectionName The name of the auth connection to use.
|
358 | * @param resourceUrls The list of resource URLs to retrieve tokens for.
|
359 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
360 | *
|
361 | * @returns A map of the [TokenResponse](xref:botframework-schema.TokenResponse) objects by resource URL.
|
362 | */
|
363 | getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[]): Promise<{
|
364 | [propertyName: string]: TokenResponse;
|
365 | }>;
|
366 | getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[], oAuthAppCredentials?: CoreAppCredentials): Promise<{
|
367 | [propertyName: string]: TokenResponse;
|
368 | }>;
|
369 | /**
|
370 | * Asynchronously Get the raw signin resource to be sent to the user for signin.
|
371 | *
|
372 | * @param context The context object for the turn.
|
373 | * @param connectionName The name of the auth connection to use.
|
374 | * @param userId The user id that will be associated with the token.
|
375 | * @param finalRedirect The final URL that the OAuth flow will redirect to.
|
376 | *
|
377 | * @returns The [BotSignInGetSignInResourceResponse](xref:botframework-connector.BotSignInGetSignInResourceResponse) object.
|
378 | */
|
379 | getSignInResource(context: TurnContext, connectionName: string, userId?: string, finalRedirect?: string, appCredentials?: CoreAppCredentials): Promise<SignInUrlResponse>;
|
380 | /**
|
381 | * Asynchronously Performs a token exchange operation such as for single sign-on.
|
382 | * @param context Context for the current turn of conversation with the user.
|
383 | * @param connectionName Name of the auth connection to use.
|
384 | * @param userId The user id that will be associated with the token.
|
385 | * @param tokenExchangeRequest The exchange request details, either a token to exchange or a uri to exchange.
|
386 | */
|
387 | exchangeToken(context: TurnContext, connectionName: string, userId: string, tokenExchangeRequest: TokenExchangeRequest, appCredentials?: CoreAppCredentials): Promise<TokenResponse>;
|
388 | /**
|
389 | * Asynchronously sends an emulated OAuth card for a channel.
|
390 | *
|
391 | * This method supports the framework and is not intended to be called directly for your code.
|
392 | *
|
393 | * @param contextOrServiceUrl The URL of the emulator.
|
394 | * @param emulate `true` to send an emulated OAuth card to the emulator; or `false` to not send the card.
|
395 | *
|
396 | * @remarks
|
397 | * When testing a bot in the Bot Framework Emulator, this method can emulate the OAuth card interaction.
|
398 | */
|
399 | emulateOAuthCards(contextOrServiceUrl: TurnContext | string, emulate: boolean): Promise<void>;
|
400 | /**
|
401 | * Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.
|
402 | *
|
403 | * @param req An Express or Restify style request object.
|
404 | * @param res An Express or Restify style response object.
|
405 | * @param logic The function to call at the end of the middleware pipeline.
|
406 | *
|
407 | * @remarks
|
408 | * This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:
|
409 | *
|
410 | * 1. Parses and authenticates an incoming request.
|
411 | * - The activity is read from the body of the incoming request. An error will be returned
|
412 | * if the activity can't be parsed.
|
413 | * - The identity of the sender is authenticated as either the Emulator or a valid Microsoft
|
414 | * server, using the bot's `appId` and `appPassword`. The request is rejected if the sender's
|
415 | * identity is not verified.
|
416 | * 1. Creates a [TurnContext](xref:botbuilder-core.TurnContext) object for the received activity.
|
417 | * - This object is wrapped with a [revocable proxy](https://www.ecma-international.org/ecma-262/6.0/#sec-proxy.revocable).
|
418 | * - When this method completes, the proxy is revoked.
|
419 | * 1. Sends the turn context through the adapter's middleware pipeline.
|
420 | * 1. Sends the turn context to the `logic` function.
|
421 | * - The bot may perform additional routing or processing at this time.
|
422 | * Returning a promise (or providing an `async` handler) will cause the adapter to wait for any asynchronous operations to complete.
|
423 | * - After the `logic` function completes, the promise chain set up by the middleware is resolved.
|
424 | *
|
425 | * > [!TIP]
|
426 | * > If you see the error `TypeError: Cannot perform 'set' on a proxy that has been revoked`
|
427 | * > in your bot's console output, the likely cause is that an async function was used
|
428 | * > without using the `await` keyword. Make sure all async functions use await!
|
429 | *
|
430 | * Middleware can _short circuit_ a turn. When this happens, subsequent middleware and the
|
431 | * `logic` function is not called; however, all middleware prior to this point still run to completion.
|
432 | * For more information about the middleware pipeline, see the
|
433 | * [how bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
434 | * [middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware) articles.
|
435 | * Use the adapter's [use](xref:botbuilder-core.BotAdapter.use) method to add middleware to the adapter.
|
436 | *
|
437 | * For example:
|
438 | * ```JavaScript
|
439 | * server.post('/api/messages', (req, res) => {
|
440 | * // Route received request to adapter for processing
|
441 | * adapter.processActivity(req, res, async (context) => {
|
442 | * // Process any messages received
|
443 | * if (context.activity.type === ActivityTypes.Message) {
|
444 | * await context.sendActivity(`Hello World`);
|
445 | * }
|
446 | * });
|
447 | * });
|
448 | * ```
|
449 | */
|
450 | processActivity(req: WebRequest, res: WebResponse, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
451 | /**
|
452 | * Asynchronously creates a turn context and runs the middleware pipeline for an incoming activity.
|
453 | *
|
454 | * @param activity The activity to process.
|
455 | * @param logic The function to call at the end of the middleware pipeline.
|
456 | *
|
457 | * @remarks
|
458 | * This is the main way a bot receives incoming messages and defines a turn in the conversation. This method:
|
459 | *
|
460 | * 1. Creates a [TurnContext](xref:botbuilder-core.TurnContext) object for the received activity.
|
461 | * - This object is wrapped with a [revocable proxy](https://www.ecma-international.org/ecma-262/6.0/#sec-proxy.revocable).
|
462 | * - When this method completes, the proxy is revoked.
|
463 | * 1. Sends the turn context through the adapter's middleware pipeline.
|
464 | * 1. Sends the turn context to the `logic` function.
|
465 | * - The bot may perform additional routing or processing at this time.
|
466 | * Returning a promise (or providing an `async` handler) will cause the adapter to wait for any asynchronous operations to complete.
|
467 | * - After the `logic` function completes, the promise chain set up by the middleware is resolved.
|
468 | *
|
469 | * Middleware can _short circuit_ a turn. When this happens, subsequent middleware and the
|
470 | * `logic` function is not called; however, all middleware prior to this point still run to completion.
|
471 | * For more information about the middleware pipeline, see the
|
472 | * [how bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
|
473 | * [middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware) articles.
|
474 | * Use the adapter's [use](xref:botbuilder-core.BotAdapter.use) method to add middleware to the adapter.
|
475 | */
|
476 | processActivityDirect(activity: Activity, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
477 | /**
|
478 | * Asynchronously sends a set of outgoing activities to a channel server.
|
479 | *
|
480 | * This method supports the framework and is not intended to be called directly for your code.
|
481 | * Use the turn context's [sendActivity](xref:botbuilder-core.TurnContext.sendActivity) or
|
482 | * [sendActivities](xref:botbuilder-core.TurnContext.sendActivities) method from your bot code.
|
483 | *
|
484 | * @param context The context object for the turn.
|
485 | * @param activities The activities to send.
|
486 | *
|
487 | * @returns An array of [ResourceResponse](xref:)
|
488 | *
|
489 | * @remarks
|
490 | * The activities will be sent one after another in the order in which they're received. A
|
491 | * response object will be returned for each sent activity. For `message` activities this will
|
492 | * contain the ID of the delivered message.
|
493 | */
|
494 | sendActivities(context: TurnContext, activities: Partial<Activity>[]): Promise<ResourceResponse[]>;
|
495 | /**
|
496 | * Asynchronously replaces a previous activity with an updated version.
|
497 | *
|
498 | * This interface supports the framework and is not intended to be called directly for your code.
|
499 | * Use [TurnContext.updateActivity](xref:botbuilder-core.TurnContext.updateActivity) to update
|
500 | * an activity from your bot code.
|
501 | *
|
502 | * @param context The context object for the turn.
|
503 | * @param activity The updated version of the activity to replace.
|
504 | *
|
505 | * @remarks
|
506 | * Not all channels support this operation. For channels that don't, this call may throw an exception.
|
507 | */
|
508 | updateActivity(context: TurnContext, activity: Partial<Activity>): Promise<void>;
|
509 | /**
|
510 | * Creates a connector client.
|
511 | *
|
512 | * @param serviceUrl The client's service URL.
|
513 | *
|
514 | * @remarks
|
515 | * Override this in a derived class to create a mock connector client for unit testing.
|
516 | */
|
517 | createConnectorClient(serviceUrl: string): ConnectorClient;
|
518 | /**
|
519 | * Create a ConnectorClient with a ClaimsIdentity.
|
520 | * @remarks
|
521 | * If the ClaimsIdentity contains the claims for a Skills request, create a ConnectorClient for use with Skills.
|
522 | * Derives the correct audience from the ClaimsIdentity, or the instance's credentials property.
|
523 | * @param serviceUrl
|
524 | * @param identity ClaimsIdentity
|
525 | */
|
526 | createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity): Promise<ConnectorClient>;
|
527 | /**
|
528 | * Create a ConnectorClient with a ClaimsIdentity and an explicit audience.
|
529 | * @remarks
|
530 | * If the trimmed audience is not a non-zero length string, the audience will be derived from the ClaimsIdentity or
|
531 | * the instance's credentials property.
|
532 | * @param serviceUrl
|
533 | * @param identity ClaimsIdentity
|
534 | * @param audience The recipient of the ConnectorClient's messages. Normally the Bot Framework Channel Service or the AppId of another bot.
|
535 | */
|
536 | createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity, audience: string): Promise<ConnectorClient>;
|
537 | /**
|
538 | * @private
|
539 | * @param serviceUrl The client's service URL.
|
540 | * @param credentials AppCredentials instance to construct the ConnectorClient with.
|
541 | */
|
542 | private createConnectorClientInternal;
|
543 | /**
|
544 | * @private
|
545 | * @param serviceUrl The service URL to use for the new ConnectorClientOptions.
|
546 | * @param httpClient Optional. The @azure/ms-rest-js.HttpClient to use for the new ConnectorClientOptions.
|
547 | */
|
548 | private getClientOptions;
|
549 | /**
|
550 | * @private
|
551 | * Retrieves the ConnectorClient from the TurnContext or creates a new ConnectorClient with the provided serviceUrl and credentials.
|
552 | * @param context
|
553 | * @param serviceUrl
|
554 | * @param credentials
|
555 | */
|
556 | private getOrCreateConnectorClient;
|
557 | private getOAuthScope;
|
558 | /**
|
559 | *
|
560 | * @remarks
|
561 | * When building credentials for bot-to-bot communication, oAuthScope must be passed in.
|
562 | * @param appId
|
563 | * @param oAuthScope
|
564 | */
|
565 | protected buildCredentials(appId: string, oAuthScope?: string): Promise<AppCredentials>;
|
566 | /**
|
567 | * Creates an OAuth API client.
|
568 | *
|
569 | * @param serviceUrl The client's service URL.
|
570 | * @param oAuthAppCredentials AppCredentials for OAuth.
|
571 | *
|
572 | * @remarks
|
573 | * Override this in a derived class to create a mock OAuth API client for unit testing.
|
574 | */
|
575 | protected createTokenApiClient(serviceUrl: string, oAuthAppCredentials?: CoreAppCredentials): TokenApiClient;
|
576 | /**
|
577 | * Allows for the overriding of authentication in unit tests.
|
578 | * @param request Received request.
|
579 | * @param authHeader Received authentication header.
|
580 | */
|
581 | protected authenticateRequest(request: Partial<Activity>, authHeader: string): Promise<void>;
|
582 | /**
|
583 | * @ignore
|
584 | * @private
|
585 | * Returns the actual ClaimsIdentity from the JwtTokenValidation.authenticateRequest() call.
|
586 | * @remarks
|
587 | * This method is used instead of authenticateRequest() in processActivity() to obtain the ClaimsIdentity for caching in the TurnContext.turnState.
|
588 | *
|
589 | * @param request Received request.
|
590 | * @param authHeader Received authentication header.
|
591 | */
|
592 | private authenticateRequestInternal;
|
593 | /**
|
594 | * Generates the CallerId property for the activity based on
|
595 | * https://github.com/microsoft/botframework-obi/blob/master/protocols/botframework-activity/botframework-activity.md#appendix-v---caller-id-values.
|
596 | * @param identity
|
597 | */
|
598 | private generateCallerId;
|
599 | /**
|
600 | * Gets the OAuth API endpoint.
|
601 | *
|
602 | * @param contextOrServiceUrl The URL of the channel server to query or
|
603 | * a [TurnContext](xref:botbuilder-core.TurnContext). For a turn context, the context's
|
604 | * [activity](xref:botbuilder-core.TurnContext.activity).[serviceUrl](xref:botframework-schema.Activity.serviceUrl)
|
605 | * is used for the URL.
|
606 | *
|
607 | * @remarks
|
608 | * Override this in a derived class to create a mock OAuth API endpoint for unit testing.
|
609 | */
|
610 | protected oauthApiUrl(contextOrServiceUrl: TurnContext | string): string;
|
611 | /**
|
612 | * Checks the environment and can set a flag to emulate OAuth cards.
|
613 | *
|
614 | * @param context The context object for the turn.
|
615 | *
|
616 | * @remarks
|
617 | * Override this in a derived class to control how OAuth cards are emulated for unit testing.
|
618 | */
|
619 | protected checkEmulatingOAuthCards(context: TurnContext): void;
|
620 | /**
|
621 | * Creates a turn context.
|
622 | *
|
623 | * @param request An incoming request body.
|
624 | *
|
625 | * @remarks
|
626 | * Override this in a derived class to modify how the adapter creates a turn context.
|
627 | */
|
628 | protected createContext(request: Partial<Activity>): TurnContext;
|
629 | /**
|
630 | * Checks the validity of the request and attempts to map it the correct virtual endpoint,
|
631 | * then generates and returns a response if appropriate.
|
632 | * @param request A ReceiveRequest from the connected channel.
|
633 | * @returns A response created by the BotAdapter to be sent to the client that originated the request.
|
634 | */
|
635 | processRequest(request: IReceiveRequest): Promise<StreamingResponse>;
|
636 | healthCheck(context: TurnContext): Promise<HealthCheckResponse>;
|
637 | /**
|
638 | * Connects the handler to a Named Pipe server and begins listening for incoming requests.
|
639 | * @param pipeName The name of the named pipe to use when creating the server.
|
640 | * @param logic The logic that will handle incoming requests.
|
641 | */
|
642 | useNamedPipe(logic: (context: TurnContext) => Promise<any>, pipeName?: string): Promise<void>;
|
643 | /**
|
644 | * Process the initial request to establish a long lived connection via a streaming server.
|
645 | * @param req The connection request.
|
646 | * @param socket The raw socket connection between the bot (server) and channel/caller (client).
|
647 | * @param head The first packet of the upgraded stream.
|
648 | * @param logic The logic that handles incoming streaming requests for the lifetime of the WebSocket connection.
|
649 | */
|
650 | useWebSocket(req: WebRequest, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<any>): Promise<void>;
|
651 | private authenticateConnection;
|
652 | /**
|
653 | * Connects the handler to a WebSocket server and begins listening for incoming requests.
|
654 | * @param socket The socket to use when creating the server.
|
655 | */
|
656 | private startWebSocket;
|
657 | private readRequestBodyAsString;
|
658 | private handleVersionRequest;
|
659 | /**
|
660 | * Determine if the serviceUrl was sent via an Http/Https connection or Streaming
|
661 | * This can be determined by looking at the ServiceUrl property:
|
662 | * (1) All channels that send messages via http/https are not streaming
|
663 | * (2) Channels that send messages via streaming have a ServiceUrl that does not begin with http/https.
|
664 | * @param serviceUrl the serviceUrl provided in the resquest.
|
665 | */
|
666 | private static isStreamingServiceUrl;
|
667 | }
|
668 | //# sourceMappingURL=botFrameworkAdapter.d.ts.map |
\ | No newline at end of file |