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