@wix/himalaya-cli 0.1614.0 → 0.1615.0

package/templates/salon-spa/tier5-src/_shared/business-chat-presenter.ts

@@ -0,0 +1,581 @@
+import { businessChatCopy } from "./business-chat-copy.js";
+import { formatMonthDay } from "./engine-intl.js";
+type RecordValue = Record<string, unknown>;
+
+export type BusinessMessagePart = {
+  kind?: string;
+  text?: string;
+  fileName?: string;
+  caption?: string;
+  url?: string;
+  thumbnailUrl?: string;
+  fields?: { name: string; value: string }[];
+  buttons?: { id: string; label: string; url: string; interactionId?: string; enabled: boolean }[];
+};
+
+export type BusinessTextRun = { text: string; marks?: string[] };
+export type BusinessSuggestion = { id: string; messageId: string; label: string; kind: "postback" | "visitor_option"; appId?: string; interactionId?: string; enabled: boolean; disabled: boolean };
+/** `inApp` buttons open `screenId` with `targetId` inside the app; the rest open `url` in the browser. Only a
+ *  `routable` one (a link in the text or a template button, never a file) may be opened in the app. */
+export type BusinessArticleAction = { id: string; label: string; url: string; style: "primary" | "secondary"; screenId: string; targetId: string; inApp: boolean; web: boolean; routable: boolean };
+/** The app's own screen for a site link, named by the slug in the link's path. */
+export type BusinessInAppRoute = { kind: "product" | "service"; slug: string };
+
+/** A store product page or a bookings service (its page or its booking calendar) on this app's own site has a screen
+ *  in the app; another site's page (even one on the same host, as Wix sites share one), a pay link or a file has
+ *  none, and with no site configured nothing is routed. The slug only names the item: the worker still has to find it. */
+export function businessInAppRoute(url: string, siteUrl: string): BusinessInAppRoute | undefined {
+  const site = /^https:\/\/[^/?#\s]+(?:\/[^?#\s]*)?/i.exec(siteUrl.trim())?.[0].replace(/\/+$/, "") ?? "";
+  if (!site || !url.toLowerCase().startsWith(`${site.toLowerCase()}/`)) return undefined;
+  const match = /^\/(product-page|service-page|booking-calendar)\/([^/?#]+)\/?(?:[?#].*)?$/i.exec(url.slice(site.length));
+  if (!match) return undefined;
+  let slug: string;
+  // A malformed escape ("50%-off") names nothing the app can look up: the link stays a web link.
+  try { slug = decodeURIComponent(match[2]!); } catch { return undefined; }
+  return slug ? { kind: match[1]!.toLowerCase() === "product-page" ? "product" : "service", slug } : undefined;
+}
+const webAction = { screenId: "", targetId: "", inApp: false, web: true, routable: true };
+export type BusinessVisitorOptions = { answerTo: string; labels: string[] };
+
+export type BusinessMessage = {
+  id: string;
+  sender: string;
+  senderName: string;
+  senderId: string;
+  mine: boolean;
+  when: string;
+  createdDate: string;
+  plainText: string;
+  parts: BusinessMessagePart[];
+};
+
+export type BusinessRoomSummary = {
+  id?: unknown;
+  participantId?: unknown;
+  participantCount?: unknown;
+  clientReferenceType?: unknown;
+  businessContext?: unknown;
+};
+
+/** Keep host capability failures visible without exposing runtime error details. */
+export function businessRealtimeStatusLabel(state: string, reason = ""): string {
+  if (state === "connected") return "";
+  if (state === "connecting") return businessChatCopy('connecting');
+  if (state === "reconnecting") return businessChatCopy('reconnecting');
+  if (reason === "chat_setup_scope_unavailable") return businessChatCopy('liveSessionUnavailable');
+  if (reason === "runtime_unavailable") return businessChatCopy('liveHostUnavailable');
+  if (reason === "invalid_setup_response") return businessChatCopy('liveSetupFailed');
+  if (reason === "firebase_auth_failed") return businessChatCopy('liveAuthFailed');
+  if (reason === "firebase_connection_failed") return businessChatCopy('liveInterrupted');
+  if (reason === "invalid_event") return businessChatCopy('liveUnreadable');
+  if (reason === "event_overflow") return businessChatCopy('livePaused');
+  return businessChatCopy('liveUnavailable');
+}
+
+const object = (value: unknown): RecordValue =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as RecordValue : {};
+
+/** Return a sole existing two-party business room, or a unique business-name match among several;
+ * never create a room or guess among remaining matches. */
+export function selectExistingBusinessRoom(rooms: unknown[], businessName?: string, requireUnambiguous = false): { id: string; participantId: string } | undefined {
+  let candidates = rooms.filter((value) => {
+    const room = object(value);
+    return typeof room.id === "string" && !!room.id &&
+      typeof room.participantId === "string" && !!room.participantId &&
+      room.participantCount === 2 && room.clientReferenceType === "contactId" &&
+      Object.keys(object(room.businessContext)).length > 0;
+  });
+  const candidateCount = candidates.length;
+  if (candidateCount > 1 && businessName?.trim()) {
+    // Keep case significant so differently named businesses are not conflated.
+    const name = businessName.trim();
+    candidates = candidates.filter((value) => {
+      const roomName = object(object(value).businessContext).name;
+      return typeof roomName === "string" && roomName.trim() === name;
+    });
+  }
+  if (candidates.length !== 1) {
+    if (requireUnambiguous && candidateCount > 1) throw new Error("business_room_selection_ambiguous");
+    return undefined;
+  }
+  const room = object(candidates[0]);
+  return { id: room.id as string, participantId: room.participantId as string };
+}
+
+/** The member's current AI quick replies: the newest assistant answer with real `visitorOptions` that no
+ *  selection has answered yet (typed free text does not consume them, matching the website widget).
+ *  Wix's AI `inboxId` is a different id namespace from the chat-web row id, so these are composer-level,
+ *  not joined to a row. They must belong to the same AI conversation as the newest message in the list;
+ *  `answerTo` is always the exact AI answer id. */
+export function businessVisitorOptionsFromAiMessages(aiMessages: unknown[]): BusinessVisitorOptions | null {
+  const dated = aiMessages.map(object).map((message, index) => ({ message, index, at: Date.parse(String(message.createdDate)) }))
+    .filter(({ at }) => Number.isFinite(at))
+    .sort((left, right) => left.at - right.at || left.index - right.index)
+    .map(({ message }) => message);
+  const conversationId = dated.at(-1)?.conversationId;
+  if (typeof conversationId !== "string" || !conversationId) return null;
+  const answered = new Set(dated.filter((message) => message.messageType === "VISITOR_OPTION_SELECTED" && typeof message.answerTo === "string")
+    .map((message) => message.answerTo as string));
+  for (const message of dated.slice().reverse()) {
+    const id = typeof message.id === "string" ? message.id.trim() : "";
+    const labels = Array.isArray(message.visitorOptions)
+      ? message.visitorOptions.filter((value): value is string => typeof value === "string" && !!value.trim()).map((value) => value.trim())
+      : [];
+    if (message.sender !== "ASSISTANT" || message.messageType !== "ANSWER" || !id || !labels.length) continue;
+    return message.conversationId === conversationId && !answered.has(id) ? { answerTo: id, labels } : null;
+  }
+  return null;
+}
+
+/** Build the observed Wix Smart Chat visitor-option selection only from current,
+ *  identity-scoped AI metadata. The ID is request-local; the answerTo anchors it
+ *  to the exact assistant answer. */
+export function businessVisitorOptionRequest(
+  options: BusinessVisitorOptions | null | undefined,
+  label: string,
+  selectionId: string,
+): { message: { sender: "SITE_VISITOR"; messageType: "VISITOR_OPTION_SELECTED"; answerTo: string; body: { mainText: string; additionalData: { id: string; type: "select_option"; action: string }[] } } } | undefined {
+  if (!options || !options.answerTo || !options.labels.includes(label) || !/^[0-9a-f-]{36}$/i.test(selectionId)) return undefined;
+  return {
+    message: {
+      sender: "SITE_VISITOR",
+      messageType: "VISITOR_OPTION_SELECTED",
+      answerTo: options.answerTo,
+      body: { mainText: label, additionalData: [{ id: selectionId, type: "select_option", action: label }] },
+    },
+  };
+}
+
+export function newBusinessSelectionId(random: () => number = Math.random): string {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (value) => {
+    const n = Math.floor(random() * 16);
+    return (value === "x" ? n : (n & 0x3) | 0x8).toString(16);
+  });
+}
+
+export function businessVisitorOptionSuggestions(options: BusinessVisitorOptions | null | undefined): BusinessSuggestion[] {
+  if (!options?.answerTo) return [];
+  return options.labels.map((label, index) => ({
+    id: `${options.answerTo}:visitor-option-${index}`,
+    messageId: options.answerTo,
+    label,
+    kind: "visitor_option",
+    enabled: true,
+    disabled: false,
+  }));
+}
+
+/** Wix Chat realtime currently sends `{type, timestamp, summary, message?}` events. */
+export function isBusinessMessageEvent(envelope: unknown, roomId: string, smartChat = false): boolean {
+  const event = object(object(envelope).event);
+  if ((!roomId && !smartChat) || typeof event.type !== "string" || !/^(message|messagesent)$/i.test(event.type)) return false;
+  const message = object(event.message);
+  const data = object(event.data);
+  const nested = object(data.message);
+  const eventRoomId = [event.chatroomId, event.chatRoomId, message.chatroomId, message.chatRoomId, data.chatroomId, nested.chatroomId]
+    .find((value): value is string => typeof value === "string" && value.length > 0);
+  // Smart Chat's room can differ from the Members room. The subsequent read is scoped by
+  // the current member/site identity, never by the event's untrusted room id.
+  return smartChat || !eventRoomId || eventRoomId === roomId;
+}
+
+export function shouldRefreshBusinessHistory(
+  envelope: unknown,
+  roomId: string,
+  session: { member: boolean; principal: string; currentPrincipal: string; scope: string; currentScope: string },
+  smartChat = false,
+): boolean {
+  return !!session.member && (!!roomId || smartChat) && !!session.principal && session.principal === session.currentPrincipal &&
+    session.scope === session.currentScope && isBusinessMessageEvent(envelope, roomId, smartChat);
+}
+
+function safeAvatar(value: unknown): string {
+  if (typeof value !== "string" || /[\s\\\u0000-\u001f\u007f-\u009f]/u.test(value)) return "";
+  const match = /^https:\/\/([^/?#]+)(?:[/?#].*)?$/iu.exec(value);
+  // No credentials, and no percent escapes in the host: a host is plain letters, digits, dots and hyphens.
+  return match && !/[@%]/.test(match[1]!) ? value : "";
+}
+
+/** A card's picture, only a plain https URL. Wix sends a 200-point thumbnail; a card shows it about 270 wide on a
+ *  dense screen, so a Wix media URL asks its image service for a larger copy instead of being blown up. */
+function cardImage(value: unknown): string {
+  const url = safeAvatar(value);
+  return /^https:\/\/static\.wixstatic\.com\/media\//i.test(url) ? url.replace(/\/v1\/fit\/w_\d+,h_\d+,/i, "/v1/fit/w_800,h_800,") : url;
+}
+
+function initials(value: string): string {
+  const words = value.trim().split(/\s+/).filter(Boolean);
+  return words.length > 1 ? `${words[0]![0]}${words[words.length - 1]![0]}`.toUpperCase() : (words[0]?.slice(0, 2) ?? "").toUpperCase();
+}
+
+function decodeHtml(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#[0-9]+|amp|lt|gt|quot|apos|nbsp);/gi, (whole, entity: string) => {
+    const names: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'", nbsp: " " };
+    if (entity[0] !== "#") return names[entity.toLowerCase()] ?? whole;
+    const code = entity[1]?.toLowerCase() === "x" ? parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+    return code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : whole;
+  });
+}
+
+/** Convert Wix's text/html parts into safe inline text marks; HTML is never rendered. */
+function htmlRuns(html: string): BusinessTextRun[] {
+  const source = html.replace(/<!--[\s\S]*?-->/g, "").replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "");
+  const runs: BusinessTextRun[] = [];
+  const marks = new Set<string>();
+  const append = (text: string) => {
+    if (!text) return;
+    const active = [...marks].sort();
+    const last = runs[runs.length - 1];
+    if (last && JSON.stringify(last.marks ?? []) === JSON.stringify(active)) last.text += text;
+    else runs.push(active.length ? { text, marks: active } : { text });
+  };
+  const tokens = source.match(/<[^>]*>|[^<]+/g) ?? [];
+  for (const token of tokens) {
+    if (!token.startsWith("<")) { append(decodeHtml(token)); continue; }
+    const tag = /^<\s*(\/?)\s*([a-z0-9]+)/i.exec(token);
+    if (!tag) continue;
+    const closing = tag[1] === "/";
+    const name = tag[2]!.toLowerCase();
+    if (name === "br" || name === "p" || name === "div" || name === "li" || /^h[1-6]$/.test(name)) {
+      if (closing || name === "br" || name === "li") append("\n");
+    }
+    const mark = name === "b" || name === "strong" ? "bold" : name === "i" || name === "em" ? "italic" : name === "u" ? "underline" : name === "code" ? "code" : name === "a" ? "link" : "";
+    if (!mark) continue;
+    if (closing) marks.delete(mark); else marks.add(mark);
+  }
+  return runs.map((run) => ({ ...run, text: run.text.replace(/\n{3,}/g, "\n\n") })).filter((run) => run.text.length > 0);
+}
+
+function htmlMessageRuns(message: RecordValue): BusinessTextRun[] | undefined {
+  const parts = Array.isArray(message.data) ? message.data : [];
+  const htmlPart = parts.map(object).find((part) => typeof part.mimeType === "string" && part.mimeType.toLowerCase().split(";")[0] === "text/html");
+  if (!htmlPart) return undefined;
+  const data = typeof htmlPart.data === "string" ? htmlPart.data : object(htmlPart.data).html ?? object(htmlPart.data).text;
+  return typeof data === "string" ? htmlRuns(data) : undefined;
+}
+
+/** Recognize the inline Markdown Wix AI emits in text/plain messages; all other markers stay escaped. */
+function markdownRuns(value: string): BusinessTextRun[] {
+  const runs: BusinessTextRun[] = [];
+  const pattern = /(\*\*[^*\n]+?\*\*|__[^_\n]+?__|`[^`\n]+`|\*[^*\n]+?\*|_[^_\n]+?_)/g;
+  let cursor = 0;
+  for (const match of value.matchAll(pattern)) {
+    const index = match.index ?? 0;
+    const token = match[0];
+    // Underscore emphasis needs a word boundary, so `my_file_name` keeps its underscores (as on Android).
+    if (token.startsWith("_") && (/\w/.test(value[index - 1] ?? "") || /\w/.test(value[index + token.length] ?? ""))) continue;
+    if (index > cursor) runs.push({ text: value.slice(cursor, index) });
+    const double = token.startsWith("**") || token.startsWith("__");
+    const code = token.startsWith("`");
+    const mark = code ? "code" : double ? "bold" : token.startsWith("_") ? "italic" : token.startsWith("*") ? "italic" : "";
+    const delimiter = code ? 1 : double ? 2 : 1;
+    runs.push({ text: token.slice(delimiter, -delimiter), ...(mark ? { marks: [mark] } : {}) });
+    cursor = index + token.length;
+  }
+  if (cursor < value.length) runs.push({ text: value.slice(cursor) });
+  return runs;
+}
+
+function messageButtons(message: RecordValue, messageId: string): BusinessSuggestion[] {
+  const template = object(message.templateData);
+  const candidates: unknown[] = Array.isArray(template.buttons) ? template.buttons : [];
+  const content = object(message.content);
+  const cards = Array.isArray(object(content.template).buttons) ? object(content.template).buttons as unknown[] : [];
+  candidates.push(...cards);
+  for (const raw of Array.isArray(message.data) ? message.data : []) {
+    const data = object(object(raw).data);
+    for (const card of Array.isArray(data.cards) ? data.cards : []) candidates.push(...(Array.isArray(object(card).buttons) ? object(card).buttons as unknown[] : []));
+  }
+  return candidates.flatMap((value, index) => {
+    const button = object(value);
+    const label = [button.label, button.title, button.text].find((value): value is string => typeof value === "string" && !!value.trim())?.trim() ?? "";
+    const payload = object(button.payload);
+    const appId = typeof payload.appId === "string" ? payload.appId.trim() : "";
+    const interactionId = typeof payload.interactionId === "string" ? payload.interactionId.trim() : "";
+    if (button.cta && !appId && !interactionId) return [];
+    const enabled = !!label && !!appId && !!interactionId;
+    return label ? [{ id: `${messageId}:suggestion-${index}`, messageId, label, kind: "postback", ...(appId ? { appId } : {}), ...(interactionId ? { interactionId } : {}), enabled, disabled: !enabled }] : [];
+  });
+}
+
+/** Article links and chat postbacks are different Wix button actions. Only expose
+ *  payload-free HTTPS CTAs here; postbacks remain in messageButtons. */
+function articleActions(message: RecordValue, messageId: string): BusinessArticleAction[] {
+  const buttons = object(message.templateData).buttons;
+  if (!Array.isArray(buttons)) return [];
+  return buttons.flatMap((value, index) => {
+    const button = object(value);
+    const label = typeof button.text === "string" ? button.text.trim() : "";
+    const rawUrl = typeof button.cta === "string" ? button.cta.trim() : "";
+    if (!label || !rawUrl || button.payload != null) return [];
+    // No `URL` global in a worker: accept only a plain https URL whose authority carries no credentials.
+    if (!isSafeLink(rawUrl)) return [];
+    return [{ id: `${messageId}:article-${index}`, label, url: rawUrl, style: "secondary" as const, ...webAction }];
+  });
+}
+
+/** Text renders a limited inline Markdown subset, and Android and web ignore backslash escapes (they would
+ *  print the backslash), so nothing is escaped that way. Link syntax is broken once, on the joined text so
+ *  a `](` split across two runs is caught too, with an invisible character: message text can never become
+ *  a tappable link. A lone marker stays literal on every renderer. */
+function markdownFromRuns(runs: BusinessTextRun[]): string {
+  return runs.map((run) => {
+    let text = run.text;
+    const marks = run.marks ?? [];
+    if (marks.includes("code")) return `\`${text.replace(/`/g, "'")}\``;
+    if (marks.includes("bold")) text = `**${text}**`;
+    if (marks.includes("italic")) text = `*${text}*`;
+    return text;
+  }).join("").replace(/\]\(/g, "]\u200b(");
+}
+
+function hiddenInternalNotice(message: RecordValue): boolean {
+  const template = object(message.templateData);
+  const origin = typeof message.originMethod === "string" ? message.originMethod : "";
+  const summary = typeof message.summary === "string" ? message.summary.trim() : "";
+  const text = typeof template.text === "string" ? template.text.trim() : "";
+  const pauseNotice = "AI RESPONSES ARE PAUSED WHILE YOU TALK TO THIS VISITOR";
+  const isPauseNotice = summary.toUpperCase() === pauseNotice || text.toUpperCase() === pauseNotice;
+  const hasActionsOrMedia = !!template.image || !!template.icon || !!template.link ||
+    [template.buttons, template.fields, template.lines].some((value) => Array.isArray(value) && value.length > 0);
+  const content = object(message.content);
+  return message.messageType === "template/minimal" && !!message.appId && /:AI_SITE_CHAT$/i.test(origin) &&
+    isPauseNotice && (!Array.isArray(message.data) || message.data.length === 0) &&
+    Object.keys(content).length === 0 && !hasActionsOrMedia;
+}
+
+const SAFE_LINK = /^https:\/\/[^\s\\@/?#]+(?:[/?#]\S*)?$/;
+/** Sentence punctuation after a link ("…/page." or "(see …/page)") is not part of it. */
+function cleanLinkUrl(raw: string): string {
+  let url = raw;
+  for (;;) {
+    const last = url[url.length - 1];
+    if (last && (".,;:!?".includes(last) || (last === ")" && !url.includes("(")))) url = url.slice(0, -1); else break;
+  }
+  return url;
+}
+/** A plain https link with no control characters (a null byte would pass `\S`). */
+const isSafeLink = (url: string): boolean => SAFE_LINK.test(url) && !/[\u0000-\u001f\u007f-\u009f]/.test(url);
+
+/** Owner tools (a product, a coupon, a scheduling link) reach a member as plain text: a title, detail
+ *  lines and `Label: https://…` lines. On a phone that is a wall of text with a URL nobody can tap, so a
+ *  link line becomes a button and a coupon code its own block. Only plain https links are lifted. A message shown
+ *  without a card (an AI answer) has no coupon block, so `liftCoupon: false` leaves its code in the text. */
+export function extractBusinessMessageExtras(markdown: string, options: { liftCoupon?: boolean } = {}): { text: string; links: { label: string; url: string }[]; couponCode: string } {
+  const liftCoupon = options.liftCoupon ?? true;
+  const kept: string[] = [];
+  const links: { label: string; url: string }[] = [];
+  let couponCode = "";
+  // True only when a button was really added: a repeated link, or one past the sixth, stays in the text.
+  const addLink = (label: string, url: string): boolean => {
+    if (links.length >= 6 || links.some((link) => link.url === url)) return false;
+    links.push({ label: label.replace(/[*_`]/g, "").trim().slice(0, 40) || businessChatCopy('openLink'), url });
+    return true;
+  };
+  for (const line of markdown.split("\n")) {
+    const trimmed = line.trim();
+    const labelled = /^(?:[-*•]\s+)?([^:\n]{1,40}):\s*(https:\/\/\S+)$/.exec(trimmed);
+    const labelledUrl = labelled ? cleanLinkUrl(labelled[2]!) : "";
+    if (labelled && isSafeLink(labelledUrl) && addLink(labelled[1]!, labelledUrl)) continue;
+    const bare = /^(https:\/\/\S+)$/.exec(trimmed);
+    const bareUrl = bare ? cleanLinkUrl(bare[1]!) : "";
+    if (bare && isSafeLink(bareUrl)) {
+      // A bare link is named by the list item above it ("- Settle Into Sleep"), else by its site.
+      const item = /^[-*•]\s+(.{1,60})$/.exec((kept[kept.length - 1] ?? "").trim());
+      if (addLink(item?.[1] ?? `Open ${bareUrl.slice(8).split(/[/?#]/)[0]!.replace(/^www\./, "")}`, bareUrl)) {
+        if (item) kept.pop();
+        continue;
+      }
+    }
+    const code = /^(.*?)[,;]?\s*\b[Cc]ode:\s*([A-Z0-9_-]{3,32})$/.exec(trimmed);
+    if (code && liftCoupon && !couponCode) {
+      couponCode = code[2]!;
+      if (code[1]!.trim()) kept.push(code[1]!.trim());
+      continue;
+    }
+    kept.push(line);
+  }
+  // Text with nothing lifted out is returned untouched, trailing newline included.
+  return { text: links.length || couponCode ? kept.join("\n").trim() : markdown, links, couponCode };
+}
+
+/** Adds only Business business-chat presentation fields to the canonical message rows. */
+export function presentBusinessMessages<T extends Pick<BusinessMessage, "id" | "sender" | "mine" | "createdDate" | "plainText" | "parts">>(
+  rows: T[],
+  raw: unknown[],
+  participantId = "",
+  now = new Date(),
+): (T & {
+  senderAvatar: string;
+  senderName: string;
+  senderInitials: string;
+  senderBadge: string;
+  imageUrl: string;
+  imageDescription: string;
+  noImage: boolean;
+  bodyText: string;
+  bodyRuns: BusinessTextRun[];
+  isAiGenerated: boolean;
+  suggestions: BusinessSuggestion[];
+  articleActions: BusinessArticleAction[];
+  bodyMarkdown: string;
+  dayLabel: string;
+  dayHidden: boolean;
+  startsDay: boolean;
+  scrollAnchor: string;
+  notMine: boolean;
+  couponCode: string;
+  noCoupon: boolean;
+  productSlug: string;
+  productName: string;
+  isCard: boolean;
+  notCard: boolean;
+  noSuggestions: boolean;
+  noActions: boolean;
+  cardTitle: string;
+  cardDetail: string;
+  /** A card with neither title nor detail (a file, a coupon with no line): its text block is hidden, not an empty gap. */
+  noCardText: boolean;
+})[] {
+  const metadata = new Map<string, RecordValue>();
+  for (const value of raw) {
+    const message = object(value);
+    const id = typeof message.id === "string" ? message.id : typeof message._id === "string" ? message._id : "";
+    if (id) metadata.set(id, message);
+  }
+  const dateKey = (date: Date) => `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+  const today = dateKey(now);
+  const yesterday = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
+  const yesterdayKey = dateKey(yesterday);
+  let previousDay = "";
+
+  return rows.filter((row) => !hiddenInternalNotice(metadata.get(row.id) ?? {})).map((row) => {
+    const message = metadata.get(row.id) ?? {};
+    const display = object(message.senderDisplayData);
+    const image = object(display.image);
+    const sender = object(message.sender);
+    const imagePart = row.parts.find((part) => part.kind === "image");
+    const timestamp = new Date(row.createdDate);
+    const key = Number.isFinite(timestamp.getTime()) ? dateKey(timestamp) : "";
+    const startsDay = !!key && key !== previousDay;
+    const dayLabel = startsDay
+      ? key === today ? businessChatCopy('today') : key === yesterdayKey ? businessChatCopy('yesterday') : formatMonthDay(timestamp)
+      : "";
+    if (key) previousDay = key;
+
+    const template = object(message.templateData);
+    // A product the owner sends from the Inbox carries its picture on the card itself (`templateData.image`).
+    const imageUrl = imagePart?.url || cardImage(template.image);
+    const standardEventText = message.messageType === "template/standard-event"
+      ? [template.title, ...(Array.isArray(template.lines) ? template.lines : [])]
+        .filter((value): value is string => typeof value === "string" && !!value.trim())
+        .join("\n")
+      : "";
+    const bodyText = imagePart?.url
+      ? row.parts.filter((part) => part.kind === "text").map((part) => [part.text, ...(part.fields ?? []).map((field) => `${field.name}: ${field.value}`)].filter(Boolean).join("\n")).filter(Boolean).join("\n")
+      : standardEventText || row.plainText;
+    const senderAvatar = safeAvatar(image.url);
+    const mine = participantId && typeof sender.userId === "string" ? sender.userId === participantId : row.mine;
+    const isAiGenerated = message.aiSiteChatSender === "ASSISTANT" || (message.aiSiteChatSender !== "USER" && !!participantId && !mine && !!message.appId && typeof message.originMethod === "string" && /:AI_SITE_CHAT$/i.test(message.originMethod) &&
+      (message.messageType === "message" || message.messageType === "template/standard-event" || message.messageType === "template/card"));
+    const rawSenderName = typeof display.name === "string" && display.name.trim()
+      ? display.name.trim()
+      : typeof display.displayName === "string" && display.displayName.trim() ? display.displayName.trim() : "";
+    const senderName = !mine && /^visitor(?:\s*#?\d+)?$/i.test(rawSenderName) ? "" : rawSenderName;
+    const plainTextRuns = standardEventText
+      ? markdownRuns(standardEventText)
+      : row.parts.filter((part) => part.kind === "text" && typeof part.text === "string").flatMap((part, at) => [...(at > 0 ? [{ text: "\n" }] : []), ...markdownRuns(part.text as string)]);
+    const bodyRuns = htmlMessageRuns(message) ?? plainTextRuns;
+    const bodyMarkdown = markdownFromRuns(bodyRuns);
+    const buttons = messageButtons(message, row.id);
+    // An AI answer is never a card, and only a card shows the coupon block, so its code stays in its text.
+    const extras = mine ? { text: bodyMarkdown, links: [], couponCode: "" } : extractBusinessMessageExtras(bodyMarkdown, { liftCoupon: !isAiGenerated });
+    // A card is a title and detail lines: Wix sends events as one, and an owner's product, coupon or scheduling link
+    // arrives as plain text of the same shape. Its title leads in bold, and a coupon's title is its code, which
+    // the coupon block already shows.
+    const lines = extras.text.split("\n");
+    const first = lines[0]!.trim();
+    // A title is short, is not a sentence, and carries no markup of its own: bolding a whole paragraph would flip the
+    // meaning of the `**` already inside it.
+    const titleLike = lines.length > 1 && first.length <= 60 && !/[.!?:]$/.test(first) && !first.includes("*");
+    const cardLike = titleLike && (!!standardEventText || extras.links.length > 0 || !!extras.couponCode);
+    const titled = cardLike && extras.couponCode && first === extras.couponCode ? lines.slice(1).join("\n")
+      : cardLike && lines.length > 1 && !first.startsWith("**") ? `**${first}**\n${lines.slice(1).join("\n")}` : extras.text;
+    // A product card links to its store page; the slug lets the worker find the product and show its picture.
+    // The link is a line of the text or, from the Inbox's product tool, a template button.
+    // Only a card shows the picture, so an AI answer (never a card) does not look one up.
+    const productPage = cardLike && !isAiGenerated ? [...extras.links, ...articleActions(message, row.id)].map((link) => /^https:\/\/[^/?#]+(?:\/[^/?#]+)*?\/product-page\/([^/?#]+)/i.exec(link.url)?.[1]).find(Boolean) : undefined;
+    // A file, recording or video has no inline player here: it gets a button that opens it.
+    const attachmentLinks = row.parts.filter((part) => (part.kind === "file" || part.kind === "audio" || part.kind === "video") && !!part.url)
+      // A file, recording or video always opens as itself in the browser, wherever its URL lives.
+      .map((part, at) => ({ id: `${row.id}:attachment-${at}`, label: (part.fileName || part.caption || `Open ${part.kind}`).slice(0, 40), url: part.url as string, style: "secondary" as const, ...webAction, routable: false }));
+    // The card look (a framed box with a centred title) is for what an owner tool sends: a product, coupon, scheduling
+    // or pay link, an event, or a file. A coupon's title is its code, which the coupon block already shows.
+    // An AI answer is text with link pills, as on the site's Smart Chat, even when it is shaped like a card.
+    const isCard = !mine && !isAiGenerated && (cardLike || !!extras.couponCode || (attachmentLinks.length > 0 && !imageUrl));
+    const cardTitle = cardLike && !(extras.couponCode && first === extras.couponCode) ? first.replace(/^\*\*(.+)\*\*$/, "$1") : "";
+    // A product card shows its name and price, as on the site's Smart Chat; the "4 variants | In stock" summary the
+    // Inbox adds to the text is left out of it.
+    const cardLines = cardTitle ? lines.slice(1) : titled.split("\n");
+    const cardDetail = (productPage ? cardLines.filter((line) => !/^\s*\d+\s+variants?\b|\|\s*(?:in|out of)\s+stock\s*$/i.test(line)) : cardLines).join("\n");
+    const articles = [...articleActions(message, row.id), ...attachmentLinks, ...extras.links.map((link, at) => ({ id: `${row.id}:link-${at}`, label: link.label, url: link.url, style: /\b(view|buy|shop|book|pay|order|checkout|reserve|schedule)\b/i.test(link.label) ? "primary" as const : "secondary" as const, ...webAction }))]
+      .filter((action, at, all) => all.findIndex((other) => other.url === action.url) === at);
+
+    return {
+      ...row,
+      mine,
+      side: mine ? "mine" : "other",
+      senderAvatar,
+      senderName,
+      senderInitials: typeof display.initials === "string" && display.initials.trim() ? display.initials.trim() : initials(senderName),
+      senderBadge: participantId && !mine ? isAiGenerated ? businessChatCopy('aiAssistant') : businessChatCopy('staffResponse') : "",
+      imageUrl,
+      // A card's own picture is named by the card (a product's name), not as an anonymous attachment.
+      imageDescription: imagePart?.caption || (imageUrl && !imagePart?.url && first ? first.replace(/\*/g, "") : businessChatCopy('imageAttachment')),
+      noImage: !imageUrl,
+      bodyText,
+      bodyRuns,
+      bodyMarkdown: titled,
+      couponCode: extras.couponCode,
+      noCoupon: !extras.couponCode,
+      productSlug: productPage ?? "",
+      productName: productPage ? first : "",
+      isCard,
+      notCard: !isCard,
+      noSuggestions: buttons.length === 0,
+      noActions: articles.length === 0,
+      cardTitle,
+      noCardText: !cardTitle && !cardDetail.trim(),
+      cardDetail,
+      isAiGenerated,
+      suggestions: buttons,
+      articleActions: articles,
+      dayLabel,
+      dayHidden: !dayLabel,
+      startsDay,
+      scrollAnchor: `himi_business_chat.message_${row.id}`,
+      notMine: !mine,
+    };
+  });
+}
+
+/** Resolve a suggestion only from the currently normalized rows and only when the server supplied both postback fields. */
+export function findBusinessSuggestion<T extends { suggestions?: BusinessSuggestion[] }>(rows: T[], suggestionId: string): BusinessSuggestion | undefined {
+  if (!suggestionId) return undefined;
+  return rows.flatMap((row) => row.suggestions ?? []).find((suggestion) => suggestion.id === suggestionId && suggestion.enabled &&
+    (suggestion.kind === "visitor_option" || (!!suggestion.appId && !!suggestion.interactionId)));
+}
+
+/** Execute a row's verified semantic button only inside its still-current member room/session. */
+export async function dispatchBusinessSuggestion<T extends { suggestions?: BusinessSuggestion[] }>(
+  rows: T[],
+  suggestionId: string,
+  session: { member: boolean; roomId: string; principal: string; currentPrincipal: string; scope: string; currentScope: string },
+  submit: (suggestion: BusinessSuggestion) => Promise<unknown>,
+): Promise<boolean> {
+  if (!session.member || !session.principal || session.principal !== session.currentPrincipal || session.scope !== session.currentScope) return false;
+  const suggestion = findBusinessSuggestion(rows, suggestionId);
+  if (!suggestion || (suggestion.kind === "postback" && !session.roomId)) return false;
+  // A submit that reports `false` (a stale quick reply nobody posted) is not a send.
+  return (await submit(suggestion)) !== false;
+}