@nyaruka/temba-components 0.171.0 → 0.172.0

package/src/live/ContactWatch.ts

@@ -1,7 +1,19 @@
 import { Contact } from '../interfaces';
 import { Events } from '../events/eventRenderers';
 import { getStore } from '../store/Store';
-import { RealtimeSubscription, subscribeToContactHistory } from './Realtime';
+import { Watchers } from './Watchers';
+import {
+  ContactFieldChangedEvent,
+  ContactFlowChangedEvent,
+  ContactGroupsChangedEvent,
+  ContactHistoryEvent,
+  ContactLanguageChangedEvent,
+  ContactLastSeenChangedEvent,
+  ContactNameChangedEvent,
+  ContactStatusChangedEvent,
+  RealtimeSubscription,
+  subscribeToContactHistory
+} from './Realtime';
 
 /**
  * Central interest registry for live contact state. Components declare what
@@ -28,7 +40,12 @@ import { RealtimeSubscription, subscribeToContactHistory } from './Realtime';
  * unsubscribes the socket subscription and cached contact are dropped.
  *
  * Wildcard watchers are event-stream consumers (e.g. chat renders history) -
- * they get every live event but no eventless deliveries.
+ * they get every live event but no eventless deliveries, and an entry with
+ * only those holds no contact and fetches nothing. They keep their own copy
+ * instead, applying events to it with applyContactEvent so how an event
+ * changes a contact is still defined in one place. Any watcher can pass
+ * onSubscribed to be told when the channel goes live, which is where a
+ * stream consumer catches up on what it missed while offline.
  */
 
 // same shape components previously fetched themselves - urns are expanded and
@@ -60,15 +77,19 @@ export const CONTACT_STATE_TYPES = [
   Events.CONTACT_LAST_SEEN_CHANGED
 ];
 
-export type ContactEventHandler = (event: any, contact: Contact) => void;
+export type ContactEventHandler = (
+  event: ContactHistoryEvent | null,
+  contact: Contact
+) => void;
 
 interface Watcher {
   types: string[] | '*';
   onEvent: ContactEventHandler;
+  onSubscribed?: () => void;
 }
 
 interface WatchedContact {
-  watchers: Watcher[];
+  watchers: Watchers<Watcher>;
   sub: RealtimeSubscription;
   contact: Contact;
   fetchSeq: number;
@@ -76,10 +97,19 @@ interface WatchedContact {
   // events landing while one is outstanding need a refetch to survive
   fetching: number;
   refetchTimer: number;
+  // whether the channel is live, so watchers joining an already-subscribed
+  // channel still get their initial catch-up call
+  subscribed: boolean;
 }
 
 const watched = new Map<string, WatchedContact>();
 
+const newWatchers = (watcher: Watcher): Watchers<Watcher> => {
+  const watchers = new Watchers<Watcher>('contact watcher');
+  watchers.add(watcher);
+  return watchers;
+};
+
 /**
  * Serializes an engine field value from an event the way the read API
  * would - both read the same engine value dict, keyed by the field's type
@@ -107,19 +137,28 @@ const serializeFieldValue = (key: string, value: any): string | undefined => {
 const appliers: {
   [type: string]: (contact: Contact, event: any) => boolean | void;
 } = {
-  [Events.CONTACT_NAME_CHANGED]: (contact, event) => {
+  [Events.CONTACT_NAME_CHANGED]: (contact, event: ContactNameChangedEvent) => {
     contact.name = event.name;
   },
-  [Events.CONTACT_LANGUAGE_CHANGED]: (contact, event) => {
+  [Events.CONTACT_LANGUAGE_CHANGED]: (
+    contact,
+    event: ContactLanguageChangedEvent
+  ) => {
     contact.language = event.language;
   },
-  [Events.CONTACT_STATUS_CHANGED]: (contact, event) => {
+  [Events.CONTACT_STATUS_CHANGED]: (
+    contact,
+    event: ContactStatusChangedEvent
+  ) => {
     contact.status = event.status;
   },
-  [Events.CONTACT_FLOW_CHANGED]: (contact, event) => {
+  [Events.CONTACT_FLOW_CHANGED]: (contact, event: ContactFlowChangedEvent) => {
     contact.flow = event.flow || null;
   },
-  [Events.CONTACT_LAST_SEEN_CHANGED]: (contact, event) => {
+  [Events.CONTACT_LAST_SEEN_CHANGED]: (
+    contact,
+    event: ContactLastSeenChangedEvent
+  ) => {
     // last seen only ever moves forward - ignore out of order deliveries
     if (
       !contact.last_seen_on ||
@@ -128,7 +167,10 @@ const appliers: {
       contact.last_seen_on = event.last_seen_on;
     }
   },
-  [Events.CONTACT_FIELD_CHANGED]: (contact, event) => {
+  [Events.CONTACT_FIELD_CHANGED]: (
+    contact,
+    event: ContactFieldChangedEvent
+  ) => {
     const key = event.field?.key;
     if (!key) {
       return;
@@ -141,19 +183,21 @@ const appliers: {
     // replace rather than mutate so earlier deliveries keep their values
     contact.fields = { ...contact.fields, [key]: value };
   },
-  [Events.CONTACT_GROUPS_CHANGED]: (contact, event) => {
+  [Events.CONTACT_GROUPS_CHANGED]: (
+    contact,
+    event: ContactGroupsChangedEvent
+  ) => {
     const added = event.groups_added || [];
     const removed = new Set(
-      (event.groups_removed || []).map((group: any) => group.uuid)
+      (event.groups_removed || []).map((group) => group.uuid)
     );
     contact.groups = [
       ...(contact.groups || []).filter(
         (group) =>
-          !removed.has(group.uuid) &&
-          !added.some((a: any) => a.uuid === group.uuid)
+          !removed.has(group.uuid) && !added.some((a) => a.uuid === group.uuid)
       ),
       // group references can arrive without a name, but consumers sort on it
-      ...added.map((group: any) => ({
+      ...added.map((group) => ({
         uuid: group.uuid,
         name: group.name || ''
       }))
@@ -172,14 +216,31 @@ const matches = (watcher: Watcher, type: string): boolean => {
   return watcher.types === '*' || watcher.types.includes(type);
 };
 
-// watchers are page components we don't control - one of them throwing can't
-// be allowed to cost the others their delivery
-const deliver = (watcher: Watcher, event: any, contact: Contact) => {
-  try {
-    watcher.onEvent(event, contact);
-  } catch (error) {
-    console.error('contact watcher failed', error);
+/**
+ * Whether anyone is watching this contact's *state*. Wildcard watchers are
+ * stream consumers - they take the events and keep their own view of the
+ * contact - so an entry with only those has no contact to hold current and
+ * nothing to fetch.
+ */
+const needsContact = (entry: WatchedContact): boolean => {
+  return entry.watchers.some((watcher) => watcher.types !== '*');
+};
+
+/**
+ * Applies a live contact event to a contact, the same way the registry
+ * applies it to the one it holds. Exposed for stream consumers that keep
+ * their own copy, so how an event changes a contact is defined once.
+ * Returns false when the event couldn't be applied.
+ */
+export const applyContactEvent = (
+  contact: Contact,
+  event: ContactHistoryEvent
+): boolean | void => {
+  const apply = appliers[event.type];
+  if (!contact || !apply) {
+    return;
   }
+  return apply(contact, event);
 };
 
 /**
@@ -187,11 +248,10 @@ const deliver = (watcher: Watcher, event: any, contact: Contact) => {
  * delivery.
  */
 const primeAll = (entry: WatchedContact) => {
-  for (const watcher of [...entry.watchers]) {
-    if (watcher.types !== '*') {
-      deliver(watcher, null, entry.contact);
-    }
-  }
+  entry.watchers.each(
+    (watcher) => watcher.onEvent(null, entry.contact),
+    (watcher) => watcher.types !== '*'
+  );
 };
 
 const clearRefetch = (entry: WatchedContact) => {
@@ -286,7 +346,11 @@ const scheduleRefetch = (uuid: string, entry: WatchedContact) => {
   }, REFETCH_DEBOUNCE);
 };
 
-const handleEvent = (uuid: string, entry: WatchedContact, event: any) => {
+const handleEvent = (
+  uuid: string,
+  entry: WatchedContact,
+  event: ContactHistoryEvent
+) => {
   const apply = appliers[event.type];
   const applied = entry.contact && apply ? apply(entry.contact, event) : null;
 
@@ -294,34 +358,58 @@ const handleEvent = (uuid: string, entry: WatchedContact, event: any) => {
   // was no snapshot to patch, a fetch that predates the event is still in
   // flight, or the applier couldn't resolve what it needed. Scheduling ahead
   // of the fan-out keeps a throwing watcher from costing us the refetch, and
-  // the debounce collapses a burst into a single fetch
-  const stale =
-    !!apply && (!entry.contact || entry.fetching > 0 || applied === false);
-  if (stale || refetchTypes.has(event.type)) {
-    scheduleRefetch(uuid, entry);
+  // the debounce collapses a burst into a single fetch. Entries nobody needs
+  // a contact from have nothing to keep current
+  if (needsContact(entry)) {
+    const stale =
+      !!apply && (!entry.contact || entry.fetching > 0 || applied === false);
+    if (stale || refetchTypes.has(event.type)) {
+      scheduleRefetch(uuid, entry);
+    }
   }
 
-  for (const watcher of [...entry.watchers]) {
-    if (matches(watcher, event.type)) {
-      deliver(watcher, event, entry.contact);
-    }
+  entry.watchers.each(
+    (watcher) => watcher.onEvent(event, entry.contact),
+    (watcher) => matches(watcher, event.type)
+  );
+};
+
+/**
+ * A (re)subscribe on the contact's channel. Watchers that render contact
+ * state get a fresh fetch; every watcher that asked for it gets told, so
+ * stream consumers can fetch whatever they missed while we were away.
+ */
+const handleSubscribed = (uuid: string, entry: WatchedContact) => {
+  entry.subscribed = true;
+  if (needsContact(entry)) {
+    fetchContact(uuid, entry);
   }
+  entry.watchers.each(
+    (watcher) => watcher.onSubscribed(),
+    (watcher) => !!watcher.onSubscribed
+  );
 };
 
 export const watchContact = (
   uuid: string,
   types: string[] | '*',
-  onEvent: ContactEventHandler
+  onEvent: ContactEventHandler,
+  onSubscribed?: () => void
 ): RealtimeSubscription => {
-  let entry = watched.get(uuid);
+  const entry = watched.get(uuid);
+  const watcher: Watcher = { types, onEvent, onSubscribed };
+
   if (!entry) {
     const newEntry: WatchedContact = {
-      watchers: [],
+      // registered before we subscribe so the first (re)subscribe already
+      // knows whether anyone needs a contact held for them
+      watchers: newWatchers(watcher),
       sub: null,
       contact: null,
       fetchSeq: 0,
       fetching: 0,
-      refetchTimer: null
+      refetchTimer: null,
+      subscribed: false
     };
     watched.set(uuid, newEntry);
     newEntry.sub = subscribeToContactHistory(
@@ -330,39 +418,54 @@ export const watchContact = (
       (event) => handleEvent(uuid, newEntry, event),
       // fires on every (re)subscribe incl. after reconnects - (re)fetch so
       // watchers see anything that changed while we weren't listening
-      () => fetchContact(uuid, newEntry)
+      () => handleSubscribed(uuid, newEntry)
     );
-    entry = newEntry;
+    return unwatch(uuid, newEntry, watcher);
   }
 
-  const watcher: Watcher = { types, onEvent };
-  entry.watchers.push(watcher);
+  entry.watchers.add(watcher);
+
+  // a watcher that renders contact state joining an entry that was holding
+  // none (only stream consumers so far) needs one fetched for it. On a
+  // channel that isn't live yet the pending (re)subscribe covers it
+  if (types !== '*' && entry.subscribed && !entry.contact && !entry.fetching) {
+    fetchContact(uuid, entry);
+  }
 
   // late joiners on an already-fetched contact get their initial delivery
   // without waiting for another fetch - async so it mirrors the fetch path
   if (entry.contact && types !== '*') {
     const contact = entry.contact;
-    Promise.resolve().then(() => {
-      if (entry.watchers.includes(watcher)) {
-        deliver(watcher, null, contact);
-      }
-    });
+    entry.watchers.prime(watcher, () => watcher.onEvent(null, contact));
   }
 
-  return {
-    unsubscribe: () => {
-      const index = entry.watchers.indexOf(watcher);
-      if (index < 0) {
-        return;
-      }
-      entry.watchers.splice(index, 1);
-      if (entry.watchers.length === 0) {
-        dropEntry(uuid, entry);
-      }
-    }
-  };
+  // and joiners on an already-live channel get their initial catch-up call,
+  // which they'd otherwise wait for a reconnect to see
+  if (entry.subscribed && onSubscribed) {
+    entry.watchers.prime(watcher, () => watcher.onSubscribed());
+  }
+
+  return unwatch(uuid, entry, watcher);
 };
 
+const unwatch = (
+  uuid: string,
+  entry: WatchedContact,
+  watcher: Watcher
+): RealtimeSubscription => ({
+  unsubscribe: () => {
+    if (entry.watchers.remove(watcher) && entry.watchers.size === 0) {
+      dropEntry(uuid, entry);
+    } else if (!needsContact(entry)) {
+      // only stream consumers left, and nothing keeps their contact current -
+      // holding onto this one would leave it drifting until a state watcher
+      // joined later and got primed with the drift
+      entry.contact = null;
+      clearRefetch(entry);
+    }
+  }
+});
+
 /**
  * Pushes a fresh copy of a contact into the registry, priming its watchers.
  * Components that write contact changes call this with the server's response
@@ -409,7 +512,7 @@ const dropEntry = (uuid: string, entry: WatchedContact) => {
 // for tests - real pages just unwatch
 export const resetContactWatches = () => {
   for (const [uuid, entry] of [...watched.entries()]) {
-    entry.watchers.length = 0;
+    entry.watchers.clear();
     dropEntry(uuid, entry);
   }
 };

package/src/live/Realtime.ts

@@ -1,4 +1,6 @@
-import { Notification } from '../interfaces';
+import { Notification, ObjectReference, User } from '../interfaces';
+import { Events } from '../events/eventRenderers';
+import type { StoreAsset } from '../store/Store';
 import {
   PublicationHandler,
   SocketSubscription,
@@ -9,18 +11,137 @@ import {
  * Typed access to our realtime topics. SocketService owns the shared
  * connection and per-channel fan-out; this module owns how topics map to
  * channel names, including the page identity (org and user uuids) needed to
- * address user-scoped channels.
+ * address user-scoped channels, and what each topic publishes.
  *
  * The identity arrives via temba-store (hydrated from the page template), so
  * user-scoped subscriptions requested before the store mounts are queued and
  * activate when the context is set. On pages with no authenticated context
  * they simply never activate.
+ *
+ * Payload types below describe the wire, which is raw JSON - timestamps are
+ * strings here even where the rendered equivalents in events.ts carry Dates.
  */
 
 export interface RealtimeSubscription {
   unsubscribe(): void;
 }
 
+/** Anything published on any of our topics. */
+export interface RealtimeEvent {
+  type: string;
+}
+
+/**
+ * org:<org-uuid> - workspace-wide state every component on the page shares.
+ * An asset changed somewhere, so anything displaying it can update.
+ */
+export interface AssetChangedEvent extends RealtimeEvent {
+  type: 'asset_changed';
+  asset: StoreAsset;
+}
+
+export type OrganizationEvent = AssetChangedEvent;
+
+/**
+ * flow:<flow-uuid> - published once per committed sprint batch while a flow
+ * is running. It carries no counts, it just says they moved: the editor reads
+ * the current numbers over http when it sees one.
+ */
+export interface FlowActivityEvent extends RealtimeEvent {
+  type: 'activity';
+}
+
+export type FlowEvent = FlowActivityEvent;
+
+/**
+ * history:<contact-uuid> and history:<contact-uuid>:<ticket-uuid> - the
+ * engine's contact events (the payloads in events.ts, before their dates are
+ * parsed) plus the ephemeral ones below, which are never persisted.
+ */
+export interface ContactHistoryEvent extends RealtimeEvent {
+  uuid?: string;
+  created_on?: string;
+  _user?: User;
+  // the rest of the payload varies by type. The contact-state events - the
+  // ones we read fields off rather than hand straight to the renderers - are
+  // typed below; events.ts describes the rendered shape of the others.
+  // unknown rather than any, so reading a field nobody declared is a type
+  // error at the point of use instead of silently spreading
+  [key: string]: unknown;
+}
+
+/**
+ * The events that change what a contact *is*, as opposed to recording
+ * something that happened to them. These are the ones ContactWatch applies to
+ * the contact it holds, so their payloads are what a server-side rename would
+ * break.
+ */
+export interface ContactNameChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_NAME_CHANGED;
+  name: string;
+}
+
+export interface ContactLanguageChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_LANGUAGE_CHANGED;
+  language: string;
+}
+
+export interface ContactStatusChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_STATUS_CHANGED;
+  status: string;
+}
+
+export interface ContactFlowChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_FLOW_CHANGED;
+  flow: ObjectReference | null;
+}
+
+export interface ContactLastSeenChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_LAST_SEEN_CHANGED;
+  last_seen_on: string;
+}
+
+export interface ContactFieldChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_FIELD_CHANGED;
+  field: { key: string; name: string };
+  // engine field values always carry text; typed representations are present
+  // when the value parses as that type (see goflow's Value)
+  value: { text: string; datetime?: string; number?: string } | null;
+}
+
+export interface ContactGroupsChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_GROUPS_CHANGED;
+  groups_added?: ObjectReference[];
+  groups_removed?: ObjectReference[];
+}
+
+export interface ContactURNsChangedEvent extends ContactHistoryEvent {
+  type: Events.CONTACT_URNS_CHANGED;
+  urns: string[];
+}
+
+export type ContactStateEvent =
+  | ContactNameChangedEvent
+  | ContactLanguageChangedEvent
+  | ContactStatusChangedEvent
+  | ContactFlowChangedEvent
+  | ContactLastSeenChangedEvent
+  | ContactFieldChangedEvent
+  | ContactGroupsChangedEvent
+  | ContactURNsChangedEvent;
+
+/**
+ * Published by agents as they compose, and echoed back to the publisher, so
+ * consumers filter out their own by _user.
+ */
+export interface TypingEvent extends ContactHistoryEvent {
+  type: Events.TYPING_STARTED | Events.TYPING_STOPPED;
+  direction?: string;
+  // whatsapp expresses typing as an operation on the contact's last incoming
+  // message, so publications carry its external id when we have one
+  msg_external_id?: string;
+}
+
 export interface RealtimeContext {
   org: string;
   user: string;
@@ -119,10 +240,14 @@ export const subscribeToNotifications = (
  * Workspace-wide state changes shared by every component on the page.
  */
 export const subscribeToOrganization = (
-  onEvent: (event: any) => void,
+  onEvent: (event: OrganizationEvent) => void,
   onSubscribed?: () => void
 ): RealtimeSubscription => {
-  return subscribeWhenReady((ctx) => `org:${ctx.org}`, onEvent, onSubscribed);
+  return subscribeWhenReady(
+    (ctx) => `org:${ctx.org}`,
+    (data) => onEvent(data as OrganizationEvent),
+    onSubscribed
+  );
 };
 
 /**
@@ -131,10 +256,14 @@ export const subscribeToOrganization = (
  */
 export const subscribeToFlow = (
   flow: string,
-  onEvent: (event: any) => void,
+  onEvent: (event: FlowEvent) => void,
   onSubscribed?: () => void
 ): RealtimeSubscription => {
-  return subscribeToSocket(`flow:${flow}`, onEvent, onSubscribed);
+  return subscribeToSocket(
+    `flow:${flow}`,
+    (data) => onEvent(data as FlowEvent),
+    onSubscribed
+  );
 };
 
 /**
@@ -144,12 +273,12 @@ export const subscribeToFlow = (
 export const subscribeToContactHistory = (
   contact: string,
   ticket: string | null,
-  onEvent: (event: any) => void,
+  onEvent: (event: ContactHistoryEvent) => void,
   onSubscribed?: () => void
 ): RealtimeSubscription => {
   return subscribeToSocket(
     ticket ? `history:${contact}:${ticket}` : `history:${contact}`,
-    onEvent,
+    (data) => onEvent(data as ContactHistoryEvent),
     onSubscribed
   );
 };