@appsupportkit/support-sdk 0.3.0 → 0.4.0

package/src/i18n/strings/zh.ts

@@ -42,6 +42,9 @@ export const zh: StringTable = {
   'thread.resolvedAt': '已解决 · {date}',
   'thread.readOnly': '此对话已解决，仅供查看',
   'thread.placeholder': '写下回复…',
+  'chat.placeholder': '输入消息…',
+  'review.appStore': '在 App Store 评分',
+  'review.playStore': '在 Google Play 评分',
   'thread.sendA11y': '发送回复',
   'thread.sendingA11y': '发送中',
   'thread.translating': '翻译中…',

package/src/index.tsx

@@ -3,9 +3,11 @@ export {
   supportDarkTheme,
   supportLightTheme,
   resolveTheme,
+  type SupportColors,
   type SupportTheme,
 } from './theme';
 export { SupportApiError } from './api';
+export { SDK_VERSION } from './version';
 export { isPushAvailable } from './push';
 export {
   DEFAULT_LANGUAGE,
@@ -16,6 +18,7 @@ export {
   type Language,
 } from './i18n/languages';
 export type {
+  AccentColor,
   LauncherVariant,
   MessageSender,
   PushPermissionStatus,
@@ -27,6 +30,8 @@ export type {
   ThreadMessage,
   ThreadsResponse,
   ThemeName,
+  ThemePreference,
+  UserPlan,
 } from './types';
 export {
   QUERY_TYPE_LABEL,

package/src/push.ts

@@ -12,6 +12,17 @@
 
 import type { PushPermissionStatus } from './types';
 
+/** The slice of a NotificationResponse that tap handling reads. */
+interface NotificationResponse {
+  actionIdentifier: string;
+  notification: {
+    request: {
+      identifier: string;
+      content: { data?: Record<string, unknown> | null };
+    };
+  };
+}
+
 /** The slice of expo-notifications this SDK uses. */
 interface ExpoNotificationsModule {
   getPermissionsAsync(): Promise<{ status: string; canAskAgain: boolean }>;
@@ -19,6 +30,11 @@ interface ExpoNotificationsModule {
   getExpoPushTokenAsync(options?: {
     projectId?: string;
   }): Promise<{ data: string }>;
+  addNotificationResponseReceivedListener(
+    listener: (response: NotificationResponse) => void,
+  ): { remove(): void };
+  getLastNotificationResponseAsync(): Promise<NotificationResponse | null>;
+  DEFAULT_ACTION_IDENTIFIER?: string;
 }
 
 function loadNotifications(): ExpoNotificationsModule | null {
@@ -51,13 +67,16 @@ function normalizeStatus(status: string): PushPermissionStatus {
 
 /**
  * Ensures notification permission has been requested, and returns the
- * outcome plus an Expo push token when one is obtainable.
+ * outcome plus an Expo push token when one is obtainable. With
+ * `prompt: false` it only reads the current state — for refreshing the token
+ * at launch without ever showing the OS prompt outside the support sheet.
  *
  * Never throws: any failure resolves to an 'undetermined' registration so
  * callers can report it and move on.
  */
 export async function ensurePushPermission(
   expoProjectId?: string,
+  { prompt = true }: { prompt?: boolean } = {},
 ): Promise<PushRegistration> {
   if (!notifications) {
     return { status: 'undetermined', asked: false, token: null };
@@ -70,7 +89,7 @@ export async function ensurePushPermission(
 
     // Only prompt when the OS will actually show something. Re-prompting a
     // user who already decided is impossible on iOS and annoying on Android.
-    if (status === 'undetermined' && current.canAskAgain) {
+    if (prompt && status === 'undetermined' && current.canAskAgain) {
       const requested = await notifications.requestPermissionsAsync();
       status = normalizeStatus(requested.status);
       asked = true;
@@ -95,3 +114,82 @@ export async function ensurePushPermission(
     return { status: 'undetermined', asked: false, token: null };
   }
 }
+
+// ---------- opening the thread from a tapped notification ----------
+//
+// send-push tags every support reply with `{ type: 'support_reply',
+// query_id }`. Tapping one should land the user in that thread, not wherever
+// the host app happens to open.
+//
+// The observer starts when this module loads rather than when a launcher
+// mounts, for two reasons: a cold start's tap is only reported once, early,
+// and a host app may mount the launcher later (behind auth, on a settings
+// screen). A tap seen before any launcher is listening is held for
+// PENDING_TAP_TTL_MS and then dropped — opening the sheet minutes after the
+// tap, the first time the user wanders onto that screen, would be a surprise.
+
+const PENDING_TAP_TTL_MS = 60_000;
+
+type SupportTapListener = (threadId: string) => void;
+
+const tapListeners: SupportTapListener[] = [];
+let pendingTap: { threadId: string; at: number } | null = null;
+// Both the listener and getLastNotificationResponseAsync can report the same
+// cold-start tap, and the latter keeps reporting it for the life of the
+// process. Each tap is handled once.
+const handledTaps = new Set<string>();
+
+function supportReplyThreadId(response: NotificationResponse): string | null {
+  const defaultAction = notifications?.DEFAULT_ACTION_IDENTIFIER;
+  if (defaultAction && response.actionIdentifier !== defaultAction) return null;
+  const data = response.notification?.request?.content?.data;
+  if (data?.type !== 'support_reply') return null;
+  return typeof data.query_id === 'string' ? data.query_id : null;
+}
+
+function handleResponse(response: NotificationResponse | null) {
+  if (!response) return;
+  const threadId = supportReplyThreadId(response);
+  const tapId = response.notification?.request?.identifier;
+  if (threadId === null || !tapId || handledTaps.has(tapId)) return;
+  handledTaps.add(tapId);
+
+  // One sheet, not one per mounted launcher: the newest launcher takes it.
+  const listener = tapListeners[tapListeners.length - 1];
+  if (listener) listener(threadId);
+  else pendingTap = { threadId, at: Date.now() };
+}
+
+if (notifications) {
+  try {
+    notifications.addNotificationResponseReceivedListener(handleResponse);
+    notifications
+      .getLastNotificationResponseAsync()
+      .then(handleResponse)
+      .catch(() => {});
+  } catch {
+    // Same contract as the rest of this file: push never breaks support.
+  }
+}
+
+/**
+ * Calls `listener` with the thread id whenever the user taps a support-reply
+ * notification — including, once, a tap from the last minute that arrived
+ * before anything was listening. Returns an unsubscribe function.
+ */
+export function onSupportNotificationTap(
+  listener: SupportTapListener,
+): () => void {
+  tapListeners.push(listener);
+
+  const pending = pendingTap;
+  pendingTap = null;
+  if (pending && Date.now() - pending.at < PENDING_TAP_TTL_MS) {
+    listener(pending.threadId);
+  }
+
+  return () => {
+    const index = tapListeners.lastIndexOf(listener);
+    if (index !== -1) tapListeners.splice(index, 1);
+  };
+}

package/src/review.ts

@@ -0,0 +1,54 @@
+// Review requests: a support reply with a "Rate on the App Store / Google
+// Play" button. The button opens the store's write-a-review page — the store
+// app where there is one, its website otherwise. It is a link, not a prompt:
+// Apple's guidelines reserve in-app rating prompts for SKStoreReviewController,
+// and linking to the review page is what they document for everything else.
+
+import { Linking, Platform } from 'react-native';
+import type { StoreListing } from './types';
+
+interface StoreLinks {
+  /** Opens the store app. */
+  app: string;
+  /** The same page on the web, if the store app won't open. */
+  web: string;
+}
+
+/** Links for this device's store, or null when the team hasn't set one up. */
+export function storeLinks(store: StoreListing | null | undefined): StoreLinks | null {
+  if (Platform.OS === 'ios' && store?.app_store_id) {
+    const id = encodeURIComponent(store.app_store_id);
+    return {
+      app: `itms-apps://apps.apple.com/app/id${id}?action=write-review`,
+      web: `https://apps.apple.com/app/id${id}?action=write-review`,
+    };
+  }
+  if (Platform.OS === 'android' && store?.play_store_package) {
+    const pkg = encodeURIComponent(store.play_store_package);
+    return {
+      app: `market://details?id=${pkg}&showAllReviews=true`,
+      web: `https://play.google.com/store/apps/details?id=${pkg}&showAllReviews=true`,
+    };
+  }
+  return null;
+}
+
+/** Opens the review page; resolves false if neither link would open. */
+export async function openStoreReview(links: StoreLinks): Promise<boolean> {
+  try {
+    await Linking.openURL(links.app);
+    return true;
+  } catch {
+    try {
+      await Linking.openURL(links.web);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** The platform the backend should know this user by, if it's a store one. */
+export function storePlatform(): 'ios' | 'android' | undefined {
+  return Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : undefined;
+}

package/src/theme.ts

@@ -1,7 +1,9 @@
 // The SDK consumes the same design tokens as the admin dashboard, so both
 // surfaces look like one product. On top of those it adds the few values
-// that only exist on mobile: sheet/bubble radii and the elevation used by
-// the launcher and the sheet (the web side gets those from CSS).
+// that only exist on mobile: sheet/bubble radii, the elevation used by the
+// launcher and the sheet (the web side gets those from CSS), and a re-cut of
+// the surfaces and text ramp for a sheet held at arm's length (see
+// SHEET_OVERRIDES).
 import {
   darkColors,
   lightColors,
@@ -11,7 +13,7 @@ import {
   type ThemeColors,
 } from '@appsupportkit/design-tokens';
 import type { ViewStyle } from 'react-native';
-import type { ThemeName } from './types';
+import type { AccentColor, ThemeName } from './types';
 
 /** Rounder than the dashboard: touch targets read better with more radius. */
 export const supportRadii = {
@@ -27,6 +29,17 @@ export const supportRadii = {
   pill: 999,
 } as const;
 
+export interface SupportColors extends ThemeColors {
+  /** The sheet's own background — the layer every screen is drawn on. */
+  sheet: string;
+  /**
+   * The accent where it is small text — status labels, the "New" divider.
+   * The fill color can sit at 3:1; text needs 4.5:1 on the sheet and on the
+   * cards over it, so this is the accent nudged as far as that takes.
+   */
+  accentText: string;
+}
+
 export interface SupportShadows {
   /** Floating launcher button. */
   launcher: ViewStyle;
@@ -52,7 +65,7 @@ export interface LauncherPalette {
 
 export interface SupportTheme {
   name: ThemeName;
-  colors: ThemeColors;
+  colors: SupportColors;
   spacing: typeof spacing;
   radii: typeof supportRadii;
   motion: typeof motion;
@@ -63,9 +76,15 @@ export interface SupportTheme {
 // Color helpers come first: the themes below are built at module load, so
 // anything they reach for has to already be initialized. (A `const` used
 // before its definition survives tsc but lands as `undefined` on Hermes.)
+type Rgb = [number, number, number];
+
 const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
+const WHITE: Rgb = [255, 255, 255];
+/** Foreground for light accents — the dashboard's near-black, not pure black. */
+const INK = '#111113';
+const INK_RGB: Rgb = [17, 17, 19];
 
-function parseHex(color: string): [number, number, number] | null {
+function parseHex(color: string): Rgb | null {
   const match = HEX.exec(color.trim());
   const digits = match?.[1];
   if (digits === undefined) return null;
@@ -83,11 +102,94 @@ function parseHex(color: string): [number, number, number] | null {
   ];
 }
 
-function mix([r, g, b]: [number, number, number], target: number, amount: number) {
+function toHex(rgb: Rgb): string {
+  return `#${rgb.map((c) => c.toString(16).padStart(2, '0')).join('').toUpperCase()}`;
+}
+
+function mixRgb([r, g, b]: Rgb, target: number, amount: number): Rgb {
   const channel = (c: number) => Math.round(c + (target - c) * amount);
-  return `rgb(${channel(r)}, ${channel(g)}, ${channel(b)})`;
+  return [channel(r), channel(g), channel(b)];
+}
+
+function mix(rgb: Rgb, target: number, amount: number): string {
+  return toHex(mixRgb(rgb, target, amount));
+}
+
+/** WCAG relative luminance. */
+function luminance(rgb: Rgb): number {
+  const [r, g, b] = rgb.map((c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  }) as Rgb;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio, 1–21. */
+function contrast(a: Rgb, b: Rgb): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [
+    number,
+    number,
+  ];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Nudges `color` toward white (dark theme) or black (light theme) in 5%
+ * steps until it reaches `ratio` against every background. The smallest
+ * step that works wins, so a brand color stays recognizably itself.
+ */
+function legible(
+  color: string,
+  backgrounds: string[],
+  ratio: number,
+  name: ThemeName,
+): string {
+  const rgb = parseHex(color);
+  if (rgb === null) return color;
+  const against = backgrounds
+    .map(parseHex)
+    .filter((c): c is Rgb => c !== null);
+  const target = name === 'dark' ? 255 : 0;
+  for (let step = 0; step <= 20; step += 1) {
+    const candidate = mixRgb(rgb, target, step * 0.05);
+    if (against.every((bg) => contrast(candidate, bg) >= ratio)) {
+      return toHex(candidate);
+    }
+  }
+  return name === 'dark' ? '#FFFFFF' : '#000000';
 }
 
+/**
+ * Where the SDK departs from the dashboard tokens.
+ *
+ * Dark: the sheet floats over the host app, so it takes an elevated gray the
+ * way iOS sheets do, and the cards and bubbles on it step lighter again. On
+ * the dashboard's near-black base, cards sat 1.05:1 from the background and
+ * the layering disappeared.
+ *
+ * Both: the text ramp is re-cut so every step clears WCAG AA (4.5:1) on the
+ * sheet and on the cards over it. Tertiary carries timestamps and labels at
+ * 11–12px and was 3.1:1 (dark) and 2.5:1 (light); secondary moves too, so
+ * the two stay a visible step apart.
+ */
+const SHEET_OVERRIDES: Record<ThemeName, Partial<SupportColors>> = {
+  dark: {
+    sheet: '#161618',
+    surface: '#1F1F23',
+    surfaceHover: '#26262B',
+    surfaceActive: '#2D2D33',
+    border: '#2E2E35',
+    borderStrong: '#3C3C44',
+    textSecondary: '#A3A3AB', // 6.5:1 on surface
+    textTertiary: '#87878F', // 4.6:1 on surface, 5.1:1 on sheet
+  },
+  light: {
+    sheet: lightColors.bg,
+    textSecondary: '#5A5A62', // 6.5:1 on sheet
+    textTertiary: '#717179', // 4.6:1 on sheet, 4.8:1 on surface
+  },
+};
+
 function shadowsFor(name: ThemeName, accent: string): SupportShadows {
   const dark = name === 'dark';
   return {
@@ -129,7 +231,21 @@ function launcherFor(name: ThemeName, accent: string): LauncherPalette {
   };
 }
 
-function buildTheme(name: ThemeName, colors: ThemeColors): SupportTheme {
+function buildTheme(name: ThemeName, tokens: ThemeColors): SupportTheme {
+  const base = {
+    ...tokens,
+    ...SHEET_OVERRIDES[name],
+  } as SupportColors;
+  // Status tones double as 12px labels, so they get the text bar too.
+  const onSheet = [base.sheet, base.surface];
+  const colors: SupportColors = {
+    ...base,
+    statusOpen: legible(base.statusOpen, onSheet, 4.5, name),
+    statusProgress: legible(base.statusProgress, onSheet, 4.5, name),
+    statusResolved: legible(base.statusResolved, onSheet, 4.5, name),
+    statusDanger: legible(base.statusDanger, onSheet, 4.5, name),
+    accentText: legible(base.accent, onSheet, 4.5, name),
+  };
   return {
     name,
     colors,
@@ -146,41 +262,79 @@ export const supportLightTheme: SupportTheme = buildTheme('light', lightColors);
 
 /**
  * Derives the accent family from a single brand color: a pressed shade, the
- * 12% wash used behind chips and own-message bubbles, and a foreground that
- * stays legible on top (dark text on light brands, white on dark ones).
+ * 12% wash used behind chips, a text-safe variant, and whichever of white or
+ * ink reads better on top of it.
+ *
+ * `adapt` is for a color that has to serve both themes: it is lifted just
+ * far enough to read as a fill (3:1, the WCAG bar for UI components) on this
+ * theme's sheet — a navy brand would otherwise vanish in dark mode. A color
+ * given for this mode specifically is used as is.
  */
-function withAccent(theme: SupportTheme, accent: string): SupportTheme {
-  const rgb = parseHex(accent);
-  if (!rgb) return theme;
+function withAccent(
+  theme: SupportTheme,
+  accent: string,
+  adapt: boolean,
+): SupportTheme {
+  if (parseHex(accent) === null) return theme;
+  const { name } = theme;
+  const fill = adapt
+    ? legible(accent, [theme.colors.sheet], 3, name)
+    : toHex(parseHex(accent) as Rgb);
+  const rgb = parseHex(fill) as Rgb;
   const [r, g, b] = rgb;
-  // Relative luminance, sRGB coefficients — good enough to pick a foreground.
-  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
-  const colors: ThemeColors = {
+  const accentText = legible(
+    fill,
+    [theme.colors.sheet, theme.colors.surface],
+    4.5,
+    name,
+  );
+  const colors: SupportColors = {
     ...theme.colors,
-    accent,
-    accentHover: mix(rgb, theme.name === 'dark' ? 255 : 0, 0.12),
+    accent: fill,
+    accentHover: mix(rgb, name === 'dark' ? 255 : 0, 0.12),
     accentMuted: `rgba(${r}, ${g}, ${b}, 0.12)`,
-    accentForeground: luminance > 0.62 ? '#111113' : '#FFFFFF',
-    statusOpen: accent,
+    accentForeground:
+      contrast(rgb, WHITE) >= contrast(rgb, INK_RGB) ? '#FFFFFF' : INK,
+    accentText,
+    statusOpen: accentText,
     statusOpenBg: `rgba(${r}, ${g}, ${b}, 0.10)`,
-    focusRing: accent,
+    focusRing: fill,
   };
   return {
     ...theme,
     colors,
-    shadows: shadowsFor(theme.name, accent),
-    launcher: launcherFor(theme.name, accent),
+    shadows: shadowsFor(name, fill),
+    launcher: launcherFor(name, fill),
   };
 }
 
 /**
- * @param name  "light" | "dark" (default dark).
- * @param accentColor Optional brand color (hex) replacing the default accent.
+ * The theme for one resolved mode. `accent` is the color for this mode
+ * (already picked from a light/dark pair), and `adapt` says whether it was a
+ * single color that has to be made to work here.
+ */
+export function themeFor(
+  name: ThemeName,
+  accent: string | undefined,
+  adapt: boolean,
+): SupportTheme {
+  const base = name === 'light' ? supportLightTheme : supportDarkTheme;
+  return accent ? withAccent(base, accent, adapt) : base;
+}
+
+/**
+ * @param name  "light" | "dark" (default dark). SupportButton resolves its
+ *   "system" default before calling this.
+ * @param accentColor Optional brand color: one hex for both modes (adjusted
+ *   per mode where needed), or a `{ light, dark }` pair used as given.
  */
 export function resolveTheme(
   name: ThemeName | undefined,
-  accentColor?: string,
+  accentColor?: AccentColor,
 ): SupportTheme {
-  const base = name === 'light' ? supportLightTheme : supportDarkTheme;
-  return accentColor ? withAccent(base, accentColor) : base;
+  const mode: ThemeName = name === 'light' ? 'light' : 'dark';
+  if (typeof accentColor === 'object' && accentColor !== null) {
+    return themeFor(mode, accentColor[mode], false);
+  }
+  return themeFor(mode, accentColor, true);
 }

package/src/types.ts

@@ -1,10 +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';
 
 /**
@@ -18,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". */
@@ -39,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. */
@@ -98,6 +126,17 @@ export interface ThreadMessage {
    * 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;
 }
 
 /**
@@ -126,6 +165,8 @@ export interface ThreadsResponse {
   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;
 }
 
 /**
@@ -137,7 +178,8 @@ 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;