@appsupportkit/support-sdk 0.1.2 → 0.2.0

package/src/types.ts

@@ -1,9 +1,19 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 export type QueryType = 'feedback' | 'feature_request' | 'bug_report';
 export type QueryStatus = 'open' | 'resolved';
 export type MessageSender = 'user' | 'admin';
 export type ThemeName = 'dark' | 'light';
 export type PushPermissionStatus = 'undetermined' | 'granted' | 'denied';
 
+/**
+ * How the launcher renders:
+ *   solid   — accent fill, elevated. The floating action button.
+ *   soft    — app surface + hairline border. Sits in a header or toolbar.
+ *   minimal — bare mark, no fill or border. Sits in a nav bar.
+ */
+export type LauncherVariant = 'solid' | 'soft' | 'minimal';
+
 export interface SupportUser {
   /** Display name shown to the support team. */
   name: string;
@@ -30,6 +40,20 @@ export interface SupportButtonProps {
   supabaseUrl: string;
   /** Visual theme. Matches the admin dashboard tokens. Default "dark". */
   theme?: ThemeName;
+  /**
+   * Brand color (hex, e.g. "#FF5A1F") replacing the default accent across
+   * the launcher, buttons, and the user's own message bubbles. The pressed
+   * shade, the 12% wash, and a legible foreground are derived from it.
+   */
+  accentColor?: string;
+  /** Launcher style. Default "solid" — the floating action button. */
+  variant?: LauncherVariant;
+  /** Launcher diameter in px (height when `label` is set). Default 52. */
+  size?: number;
+  /** Renders the launcher as a pill with this text beside the mark. */
+  label?: string;
+  /** Style applied to the launcher — position it, add margins, etc. */
+  style?: StyleProp<ViewStyle>;
   /**
    * Idle poll interval (ms) — how often the unread badge is refreshed while
    * the sheet is CLOSED, using a lightweight count-only endpoint. Default

package/src/unread.ts

@@ -0,0 +1,91 @@
+// Unread accounting.
+//
+// The server counts a thread's unread as "admin messages newer than the
+// user's read receipt". That number is authoritative, but it is always a
+// little behind the device: between the moment the user opens a thread and
+// the moment `mark-read` lands, every already-in-flight poll still reports
+// the old count — which is what made the badge flicker back on after being
+// cleared, and what made a thread the user was actively reading accumulate
+// unread replies.
+//
+// So the client keeps its own watermark per thread: the `created_at` of the
+// newest admin message the user has actually seen. Those are *server*
+// timestamps, so nothing here compares against the device clock.
+//
+// Displayed unread is then the stricter of the two counts, which is correct
+// in both directions:
+//
+//   read here, receipt not written yet  → local watermark wins  (0)
+//   read on another device              → server count wins     (0)
+
+import type { Thread } from './types';
+
+/** Watermark map: thread id → `created_at` (ms) of the newest seen reply. */
+export type ReadWatermarks = Map<string, number>;
+
+/** `created_at` (ms) of the newest admin message, or 0 if there are none. */
+export function latestAdminMessageAt(thread: Thread): number {
+  let latest = 0;
+  for (const message of thread.messages) {
+    if (message.sender !== 'admin') continue;
+    const at = Date.parse(message.created_at);
+    if (Number.isFinite(at) && at > latest) latest = at;
+  }
+  return latest;
+}
+
+/** Admin messages in `thread` newer than `watermark`. */
+export function unreadSince(thread: Thread, watermark: number): number {
+  let count = 0;
+  for (const message of thread.messages) {
+    if (message.sender !== 'admin') continue;
+    const at = Date.parse(message.created_at);
+    if (Number.isFinite(at) && at > watermark) count += 1;
+  }
+  return count;
+}
+
+/**
+ * Returns `thread` with `unread_count` narrowed by what this device knows
+ * the user has read. Identity is preserved when nothing changes so lists
+ * stay referentially stable between polls.
+ */
+export function reconcileThread(
+  thread: Thread,
+  watermarks: ReadWatermarks,
+): Thread {
+  const watermark = watermarks.get(thread.id);
+  if (watermark === undefined || thread.unread_count === 0) return thread;
+  const unread = Math.min(thread.unread_count, unreadSince(thread, watermark));
+  return unread === thread.unread_count ? thread : { ...thread, unread_count: unread };
+}
+
+export function reconcileThreads(
+  threads: Thread[],
+  watermarks: ReadWatermarks,
+): Thread[] {
+  return threads.map((thread) => reconcileThread(thread, watermarks));
+}
+
+export function sumUnread(threads: Thread[]): number {
+  return threads.reduce((total, thread) => total + thread.unread_count, 0);
+}
+
+/**
+ * Drops watermarks the server has caught up on (its own count is already 0)
+ * and ones for threads that no longer exist, so the map can't grow without
+ * bound over a long session.
+ */
+export function pruneWatermarks(
+  watermarks: ReadWatermarks,
+  serverThreads: Thread[],
+): ReadWatermarks {
+  const keep: ReadWatermarks = new Map();
+  for (const thread of serverThreads) {
+    const watermark = watermarks.get(thread.id);
+    if (watermark !== undefined && thread.unread_count > 0) {
+      keep.set(thread.id, watermark);
+    }
+  }
+  return keep;
+}

package/src/useSupportThreads.ts

@@ -0,0 +1,372 @@
+// Threads + unread state for the SDK: fetching, poll cadence, and read
+// tracking. Kept out of SupportButton so the rules below live in one place.
+//
+// Three invariants make the badge trustworthy:
+//
+//   1. Responses are applied in issue order (`appliedSeq`), so a slow poll
+//      can never overwrite a newer one.
+//   2. The badge-only endpoint returns a bare number that cannot be
+//      reconciled against local reads, so its answer is dropped when a read
+//      happened while it was in flight (`readEpoch`), and it isn't used at
+//      all while any `mark-read` is still unconfirmed — the full endpoint is
+//      polled instead, since that payload *can* be reconciled.
+//   3. `mark-read` failures are retried instead of swallowed, and the local
+//      watermark holds the UI correct in the meantime.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AppState } from 'react-native';
+import {
+  getThreads,
+  getUnreadCount,
+  markRead,
+  SupportApiError,
+  type ApiConfig,
+} from './api';
+import type { Thread } from './types';
+import {
+  latestAdminMessageAt,
+  pruneWatermarks,
+  reconcileThreads,
+  sumUnread,
+  type ReadWatermarks,
+} from './unread';
+
+// Poll cadence by context: fast where latency is felt (staring at a thread
+// waiting for a reply), slow when the sheet is closed — and the idle tick
+// uses the count-only endpoint, so it costs ~18 bytes instead of the full
+// thread list.
+const THREAD_POLL_MS = 5_000;
+const SHEET_POLL_MS = 15_000;
+export const IDLE_POLL_MS = 60_000;
+const MIN_POLL_MS = 3_000;
+
+// A failed mark-read used to be dropped on the floor, which resurrected the
+// badge on the next poll. Retry a few times with backoff; anything still
+// unconfirmed after that is picked up by the next poll tick or foreground.
+const MARK_READ_MAX_ATTEMPTS = 4;
+const MARK_READ_BACKOFF_MS = 1_500;
+
+/**
+ * Load failures the user can act on say so; the rest stay neutral. A 401 is
+ * an integration mistake — the end user retrying forever won't fix a key
+ * that doesn't match the app — so the real cause is logged for whoever is
+ * running the build instead of hidden behind "couldn't load".
+ */
+function loadErrorMessage(e: unknown): string {
+  if (e instanceof SupportApiError) {
+    if (e.offline) return "You're offline — check your connection";
+    if (e.status === 401 || e.status === 403) {
+      if (__DEV__) {
+        console.error(
+          'SupportButton: the support API rejected this app (401). Check that ' +
+            '`apiKey` is the key shown when the app was registered and that ' +
+            '`appName` matches that app exactly.',
+        );
+      }
+      return 'Support is unavailable right now';
+    }
+    if (e.status === 429) return 'Too many requests — try again in a bit';
+  }
+  return "Couldn't load your conversations";
+}
+
+interface ReadAttempt {
+  /** Newest reply timestamp this thread's receipt still has to cover. */
+  target: number;
+  /** Timestamp covered by the request currently in flight, if any. */
+  inFlight: number | null;
+  attempts: number;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+export interface SupportThreadsState {
+  /** Server threads with unread counts narrowed by local reads. */
+  threads: Thread[] | null;
+  totalUnread: number;
+  /** First load only — there is nothing cached to show yet. */
+  loading: boolean;
+  /** User-pulled refresh with content already on screen. */
+  refreshing: boolean;
+  /** Set only when there is nothing cached; background failures stay quiet. */
+  error: string | null;
+  /** User-initiated refresh (pull-to-refresh, retry button). */
+  refresh: () => void;
+  /** Awaited by send/submit handlers so the list reflects the write. */
+  reload: () => Promise<void>;
+}
+
+export function useSupportThreads({
+  config,
+  revenuecatId,
+  enabled,
+  sheetOpen,
+  activeThreadId,
+  idlePollMs,
+}: {
+  config: ApiConfig;
+  revenuecatId: string;
+  /** False when props failed validation — no requests are made. */
+  enabled: boolean;
+  sheetOpen: boolean;
+  activeThreadId: string | null;
+  idlePollMs: number;
+}): SupportThreadsState {
+  const [threads, setThreads] = useState<Thread[] | null>(null);
+  const [totalUnread, setTotalUnread] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [refreshing, setRefreshing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const mounted = useRef(true);
+  /** Last server payload, before local read reconciliation. */
+  const rawThreads = useRef<Thread[] | null>(null);
+  const watermarks = useRef<ReadWatermarks>(new Map());
+  const reads = useRef(new Map<string, ReadAttempt>());
+  const requestSeq = useRef(0);
+  const appliedSeq = useRef(0);
+  const readEpoch = useRef(0);
+  const activeThreadIdRef = useRef<string | null>(activeThreadId);
+
+  useEffect(() => {
+    activeThreadIdRef.current = activeThreadId;
+  }, [activeThreadId]);
+
+  useEffect(() => {
+    mounted.current = true;
+    const timers = reads.current;
+    return () => {
+      mounted.current = false;
+      for (const attempt of timers.values()) {
+        if (attempt.timer !== null) clearTimeout(attempt.timer);
+      }
+      timers.clear();
+    };
+  }, []);
+
+  const publish = useCallback(() => {
+    const raw = rawThreads.current;
+    if (raw === null) return;
+    const reconciled = reconcileThreads(raw, watermarks.current);
+    setThreads(reconciled);
+    setTotalUnread(sumUnread(reconciled));
+  }, []);
+
+  /** POSTs the receipt, retrying transient failures with backoff. */
+  const sendRead = useCallback(
+    (threadId: string) => {
+      const attempt = reads.current.get(threadId);
+      if (!attempt || attempt.inFlight !== null) return;
+      const covers = attempt.target;
+      attempt.inFlight = covers;
+      attempt.timer = null;
+
+      markRead(config, { queryId: threadId, revenuecatId })
+        .then(() => {
+          if (!mounted.current) return;
+          const current = reads.current.get(threadId);
+          if (!current) return;
+          current.inFlight = null;
+          // A reply that landed while this request was in flight isn't
+          // covered by the receipt it just wrote — send one more.
+          if (current.target > covers) {
+            current.attempts = 0;
+            sendRead(threadId);
+            return;
+          }
+          reads.current.delete(threadId);
+          // The receipt now exists server-side, so any response still in
+          // flight predates it and must not be trusted for unread counts.
+          readEpoch.current += 1;
+        })
+        .catch(() => {
+          if (!mounted.current) return;
+          const current = reads.current.get(threadId);
+          if (!current) return;
+          current.inFlight = null;
+          current.attempts += 1;
+          if (current.attempts >= MARK_READ_MAX_ATTEMPTS) return;
+          current.timer = setTimeout(
+            () => sendRead(threadId),
+            MARK_READ_BACKOFF_MS * 2 ** (current.attempts - 1),
+          );
+        });
+    },
+    [config, revenuecatId],
+  );
+
+  /** Re-drives receipts that gave up earlier (next poll tick / foreground). */
+  const flushReads = useCallback(() => {
+    for (const [threadId, attempt] of reads.current) {
+      if (attempt.inFlight !== null || attempt.timer !== null) continue;
+      attempt.attempts = 0;
+      sendRead(threadId);
+    }
+  }, [sendRead]);
+
+  /**
+   * Records that the user has seen every reply currently in `threadId` and
+   * persists it. Idempotent: re-marking a thread with nothing new is a
+   * no-op, so the 5s in-thread poll doesn't spam the endpoint.
+   */
+  const markThreadRead = useCallback(
+    (threadId: string) => {
+      const thread = rawThreads.current?.find((t) => t.id === threadId);
+      if (!thread) return;
+      const latest = latestAdminMessageAt(thread);
+      if (latest === 0) return;
+      if (latest <= (watermarks.current.get(threadId) ?? 0)) return;
+
+      watermarks.current.set(threadId, latest);
+      // Invalidate the bare counts of any request already in flight.
+      readEpoch.current += 1;
+      publish();
+
+      const attempt = reads.current.get(threadId);
+      if (attempt) attempt.target = latest;
+      else {
+        reads.current.set(threadId, {
+          target: latest,
+          inFlight: null,
+          attempts: 0,
+          timer: null,
+        });
+      }
+      sendRead(threadId);
+    },
+    [publish, sendRead],
+  );
+
+  const fetchThreads = useCallback(
+    async (mode: 'initial' | 'user' | 'background') => {
+      if (!enabled) return;
+      const seq = (requestSeq.current += 1);
+      // With nothing cached there is no list to pull down, so a retry shows
+      // the skeleton rather than a spinner nobody can see.
+      const blank = rawThreads.current === null;
+      const spinner = mode === 'user' && !blank;
+      const skeleton = mode !== 'background' && blank;
+      if (spinner) setRefreshing(true);
+      if (skeleton) setLoading(true);
+
+      try {
+        const data = await getThreads(config, revenuecatId);
+        if (!mounted.current) return;
+        // A slower earlier request must never clobber a newer answer.
+        if (seq <= appliedSeq.current) return;
+        appliedSeq.current = seq;
+
+        rawThreads.current = data.threads;
+        watermarks.current = pruneWatermarks(watermarks.current, data.threads);
+        setError(null);
+        publish();
+
+        // Replies that arrived while the user is sitting in the thread are
+        // read on arrival — otherwise the badge climbed while they read.
+        const active = activeThreadIdRef.current;
+        if (active !== null) markThreadRead(active);
+        flushReads();
+      } catch (e) {
+        if (!mounted.current) return;
+        // A failed background poll must not blow away cached threads.
+        if (rawThreads.current === null) setError(loadErrorMessage(e));
+      } finally {
+        if (mounted.current) {
+          if (spinner) setRefreshing(false);
+          if (skeleton) setLoading(false);
+        }
+      }
+    },
+    [config, enabled, revenuecatId, publish, markThreadRead, flushReads],
+  );
+
+  /** Badge-only refresh — the cheap endpoint, used while idle. */
+  const fetchCount = useCallback(async () => {
+    if (!enabled) return;
+    const seq = (requestSeq.current += 1);
+    const epoch = readEpoch.current;
+    try {
+      const data = await getUnreadCount(config, revenuecatId);
+      if (!mounted.current) return;
+      // This payload is just a number: there is no way to subtract reads
+      // that happened while it was in flight, so discard it instead.
+      if (readEpoch.current !== epoch) return;
+      if (seq <= appliedSeq.current) return;
+      appliedSeq.current = seq;
+      setTotalUnread(data.total_unread);
+    } catch {
+      // Best effort: the next tick or the next sheet open reconciles.
+    }
+  }, [config, enabled, revenuecatId]);
+
+  // Initial load.
+  useEffect(() => {
+    void fetchThreads('initial');
+  }, [fetchThreads]);
+
+  // Opening the sheet always shows fresh data.
+  useEffect(() => {
+    if (sheetOpen) void fetchThreads('background');
+  }, [sheetOpen, fetchThreads]);
+
+  // Opening a thread marks it read immediately, before the next poll.
+  useEffect(() => {
+    if (activeThreadId !== null) markThreadRead(activeThreadId);
+  }, [activeThreadId, markThreadRead]);
+
+  // Cadence follows what the user is looking at; the app returning to the
+  // foreground always ticks.
+  useEffect(() => {
+    if (!enabled) return;
+    const idle = !sheetOpen;
+    const intervalMs = idle
+      ? idlePollMs
+      : activeThreadId !== null
+        ? THREAD_POLL_MS
+        : SHEET_POLL_MS;
+
+    const tick = () => {
+      // While a receipt is unconfirmed the count-only endpoint would report
+      // replies the user has already read, so pay for the full payload.
+      if (idle && reads.current.size === 0) void fetchCount();
+      else void fetchThreads('background');
+    };
+
+    // Clamped so a typo like `pollIntervalMs={30}` can't hammer the API;
+    // 0 (or negative) disables idle polling entirely.
+    const timer =
+      intervalMs > 0
+        ? setInterval(tick, Math.max(intervalMs, MIN_POLL_MS))
+        : null;
+
+    const appStateSub = AppState.addEventListener('change', (state) => {
+      if (state === 'active') tick();
+    });
+
+    return () => {
+      if (timer !== null) clearInterval(timer);
+      appStateSub.remove();
+    };
+  }, [
+    enabled,
+    sheetOpen,
+    activeThreadId,
+    idlePollMs,
+    fetchThreads,
+    fetchCount,
+  ]);
+
+  const refresh = useCallback(() => {
+    void fetchThreads('user');
+  }, [fetchThreads]);
+
+  const reload = useCallback(() => fetchThreads('background'), [fetchThreads]);
+
+  return {
+    threads,
+    totalUnread,
+    loading,
+    refreshing,
+    error,
+    refresh,
+    reload,
+  };
+}

package/src/utils.ts

@@ -24,6 +24,39 @@ export function formatDate(iso: string): string {
   });
 }
 
+/** "14:32" in the device's locale — shown under a group of messages. */
+export function formatTime(iso: string): string {
+  return new Date(iso).toLocaleTimeString(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+
+export function isSameDay(a: string, b: string): boolean {
+  const first = new Date(a);
+  const second = new Date(b);
+  return (
+    first.getFullYear() === second.getFullYear() &&
+    first.getMonth() === second.getMonth() &&
+    first.getDate() === second.getDate()
+  );
+}
+
+/** Date separator label: Today / Yesterday / "Mon, 5 Jan". */
+export function dayLabel(iso: string): string {
+  const now = new Date();
+  if (isSameDay(iso, now.toISOString())) return 'Today';
+  const yesterday = new Date(now.getTime() - 86_400_000);
+  if (isSameDay(iso, yesterday.toISOString())) return 'Yesterday';
+  const date = new Date(iso);
+  return date.toLocaleDateString(undefined, {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: 'numeric' }),
+  });
+}
+
 /** Dev-mode prop validation with actionable messages. */
 export function validateProps(props: {
   appName?: unknown;