@wix/himalaya-cli 0.1445.0 → 0.1447.0

package/templates/branded-lite/tier5-src/_shared/business-chat-transport.ts

@@ -0,0 +1,102 @@
+// The business chat's Wix calls: the member-role chat-web SDK for rooms, history and sends, plus the two
+// calls the SDK has no helper for (a tapped button, a private attachment's download URL).
+import { getChatToken, getMessagesPage, listChatroomsPage, sendChatMessage } from "@himalaya/wix-chat-web";
+import { assertMemberAccess, memberAccess } from "./member-access.js";
+
+const MANAGE = "https://manage.wix.com";
+const MEMBER = { role: "member" } as const;
+type Raw = Record<string, unknown>;
+type Bridge = { call(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<unknown> };
+
+/** Who is signed in. `userId` is empty until the host reports it; the chat then tells the business
+ *  side apart by the room's participant id instead. */
+export interface ChatIdentity { authenticated: boolean; userId: string; email: string; scope: string }
+export async function chatIdentity(): Promise<ChatIdentity> {
+  const member = await memberAccess();
+  return { authenticated: !!member.email, userId: "", email: member.email, scope: member.scope };
+}
+export const assertChatIdentity = (identity: ChatIdentity): Promise<void> => assertMemberAccess(identity);
+
+/** Every request is fenced: the member is re-checked before it goes out and again before its response is
+ *  used, so a sign-out or account switch mid-request never leaks one member's data to the next. */
+async function fenced<T>(identity: ChatIdentity, run: () => Promise<T>): Promise<T> {
+  await assertChatIdentity(identity);
+  const result = await run();
+  await assertChatIdentity(identity);
+  return result;
+}
+
+/** Any other member-scoped call (the AI chat's) goes through the same fence. */
+export const fence = fenced;
+
+// Minting a chat token is a network round trip, and every chat call used to mint its own. One token
+// per member is reused until the member changes or a request using it is refused.
+let cachedToken: { key: string; token: string } | null = null;
+const tokenKey = (identity: ChatIdentity): string => `${identity.email}|${identity.scope}`;
+async function chatTokenFor(identity: ChatIdentity): Promise<string> {
+  const key = tokenKey(identity);
+  if (cachedToken?.key === key) return cachedToken.token;
+  const { chatToken } = await getChatToken(MEMBER);
+  // The host mints for whoever is signed in NOW: a token minted while the member switched belongs to the
+  // new member and must not be cached under the old one.
+  await assertChatIdentity(identity);
+  cachedToken = { key, token: chatToken };
+  return chatToken;
+}
+/** Runs `run` with the member's cached token; a refused request mints a fresh token and tries once more. */
+async function withToken<T>(identity: ChatIdentity, run: (chatToken: string) => Promise<T>): Promise<T> {
+  const reused = cachedToken?.key === tokenKey(identity);
+  try {
+    return await run(await chatTokenFor(identity));
+  } catch (error) {
+    cachedToken = null;
+    if (!reused || !/\b(?:401|403)\b|token/i.test(String((error as Error)?.message ?? error))) throw error;
+    return run(await chatTokenFor(identity));
+  }
+}
+
+const MAX_ROOM_PAGES = 20;
+/** Every chatroom the member can see: the cursor is followed so the business room is found on any page. */
+export const listRooms = (identity: ChatIdentity): Promise<{ items: Raw[]; more: boolean }> => fenced(identity, async () => {
+  const items: Raw[] = [];
+  let nextPointer: number | string | undefined;
+  for (let page = 0; page < MAX_ROOM_PAGES; page++) {
+    const result = await withToken(identity, (chatToken) => listChatroomsPage({ ...MEMBER, chatToken, pageSize: 50, ...(nextPointer !== undefined ? { nextPointer } : {}) }));
+    items.push(...(result.items as unknown as Raw[]));
+    nextPointer = result.nextPointer;
+    if (nextPointer === undefined) return { items, more: false };
+  }
+  return { items, more: true };
+});
+export const messagesPage = (identity: ChatIdentity, roomId: string): Promise<Raw[]> => fenced(identity, async () =>
+  (await withToken(identity, (chatToken) => getMessagesPage(roomId, { ...MEMBER, chatToken, pageSize: 50, ordering: "Desc" }))).items as unknown as Raw[]);
+export const sendMessage = (identity: ChatIdentity, roomId: string, intent: { id: string; text: string }): Promise<void> =>
+  fenced(identity, () => withToken(identity, (chatToken) => sendChatMessage(roomId, intent.text, { ...MEMBER, chatToken, messageId: intent.id })));
+
+function bridge(): Bridge {
+  const api = (globalThis as unknown as { himalaya?: { wixApi?: Bridge } }).himalaya?.wixApi;
+  if (!api) throw new Error("wix_api_bridge_unavailable");
+  return api;
+}
+/** A tapped button is a silent, ephemeral message carrying the button's chat action. */
+export const sendButton = (identity: ChatIdentity, roomId: string, input: { id: string; text: string; appId: string; interactionId: string }): Promise<void> => fenced(identity, async () => {
+  await withToken(identity, (chatToken) => bridge().call("POST", `${MANAGE}/_api/chat-web/v2/chatrooms/${encodeURIComponent(roomId)}/messages`, {
+    sendMessageBody: { id: input.id, messageType: "message", messageTypeVersion: 1, summary: input.text, isEphemeral: true, isSilent: true, data: [{ mimeType: "text/plain", data: { text: input.text } }] },
+    sendMessageOptions: { chatAction: { actionType: "BUTTON_INTERACTION", appId: input.appId, interactionId: input.interactionId } },
+  }, { ChatToken: chatToken }));
+});
+
+const https = (value: unknown): string => (typeof value === "string" && /^https:\/\/[^\s\\]+$/.test(value) ? value : "");
+/** A fresh, authorized URL for an attachment. A private file is always fetched by its id. */
+export const attachmentUrl = (identity: ChatIdentity, media: { mediaId?: string; mediaProvider?: string; url?: string; fileName?: string }): Promise<string> => fenced(identity, async () => {
+  if (media.mediaProvider === "WixMediaPrivate") {
+    if (!media.mediaId) throw new Error("attachment_has_no_media_id");
+    const response = await bridge().call("POST", "/communication-channels-media/v1/download-url", {
+      fileId: media.mediaId, ...(media.fileName ? { downloadFileName: media.fileName } : {}),
+    }) as Raw | null;
+    const url = https(response?.downloadUrl);
+    if (!url) throw new Error("attachment_download_url_invalid");
+    return url;
+  }
+  return https(media.url);
+});

package/templates/branded-lite/tier5-src/_shared/collection-query.ts

@@ -20,6 +20,13 @@ export interface CollectionQueryState<Row> extends CollectionPage<Row> {
   pageError: boolean;
   complete: boolean;
   error: string;
+  /** The rows are the source's `cached` page, shown while the live read is still out. */
+  provisional?: boolean;
+}
+/** What a collection showed, as `shownPage` hands it out and `seed` takes it back on a restored boot. */
+export interface CollectionShownPage<Row> {
+  state: CollectionQueryState<Row>;
+  loadedPages: number;
 }
 export interface CollectionQuerySource<Row> {
   fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
@@ -50,13 +57,19 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   let state: CollectionQueryState<Row> = { criteria: normalize({}), items: [], nextCursor: '', status: 'idle', loadingMore: false, pageError: false, complete: false, error: '' };
   /** The query a revalidation is running under: its snapshots are held back until it is done. */
   let revalidating = -1;
-  /** What the screen shows: the last published state, restored when a revalidation fails. */
-  let shown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
+   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
+   *  it leaves those rows on screen, so it is still this. */
+  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
   let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
   const emit = () => {
     if (disposed || revalidating === generation) return;
-    shown = { state: snapshot(), loadedPages };
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept.
+    if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
+      lastShown = state.items.length > 0 ? { state: snapshot(), loadedPages } : undefined;
+    }
     publish(snapshot());
   };
   const merge = (old: Row[], page: Row[]): Row[] => {
@@ -77,14 +90,14 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     const criteria = copyQuery(state.criteria);
     if (!append) loadedPages = 0;
     state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
-      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false }) };
+      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
     emit();
     try {
       if (!append && source.cached) {
         const cached = await source.cached(criteria).catch(() => undefined);
         if (disposed || generation !== revision) return;
         if (cached?.items.length) {
-          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false };
+          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
           emit();
         }
       }
@@ -94,17 +107,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
         total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
         metadata: page.metadata ?? (append ? state.metadata : undefined),
-        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor };
+        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
       loadedPages++;
     } catch (error) {
       if (disposed || generation !== revision) return;
       const clear = source.clearOnError?.(error) === true;
       // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
       clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
+      if (clearedByError) lastShown = undefined;
       if (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
-        error: source.errorMessage?.(error) ?? '' };
+        provisional: false, error: source.errorMessage?.(error) ?? '' };
     }
     emit();
   };
@@ -117,8 +131,7 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       const next = normalize(criteria);
       const same = JSON.stringify(next) === JSON.stringify(state.criteria);
       const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
-      const showing = shown && shown.state.status === 'ready' && shown.state.items.length > 0 && !shown.state.pageError
-        && !shown.state.loadingMore && JSON.stringify(shown.state.criteria) === JSON.stringify(next) ? shown : undefined;
+      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
       if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
@@ -140,6 +153,27 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
         emit();
       }
     },
+    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
+     *  state; undefined when it shows none. */
+    shownPage(): CollectionShownPage<Row> | undefined {
+      if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
+      const page = lastShown.state;
+      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+    },
+    /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
+     *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page. */
+    seed(page: unknown): boolean {
+      const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
+      const restored = candidate?.state;
+      if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
+        || !Array.isArray(restored.items) || restored.items.length === 0 || typeof restored.nextCursor !== 'string') return false;
+      try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
+      state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
+        loadingMore: false, pageError: false, provisional: false, error: '' };
+      loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      lastShown = { state: snapshot(), loadedPages };
+      return true;
+    },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),
     retry: () => fetch(state.pageError),

package/templates/branded-lite/tier5-src/_shared/collection-service.ts

@@ -142,6 +142,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // the query controller carries a recoverable failure. Treat each shape as
     // one collection state so the shared UI never renders a blank catalog.
     const backendState = backend?.controller.getState();
+    const provisional = backendState?.provisional === true;
     const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
     const domainError = typeof s.error === 'string' ? s.error.trim() : '';
     const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
@@ -177,13 +178,17 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // un-narrowed failure. A re-query while typing keeps it (and the search field's focus).
     const hideChrome = (!narrowed && !s.nextCursor && projected.loaded < COLLECTION_CHROME_MIN_ITEMS)
       || sourceEmpty || ((loading || errored) && rows.length === 0 && !narrowed);
-    return { ...s, collection: { ...prefs, ...projected,
+    // Kept with the state, so a cold boot restored from disk shows its last page and revalidates behind it.
+    const collectionShown = backend?.controller.shownPage();
+    return { ...s, ...(backend ? { collectionShown: collectionShown ?? null } : {}), collection: { ...prefs, ...projected,
       hideChrome, noActiveCriteria: !narrowed,
       viewName, viewMessage, saveMessage, noSavedViews: prefs.savedViews.length === 0,
       cursor: s.pageError === true || s.loadingMore === true ? '' : s.nextCursor,
       noMore: !s.nextCursor || s.pageError === true || s.loadingMore === true,
       noPageError: s.pageError !== true,
-      noOffline: s.fromCache !== true,
+      // Rows read from the device ahead of the live read are shown as they are: "saved offline" is what stays on
+      // screen when the live read failed, not a first visit that is still loading.
+      noOffline: s.fromCache !== true || provisional,
       noError: !errored,
       noRetry: !canRetry || signInRequired,
       noSignIn: !signInRequired,
@@ -202,7 +207,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       filtersPresented, previewPresented: !!previewId, preview: projected.items.filter(row => row.collectionId === previewId),
       persistenceLabel: persisted.available ? copyParam('collection.onDevice', 'Saved on this device') : copyParam('collection.sessionOnly', 'Choices last for this session'),
       noEmpty: loading || errored || sourceEmpty || domainNarrowed || projected.items.length > 0,
-      summary: backend && config.backendQuery && s.fromCache
+      summary: backend && config.backendQuery && s.fromCache && !provisional
         ? copyParam('collection.cached', 'Saved offline · may be outdated')
         : collectionSummary({ shown: projected.items.length, loaded: projected.loaded, backend: !!(backend && config.backendQuery),
           total: typeof s.total === 'number' ? s.total : undefined, noun: config.countNoun
@@ -345,6 +350,13 @@ export function defineBackendCollection<S extends object, Row extends object>(na
     apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
   });
   const handle = (options.register ?? register)(name, definition);
+  // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
+  // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)
+  // starts its first load as before, never from rows it chose not to restore.
+  const restored = (handle as { getState?: () => State }).getState?.();
+  const rowsKey = COLLECTIONS[name]?.rows;
+  const restoredRows = rowsKey ? restored?.[rowsKey] : undefined;
+  if (Array.isArray(restoredRows) && restoredRows.length > 0) controller.seed(restored?.collectionShown);
   publish = () => handle.collectionDataChanged();
   return handle;
 }

package/templates/branded-lite/tier5-src/_shared/iap-presentation.ts

@@ -45,7 +45,9 @@ export function withIapPresentation<S extends object>(options: {
       return project(next);
     }]));
     const service = (options.register ?? defineService)(name, {
-      ...definition, notHydrated: [...(definition.notHydrated ?? []), ...options.transientKeys],
+      // The collection's shown page goes with the rows and chrome it copies: kept out of the restore with them.
+      ...definition, notHydrated: [...(definition.notHydrated ?? []), ...options.transientKeys,
+        ...((options.transientKeys as string[]).includes('collection') ? ['collectionShown' as keyof S & string] : [])],
       actions: { ...actions, iapPublish: project, iapPoll: async () => { await commerce.poll(); return undefined; },
         iapRefresh: async () => { await commerce.loadPrices(items); return undefined; } },
     });

package/templates/branded-lite/tier5-src/business-chat/index.ts

@@ -0,0 +1,304 @@
+import { defineService } from '@himalaya/state';
+import * as chat from '../_shared/business-chat-transport.js';
+import type { ChatIdentity } from '../_shared/business-chat-transport.js';
+import { type MessageRow } from '../_shared/business-chat-message-model.js';
+import { businessChatSendRejected, draftAfterAcceptedSend, pendingIntentWasObserved, chronologicalMessages, newBusinessChatIntent, type BusinessChatIntent } from '../_shared/business-chat-model.js';
+import { subscribeRealtime, unsubscribeRealtime, getRealtimeStatus, type RealtimeStatus, type RealtimeEventEnvelope } from '@himalaya/wix-chat';
+import { dispatchBusinessSuggestion, businessRealtimeStatusLabel, businessVisitorOptionSuggestions, presentBusinessMessages, selectExistingBusinessRoom, shouldRefreshBusinessHistory, type BusinessSuggestion, type BusinessVisitorOptions, businessVisitorOptionRequest, businessVisitorOptionsFromAiMessages, newBusinessSelectionId} from '../_shared/business-chat-presenter.js';
+import { listMessages, streamMessages } from '@himalaya/wix-ai-site-chat';
+import { hostSiteFromInput } from '../_shared/branded-lite-hosted.js';
+
+type PendingIntent = BusinessChatIntent;
+type BusinessMessageRow = MessageRow & {
+ senderAvatar:string; senderName:string; senderInitials:string; senderBadge:string; imageUrl:string; imageDescription:string; noImage:boolean; bodyText:string; bodyMarkdown:string; bodyRuns:{text:string;marks?:string[]}[]; isAiGenerated:boolean; suggestions:BusinessSuggestion[]; visitorOptions:BusinessVisitorOptions|null; notMine:boolean;
+ dayLabel:string; dayHidden:boolean; startsDay:boolean; scrollAnchor:string;
+};
+type State = {
+  phase:'loading'|'ready'|'error'|'guest'; error:string; notice:string; member:boolean;
+  roomId:string; principal:string; scope:string; messages:BusinessMessageRow[]; draft:string; busy:boolean;
+  liveState:string; liveReason:string; realtimeEventCount:number; lastRealtimeEventType:string; pendingIntent:PendingIntent|null; scrollAnchor:string; scrollSend:number; usedSuggestionIds:string[]; visitorOptions:BusinessVisitorOptions|null; quickReplies:BusinessSuggestion[]; hasQuickReplies:boolean; noQuickReplies:boolean;
+  liveLabel:string; hasActiveRoom:boolean; noActiveRoom:boolean; isGuest:boolean; notGuest:boolean; realtimeDiagnostic:string; noError:boolean; noNotice:boolean; noMessages:boolean; hasMessages:boolean; noEmpty:boolean; notLoading:boolean;
+  hostedName:string; hasHostedName:boolean; noHostedName:boolean;
+  sendDisabled:boolean; sendEnabled:boolean; noLive:boolean; loadingHidden:boolean; errorText:string; loadFailure:string;
+};
+// A hosted build serves many businesses: the title is the site the host opened, not the app's own name.
+const hostedName=hostSiteFromInput((globalThis as {himalaya?:{input?:unknown}}).himalaya?.input)?.name??'';
+const initial:State={hostedName,hasHostedName:!!hostedName,noHostedName:!hostedName,phase:'loading',error:'',notice:'',member:false,roomId:'',principal:'',scope:'',messages:[],draft:'',busy:false,
+  liveState:'unavailable',liveReason:'',realtimeEventCount:0,lastRealtimeEventType:'',liveLabel:'',hasActiveRoom:false,noActiveRoom:true,isGuest:false,notGuest:true,realtimeDiagnostic:'',pendingIntent:null,scrollAnchor:'',scrollSend:0,usedSuggestionIds:[],visitorOptions:null,quickReplies:[],hasQuickReplies:false,noQuickReplies:true,noError:true,noNotice:true,noMessages:true,hasMessages:false,noEmpty:true,notLoading:false,sendDisabled:true,sendEnabled:false,noLive:true,loadingHidden:false,errorText:'',loadFailure:''};
+let currentIdentity:ChatIdentity|null=null;
+let subscriptionId='';
+let initFlight=false;
+let sendFlight=false;
+let suggestionFlight=false;
+let refreshFlight=false;
+let refreshQueued=false;
+let epoch=0;
+let statusSeq=0;
+let eventDuringInit=false;
+let statusDuringInit:{state:string;reason:string}|null=null;
+// Read through functions: a plain read after init's own assignment is narrowed by the compiler to its initial value.
+function takeEventDuringInit():boolean{const seen=eventDuringInit;eventDuringInit=false;return seen;}
+function takeStatusDuringInit():{state:string;reason:string}|null{const seen=statusDuringInit;statusDuringInit=null;return seen;}
+let draftRevision=0;
+let businessParticipantId='';
+let loadStage:'room_selection'|'history_request'|'history_normalization'|'ai_enrichment'='room_selection';
+let readServiceState:()=>State=()=>shape(initial);
+
+/** The member-scoped AI conversation's current unanswered quick replies. */
+async function loadBusinessVisitorOptions():Promise<BusinessVisitorOptions|null>{
+ const response=await chat.fence(me(),()=>listMessages({cursorPaging:{limit:20}}));
+ return businessVisitorOptionsFromAiMessages(response.messages??[]);
+}
+/** Submit a displayed quick reply through the AI endpoint; a label counts only while it is still a current option. */
+async function sendBusinessVisitorOption(options:BusinessVisitorOptions|null|undefined,label:string):Promise<boolean>{
+ const request=businessVisitorOptionRequest(options,label,newBusinessSelectionId());
+ if(!request)return false;
+ await chat.fence(me(),()=>streamMessages(request));
+ return true;
+}
+function liveDescription(state:string,reason:string):string{return businessRealtimeStatusLabel(state,reason);}
+function shape(s:State):State{const used=new Set(s.usedSuggestionIds);const messages=s.messages.map(row=>({...row,suggestions:(row.suggestions||[]).map(button=>used.has(button.id)?{...button,enabled:false,disabled:true}:button)}));const quickReplies=(s.quickReplies||[]).map(button=>used.has(button.id)?{...button,enabled:false,disabled:true}:button);const quickEnabled=quickReplies.some(button=>button.enabled);return {...s,messages,quickReplies,hasQuickReplies:quickEnabled,noQuickReplies:!quickEnabled,scrollAnchor:messages[messages.length-1]?.scrollAnchor||'',liveLabel:liveDescription(s.liveState,s.liveReason),hasActiveRoom:!!s.roomId,noActiveRoom:!s.roomId,hasHostedName:!!s.hostedName,noHostedName:!s.hostedName,isGuest:s.phase==='guest',notGuest:s.phase!=='guest',realtimeDiagnostic:`state=${s.liveState}; reason=${s.liveReason||'none'}; events=${s.realtimeEventCount}; lastType=${/^(message|messagesent)$/i.test(s.lastRealtimeEventType)?s.lastRealtimeEventType:'none'}`,errorText:s.error,loadingHidden:s.phase!=='loading'||!!s.error,noError:!s.error,noNotice:!s.notice,noMessages:!messages.length,hasMessages:!!messages.length,noEmpty:s.phase!=='ready'||!!messages.length,
+  notLoading:s.phase!=='loading',sendDisabled:!s.member||!s.roomId||s.busy||!s.draft.trim()||!!s.pendingIntent,sendEnabled:!!s.member&&!!s.roomId&&!s.busy&&!!s.draft.trim()&&!s.pendingIntent,noLive:!s.roomId||s.liveState==='connected'};}
+function safeLoadFailure(error:unknown):string{
+ const name=error instanceof Error?error.name:'UnknownError';
+ const code=(error as {code?:unknown}|null)?.code;
+ const safeCode=typeof code==='string'&&/^[a-z0-9_]{1,48}$/i.test(code)?`:${code}`:'';
+ return `${loadStage}:${/^(TypeError|SyntaxError|ProtocolError|Unsupported|Error)$/.test(name)?name:'OtherError'}${safeCode}`;
+}
+function value(arg:unknown):string{if(typeof arg==='string')return arg;const a=arg as Record<string,unknown>|null;return typeof a?.value==='string'?a.value:'';}
+function param(arg:unknown,key:string):string{const a=arg as Record<string,unknown>|null;const p=a?.params as Record<string,unknown>|undefined;return typeof a?.[key]==='string'?a[key] as string:typeof p?.[key]==='string'?p[key] as string:'';}
+async function presentMessages(existing:BusinessMessageRow[],raw:unknown[],memberId?:string):Promise<BusinessMessageRow[]>{
+ const rows=chronologicalMessages(existing,raw,memberId) as BusinessMessageRow[];
+ const prepared=await Promise.all(rows.map(async row=>{
+  const parts=await Promise.all(row.parts.map(async part=>{
+   if(part.kind!=='image')return part;
+   if(part.mediaProvider==='WixMediaPrivate'&&part.mediaId){
+    try{return {...part,url:await chat.attachmentUrl(me(),part)};}catch{return {...part,url:''};}
+   }
+   return part;
+  }));
+  return {...row,parts};
+ }));
+ return presentBusinessMessages(prepared as unknown as Parameters<typeof presentBusinessMessages>[0],raw,businessParticipantId) as unknown as BusinessMessageRow[];
+}
+function me():ChatIdentity{
+ const identity=currentIdentity;
+ if(!identity?.authenticated)throw new Error('member_sign_in_required');
+ return identity;
+}
+async function getCurrentMember():Promise<ChatIdentity>{return chat.chatIdentity();}
+async function resolveExistingBusinessRoom(startEpoch:number):Promise<{id:string;participantId:string}>{
+ businessParticipantId='';
+ const page=await chat.listRooms(me());
+ if(startEpoch!==epoch)throw new Error('MemberAccessChanged');
+  const room=selectExistingBusinessRoom(page.items);
+ if(!room)throw new Error('existing_business_conversation_unavailable');
+ return room;
+}
+function safeError(error:unknown,operation:'load'|'send'|'init'):string{
+ const text=String((error as Error)?.message||error);
+ if(/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(text))return 'Your member session changed. Sign in again to continue.';
+ if(/approved first-party|webwix_owner_only|chat_setup_scope_unavailable/i.test(text))return 'This app host cannot reach the inbox yet.';
+ return operation==='send'?'Message delivery could not be confirmed. Check the conversation before trying again.':
+  operation==='init'?'Couldn’t open the conversation. Try again.':'Couldn’t load the conversation. Try again.';
+}
+async function endSubscription():Promise<void>{const id=subscriptionId;subscriptionId='';if(id)try{await unsubscribeRealtime({subscriptionId:id});}catch{}}
+function clearPrivate(s:State,phase:'guest'|'error'='guest'):State{
+ currentIdentity=null;businessParticipantId='';epoch++;void endSubscription();
+ return shape({...initial,phase,error:phase==='guest'?'Sign in to send a message.':s.error});
+}
+let refreshTail:Promise<unknown>=Promise.resolve();
+/** One refresh runs at a time. A caller that needs the data (init, a send) waits for the one in flight and
+ *  then runs its own; a realtime event only asks the running one to go again, and gets nothing back. */
+async function loadHistory(s:State,wait=false):Promise<State|undefined>{
+ if(!s.roomId)return s;
+ while(refreshFlight){
+  if(!wait){refreshQueued=true;return withLiveDraft(s);}
+  await refreshTail.catch(()=>{});
+ }
+ const run=refreshHistory(s);
+ refreshTail=run;
+ return run;
+}
+async function refreshHistory(s:State):Promise<State|undefined>{
+ refreshFlight=true;const startEpoch=epoch;const roomId=s.roomId;const principal=s.principal;const startDraftRevision=draftRevision;
+ // A refresh that outlived its member or session says nothing: returning a state would overwrite the new one.
+ const stale=()=>startEpoch!==epoch||(currentIdentity?.userId||currentIdentity?.email)!==principal;
+ try{
+  loadStage='history_request';
+  // The room history and the AI's open options are independent reads: fetch them together.
+  const optionsRead:Promise<BusinessVisitorOptions|null>=currentIdentity?.authenticated?loadBusinessVisitorOptions().catch(()=>null/* Optional AI list failure must not hide Inbox history. */):Promise.resolve(null);
+  const page=await chat.messagesPage(me(),roomId);
+  const visitorOptions=await optionsRead;
+  if(stale())return undefined;
+  loadStage='history_normalization';
+  // Presented from the page alone: a row kept from an earlier page would be re-presented without the
+  // metadata that only the page carries (sender, avatar, AI badge, article buttons).
+  const messages=await presentMessages([],page,currentIdentity?.userId||undefined);
+  if(stale())return undefined;
+  // Read the live state last: what other actions changed while this one awaited is theirs to keep.
+  const latest=readServiceState();
+  const same=latest.roomId===roomId&&latest.principal===principal;
+  // What was typed while this ran is kept even on the first load, when the live state is still empty.
+  const liveDraft=draftRevision!==startDraftRevision?latest.draft:s.draft;
+  const base:State=same?withLiveFields(s,latest,liveDraft):{...s,draft:liveDraft};
+  const intentObserved=pendingIntentWasObserved(messages,base.pendingIntent);
+  const draft=intentObserved&&base.pendingIntent&&base.draft.trim()===base.pendingIntent.text?'':base.draft;
+  return shape({...base,messages,visitorOptions,quickReplies:businessVisitorOptionSuggestions(visitorOptions),draft,pendingIntent:intentObserved?null:base.pendingIntent,phase:'ready',error:'',loadFailure:''});
+ }catch(error){
+  const wrapped=error instanceof Error?error:new Error('load_failed');
+  Object.assign(wrapped,{businessLoadFailure:safeLoadFailure(error)});
+  throw wrapped;
+ }finally{refreshFlight=false;}
+}
+/** What other actions own and may have changed while this one awaited, taken from the live state. A state
+ *  built from a snapshot taken before an await must carry these forward or it rolls them back. */
+function withLiveFields(st:State,latest:State,draft:string):State{
+ return {...st,draft,pendingIntent:latest.pendingIntent||st.pendingIntent,
+  usedSuggestionIds:[...new Set([...st.usedSuggestionIds,...latest.usedSuggestionIds])],
+  liveState:latest.liveState,liveReason:latest.liveReason,realtimeEventCount:Math.max(st.realtimeEventCount,latest.realtimeEventCount),lastRealtimeEventType:latest.lastRealtimeEventType,
+  scrollSend:Math.max(st.scrollSend,latest.scrollSend)};
+}
+function withLiveDraft(st:State):State{const latest=readServiceState();return withLiveFields(st,latest,latest.draft);}
+const svc=defineService<State,Record<string,(s:State,a?:unknown)=>State|undefined|Promise<State|undefined>>>('businessChat',{
+ state:shape(initial),notHydrated:Object.keys(initial) as (keyof State)[],
+ actions:{
+  init:async s=>{
+   if(initFlight)return s;initFlight=true;eventDuringInit=false;statusDuringInit=null;
+   const oldPrincipal=s.principal;
+   const initRevision=draftRevision;
+   // Text typed at any point of the load, subscribe step included, outlives the snapshot this started from.
+   const keepTyped=(st:State):State=>draftRevision!==initRevision?{...st,draft:readServiceState().draft}:st;
+   let myEpoch=epoch;
+   try{
+    loadStage='room_selection';
+    const identity=await getCurrentMember();
+    if(myEpoch!==epoch)return undefined;
+    if(!identity.authenticated)throw new Error('member_sign_in_required');
+    if(oldPrincipal&&(oldPrincipal!==(identity.userId||identity.email)||s.scope!==identity.scope)){s=clearPrivate(s,'guest');myEpoch=epoch;}
+    currentIdentity=identity;
+    s=shape({...s,phase:'loading',member:true,principal:identity.userId||identity.email,scope:identity.scope,error:'',notice:''});
+    const existingRoom=await resolveExistingBusinessRoom(myEpoch);
+    if(myEpoch!==epoch)return undefined;
+    businessParticipantId=existingRoom.participantId;
+    s=shape({...s,roomId:existingRoom.id});
+    // Subscribe before reading history, so anything that lands after the read arrives as a realtime event.
+    if(!subscriptionId){try{const result=await subscribeRealtime({onEvent:'businessChat.onEvent',onStatus:'businessChat.onStatus'});if(myEpoch!==epoch){if(result.subscriptionId)await unsubscribeRealtime({subscriptionId:result.subscriptionId});return undefined;}subscriptionId=result.subscriptionId;const status=subscriptionId?await getRealtimeStatus({subscriptionId}):result;s=shape({...s,liveState:status.state,liveReason:status.reason||''});}catch{s=shape({...s,liveState:'unavailable',liveReason:'runtime_unavailable'});}}
+    let loaded=await loadLatest(s,true);
+    if(!loaded||myEpoch!==epoch)return undefined;
+    // Until this returns the stored state has no room, so events are ignored; one that arrived meanwhile asks for another pass.
+    for(let pass=0;pass<3&&takeEventDuringInit();pass++){const again=await loadLatest(loaded,true);if(!again||myEpoch!==epoch)return undefined;loaded=again;}
+    const opened=takeStatusDuringInit();
+    return shape(keepTyped(opened?{...loaded,liveState:opened.state,liveReason:opened.reason}:loaded));
+   }catch(error){
+    const sessionLost=/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error));
+    const loadFailure=typeof (error as {businessLoadFailure?:unknown})?.businessLoadFailure==='string'?(error as {businessLoadFailure:string}).businessLoadFailure:safeLoadFailure(error);
+    return sessionLost?clearPrivate(s,'guest'):shape(keepTyped({...s,phase:'error',member:!!currentIdentity?.authenticated,error:safeError(error,'init'),loadFailure}));
+   }finally{initFlight=false;}
+  },
+  // Runs on every keystroke, so it must not rebuild the message list the way `shape` does.
+  setDraft:(s,a)=>{draftRevision++;const draft=value(a);const sendEnabled=!!s.member&&!!s.roomId&&!s.busy&&!!draft.trim()&&!s.pendingIntent;return {...s,draft,sendEnabled,sendDisabled:!sendEnabled};},
+  send:async s=>{
+   const text=s.draft.trim();
+   if(!text||sendFlight||!s.roomId||!s.member||s.pendingIntent)return s;
+   sendFlight=true;const pending=newBusinessChatIntent(text,s.roomId,s.principal);
+   const draftAtSend=s.draft;const sendEpoch=epoch;
+   try{
+    await chat.sendMessage(me(),pending.roomId,{id:pending.id,text:pending.text});
+    if(sendEpoch!==epoch)return undefined;
+    const latest=readServiceState();
+    if(latest.roomId!==pending.roomId||latest.principal!==pending.principal)return undefined;
+    draftRevision++;// a refresh that began before this send must not bring the sent text back into the composer
+    s=shape({...latest,draft:draftAfterAcceptedSend(latest.draft,draftAtSend),pendingIntent:null,error:'',notice:'Message sent.',scrollSend:latest.scrollSend+1});
+    try{const loaded=await loadLatest(s,true);return loaded?shape({...loaded,notice:'Message sent.'}):undefined;}catch(error){
+     // A session lost by an older operation says nothing about the member who is signed in now.
+     if(sendEpoch!==epoch)return undefined;
+     if(/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error)))return clearPrivate(s,'guest');
+     return withLiveDraft(s);
+    }
+   }catch(error){
+    if(sendEpoch!==epoch)return undefined;
+    const lost=/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error));
+    if(lost)return clearPrivate(s,'guest');
+    const definitive=businessChatSendRejected(error);
+    const latest=readServiceState();
+    if(latest.roomId!==pending.roomId||latest.principal!==pending.principal)return undefined;
+    return shape({...latest,pendingIntent:definitive?null:pending,error:safeError(error,'send'),notice:definitive?'The message was rejected. Your draft is retained.':'No automatic retry was made. Reopen the conversation to check whether it arrived.'});
+   }finally{sendFlight=false;}
+  },
+  sendSuggestion:async(s,a)=>{
+   if(suggestionFlight||!s.member||!s.roomId||!!s.pendingIntent)return s;
+   const id=param(a,'id');
+   if(!id||s.usedSuggestionIds.includes(id))return s;
+   const rows=[{suggestions:s.quickReplies} as {suggestions?:BusinessSuggestion[]},...s.messages];
+   const options=s.visitorOptions;
+   const intent=newBusinessChatIntent('suggestion',s.roomId,s.principal);
+   const sendEpoch=epoch;
+   suggestionFlight=true;
+   s=shape({...s,usedSuggestionIds:[...s.usedSuggestionIds,id],error:'',notice:''});
+   try{
+    const sent=await dispatchBusinessSuggestion(rows,id,{member:s.member,roomId:s.roomId,principal:s.principal,currentPrincipal:currentIdentity?.userId||currentIdentity?.email||'',scope:s.scope,currentScope:currentIdentity?.scope||''},suggestion=>suggestion.kind==='visitor_option'
+      ? sendBusinessVisitorOption(options,suggestion.label)
+      : chat.sendButton(me(),s.roomId,{id:intent.id,text:suggestion.label,appId:suggestion.appId!,interactionId:suggestion.interactionId!}));
+    if(sendEpoch!==epoch)return undefined;
+    if(!sent)return withLiveDraft(s);
+    const latest=readServiceState();
+    if(latest.roomId!==s.roomId||latest.principal!==s.principal)return undefined;
+    try{const loaded=await loadLatest(withLiveDraft(shape({...s,scrollSend:s.scrollSend+1,error:'',notice:'Suggestion sent.'})),true);return loaded?shape({...loaded,notice:'Suggestion sent.'}):undefined;}
+    catch{return withLiveDraft(shape({...s,scrollSend:s.scrollSend+1,error:'',notice:'Suggestion sent.'}));}
+   }catch(error){
+    if(sendEpoch!==epoch)return undefined;
+    if(/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error)))return clearPrivate(s,'guest');
+    const definitive=businessChatSendRejected(error);
+    return shape({...withLiveDraft(s),usedSuggestionIds:definitive?s.usedSuggestionIds.filter(value=>value!==id):s.usedSuggestionIds,error:safeError(error,'send'),notice:definitive?'The suggestion was rejected.':'Suggestion delivery is unconfirmed; it will not be sent again automatically.'});
+   }finally{suggestionFlight=false;}
+  },
+  onEvent:async(s,a)=>{
+   if(initFlight){eventDuringInit=true;return undefined;}
+   const startEpoch=epoch;
+   const envelope=a as RealtimeEventEnvelope|undefined;
+   const eventType=typeof envelope?.event?.type==='string'?envelope.event.type:'';
+   s=shape({...s,realtimeEventCount:s.realtimeEventCount+1,lastRealtimeEventType:eventType});
+   if(!currentIdentity||!shouldRefreshBusinessHistory(envelope,s.roomId,{member:s.member,principal:s.principal,currentPrincipal:currentIdentity.userId||currentIdentity.email,scope:s.scope,currentScope:currentIdentity.scope}))return s;
+   if(refreshFlight){refreshQueued=true;return withLiveDraft(s);}
+   try{return await loadLatest(s);}catch(error){
+    if(startEpoch!==epoch)return undefined;
+    return /member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error))?clearPrivate(s,'guest'):shape({...withLiveDraft(s),error:safeError(error,'load'),loadFailure:typeof (error as {businessLoadFailure?:unknown})?.businessLoadFailure==='string'?(error as {businessLoadFailure:string}).businessLoadFailure:safeLoadFailure(error)});
+   }
+  },
+  onStatus:async(s,a)=>{
+   const startEpoch=epoch;const mySeq=++statusSeq;
+   const status=a as RealtimeStatus|undefined;
+   const liveState=status?.state||'unavailable';
+   // While init is opening, the stored state has no room yet: remember the status and let init apply it.
+   if(initFlight){statusDuringInit={state:liveState,reason:liveState==='connected'?'':status?.reason||''};return undefined;}
+   let next=shape({...s,liveState,liveReason:liveState==='connected'?'':status?.reason||''});
+   if(liveState!=='connected'||s.liveState==='connected'||!s.member||!s.roomId||!currentIdentity||s.principal!==(currentIdentity.userId||currentIdentity.email)||s.scope!==currentIdentity.scope)return next;
+   try{
+    const loaded=await loadLatest(next);
+    if(!loaded)return undefined;
+    // A newer status applied while the refresh ran wins over the one this handler started with.
+    const live=readServiceState();
+    const newer=statusSeq!==mySeq;
+    return shape({...loaded,liveState:newer?live.liveState:liveState,liveReason:newer?live.liveReason:(liveState==='connected'?'':status?.reason||''),error:''});
+   }
+   catch(error){if(startEpoch!==epoch)return undefined;const lost=/member_sign_in_required|MemberAccessChanged|\b401\b|\b403\b/i.test(String(error));return lost?clearPrivate(next,'guest'):shape({...withLiveDraft(next),error:safeError(error,'load'),loadFailure:typeof (error as {businessLoadFailure?:unknown})?.businessLoadFailure==='string'?(error as {businessLoadFailure:string}).businessLoadFailure:safeLoadFailure(error)});}
+  },
+  dispose:async s=>{epoch++;currentIdentity=null;businessParticipantId='';await endSubscription();return shape({...initial,phase:'guest'});},
+ }
+});
+readServiceState=()=>svc.getState();
+async function loadLatest(s:State,wait=false):Promise<State|undefined>{
+ // A caller that does not need the data asks the running refresh to go again and keeps its own change
+ // (a status, an event count): returning nothing would drop it.
+ if(!wait&&refreshFlight){refreshQueued=true;return withLiveDraft(s);}
+ let next=await loadHistory(s,wait);
+ // Events that arrived during a refresh ask for another pass, a few at most.
+ for(let pass=0;next&&refreshQueued&&pass<3;pass++){
+  refreshQueued=false;
+  next=await loadHistory(next,true);
+ }
+ if(!next)refreshQueued=false;
+ return next;
+}
+export { svc };

package/templates/community-club/tier5-src/_shared/branded-lite-hosted.ts

@@ -72,6 +72,7 @@ export const HOSTED_SCREEN_VERTICALS: Readonly<Record<string, readonly BrandedLi
   himi_blog: ["blog"],
   himi_bookings: ["bookings"],
   himi_cart: ["store"],
+  himi_business_chat: ["inbox"],
   himi_chat_thread: ["inbox", "members"],
   himi_cms: ["cms"],
   himi_collection: ["store"],