@leisuresaas/react-native 0.6.2

package/src/app-update/context.tsx

@@ -0,0 +1,380 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { Alert, AppState, Linking, Platform, Pressable, Text, View } from "react-native";
+import * as SecureStore from "expo-secure-store";
+import Constants from "expo-constants";
+
+import { appBundleId } from "../ads/bundle-id";
+import { resolveGatewayUrlFromEnv } from "../gateway-url";
+import { mobilePlatform } from "../platform";
+import { getPublicAppConfig, type AppConfigResponse } from "../public-app-config";
+import { resolvePublishableKeyFromEnv } from "../publishable-key";
+
+const DISMISS_KEY_PREFIX = "leisuresaas_app_update_dismissed_";
+const THROTTLE_KEY = "leisuresaas_app_update_last_check_at";
+const DEFAULT_FOREGROUND_THROTTLE_MS = 4 * 60 * 60 * 1000;
+
+export type AppUpdateStatus = "idle" | "checking" | "up_to_date" | "recommended" | "required" | "error";
+
+export type AppUpdateInfo = AppConfigResponse;
+
+/** Override default Alert / Settings Card copy (server `update_message` still preferred for body). */
+export type AppUpdateLabels = {
+  requiredTitle?: string;
+  recommendedTitle?: string;
+  updateNow?: string;
+  later?: string;
+  update?: string;
+  settingsTitle?: string;
+  checkForUpdates?: string;
+  checking?: string;
+  openStore?: string;
+  upToDate?: string;
+  checkFailed?: string;
+};
+
+/** Headless Settings-page state: product owns all UI; SDK owns check / store actions. */
+export type AppVersionSettingsState = {
+  status: AppUpdateStatus;
+  displayVersion: string;
+  message: string | null;
+  busy: boolean;
+  canOpenStore: boolean;
+  checkNow: () => Promise<void>;
+  openStore: () => Promise<void>;
+  labels: Required<AppUpdateLabels>;
+  info: AppUpdateInfo | null;
+  error: string | null;
+};
+
+export type AppVersionSettingsCardProps = {
+  /** Custom Settings UI; omit to use the unstyled reference layout. */
+  children?: (state: AppVersionSettingsState) => ReactNode;
+};
+
+const defaultLabels: Required<AppUpdateLabels> = {
+  requiredTitle: "Update required",
+  recommendedTitle: "Update available",
+  updateNow: "Update now",
+  later: "Later",
+  update: "Update",
+  settingsTitle: "App version",
+  checkForUpdates: "Check for updates",
+  checking: "Checking…",
+  openStore: "Open store",
+  upToDate: "You're up to date.",
+  checkFailed: "Check failed. Try again.",
+};
+
+export type AppUpdateProviderProps = {
+  publishableKey?: string;
+  /** Platform API root for Public App Config. Defaults to EXPO_PUBLIC_GATEWAY_URL (never OAuth issuer). */
+  gatewayUrl?: string;
+  locale?: string;
+  labels?: AppUpdateLabels;
+  checkOnMount?: boolean;
+  checkOnForeground?: boolean;
+  foregroundThrottleMs?: number;
+  skipInDev?: boolean;
+  skipOnWeb?: boolean;
+  onUpdateRequired?: (info: AppUpdateInfo) => void;
+  onUpdateRecommended?: (info: AppUpdateInfo) => void;
+  children: ReactNode;
+};
+
+type AppUpdateContextValue = {
+  status: AppUpdateStatus;
+  info: AppUpdateInfo | null;
+  error: string | null;
+  displayVersion: string;
+  labels: Required<AppUpdateLabels>;
+  checkForUpdate: (opts?: { fresh?: boolean; quiet?: boolean }) => Promise<AppUpdateInfo | null>;
+  openStore: () => Promise<void>;
+  dismiss: () => Promise<void>;
+};
+
+const AppUpdateContext = createContext<AppUpdateContextValue | null>(null);
+
+function nativeAppVersion(): string {
+  return Constants.nativeApplicationVersion?.trim() || Constants.expoConfig?.version?.trim() || "0.0.0";
+}
+
+function nativeAppBuild(): string {
+  return Constants.nativeBuildVersion?.trim() || "";
+}
+
+function displayVersionString(): string {
+  const v = nativeAppVersion();
+  const b = nativeAppBuild();
+  return b ? `${v} (${b})` : v;
+}
+
+function mergeLabels(partial?: AppUpdateLabels): Required<AppUpdateLabels> {
+  return { ...defaultLabels, ...partial };
+}
+
+export function AppUpdateProvider({
+  publishableKey,
+  gatewayUrl,
+  locale,
+  labels: labelsProp,
+  checkOnMount = true,
+  checkOnForeground = true,
+  foregroundThrottleMs = DEFAULT_FOREGROUND_THROTTLE_MS,
+  skipInDev = true,
+  skipOnWeb = true,
+  onUpdateRequired,
+  onUpdateRecommended,
+  children,
+}: AppUpdateProviderProps) {
+  const [status, setStatus] = useState<AppUpdateStatus>("idle");
+  const [info, setInfo] = useState<AppUpdateInfo | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const lastCheckAt = useRef(0);
+  const labels = useMemo(() => mergeLabels(labelsProp), [labelsProp]);
+  const callbacksRef = useRef({ onUpdateRequired, onUpdateRecommended });
+  callbacksRef.current = { onUpdateRequired, onUpdateRecommended };
+  const labelsRef = useRef(labels);
+  labelsRef.current = labels;
+  const displayVersion = useMemo(() => displayVersionString(), []);
+
+  const skipped =
+    (skipInDev && typeof __DEV__ !== "undefined" && __DEV__) || (skipOnWeb && Platform.OS === "web");
+
+  const resolvedPublishableKey = publishableKey?.trim() || resolvePublishableKeyFromEnv();
+  const resolvedGatewayUrl = gatewayUrl?.trim() || resolveGatewayUrlFromEnv();
+
+  const dismissForVersion = useCallback(async (latest: string) => {
+    const v = latest.trim();
+    if (!v) return;
+    await SecureStore.setItemAsync(DISMISS_KEY_PREFIX + v, "1");
+  }, []);
+
+  const showDefaultAlert = useCallback(
+    (next: AppConfigResponse) => {
+      const L = labelsRef.current;
+      const body =
+        next.policy.update_message ||
+        next.policy.release_notes ||
+        (next.update.required ? "Please update to continue using the app." : "A new version is available.");
+
+      if (next.update.required) {
+        if (callbacksRef.current.onUpdateRequired) {
+          callbacksRef.current.onUpdateRequired(next);
+          return;
+        }
+        Alert.alert(
+          L.requiredTitle,
+          body,
+          [{ text: L.updateNow, onPress: () => void Linking.openURL(next.policy.store_url) }],
+          { cancelable: false },
+        );
+        return;
+      }
+      if (next.update.recommended) {
+        if (callbacksRef.current.onUpdateRecommended) {
+          callbacksRef.current.onUpdateRecommended(next);
+          return;
+        }
+        Alert.alert(L.recommendedTitle, body, [
+          {
+            text: L.later,
+            style: "cancel",
+            onPress: () => {
+              void dismissForVersion(next.policy.latest_version);
+            },
+          },
+          { text: L.update, onPress: () => void Linking.openURL(next.policy.store_url) },
+        ]);
+      }
+    },
+    [dismissForVersion],
+  );
+
+  const checkForUpdate = useCallback(
+    async (opts?: { fresh?: boolean; quiet?: boolean }) => {
+      const key = resolvedPublishableKey;
+      const gw = resolvedGatewayUrl;
+      if (!key || !gw || skipped) {
+        return null;
+      }
+      setStatus("checking");
+      setError(null);
+      try {
+        const next = await getPublicAppConfig(
+          {
+            gatewayUrl: gw,
+            publishableKey: key,
+            platform: mobilePlatform(),
+            bundleId: appBundleId(),
+            locale,
+          },
+          {
+            appVersion: nativeAppVersion(),
+            appBuild: nativeAppBuild(),
+            fresh: opts?.fresh,
+          },
+        );
+        setInfo(next);
+        lastCheckAt.current = Date.now();
+        void SecureStore.setItemAsync(THROTTLE_KEY, String(lastCheckAt.current));
+
+        if (next.update.required) {
+          setStatus("required");
+          if (!opts?.quiet) showDefaultAlert(next);
+        } else if (next.update.recommended) {
+          setStatus("recommended");
+          const dismissed = await SecureStore.getItemAsync(DISMISS_KEY_PREFIX + next.policy.latest_version);
+          // Auto-prompt skips dismissed; manual fresh check always shows the dialog.
+          const shouldPrompt = opts?.fresh || !dismissed;
+          if (shouldPrompt && !opts?.quiet) showDefaultAlert(next);
+        } else {
+          setStatus("up_to_date");
+        }
+        return next;
+      } catch (err) {
+        setStatus("error");
+        setError(err instanceof Error ? err.message : "update check failed");
+        return null;
+      }
+    },
+    [resolvedPublishableKey, resolvedGatewayUrl, locale, skipped, showDefaultAlert],
+  );
+
+  const openStore = useCallback(async () => {
+    const url = info?.policy.store_url?.trim();
+    if (url) await Linking.openURL(url);
+  }, [info]);
+
+  const dismiss = useCallback(async () => {
+    const latest = info?.policy.latest_version;
+    if (latest) await dismissForVersion(latest);
+  }, [info, dismissForVersion]);
+
+  useEffect(() => {
+    if (checkOnMount) void checkForUpdate();
+  }, [checkOnMount, checkForUpdate]);
+
+  useEffect(() => {
+    if (!checkOnForeground || skipped) return;
+    let cancelled = false;
+    void (async () => {
+      const raw = await SecureStore.getItemAsync(THROTTLE_KEY);
+      const n = Number(raw ?? 0);
+      if (!cancelled && Number.isFinite(n) && n > 0) lastCheckAt.current = n;
+    })();
+    const sub = AppState.addEventListener("change", (state) => {
+      if (state !== "active") return;
+      if (Date.now() - lastCheckAt.current < foregroundThrottleMs) return;
+      void checkForUpdate();
+    });
+    return () => {
+      cancelled = true;
+      sub.remove();
+    };
+  }, [checkOnForeground, checkForUpdate, foregroundThrottleMs, skipped]);
+
+  const value = useMemo(
+    (): AppUpdateContextValue => ({
+      status, info, error, displayVersion, labels, checkForUpdate, openStore, dismiss,
+    }),
+    [status, info, error, displayVersion, labels, checkForUpdate, openStore, dismiss],
+  );
+
+  return <AppUpdateContext.Provider value={value}>{children}</AppUpdateContext.Provider>;
+}
+
+export function useAppUpdate(): AppUpdateContextValue {
+  const ctx = useContext(AppUpdateContext);
+  if (!ctx) throw new Error("useAppUpdate must be used within AppUpdateProvider");
+  return ctx;
+}
+
+/**
+ * Settings-page headless API: version display + manual check + open store.
+ * Prefer this over `AppVersionSettingsCard` when matching product branding.
+ */
+export function useAppVersionSettings(): AppVersionSettingsState {
+  const { status, displayVersion, checkForUpdate, openStore, info, error, labels } = useAppUpdate();
+  const [busy, setBusy] = useState(false);
+  const [message, setMessage] = useState<string | null>(null);
+
+  const checkNow = useCallback(async () => {
+    setBusy(true);
+    setMessage(null);
+    try {
+      const next = await checkForUpdate({ fresh: true });
+      if (!next) {
+        setMessage(labels.checkFailed);
+        return;
+      }
+      if (next.update.required || next.update.recommended) {
+        setMessage(next.policy.update_message || next.policy.release_notes || labels.recommendedTitle);
+      } else {
+        setMessage(labels.upToDate);
+      }
+    } finally {
+      setBusy(false);
+    }
+  }, [checkForUpdate, labels.checkFailed, labels.recommendedTitle, labels.upToDate]);
+
+  const canOpenStore = Boolean(info?.update.required || info?.update.recommended);
+
+  return useMemo(
+    (): AppVersionSettingsState => ({
+      status,
+      displayVersion,
+      message,
+      busy,
+      canOpenStore,
+      checkNow,
+      openStore,
+      labels,
+      info,
+      error,
+    }),
+    [status, displayVersion, message, busy, canOpenStore, checkNow, openStore, labels, info, error],
+  );
+}
+
+/**
+ * Optional reference Settings UI (unstyled). Prefer `useAppVersionSettings` + product layout.
+ * Pass `children` as a render prop for full visual control without rewriting check logic.
+ */
+export function AppVersionSettingsCard({ children }: AppVersionSettingsCardProps) {
+  const state = useAppVersionSettings();
+  if (children) return <>{children(state)}</>;
+
+  const { status, displayVersion, message, busy, canOpenStore, checkNow, openStore, labels } = state;
+  return (
+    <View style={{ gap: 8, paddingVertical: 8 }}>
+      <Text style={{ fontSize: 16, fontWeight: "600" }}>{labels.settingsTitle}</Text>
+      <Text style={{ opacity: 0.7 }}>{displayVersion}</Text>
+      {message ? <Text>{message}</Text> : null}
+      <View style={{ flexDirection: "row", gap: 12 }}>
+        <Pressable
+          onPress={() => void checkNow()}
+          disabled={busy || status === "checking"}
+          style={{ paddingVertical: 8, paddingHorizontal: 12, opacity: busy ? 0.5 : 1 }}
+        >
+          <Text>{busy || status === "checking" ? labels.checking : labels.checkForUpdates}</Text>
+        </Pressable>
+        {canOpenStore ? (
+          <Pressable onPress={() => void openStore()} style={{ paddingVertical: 8, paddingHorizontal: 12 }}>
+            <Text>{labels.openStore}</Text>
+          </Pressable>
+        ) : null}
+      </View>
+    </View>
+  );
+}

package/src/auth-errors.ts

@@ -0,0 +1,50 @@
+export type AuthLoginErrorCode = "cancelled" | "no_code" | "exchange_failed" | "not_ready";
+
+const STABLE_MESSAGES: Record<AuthLoginErrorCode, string> = {
+  cancelled: "Cancelled",
+  no_code: "Did not redirect",
+  exchange_failed: "Login failed",
+  not_ready: "Login failed",
+};
+
+function causeSummary(cause: unknown): string {
+  if (cause == null) {
+    return "";
+  }
+  if (cause instanceof Error && cause.message.trim()) {
+    return cause.message.trim();
+  }
+  if (typeof cause === "string" && cause.trim()) {
+    return cause.trim();
+  }
+  try {
+    return String(cause);
+  } catch {
+    return "";
+  }
+}
+
+/** Stable OAuth login failure for product UI; use `message` only outside __DEV__. */
+export class AuthLoginError extends Error {
+  readonly code: AuthLoginErrorCode;
+  readonly cause?: unknown;
+
+  constructor(code: AuthLoginErrorCode, cause?: unknown) {
+    const stable = STABLE_MESSAGES[code];
+    const detail = typeof __DEV__ !== "undefined" && __DEV__ ? causeSummary(cause) : "";
+    super(detail ? `${stable}: ${detail}` : stable);
+    this.name = "AuthLoginError";
+    this.code = code;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+export function toAuthLoginError(code: AuthLoginErrorCode, cause?: unknown): AuthLoginError {
+  const err = new AuthLoginError(code, cause);
+  if (typeof __DEV__ !== "undefined" && __DEV__) {
+    console.warn(`[AuthProvider] login ${code}`, cause ?? err.message);
+  }
+  return err;
+}

package/src/auth-session.ts

@@ -0,0 +1,129 @@
+const REFRESH_SKEW_SEC = 60;
+
+export function accessExpUnix(accessToken: string): number | undefined {
+  const parts = accessToken.split(".");
+  if (parts.length < 2) {
+    return undefined;
+  }
+  try {
+    const json = atob(parts[1].replace(/-/g, "+").replace(/_/g, "/"));
+    const payload = JSON.parse(json) as { exp?: number };
+    return typeof payload.exp === "number" ? payload.exp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function accessNeedsRefresh(accessToken: string): boolean {
+  const exp = accessExpUnix(accessToken);
+  if (!exp) {
+    return false;
+  }
+  return exp - Math.floor(Date.now() / 1000) <= REFRESH_SKEW_SEC;
+}
+
+export type OAuthTokenResponse = {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  refreshExpiresIn?: number;
+};
+
+async function postOAuthToken(
+  issuer: string,
+  body: URLSearchParams,
+  label: string,
+): Promise<OAuthTokenResponse> {
+  const res = await fetch(`${issuer.replace(/\/$/, "")}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${label} failed (${res.status}): ${text}`);
+  }
+  const data = (await res.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    refresh_expires_in?: number;
+  };
+  const accessToken = data.access_token?.trim();
+  if (!accessToken) {
+    throw new Error(`${label}: missing access_token`);
+  }
+  return {
+    accessToken,
+    refreshToken: data.refresh_token?.trim() || undefined,
+    expiresIn: data.expires_in,
+    refreshExpiresIn: data.refresh_expires_in,
+  };
+}
+
+export async function refreshOAuthTokens(
+  issuer: string,
+  clientId: string,
+  refreshToken: string,
+): Promise<OAuthTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId,
+  });
+  return postOAuthToken(issuer, body, "token refresh");
+}
+
+/** Exchange an authorization code (PKCE) at the platform token endpoint. */
+export async function exchangeAuthorizationCode(
+  issuer: string,
+  clientId: string,
+  code: string,
+  redirectUri: string,
+  codeVerifier: string,
+): Promise<OAuthTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: code.trim(),
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: codeVerifier,
+  });
+  return postOAuthToken(issuer, body, "authorization code exchange");
+}
+
+/** Exchange a one-time magic_token from household Magic redeem (grant magic-token). */
+export async function exchangeMagicToken(
+  issuer: string,
+  clientId: string,
+  magicToken: string,
+  clientSecret?: string,
+): Promise<OAuthTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "urn:leisuresaas:oauth:magic-token",
+    magic_token: magicToken.trim(),
+    client_id: clientId,
+  });
+  if (clientSecret?.trim()) {
+    body.set("client_secret", clientSecret.trim());
+  }
+  return postOAuthToken(issuer, body, "magic token exchange");
+}
+
+/** Read magic_token from an App Link / redirect URL after Magic confirm. */
+export function magicTokenFromURL(url: string): string | undefined {
+  try {
+    const u = new URL(url);
+    const fromQuery = u.searchParams.get("magic_token")?.trim();
+    if (fromQuery) {
+      return fromQuery;
+    }
+    if (u.hash) {
+      const hash = new URLSearchParams(u.hash.replace(/^#/, ""));
+      return hash.get("magic_token")?.trim() || undefined;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}

package/src/auth-storage.ts

@@ -0,0 +1,62 @@
+import * as SecureStore from "expo-secure-store";
+import { Platform } from "react-native";
+
+const WEB_PROD_MSG =
+  "OAuth token persistence is not supported on web production builds; use the native app.";
+
+/** Metro / Expo web development (`npm start` in browser). */
+export function isWebDev(): boolean {
+  return Platform.OS === "web" && typeof __DEV__ !== "undefined" && __DEV__;
+}
+
+/** Web production / release build — no durable OAuth tokens. */
+export function isWebProduction(): boolean {
+  return Platform.OS === "web" && !isWebDev();
+}
+
+/** Throws when Web production would persist OAuth credentials. */
+export function assertAuthStorageAllowed(): void {
+  if (isWebProduction()) {
+    throw new Error(WEB_PROD_MSG);
+  }
+}
+
+export async function authGetItem(key: string): Promise<string | null> {
+  if (Platform.OS !== "web") {
+    return SecureStore.getItemAsync(key);
+  }
+  if (isWebDev()) {
+    try {
+      return globalThis.localStorage?.getItem(key) ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export async function authSetItem(key: string, value: string): Promise<void> {
+  if (Platform.OS !== "web") {
+    await SecureStore.setItemAsync(key, value);
+    return;
+  }
+  if (isWebDev()) {
+    globalThis.localStorage?.setItem(key, value);
+    return;
+  }
+  throw new Error(WEB_PROD_MSG);
+}
+
+export async function authDeleteItem(key: string): Promise<void> {
+  if (Platform.OS !== "web") {
+    await SecureStore.deleteItemAsync(key);
+    return;
+  }
+  if (isWebDev()) {
+    try {
+      globalThis.localStorage?.removeItem(key);
+    } catch {
+      /* ignore */
+    }
+  }
+}