Add EventFactory and HandoffEventNames to botbuilder (#2010)

* first pass at EventFactory

* Update EventFactory to latest in dotnet master

* update EventFactory tests

Author: stevengum

libraries/botbuilder/package.json

@@ -27,7 +27,8 @@
     "botframework-connector": "4.1.6",
     "botframework-streaming": "4.1.6",
     "filenamify": "^4.1.0",
-    "fs-extra": "^7.0.1"
+    "fs-extra": "^7.0.1",
+    "moment-timezone": "^0.5.28"
   },
   "devDependencies": {
     "@types/mocha": "^2.2.47",

libraries/botbuilder/src/eventFactory.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from 'botbuilder-core';
+import { Activity, Attachment, ConversationAccount, ConversationReference, Transcript } from 'botframework-schema';
+import * as moment from 'moment-timezone';
+import { HandoffEventNames } from './handoffEventNames';
+
+/**
+ * Contains utility methods for creating various event types.
+ */
+export class EventFactory {
+    /**
+     * Create handoff initiation event.
+     * @param context The context object for the turn.
+     * @param handoffContext Agent hub-specific context.
+     * @param transcript Transcript of the conversation.
+     */
+    public static createHandoffInitiation(context: TurnContext, handoffContext: any, transcript?: Transcript): Activity {
+        if (!context) {
+            throw new TypeError('EventFactory.createHandoffInitiation(): Missing context.');
+        }
+
+        const handoffEvent = this.createHandoffEvent(HandoffEventNames.InitiateHandoff, handoffContext, context.activity.conversation);
+
+        handoffEvent.from = context.activity.from;
+        handoffEvent.relatesTo = TurnContext.getConversationReference(context.activity) as ConversationReference;
+        handoffEvent.replyToId = context.activity.id;
+        handoffEvent.serviceUrl = context.activity.serviceUrl;
+        handoffEvent.channelId = context.activity.channelId;
+
+        if (transcript) {
+            const attachment: Attachment = {
+                content: transcript,
+                contentType: 'application/json',
+                name: 'Transcript'
+            };
+            handoffEvent.attachments.push(attachment);
+        }
+
+        return handoffEvent;
+    }
+
+    /**
+     * Create handoff status event.
+     * @param conversation Conversation being handed over.
+     * @param state State, possible values are: "accepted", "failed", "completed".
+     * @param message Additional message for failed handoff.
+     */
+    public static createHandoffStatus(conversation: ConversationAccount, state: string, message?: string): Activity {
+        if (!conversation) {
+            throw new TypeError('EventFactory.createHandoffStatus(): missing conversation.');
+        }
+
+        if (!state) {
+            throw new TypeError('EventFactory.createHandoffStatus(): missing state.');
+        }
+        
+        const value: any = { state, message };
+
+        const handoffEvent = this.createHandoffEvent(HandoffEventNames.HandoffStatus, value, conversation);
+
+        return handoffEvent;
+    }
+
+    private static createHandoffEvent(name: string, value: any, conversation: ConversationAccount): Activity {
+        const handoffEvent: Activity = {} as any;
+
+        handoffEvent.name = name;
+        handoffEvent.value = value;
+        handoffEvent.id = uuid();
+        handoffEvent.timestamp = new Date(Date.now());
+        // The timestamp does not contain the local offset which is a known limitation of Date objects in JavaScript.
+        // Therefore, the localTimezone is included in the handoffEvent.
+        handoffEvent.localTimezone = moment.tz.guess();
+        handoffEvent.conversation = conversation;
+        handoffEvent.attachments = [];
+        handoffEvent.entities = [];
+
+        return handoffEvent;
+    }
+}
+
+function uuid(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c): string => {
+        let r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}

libraries/botbuilder/src/handoffEventNames.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export class HandoffEventNames {
+
+    public static readonly InitiateHandoff: string = 'handoff.initiate';
+
+    public static readonly HandoffStatus: string = 'handoff.status';
+}

libraries/botbuilder/src/index.ts

@@ -14,6 +14,8 @@ export { BotFrameworkHttpClient } from './botFrameworkHttpClient';
 export { ChannelServiceHandler } from './channelServiceHandler';
 export { ChannelServiceRoutes, RouteHandler, WebServer } from './channelServiceRoutes';
 export * from './fileTranscriptStore';
+export { HandoffEventNames } from './handoffEventNames';
+export { EventFactory } from './eventFactory';
 export * from './inspectionMiddleware';
 export {
     WebRequest,

libraries/botbuilder/tests/eventFactoryTests.test.js

@@ -0,0 +1,103 @@
+const { equal, ok: assert, strictEqual } = require('assert');
+const moment = require('moment-timezone');
+
+const {
+    ActivityTypes,
+    EventFactory,
+    HandoffEventNames,
+    MessageFactory,
+    TestAdapter,
+    TurnContext
+} = require('../');
+
+describe('EventFactory', function() {
+    this.timeout(5000);
+
+    describe('createHandoffInitiation', () => {
+        it('should succeed', () => {
+            const adapter = new TestAdapter(async context => { /* no op */ });
+            const fromId = 'test';
+            const activity = {
+                type: ActivityTypes.Message,
+                text: '',
+                conversation: {},
+                recipient: {},
+                from: { id: fromId },
+                channelId: 'testchannel',
+                serviceUrl: 'http://myservice'
+            };
+
+            const context = new TurnContext(adapter, activity);
+            const transcript = { activities: [ MessageFactory.text('hello') ] };
+
+            equal(transcript.activities[0].channelId, undefined);
+            equal(transcript.activities[0].serviceUrl, undefined);
+            equal(transcript.activities[0].conversation, undefined);
+
+            const skillValue = 'any';
+            const handoffEvent = EventFactory.createHandoffInitiation(context, { skill: skillValue }, transcript);
+
+            strictEqual(handoffEvent.name, HandoffEventNames.InitiateHandoff);
+            const skill = handoffEvent.value && handoffEvent.value.skill;
+            strictEqual(skill, skillValue);
+            strictEqual(handoffEvent.from.id, fromId);
+        });
+
+        it('should throw if turnContext is falsy', () => {
+            try {
+                EventFactory.createHandoffInitiation(null, 'some text');
+            } catch (e) {
+                strictEqual(e.message, 'EventFactory.createHandoffInitiation(): Missing context.');
+            }
+        });
+    });
+
+    describe('createHandoffStatus', () => {
+        it('should succeed', () => {
+            const state = 'failed';
+            const message = 'timed out';
+            const handoffEvent = EventFactory.createHandoffStatus({}, state, message);
+
+            strictEqual(handoffEvent.name, HandoffEventNames.HandoffStatus);
+
+            const stateFormEvent = handoffEvent.value && handoffEvent.value.state;
+            strictEqual(stateFormEvent, state);
+
+            const messageFormEvent = handoffEvent.value && handoffEvent.value.message;
+            strictEqual(messageFormEvent, message);
+
+            const status = JSON.stringify(handoffEvent.value);
+            strictEqual(status, `{\"state\":\"${ state }\",\"message\":\"${ message }\"}`);
+            assert(handoffEvent.attachments, 'handoffEvent.attachments should not be undefined.');
+            assert(handoffEvent.id, 'handoffEvent.id should not be undefined.');
+            strictEqual(handoffEvent.localTimezone, moment.tz.guess());
+        });
+
+        it('should succeed with no message', () => {
+            const state = 'failed';
+            const handoffEvent = EventFactory.createHandoffStatus({}, state);
+
+            const stateFormEvent = handoffEvent.value && handoffEvent.value.state;
+            strictEqual(state, stateFormEvent);
+
+            const messageFormEvent = handoffEvent.value && handoffEvent.value.message;
+            strictEqual(undefined, messageFormEvent);
+        });
+
+        it('should throw if conversation is falsy', () => {
+            try {
+                EventFactory.createHandoffStatus(null, 'some text');
+            } catch (e) {
+                strictEqual(e.message, 'EventFactory.createHandoffStatus(): missing conversation.');
+            }
+        });
+
+        it('should throw if state is falsy', () => {
+            try {
+                EventFactory.createHandoffStatus({}, null);
+            } catch (e) {
+                strictEqual(e.message, 'EventFactory.createHandoffStatus(): missing state.');
+            }
+        });
+    });
+});