@repzo/widget-react-native 1.0.9 → 1.2.0

package/lib/module/state/widget-store.js

@@ -20,7 +20,9 @@ import { CONFIG_KEY, LEGACY_CONFIG_KEY, SecureStorage, Storage, UNREAD_KEY, USER
 import { setAttachmentOptions } from "../attachments/pickers.js";
 import { DEFAULT_BASE_URL } from "../types.js";
 import { setOpenUrlHandler } from "../ui/utils/safe-url.js";
-const SDK_VERSION = '@repzo/widget-react-native@1.0.5';
+
+/** Sent on every init; must match `package.json` (tests/version.test.js checks). */
+const SDK_VERSION = '@repzo/widget-react-native@1.2.0';
 
 /** The platform this session reports — mobile sessions get the Mobile SDKs overrides. */
 function sessionPlatform() {
@@ -43,6 +45,12 @@ const STREAM_REAUTH_MIN_INTERVAL_MS = 30_000;
 const MARK_READ_DEBOUNCE_MS = 1_000;
 /** Live events held back while a draft's first send is creating its thread. */
 const DRAFT_EVENT_BUFFER_LIMIT = 50;
+/** How long a post stays up after a reaction, thanking them, before it goes. */
+export const POST_THANKS_MS = 1600;
+
+/** Ask a moment after the server's "post stops" time, never waiting longer than this per timer. */
+const POST_RECHECK_SLACK_MS = 1_000;
+const POST_RECHECK_MAX_MS = 6 * 60 * 60 * 1000;
 /** Plain-http `baseUrl` is only accepted for these (plus `*.local` and `__DEV__`). */
 const LOCAL_DEV_HOSTS = new Set(['localhost', '127.0.0.1', '10.0.2.2']);
 const sumUnread = map => Object.values(map).reduce((sum, count) => sum + count, 0);
@@ -69,7 +77,9 @@ const INITIAL_STATE = {
   prefillText: '',
   outboundMessage: null,
   visitorProfile: {},
-  inAppNotification: null
+  inAppNotification: null,
+  post: null,
+  postExpanded: false
 };
 
 /** Everything in state that belongs to the signed-in visitor. */
@@ -89,14 +99,16 @@ const USER_SCOPED_STATE = {
   prefillText: '',
   outboundMessage: null,
   visitorProfile: {},
-  inAppNotification: null
+  inAppNotification: null,
+  post: null,
+  postExpanded: false
 };
 export class WidgetStore {
   client = new WidgetApiClient();
   events = new EventEmitter();
   push = new PushManager(this.client, conversationId => {
     void this.openConversation(conversationId);
-  });
+  }, campaignId => this.openPostFromPush(campaignId));
   state = INITIAL_STATE;
   subscribers = new Set();
   realtime = new WidgetRealtime();
@@ -107,6 +119,34 @@ export class WidgetStore {
   /** `boot({ inAppNotifications })` — the card over the app for new replies. */
   inAppNotificationsEnabled = true;
 
+  /** `boot({ posts })` — Send posts over the app. */
+  postsEnabled = true;
+
+  /** Posts whose view was reported this session (the server also dedupes per day). */
+  viewedPostIds = new Set();
+
+  /** Bumped per post load, so an older answer never lands over a newer one. */
+  postRequest = 0;
+
+  /** Bumped when a live answer or a saved reply joins the post, so a load sent before it is retried, not shown. */
+  postRevision = 0;
+
+  /** Conversations whose unread replies include one the post can't show (attachments only): opening the post leaves them unread. */
+  postUnshownReplies = new Set();
+  postRecheckTimer = null;
+
+  /** A post push tapped before the session was ready: open it once it is. */
+  pendingPostId = null;
+
+  /** Posts closed with × whose report failed (offline, say): kept down, and the close re-sent when they come back. */
+  unsentDismissIds = new Set();
+
+  /** Bumped when the visitor's posts are reset (logout, wipe, posts off): older post callbacks stand down. */
+  postSession = 0;
+
+  /** A reaction's "thanks" moment: when it ends, the post goes. */
+  postThanksTimer = null;
+
   /** The launch card (see showUnreadOnLaunch) is offered once per visitor session. */
   launchCardOffered = false;
   bootPromise = null;
@@ -262,6 +302,17 @@ export class WidgetStore {
     if (options.inAppNotifications !== undefined) {
       this.inAppNotificationsEnabled = options.inAppNotifications !== false;
     }
+    if (options.posts !== undefined) {
+      const wasEnabled = this.postsEnabled;
+      this.postsEnabled = options.posts !== false;
+      if (!this.postsEnabled) {
+        this.resetPost();
+        this.pendingPostId = null;
+      } else if (!wasEnabled) {
+        // A booted session returns early below, so turning posts back on asks here.
+        this.loadPost();
+      }
+    }
     const sameTarget = this.bootConfig?.baseUrl === baseUrl && this.bootConfig?.channelAccountId === options.channelAccountId;
     const userKey = options.user ? identityKey(options.user) : null;
     if (sameTarget && this.bootPromise && (!userKey || userKey === this.bootingUserKey)) {
@@ -461,6 +512,8 @@ export class WidgetStore {
     this.connectRealtime(result.token);
     this.watchAppState();
     this.loadOutboundMessage();
+    // Audiences and closed posts are per person, so every new session asks again.
+    this.loadPost();
     // Re-runs on login switches too — the token moves to the new identity.
     void this.push.start();
     if (this.pendingConversationId) {
@@ -666,6 +719,8 @@ export class WidgetStore {
     this.resetThreadTracking();
     this.appStateSubscription?.remove();
     this.appStateSubscription = null;
+    this.resetPost();
+    this.pendingPostId = null;
     this.setState({
       ...INITIAL_STATE
     });
@@ -698,9 +753,11 @@ export class WidgetStore {
     this.userKeyLoaded = true;
     this.pendingAgentByConversation = {};
     this.seenMessageIds = [];
+    this.earlyStatuses.clear();
     this.visitorTypingActive = false;
     this.lastTypingPingAt = 0;
     this.launchCardOffered = false;
+    this.resetPost();
     this.setState({
       ...USER_SCOPED_STATE
     });
@@ -806,6 +863,8 @@ export class WidgetStore {
     // and the thread on screen so replies sent meanwhile show up.
     await Promise.all([this.refreshConversations(), this.refreshOpenThread()]);
     await this.refreshConfig();
+    // A post may have gone live (or ended) while the app was away.
+    if (!this.isStale(epoch)) this.loadPost();
   }
 
   /**
@@ -853,6 +912,8 @@ export class WidgetStore {
         if (this.streamConnectedOnce || this.streamErrored) {
           void this.refreshConversations();
           void this.refreshOpenThread();
+          // Answers under the post too.
+          this.loadPost();
         }
         this.streamConnectedOnce = true;
         this.streamErrored = false;
@@ -975,12 +1036,6 @@ export class WidgetStore {
     return false;
   }
 
-  /**
-   * A teammate deleted a message: the visitor sees "This message was deleted"
-   * in its place (they can't delete anything themselves), and the list is
-   * refreshed so its preview stops showing the text. The id stays in
-   * `seenMessageIds`, so a replayed `message.new` can't restore the content.
-   */
   /**
    * A teammate opened the conversation: the visitor's messages are now Seen.
    * The ids are also remembered, because the event can arrive before the send
@@ -990,9 +1045,15 @@ export class WidgetStore {
     const ids = Array.isArray(data?.messageIds) ? data.messageIds : [];
     const status = typeof data?.status === 'string' ? data.status : undefined;
     if (!status || ids.length === 0) return;
-    for (const id of ids) this.earlyStatuses.set(id, status);
-    if (this.earlyStatuses.size > SEEN_MESSAGE_LIMIT) {
-      this.earlyStatuses.delete(this.earlyStatuses.keys().next().value);
+    for (const id of ids) {
+      // Re-inserted, so a repeated id counts as newest when trimming.
+      this.earlyStatuses.delete(id);
+      this.earlyStatuses.set(id, status);
+    }
+    // One event can carry many ids: trim back to the cap, oldest first.
+    for (const id of this.earlyStatuses.keys()) {
+      if (this.earlyStatuses.size <= SEEN_MESSAGE_LIMIT) break;
+      this.earlyStatuses.delete(id);
     }
     if (!this.isThreadOnScreen(data?.conversationId)) return;
     this.setState(current => ({
@@ -1002,6 +1063,13 @@ export class WidgetStore {
       } : message)
     }));
   }
+
+  /**
+   * A teammate deleted a message: the visitor sees "This message was deleted"
+   * in its place (they can't delete anything themselves), and the list is
+   * refreshed so its preview stops showing the text. The id stays in
+   * `seenMessageIds`, so a replayed `message.new` can't restore the content.
+   */
   handleDeletedMessage(data) {
     const messageId = data?.messageId;
     if (!messageId) return;
@@ -1044,6 +1112,17 @@ export class WidgetStore {
     // never system rows like "agent joined" (the server counts the same way).
     const isTeamReply = message.messageType === 'message' && message.direction !== 'inbound' && message.senderType !== 'visitor';
     const onScreen = this.isThreadOnScreen(conversationId);
+    // A team answer in the shown post's conversation shows under the post —
+    // and, with the post open in front of them, counts as read there. The
+    // post only shows text: an attachment-only answer stays unread (card,
+    // badge) for the messenger, and so does everything after it until the
+    // conversation is opened there, since reading moves the server cursor past it.
+    const post = this.state.post;
+    const inPost = isTeamReply && !!conversationId && post?.conversationId === conversationId;
+    const answerText = (message.bodyPlain ?? '').trim();
+    if (inPost && !this.state.unreadByConversation[conversationId]) this.postUnshownReplies.delete(conversationId);
+    const readInPost = inPost && !!answerText && this.state.postExpanded && !this.state.isOpen && !this.state.unreadByConversation[conversationId];
+    if (inPost && !answerText) this.postUnshownReplies.add(conversationId);
 
     // Set inside the updater, read after: `setState` runs synchronously.
     let countedAsUnread = false;
@@ -1062,7 +1141,7 @@ export class WidgetStore {
           agentTyping: clearsTyping ? false : current.agentTyping
         };
       }
-      if (!isTeamReply || !conversationId) return {
+      if (!isTeamReply || !conversationId || readInPost) return {
         conversations
       };
       const unreadByConversation = {
@@ -1095,7 +1174,23 @@ export class WidgetStore {
 
     // The visitor is reading it live — move the server cursor too, or the
     // next list/init would badge a reply they already saw.
-    if (onScreen && isTeamReply && conversationId) this.scheduleMarkRead(conversationId);
+    if ((onScreen || readInPost) && isTeamReply && conversationId) this.scheduleMarkRead(conversationId);
+    const current = this.state.post;
+    if (inPost && answerText && current?.id === post?.id) {
+      const answer = {
+        from: 'team',
+        text: answerText,
+        senderName: message.senderName,
+        at: message.createdAt
+      };
+      this.postRevision += 1;
+      this.setState({
+        post: {
+          ...current,
+          thread: [...current.thread, answer]
+        }
+      });
+    }
 
     // Emitted after the state write so a listener reading the unread count sees
     // the new value. Only unread-counting replies fire it, which keeps the event
@@ -1146,7 +1241,7 @@ export class WidgetStore {
       body: null,
       bodyPlain: data.bodyPlain || 'Conversation updated',
       attachments: null,
-      metadata: data.metadata || null,
+      metadata: this.hydrateMetadata(data.metadata || null),
       status: 'delivered',
       createdAt: data.createdAt || new Date().toISOString()
     };
@@ -1264,6 +1359,8 @@ export class WidgetStore {
     });
     this.clearTypingTimer();
     this.track('widget_closed');
+    // A post left open behind the messenger is back in front of them.
+    this.readPostConversation();
   }
   toggle(space) {
     if (this.state.isOpen) this.hide();else this.present(space);
@@ -1556,12 +1653,39 @@ export class WidgetStore {
     })).reverse();
   }
 
-  /** The "joined" line's avatar can be a server-relative media path. */
+  /**
+   * Media URLs inside metadata (the "joined" line's avatar, product photos in
+   * agent blocks) can be server-relative paths, and are remote content: like
+   * every other media URL they resolve against `baseUrl`, and anything that
+   * isn't http(s) is dropped before it reaches an `<Image>`.
+   */
   hydrateMetadata(metadata) {
-    if (!metadata || typeof metadata.agentAvatar !== 'string') return metadata ?? null;
+    if (!metadata) return null;
+    let next = metadata;
+    if (typeof metadata.agentAvatar === 'string') {
+      next = {
+        ...next,
+        agentAvatar: this.client.resolveUrl(metadata.agentAvatar)
+      };
+    }
+    if (Array.isArray(metadata.agentUiBlocks)) {
+      next = {
+        ...next,
+        agentUiBlocks: metadata.agentUiBlocks.map(block => this.hydrateBlockMedia(block))
+      };
+    }
+    return next;
+  }
+  hydrateBlockMedia(block) {
+    const candidate = block;
+    const imageUrl = candidate?.product?.imageUrl;
+    if (candidate?.type !== 'product_service_card' || typeof imageUrl !== 'string') return block;
     return {
-      ...metadata,
-      agentAvatar: this.client.resolveUrl(metadata.agentAvatar)
+      ...candidate,
+      product: {
+        ...candidate.product,
+        imageUrl: this.client.resolveUrl(imageUrl) ?? undefined
+      }
     };
   }
 
@@ -1798,9 +1922,366 @@ export class WidgetStore {
     }).catch(() => {});
   }
 
+  // ─── Send posts ─────────────────────────────────────────────────────────
+
+  /** Ask the server for the post this visitor should see now. */
+  loadPost() {
+    if (!this.postsEnabled || !this.state.booted) return;
+    const session = this.postSession;
+    const request = ++this.postRequest;
+    const revision = this.postRevision;
+    this.client.getPost().then(({
+      post,
+      recheckInMs
+    }) => {
+      if (this.postStale(session) || request !== this.postRequest) return;
+      // An answer or reply joined the post meanwhile, maybe after this was
+      // read: ask again rather than show the post without it.
+      if (revision !== this.postRevision) {
+        this.loadPost();
+        return;
+      }
+      const hydrated = post ? this.hydratePost(post) : null;
+      const pushed = this.pendingPostId;
+      this.pendingPostId = null;
+      this.schedulePostRecheck(recheckInMs, session);
+      if (hydrated && this.unsentDismissIds.has(hydrated.id)) {
+        // Closed already; the server only missed hearing it.
+        this.showPost(null);
+        this.resendPostDismiss(hydrated.id, session);
+        return;
+      }
+      // A full post opens by itself unless they minimized it; a tapped push always opens it.
+      this.showPost(hydrated, !!hydrated && (hydrated.sentAs === 'full' && !hydrated.minimized || hydrated.id === pushed));
+    })
+    // Keep whatever is on screen; the next session or foreground asks again.
+    .catch(() => {});
+  }
+
+  /**
+   * Coerces the server's post into the shape the view relies on: missing
+   * strings become empty, unknown enum values fall back to the plainest
+   * option, and malformed reactions or replies are dropped.
+   */
+  hydratePost(post) {
+    if (!post || typeof post.id !== 'string' || !post.id || typeof post.bodyHtml !== 'string') return null;
+    const text = value => typeof value === 'string' ? value : '';
+    const sender = post.sender && text(post.sender.name) ? post.sender : null;
+    const replies = Array.isArray(post.replies) ? post.replies.filter(reply => typeof reply?.text === 'string' && reply.text.length > 0).map(reply => ({
+      text: reply.text,
+      at: text(reply.at)
+    })) : [];
+    return {
+      id: post.id,
+      bodyHtml: post.bodyHtml,
+      snippet: text(post.snippet),
+      sender: sender ? {
+        name: sender.name,
+        initials: text(sender.initials),
+        // Teammate photos can be server-relative media paths.
+        avatarUrl: this.client.resolveUrl(typeof sender.avatarUrl === 'string' ? sender.avatarUrl : null)
+      } : null,
+      workspaceName: text(post.workspaceName),
+      format: post.format === 'large' ? 'large' : 'small',
+      replyType: post.replyType === 'text' || post.replyType === 'reaction' ? post.replyType : 'none',
+      reactions: Array.isArray(post.reactions) ? post.reactions.filter(emoji => typeof emoji === 'string' && emoji.length > 0) : [],
+      sentAs: post.sentAs === 'badge' || post.sentAs === 'full' ? post.sentAs : 'snippet',
+      reacted: typeof post.reacted === 'string' && post.reacted ? post.reacted : null,
+      // Older Workstation versions don't send it.
+      minimized: post.minimized === true,
+      replies,
+      thread: Array.isArray(post.thread) ? post.thread.filter(message => typeof message?.text === 'string' && message.text.length > 0).map(message => ({
+        from: message.from === 'team' ? 'team' : 'person',
+        text: message.text,
+        senderName: message.from === 'team' ? text(message.senderName) || null : null,
+        at: text(message.at)
+      })) : replies.map(reply => ({
+        from: 'person',
+        text: reply.text,
+        senderName: null,
+        at: reply.at
+      })),
+      conversationId: text(post.conversationId) || null
+    };
+  }
+
+  /**
+   * Puts a post on screen (or takes it down). A different post starts open or
+   * as its card per `expand`; the same one keeps what the visitor left it as,
+   * so a full post put back to its card doesn't pop open on every foreground.
+   */
+  showPost(post, expand = false) {
+    const current = this.state.post;
+    if (current && current.id !== post?.id) this.viewedPostIds.delete(current.id);
+    const samePost = !!post && current?.id === post.id;
+    const expanded = !!post && (samePost ? this.state.postExpanded : expand);
+    this.setState({
+      post,
+      postExpanded: expanded
+    });
+    if (post && expanded && !samePost) this.reportPostOpen(post);
+    this.readPostConversation();
+  }
+
+  /** The post's card or full view is on screen. Reported once each time it's shown. */
+  postDidShow(campaignId) {
+    if (this.state.post?.id !== campaignId || this.viewedPostIds.has(campaignId)) return;
+    this.viewedPostIds.add(campaignId);
+    this.client.sendPostInteraction(campaignId, 'view').catch(() => {});
+  }
+
+  /** The visitor tapped the post's card: open it in full. */
+  expandPost(campaignId) {
+    const post = this.state.post;
+    if (!post || post.id !== campaignId || this.state.postExpanded) return;
+    this.setState({
+      postExpanded: true
+    });
+    this.reportPostOpen(post);
+    this.readPostConversation();
+  }
+
+  /**
+   * The post is open in front of them (and the messenger isn't): the team's
+   * answers under it are read, here and on the server. Not when one of them
+   * is something the post can't show, or the post has fewer answers since
+   * their last reply than are unread (an attachment from before this launch,
+   * say): those wait for the messenger.
+   */
+  readPostConversation() {
+    const {
+      post,
+      postExpanded,
+      isOpen,
+      unreadByConversation
+    } = this.state;
+    const conversationId = post?.conversationId;
+    const unread = conversationId ? unreadByConversation[conversationId] ?? 0 : 0;
+    if (!post || !conversationId || !postExpanded || isOpen || unread === 0) return;
+    if (this.postUnshownReplies.has(conversationId)) return;
+    let shown = 0;
+    for (let index = post.thread.length - 1; index >= 0 && post.thread[index]?.from === 'team'; index -= 1) shown += 1;
+    if (shown < unread) return;
+    this.setState({
+      unreadByConversation: this.clearUnreadFor(conversationId)
+    });
+    this.events.emit(RepzoWidgetEvents.ConversationDidRead, {
+      conversationId
+    });
+    this.scheduleMarkRead(conversationId);
+  }
+
+  /** Back to its pill or card for now, without telling the server (see PostOverlay's onCollapse). */
+  collapsePost(campaignId) {
+    if (this.state.post?.id !== campaignId || !this.state.postExpanded) return;
+    this.setState({
+      postExpanded: false
+    });
+  }
+
+  /**
+   * "Not now" — the ⌄ button, a swipe down, or Android's back: the post goes
+   * back to its badge (or snippet card) and stays there, on later launches
+   * too, instead of opening by itself again. Unlike ×, it can be opened again.
+   */
+  minimizePost(campaignId) {
+    const post = this.state.post;
+    if (!post || post.id !== campaignId || !this.state.postExpanded) return;
+    this.setState({
+      post: {
+        ...post,
+        minimized: true
+      },
+      postExpanded: false
+    });
+    if (!post.minimized) this.client.sendPostInteraction(campaignId, 'minimize').catch(() => {});
+  }
+  reportPostOpen(post) {
+    // "Opened" is opening it from its card; a full post is opened by showing it.
+    if (post.sentAs === 'full') return;
+    this.client.sendPostInteraction(post.id, 'open').catch(() => {});
+  }
+
+  /**
+   * The visitor tapped a link, reacted, replied to or closed the post. Closing
+   * takes it down at once and loads the next one; a reaction shows as picked
+   * right away. A reply resolves with what was saved (shown under the post)
+   * and rejects when it wasn't, so the reply box can keep the text.
+   */
+  async recordPostInteraction(campaignId, kind, value) {
+    const post = this.state.post;
+    if (!post || post.id !== campaignId) return undefined;
+    const session = this.postSession;
+    if (kind === 'dismiss') {
+      // A load already in flight would put the closed post back.
+      this.postRequest += 1;
+      this.showPost(null);
+    }
+    if (kind === 'reaction' && value) this.setState({
+      post: {
+        ...post,
+        reacted: value
+      }
+    });
+    const sent = this.client.sendPostInteraction(campaignId, kind, value);
+    // A reaction answers the post: it thanks them for a moment, then goes
+    // (another tap in the meantime changes their pick and restarts it).
+    if (kind === 'reaction' && value) this.startPostThanks(campaignId, sent, session);
+    let result;
+    try {
+      result = await sent;
+    } catch (error) {
+      if (kind === 'reply') throw error;
+      if (this.postStale(session)) return undefined;
+      // × closes it for good, so it stays down until the server hears it.
+      if (kind === 'dismiss') this.unsentDismissIds.add(campaignId);
+      if (kind === 'reaction') {
+        const current = this.state.post;
+        if (current?.id === campaignId && current.reacted === value) {
+          this.setState({
+            post: {
+              ...current,
+              reacted: post.reacted
+            }
+          });
+          // Not saved: it stays, as it was, so they can try again — unless an
+          // earlier pick was saved, which already answered it: that one leaves.
+          if (post.reacted) this.startPostThanks(campaignId, Promise.resolve(), session);else this.clearPostThanks();
+        }
+      }
+      return undefined;
+    }
+    if (this.postStale(session)) return undefined;
+    if (kind === 'reply') {
+      // Falls back to what was typed when the response has no usable reply.
+      const saved = result?.reply;
+      const reply = typeof saved?.text === 'string' && saved.text ? {
+        text: saved.text,
+        at: typeof saved.at === 'string' ? saved.at : new Date().toISOString()
+      } : {
+        text: value ?? '',
+        at: new Date().toISOString()
+      };
+      const current = this.state.post;
+      if (current?.id === campaignId) {
+        // Their first reply starts the post's conversation: answers there join the thread from now on.
+        const conversationId = typeof result?.conversationId === 'string' && result.conversationId ? result.conversationId : current.conversationId;
+        this.postRevision += 1;
+        this.setState({
+          post: {
+            ...current,
+            replies: [...current.replies, reply],
+            thread: [...current.thread, {
+              from: 'person',
+              text: reply.text,
+              senderName: null,
+              at: reply.at
+            }],
+            conversationId
+          }
+        });
+      }
+      // The reply went to the post's conversation: show it in the Messenger's list.
+      void this.refreshConversations();
+      return reply;
+    }
+    // A reaction's post leaves when its thanks ends (see startPostThanks).
+    if (result?.hidden && kind !== 'reaction') {
+      if (this.state.post?.id === campaignId) this.showPost(null);
+      this.loadPost();
+    }
+    return undefined;
+  }
+  startPostThanks(campaignId, sent, session) {
+    this.clearPostThanks();
+    this.postThanksTimer = setTimeout(() => {
+      this.postThanksTimer = null;
+      if (this.postStale(session) || this.state.post?.id !== campaignId) return;
+      this.postRequest += 1;
+      this.showPost(null);
+      // Ask for the next one once the server has the reaction, so it doesn't send this one back.
+      sent.then(() => {
+        if (!this.postStale(session)) this.loadPost();
+      }, () => {
+        if (!this.postStale(session)) this.loadPost();
+      });
+    }, POST_THANKS_MS);
+  }
+  clearPostThanks() {
+    if (this.postThanksTimer) clearTimeout(this.postThanksTimer);
+    this.postThanksTimer = null;
+  }
+  resendPostDismiss(campaignId, session) {
+    this.client.sendPostInteraction(campaignId, 'dismiss').then(() => {
+      if (this.postStale(session)) return;
+      this.unsentDismissIds.delete(campaignId);
+      this.loadPost();
+    })
+    // Still offline: it stays down and the next load tries again.
+    .catch(() => {});
+  }
+
+  /**
+   * A post push was tapped: show that post, open in full, as soon as the
+   * session is ready. The messenger steps aside for it, the way a reply push
+   * opens its conversation.
+   */
+  openPostFromPush(campaignId) {
+    if (!this.postsEnabled) return;
+    if (this.state.isOpen) this.hide();
+    this.pendingPostId = campaignId;
+    if (this.state.post?.id === campaignId) {
+      this.pendingPostId = null;
+      this.expandPost(campaignId);
+      return;
+    }
+    if (this.state.booted) this.loadPost();
+  }
+  clearPostRecheck() {
+    if (this.postRecheckTimer) clearTimeout(this.postRecheckTimer);
+    this.postRecheckTimer = null;
+  }
+
+  /** The server knows when the shown post stops; ask again then, so it leaves on time. */
+  schedulePostRecheck(recheckInMs, session) {
+    this.clearPostRecheck();
+    if (typeof recheckInMs !== 'number' || !Number.isFinite(recheckInMs)) return;
+    const delay = Math.min(Math.max(recheckInMs, 0) + POST_RECHECK_SLACK_MS, POST_RECHECK_MAX_MS);
+    this.postRecheckTimer = setTimeout(() => {
+      this.postRecheckTimer = null;
+      if (!this.postStale(session)) this.loadPost();
+    }, delay);
+  }
+
+  /**
+   * Post callbacks check this, not the identity epoch: a same-user login or
+   * an anonymous re-login bumps the epoch but keeps the session (and the post),
+   * and would otherwise drop the post's load and strand its timers.
+   */
+  postStale(session) {
+    return session !== this.postSession;
+  }
+
+  /** The visitor changed or posts were turned off: drop it and any pending load. */
+  resetPost() {
+    this.postSession += 1;
+    this.clearPostRecheck();
+    this.clearPostThanks();
+    this.postRequest += 1;
+    this.viewedPostIds.clear();
+    this.unsentDismissIds.clear();
+    this.postUnshownReplies.clear();
+    if (this.state.post || this.state.postExpanded) this.setState({
+      post: null,
+      postExpanded: false
+    });
+  }
+
   // ─── Teardown (tests / hot reload) ──────────────────────────────────────
 
   destroy() {
+    this.clearPostRecheck();
+    this.clearPostThanks();
     this.realtime.close();
     this.clearTypingTimer();
     this.resetThreadTracking();
@@ -1827,11 +2308,6 @@ function isLocalMessage(message) {
   return message.id.startsWith('temp-');
 }
 
-/**
- * A sent visitor message keeps its local previews (a `file://` URI, or no URL
- * at all) until the server copy shows up — the stream echo or a history page.
- * Its attachments, the only ones that can be opened, then replace them.
- */
 /** A "Seen" missed while the stream was down shows up on the next re-read. */
 function adoptServerStatuses(messages, server) {
   const seen = new Set(server.filter(message => message.status === 'read').map(message => message.id));
@@ -1873,6 +2349,12 @@ function adoptServerDeletions(messages, server) {
   });
   return changed ? next : messages;
 }
+
+/**
+ * A sent visitor message keeps its local previews (a `file://` URI, or no URL
+ * at all) until the server copy shows up — the stream echo or a history page.
+ * Its attachments, the only ones that can be opened, then replace them.
+ */
 function adoptServerAttachments(messages, server) {
   const serverCopies = new Map(server.filter(message => message.attachments?.length).map(message => [message.id, message]));
   if (serverCopies.size === 0) return messages;