botframework-webchat-core 4.18.1 → 4.19.0

package/src/reducers/activities/sort/deleteActivityByLocalId.ts

@@ -0,0 +1,177 @@
+import computePartListTimestamp from './private/computePartListTimestamp';
+import computeSortedActivities from './private/computeSortedActivities';
+import type { LocalId } from './property/LocalId';
+import type { LivestreamSessionMapEntry, State } from './types';
+
+export default function deleteActivityByLocalId(state: State, localId: LocalId): State {
+  const nextActivityIdToLocalIdMap = new Map(state.activityIdToLocalIdMap);
+  const nextActivityMap = new Map(state.activityMap);
+  const nextClientActivityIdToLocalIdMap = new Map(state.clientActivityIdToLocalIdMap);
+  const nextHowToGroupingMap = new Map(state.howToGroupingMap);
+  const nextLivestreamSessionMap = new Map(state.livestreamSessionMap);
+  let nextSortedChatHistoryList = Array.from(state.sortedChatHistoryList);
+
+  if (!nextActivityMap.delete(localId)) {
+    throw new Error(`botframework-webchat: Cannot find activity with local ID "${localId}" to delete`);
+  }
+
+  for (const entry of nextActivityIdToLocalIdMap) {
+    if (entry[1] === localId) {
+      nextActivityIdToLocalIdMap.delete(entry[0]);
+
+      break;
+    }
+  }
+
+  for (const entry of nextClientActivityIdToLocalIdMap) {
+    if (entry[1] === localId) {
+      nextClientActivityIdToLocalIdMap.delete(entry[0]);
+
+      break;
+    }
+  }
+
+  for (const [howToGroupingId, entry] of nextHowToGroupingMap) {
+    const partIndex = entry.partList.findIndex(part => part.type === 'activity' && part.activityLocalId === localId);
+
+    if (~partIndex) {
+      const nextPartList = Array.from(entry.partList);
+
+      nextPartList.splice(partIndex, 1);
+
+      if (nextPartList.length) {
+        const nextHowToGroupingMapEntry = Object.freeze({
+          ...entry,
+          logicalTimestamp: computePartListTimestamp(nextPartList),
+          partList: Object.freeze(nextPartList)
+        });
+
+        nextHowToGroupingMap.set(howToGroupingId, nextHowToGroupingMapEntry);
+
+        nextSortedChatHistoryList = nextSortedChatHistoryList.map(entry => {
+          if (entry.type === 'how to grouping' && entry.howToGroupingId === howToGroupingId) {
+            return {
+              howToGroupingId,
+              logicalTimestamp: nextHowToGroupingMapEntry.logicalTimestamp,
+              type: 'how to grouping'
+            };
+          }
+
+          return entry;
+        });
+      } else {
+        nextHowToGroupingMap.delete(howToGroupingId);
+
+        const sortedChatHistoryListIndex = nextSortedChatHistoryList.findIndex(
+          entry => entry.type === 'how to grouping' && entry.howToGroupingId === howToGroupingId
+        );
+
+        ~sortedChatHistoryListIndex && nextSortedChatHistoryList.splice(sortedChatHistoryListIndex, 1);
+      }
+    }
+  }
+
+  for (const [livestreamSessionId, livestreamSessionMapEntry] of nextLivestreamSessionMap) {
+    const activityIndex = livestreamSessionMapEntry.activities.findIndex(
+      activity => activity.activityLocalId === localId
+    );
+
+    if (~activityIndex) {
+      const nextActivities = Array.from(livestreamSessionMapEntry.activities);
+
+      nextActivities.splice(activityIndex, 1);
+
+      if (nextActivities.length) {
+        // eslint-disable-next-line no-magic-numbers
+        const lastActivity = nextActivities.at(-1);
+        const finalActivity = lastActivity?.sequenceNumber === Infinity ? lastActivity : undefined;
+
+        const logicalTimestamp = finalActivity
+          ? finalActivity.logicalTimestamp
+          : nextActivities.at(0)?.logicalTimestamp;
+
+        const nextLivestreamSessionMapEntry: LivestreamSessionMapEntry = {
+          ...livestreamSessionMapEntry,
+          activities: nextActivities,
+          finalized: !!finalActivity,
+          logicalTimestamp
+        };
+
+        nextLivestreamSessionMap.set(livestreamSessionId, nextLivestreamSessionMapEntry);
+
+        for (const [howToGroupingId, entry] of nextHowToGroupingMap) {
+          let changed = false;
+
+          const nextPartList = entry.partList.map(part => {
+            if (part.type === 'livestream session' && part.livestreamSessionId === livestreamSessionId) {
+              changed = true;
+
+              return { ...part, logicalTimestamp };
+            }
+
+            return part;
+          });
+
+          if (changed) {
+            nextHowToGroupingMap.set(howToGroupingId, {
+              ...entry,
+              logicalTimestamp: computePartListTimestamp(nextPartList),
+              partList: nextPartList
+            });
+          }
+        }
+      } else {
+        nextLivestreamSessionMap.delete(livestreamSessionId);
+
+        const sortedChatHistoryListIndex = nextSortedChatHistoryList.findIndex(
+          entry => entry.type === 'livestream session' && entry.livestreamSessionId === livestreamSessionId
+        );
+
+        ~sortedChatHistoryListIndex && nextSortedChatHistoryList.splice(sortedChatHistoryListIndex, 1);
+
+        for (const [howToGroupingId, entry] of nextHowToGroupingMap) {
+          const partIndex = entry.partList.findIndex(
+            part => part.type === 'livestream session' && part.livestreamSessionId === livestreamSessionId
+          );
+
+          if (~partIndex) {
+            const nextPartList = Array.from(entry.partList);
+
+            nextPartList.splice(partIndex, 1);
+
+            nextHowToGroupingMap.set(howToGroupingId, {
+              ...entry,
+              logicalTimestamp: computePartListTimestamp(nextPartList),
+              partList: nextPartList
+            });
+          }
+        }
+      }
+    }
+  }
+
+  nextSortedChatHistoryList = nextSortedChatHistoryList.filter(entry => {
+    if (entry.type === 'activity' && entry.activityLocalId === localId) {
+      return false;
+    }
+
+    return true;
+  });
+
+  const nextSortedActivities = computeSortedActivities({
+    activityMap: nextActivityMap,
+    howToGroupingMap: nextHowToGroupingMap,
+    livestreamSessionMap: nextLivestreamSessionMap,
+    sortedChatHistoryList: nextSortedChatHistoryList
+  });
+
+  return Object.freeze({
+    activityIdToLocalIdMap: Object.freeze(nextActivityIdToLocalIdMap),
+    activityMap: Object.freeze(nextActivityMap),
+    clientActivityIdToLocalIdMap: Object.freeze(nextClientActivityIdToLocalIdMap),
+    howToGroupingMap: Object.freeze(nextHowToGroupingMap),
+    livestreamSessionMap: Object.freeze(nextLivestreamSessionMap),
+    sortedActivities: Object.freeze(nextSortedActivities),
+    sortedChatHistoryList: Object.freeze(nextSortedChatHistoryList)
+  } satisfies State);
+}

package/src/reducers/activities/sort/private/computePartListTimestamp.ts

@@ -0,0 +1,9 @@
+import type { HowToGroupingMapPartEntry } from '../types';
+
+export default function computePartListTimestamp(partList: readonly HowToGroupingMapPartEntry[]): number | undefined {
+  return partList.reduce<number | undefined>(
+    (max, { logicalTimestamp }) =>
+      typeof logicalTimestamp === 'undefined' ? max : Math.max(max ?? -Infinity, logicalTimestamp),
+    undefined
+  );
+}

package/src/reducers/activities/sort/private/computeSortedActivities.ts

@@ -0,0 +1,51 @@
+import type { Activity, LivestreamSessionMap, State } from '../types';
+
+function* yieldSessionActivities(
+  session: NonNullable<ReturnType<LivestreamSessionMap['get']>>,
+  activityMap: State['activityMap']
+): Generator<Activity> {
+  if (session.finalized) {
+    // After finalization, only yield the final revision — intermediate revisions are pruned.
+    // eslint-disable-next-line no-magic-numbers
+    const lastEntry = session.activities.at(-1);
+
+    lastEntry && (yield activityMap.get(lastEntry.activityLocalId)!.activity);
+  } else {
+    for (const activityEntry of session.activities) {
+      yield activityMap.get(activityEntry.activityLocalId)!.activity;
+    }
+  }
+}
+
+export default function computeSortedActivities(
+  temporalState: Pick<State, 'activityMap' | 'howToGroupingMap' | 'livestreamSessionMap' | 'sortedChatHistoryList'>
+): Activity[] {
+  const { activityMap, howToGroupingMap, livestreamSessionMap, sortedChatHistoryList } = temporalState;
+
+  return Array.from<Activity>(
+    (function* () {
+      for (const sortedEntry of sortedChatHistoryList) {
+        if (sortedEntry.type === 'activity') {
+          // TODO: [P*] Instead of deferencing using internal ID, use pointer instead.
+          yield activityMap.get(sortedEntry.activityLocalId)!.activity;
+        } else if (sortedEntry.type === 'how to grouping') {
+          const howToGrouping = howToGroupingMap.get(sortedEntry.howToGroupingId)!;
+
+          for (const howToPartEntry of howToGrouping.partList) {
+            if (howToPartEntry.type === 'activity') {
+              yield activityMap.get(howToPartEntry.activityLocalId)!.activity;
+            } else {
+              howToPartEntry.type satisfies 'livestream session';
+
+              yield* yieldSessionActivities(livestreamSessionMap.get(howToPartEntry.livestreamSessionId)!, activityMap);
+            }
+          }
+        } else {
+          sortedEntry.type satisfies 'livestream session';
+
+          yield* yieldSessionActivities(livestreamSessionMap.get(sortedEntry.livestreamSessionId)!, activityMap);
+        }
+      }
+    })()
+  );
+}

package/src/reducers/activities/sort/private/getLogicalTimestamp.spec.ts

@@ -0,0 +1,49 @@
+/* eslint-disable no-restricted-globals */
+
+import { scenario } from '@testduet/given-when-then';
+import type { WebChatActivity } from '../../../../types/WebChatActivity';
+import type { LocalId } from '../property/LocalId';
+import getLogicalTimestamp from './getLogicalTimestamp';
+
+scenario('get logical timestamp', bdd => {
+  bdd
+    .given(
+      'an activity with timestamp property of new Date(123)',
+      () =>
+        ({
+          channelData: {
+            'webchat:internal:local-id': '_:a-00001' as LocalId,
+            'webchat:internal:position': 1,
+            'webchat:send-status': undefined
+          },
+          from: { id: 'bot', role: 'bot' },
+          id: 'a-00001',
+          text: 'Hello, World!',
+          timestamp: new Date(123).toISOString(),
+          type: 'message'
+        }) satisfies WebChatActivity
+    )
+    .when('getting its logical timestamp', activity => getLogicalTimestamp(activity, { Date }))
+    .then('should get 123', (_, actual) => expect(actual).toBe(123));
+
+  bdd
+    .given(
+      'an activity with sequence ID of 123',
+      () =>
+        ({
+          channelData: {
+            'webchat:internal:local-id': '_:a-00001' as LocalId,
+            'webchat:internal:position': 1,
+            'webchat:sequence-id': 123,
+            'webchat:send-status': 'sent'
+          },
+          from: { id: 'bot', role: 'bot' },
+          id: 'a-00001',
+          text: 'Hello, World!',
+          timestamp: undefined as any,
+          type: 'message'
+        }) satisfies WebChatActivity
+    )
+    .when('getting its logical timestamp', activity => getLogicalTimestamp(activity, { Date }))
+    .then('should get 123', (_, actual) => expect(actual).toBe(123));
+});

package/src/reducers/activities/sort/private/getLogicalTimestamp.ts

@@ -0,0 +1,33 @@
+import type { GlobalScopePonyfill } from '../../../../types/GlobalScopePonyfill';
+import type { Activity } from '../types';
+
+/**
+ * Get sequence ID from `activity.channelData['webchat:sequence-id']` and fallback to `+new Date(activity.timestamp)`.
+ *
+ * Chat adapter may send sequence ID to affect activity reordering. Sequence ID is supposed to be Unix timestamp.
+ *
+ * @param activity Activity to get sequence ID from.
+ * @returns Sequence ID.
+ */
+export default function getLogicalTimestamp(
+  activity: Activity,
+  ponyfill: Pick<GlobalScopePonyfill, 'Date'>
+): number | undefined {
+  const sequenceId = activity.channelData?.['webchat:sequence-id'];
+
+  if (typeof sequenceId === 'number') {
+    return sequenceId;
+  }
+
+  const { timestamp } = activity;
+
+  if (typeof timestamp === 'string') {
+    return +new ponyfill.Date(timestamp);
+  } else if (typeof timestamp !== 'undefined' && (timestamp as any) instanceof ponyfill.Date) {
+    console.warn('botframework-webchat: "timestamp" must be of type string, instead of Date.');
+
+    return +timestamp;
+  }
+
+  return undefined;
+}

package/src/reducers/activities/sort/private/getPartGroupingMetadataMap.spec.ts

@@ -0,0 +1,92 @@
+/* eslint-disable no-restricted-globals */
+
+import { expect } from '@jest/globals';
+import { scenario } from '@testduet/given-when-then';
+import type { WebChatActivity } from '../../../../types/WebChatActivity';
+import type { LocalId } from '../property/LocalId';
+import getPartGroupingMetadataMap, { type PartGroupingMetadataMapEntry } from './getPartGroupingMetadataMap';
+
+scenario('getPartGroupingMetadataMap', bdd => {
+  bdd
+    .given(
+      'an activity with isPartOf[@type="HowTo"]',
+      () =>
+        ({
+          channelData: {
+            'webchat:internal:local-id': '_:a-00001' as LocalId,
+            'webchat:internal:position': 0
+          },
+          entities: [
+            {
+              '@context': 'https://schema.org',
+              '@id': '',
+              '@type': 'Message',
+              type: 'https://schema.org/Message',
+              isPartOf: { '@id': '_:c-00001', '@type': 'HowTo' },
+              position: 1
+            } as any // TODO: [P0] We need to redo the typing of `WebChatActivity`.
+          ],
+          from: {
+            id: 'bot',
+            role: 'bot'
+          },
+          id: 'a-00001',
+          text: 'Hello, World!',
+          timestamp: new Date(0).toISOString(),
+          type: 'message'
+        }) satisfies WebChatActivity
+    )
+    .when('getPartGroupingMetadataMap() is called', activity => getPartGroupingMetadataMap(activity))
+    .then('should return part grouping metadata', (_, actual) => {
+      expect(actual).toEqual(
+        new Map<string, PartGroupingMetadataMapEntry>([
+          ['HowTo', { groupingId: '_:c-00001', position: 1 }]
+        ]) satisfies ReturnType<typeof getPartGroupingMetadataMap>
+      );
+    });
+});
+
+// TODO: [P0] Enable multiple part grouping once the schema behind `parseThing()` supports multiple part grouping.
+scenario('getPartGroupingMetadataMap with multiple part grouping', bdd => {
+  bdd
+    .given(
+      'an activity with isPartOf[@type="Conversation"][@type="HowTo"]',
+      () =>
+        ({
+          channelData: {
+            'webchat:internal:local-id': '_:a-00001' as LocalId,
+            'webchat:internal:position': 0
+          },
+          entities: [
+            {
+              '@context': 'https://schema.org',
+              '@id': '',
+              '@type': 'Message',
+              type: 'https://schema.org/Message',
+              isPartOf: [
+                { '@id': '_:conv:00001', '@type': 'Conversation' },
+                { '@id': '_:how-to:00001', '@type': 'HowTo' }
+              ],
+              position: 1
+            } as any // TODO: [P0] We need to redo the typing of `WebChatActivity`.
+          ],
+          from: {
+            id: 'bot',
+            role: 'bot'
+          },
+          id: 'a-00001',
+          text: 'Hello, World!',
+          timestamp: new Date(0).toISOString(),
+          type: 'message'
+        }) satisfies WebChatActivity
+    )
+    .when('getPartGroupingMetadataMap() is called', activity => getPartGroupingMetadataMap(activity))
+    .then('should return part grouping metadata', (_, actual) => {
+      expect(actual).toEqual(
+        new Map<string, PartGroupingMetadataMapEntry>([
+          ['Conversation', { groupingId: '_:conv:00001', position: 1 }],
+          ['HowTo', { groupingId: '_:how-to:00001', position: 1 }]
+        ]) satisfies ReturnType<typeof getPartGroupingMetadataMap>
+      );
+    });
+});

package/src/reducers/activities/sort/private/getPartGroupingMetadataMap.ts

@@ -0,0 +1,37 @@
+import type { WebChatActivity } from '../../../../types/WebChatActivity';
+import getOrgSchemaMessage from '../../../../utils/getOrgSchemaMessage';
+
+type PartGroupingMetadataMapEntry = {
+  readonly groupingId: string;
+  readonly position: number | undefined;
+};
+
+function getPartGroupingMetadataMap(activity: WebChatActivity): ReadonlyMap<string, PartGroupingMetadataMapEntry> {
+  const metadataMap = new Map<string, PartGroupingMetadataMapEntry>();
+
+  const message = getOrgSchemaMessage(activity.entities || []);
+
+  if (message) {
+    for (const item of message.isPartOf) {
+      if (item['@id']) {
+        const [firstPosition] = message.position;
+
+        for (const type of item['@type']) {
+          metadataMap.set(
+            type,
+            Object.freeze({
+              groupingId: item['@id'],
+              // We do not support non-number position.
+              position: typeof firstPosition === 'number' ? firstPosition : undefined
+            })
+          );
+        }
+      }
+    }
+  }
+
+  return metadataMap;
+}
+
+export default getPartGroupingMetadataMap;
+export type { PartGroupingMetadataMapEntry };

package/src/reducers/activities/sort/private/insertSorted.spec.ts

@@ -0,0 +1,106 @@
+import { scenario } from '@testduet/given-when-then';
+import insertSorted from './insertSorted';
+
+scenario('insert to sorted array', bdd => {
+  bdd
+    .given('a sorted array of [1, 3, 5]', () => [1, 3, 5])
+    .when('inserting 2', array => insertSorted(array, 2, (x, y) => x - y))
+    .then('should return [1, 2, 3, 5]', (_, actual) => {
+      expect(actual).toEqual([1, 2, 3, 5]);
+    });
+
+  bdd
+    .given('a sorted array of [1, 3, 5]', () => [1, 3, 5])
+    .when('inserting 6', array => insertSorted(array, 6, (x, y) => x - y))
+    .then('should return [1, 3, 5, 6]', (_, actual) => {
+      expect(actual).toEqual([1, 3, 5, 6]);
+    });
+
+  bdd
+    .given('a sorted array of [1, 3, 5]', () => [1, 3, 5])
+    .when('inserting 0', array => insertSorted(array, 0, (x, y) => x - y))
+    .then('should return [0, 1, 3, 5]', (_, actual) => {
+      expect(actual).toEqual([0, 1, 3, 5]);
+    });
+
+  bdd
+    .given('an empty array', () => [])
+    .when('inserting 0', array => insertSorted(array, 0, (x, y) => x - y))
+    .then('should return [0]', (_, actual) => {
+      expect(actual).toEqual([0]);
+    });
+
+  bdd
+    .given("a sorted array of ['1b', '2b', '3b']", () => ['1b', '2b', '3b'])
+    .when('inserting 2c with a parseInt comparer', array =>
+      insertSorted(array, '2c', (x, y) => parseInt(x, 10) - parseInt(y, 10))
+    )
+    .then("should return ['1b', '2b', '2c', '3b']", (_, actual) => {
+      expect(actual).toEqual(['1b', '2b', '2c', '3b']);
+    });
+
+  bdd
+    .given("a sorted array of ['1b', '2b', '3b']", () => ['1b', '2b', '3b'])
+    .when('inserting 2a with a parseInt comparer', array =>
+      insertSorted(array, '2a', (x, y) => parseInt(x, 10) - parseInt(y, 10))
+    )
+    .then("should return ['1b', '2b', '2a', '3b']", (_, actual) => {
+      // For items with same weight, the new item should be appended.
+      expect(actual).toEqual(['1b', '2b', '2a', '3b']);
+    });
+});
+
+scenario('insert to sorted array ignoring undefined elements with a custom compareFn', bdd => {
+  function compareFn(x: number | undefined, y: number | undefined): number {
+    return typeof x === 'undefined' || typeof y === 'undefined' ? -1 : x - y;
+  }
+
+  bdd
+    .given('a sorted array of [1, undefined, 3, undefined, 5]', () => [1, undefined, 3, undefined, 5])
+    .when('inserting 2', array => insertSorted(array, 2, compareFn))
+    .then('should return [1, undefined, 2, 3, undefined, 5]', (_, actual) => {
+      expect(actual).toEqual([1, undefined, 2, 3, undefined, 5]);
+    });
+
+  bdd
+    .given('a sorted array of [1, undefined, 3, undefined, 5]', () => [1, undefined, 3, undefined, 5])
+    .when('inserting 4', array => insertSorted(array, 4, compareFn))
+    .then('should return [1, undefined, 3, undefined, 4, 5]', (_, actual) => {
+      expect(actual).toEqual([1, undefined, 3, undefined, 4, 5]);
+    });
+
+  bdd
+    .given('a sorted array of [undefined, 3, undefined]', () => [undefined, 3, undefined])
+    .when('inserting 2', array => insertSorted(array, 2, compareFn))
+    .then('should return [undefined, 2, 3, undefined]', (_, actual) => {
+      expect(actual).toEqual([undefined, 2, 3, undefined]);
+    });
+
+  bdd
+    .given('a sorted array of [undefined, 3, undefined]', () => [undefined, 3, undefined])
+    .when('inserting 4', array => insertSorted(array, 4, compareFn))
+    .then('should return [undefined, 3, undefined, 4]', (_, actual) => {
+      expect(actual).toEqual([undefined, 3, undefined, 4]);
+    });
+
+  bdd
+    .given('a sorted array of [1, 3, 5]', () => [1, 3, 5])
+    .when('inserting undefined', array => insertSorted(array, undefined, compareFn))
+    .then('should return [1, 3, 5, undefined]', (_, actual) => {
+      expect(actual).toEqual([1, 3, 5, undefined]);
+    });
+
+  bdd
+    .given('a sorted array of [1, undefined, 3, undefined, 5]', () => [1, undefined, 3, undefined, 5])
+    .when('inserting undefined', array => insertSorted(array, undefined, compareFn))
+    .then('should return [1, undefined, 3, undefined, 5, undefined]', (_, actual) => {
+      expect(actual).toEqual([1, undefined, 3, undefined, 5, undefined]);
+    });
+
+  bdd
+    .given('an array of [undefined]', () => [undefined])
+    .when('inserting undefined', array => insertSorted(array, undefined, compareFn))
+    .then('should return [undefined, undefined]', (_, actual) => {
+      expect(actual).toEqual([undefined, undefined]);
+    });
+});

package/src/reducers/activities/sort/private/insertSorted.ts

@@ -0,0 +1,18 @@
+import { toSpliced } from '@msinternal/botframework-webchat-base/utils';
+
+/**
+ * Inserts a single item into a sorted array.
+ *
+ * For multiple items, consider other options for efficiency.
+ *
+ * @param sortedArray A sorted array.
+ * @param item Item to be inserted.
+ * @param compareFn Function used to determine the order of the elements. It is expected to return a negative value if the first argument is less than the second argument, zero if they're equal, and a positive value otherwise.
+ * @returns A new sorted array with the new item.
+ */
+export default function insertSorted<T>(sortedArray: readonly T[], item: T, compareFn: (x: T, y: T) => number): T[] {
+  // TODO: Implements `binaryFindIndex()` for better performance.
+  const indexToInsert = sortedArray.findIndex(i => compareFn(i, item) > 0);
+
+  return toSpliced(sortedArray, ~indexToInsert ? indexToInsert : sortedArray.length, 0, item);
+}

package/src/reducers/activities/sort/property/LocalId.ts

@@ -0,0 +1,60 @@
+import { IdentifierSchema, type Identifier } from '@msinternal/botframework-webchat-core-graph';
+import type { Tagged } from 'type-fest';
+import { v4 } from 'uuid';
+import { object, parse, pipe, safeParse, transform, type InferOutput } from 'valibot';
+import type { Activity } from '../types';
+
+const LocalIdSchema = pipe(
+  IdentifierSchema,
+  transform(value => value as Tagged<Identifier, 'local id'>)
+);
+
+type LocalId = InferOutput<typeof LocalIdSchema>;
+
+const ActivityWithLocalIdSchema = object({
+  channelData: object({
+    'webchat:internal:local-id': LocalIdSchema
+  })
+});
+
+function getLocalIdFromActivity(activity: Readonly<Activity>): LocalId {
+  return parse(ActivityWithLocalIdSchema, activity).channelData['webchat:internal:local-id'];
+}
+
+function queryLocalIdFromActivity(activity: Readonly<Activity>): LocalId | undefined {
+  const result = safeParse(ActivityWithLocalIdSchema, activity);
+
+  return result.success ? result.output.channelData['webchat:internal:local-id'] : undefined;
+}
+
+function setLocalIdInActivity(activity: Readonly<Activity>, value: LocalId | undefined): Activity {
+  const nextChannelData = { ...activity.channelData };
+
+  if (typeof value === 'undefined') {
+    delete (nextChannelData as any)['webchat:internal:local-id'];
+  } else {
+    nextChannelData['webchat:internal:local-id'] = parse(LocalIdSchema, value);
+  }
+
+  return {
+    ...activity,
+    channelData: nextChannelData as any
+  };
+}
+
+// TODO: [P1] We can use a UUID v6 (reorder). Then, we can drop `receivedAt`.
+function generateLocalId(): LocalId {
+  return parse(LocalIdSchema, `_:${v4()}`);
+}
+
+function generateLocalIdInActivity(activity: Readonly<Activity>): Activity {
+  if (queryLocalIdFromActivity(activity)) {
+    throw new Error(
+      'botframework-webchat: Cannot generate a new local ID for activity because the activity already has a local ID'
+    );
+  }
+
+  return setLocalIdInActivity(activity, generateLocalId());
+}
+
+export { generateLocalIdInActivity, getLocalIdFromActivity, LocalIdSchema, setLocalIdInActivity, type LocalId };

package/src/reducers/activities/sort/property/Position.ts

@@ -0,0 +1,39 @@
+import { number, object, parse, safeParse, type InferOutput } from 'valibot';
+import type { Activity } from '../types';
+
+const PositionSchema = number('position must be a number');
+
+type Position = InferOutput<typeof PositionSchema>;
+
+const ActivityWithPositionSchema = object({
+  channelData: object({
+    'webchat:internal:position': PositionSchema
+  })
+});
+
+function getPositionFromActivity(activity: Readonly<Activity>): Position {
+  return parse(ActivityWithPositionSchema, activity).channelData['webchat:internal:position'];
+}
+
+function queryPositionFromActivity(activity: Readonly<Activity>): Position | undefined {
+  const result = safeParse(ActivityWithPositionSchema, activity);
+
+  return result.success ? result.output.channelData['webchat:internal:position'] : undefined;
+}
+
+function setPositionInActivity(activity: Readonly<Activity>, value: Position | undefined): Activity {
+  const nextChannelData = { ...activity.channelData };
+
+  if (typeof value === 'undefined') {
+    delete (nextChannelData as any)['webchat:internal:position'];
+  } else {
+    nextChannelData['webchat:internal:position'] = parse(PositionSchema, value);
+  }
+
+  return {
+    ...activity,
+    channelData: nextChannelData as any
+  };
+}
+
+export { getPositionFromActivity, PositionSchema, queryPositionFromActivity, setPositionInActivity, type Position };