@nyaruka/temba-components 0.168.1 → 0.170.0

package/src/live/ContactWatch.ts

@@ -0,0 +1,415 @@
+import { Contact } from '../interfaces';
+import { Events } from '../events/eventRenderers';
+import { getStore } from '../store/Store';
+import { RealtimeSubscription, subscribeToContactHistory } from './Realtime';
+
+/**
+ * Central interest registry for live contact state. Components declare what
+ * they care about - specific event types or '*' for everything - and this
+ * module owns the rest: it holds the single socket subscription per contact
+ * (the firehose on "history:<contact-uuid>"), fetches the contact so watchers
+ * get an initial value without something having to change, and fans each
+ * event out to just the watchers whose interest matches.
+ *
+ *   const watch = watchContact(uuid, [Events.CONTACT_NAME_CHANGED], (event, contact) => {
+ *     ...
+ *   });
+ *   watch.unsubscribe();
+ *
+ * Every delivery hands the watcher the current contact alongside the event
+ * that triggered it, so watchers can read state without knowing where the
+ * data originally came from. The contact is kept current centrally: scalar
+ * events are applied to it directly, while events whose full effect isn't in
+ * the event payload (see refetchTypes) trigger a refetch. Initial values and
+ * refetches arrive through the same handler as live changes, as a delivery
+ * with no event, so watchers have a single code path. The fetch happens on
+ * every (re)subscribe, including after reconnects, so watchers also catch up
+ * on anything missed while offline. When the last watcher for a contact
+ * 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.
+ */
+
+// same shape components previously fetched themselves - urns are expanded and
+// priority ordered so watchers can pick the messaging destination
+const CONTACT_ENDPOINT =
+  '/api/v2/contacts.json?expand_urns=true&urn_order=priority&uuid=';
+
+// how long we wait for an event burst (e.g. one flow sprint updating several
+// fields) to settle before refetching
+const REFETCH_DEBOUNCE = 100;
+
+// a fetch can fail on an otherwise healthy socket, which would leave watchers
+// with no contact at all until something else triggers a fetch - retry a few
+// times, backing off between attempts
+const FETCH_RETRIES = 3;
+const FETCH_RETRY_DELAY = 1000;
+
+// the contact-state events - everything that changes what a contact *is*, as
+// opposed to recording something that happened to them. The default interest
+// for components that render contact data
+export const CONTACT_STATE_TYPES = [
+  Events.CONTACT_NAME_CHANGED,
+  Events.CONTACT_URNS_CHANGED,
+  Events.CONTACT_FIELD_CHANGED,
+  Events.CONTACT_GROUPS_CHANGED,
+  Events.CONTACT_LANGUAGE_CHANGED,
+  Events.CONTACT_STATUS_CHANGED,
+  Events.CONTACT_FLOW_CHANGED,
+  Events.CONTACT_LAST_SEEN_CHANGED
+];
+
+export type ContactEventHandler = (event: any, contact: Contact) => void;
+
+interface Watcher {
+  types: string[] | '*';
+  onEvent: ContactEventHandler;
+}
+
+interface WatchedContact {
+  watchers: Watcher[];
+  sub: RealtimeSubscription;
+  contact: Contact;
+  fetchSeq: number;
+  // fetches in flight - their responses predate anything arriving now, so
+  // events landing while one is outstanding need a refetch to survive
+  fetching: number;
+  refetchTimer: number;
+}
+
+const watched = new Map<string, WatchedContact>();
+
+/**
+ * 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
+ * (the API calls number fields "numeric"). A value that didn't parse as the
+ * field's type serializes as null, same as the API. Returns undefined when
+ * the field definition isn't known, since without it there's no way to tell
+ * which engine value the API would have read.
+ */
+const serializeFieldValue = (key: string, value: any): string | undefined => {
+  if (!value) {
+    return null;
+  }
+  const fieldType = getStore()?.getContactField(key)?.value_type;
+  if (!fieldType) {
+    return undefined;
+  }
+  const engineType = fieldType === 'numeric' ? 'number' : fieldType;
+  const engineValue = value[engineType];
+  return engineValue != null ? String(engineValue) : null;
+};
+
+// how live events patch the cached contact so every delivery carries current
+// state. Returning false means the event couldn't be applied and the contact
+// needs a refetch to be current
+const appliers: {
+  [type: string]: (contact: Contact, event: any) => boolean | void;
+} = {
+  [Events.CONTACT_NAME_CHANGED]: (contact, event) => {
+    contact.name = event.name;
+  },
+  [Events.CONTACT_LANGUAGE_CHANGED]: (contact, event) => {
+    contact.language = event.language;
+  },
+  [Events.CONTACT_STATUS_CHANGED]: (contact, event) => {
+    contact.status = event.status;
+  },
+  [Events.CONTACT_FLOW_CHANGED]: (contact, event) => {
+    contact.flow = event.flow || null;
+  },
+  [Events.CONTACT_LAST_SEEN_CHANGED]: (contact, event) => {
+    // last seen only ever moves forward - ignore out of order deliveries
+    if (
+      !contact.last_seen_on ||
+      new Date(event.last_seen_on) > new Date(contact.last_seen_on)
+    ) {
+      contact.last_seen_on = event.last_seen_on;
+    }
+  },
+  [Events.CONTACT_FIELD_CHANGED]: (contact, event) => {
+    const key = event.field?.key;
+    if (!key) {
+      return;
+    }
+    const value = serializeFieldValue(key, event.value);
+    if (value === undefined) {
+      // no field definition to serialize against - don't guess at a value
+      return false;
+    }
+    // replace rather than mutate so earlier deliveries keep their values
+    contact.fields = { ...contact.fields, [key]: value };
+  },
+  [Events.CONTACT_GROUPS_CHANGED]: (contact, event) => {
+    const added = event.groups_added || [];
+    const removed = new Set(
+      (event.groups_removed || []).map((group: any) => group.uuid)
+    );
+    contact.groups = [
+      ...(contact.groups || []).filter(
+        (group) =>
+          !removed.has(group.uuid) &&
+          !added.some((a: any) => a.uuid === group.uuid)
+      ),
+      // group references can arrive without a name, but consumers sort on it
+      ...added.map((group: any) => ({
+        uuid: group.uuid,
+        name: group.name || ''
+      }))
+    ];
+  }
+};
+
+// events whose new state can't be patched into the cached contact from the
+// event alone - urns arrive as raw strings while the contact carries them
+// expanded with their channels, which picking a messaging destination needs.
+// Their arrival triggers a (debounced) refetch, which re-primes every
+// watcher with current values.
+const refetchTypes = new Set<string>([Events.CONTACT_URNS_CHANGED]);
+
+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);
+  }
+};
+
+/**
+ * Hands every non-wildcard watcher the current contact as an eventless
+ * delivery.
+ */
+const primeAll = (entry: WatchedContact) => {
+  for (const watcher of [...entry.watchers]) {
+    if (watcher.types !== '*') {
+      deliver(watcher, null, entry.contact);
+    }
+  }
+};
+
+const clearRefetch = (entry: WatchedContact) => {
+  if (entry.refetchTimer) {
+    window.clearTimeout(entry.refetchTimer);
+    entry.refetchTimer = null;
+  }
+};
+
+// a fetch that couldn't happen leaves watchers with no value at all, so try
+// again with a backoff - anything that supersedes us in the meantime (a newer
+// fetch, a local write, the last watcher leaving) cancels it
+const retryFetch = (
+  uuid: string,
+  entry: WatchedContact,
+  attempt: number,
+  seq: number
+) => {
+  if (attempt >= FETCH_RETRIES) {
+    return;
+  }
+
+  window.setTimeout(
+    () => {
+      if (watched.get(uuid) === entry && entry.fetchSeq === seq) {
+        fetchContact(uuid, entry, attempt + 1);
+      }
+    },
+    FETCH_RETRY_DELAY * Math.pow(2, attempt)
+  );
+};
+
+const fetchContact = (uuid: string, entry: WatchedContact, attempt = 0) => {
+  const store = getStore();
+  if (!store) {
+    // the store element can be added to the page after the components that
+    // watch through it - come back for it instead of leaving watchers empty
+    // for good. Claim a seq like a real fetch does so a later call supersedes
+    // this chain instead of running alongside it
+    retryFetch(uuid, entry, attempt, ++entry.fetchSeq);
+    return;
+  }
+
+  // a pending debounce would only land behind us with the same data
+  clearRefetch(entry);
+
+  const seq = ++entry.fetchSeq;
+  entry.fetching++;
+  store
+    // skip the store cache in both directions - we always want current data
+    // and the cache holds this url in a different shape for components that
+    // still fetch it themselves
+    .getUrl(`${CONTACT_ENDPOINT}${uuid}`, { force: true, skipCache: true })
+    // two-argument form so a throw out of the success handler isn't taken
+    // for a failed fetch and retried on top of itself
+    .then(
+      (response) => {
+        entry.fetching--;
+
+        // ignore responses that arrive after everyone left or a newer fetch
+        if (watched.get(uuid) !== entry || entry.fetchSeq !== seq) {
+          return;
+        }
+
+        const contact = response.json?.results?.[0] || null;
+        if (!contact) {
+          return;
+        }
+
+        entry.contact = contact;
+        primeAll(entry);
+      },
+      () => {
+        entry.fetching--;
+
+        if (watched.get(uuid) !== entry || entry.fetchSeq !== seq) {
+          return;
+        }
+
+        retryFetch(uuid, entry, attempt, seq);
+      }
+    );
+};
+
+const scheduleRefetch = (uuid: string, entry: WatchedContact) => {
+  clearRefetch(entry);
+  entry.refetchTimer = window.setTimeout(() => {
+    entry.refetchTimer = null;
+    if (watched.get(uuid) === entry) {
+      fetchContact(uuid, entry);
+    }
+  }, REFETCH_DEBOUNCE);
+};
+
+const handleEvent = (uuid: string, entry: WatchedContact, event: any) => {
+  const apply = appliers[event.type];
+  const applied = entry.contact && apply ? apply(entry.contact, event) : null;
+
+  // a state event we couldn't fully apply leaves the contact stale - there
+  // 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);
+  }
+
+  for (const watcher of [...entry.watchers]) {
+    if (matches(watcher, event.type)) {
+      deliver(watcher, event, entry.contact);
+    }
+  }
+};
+
+export const watchContact = (
+  uuid: string,
+  types: string[] | '*',
+  onEvent: ContactEventHandler
+): RealtimeSubscription => {
+  let entry = watched.get(uuid);
+  if (!entry) {
+    const newEntry: WatchedContact = {
+      watchers: [],
+      sub: null,
+      contact: null,
+      fetchSeq: 0,
+      fetching: 0,
+      refetchTimer: null
+    };
+    watched.set(uuid, newEntry);
+    newEntry.sub = subscribeToContactHistory(
+      uuid,
+      null,
+      (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)
+    );
+    entry = newEntry;
+  }
+
+  const watcher: Watcher = { types, onEvent };
+  entry.watchers.push(watcher);
+
+  // 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);
+      }
+    });
+  }
+
+  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);
+      }
+    }
+  };
+};
+
+/**
+ * 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
+ * so every watcher on the page reflects an edit immediately, without waiting
+ * for the change to echo back over the socket. A no-op for unwatched
+ * contacts.
+ */
+export const updateContact = (uuid: string, contact: Contact) => {
+  const entry = watched.get(uuid);
+  if (entry) {
+    // discard any in-flight fetch and any pending refetch - both started
+    // before this write and could land after it with pre-write data
+    entry.fetchSeq++;
+    clearRefetch(entry);
+    // the caller keeps using the object they handed us (it's their data and
+    // the store's cache entry) while appliers patch ours in place - copy the
+    // parts they touch so a live event can't reach back into it
+    entry.contact = {
+      ...contact,
+      groups: (contact.groups || []).map((group) => ({ ...group })),
+      fields: { ...contact.fields }
+    };
+    primeAll(entry);
+  }
+};
+
+/**
+ * Forces a refetch of a watched contact, re-priming its watchers. A no-op
+ * for unwatched contacts.
+ */
+export const refreshContact = (uuid: string) => {
+  const entry = watched.get(uuid);
+  if (entry) {
+    fetchContact(uuid, entry);
+  }
+};
+
+const dropEntry = (uuid: string, entry: WatchedContact) => {
+  watched.delete(uuid);
+  clearRefetch(entry);
+  entry.sub.unsubscribe();
+};
+
+// for tests - real pages just unwatch
+export const resetContactWatches = () => {
+  for (const [uuid, entry] of [...watched.entries()]) {
+    entry.watchers.length = 0;
+    dropEntry(uuid, entry);
+  }
+};

package/src/locales/es.ts

@@ -14,6 +14,7 @@
 'sbc913d7dc0f33877': `to add`,
 's7722a91d3a512442': str`Last seen ${0}`,
 's22965bb9808befb0': `Interrupt`,
+'s6dbbe2646b239ca5': `Closed`,
 's122d4de68bcfcdf4': `It's okay to restart`,
 's3eb2567092b4d7c1': `from the beginning`,
 's28f37776b3901438': `It's okay to interrupt`,

package/src/locales/fr.ts

@@ -14,6 +14,7 @@
 'sbc913d7dc0f33877': `to add`,
 's7722a91d3a512442': str`Last seen ${0}`,
 's22965bb9808befb0': `Interrupt`,
+'s6dbbe2646b239ca5': `Closed`,
 's122d4de68bcfcdf4': `It's okay to restart`,
 's3eb2567092b4d7c1': `from the beginning`,
 's28f37776b3901438': `It's okay to interrupt`,

package/src/locales/pt.ts

@@ -14,6 +14,7 @@
 'sbc913d7dc0f33877': `to add`,
 's7722a91d3a512442': str`Last seen ${0}`,
 's22965bb9808befb0': `Interrupt`,
+'s6dbbe2646b239ca5': `Closed`,
 's122d4de68bcfcdf4': `It's okay to restart`,
 's3eb2567092b4d7c1': `from the beginning`,
 's28f37776b3901438': `It's okay to interrupt`,

package/src/simulator/Simulator.ts

@@ -630,6 +630,7 @@ export class Simulator extends RapidElement {
       }
       .message-input input {
         flex: 1;
+        min-width: 0;
         border: 1px solid #c6c6c857;
         border-radius: 20px;
         padding: 8px 15px;

package/temba-modules.ts

@@ -30,13 +30,11 @@ import { ContactUrn } from './src/display/ContactUrn';
 import { ContactFields } from './src/live/ContactFields';
 import { ContactFieldEditor } from './src/live/ContactFieldEditor';
 
-import { ContactBadges } from './src/live/ContactBadges';
 import { ContactTimeline } from './src/live/ContactTimeline';
 import { CampaignEvents } from './src/live/CampaignEvents';
 import { TembaSlider } from './src/form/TembaSlider';
 import { RunList } from './src/list/RunList';
 import { FlowStoreElement } from './src/store/FlowStoreElement';
-import { ContactNameFetch } from './src/live/ContactNameFetch';
 import { DatePicker } from './src/form/DatePicker';
 import { FieldManager } from './src/live/FieldManager';
 import { SortableList } from './src/list/SortableList';
@@ -125,7 +123,6 @@ addCustomElement('temba-button', Button);
 addCustomElement('temba-omnibox', Omnibox);
 addCustomElement('temba-tip', Tip);
 addCustomElement('temba-contact-name', ContactName);
-addCustomElement('temba-contact-name-fetch', ContactNameFetch);
 addCustomElement('temba-contact-field', ContactFieldEditor);
 addCustomElement('temba-contact-fields', ContactFields);
 addCustomElement('temba-field-manager', FieldManager);
@@ -162,7 +159,6 @@ addCustomElement('temba-icon', VectorIcon);
 addCustomElement('temba-dropdown', Dropdown);
 addCustomElement('temba-tabs', TabPane);
 addCustomElement('temba-tab', Tab);
-addCustomElement('temba-contact-badges', ContactBadges);
 addCustomElement('temba-contact-timeline', ContactTimeline);
 addCustomElement('temba-campaign-events', CampaignEvents);
 addCustomElement('temba-slider', TembaSlider);

package/xliff/es.xlf

@@ -42,6 +42,9 @@
 <trans-unit id="s7722a91d3a512442">
   <source>Last seen <x id="0" equiv-text="${lastSeen.duration}"/></source>
 </trans-unit>
+<trans-unit id="s6dbbe2646b239ca5">
+  <source>Closed</source>
+</trans-unit>
 </body>
 </file>
 </xliff>

package/xliff/fr.xlf

@@ -41,6 +41,9 @@
 <trans-unit id="s7722a91d3a512442">
   <source>Last seen <x id="0" equiv-text="${lastSeen.duration}"/></source>
 </trans-unit>
+<trans-unit id="s6dbbe2646b239ca5">
+  <source>Closed</source>
+</trans-unit>
 </body>
 </file>
 </xliff>

package/xliff/pt.xlf

@@ -41,6 +41,9 @@
 <trans-unit id="s7722a91d3a512442">
   <source>Last seen <x id="0" equiv-text="${lastSeen.duration}"/></source>
 </trans-unit>
+<trans-unit id="s6dbbe2646b239ca5">
+  <source>Closed</source>
+</trans-unit>
 </body>
 </file>
 </xliff>