@appsupportkit/support-sdk 0.2.0 → 0.4.0

package/src/i18n/strings/zh.ts

@@ -0,0 +1,78 @@
+import type { StringTable } from './en';
+
+export const zh: StringTable = {
+  'home.title': '客服支持',
+  'home.subtitle': '发起一次对话 —— 我们就在这里回复你。',
+  'home.close': '关闭客服',
+  'home.open': '进行中',
+  'home.resolved': '已解决',
+  'home.empty': '还没有对话',
+  'home.emptyHint': '你发送的内容都会送到团队，他们的回复也会回到这个窗口。',
+  'home.noMessages': '还没有消息',
+  'home.you': '你',
+  'home.threadA11y': '对话：{type}',
+  'home.threadUnreadA11y': '对话：{type}，{count} 条未读',
+  'home.newA11y': '新建：{type}',
+  'home.language': '语言',
+
+  'type.feedback': '反馈',
+  'type.feature_request': '功能请求',
+  'type.bug_report': '错误报告',
+  'hint.feedback': '告诉我们你的想法',
+  'hint.feature_request': '提出一个改进建议',
+  'hint.bug_report': '有功能无法正常使用',
+  'prompt.feedback': '有什么想让我们知道的？',
+  'prompt.feature_request': '你希望看到什么？',
+  'prompt.bug_report': '发生了什么，你期待的结果是什么？',
+  'sub.feedback': '好评差评都会直接送到团队。',
+  'sub.feature_request': '告诉我们你想完成什么。',
+  'sub.bug_report': '操作步骤、所在页面和你的预期都很有帮助。',
+
+  'compose.back': '返回对话列表',
+  'compose.sent': '已发送',
+  'compose.sentHint':
+    '我们会在这里回复。对话会出现在「进行中」，我们回复后按钮上会显示提示。',
+  'compose.done': '完成',
+  'compose.send': '发送',
+  'compose.sending': '发送中…',
+  'compose.minChars': '至少输入 {count} 个字符',
+
+  'thread.support': '客服支持',
+  'thread.new': '新消息',
+  'thread.resolvedAt': '已解决 · {date}',
+  'thread.readOnly': '此对话已解决，仅供查看',
+  'thread.placeholder': '写下回复…',
+  'chat.placeholder': '输入消息…',
+  'review.appStore': '在 App Store 评分',
+  'review.playStore': '在 Google Play 评分',
+  'thread.sendA11y': '发送回复',
+  'thread.sendingA11y': '发送中',
+  'thread.translating': '翻译中…',
+
+  'status.open': '进行中',
+  'status.resolved': '已解决',
+
+  'error.tryAgain': '重试',
+  'error.rateLimited': '请求过于频繁 —— 请稍后再试',
+  'error.offline': '你已离线 —— 请检查网络连接',
+  'error.sendFailed': '发送失败 —— 请重试',
+  'error.loadFailed': '无法加载你的对话',
+  'error.unavailable': '客服支持暂时不可用',
+  'error.loadRateLimited': '请求过于频繁 —— 请稍等片刻再试',
+
+  'lang.title': '选择你的语言',
+  'lang.subtitle': '用你习惯的语言书写 —— 我们会在你和客服团队之间翻译。',
+  'lang.continue': '继续',
+  'lang.change': '更改语言',
+  'lang.saveFailed': '保存失败 —— 请重试',
+
+  'time.justNow': '刚刚',
+  'time.minutes': '{count} 分钟前',
+  'time.hours': '{count} 小时前',
+  'time.days': '{count} 天前',
+  'time.weeks': '{count} 周前',
+  'time.months': '{count} 个月前',
+  'time.years': '{count} 年前',
+  'time.today': '今天',
+  'time.yesterday': '昨天',
+};

package/src/index.tsx

@@ -3,11 +3,22 @@ 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,
+  deviceLanguage,
+  isSupportedLanguage,
+  LANGUAGE_LABELS,
+  SUPPORTED_LANGUAGES,
+  type Language,
+} from './i18n/languages';
 export type {
+  AccentColor,
   LauncherVariant,
   MessageSender,
   PushPermissionStatus,
@@ -19,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);
 }