@appsupportkit/support-sdk 0.2.0 → 0.4.0

package/src/types.ts

@@ -1,9 +1,24 @@
 import type { StyleProp, ViewStyle } from 'react-native';
+import type { Language } from './i18n/languages';
 
-export type QueryType = 'feedback' | 'feature_request' | 'bug_report';
+/**
+ * 'support' is the single chat (0.4+). The other three are the typed requests
+ * older builds file; their conversations still show in the chat.
+ */
+export type QueryType = 'feedback' | 'feature_request' | 'bug_report' | 'support';
+/** Shown to the support team, which can filter and message users by it. */
+export type UserPlan = 'free' | 'trial' | 'pro';
 export type QueryStatus = 'open' | 'resolved';
 export type MessageSender = 'user' | 'admin';
 export type ThemeName = 'dark' | 'light';
+/** What the host app asks for. "system" follows the app's light/dark appearance. */
+export type ThemePreference = ThemeName | 'system';
+/**
+ * A brand color: one hex for both modes, or a pair. A single color is
+ * lightened in dark mode (darkened in light) only as far as it takes to
+ * stay visible; a pair is used exactly as given.
+ */
+export type AccentColor = string | { light: string; dark: string };
 export type PushPermissionStatus = 'undetermined' | 'granted' | 'denied';
 
 /**
@@ -17,8 +32,17 @@ export type LauncherVariant = 'solid' | 'soft' | 'minimal';
 export interface SupportUser {
   /** Display name shown to the support team. */
   name: string;
-  /** Whether the user is on a paid plan. */
-  isPaid: boolean;
+  /**
+   * The user's plan: "free", "trial" (in a free trial) or "pro" (paying).
+   * With RevenueCat: "trial" when the active entitlement's periodType is
+   * TRIAL, "pro" when it is active otherwise, else "free".
+   */
+  plan?: UserPlan;
+  /**
+   * @deprecated Pass `plan`, which can also say "trial". Still accepted:
+   * true reads as "pro", false as "free". One of the two is required.
+   */
+  isPaid?: boolean;
   /** RevenueCat app user id — identifies the user's threads. */
   revenuecatId: string;
   /** Host app version, e.g. "2.4.1". */
@@ -38,14 +62,19 @@ export interface SupportButtonProps {
    * Edge Functions.
    */
   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.
+   * Visual theme. Default "system": follows the host app's light/dark
+   * appearance (the device setting, unless the app pins one) and switches
+   * live when it changes. Pass "light" or "dark" to pin it.
+   */
+  theme?: ThemePreference;
+  /**
+   * Brand color replacing the default accent across the launcher, buttons,
+   * and the user's own message bubbles: a hex like "#FF5A1F", or
+   * `{ light, dark }` for a color per mode. The pressed shade, the 12% wash,
+   * a text-safe variant, and a legible foreground are derived from it.
    */
-  accentColor?: string;
+  accentColor?: AccentColor;
   /** Launcher style. Default "solid" — the floating action button. */
   variant?: LauncherVariant;
   /** Launcher diameter in px (height when `label` is set). Default 52. */
@@ -71,23 +100,56 @@ export interface SupportButtonProps {
    * installed — it is an optional peer dependency.
    */
   expoProjectId?: string;
+  /**
+   * Pre-selects a language in the picker the first time a user opens support.
+   * Pass it when the host app already knows what the user reads — an in-app
+   * language setting beats the device locale, which is what the SDK falls
+   * back to. It is a default, not an override: the user still chooses, and a
+   * choice they have already made always wins.
+   */
+  defaultLanguage?: Language;
 }
 
 export interface ThreadMessage {
   id: string;
   sender: MessageSender;
+  /**
+   * Already in the user's language: their own messages as they wrote them,
+   * support replies translated. The server does the choosing — see the
+   * get-threads function.
+   */
   body: string;
   created_at: string;
-  admin_name: string | null;
+  /**
+   * A support reply whose translation hasn't landed yet. `body` currently
+   * holds the English original; it will change under the reader shortly, so
+   * the UI says so rather than letting it flicker.
+   */
+  translation_pending: boolean;
+  /**
+   * 'review_request': a support reply that carries a store review button.
+   * Absent from servers older than 0.4, where every message is text.
+   */
+  kind?: 'text' | 'review_request';
 }
 
+/** Where a review request's button points; set per app in the dashboard. */
+export interface StoreListing {
+  app_store_id: string | null;
+  play_store_package: string | null;
+}
+
+/**
+ * Note the absence of any admin identity: end users see one support team,
+ * not the people staffing it, so the names never leave the server. The
+ * dashboard still shows who wrote and who resolved what.
+ */
 export interface Thread {
   id: string;
   type: QueryType;
   status: QueryStatus;
   created_at: string;
   resolved_at: string | null;
-  resolved_by_name: string | null;
   app_version: string;
   unread_count: number;
   last_message: {
@@ -101,13 +163,23 @@ export interface Thread {
 export interface ThreadsResponse {
   threads: Thread[];
   total_unread: number;
+  /** Null when this user has never picked one — the SDK then asks. */
+  language: string | null;
+  /** The app's store listings, for review requests. */
+  store?: StoreListing;
 }
 
+/**
+ * English labels, kept for host apps that render their own entry points.
+ * Inside the sheet the labels come from the string table instead, so they
+ * follow the user's language.
+ */
 export const QUERY_TYPE_LABEL: Record<QueryType, string> = {
   feedback: 'Feedback',
   feature_request: 'Feature request',
   bug_report: 'Bug report',
+  support: 'Support',
 };
 
-export const USER_MESSAGE_MIN = 10;
-export const USER_MESSAGE_MAX = 300;
+export const USER_MESSAGE_MIN = 1;
+export const USER_MESSAGE_MAX = 1000;

package/src/useSupportThreads.ts

@@ -21,7 +21,8 @@ import {
   SupportApiError,
   type ApiConfig,
 } from './api';
-import type { Thread } from './types';
+import type { StringKey } from './i18n';
+import type { StoreListing, Thread } from './types';
 import {
   latestAdminMessageAt,
   pruneWatermarks,
@@ -30,11 +31,11 @@ import {
   type ReadWatermarks,
 } from './unread';
 
-// Poll cadence by context: fast where latency is felt (staring at a thread
+// Poll cadence by context: fast where latency is felt (looking at the chat,
 // 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 CHAT_POLL_MS = 5_000;
 const SHEET_POLL_MS = 15_000;
 export const IDLE_POLL_MS = 60_000;
 const MIN_POLL_MS = 3_000;
@@ -50,10 +51,14 @@ const MARK_READ_BACKOFF_MS = 1_500;
  * 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".
+ *
+ * Returns a key rather than a message: the hook has no business knowing what
+ * language the sheet is in, and resolving it here would make every callback
+ * depend on the translator.
  */
-function loadErrorMessage(e: unknown): string {
+function loadErrorKey(e: unknown): StringKey {
   if (e instanceof SupportApiError) {
-    if (e.offline) return "You're offline — check your connection";
+    if (e.offline) return 'error.offline';
     if (e.status === 401 || e.status === 403) {
       if (__DEV__) {
         console.error(
@@ -62,11 +67,11 @@ function loadErrorMessage(e: unknown): string {
             '`appName` matches that app exactly.',
         );
       }
-      return 'Support is unavailable right now';
+      return 'error.unavailable';
     }
-    if (e.status === 429) return 'Too many requests — try again in a bit';
+    if (e.status === 429) return 'error.loadRateLimited';
   }
-  return "Couldn't load your conversations";
+  return 'error.loadFailed';
 }
 
 interface ReadAttempt {
@@ -87,7 +92,18 @@ export interface SupportThreadsState {
   /** User-pulled refresh with content already on screen. */
   refreshing: boolean;
   /** Set only when there is nothing cached; background failures stay quiet. */
-  error: string | null;
+  errorKey: StringKey | null;
+  /** The language this user picked, or null if they never have. */
+  serverLanguage: string | null;
+  /**
+   * False until the first successful load. `serverLanguage === null` only
+   * means "never picked" once this is true — before that it means "don't
+   * know yet", and showing the picker on a guess would nag a user who
+   * answered on another device.
+   */
+  languageLoaded: boolean;
+  /** The app's store listings, for review request buttons. */
+  store: StoreListing | null;
   /** User-initiated refresh (pull-to-refresh, retry button). */
   refresh: () => void;
   /** Awaited by send/submit handlers so the list reflects the write. */
@@ -99,7 +115,7 @@ export function useSupportThreads({
   revenuecatId,
   enabled,
   sheetOpen,
-  activeThreadId,
+  chatVisible,
   idlePollMs,
 }: {
   config: ApiConfig;
@@ -107,14 +123,21 @@ export function useSupportThreads({
   /** False when props failed validation — no requests are made. */
   enabled: boolean;
   sheetOpen: boolean;
-  activeThreadId: string | null;
+  /**
+   * The chat is on screen. It shows every conversation at once, so all of
+   * them are read while it is — including replies that arrive meanwhile.
+   */
+  chatVisible: boolean;
   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 [errorKey, setErrorKey] = useState<StringKey | null>(null);
+  const [serverLanguage, setServerLanguage] = useState<string | null>(null);
+  const [languageLoaded, setLanguageLoaded] = useState(false);
+  const [store, setStore] = useState<StoreListing | null>(null);
 
   const mounted = useRef(true);
   /** Last server payload, before local read reconciliation. */
@@ -124,11 +147,11 @@ export function useSupportThreads({
   const requestSeq = useRef(0);
   const appliedSeq = useRef(0);
   const readEpoch = useRef(0);
-  const activeThreadIdRef = useRef<string | null>(activeThreadId);
+  const chatVisibleRef = useRef(chatVisible);
 
   useEffect(() => {
-    activeThreadIdRef.current = activeThreadId;
-  }, [activeThreadId]);
+    chatVisibleRef.current = chatVisible;
+  }, [chatVisible]);
 
   useEffect(() => {
     mounted.current = true;
@@ -235,6 +258,11 @@ export function useSupportThreads({
     [publish, sendRead],
   );
 
+  /** Marks every conversation read — the chat shows them all at once. */
+  const markAllRead = useCallback(() => {
+    for (const thread of rawThreads.current ?? []) markThreadRead(thread.id);
+  }, [markThreadRead]);
+
   const fetchThreads = useCallback(
     async (mode: 'initial' | 'user' | 'background') => {
       if (!enabled) return;
@@ -256,18 +284,20 @@ export function useSupportThreads({
 
         rawThreads.current = data.threads;
         watermarks.current = pruneWatermarks(watermarks.current, data.threads);
-        setError(null);
+        setErrorKey(null);
+        setServerLanguage(data.language);
+        setLanguageLoaded(true);
+        setStore(data.store ?? null);
         publish();
 
-        // Replies that arrived while the user is sitting in the thread are
+        // Replies that arrived while the user is looking at the chat are
         // read on arrival — otherwise the badge climbed while they read.
-        const active = activeThreadIdRef.current;
-        if (active !== null) markThreadRead(active);
+        if (chatVisibleRef.current) markAllRead();
         flushReads();
       } catch (e) {
         if (!mounted.current) return;
         // A failed background poll must not blow away cached threads.
-        if (rawThreads.current === null) setError(loadErrorMessage(e));
+        if (rawThreads.current === null) setErrorKey(loadErrorKey(e));
       } finally {
         if (mounted.current) {
           if (spinner) setRefreshing(false);
@@ -275,7 +305,7 @@ export function useSupportThreads({
         }
       }
     },
-    [config, enabled, revenuecatId, publish, markThreadRead, flushReads],
+    [config, enabled, revenuecatId, publish, markAllRead, flushReads],
   );
 
   /** Badge-only refresh — the cheap endpoint, used while idle. */
@@ -307,10 +337,10 @@ export function useSupportThreads({
     if (sheetOpen) void fetchThreads('background');
   }, [sheetOpen, fetchThreads]);
 
-  // Opening a thread marks it read immediately, before the next poll.
+  // Opening the chat marks everything read immediately, before the next poll.
   useEffect(() => {
-    if (activeThreadId !== null) markThreadRead(activeThreadId);
-  }, [activeThreadId, markThreadRead]);
+    if (chatVisible) markAllRead();
+  }, [chatVisible, markAllRead]);
 
   // Cadence follows what the user is looking at; the app returning to the
   // foreground always ticks.
@@ -319,8 +349,8 @@ export function useSupportThreads({
     const idle = !sheetOpen;
     const intervalMs = idle
       ? idlePollMs
-      : activeThreadId !== null
-        ? THREAD_POLL_MS
+      : chatVisible
+        ? CHAT_POLL_MS
         : SHEET_POLL_MS;
 
     const tick = () => {
@@ -348,7 +378,7 @@ export function useSupportThreads({
   }, [
     enabled,
     sheetOpen,
-    activeThreadId,
+    chatVisible,
     idlePollMs,
     fetchThreads,
     fetchCount,
@@ -365,7 +395,10 @@ export function useSupportThreads({
     totalUnread,
     loading,
     refreshing,
-    error,
+    errorKey,
+    serverLanguage,
+    languageLoaded,
+    store,
     refresh,
     reload,
   };

package/src/utils.ts

@@ -1,32 +1,20 @@
-/** "2h ago" relative time — mirrors the web dashboard's formatting. */
-export function relativeTime(iso: string): string {
-  const then = new Date(iso).getTime();
-  const seconds = Math.max(0, Math.floor((Date.now() - then) / 1000));
-  if (seconds < 60) return 'just now';
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}d ago`;
-  const weeks = Math.floor(days / 7);
-  if (weeks < 5) return `${weeks}w ago`;
-  const months = Math.floor(days / 30);
-  if (months < 12) return `${months}mo ago`;
-  return `${Math.floor(days / 365)}y ago`;
-}
+import type { Translator } from './i18n';
+import type { SupportUser, UserPlan } from './types';
+
+// Dates and times follow the language the user picked, not the device's:
+// a sheet that says "Traduction…" above "2 days ago" reads as broken.
 
-export function formatDate(iso: string): string {
-  return new Date(iso).toLocaleDateString(undefined, {
+export function formatDate(iso: string, strings: Translator): string {
+  return new Date(iso).toLocaleDateString(strings.locale, {
     year: 'numeric',
     month: 'short',
     day: 'numeric',
   });
 }
 
-/** "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, {
+/** "14:32" in the user's locale — shown under a group of messages. */
+export function formatTime(iso: string, strings: Translator): string {
+  return new Date(iso).toLocaleTimeString(strings.locale, {
     hour: 'numeric',
     minute: '2-digit',
   });
@@ -43,13 +31,13 @@ export function isSameDay(a: string, b: string): boolean {
 }
 
 /** Date separator label: Today / Yesterday / "Mon, 5 Jan". */
-export function dayLabel(iso: string): string {
+export function dayLabel(iso: string, strings: Translator): string {
   const now = new Date();
-  if (isSameDay(iso, now.toISOString())) return 'Today';
+  if (isSameDay(iso, now.toISOString())) return strings.t('time.today');
   const yesterday = new Date(now.getTime() - 86_400_000);
-  if (isSameDay(iso, yesterday.toISOString())) return 'Yesterday';
+  if (isSameDay(iso, yesterday.toISOString())) return strings.t('time.yesterday');
   const date = new Date(iso);
-  return date.toLocaleDateString(undefined, {
+  return date.toLocaleDateString(strings.locale, {
     weekday: 'short',
     month: 'short',
     day: 'numeric',
@@ -57,6 +45,13 @@ export function dayLabel(iso: string): string {
   });
 }
 
+const PLANS: UserPlan[] = ['free', 'trial', 'pro'];
+
+/** The user's plan, reading the deprecated `isPaid` when `plan` is absent. */
+export function userPlan(user: SupportUser): UserPlan {
+  return user.plan ?? (user.isPaid ? 'pro' : 'free');
+}
+
 /** Dev-mode prop validation with actionable messages. */
 export function validateProps(props: {
   appName?: unknown;
@@ -78,13 +73,16 @@ export function validateProps(props: {
   }
   const user = props.user as Record<string, unknown> | undefined;
   if (!user || typeof user !== 'object') {
-    return 'SupportButton: `user` is required — { name, isPaid, revenuecatId, appVersion }.';
+    return 'SupportButton: `user` is required — { name, plan, revenuecatId, appVersion }.';
   }
   if (typeof user.name !== 'string' || user.name.length === 0) {
     return 'SupportButton: `user.name` is required (string).';
   }
-  if (typeof user.isPaid !== 'boolean') {
-    return 'SupportButton: `user.isPaid` is required (boolean).';
+  if (user.plan !== undefined && !PLANS.includes(user.plan as UserPlan)) {
+    return 'SupportButton: `user.plan` must be "free", "trial" or "pro".';
+  }
+  if (user.plan === undefined && typeof user.isPaid !== 'boolean') {
+    return 'SupportButton: `user.plan` is required — "free", "trial" or "pro".';
   }
   if (typeof user.revenuecatId !== 'string' || user.revenuecatId.length === 0) {
     return 'SupportButton: `user.revenuecatId` is required (string) — the RevenueCat app user id.';

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * Sent as `x-sdk-version` on every request. The backend uses its presence to
+ * tell 0.4+ (one support chat) from older builds still in the App Store, so
+ * keep it in step with package.json.
+ */
+export const SDK_VERSION = '0.4.0';