Add support for streaming through entities

CHANGELOG.md

@@ -107,6 +107,7 @@ Notes: web developers are advised to use [`~` (tilde range)](https://github.com/
 - Added `disableFileUpload` flag to completelly disable file upload feature, in PR [#5508](https://github.com/microsoft/BotFramework-WebChat/pull/5508), by [@JamesNewbyAtMicrosoft](https://github.com/JamesNewbyAtMicrosoft)
    - Deprecated `hideUploadButton` in favor of `disableFileUpload`.
    - Updated `BasicSendBoxToolbar` to rely solely on `disableFileUpload`.
+- Added livestreaming support for livestreaming data in `entities` in PR [#5517](https://github.com/microsoft/BotFramework-WebChat/pull/5517) by [@kylerohn](https://github.com/kylerohn)
 
 ### Changed
 

docs/LIVESTREAMING.md

@@ -64,6 +64,23 @@ To simplify this documentation, we are using the term "bot" instead of "copilot"
 
 Bot developers would need to implement the livestreaming as outlined in this section. The implementation below will enable livestreaming to both Azure Bot Services and Teams.
 
+> [!NOTE]
+> In the scenarios below, the livestream metadata is inside the `channelData` field. BotFramework-WebChat checks both `channelData` and the first element of the `entities` field for livestreaming metadata. It will appear in different places depending on the platform used to communicate with BotFramework-WebChat:
+>
+> ```json
+> {
+>    "entities": [
+>       {
+>          "streamSequence": 1,
+>          "streamType": "streaming",
+>          "type": "streaminfo"
+>       }
+>    ],
+>    "text": "A quick",
+>    "type": "typing"
+> }
+> ```
+
 ### Scenario 1: Livestream from start to end
 
 > In this example, we assume the bot is livestreaming the following sentence to the user:

packages/core/src/utils/getActivityLivestreamingMetadata.spec.ts

@@ -2,7 +2,7 @@ import type { WebChatActivity } from '../types/WebChatActivity';
 import getActivityLivestreamingMetadata from './getActivityLivestreamingMetadata';
 
 describe.each([['with "streamId"' as const], ['without "streamId"' as const]])('activity %s', variant => {
-  describe('activity with "streamType" of "streaming"', () => {
+  describe('activity with "streamType" of "streaming" (channelData)', () => {
     let activity: WebChatActivity;
 
     beforeEach(() => {
@@ -32,7 +32,7 @@ describe.each([['with "streamId"' as const], ['without "streamId"' as const]])('
     }
   });
 
-  describe('activity with "streamType" of "informative message"', () => {
+  describe('activity with "streamType" of "informative message" (channelData)', () => {
     let activity: WebChatActivity;
 
     beforeEach(() => {
@@ -62,7 +62,7 @@ describe.each([['with "streamId"' as const], ['without "streamId"' as const]])('
     }
   });
 
-  describe('activity with "streamType" of "final"', () => {
+  describe('activity with "streamType" of "final" (channelData)', () => {
     let activity: WebChatActivity;
 
     beforeEach(() => {
@@ -91,22 +91,133 @@ describe.each([['with "streamId"' as const], ['without "streamId"' as const]])('
   });
 });
 
+describe.each([['with "streamId"' as const], ['without "streamId"' as const]])('activity %s', variant => {
+  describe('activity with "streamType" of "streaming" (entities)', () => {
+    let activity: WebChatActivity;
+
+    beforeEach(() => {
+      activity = {
+        entities: [
+          {
+            ...(variant === 'with "streamId"' ? { streamId: 'a-00001' } : {}),
+            streamSequence: 1,
+            streamType: 'streaming',
+            type: 'streaminfo'
+          }
+        ],
+        channelData: {},
+        id: 'a-00002',
+        text: 'Hello, World!',
+        type: 'typing'
+      } as any;
+    });
+
+    test('should return type of "interim activity"', () =>
+      expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('type', 'interim activity'));
+    test('should return sequence number', () =>
+      expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sequenceNumber', 1));
+
+    if (variant === 'with "streamId"') {
+      test('should return session ID with value from "entities.streamId"', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sessionId', 'a-00001'));
+    } else {
+      test('should return session ID with value of "activity.id"', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sessionId', 'a-00002'));
+    }
+  });
+
+  describe('activity with "streamType" of "informative message" (entities)', () => {
+    let activity: WebChatActivity;
+
+    beforeEach(() => {
+      activity = {
+        entities: [
+          {
+            ...(variant === 'with "streamId"' ? { streamId: 'a-00001' } : {}),
+            streamSequence: 1,
+            streamType: 'informative',
+            type: 'streaminfo'
+          }
+        ],
+        channelData: {},
+        id: 'a-00002',
+        text: 'Hello, World!',
+        type: 'typing'
+      } as any;
+    });
+
+    test('should return type of "informative message"', () =>
+      expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('type', 'informative message'));
+    test('should return sequence number', () =>
+      expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sequenceNumber', 1));
+
+    if (variant === 'with "streamId"') {
+      test('should return session ID with value from "entities.streamId"', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sessionId', 'a-00001'));
+    } else {
+      test('should return session ID with value of "activity.id"', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sessionId', 'a-00002'));
+    }
+  });
+
+  describe('activity with "streamType" of "final" (entities)', () => {
+    let activity: WebChatActivity;
+
+    beforeEach(() => {
+      activity = {
+        entities: [
+          {
+            ...(variant === 'with "streamId"' ? { streamId: 'a-00001' } : {}),
+            streamType: 'final',
+            type: 'streaminfo'
+          }
+        ],
+        channelData: {},
+        id: 'a-00002',
+        text: 'Hello, World!',
+        type: 'message'
+      } as any;
+    });
+
+    if (variant === 'with "streamId"') {
+      test('should return type of "final activity"', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('type', 'final activity'));
+      test('should return sequence number of Infinity', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sequenceNumber', Infinity));
+      test('should return session ID', () =>
+        expect(getActivityLivestreamingMetadata(activity)).toHaveProperty('sessionId', 'a-00001'));
+    } else {
+      // Final activity must have "streamId". Final activity without "streamId" is not a valid livestream activity.
+      test('should return undefined', () => expect(getActivityLivestreamingMetadata(activity)).toBeUndefined());
+    }
+  });
+});
+
 test('invalid activity should return undefined', () =>
   expect(getActivityLivestreamingMetadata('invalid' as any)).toBeUndefined());
 
-test('activity with "streamType" of "streaming" without critical fields should return undefined', () =>
+test('activity with "streamType" of "streaming" without critical fields should return undefined (channelData)', () =>
   expect(
     getActivityLivestreamingMetadata({
       channelData: { streamType: 'streaming' },
       type: 'typing'
     } as any)
   ).toBeUndefined());
 
+test('activity with "streamType" of "streaming" without critical fields should return undefined (entities)', () =>
+  expect(
+    getActivityLivestreamingMetadata({
+      entities: [{ streamType: 'streaming', type: 'streaminfo' }],
+      channelData: {},
+      type: 'typing'
+    } as any)
+  ).toBeUndefined());
+
 describe.each([
   ['integer', 1, true],
   ['zero', 0, false],
   ['decimal', 1.234, false]
-])('activity with %s "streamSequence" should return undefined', (_, streamSequence, isValid) => {
+])('activity with %s "streamSequence" should return undefined (channelData)', (_, streamSequence, isValid) => {
   const activity = {
     channelData: { streamSequence, streamType: 'streaming' },
     id: 'a-00001',
@@ -121,7 +232,27 @@ describe.each([
   }
 });
 
-describe('"typing" activity with "streamType" of "final"', () => {
+describe.each([
+  ['integer', 1, true],
+  ['zero', 0, false],
+  ['decimal', 1.234, false]
+])('activity with %s "streamSequence" should return undefined (entities)', (_, streamSequence, isValid) => {
+  const activity = {
+    entities: [{ streamSequence, streamType: 'streaming', type: 'streaminfo' }],
+    channelData: {},
+    id: 'a-00001',
+    text: '',
+    type: 'typing'
+  } as any;
+
+  if (isValid) {
+    expect(getActivityLivestreamingMetadata(activity)).toBeTruthy();
+  } else {
+    expect(getActivityLivestreamingMetadata(activity)).toBeUndefined();
+  }
+});
+
+describe('"typing" activity with "streamType" of "final" (channelData)', () => {
   test('should return undefined if "text" field is defined', () =>
     expect(
       getActivityLivestreamingMetadata({
@@ -143,11 +274,45 @@ describe('"typing" activity with "streamType" of "final"', () => {
     ).toHaveProperty('type', 'final activity'));
 });
 
-test('activity with "streamType" of "streaming" without "content" should return type of "contentless"', () =>
+describe('"typing" activity with "streamType" of "final" (entities)', () => {
+  test('should return undefined if "text" field is defined', () =>
+    expect(
+      getActivityLivestreamingMetadata({
+        entities: [{ streamId: 'a-00001', streamType: 'final', type: 'streaminfo' }],
+        channelData: {},
+        id: 'a-00002',
+        text: 'Final "typing" activity, must not have "text".',
+        type: 'typing'
+      } as any)
+    ).toBeUndefined());
+
+  test('should return truthy if "text" field is not defined', () =>
+    expect(
+      getActivityLivestreamingMetadata({
+        entities: [{ streamId: 'a-00001', streamType: 'final', type: 'streaminfo' }],
+        channelData: {},
+        id: 'a-00002',
+        // Final activity can be "typing" if it does not have "text".
+        type: 'typing'
+      } as any)
+    ).toHaveProperty('type', 'final activity'));
+});
+
+test('activity with "streamType" of "streaming" without "content" should return type of "contentless" (channelData)', () =>
   expect(
     getActivityLivestreamingMetadata({
       channelData: { streamSequence: 1, streamType: 'streaming' },
       id: 'a-00001',
       type: 'typing'
     } as any)
   ).toHaveProperty('type', 'contentless'));
+
+test('activity with "streamType" of "streaming" without "content" should return type of "contentless" (entities)', () =>
+  expect(
+    getActivityLivestreamingMetadata({
+      entities: [{ streamSequence: 1, streamType: 'streaming', type: 'streaminfo' }],
+      channelData: {},
+      id: 'a-00001',
+      type: 'typing'
+    } as any)
+  ).toHaveProperty('type', 'contentless'));