botbuilder-core
Advanced tools
Comparing version
@@ -16,7 +16,2 @@ /** | ||
* and a user over a specific channel, or set of channels. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```JavaScript | ||
* ``` | ||
*/ | ||
@@ -23,0 +18,0 @@ export declare abstract class BotAdapter { |
@@ -17,7 +17,2 @@ "use strict"; | ||
* and a user over a specific channel, or set of channels. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```JavaScript | ||
* ``` | ||
*/ | ||
@@ -24,0 +19,0 @@ class BotAdapter { |
@@ -28,4 +28,17 @@ import { TurnContext } from './turnContext'; | ||
* A set of `Middleware` plugins. The set itself is middleware so you can easily package up a set | ||
* of middleware that can be composed into a bot with a single `bot.use(mySet)` call or even into | ||
* another middleware set using `set.use(mySet)`. | ||
* of middleware that can be composed into an adapter with a single `adapter.use(mySet)` call or | ||
* even into another middleware set using `set.use(mySet)`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const { MiddlewareSet } = require('botbuilder'); | ||
* | ||
* const set = new MiddlewareSet(); | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
*/ | ||
@@ -35,3 +48,3 @@ export declare class MiddlewareSet implements Middleware { | ||
/** | ||
* Creates a new instance of a MiddlewareSet. | ||
* Creates a new MiddlewareSet instance. | ||
* @param middleware Zero or more middleware handlers(s) to register. | ||
@@ -43,2 +56,12 @@ */ | ||
* Registers middleware handlers(s) with the set. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
* @param middleware One or more middleware handlers(s) to register. | ||
@@ -49,2 +72,10 @@ */ | ||
* Executes a set of middleware in series. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await set.run(context, async (context) => { | ||
* console.log(`Bot Logic`); | ||
* }); | ||
* ``` | ||
* @param context Context for the current turn of conversation with the user. | ||
@@ -51,0 +82,0 @@ * @param next Function to invoke at the end of the middleware chain. |
@@ -7,8 +7,21 @@ "use strict"; | ||
* A set of `Middleware` plugins. The set itself is middleware so you can easily package up a set | ||
* of middleware that can be composed into a bot with a single `bot.use(mySet)` call or even into | ||
* another middleware set using `set.use(mySet)`. | ||
* of middleware that can be composed into an adapter with a single `adapter.use(mySet)` call or | ||
* even into another middleware set using `set.use(mySet)`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const { MiddlewareSet } = require('botbuilder'); | ||
* | ||
* const set = new MiddlewareSet(); | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
*/ | ||
class MiddlewareSet { | ||
/** | ||
* Creates a new instance of a MiddlewareSet. | ||
* Creates a new MiddlewareSet instance. | ||
* @param middleware Zero or more middleware handlers(s) to register. | ||
@@ -25,2 +38,12 @@ */ | ||
* Registers middleware handlers(s) with the set. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
* @param middleware One or more middleware handlers(s) to register. | ||
@@ -44,2 +67,10 @@ */ | ||
* Executes a set of middleware in series. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await set.run(context, async (context) => { | ||
* console.log(`Bot Logic`); | ||
* }); | ||
* ``` | ||
* @param context Context for the current turn of conversation with the user. | ||
@@ -46,0 +77,0 @@ * @param next Function to invoke at the end of the middleware chain. |
@@ -38,9 +38,9 @@ /** | ||
* | ||
* For TypeScript developers the `BotContext` is also exposed as an interface which you can derive | ||
* For TypeScript developers the `TurnContext` is also exposed as an interface which you can derive | ||
* from to better describe the actual shape of the context object being passed around. Middleware | ||
* can potentially extend the context object with additional members so in order to get intellisense | ||
* for those added members you'll need to define them on an interface that extends BotContext: | ||
* for those added members you'll need to define them on an interface that extends TurnContext: | ||
* | ||
* ```JavaScript | ||
* interface MyContext extends BotContext { | ||
* ```JS | ||
* interface MyContext extends TurnContext { | ||
* // Added by UserState middleware. | ||
@@ -53,3 +53,3 @@ * readonly userState: MyUserState; | ||
* | ||
* adapter.processRequest(req, res, (context: MyContext) => { | ||
* adapter.processActivity(req, res, (context: MyContext) => { | ||
* const state = context.conversationState; | ||
@@ -68,3 +68,3 @@ * }); | ||
/** | ||
* Creates a new BotContext instance for a turn of conversation. | ||
* Creates a new TurnContext instance. | ||
* @param adapterOrContext Adapter that constructed the context or a context object to clone. | ||
@@ -76,17 +76,71 @@ * @param request Request being processed. | ||
/** | ||
* Called when this BotContext instance is passed into the constructor of a new BotContext | ||
* instance. | ||
* Called when this TurnContext instance is passed into the constructor of a new TurnContext | ||
* instance. Can be overridden in derived classes. | ||
* @param context The context object to copy private members to. Everything should be copied by reference. | ||
*/ | ||
protected copyTo(context: TurnContext): void; | ||
/** The adapter for this context. */ | ||
/** | ||
* The adapter for this context. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
*/ | ||
readonly adapter: BotAdapter; | ||
/** The received activity. */ | ||
/** | ||
* The received activity. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const utterance = (context.activity.text || '').trim(); | ||
* ``` | ||
*/ | ||
readonly activity: Activity; | ||
/** If `true` at least one response has been sent for the current turn of conversation. */ | ||
/** | ||
* If `true` at least one response has been sent for the current turn of conversation. This is | ||
* primarily useful for determining if a bot should run fallback routing logic. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await routeActivity(context); | ||
* if (!context.responded) { | ||
* await context.sendActivity(`I'm sorry. I didn't understand.`); | ||
* } | ||
* ``` | ||
*/ | ||
responded: boolean; | ||
/** Map of services and other values cached for the lifetime of the turn. */ | ||
/** | ||
* Map of services and other values cached for the lifetime of the turn. Middleware, other | ||
* components, and services will typically use this to cache information that could be asked | ||
* for by a bot multiple times during a turn. The bots logic is free to use this to pass | ||
* information between its own components. | ||
* | ||
* > NOTE: For middleware and third party components, consider using a `Symbol()` for your | ||
* cache key to avoid potential naming collisions with the bots caching and other | ||
* components. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const cart = await loadUsersShoppingCart(context); | ||
* context.services.set('cart', cart); | ||
* ``` | ||
*/ | ||
readonly services: Map<any, any>; | ||
/** | ||
* Sends a single activity or message to the user. | ||
* Sends a single activity or message to the user. This ultimately calls [sendActivities()](#sendactivites) | ||
* and is provided as a convenience to make formating and sending individual activities easier. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivity(`Hello World`); | ||
* ``` | ||
* @param activityOrText Activity or text of a message to send the user. | ||
@@ -104,2 +158,12 @@ * @param speak (Optional) SSML that should be spoken to the user for the message. | ||
* handlers and then passed to `adapter.sendActivities()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivities([ | ||
* { type: 'typing' }, | ||
* { type: 'delay', value: 2000 }, | ||
* { type: 'message', text: 'Hello... How are you?' } | ||
* ]); | ||
* ``` | ||
* @param activities One or more activities to send to the user. | ||
@@ -113,2 +177,12 @@ */ | ||
* before being passed to `adapter.updateActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const update = await approveExpenseReport(matched[1]); | ||
* await context.updateActivity(update); | ||
* } | ||
* ``` | ||
* @param activity New replacement activity. The activity should already have it's ID information populated. | ||
@@ -122,2 +196,12 @@ */ | ||
* [onDeleteActivity](#ondeleteactivity) handlers before being passed to `adapter.deleteActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const savedId = await approveExpenseReport(matched[1]); | ||
* await context.deleteActivity(savedId); | ||
* } | ||
* ``` | ||
* @param idOrReference ID or conversation of the activity being deleted. If an ID is specified the conversation reference information from the current request will be used to delete the activity. | ||
@@ -128,2 +212,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept the sending of activities. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onSendActivities(await (ctx, activities, next) => { | ||
* // Deliver activities | ||
* await next(); | ||
* | ||
* // Log sent messages | ||
* activities.filter(a => a.type === 'message').forEach(a => logSend(a)); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [sendActivity()](#sendactivity) is called. The handler should call `next()` to continue sending of the activities. | ||
@@ -134,2 +230,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being updated. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onUpdateActivities(await (ctx, activity, next) => { | ||
* // Replace activity | ||
* await next(); | ||
* | ||
* // Log update | ||
* logUpdate(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [updateActivity()](#updateactivity) is called. The handler should call `next()` to continue sending of the replacement activity. | ||
@@ -140,2 +248,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being deleted. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onDeleteActivities(await (ctx, reference, next) => { | ||
* // Delete activity | ||
* await next(); | ||
* | ||
* // Log delete | ||
* logDelete(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [deleteActivity()](#deleteactivity) is called. The handler should call `next()` to continue deletion of the activity. | ||
@@ -165,6 +285,6 @@ */ | ||
* ```JavaScript | ||
* // Send a typing indicator without calling any handlers | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* return context.adapter.sendActivity(activity); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
@@ -171,0 +291,0 @@ * @param activity Activity to copy delivery information to. |
@@ -19,9 +19,9 @@ "use strict"; | ||
* | ||
* For TypeScript developers the `BotContext` is also exposed as an interface which you can derive | ||
* For TypeScript developers the `TurnContext` is also exposed as an interface which you can derive | ||
* from to better describe the actual shape of the context object being passed around. Middleware | ||
* can potentially extend the context object with additional members so in order to get intellisense | ||
* for those added members you'll need to define them on an interface that extends BotContext: | ||
* for those added members you'll need to define them on an interface that extends TurnContext: | ||
* | ||
* ```JavaScript | ||
* interface MyContext extends BotContext { | ||
* ```JS | ||
* interface MyContext extends TurnContext { | ||
* // Added by UserState middleware. | ||
@@ -34,3 +34,3 @@ * readonly userState: MyUserState; | ||
* | ||
* adapter.processRequest(req, res, (context: MyContext) => { | ||
* adapter.processActivity(req, res, (context: MyContext) => { | ||
* const state = context.conversationState; | ||
@@ -58,4 +58,4 @@ * }); | ||
/** | ||
* Called when this BotContext instance is passed into the constructor of a new BotContext | ||
* instance. | ||
* Called when this TurnContext instance is passed into the constructor of a new TurnContext | ||
* instance. Can be overridden in derived classes. | ||
* @param context The context object to copy private members to. Everything should be copied by reference. | ||
@@ -68,11 +68,42 @@ */ | ||
} | ||
/** The adapter for this context. */ | ||
/** | ||
* The adapter for this context. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
*/ | ||
get adapter() { | ||
return this._adapter; | ||
} | ||
/** The received activity. */ | ||
/** | ||
* The received activity. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const utterance = (context.activity.text || '').trim(); | ||
* ``` | ||
*/ | ||
get activity() { | ||
return this._activity; | ||
} | ||
/** If `true` at least one response has been sent for the current turn of conversation. */ | ||
/** | ||
* If `true` at least one response has been sent for the current turn of conversation. This is | ||
* primarily useful for determining if a bot should run fallback routing logic. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await routeActivity(context); | ||
* if (!context.responded) { | ||
* await context.sendActivity(`I'm sorry. I didn't understand.`); | ||
* } | ||
* ``` | ||
*/ | ||
get responded() { | ||
@@ -87,3 +118,19 @@ return this._respondedRef.responded; | ||
} | ||
/** Map of services and other values cached for the lifetime of the turn. */ | ||
/** | ||
* Map of services and other values cached for the lifetime of the turn. Middleware, other | ||
* components, and services will typically use this to cache information that could be asked | ||
* for by a bot multiple times during a turn. The bots logic is free to use this to pass | ||
* information between its own components. | ||
* | ||
* > NOTE: For middleware and third party components, consider using a `Symbol()` for your | ||
* cache key to avoid potential naming collisions with the bots caching and other | ||
* components. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const cart = await loadUsersShoppingCart(context); | ||
* context.services.set('cart', cart); | ||
* ``` | ||
*/ | ||
get services() { | ||
@@ -93,3 +140,10 @@ return this._services; | ||
/** | ||
* Sends a single activity or message to the user. | ||
* Sends a single activity or message to the user. This ultimately calls [sendActivities()](#sendactivites) | ||
* and is provided as a convenience to make formating and sending individual activities easier. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivity(`Hello World`); | ||
* ``` | ||
* @param activityOrText Activity or text of a message to send the user. | ||
@@ -122,2 +176,12 @@ * @param speak (Optional) SSML that should be spoken to the user for the message. | ||
* handlers and then passed to `adapter.sendActivities()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivities([ | ||
* { type: 'typing' }, | ||
* { type: 'delay', value: 2000 }, | ||
* { type: 'message', text: 'Hello... How are you?' } | ||
* ]); | ||
* ``` | ||
* @param activities One or more activities to send to the user. | ||
@@ -148,2 +212,12 @@ */ | ||
* before being passed to `adapter.updateActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const update = await approveExpenseReport(matched[1]); | ||
* await context.updateActivity(update); | ||
* } | ||
* ``` | ||
* @param activity New replacement activity. The activity should already have it's ID information populated. | ||
@@ -159,2 +233,12 @@ */ | ||
* [onDeleteActivity](#ondeleteactivity) handlers before being passed to `adapter.deleteActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const savedId = await approveExpenseReport(matched[1]); | ||
* await context.deleteActivity(savedId); | ||
* } | ||
* ``` | ||
* @param idOrReference ID or conversation of the activity being deleted. If an ID is specified the conversation reference information from the current request will be used to delete the activity. | ||
@@ -175,2 +259,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept the sending of activities. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onSendActivities(await (ctx, activities, next) => { | ||
* // Deliver activities | ||
* await next(); | ||
* | ||
* // Log sent messages | ||
* activities.filter(a => a.type === 'message').forEach(a => logSend(a)); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [sendActivity()](#sendactivity) is called. The handler should call `next()` to continue sending of the activities. | ||
@@ -184,2 +280,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being updated. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onUpdateActivities(await (ctx, activity, next) => { | ||
* // Replace activity | ||
* await next(); | ||
* | ||
* // Log update | ||
* logUpdate(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [updateActivity()](#updateactivity) is called. The handler should call `next()` to continue sending of the replacement activity. | ||
@@ -193,2 +301,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being deleted. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onDeleteActivities(await (ctx, reference, next) => { | ||
* // Delete activity | ||
* await next(); | ||
* | ||
* // Log delete | ||
* logDelete(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [deleteActivity()](#deleteactivity) is called. The handler should call `next()` to continue deletion of the activity. | ||
@@ -245,6 +365,6 @@ */ | ||
* ```JavaScript | ||
* // Send a typing indicator without calling any handlers | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* return context.adapter.sendActivity(activity); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
@@ -251,0 +371,0 @@ * @param activity Activity to copy delivery information to. |
@@ -5,3 +5,3 @@ { | ||
"description": "Bot Builder core library. Bot Builder is a toolkit for building rich bots on virtually any platform.", | ||
"version": "4.0.0-m3.0", | ||
"version": "4.0.0-m4.0", | ||
"license": "MIT", | ||
@@ -25,3 +25,3 @@ "keywords": [ | ||
"@types/node": "^9.3.0", | ||
"botframework-schema": "4.0.0-m3.0", | ||
"botframework-schema": "4.0.0-m4.0", | ||
"assert": "^1.4.1" | ||
@@ -28,0 +28,0 @@ }, |
@@ -18,7 +18,2 @@ /** | ||
* and a user over a specific channel, or set of channels. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```JavaScript | ||
* ``` | ||
*/ | ||
@@ -25,0 +20,0 @@ export abstract class BotAdapter { |
@@ -40,4 +40,17 @@ /** | ||
* A set of `Middleware` plugins. The set itself is middleware so you can easily package up a set | ||
* of middleware that can be composed into a bot with a single `bot.use(mySet)` call or even into | ||
* another middleware set using `set.use(mySet)`. | ||
* of middleware that can be composed into an adapter with a single `adapter.use(mySet)` call or | ||
* even into another middleware set using `set.use(mySet)`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const { MiddlewareSet } = require('botbuilder'); | ||
* | ||
* const set = new MiddlewareSet(); | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
*/ | ||
@@ -48,3 +61,3 @@ export class MiddlewareSet implements Middleware { | ||
/** | ||
* Creates a new instance of a MiddlewareSet. | ||
* Creates a new MiddlewareSet instance. | ||
* @param middleware Zero or more middleware handlers(s) to register. | ||
@@ -62,2 +75,12 @@ */ | ||
* Registers middleware handlers(s) with the set. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* set.use(async (context, next) => { | ||
* console.log(`Leading Edge`); | ||
* await next(); | ||
* console.log(`Trailing Edge`); | ||
* }); | ||
* ``` | ||
* @param middleware One or more middleware handlers(s) to register. | ||
@@ -80,2 +103,10 @@ */ | ||
* Executes a set of middleware in series. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await set.run(context, async (context) => { | ||
* console.log(`Bot Logic`); | ||
* }); | ||
* ``` | ||
* @param context Context for the current turn of conversation with the user. | ||
@@ -82,0 +113,0 @@ * @param next Function to invoke at the end of the middleware chain. |
@@ -43,9 +43,9 @@ /** | ||
* | ||
* For TypeScript developers the `BotContext` is also exposed as an interface which you can derive | ||
* For TypeScript developers the `TurnContext` is also exposed as an interface which you can derive | ||
* from to better describe the actual shape of the context object being passed around. Middleware | ||
* can potentially extend the context object with additional members so in order to get intellisense | ||
* for those added members you'll need to define them on an interface that extends BotContext: | ||
* for those added members you'll need to define them on an interface that extends TurnContext: | ||
* | ||
* ```JavaScript | ||
* interface MyContext extends BotContext { | ||
* ```JS | ||
* interface MyContext extends TurnContext { | ||
* // Added by UserState middleware. | ||
@@ -58,3 +58,3 @@ * readonly userState: MyUserState; | ||
* | ||
* adapter.processRequest(req, res, (context: MyContext) => { | ||
* adapter.processActivity(req, res, (context: MyContext) => { | ||
* const state = context.conversationState; | ||
@@ -74,3 +74,3 @@ * }); | ||
/** | ||
* Creates a new BotContext instance for a turn of conversation. | ||
* Creates a new TurnContext instance. | ||
* @param adapterOrContext Adapter that constructed the context or a context object to clone. | ||
@@ -91,4 +91,4 @@ * @param request Request being processed. | ||
/** | ||
* Called when this BotContext instance is passed into the constructor of a new BotContext | ||
* instance. | ||
* Called when this TurnContext instance is passed into the constructor of a new TurnContext | ||
* instance. Can be overridden in derived classes. | ||
* @param context The context object to copy private members to. Everything should be copied by reference. | ||
@@ -102,3 +102,14 @@ */ | ||
/** The adapter for this context. */ | ||
/** | ||
* The adapter for this context. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
*/ | ||
public get adapter(): BotAdapter { | ||
@@ -108,3 +119,11 @@ return this._adapter as BotAdapter; | ||
/** The received activity. */ | ||
/** | ||
* The received activity. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const utterance = (context.activity.text || '').trim(); | ||
* ``` | ||
*/ | ||
public get activity(): Activity { | ||
@@ -114,3 +133,15 @@ return this._activity as Activity; | ||
/** If `true` at least one response has been sent for the current turn of conversation. */ | ||
/** | ||
* If `true` at least one response has been sent for the current turn of conversation. This is | ||
* primarily useful for determining if a bot should run fallback routing logic. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await routeActivity(context); | ||
* if (!context.responded) { | ||
* await context.sendActivity(`I'm sorry. I didn't understand.`); | ||
* } | ||
* ``` | ||
*/ | ||
public get responded(): boolean { | ||
@@ -125,3 +156,19 @@ return this._respondedRef.responded; | ||
/** Map of services and other values cached for the lifetime of the turn. */ | ||
/** | ||
* Map of services and other values cached for the lifetime of the turn. Middleware, other | ||
* components, and services will typically use this to cache information that could be asked | ||
* for by a bot multiple times during a turn. The bots logic is free to use this to pass | ||
* information between its own components. | ||
* | ||
* > NOTE: For middleware and third party components, consider using a `Symbol()` for your | ||
* cache key to avoid potential naming collisions with the bots caching and other | ||
* components. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const cart = await loadUsersShoppingCart(context); | ||
* context.services.set('cart', cart); | ||
* ``` | ||
*/ | ||
public get services(): Map<any, any> { | ||
@@ -132,3 +179,10 @@ return this._services; | ||
/** | ||
* Sends a single activity or message to the user. | ||
* Sends a single activity or message to the user. This ultimately calls [sendActivities()](#sendactivites) | ||
* and is provided as a convenience to make formating and sending individual activities easier. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivity(`Hello World`); | ||
* ``` | ||
* @param activityOrText Activity or text of a message to send the user. | ||
@@ -156,3 +210,13 @@ * @param speak (Optional) SSML that should be spoken to the user for the message. | ||
* set to a type of `message`. The array of activities will then be routed through any [onSendActivities()](#onsendactivities) | ||
* handlers and then passed to `adapter.sendActivities()`. | ||
* handlers and then passed to `adapter.sendActivities()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* await context.sendActivities([ | ||
* { type: 'typing' }, | ||
* { type: 'delay', value: 2000 }, | ||
* { type: 'message', text: 'Hello... How are you?' } | ||
* ]); | ||
* ``` | ||
* @param activities One or more activities to send to the user. | ||
@@ -182,2 +246,12 @@ */ | ||
* before being passed to `adapter.updateActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const update = await approveExpenseReport(matched[1]); | ||
* await context.updateActivity(update); | ||
* } | ||
* ``` | ||
* @param activity New replacement activity. The activity should already have it's ID information populated. | ||
@@ -194,2 +268,12 @@ */ | ||
* [onDeleteActivity](#ondeleteactivity) handlers before being passed to `adapter.deleteActivity()`. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* const matched = /approve (.*)/i.exec(context.text); | ||
* if (matched) { | ||
* const savedId = await approveExpenseReport(matched[1]); | ||
* await context.deleteActivity(savedId); | ||
* } | ||
* ``` | ||
* @param idOrReference ID or conversation of the activity being deleted. If an ID is specified the conversation reference information from the current request will be used to delete the activity. | ||
@@ -210,2 +294,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept the sending of activities. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onSendActivities(await (ctx, activities, next) => { | ||
* // Deliver activities | ||
* await next(); | ||
* | ||
* // Log sent messages | ||
* activities.filter(a => a.type === 'message').forEach(a => logSend(a)); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [sendActivity()](#sendactivity) is called. The handler should call `next()` to continue sending of the activities. | ||
@@ -220,2 +316,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being updated. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onUpdateActivities(await (ctx, activity, next) => { | ||
* // Replace activity | ||
* await next(); | ||
* | ||
* // Log update | ||
* logUpdate(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [updateActivity()](#updateactivity) is called. The handler should call `next()` to continue sending of the replacement activity. | ||
@@ -230,2 +338,14 @@ */ | ||
* Registers a handler to be notified of and potentially intercept an activity being deleted. | ||
* | ||
* **Usage Example** | ||
* | ||
* ```javascript | ||
* context.onDeleteActivities(await (ctx, reference, next) => { | ||
* // Delete activity | ||
* await next(); | ||
* | ||
* // Log delete | ||
* logDelete(activity); | ||
* }); | ||
* ``` | ||
* @param handler A function that will be called anytime [deleteActivity()](#deleteactivity) is called. The handler should call `next()` to continue deletion of the activity. | ||
@@ -284,6 +404,6 @@ */ | ||
* ```JavaScript | ||
* // Send a typing indicator without calling any handlers | ||
* // Send a typing indicator without going through an middleware listeners. | ||
* const reference = TurnContext.getConversationReference(context.request); | ||
* const activity = TurnContext.applyConversationReference({ type: 'typing' }, reference); | ||
* return context.adapter.sendActivity(activity); | ||
* await context.adapter.sendActivities([activity]); | ||
* ``` | ||
@@ -290,0 +410,0 @@ * @param activity Activity to copy delivery information to. |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
119431
12.19%2479
21.46%+ Added
- Removed