@visns-studio/visns-components 6.6.3 → 6.15.0

package/src/components/sms/smsHelpers.js

@@ -0,0 +1,1075 @@
+/**
+ * Everything the messaging UI knows that does not need React.
+ *
+ * Number formatting, GSM-7 vs UCS-2 segment counting, relative times, day
+ * grouping and the small list merges the live updates run through. Kept in a
+ * plain `.js` module with no JSX and no DOM so `node --test` can import it
+ * directly — the same split the vault and the call queue already use.
+ */
+
+/* ------------------------------------------------------------------ numbers */
+
+/**
+ * Country codes worth recognising by sight.
+ *
+ * Deliberately short. Australian numbers are formatted properly below; this
+ * list only exists so the handful of overseas numbers a Perth advice firm
+ * actually messages (New Zealand, the UK, Singapore, the US) get their code
+ * split off rather than swallowed into the first group of digits. Anything
+ * not listed falls back to a two-digit code, which is the commonest length.
+ */
+const COUNTRY_CODES = [
+    '1',
+    '7',
+    '20', '27', '30', '31', '32', '33', '34', '36', '39', '40', '41', '43',
+    '44', '45', '46', '47', '48', '49', '51', '52', '53', '54', '55', '56',
+    '57', '58', '60', '62', '63', '64', '65', '66', '81', '82', '84', '86',
+    '90', '91', '92', '93', '94', '95', '98',
+    '212', '213', '234', '351', '352', '353', '354', '358', '359', '370',
+    '380', '385', '386', '420', '421', '852', '853', '855', '856', '880',
+    '886', '960', '961', '962', '963', '964', '965', '966', '967', '968',
+    '971', '972', '973', '974', '975', '976', '977', '992', '993', '994',
+    '995', '998',
+];
+
+/** Strip the punctuation people type into a phone field. */
+const compactNumber = (value) =>
+    String(value ?? '')
+        .trim()
+        .replace(/[\s()\-.‐-―]/g, '');
+
+/**
+ * Does this read as a phone number at all?
+ *
+ * Used by the compose field to decide between "send to this number" and "keep
+ * searching for a client". Deliberately loose about punctuation and strict
+ * about content: a `+`, then digits, and nothing else.
+ */
+export const looksLikeNumber = (value) => {
+    const compact = compactNumber(value);
+
+    return /^\+?\d{6,17}$/.test(compact);
+};
+
+/** Group a run of digits from the left in threes, absorbing a short tail. */
+const groupThrees = (digits) => {
+    const groups = [];
+
+    for (let index = 0; index < digits.length; index += 3) {
+        groups.push(digits.slice(index, index + 3));
+    }
+
+    // A trailing group of one or two digits reads as a typo. Fold it back into
+    // its neighbour so the last block is four or five rather than "555 0 123".
+    if (groups.length > 1 && groups[groups.length - 1].length < 3) {
+        const tail = groups.pop();
+
+        groups[groups.length - 1] += tail;
+    }
+
+    return groups.join(' ');
+};
+
+/** `+14155550123` -> `+1 415 555 0123`. */
+const formatInternational = (compact) => {
+    const digits = compact.replace(/^\+/, '');
+    // Longest match wins, so `353` is not read as `35`.
+    const code =
+        [3, 2, 1]
+            .map((length) => digits.slice(0, length))
+            .find((candidate) => COUNTRY_CODES.includes(candidate)) ??
+        digits.slice(0, 2);
+
+    return `+${code} ${groupThrees(digits.slice(code.length))}`.trim();
+};
+
+/** The Australian national significant number, formatted the local way. */
+const formatAustralian = (national) => {
+    // Mobile: 04XX XXX XXX.
+    if (/^4\d{8}$/.test(national)) {
+        return `0${national.slice(0, 3)} ${national.slice(3, 6)} ${national.slice(6)}`;
+    }
+
+    // Landline: (0X) XXXX XXXX.
+    if (/^[2378]\d{8}$/.test(national)) {
+        return `(0${national[0]}) ${national.slice(1, 5)} ${national.slice(5)}`;
+    }
+
+    // 1300 / 1800 / 1900: XXXX XXX XXX.
+    if (/^1(300|800|900)\d{6}$/.test(national)) {
+        return `${national.slice(0, 4)} ${national.slice(4, 7)} ${national.slice(7)}`;
+    }
+
+    // 13 XX XX.
+    if (/^13\d{4}$/.test(national)) {
+        return `13 ${national.slice(2, 4)} ${national.slice(4)}`;
+    }
+
+    return null;
+};
+
+/**
+ * A number as a person in Perth would write it.
+ *
+ * The backend stores and sends E.164 (`+61412345678`) because that is what
+ * Zoom wants; nobody reads it that way. Australian numbers come back in the
+ * local form, everything else keeps its `+` and country code. Anything that
+ * is not a number at all — a name, an empty cell, a half-typed field — comes
+ * back untouched rather than mangled, because this also formats whatever the
+ * user is typing.
+ */
+export const normaliseNumberForDisplay = (value) => {
+    const raw = String(value ?? '').trim();
+
+    if (raw === '') return '';
+
+    const compact = compactNumber(raw);
+
+    if (!/^\+?\d{4,}$/.test(compact)) return raw;
+
+    let national = null;
+
+    if (compact.startsWith('+61')) national = compact.slice(3);
+    else if (compact.startsWith('0061')) national = compact.slice(4);
+    else if (compact.startsWith('+')) return formatInternational(compact);
+    else if (compact.startsWith('0')) national = compact.slice(1);
+    else national = compact;
+
+    return formatAustralian(national) ?? raw;
+};
+
+/**
+ * The other direction: a local number as E.164, for sending.
+ *
+ * The backend does its own parsing — it has to, it is the one talking to Zoom
+ * — so this is only ever a hint the compose box shows next to what was typed.
+ * Returns null when it cannot tell.
+ */
+export const toE164 = (value, countryCode = '61') => {
+    const compact = compactNumber(value);
+
+    if (compact === '') return null;
+    if (/^\+\d{7,17}$/.test(compact)) return compact;
+    if (/^00\d{7,17}$/.test(compact)) return `+${compact.slice(2)}`;
+    if (/^0\d{8,9}$/.test(compact)) return `+${countryCode}${compact.slice(1)}`;
+    if (/^\d{9}$/.test(compact)) return `+${countryCode}${compact}`;
+
+    return null;
+};
+
+/* ----------------------------------------------------------------- segments */
+
+/**
+ * The GSM 03.38 basic alphabet — one septet each.
+ *
+ * Written out rather than expressed as ranges because it is not one: it is a
+ * 1980s telco table with Greek capitals and a section symbol in the middle of
+ * it, and every character missing from here is what pushes a message from 160
+ * characters to 70.
+ */
+const GSM_BASIC =
+    '@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !"#¤%&\'()*+,-./0123456789:;<=>?' +
+    '¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà';
+
+/** Characters that exist in GSM-7, but cost two septets to send. */
+const GSM_EXTENDED = '\f^{}\\[~]|€';
+
+const GSM_BASIC_SET = new Set(GSM_BASIC.split(''));
+const GSM_EXTENDED_SET = new Set(GSM_EXTENDED.split(''));
+
+export const SMS_LIMITS = {
+    'GSM-7': { single: 160, concatenated: 153 },
+    'UCS-2': { single: 70, concatenated: 67 },
+};
+
+/** The most segments the composer will send in one go. */
+export const MAX_SEGMENTS = 6;
+
+/**
+ * How many SMS this body will actually cost, and why.
+ *
+ * The rule that surprises people is the second one: a single curly quote, an
+ * em dash or an emoji anywhere in the body drops the whole message to UCS-2
+ * and the limit falls from 160 characters to 70. The composer shows the
+ * encoding for exactly that reason — "70" with no explanation looks like a
+ * bug.
+ *
+ * Counted in UTF-16 code units, which is what the encoding actually charges
+ * for: an emoji outside the BMP is a surrogate pair and costs two.
+ */
+export const segmentCount = (body) => {
+    const text = String(body ?? '');
+
+    let septets = 0;
+    let unicode = false;
+
+    for (const character of text) {
+        if (GSM_BASIC_SET.has(character)) {
+            septets += 1;
+        } else if (GSM_EXTENDED_SET.has(character)) {
+            // An escape byte, then the character itself.
+            septets += 2;
+        } else {
+            unicode = true;
+            break;
+        }
+    }
+
+    const encoding = unicode ? 'UCS-2' : 'GSM-7';
+    const limits = SMS_LIMITS[encoding];
+    const characters = unicode ? text.length : septets;
+
+    if (characters === 0) {
+        return {
+            encoding,
+            characters: 0,
+            segments: 0,
+            perSegment: limits.single,
+            remaining: limits.single,
+        };
+    }
+
+    const segments =
+        characters <= limits.single
+            ? 1
+            : Math.ceil(characters / limits.concatenated);
+    const perSegment = segments === 1 ? limits.single : limits.concatenated;
+    const capacity = segments * perSegment;
+
+    return {
+        encoding,
+        characters,
+        segments,
+        perSegment,
+        remaining: capacity - characters,
+    };
+};
+
+/* -------------------------------------------------------------------- time */
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTHS = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+
+/** Midnight local time, as a number, for the day a date falls in. */
+const startOfDay = (date) =>
+    new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+
+export const parseDate = (value) => {
+    if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+    if (value === null || value === undefined || value === '') return null;
+
+    // MySQL hands back `2026-08-21 07:45:47`, which Safari refuses to parse.
+    const text =
+        typeof value === 'string' && /^\d{4}-\d{2}-\d{2} \d{2}:/.test(value)
+            ? value.replace(' ', 'T')
+            : value;
+    const date = new Date(text);
+
+    return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/**
+ * The short time a message list shows: `Now`, `4m`, `3h`, `Yesterday`, `Tue`,
+ * `12 Aug`, `12 Aug 24`.
+ *
+ * `now` is injectable so the tests are not a function of when they run.
+ */
+export const relativeTime = (value, now = Date.now()) => {
+    const date = parseDate(value);
+
+    if (!date) return '';
+
+    const stamp = date.getTime();
+    const elapsed = now - stamp;
+
+    if (elapsed < 0) return 'Now';
+    if (elapsed < MINUTE) return 'Now';
+    if (elapsed < HOUR) return `${Math.floor(elapsed / MINUTE)}m`;
+    if (elapsed < DAY) return `${Math.floor(elapsed / HOUR)}h`;
+
+    const today = startOfDay(new Date(now));
+    const days = Math.round((today - startOfDay(date)) / DAY);
+
+    if (days === 1) return 'Yesterday';
+    if (days < 7) return WEEKDAYS[date.getDay()];
+
+    const sameYear = date.getFullYear() === new Date(now).getFullYear();
+    const stem = `${date.getDate()} ${MONTHS[date.getMonth()]}`;
+
+    return sameYear ? stem : `${stem} ${String(date.getFullYear()).slice(-2)}`;
+};
+
+/** `2:07 pm`. Lower case, because a bubble is not a spreadsheet. */
+export const clockTime = (value) => {
+    const date = parseDate(value);
+
+    if (!date) return '';
+
+    const hours = date.getHours();
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const suffix = hours < 12 ? 'am' : 'pm';
+    const twelve = hours % 12 === 0 ? 12 : hours % 12;
+
+    return `${twelve}:${minutes} ${suffix}`;
+};
+
+/** The heading over a day's worth of messages. */
+export const dayLabel = (value, now = Date.now()) => {
+    const date = parseDate(value);
+
+    if (!date) return '';
+
+    const today = startOfDay(new Date(now));
+    const days = Math.round((today - startOfDay(date)) / DAY);
+
+    if (days === 0) return 'Today';
+    if (days === 1) return 'Yesterday';
+
+    const stem = `${WEEKDAYS[date.getDay()]} ${date.getDate()} ${MONTHS[date.getMonth()]}`;
+
+    return date.getFullYear() === new Date(now).getFullYear()
+        ? stem
+        : `${stem} ${date.getFullYear()}`;
+};
+
+/* ------------------------------------------------------------------ people */
+
+/**
+ * Titles that are not part of anybody's name.
+ *
+ * The CRM stores clients as "Perera, Darshini (Mrs)", so the bracketed title
+ * is the LAST word of the string — which is exactly where a naive
+ * first-word-plus-last-word rule looks for the surname, and why the avatars
+ * used to read "P(".
+ */
+const HONORIFICS = new Set([
+    'mr', 'mrs', 'ms', 'miss', 'mx', 'dr', 'prof', 'professor',
+    'rev', 'reverend', 'sir', 'dame', 'madam', 'lady', 'lord',
+]);
+
+/** Drop anything in brackets, closed or not: "(Mrs)", "[deceased]", "(Mrs". */
+const stripBrackets = (value) => value.replace(/[([{][^)\]}]*([)\]}]|$)/g, ' ');
+
+/** The name words, with titles and punctuation-only fragments removed. */
+const nameWords = (value) =>
+    String(value)
+        .split(/[\s.]+/)
+        .map((word) => word.trim())
+        .filter((word) => word !== '')
+        .filter((word) => !HONORIFICS.has(word.replace(/[^a-z]/gi, '').toLowerCase()));
+
+/** The first letter or digit in a word — "d'Angelo" must not initial as an apostrophe. */
+const firstLetter = (word) => {
+    const match = String(word || '').match(/[\p{L}\p{N}]/u);
+
+    return match ? match[0] : '';
+};
+
+/**
+ * At most two letters for an avatar.
+ *
+ * The CRM writes client names surname-first with a title on the end —
+ * "Perera, Darshini (Mrs)" — so three passes are needed before the initials
+ * mean anything: drop the brackets, drop the title, and read a comma as
+ * "Surname, First" so the initials come out in the order a person says them
+ * ("DP", not "PD").
+ *
+ * A number gets `#` rather than two of its digits: a circle reading "78" looks
+ * like data, and the only honest thing to say about an unsaved number is that
+ * nobody has named it yet. Same for nothing at all.
+ */
+export const initialsFor = (value) => {
+    const raw = String(value ?? '').trim();
+
+    if (raw === '' || looksLikeNumber(raw)) return '#';
+
+    const cleaned = stripBrackets(raw);
+
+    // "Surname, First Middle" — the CRM's own format.
+    if (cleaned.includes(',')) {
+        const [surname, ...rest] = cleaned.split(',');
+        const surnameWords = nameWords(surname);
+        const givenWords = nameWords(rest.join(' '));
+        const given = firstLetter(givenWords[0]);
+        const family = firstLetter(surnameWords[0]);
+
+        if (given && family) return `${given}${family}`.toUpperCase();
+        // Only one half survived the cleaning — fall through to the plain rule
+        // rather than returning half an avatar.
+    }
+
+    const words = nameWords(cleaned);
+
+    if (words.length === 0) return '#';
+
+    if (words.length === 1) {
+        const single = words[0].replace(/[^\p{L}\p{N}]/gu, '').slice(0, 2);
+
+        return single === '' ? '#' : single.toUpperCase();
+    }
+
+    const first = firstLetter(words[0]);
+    const last = firstLetter(words[words.length - 1]);
+    const pair = `${first}${last}`;
+
+    return pair === '' ? '#' : pair.slice(0, 2).toUpperCase();
+};
+
+/**
+ * A CRM client name split into the two halves a template needs.
+ *
+ * The CRM writes clients surname-first with a title on the end — "Second, Test
+ * (Mr)" — so "Hi {first_name}" cannot be answered by taking the first word.
+ * Three passes, the same three `initialsFor` makes: drop the brackets, drop
+ * the honorific, and read a comma as "Surname, First".
+ *
+ * A number is not a name, and neither half is guessed from one.
+ */
+export const splitPersonName = (value) => {
+    const raw = String(value ?? '').trim();
+    const nothing = { first: null, last: null };
+
+    if (raw === '' || looksLikeNumber(raw)) return nothing;
+
+    const cleaned = stripBrackets(raw).replace(/\s+/g, ' ').trim();
+
+    if (cleaned.includes(',')) {
+        const [surname, ...rest] = cleaned.split(',');
+        const given = nameWords(rest.join(' '));
+        const family = nameWords(surname);
+
+        if (given.length > 0 || family.length > 0) {
+            return { first: given[0] ?? null, last: family[0] ?? null };
+        }
+
+        return nothing;
+    }
+
+    const words = nameWords(cleaned);
+
+    if (words.length === 0) return nothing;
+    if (words.length === 1) return { first: words[0], last: null };
+
+    return { first: words[0], last: words[words.length - 1] };
+};
+
+/* --------------------------------------------------------------- templates */
+
+/**
+ * A placeholder in a template body.
+ *
+ * `{first_name}`, and the three things people type instead of it: `{{...}}`,
+ * `{ ... }` and any mixture of case. Deliberately narrow about what a token
+ * may contain (a word) so a body that happens to contain a brace — a dollar
+ * figure in curly quotes, a stray `{` — is not eaten.
+ */
+const PLACEHOLDER = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}|\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g;
+
+/** `Mon 24 Aug` — the way a reminder text says a date in Perth. */
+const templateDate = (value) => {
+    const date = parseDate(value);
+
+    if (!date) return null;
+
+    return `${WEEKDAYS[date.getDay()]} ${date.getDate()} ${MONTHS[date.getMonth()]}`;
+};
+
+const trimOrNull = (value) => {
+    const text = String(value ?? '').trim();
+
+    return text === '' ? null : text;
+};
+
+/**
+ * What each token is worth for one conversation.
+ *
+ * The fallbacks are the point. A thread carries whatever the CRM could tell it
+ * — sometimes a first name, sometimes only "Second, Test (Mr)", sometimes only
+ * a contact label somebody typed — and a template has to do the best it can
+ * with each. Anything still unknown comes back null, which leaves the token
+ * standing in the body.
+ */
+const templateValues = (context = {}) => {
+    const client = context.client || {};
+    const contactName = context.contact_name ?? context.contactName ?? null;
+
+    const fromClient = splitPersonName(client.name);
+    const fromContact = splitPersonName(contactName);
+
+    const first =
+        trimOrNull(client.first_name) ?? fromContact.first ?? fromClient.first;
+    // The other way round for the surname: the CRM's own "Surname, First" is a
+    // better source for it than a label someone typed on a phone number.
+    const last =
+        trimOrNull(client.last_name) ?? fromClient.last ?? fromContact.last;
+
+    // Never the raw stored form: "Hi Second, Test (Mr)" is not a text message.
+    const spoken = [first, last].filter(Boolean).join(' ');
+    const name =
+        trimOrNull(spoken) ??
+        trimOrNull(stripBrackets(String(client.name ?? ''))) ??
+        trimOrNull(stripBrackets(String(contactName ?? '')));
+
+    const eventDate = client.next_event?.date ?? null;
+
+    return {
+        first_name: first,
+        last_name: last,
+        name,
+        full_name: name,
+        number: trimOrNull(normaliseNumberForDisplay(context.number)),
+        line: trimOrNull(context.line),
+        date: templateDate(eventDate),
+        time: trimOrNull(clockTime(eventDate)),
+    };
+};
+
+/**
+ * A template body with its placeholders filled in from the conversation.
+ *
+ * The rule that matters is what happens when a token cannot be filled: it is
+ * left exactly as written. A client with no meeting booked yields "your review
+ * on {date}", which is visibly a blank for the sender to type over — where
+ * dropping it would yield "your review on " and get sent that way. An unknown
+ * token is left standing for the same reason.
+ */
+export const fillTemplate = (body, context = {}) => {
+    const text = String(body ?? '');
+
+    if (text === '') return '';
+
+    const values = templateValues(context);
+
+    return text.replace(PLACEHOLDER, (match, doubled, single) => {
+        const key = String(doubled ?? single ?? '').toLowerCase();
+        const value = values[key];
+
+        return value === undefined || value === null || value === ''
+            ? match
+            : value;
+    });
+};
+
+/**
+ * Where the next unfilled placeholder sits, so the composer can select it
+ * rather than merely park the caret at the end.
+ *
+ * Selecting it is what turns "the template went in" into "type here": the
+ * sender's next keystroke replaces the token instead of landing beside it.
+ */
+export const nextPlaceholder = (text, from = 0) => {
+    const body = String(text ?? '');
+    const search = new RegExp(PLACEHOLDER.source, 'g');
+
+    search.lastIndex = Math.max(0, Number(from) || 0);
+
+    const match = search.exec(body);
+
+    return match === null
+        ? null
+        : { start: match.index, end: match.index + match[0].length };
+};
+
+/** What a thread is called in a list: the client, the contact, the number. */
+export const threadDisplayName = (thread) => {
+    if (!thread) return '';
+
+    return (
+        thread.client?.name ||
+        thread.contact_name ||
+        thread.display_number ||
+        normaliseNumberForDisplay(thread.external_number) ||
+        'Unknown number'
+    );
+};
+
+/** The number under the name, only when it is not already the name. */
+export const threadSubtitle = (thread) => {
+    if (!thread) return '';
+
+    const number =
+        thread.display_number ||
+        normaliseNumberForDisplay(thread.external_number) ||
+        '';
+
+    return threadDisplayName(thread) === number ? '' : number;
+};
+
+/* --------------------------------------------------------------- messages */
+
+/** The moment a message happened, whichever of its stamps is set. */
+export const messageTimestamp = (message) =>
+    message?.created_at ??
+    message?.received_at ??
+    message?.sent_at ??
+    message?.delivered_at ??
+    null;
+
+/**
+ * What the status line under an outgoing bubble says.
+ *
+ * `not_connected` is a first-class outcome rather than an error: Zoom is not
+ * wired up yet, the message is genuinely saved and genuinely queued, and
+ * calling that "Failed" would send someone chasing a bug that does not exist.
+ */
+export const STATUS_LABELS = {
+    queued: 'Sending…',
+    sent: 'Sent',
+    delivered: 'Delivered',
+    failed: 'Failed',
+    received: 'Received',
+    not_connected: 'Held — not connected',
+};
+
+export const statusLabel = (message) => {
+    if (!message) return '';
+
+    const label = STATUS_LABELS[message.status];
+
+    if (!label) return message.status ? String(message.status) : '';
+    if (message.status === 'failed' && message.error) {
+        return `Failed — ${message.error}`;
+    }
+
+    return label;
+};
+
+/**
+ * Messages split into days, oldest first, each day labelled.
+ *
+ * The timeline renders one heading per day and never re-sorts inside a day:
+ * the server sends oldest→newest and an optimistic bubble is appended at the
+ * end, so the order on screen is the order it arrived in.
+ */
+export const groupMessagesByDay = (messages, now = Date.now()) => {
+    const list = Array.isArray(messages) ? messages : [];
+    const groups = [];
+    let current = null;
+
+    list.forEach((message) => {
+        const date = parseDate(messageTimestamp(message));
+        // A message with no usable stamp — an optimistic one mid-flight, say —
+        // belongs with whatever is on screen rather than in a day of its own.
+        const key = date
+            ? `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(
+                  date.getDate()
+              ).padStart(2, '0')}`
+            : current?.key ?? 'unknown';
+
+        if (!current || current.key !== key) {
+            current = {
+                key,
+                label: date ? dayLabel(date, now) : '',
+                messages: [],
+            };
+            groups.push(current);
+        }
+
+        current.messages.push(message);
+    });
+
+    return groups;
+};
+
+/* ------------------------------------------------------- list bookkeeping */
+
+const sameId = (a, b) => String(a) === String(b);
+
+/**
+ * Put a thread at the top of the list, replacing any older copy of it.
+ *
+ * What a `.sms.received` event does to the inbox: the conversation that just
+ * moved goes to the top, and it appears there exactly once whether or not it
+ * was already on screen.
+ */
+export const upsertThread = (threads, thread) => {
+    if (!thread || thread.id === undefined) return Array.isArray(threads) ? threads : [];
+
+    const list = Array.isArray(threads) ? threads : [];
+    const rest = list.filter((one) => !sameId(one.id, thread.id));
+    const previous = list.find((one) => sameId(one.id, thread.id));
+
+    return [previous ? { ...previous, ...thread } : thread, ...rest];
+};
+
+/**
+ * Add a message to a timeline, or reconcile the optimistic one it replaces.
+ *
+ * Two things arrive out of order here: the 201 response to a send, and the
+ * `.sms.updated` broadcast for the same message. Matching on `id` first and
+ * then on the `client_id` an optimistic bubble carries means neither one can
+ * produce a duplicate, whichever lands first.
+ */
+export const upsertMessage = (messages, message) => {
+    if (!message) return Array.isArray(messages) ? messages : [];
+
+    const list = Array.isArray(messages) ? messages : [];
+    const index = list.findIndex(
+        (one) =>
+            (message.id !== undefined && sameId(one.id, message.id)) ||
+            (message.client_id !== undefined &&
+                one.client_id !== undefined &&
+                sameId(one.client_id, message.client_id))
+    );
+
+    if (index === -1) return [...list, message];
+
+    const next = list.slice();
+
+    next[index] = { ...list[index], ...message };
+
+    return next;
+};
+
+/** Prepend a page of older messages, dropping any this timeline already has. */
+export const prependMessages = (messages, older) => {
+    const list = Array.isArray(messages) ? messages : [];
+    const page = Array.isArray(older) ? older : [];
+    const known = new Set(list.map((one) => String(one.id)));
+
+    return [...page.filter((one) => !known.has(String(one.id))), ...list];
+};
+
+/** Total unread across a `{id: n}` map, ignoring anything unparseable. */
+export const sumUnread = (byId) =>
+    Object.values(byId || {}).reduce((total, value) => {
+        const count = Number(value);
+
+        return total + (Number.isFinite(count) ? count : 0);
+    }, 0);
+
+/**
+ * The `?thread=` a deep link carries, if any.
+ *
+ * Out here rather than in the page because it is the contract between a link
+ * anyone can paste and the conversation that opens — the popover builds these
+ * URLs, the inbox reads them, and both have to agree.
+ */
+export const threadIdFromSearch = (search) => {
+    const raw = String(search ?? '');
+
+    if (raw === '') return null;
+
+    const query = raw.startsWith('?') ? raw.slice(1) : raw;
+    const match = query.match(/(?:^|&)thread=([^&#]*)/);
+
+    if (!match) return null;
+
+    const value = decodeURIComponent(match[1]);
+
+    return value === '' ? null : value;
+};
+
+/** `99+` past the point where the exact number stops mattering. */
+export const badgeCount = (count, ceiling = 99) => {
+    const value = Number(count) || 0;
+
+    if (value <= 0) return '';
+
+    return value > ceiling ? `${ceiling}+` : String(value);
+};
+
+/* ------------------------------------------------------------- transports */
+
+/**
+ * What the status endpoint means, in words a user can act on.
+ *
+ * Three states, and only one of them is "everything works". The other two are
+ * the ones this UI was built around: Zoom is not connected yet, and the dev
+ * transport that stands in for it while that is true.
+ */
+export const describeTransport = (status) => {
+    const transport = status?.transport ?? null;
+    const connected = Boolean(status?.connected);
+
+    if (transport === 'zoom' && connected) {
+        return {
+            tone: 'ok',
+            short: 'Connected',
+            title: 'Connected to Zoom Phone',
+            note: 'Messages send and receive normally.',
+            detail: 'Messages send and receive normally.',
+        };
+    }
+
+    if (transport === 'zoom') {
+        return {
+            tone: 'bad',
+            short: 'Zoom unavailable',
+            title: 'Zoom Phone is not answering',
+            note: 'Messages are held until it comes back.',
+            detail:
+                'Messages are being held and will send once the connection is back.',
+        };
+    }
+
+    if (transport === 'log') {
+        return {
+            tone: 'warn',
+            short: 'Dev transport',
+            title: 'Dev transport — replies are simulated',
+            note: 'Nothing leaves the building.',
+            detail:
+                'Nothing leaves the building: messages are written to the log instead of being sent.',
+        };
+    }
+
+    return {
+        tone: 'warn',
+        short: 'Not connected',
+        title: 'Not connected to Zoom yet — messages you send are held',
+        note: 'They send once Zoom Phone is connected.',
+        detail:
+            'You can write and queue messages now. They will be delivered once Zoom Phone is connected.',
+    };
+};
+
+/**
+ * What the composer's placeholder says, which is not always the same thing.
+ *
+ * It followed `connected` alone, so on the dev transport it promised a message
+ * would be "held until Zoom is connected" — which is not what happens: the dev
+ * transport accepts the message and answers it. Three transports, three
+ * sentences.
+ */
+export const composerPlaceholder = (status) => {
+    const transport = status?.transport ?? null;
+
+    if (transport === 'log') {
+        return 'Write a message… (dev transport: a simulated reply comes back)';
+    }
+
+    if (transport === 'zoom' && status?.connected) return 'Write a message…';
+
+    return 'Write a message — it will be held until Zoom is connected';
+};
+
+/**
+ * The counter under the composer: `0 / 160 · 1 SMS · GSM-7`.
+ *
+ * A bare "70" looks like a bug, so the denominator moves with the encoding and
+ * the encoding is named. The segment count floors at one — a message about to
+ * be typed still costs one SMS, and "0 SMS" invites the question.
+ */
+export const counterLabel = (body) => {
+    const counts = segmentCount(body);
+    const segments = Math.max(counts.segments, 1);
+    const capacity = segments * counts.perSegment;
+
+    return `${counts.characters} / ${capacity} · ${segments} SMS · ${counts.encoding}`;
+};
+
+/**
+ * Which messages end a run from one side.
+ *
+ * Consecutive bubbles from the same direction read as one utterance, so they
+ * sit tighter and only the last of them carries a timestamp — six identical
+ * times stacked down the margin is noise. Pure, so the timeline can decide
+ * this once per day group rather than peering at its neighbours mid-render.
+ */
+export const markRuns = (messages) => {
+    const list = Array.isArray(messages) ? messages : [];
+
+    return list.map((message, index) => {
+        const next = list[index + 1];
+
+        return {
+            message,
+            firstOfRun: index === 0 || list[index - 1].direction !== message.direction,
+            lastOfRun: !next || next.direction !== message.direction,
+        };
+    });
+};
+
+/**
+ * A line, as the selector lists it: `Reception · 3 unread`.
+ *
+ * "(3)" beside a name is a count of something unstated. The word is four
+ * characters and removes the question.
+ */
+export const lineOptionLabel = (line, unread = 0) => {
+    // The label alone: the number lives in the page header (lineNumberForDisplay),
+    // where it can be read without opening the picker.
+    const name = line?.label || lineNumberForDisplay(line) || 'Line';
+    const count = Number(unread) || 0;
+
+    return count > 0 ? `${name} · ${count} unread` : name;
+};
+
+/**
+ * The line's number the way it is read out to a client - "0468 193 536" -
+ * or '' when the line has none.
+ */
+export const lineNumberForDisplay = (line) =>
+    line?.display_number || normaliseNumberForDisplay(line?.phone_number) || '';
+
+/** True while the composer should warn that nothing is actually going out. */
+export const isHeldTransport = (status) =>
+    !status || status.transport === 'null' || status.connected === false;
+
+/* --------------------------------------------------------------- recipients */
+
+/**
+ * An Australian mobile in E.164: `+614` and eight more digits. Nothing else in
+ * the +61 space can receive an SMS reliably - a landline gets a text-to-speech
+ * call from some carriers and silence from the rest, and 13/1300/1800 numbers
+ * cannot receive at all.
+ */
+const AU_MOBILE = /^\+614\d{8}$/;
+
+/** The sentences the compose box says about a number, in one place. */
+export const RECIPIENT_HINTS = {
+    invalid: 'Enter an Australian mobile like 0412 345 678, or pick a client',
+    landline: 'That looks like a landline; SMS needs a mobile number',
+};
+
+/**
+ * Below this many digits the field is still being typed, not wrong.
+ *
+ * An Australian number is ten digits; judging at the sixth turns the hint red
+ * halfway through every number anyone enters. Eight is late enough to be quiet
+ * while typing and early enough to catch the case that matters - an eight-digit
+ * local number with no area code.
+ */
+const JUDGE_AT_DIGITS = 8;
+
+/** Is this an attempt at a number at all, rather than a name being searched? */
+const looksNumeric = (value) => {
+    const raw = String(value ?? '').trim();
+
+    if (raw === '') return false;
+
+    return /^[+(]?[\d\s()+\-.]*$/.test(raw);
+};
+
+/**
+ * What the compose box should say about what has been typed into "To".
+ *
+ * Three questions at once, because the answer to each depends on the one
+ * before it: is this a number or a name being searched, does it normalise, and
+ * is what it normalises to something an SMS can actually reach.
+ *
+ *   kind 'none'     nothing to say - blank, a name, or a number mid-typing
+ *   kind 'mobile'   good to send; `message` names the number it will go to
+ *   kind 'landline' an AU number, but not one that receives SMS
+ *   kind 'invalid'  digits that do not make a number we can send to
+ *
+ * Overseas numbers are only accepted when they were typed as international -
+ * a leading `+` or an `00`/`0011` dial prefix. Without that, a bare run of
+ * digits is read as Australian (that is what `toE164` does with it), and
+ * quietly sending "415 555 2671" to +61415552671 is exactly the mistake this
+ * function exists to prevent. There is no attempt to tell a French mobile from
+ * a French landline: that needs the metadata blob this module deliberately
+ * does not carry, so an international number is taken on trust.
+ *
+ * @param {string} input What is in the field.
+ * @returns {{e164: ?string, kind: string, ok: boolean, message: string}}
+ */
+export const describeRecipient = (input) => {
+    const raw = String(input ?? '').trim();
+    const nothingToSay = { e164: null, kind: 'none', ok: false, message: '' };
+
+    if (raw === '' || !looksNumeric(raw)) return nothingToSay;
+
+    const digits = raw.replace(/\D+/g, '');
+    // `0011 61 4…` is how an Australian dials out; `toE164` does not know the
+    // prefix, so it is turned into the `+` it means before anything else looks
+    // at it. Without this the IDD is swallowed into the country code.
+    const idd = ['0011', '011', '00'].find(
+        (prefix) =>
+            digits.startsWith(prefix) && digits.length > prefix.length + 6
+    );
+    let dialled = idd === undefined ? raw : `+${digits.slice(idd.length)}`;
+
+    // "61422442886" - the country code typed without its plus. Much of the
+    // practice's own contact data is stored that way, so it is pasted that way.
+    if (idd === undefined && !raw.trim().startsWith('+') && /^614\d{8}$/.test(digits)) {
+        dialled = `+${digits}`;
+    }
+
+    const international = dialled.trim().startsWith('+');
+
+    if (digits.length < JUDGE_AT_DIGITS && !international) return nothingToSay;
+
+    const e164 = toE164(dialled);
+
+    if (e164 === null) {
+        return { e164: null, kind: 'invalid', ok: false, message: RECIPIENT_HINTS.invalid };
+    }
+
+    if (e164.startsWith('+61')) {
+        // A number that only reached +61 because `toE164` defaults there, when
+        // what was typed was meant to be foreign, is not a number we can send.
+        if (AU_MOBILE.test(e164)) {
+            return {
+                e164,
+                kind: 'mobile',
+                ok: true,
+                message: `Will send to ${normaliseNumberForDisplay(e164)}`,
+            };
+        }
+
+        return {
+            e164,
+            kind: 'landline',
+            ok: false,
+            message: RECIPIENT_HINTS.landline,
+        };
+    }
+
+    // Anything outside +61 has to have been typed as international, and has to
+    // be a length E.164 allows.
+    const body = e164.replace(/^\+/, '');
+
+    if (!international || body.length < 8 || body.length > 15) {
+        return { e164: null, kind: 'invalid', ok: false, message: RECIPIENT_HINTS.invalid };
+    }
+
+    return {
+        e164,
+        kind: 'mobile',
+        ok: true,
+        message: `Will send to ${normaliseNumberForDisplay(e164)}`,
+    };
+};
+
+export default {
+    badgeCount,
+    clockTime,
+    composerPlaceholder,
+    counterLabel,
+    lineOptionLabel,
+    markRuns,
+    dayLabel,
+    describeRecipient,
+    describeTransport,
+    fillTemplate,
+    groupMessagesByDay,
+    initialsFor,
+    isHeldTransport,
+    looksLikeNumber,
+    messageTimestamp,
+    nextPlaceholder,
+    normaliseNumberForDisplay,
+    parseDate,
+    prependMessages,
+    RECIPIENT_HINTS,
+    relativeTime,
+    segmentCount,
+    splitPersonName,
+    statusLabel,
+    sumUnread,
+    threadDisplayName,
+    threadIdFromSearch,
+    threadSubtitle,
+    toE164,
+    upsertMessage,
+    upsertThread,
+};