fix: UpdateContext documentation (#182)

UpdateContext documentation

Co-authored-by: German Attanasio <[email protected]>

Author: germanattanasio

README.md

@@ -220,8 +220,6 @@ A common scenario of processing actions is:
 
 ### Using sendToWatson to update context
 
-Using sendToWatson to update context simplifies the bot code compared to solution using updateContext below.
-
 ```js
 const checkBalance =  async (context) => {
   //do something real here
@@ -258,6 +256,20 @@ const processWatsonResponse = async (bot, message) => {
 controller.on('message_received', processWatsonResponse);
 ```
 
+### Using updateContext to update context
+
+sendToWatson should cover majority of use cases,
+but updateContext method can be useful when you want to update context from bot code,
+but there is no need to make a special request to Watson.
+
+```js
+if (params.amount) {
+    const context = message.watsonData.context;
+    context.paymentAmount = params.amount;
+    await watsonMiddleware.updateContext(message.user, context);
+}
+```
+
 ## Implementing event handlers
 
 Events are messages having type different than `message`.

lib/index.d.ts

@@ -15,6 +15,7 @@
  */
 import Botkit = require('botkit');
 import AssistantV1 = require('ibm-watson/assistant/v1');
+import { Context } from 'ibm-watson/assistant/v1';
 import { BotkitMessage } from 'botkit';
 export interface WatsonMiddlewareConfig {
     version: string;
@@ -34,11 +35,6 @@ export interface WatsonMiddlewareConfig {
 export interface Payload extends AssistantV1.MessageRequest {
     workspace_id: string;
 }
-export interface Context {
-    conversation_id: string;
-    system: any;
-    [index: string]: any;
-}
 export declare type BotkitWatsonMessage = BotkitMessage & {
     watsonData?: Payload;
     watsonError?: string;
@@ -60,7 +56,7 @@ export declare class WatsonMiddleware {
     receive(bot: Botkit.BotWorker, message: Botkit.BotkitMessage): Promise<void>;
     interpret(bot: Botkit.BotWorker, message: Botkit.BotkitMessage): Promise<void>;
     readContext(user: string): Promise<Context>;
-    updateContext(user: string, contextDelta: ContextDelta): Promise<{
-        context: Context | ContextDelta;
+    updateContext(user: string, context: Context): Promise<{
+        context: Context;
     }>;
 }

lib/index.js

@@ -15,11 +15,12 @@
  */
 import { Storage } from 'botbuilder';
 import AssistantV1 = require('ibm-watson/assistant/v1');
-import { Payload, Context, ContextDelta } from './index';
+import { Context } from 'ibm-watson/assistant/v1';
+import { Payload } from './index';
 export declare function readContext(userId: string, storage: Storage): Promise<Context | null>;
 export declare function updateContext(userId: string, storage: Storage, watsonResponse: {
-    context: Context | ContextDelta;
+    context: Context;
 }): Promise<{
-    context: Context | ContextDelta;
+    context: Context;
 }>;
 export declare function postMessage(conversation: AssistantV1, payload: Payload): Promise<AssistantV1.MessageResponse>;

lib/index.js.map

@@ -18,6 +18,7 @@
 const debug = require('debug')('watson-middleware:index');
 import Botkit = require('botkit');
 import AssistantV1 = require('ibm-watson/assistant/v1');
+import { Context } from 'ibm-watson/assistant/v1';
 import { Storage } from 'botbuilder';
 import { readContext, updateContext, postMessage } from './utils';
 import deepMerge = require('deepmerge');
@@ -43,12 +44,6 @@ export interface Payload extends AssistantV1.MessageRequest {
   workspace_id: string;
 }
 
-export interface Context {
-  conversation_id: string;
-  system: any;
-  [index: string]: any;
-}
-
 export type BotkitWatsonMessage = BotkitMessage & {
   watsonData?: Payload;
   watsonError?: string;
@@ -208,15 +203,15 @@ export class WatsonMiddleware {
 
   public async updateContext(
     user: string,
-    contextDelta: ContextDelta,
-  ): Promise<{ context: Context | ContextDelta }> {
+    context: Context,
+  ): Promise<{ context: Context }> {
     if (!this.storage) {
       throw new Error(
         'updateContext is called before the first this.receive call',
       );
     }
     return updateContext(user, this.storage, {
-      context: contextDelta,
+      context: context,
     });
   }
 }

lib/utils.d.ts

@@ -18,7 +18,8 @@
 const debug = require('debug')('watson-middleware:utils');
 import { Storage } from 'botbuilder';
 import AssistantV1 = require('ibm-watson/assistant/v1');
-import { Payload, Context, ContextDelta } from './index';
+import { Context } from 'ibm-watson/assistant/v1';
+import { Payload } from './index';
 
 const storagePrefix = 'user.';
 
@@ -47,8 +48,8 @@ export async function readContext(
 export async function updateContext(
   userId: string,
   storage: Storage,
-  watsonResponse: { context: Context | ContextDelta },
-): Promise<{ context: Context | ContextDelta }> {
+  watsonResponse: { context: Context },
+): Promise<{ context: Context }> {
   const itemId = storagePrefix + userId;
 
   let userData: any = {};

lib/utils.js.map

@@ -14,12 +14,13 @@
  * limitations under the License.
  */
 
-import { Botkit, BotkitMessage } from 'botkit';
+import { Botkit } from 'botkit';
 import { updateContext } from '../lib/utils';
 import { clonePrototype } from 'clone';
 import { MemoryStorage } from 'botbuilder';
 import { WebAdapter } from 'botbuilder-adapter-web';
-import { WatsonMiddleware, BotkitWatsonMessage, Context } from '../lib/index';
+import { WatsonMiddleware, BotkitWatsonMessage } from '../lib/index';
+import { Context } from 'ibm-watson/assistant/v1';
 import nock = require('nock');
 
 //Watson Assistant params