@simon-says-build/ssb-overlay 0.6.0 → 0.8.0

package/README.md

@@ -26,4 +26,25 @@ import { captureScreen } from "react-native-view-shot";
 Nothing secret goes in the bundle: the app's own session token is checked by
 SSB against the app's backend (functions/in-app.mjs).
 
+## Help, for everyone who uses the app (0.8.0)
+
+`<SsbHelp>` is the web Help widget's native twin (docs/HELPDESK.md): ANY
+signed-in user of the app asks how it works; SSB answers, and hands it to a
+person on the organization's help desk when it cannot help. It shows only
+where the organization switched its help desk on for the app.
+
+```tsx
+import { SsbHelp, SsbHelpChat, useSsbHelp } from "@simon-says-build/ssb-overlay";
+
+<SsbHelp appId="impulse-native" backend="firebase:impulse-mode"
+  getToken={() => auth.currentUser?.getIdToken() ?? null} sessionKey={user?.uid}
+  route={usePathname()} bubble={showHelpEverywhere}>
+  {/* the app */}
+</SsbHelp>
+
+// Where Help belongs in the app: `useSsbHelp().show` / `.unread`, a screen
+// rendering <SsbHelpChat onClose={router.back} />, and `bubble` for a Help
+// button on every screen (the person's own switch, kept by the app).
+```
+
 `npm test` runs the pure half.

package/index.d.ts

@@ -39,6 +39,12 @@ export function SsbHost(props: {
    * Without it there is no Talk button.
    */
   voice?: { Room: new (opts?: object) => any; startAudio?: () => Promise<void> | void; stopAudio?: () => Promise<void> | void };
+  /**
+   * What this build is, over what the overlay reads itself (0.7.0): sent with the
+   * push token so SSB knows what is installed. `devClient: false` makes "Ready to
+   * see" pushes say the news without a preview link this build can't open.
+   */
+  client?: { app?: string; build?: string; ota?: string; os?: string; devClient?: boolean };
   /** Keep the button off the home indicator / tab bar. Default {top: 60, bottom: 40}. */
   insets?: { top?: number; bottom?: number };
   /**
@@ -49,3 +55,34 @@ export function SsbHost(props: {
   bundle?: string;
   children?: ReactNode;
 }): ReactNode;
+
+/**
+ * Help for the app's OWN users (0.8.0, docs/HELPDESK.md): the web Help
+ * widget's native twin, on the same API and desk. Wrap the app's root; it
+ * renders `children` unchanged unless the help API lets this login ask (any
+ * login the app's backend verifies, where the organization switched its help
+ * desk on). Put Help where it belongs with `useSsbHelp()` and `<SsbHelpChat>`;
+ * `bubble` floats it on every screen.
+ */
+export function SsbHelp(props: {
+  appId?: string;
+  /** Where the app signs in: its Supabase URL, or `firebase:<projectId>`. */
+  backend?: string;
+  api?: string;
+  getToken: () => Promise<string | null | undefined>;
+  sessionKey?: string | null;
+  /** The current route: sent with each question, so the answer knows the screen. */
+  route?: string;
+  /** Float a Help button on every screen (the person's own switch). Default false. */
+  bubble?: boolean;
+  /** Keep the bubble above the tab bar. Default {bottom: 100}. */
+  insets?: { bottom?: number };
+  colors?: { accent?: string; background?: string; text?: string; muted?: string; bubble?: string; team?: string; line?: string };
+  children?: ReactNode;
+}): ReactNode;
+
+/** The Help conversation as a screen of the app's own. `onClose` shows a close button. */
+export function SsbHelpChat(props: { onClose?: () => void; title?: string }): ReactNode;
+
+/** Whether this login may ask Help, whether a reply waits unread, and open it full screen. */
+export function useSsbHelp(): { show: boolean; unread: boolean; open: () => void };

package/index.js

@@ -1,2 +1,4 @@
 export { SsbHost } from './src/SsbHost.js';
+export { SsbHelp, SsbHelpChat, useSsbHelp } from './src/SsbHelp.js';
+export { helpConfig, helpApi } from './src/help.js';
 export { overlayConfig, inAppApi, drawingMark, sendBody, ssbLinkOf } from './src/core.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simon-says-build/ssb-overlay",
-  "version": "0.6.0",
-  "description": "The SSB button inside a native app SimonSays controls: screenshot the screen, mark it, and ask SSB for a change. Renders nothing for anyone SSB does not let in.",
+  "version": "0.8.0",
+  "description": "SSB inside a native app SimonSays controls: the SSB button for the people who change the app (screenshot, mark, ask for a change), and Help for everyone who uses it.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/simon-says-studio/simon-says-build.git",

package/src/SsbHelp.js

@@ -0,0 +1,165 @@
+// <SsbHelp>: Help for an app's OWN users, inside a native app — the web Help
+// widget's twin (web/public/help/widget.js, docs/HELPDESK.md), on the same API
+// and the same desk. Not <SsbHost>: that is SSB for the people who change the
+// app; this is for everyone who uses it (docs/TWO-ELEMENTS.md).
+//
+// Wrap the app's root in <SsbHelp>. It renders its children and nothing else
+// until the help API says this login may ask (`show`). Then:
+//   - `useSsbHelp()` gives the app `{ show, unread, open }`, to put Help where
+//     it belongs in the app (Impulse: the top of the chats list);
+//   - <SsbHelpChat /> is the conversation as a screen of the app's own;
+//   - `bubble` floats a Help button on every screen, opening the same
+//     conversation full screen — the app decides when (a switch the person sets).
+//
+// One conversation, held here, so the bubble and a screen show the same thread.
+// No JSX, so it needs nothing from the app's Babel setup beyond React Native's.
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  ActivityIndicator, KeyboardAvoidingView, Modal, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, View,
+} from 'react-native';
+import { canAskPerson, helpApi, helpConfig, helpPollEvery, helpSendBody, helpUnread, helpWho, ticketLine } from './help.js';
+
+const h = React.createElement;
+const DEFAULT_COLORS = { accent: '#2f5bea', background: '#ffffff', text: '#1f2430', muted: '#6b7280', bubble: '#f3f4f6', team: '#fef3c7', line: '#e5e7eb' };
+const DEFAULT_INSETS = { bottom: 100 };
+const Ctx = createContext({ show: false, unread: false, open: () => {} });
+
+/** `{ show, unread, open }`: whether this login may ask, a reply waiting, and open the conversation full screen. */
+export const useSsbHelp = () => useContext(Ctx);
+
+export function SsbHelp({ appId, backend, api: apiOrigin, getToken, sessionKey, route, bubble = false, insets, colors, children }) {
+  const config = useMemo(() => helpConfig({ appId, backend, api: apiOrigin }), [appId, backend, apiOrigin]);
+  const tokenRef = useRef(getToken);
+  tokenRef.current = getToken;
+  const api = useMemo(() => (config ? helpApi(config, () => tokenRef.current?.()) : null), [config]);
+  const [me, setMe] = useState(null);
+  const [thread, setThread] = useState({ messages: [], thinking: false, ticket: null });
+  const [screens, setScreens] = useState(0);          // <SsbHelpChat>s mounted: the conversation is open
+  const [modal, setModal] = useState(false);
+  const [seen, setSeen] = useState(0);
+  const open = screens > 0 || modal;
+  const C = { ...DEFAULT_COLORS, ...(colors || {}) };
+
+  // May this login ask? Again whenever the login changes.
+  useEffect(() => {
+    let live = true;
+    setMe(null);
+    if (!api) return undefined;
+    api.me().then((r) => { if (live) setMe(r?.show ? r : null); }).catch(() => { if (live) setMe(null); });
+    return () => { live = false; };
+  }, [api, sessionKey]);
+
+  const read = useCallback(async () => {
+    if (!api || !me?.exists || !me.chatId) return;
+    try {
+      const r = await api.chat(me.chatId);
+      setThread({ messages: r.messages || [], thinking: !!r.thinking, ticket: r.ticket || null });
+    } catch { /* the next poll */ }
+  }, [api, me]);
+  useEffect(() => {
+    if (!me) return undefined;
+    read();
+    const t = setInterval(read, helpPollEvery({ open, thinking: thread.thinking }));
+    return () => clearInterval(t);
+  }, [me, open, thread.thinking, read]);
+  useEffect(() => { if (open) setSeen(thread.messages.length); }, [open, thread.messages.length]);
+
+  const send = useCallback(async (text) => {
+    const r = await api.send(helpSendBody({ text, route, me }));
+    setMe((m) => ({ ...m, chatId: r.chatId, exists: true }));
+    setThread((t) => ({ messages: [...t.messages, { id: `local-${Date.now()}`, role: 'user', text: String(text).trim() }], thinking: !r.ticket, ticket: r.ticket || t.ticket }));
+  }, [api, route, me]);
+  const askPerson = useCallback(async () => {
+    const r = await api.escalate(me.chatId);
+    setThread((t) => ({ ...t, ticket: r.ticket || t.ticket }));
+    read();
+  }, [api, me, read]);
+
+  const value = useMemo(() => ({
+    show: !!me, unread: !open && helpUnread(thread.messages, seen), open: () => setModal(true),
+    me, thread, send, askPerson, colors: C, mount: () => { setScreens((n) => n + 1); return () => setScreens((n) => n - 1); },
+  }), [me, open, thread, seen, send, askPerson, C.accent]);   // eslint-disable-line react-hooks/exhaustive-deps
+
+  const bottom = (insets || DEFAULT_INSETS).bottom ?? DEFAULT_INSETS.bottom;
+  return h(Ctx.Provider, { value },
+    children,
+    me && bubble && !open ? h(Pressable, {
+      testID: 'ssb-help-bubble', accessibilityRole: 'button', accessibilityLabel: 'Help',
+      onPress: () => setModal(true), style: [s.bubble, { bottom, backgroundColor: C.accent }],
+    }, h(Text, { style: s.bubbleText }, '?'), value.unread ? h(View, { style: s.dot, testID: 'ssb-help-unread' }) : null) : null,
+    me ? h(Modal, { visible: modal, animationType: 'slide', presentationStyle: 'pageSheet', onRequestClose: () => setModal(false) },
+      h(SsbHelpChat, { onClose: () => setModal(false) })) : null,
+  );
+}
+
+/** The conversation, as a screen of the app's own (or the bubble's sheet). `onClose` shows a close button. */
+export function SsbHelpChat({ onClose, title }) {
+  const ctx = useContext(Ctx);
+  const { me, thread, send, askPerson, colors: C = DEFAULT_COLORS, mount } = ctx;
+  const [draft, setDraft] = useState('');
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState('');
+  const scroll = useRef(null);
+  useEffect(() => (mount ? mount() : undefined), []);   // eslint-disable-line react-hooks/exhaustive-deps
+  if (!me) return h(View, { style: [s.empty, { backgroundColor: C.background }] }, h(ActivityIndicator, null));
+  const msgs = thread.messages || [];
+  const line = ticketLine(thread.ticket || me.ticket);
+  const go = async () => {
+    const text = draft.trim();
+    if (!text || sending) return;
+    setSending(true); setError('');
+    try { await send(text); setDraft(''); } catch (e) { setError(e.message); }
+    setSending(false);
+  };
+  const person = async () => { setError(''); try { await askPerson(); } catch (e) { setError(e.message); } };
+  const first = (me.requester?.label || '').split(/[ @]/)[0];
+  return h(KeyboardAvoidingView, { style: [s.root, { backgroundColor: C.background }], behavior: Platform.OS === 'ios' ? 'padding' : undefined, testID: 'ssb-help-chat' },
+    h(View, { style: [s.header, { borderBottomColor: C.line }] },
+      h(Text, { style: [s.title, { color: C.text }] }, title || `Help${me.app?.name ? ` · ${me.app.name}` : ''}`),
+      onClose ? h(Pressable, { onPress: onClose, accessibilityLabel: 'Close', testID: 'ssb-help-close', hitSlop: 12 }, h(Text, { style: [s.close, { color: C.muted }] }, '✕')) : null),
+    line ? h(Text, { style: [s.ticket, { color: C.accent, borderBottomColor: C.line }], testID: 'ssb-help-ticket' }, line) : null,
+    h(ScrollView, { ref: scroll, style: s.body, contentContainerStyle: s.bodyIn, onContentSizeChange: () => scroll.current?.scrollToEnd?.({ animated: true }) },
+      msgs.length ? null : h(Text, { style: [s.msg, s.left, { backgroundColor: C.bubble, color: C.text }] },
+        `Hi${first ? ` ${first}` : ''} — ask anything about ${me.app?.name || 'the app'}. If I can't help, I'll get you a person.`),
+      ...msgs.map((m) => (m.role === 'event'
+        ? h(Text, { key: m.id, style: [s.event, { color: C.muted }] }, m.text)
+        : h(View, { key: m.id, style: m.role === 'user' ? s.rightWrap : s.leftWrap },
+          h(Text, { style: [s.who, { color: C.muted }] }, helpWho(m)),
+          h(Text, { style: [s.msg, m.role === 'user' ? { backgroundColor: C.accent, color: '#fff' } : { backgroundColor: m.role === 'agent' ? C.team : C.bubble, color: C.text }] }, m.text)))),
+      thread.thinking ? h(Text, { style: [s.event, { color: C.muted, fontStyle: 'italic' }], testID: 'ssb-help-thinking' }, 'Thinking…') : null),
+    h(View, { style: [s.footer, { borderTopColor: C.line }] },
+      error ? h(Text, { style: s.error }, error) : null,
+      h(View, { style: s.row },
+        h(TextInput, { value: draft, onChangeText: setDraft, placeholder: 'How do I…', placeholderTextColor: C.muted, multiline: true, testID: 'ssb-help-input', style: [s.input, { color: C.text, borderColor: C.line }] }),
+        h(Pressable, { onPress: go, disabled: sending || !draft.trim(), testID: 'ssb-help-send', style: [s.send, { backgroundColor: C.accent }, (sending || !draft.trim()) && s.disabled] },
+          h(Text, { style: s.sendText }, sending ? '…' : 'Send'))),
+      canAskPerson(msgs, thread.ticket || me.ticket) ? h(Pressable, { onPress: person, testID: 'ssb-help-person' }, h(Text, { style: [s.person, { color: C.accent }] }, 'Talk to a person')) : null));
+}
+
+const s = StyleSheet.create({
+  root: { flex: 1 },
+  empty: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  header: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 14, borderBottomWidth: 1 },
+  title: { flex: 1, fontSize: 17, fontWeight: '700' },
+  close: { fontSize: 20 },
+  ticket: { paddingHorizontal: 16, paddingVertical: 8, fontSize: 13, borderBottomWidth: 1 },
+  body: { flex: 1 },
+  bodyIn: { padding: 16, gap: 8 },
+  leftWrap: { alignItems: 'flex-start' },
+  rightWrap: { alignItems: 'flex-end' },
+  left: { alignSelf: 'flex-start' },
+  who: { fontSize: 11, marginBottom: 2 },
+  msg: { maxWidth: '85%', paddingVertical: 8, paddingHorizontal: 12, borderRadius: 14, fontSize: 15, lineHeight: 21, overflow: 'hidden' },
+  event: { fontSize: 12, textAlign: 'center', marginVertical: 4 },
+  footer: { borderTopWidth: 1, padding: 10, gap: 6 },
+  row: { flexDirection: 'row', alignItems: 'flex-end', gap: 8 },
+  input: { flex: 1, minHeight: 44, maxHeight: 120, borderWidth: 1, borderRadius: 12, paddingHorizontal: 12, paddingVertical: 10, fontSize: 15 },
+  send: { paddingHorizontal: 16, height: 44, borderRadius: 12, alignItems: 'center', justifyContent: 'center' },
+  sendText: { color: '#fff', fontWeight: '700', fontSize: 15 },
+  disabled: { opacity: 0.5 },
+  person: { fontSize: 13, fontWeight: '600' },
+  error: { color: '#b91c1c', fontSize: 13 },
+  bubble: { position: 'absolute', right: 16, width: 52, height: 52, borderRadius: 26, alignItems: 'center', justifyContent: 'center', shadowColor: '#000', shadowOpacity: 0.25, shadowRadius: 10, shadowOffset: { width: 0, height: 4 }, elevation: 6 },
+  bubbleText: { color: '#fff', fontSize: 24, fontWeight: '800' },
+  dot: { position: 'absolute', top: 2, right: 2, width: 12, height: 12, borderRadius: 6, backgroundColor: '#ef4444', borderWidth: 2, borderColor: '#fff' },
+});

package/src/SsbHost.js

@@ -25,10 +25,10 @@ import {
 } from 'react-native';
 // The app's demo player (a peer): ▶ Demo hands it the demo to play in this
 // build. An older player has no playDemo, and the button is not offered.
-import { playDemo } from '@simon-says-build/demo-player';
+import { playDemo, PLAYER_VERSION } from '@simon-says-build/demo-player';
 import {
   FAB, addPoint, clampFab, demoBanner, fabHome, isDrag, describeHost, draftsOf, fieldTop, inAppApi, namedHosts, newReply, offerOf,
-  STATE_WORD, boxItem, bundleOriginOf, elsewhereLine, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
+  STATE_WORD, boxItem, bundleOriginOf, clientInfo, elsewhereLine, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
 } from './core.js';
 
 const h = React.createElement;
@@ -73,11 +73,26 @@ const scriptURL = () => {
   try { const sc = NativeModules.SourceCode; return sc?.getConstants?.()?.scriptURL ?? sc?.scriptURL ?? ''; } catch { return ''; }
 };
 
-export function SsbHost({ appId, backend, api, getToken, sessionKey, route, capture, storage, pushToken, notifications, voice, insets, bundle, children }) {
+// What this build is, for the push registration (core.js clientInfo). Each
+// read is optional: an app without expo-application or a dev launcher still
+// registers, it just says less.
+function buildInfo(override) {
+  const mods = globalThis.expo?.modules || {};
+  const appMod = mods.ExpoApplication || NativeModules.ExpoApplication || {};
+  const updates = mods.ExpoUpdates || NativeModules.ExpoUpdates || {};
+  const hasLauncher = !!(mods.ExpoDevLauncher || mods.ExpoDevLauncherInternal || NativeModules.EXDevLauncher || NativeModules.EXDevLauncherInternal);
+  return clientInfo({
+    player: PLAYER_VERSION, app: appMod.nativeApplicationVersion, build: appMod.nativeBuildVersion,
+    os: `${Platform.OS} ${Platform.Version ?? ''}`.trim(),
+    runtime: typeof updates.runtimeVersion === 'string' ? updates.runtimeVersion : undefined, hasLauncher, bundleOrigin: bundleOriginOf(scriptURL()), override,
+  });
+}
+
+export function SsbHost({ appId, backend, api, getToken, sessionKey, route, capture, storage, pushToken, notifications, voice, insets, bundle, client, children }) {
   const config = useMemo(() => overlayConfig({ appId, backend, api }), [appId, backend, api]);
   useSsbLinks(notifications);
   if (!config || typeof getToken !== 'function') return children ?? null;
-  return h(Host, { config, getToken, sessionKey, route, capture, storage, pushToken, voice, bundle, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
+  return h(Host, { config, getToken, sessionKey, route, capture, storage, pushToken, voice, bundle, client, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
 }
 
 // A tapped "Ready to see" notification (functions/in-app-notify.mjs) opens
@@ -93,7 +108,7 @@ function useSsbLinks(notifications) {
   }, [notifications]);
 }
 
-function Host({ config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets, bundle, children }) {
+function Host({ config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets, bundle, client, children }) {
   // WHICH BUILD THIS IS (docs/IN-APP-SSB.md "Ready is this build"): Ready is
   // only what this bundle holds. `bundle` overrides (the harness); else the
   // origin the JS came from.
@@ -147,7 +162,7 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
       if (!live) return;
       setGate(g?.show ? g : null);
       // This device, for "it's done, tap to see it" — only for someone SSB let in.
-      if (g?.show && pushToken) Promise.resolve(pushToken()).then((t) => (t ? ssb.pushToken(t, Platform.OS) : null)).catch(() => {});
+      if (g?.show && pushToken) Promise.resolve(pushToken()).then((t) => (t ? ssb.pushToken(t, Platform.OS, buildInfo(client)) : null)).catch(() => {});
     }).catch(() => { if (live) setGate(null); });
     return () => { live = false; };
   }, [ssb, sessionKey]);

package/src/core.js

@@ -3,6 +3,9 @@
 // (functions/annotate.mjs), so the shapes below are the extension's.
 
 export const DEFAULT_API = 'https://simonsays.build';
+// What this overlay is, said when it registers for pushes (clientInfo below).
+// Kept equal to package.json by test/core.test.mjs.
+export const OVERLAY_VERSION = '0.8.0';
 export const HOST = 5;
 export const TEXT = 6;
 const PIN_SLOP = 12;           // a drag shorter than this is a tap: a pin, not a box
@@ -41,7 +44,8 @@ export function inAppApi(config, getToken, fetchImpl = globalThis.fetch) {
     send: (body) => post('/annotations', body),
     chat: (id) => call(`/chats/${encodeURIComponent(id)}`),
     decide: (chatId, proposalId, action, body) => post(`/chats/${encodeURIComponent(chatId)}/proposals/${encodeURIComponent(proposalId)}/${action}`, body),
-    pushToken: (token, platform) => post('/push-token', { token, platform }),
+    // `client`: what this build is (clientInfo), so SSB knows what is installed.
+    pushToken: (token, platform, client) => post('/push-token', { token, platform, ...(client ? { client } : {}) }),
     voice: (body) => post('/voice', body),
     // `bundle`: where this app's JS came from (a preview's tunnel), so SSB
     // scopes Ready to this build; undefined = the whole list, as before.
@@ -325,3 +329,16 @@ export function elsewhereLine(readyElsewhere = []) {
   if (!n) return '';
   return `${n === 1 ? '1 more change is' : `${n} more changes are`} ready in another build — open its preview to see ${n === 1 ? 'it' : 'them'}.`;
 }
+
+// WHAT IS INSTALLED (0.7.0, docs/IN-APP-SSB.md "What is installed"): said with
+// the push token, so SSB knows which builds can open a "Ready to see" preview.
+// `devClient`: a dev launcher is in the binary → true; none, and the JS came
+// from a file (a store or release build) → false; otherwise unknown (absent),
+// and SSB sends the link as before. The host's `client` prop outranks all of it.
+export function clientInfo({ player, app, build, os, runtime, hasLauncher, bundleOrigin, override } = {}) {
+  const devClient = hasLauncher ? true : bundleOrigin === '' ? false : undefined;
+  // `runtime`: expo-updates' runtimeVersion, which under the fingerprint policy
+  // IS the native fingerprint a preview is gated on (docs/DEV-CLIENTS.md).
+  const out = { overlay: OVERLAY_VERSION, player, app, build, os, runtime, devClient, ...(override || {}) };
+  return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+}

package/src/help.js

@@ -0,0 +1,76 @@
+// HELP for an app's own users, the pure half (no React Native here, so
+// node --test runs it). The web Help widget's native twin
+// (web/public/help/widget.js, docs/HELPDESK.md): the same API, the same
+// conversation, the same desk. The server is functions/help-widget.mjs: ANY
+// login the app's backend verifies is let in (this is a customer asking for
+// help, not someone changing the app), only where the app's organization
+// switched its help desk on. A native app sends no Origin, so no CORS applies.
+
+import { DEFAULT_API } from './core.js';
+
+/** The Help settings, or null when they are not set (Help renders nothing). */
+export function helpConfig({ appId, backend, api } = {}) {
+  if (!appId || !backend) return null;
+  return { appId: String(appId), backend: String(backend).replace(/\/+$/, ''), api: String(api || DEFAULT_API).replace(/\/+$/, '') };
+}
+
+/** The help API (/api/help/:appId/*). Every call carries the app's CURRENT session token. */
+export function helpApi(config, getToken, fetchImpl = globalThis.fetch) {
+  const base = `${config.api}/api/help/${encodeURIComponent(config.appId)}`;
+  const call = async (path, init = {}) => {
+    const token = await getToken();
+    if (!token) { const e = new Error('signed out'); e.status = 401; throw e; }
+    const res = await fetchImpl(`${base}${path}`, {
+      ...init,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}`, 'x-ssb-backend': config.backend, ...(init.headers || {}) },
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) { const e = new Error(json.error || `Help answered ${res.status}`); e.status = res.status; throw e; }
+    return json;
+  };
+  const post = (path, body) => call(path, { method: 'POST', body: JSON.stringify(body || {}) });
+  return {
+    me: () => call('/me'),
+    send: (body) => post('/messages', body),
+    chat: (id) => call(`/chats/${encodeURIComponent(id)}`),
+    escalate: (chatId) => post('/escalate', { chatId }),
+  };
+}
+
+/** What a message to Help carries: the words, and where in the app they were. */
+export function helpSendBody({ text, route, me }) {
+  return {
+    text: String(text || '').trim().slice(0, 6000),
+    ...(route ? { url: `app:${String(route).slice(0, 400)}` } : {}),
+    ...(me?.exists && me.chatId ? { chatId: me.chatId } : {}),
+  };
+}
+
+/** How often to read the thread: often while SSB thinks, less while open, rarely closed. */
+export function helpPollEvery({ open, thinking }) {
+  if (open) return thinking ? 2500 : 6000;
+  return 30000;
+}
+
+/** Who says a message, as the panel labels it. */
+export function helpWho(m) {
+  if (m.role === 'user') return 'You';
+  if (m.role === 'agent') return `${m.byLabel || 'Support'} · team`;
+  return 'Assistant';
+}
+
+/** The line under the header while a person has the conversation, or ''. */
+export function ticketLine(ticket) {
+  if (!ticket) return '';
+  if (ticket.status === 'solved') return 'Solved — ask anything new.';
+  return `A person${ticket.orgName ? ` from ${ticket.orgName}` : ''} has this${ticket.assignee ? ` · ${ticket.assignee}` : ''}`;
+}
+
+/** "Talk to a person" is offered once there is a conversation and nobody has it. */
+export const canAskPerson = (messages, ticket) => (messages || []).length > 0 && (!ticket || ticket.status === 'solved');
+
+/** A reply landed while the panel was closed (the bubble's dot). */
+export function helpUnread(messages, seen) {
+  const list = messages || [];
+  return list.length > seen && list[list.length - 1]?.role !== 'user';
+}