@repzo/widget-react-native 1.0.9 → 1.2.0

package/src/state/widget-store.ts

@@ -25,10 +25,13 @@ import type {
   ConversationRatingResult,
   Message,
   OutgoingAttachment,
+  PostInteractionKind,
+  PostReply,
   RepzoWidgetErrorCode,
   WidgetAttachment,
   WidgetConfig,
   WidgetCustomAttributes,
+  WidgetPost,
   WidgetSpaceType,
   WidgetState,
   WidgetUser,
@@ -36,7 +39,8 @@ import type {
 } from '../types';
 import { setOpenUrlHandler } from '../ui/utils/safe-url';
 
-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(): 'ios' | 'android' | 'web' {
@@ -65,6 +69,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']);
 
@@ -95,6 +105,8 @@ const INITIAL_STATE: WidgetState = {
   outboundMessage: null,
   visitorProfile: {},
   inAppNotification: null,
+  post: null,
+  postExpanded: false,
 };
 
 /** Everything in state that belongs to the signed-in visitor. */
@@ -115,6 +127,8 @@ const USER_SCOPED_STATE: Partial<WidgetState> = {
   outboundMessage: null,
   visitorProfile: {},
   inAppNotification: null,
+  post: null,
+  postExpanded: false,
 };
 
 export class WidgetStore {
@@ -122,9 +136,13 @@ export class WidgetStore {
 
   readonly events = new EventEmitter();
 
-  readonly push = new PushManager(this.client, (conversationId) => {
-    void this.openConversation(conversationId);
-  });
+  readonly push = new PushManager(
+    this.client,
+    (conversationId) => {
+      void this.openConversation(conversationId);
+    },
+    (campaignId) => this.openPostFromPush(campaignId)
+  );
 
   private state: WidgetState = INITIAL_STATE;
 
@@ -144,6 +162,35 @@ export class WidgetStore {
   /** `boot({ inAppNotifications })` — the card over the app for new replies. */
   private inAppNotificationsEnabled = true;
 
+  /** `boot({ posts })` — Send posts over the app. */
+  private postsEnabled = true;
+
+  /** Posts whose view was reported this session (the server also dedupes per day). */
+  private viewedPostIds = new Set<string>();
+
+  /** Bumped per post load, so an older answer never lands over a newer one. */
+  private postRequest = 0;
+
+  /** Bumped when a live answer or a saved reply joins the post, so a load sent before it is retried, not shown. */
+  private postRevision = 0;
+
+  /** Conversations whose unread replies include one the post can't show (attachments only): opening the post leaves them unread. */
+  private postUnshownReplies = new Set<string>();
+
+  private postRecheckTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /** A post push tapped before the session was ready: open it once it is. */
+  private pendingPostId: string | null = null;
+
+  /** Posts closed with × whose report failed (offline, say): kept down, and the close re-sent when they come back. */
+  private unsentDismissIds = new Set<string>();
+
+  /** Bumped when the visitor's posts are reset (logout, wipe, posts off): older post callbacks stand down. */
+  private postSession = 0;
+
+  /** A reaction's "thanks" moment: when it ends, the post goes. */
+  private postThanksTimer: ReturnType<typeof setTimeout> | null = null;
+
   /** The launch card (see showUnreadOnLaunch) is offered once per visitor session. */
   private launchCardOffered = false;
 
@@ -313,6 +360,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 &&
@@ -517,6 +575,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();
 
@@ -723,6 +783,8 @@ export class WidgetStore {
     this.resetThreadTracking();
     this.appStateSubscription?.remove();
     this.appStateSubscription = null;
+    this.resetPost();
+    this.pendingPostId = null;
     this.setState({ ...INITIAL_STATE });
 
     await this.enqueueIdentity(() => this.wipeSession());
@@ -755,9 +817,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 });
 
     const token = await this.client.getToken();
@@ -875,6 +939,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();
   }
 
   /**
@@ -920,6 +986,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;
@@ -1071,12 +1139,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
@@ -1086,9 +1148,15 @@ export class WidgetStore {
     const ids: string[] = Array.isArray(data?.messageIds) ? data.messageIds : [];
     const status: string | undefined = 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 as string);
+    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) => ({
@@ -1098,6 +1166,12 @@ export class WidgetStore {
     }));
   }
 
+  /**
+   * 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.
+   */
   private handleDeletedMessage(data: any) {
     const messageId: string | undefined = data?.messageId;
     if (!messageId) return;
@@ -1147,6 +1221,18 @@ export class WidgetStore {
       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;
@@ -1179,7 +1265,7 @@ export class WidgetStore {
         };
       }
 
-      if (!isTeamReply || !conversationId) return { conversations };
+      if (!isTeamReply || !conversationId || readInPost) return { conversations };
 
       const unreadByConversation = {
         ...current.unreadByConversation,
@@ -1209,7 +1295,14 @@ 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' as const, 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
@@ -1263,7 +1356,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(),
     };
@@ -1391,6 +1484,8 @@ export class WidgetStore {
     this.setState({ isOpen: false, view: 'bubble', agentTyping: false });
     this.clearTypingTimer();
     this.track('widget_closed');
+    // A post left open behind the messenger is back in front of them.
+    this.readPostConversation();
   }
 
   toggle(space?: WidgetSpaceType): void {
@@ -1667,10 +1762,35 @@ 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>`.
+   */
   private hydrateMetadata(metadata: Message['metadata']): Message['metadata'] {
-    if (!metadata || typeof metadata.agentAvatar !== 'string') return metadata ?? null;
-    return { ...metadata, agentAvatar: this.client.resolveUrl(metadata.agentAvatar) };
+    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: unknown) => this.hydrateBlockMedia(block)),
+      };
+    }
+    return next;
+  }
+
+  private hydrateBlockMedia(block: unknown): unknown {
+    const candidate = block as { type?: unknown; product?: { imageUrl?: unknown } } | null;
+    const imageUrl = candidate?.product?.imageUrl;
+    if (candidate?.type !== 'product_service_card' || typeof imageUrl !== 'string') return block;
+    return {
+      ...candidate,
+      product: { ...candidate.product, imageUrl: this.client.resolveUrl(imageUrl) ?? undefined },
+    };
   }
 
   /**
@@ -1933,9 +2053,345 @@ export class WidgetStore {
       .catch(() => {});
   }
 
+  // ─── Send posts ─────────────────────────────────────────────────────────
+
+  /** Ask the server for the post this visitor should see now. */
+  loadPost(): void {
+    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.
+   */
+  private hydratePost(post: WidgetPost): WidgetPost | null {
+    if (!post || typeof post.id !== 'string' || !post.id || typeof post.bodyHtml !== 'string') return null;
+    const text = (value: unknown) => (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): emoji is string => 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' as const) : ('person' as const),
+              text: message.text,
+              senderName: message.from === 'team' ? text(message.senderName) || null : null,
+              at: text(message.at),
+            }))
+        : replies.map((reply) => ({ from: 'person' as const, 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.
+   */
+  private showPost(post: WidgetPost | null, expand = false): void {
+    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: string): void {
+    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: string): void {
+    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.
+   */
+  private readPostConversation(): void {
+    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: string): void {
+    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: string): void {
+    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(() => {});
+  }
+
+  private reportPostOpen(post: WidgetPost): void {
+    // "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: string,
+    kind: Exclude<PostInteractionKind, 'view' | 'open' | 'minimize'>,
+    value?: string
+  ): Promise<PostReply | undefined> {
+    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: { hidden: boolean; reply?: PostReply; conversationId?: string | null };
+    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: PostReply =
+        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;
+  }
+
+  private startPostThanks(campaignId: string, sent: Promise<unknown>, session: number): void {
+    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);
+  }
+
+  private clearPostThanks(): void {
+    if (this.postThanksTimer) clearTimeout(this.postThanksTimer);
+    this.postThanksTimer = null;
+  }
+
+  private resendPostDismiss(campaignId: string, session: number): void {
+    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.
+   */
+  private openPostFromPush(campaignId: string): void {
+    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();
+  }
+
+  private clearPostRecheck(): void {
+    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. */
+  private schedulePostRecheck(recheckInMs: number | null | undefined, session: number): void {
+    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.
+   */
+  private postStale(session: number): boolean {
+    return session !== this.postSession;
+  }
+
+  /** The visitor changed or posts were turned off: drop it and any pending load. */
+  private resetPost(): void {
+    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(): void {
+    this.clearPostRecheck();
+    this.clearPostThanks();
     this.realtime.close();
     this.clearTypingTimer();
     this.resetThreadTracking();
@@ -1967,11 +2423,6 @@ function isLocalMessage(message: Message): boolean {
   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: Message[], server: Message[]): Message[] {
   const seen = new Set(server.filter((message) => message.status === 'read').map((message) => message.id));
@@ -2006,6 +2457,11 @@ function adoptServerDeletions(messages: Message[], server: Message[]): Message[]
   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: Message[], server: Message[]): Message[] {
   const serverCopies = new Map(
     server.filter((message) => message.attachments?.length).map((message) => [message.id, message])