@croacroa/react-native-template 2.1.0 → 3.2.0

package/hooks/usePermission.ts

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview React hook for centralized permission management
+ * Provides a reactive interface for checking and requesting permissions
+ * with automatic refresh when returning from device Settings.
+ * @module hooks/usePermission
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { AppState, AppStateStatus } from "react-native";
+
+import { PermissionManager } from "@/services/permissions/permission-manager";
+import {
+  DEFAULT_PERMISSION_CONFIGS,
+  type PermissionType,
+  type PermissionStatus,
+  type PermissionConfig,
+} from "@/services/permissions/types";
+
+/**
+ * Return type for the usePermission hook
+ */
+export interface UsePermissionReturn {
+  /** Current normalized permission status */
+  status: PermissionStatus;
+  /** Whether the permission is granted */
+  isGranted: boolean;
+  /** Whether the permission is blocked (must open Settings to change) */
+  isBlocked: boolean;
+  /** Whether the permission status is being loaded */
+  isLoading: boolean;
+  /** UI configuration for this permission (merged defaults + custom) */
+  config: PermissionConfig;
+  /** Request the permission from the user and return the resulting status */
+  request: () => Promise<PermissionStatus>;
+  /** Open device settings for this app */
+  openSettings: () => Promise<void>;
+  /** Manually refresh the permission status */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook for managing a single permission type.
+ * Checks the permission on mount and re-checks when the app returns
+ * from the background (e.g., after the user changes settings).
+ *
+ * @param type - The permission type to manage
+ * @param customConfig - Optional partial config to override defaults
+ * @returns Permission state and control functions
+ *
+ * @example
+ * ```tsx
+ * function CameraScreen() {
+ *   const { status, isGranted, isBlocked, request, openSettings } = usePermission('camera');
+ *
+ *   if (!isGranted) {
+ *     return (
+ *       <View>
+ *         <Text>Camera access required</Text>
+ *         {isBlocked ? (
+ *           <Button onPress={openSettings}>Open Settings</Button>
+ *         ) : (
+ *           <Button onPress={request}>Allow Camera</Button>
+ *         )}
+ *       </View>
+ *     );
+ *   }
+ *
+ *   return <CameraView />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom config
+ * const permission = usePermission('location', {
+ *   title: 'Share Your Location',
+ *   message: 'We use your location to find nearby restaurants.',
+ * });
+ * ```
+ */
+export function usePermission(
+  type: PermissionType,
+  customConfig?: Partial<PermissionConfig>
+): UsePermissionReturn {
+  const [status, setStatus] = useState<PermissionStatus>("undetermined");
+  const [isLoading, setIsLoading] = useState(true);
+  const appStateRef = useRef<AppStateStatus>(AppState.currentState);
+
+  // Merge custom config with defaults
+  const config: PermissionConfig = {
+    ...DEFAULT_PERMISSION_CONFIGS[type],
+    ...customConfig,
+  };
+
+  /**
+   * Check the current permission status
+   */
+  const checkPermission = useCallback(async () => {
+    try {
+      const result = await PermissionManager.check(type);
+      setStatus(result.status);
+    } catch (error) {
+      console.error(`[usePermission] Failed to check ${type}:`, error);
+    }
+  }, [type]);
+
+  /**
+   * Refresh permission status (public API)
+   */
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    await checkPermission();
+    setIsLoading(false);
+  }, [checkPermission]);
+
+  /**
+   * Request the permission
+   */
+  const request = useCallback(async (): Promise<PermissionStatus> => {
+    setIsLoading(true);
+    try {
+      const result = await PermissionManager.request(type);
+      setStatus(result.status);
+      return result.status;
+    } catch (error) {
+      console.error(`[usePermission] Failed to request ${type}:`, error);
+      return "undetermined";
+    } finally {
+      setIsLoading(false);
+    }
+  }, [type]);
+
+  /**
+   * Open device settings
+   */
+  const openSettings = useCallback(async () => {
+    await PermissionManager.openSettings();
+  }, []);
+
+  // Check permission on mount
+  useEffect(() => {
+    let isMounted = true;
+
+    const initialCheck = async () => {
+      await checkPermission();
+      if (isMounted) {
+        setIsLoading(false);
+      }
+    };
+
+    initialCheck();
+
+    return () => {
+      isMounted = false;
+    };
+  }, [checkPermission]);
+
+  // Re-check when app comes back from background (e.g., returning from Settings)
+  useEffect(() => {
+    const handleAppStateChange = (nextAppState: AppStateStatus) => {
+      if (
+        appStateRef.current.match(/inactive|background/) &&
+        nextAppState === "active"
+      ) {
+        checkPermission();
+      }
+      appStateRef.current = nextAppState;
+    };
+
+    const subscription = AppState.addEventListener(
+      "change",
+      handleAppStateChange
+    );
+
+    return () => {
+      subscription.remove();
+    };
+  }, [checkPermission]);
+
+  return {
+    status,
+    isGranted: status === "granted",
+    isBlocked: status === "blocked",
+    isLoading,
+    config,
+    request,
+    openSettings,
+    refresh,
+  };
+}

package/hooks/usePresence.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview User presence tracking hook
+ * Tracks online users in a channel via presence_join, presence_leave,
+ * and presence_sync WebSocket messages.
+ * @module hooks/usePresence
+ */
+
+import { useEffect, useState, useCallback, useRef } from "react";
+
+import { WebSocketManager } from "@/services/realtime/websocket-manager";
+import type { PresenceUser } from "@/services/realtime/types";
+
+/**
+ * Return type for the usePresence hook.
+ */
+export interface UsePresenceReturn {
+  /** Array of currently online users in the channel */
+  onlineUsers: PresenceUser[];
+  /** Check whether a specific user is currently online */
+  isUserOnline: (userId: string) => boolean;
+}
+
+/**
+ * Hook for tracking user presence in a WebSocket channel.
+ *
+ * Subscribes to the given channel and listens for presence-related message types:
+ * - `presence_join` — A user has come online
+ * - `presence_leave` — A user has gone offline
+ * - `presence_sync` — Full list of currently online users (requested on mount)
+ *
+ * On mount, sends a `presence_sync` request to the server so the initial state
+ * is populated.
+ *
+ * @param manager - The WebSocketManager instance (from useWebSocket)
+ * @param channel - The channel to track presence for
+ * @returns Object with onlineUsers array and isUserOnline helper
+ *
+ * @example
+ * ```tsx
+ * function OnlineIndicator({ roomId }: { roomId: string }) {
+ *   const { manager } = useWebSocket({ url: WS_URL });
+ *   const { onlineUsers, isUserOnline } = usePresence(manager, `room:${roomId}`);
+ *
+ *   return (
+ *     <View>
+ *       <Text>{onlineUsers.length} online</Text>
+ *       {onlineUsers.map((user) => (
+ *         <Text key={user.id}>{user.name ?? user.id}</Text>
+ *       ))}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function usePresence(
+  manager: WebSocketManager,
+  channel: string
+): UsePresenceReturn {
+  const [onlineUsers, setOnlineUsers] = useState<PresenceUser[]>([]);
+  const usersRef = useRef<Map<string, PresenceUser>>(new Map());
+
+  useEffect(() => {
+    // Reset state when channel changes
+    usersRef.current = new Map();
+    setOnlineUsers([]);
+
+    const unsubscribe = manager.subscribe(channel, (message) => {
+      const { type, payload } = message;
+
+      switch (type) {
+        case "presence_join": {
+          const user = payload as PresenceUser;
+          if (!user?.id) break;
+          usersRef.current.set(user.id, {
+            ...user,
+            lastSeen: user.lastSeen ?? new Date().toISOString(),
+          });
+          setOnlineUsers(Array.from(usersRef.current.values()));
+          break;
+        }
+
+        case "presence_leave": {
+          const leavePayload = payload as { id: string };
+          if (!leavePayload?.id) break;
+          usersRef.current.delete(leavePayload.id);
+          setOnlineUsers(Array.from(usersRef.current.values()));
+          break;
+        }
+
+        case "presence_sync": {
+          const users = payload as PresenceUser[];
+          if (!Array.isArray(users)) break;
+          usersRef.current = new Map(
+            users
+              .filter((user) => user?.id)
+              .map((user) => [
+                user.id,
+                {
+                  ...user,
+                  lastSeen: user.lastSeen ?? new Date().toISOString(),
+                },
+              ])
+          );
+          setOnlineUsers(Array.from(usersRef.current.values()));
+          break;
+        }
+
+        default:
+          break;
+      }
+    });
+
+    // Request a full sync from the server on mount
+    manager.send("presence_sync", { channel }, channel);
+
+    return () => {
+      unsubscribe();
+    };
+  }, [manager, channel]);
+
+  const isUserOnline = useCallback((userId: string): boolean => {
+    return usersRef.current.has(userId);
+  }, []);
+
+  return {
+    onlineUsers,
+    isUserOnline,
+  };
+}

package/hooks/useProducts.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Hook for fetching available in-app products
+ * Uses TanStack Query for caching and automatic refetching.
+ * @module hooks/useProducts
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { Payments } from "@/services/payments/payment-adapter";
+import type { Product } from "@/services/payments/types";
+
+/**
+ * Fetch available products by their store IDs.
+ * Results are cached for 5 minutes to avoid unnecessary store lookups.
+ *
+ * @param productIds - Array of product identifiers to fetch
+ * @returns TanStack Query result with products array
+ *
+ * @example
+ * ```tsx
+ * function ProductList() {
+ *   const { data: products, isLoading } = useProducts(["premium_monthly", "premium_yearly"]);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *
+ *   return products?.map((p) => <Text key={p.id}>{p.title} — {p.priceString}</Text>);
+ * }
+ * ```
+ */
+export function useProducts(productIds: string[]) {
+  return useQuery<Product[], Error>({
+    queryKey: ["products", productIds],
+    queryFn: () => Payments.getProducts(productIds),
+    staleTime: 1000 * 60 * 5, // 5 minutes
+    enabled: productIds.length > 0,
+  });
+}

package/hooks/usePurchase.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Hook for initiating purchases and restoring transactions
+ * Wraps the Payments facade with loading/error state management.
+ * @module hooks/usePurchase
+ */
+
+import { useState, useCallback } from "react";
+import { Payments } from "@/services/payments/payment-adapter";
+import type { Purchase } from "@/services/payments/types";
+
+/**
+ * Return type for the usePurchase hook.
+ */
+export interface UsePurchaseReturn {
+  /** Initiate a purchase for the given product ID */
+  purchase: (productId: string) => Promise<Purchase | null>;
+  /** Restore previously completed purchases */
+  restore: () => Promise<Purchase[]>;
+  /** Whether a purchase or restore operation is in progress */
+  isLoading: boolean;
+  /** The most recent error, or null */
+  error: Error | null;
+}
+
+/**
+ * Hook for initiating purchases and restoring transactions.
+ * Provides loading and error state so the UI can react accordingly.
+ *
+ * @returns Object with purchase/restore functions and state
+ *
+ * @example
+ * ```tsx
+ * function BuyButton({ productId }: { productId: string }) {
+ *   const { purchase, isLoading, error } = usePurchase();
+ *
+ *   const handleBuy = async () => {
+ *     const result = await purchase(productId);
+ *     if (result) {
+ *       // Purchase succeeded
+ *     }
+ *   };
+ *
+ *   return (
+ *     <Button onPress={handleBuy} isLoading={isLoading}>
+ *       Buy Now
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export function usePurchase(): UsePurchaseReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const purchase = useCallback(
+    async (productId: string): Promise<Purchase | null> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const result = await Payments.purchase(productId);
+        return result;
+      } catch (err) {
+        const purchaseError =
+          err instanceof Error ? err : new Error("Purchase failed");
+        setError(purchaseError);
+
+        if (__DEV__) {
+          console.warn("[usePurchase] Purchase error:", purchaseError.message);
+        }
+
+        return null;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    []
+  );
+
+  const restore = useCallback(async (): Promise<Purchase[]> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const purchases = await Payments.restorePurchases();
+      return purchases;
+    } catch (err) {
+      const restoreError =
+        err instanceof Error ? err : new Error("Restore failed");
+      setError(restoreError);
+
+      if (__DEV__) {
+        console.warn("[usePurchase] Restore error:", restoreError.message);
+      }
+
+      return [];
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  return { purchase, restore, isLoading, error };
+}

package/hooks/useRateLimit.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Hook to expose the ApiClient's rate limit state to components.
+ * Polls the singleton ApiClient every second while rate limited.
+ * @module hooks/useRateLimit
+ */
+
+import { useState, useEffect } from "react";
+import { api } from "@/services/api";
+
+interface UseRateLimitReturn {
+  /** true while the API client is rate limited */
+  isRateLimited: boolean;
+  /** Seconds remaining until the rate limit expires (0 when not limited) */
+  retryAfter: number;
+  /** Date when the rate limit expires, or null when not limited */
+  resetTime: Date | null;
+}
+
+/**
+ * Returns the current rate-limit state of the shared ApiClient singleton.
+ *
+ * While rate limited the hook polls every second so the UI can show a
+ * countdown or disable submit buttons.
+ *
+ * @example
+ * ```tsx
+ * const { isRateLimited, retryAfter } = useRateLimit();
+ * if (isRateLimited) {
+ *   return <Text>Try again in {retryAfter}s</Text>;
+ * }
+ * ```
+ */
+export function useRateLimit(): UseRateLimitReturn {
+  const [state, setState] = useState<UseRateLimitReturn>({
+    isRateLimited: false,
+    retryAfter: 0,
+    resetTime: null,
+  });
+
+  useEffect(() => {
+    // Poll every second — the cost is negligible since setState short-circuits
+    // when values haven't changed. Continuous polling ensures we always detect
+    // new 429 responses even after a previous rate limit window has expired.
+    const interval = setInterval(() => {
+      const now = Date.now();
+      const until = api.rateLimitedUntil;
+
+      if (now < until) {
+        setState((prev) => {
+          const retryAfter = Math.ceil((until - now) / 1000);
+          if (prev.isRateLimited && prev.retryAfter === retryAfter) return prev;
+          return {
+            isRateLimited: true,
+            retryAfter,
+            resetTime: new Date(until),
+          };
+        });
+      } else {
+        setState((prev) => {
+          if (!prev.isRateLimited) return prev;
+          return { isRateLimited: false, retryAfter: 0, resetTime: null };
+        });
+      }
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, []);
+
+  return state;
+}

package/hooks/useSubscription.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Hook for querying the current subscription status
+ * Uses TanStack Query for caching and provides derived boolean helpers.
+ * @module hooks/useSubscription
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { Payments } from "@/services/payments/payment-adapter";
+import type { SubscriptionInfo } from "@/services/payments/types";
+
+/**
+ * Query the current user's subscription status.
+ * Results are cached for 1 minute so the UI stays responsive without
+ * over-querying the payment provider.
+ *
+ * Returns the full TanStack Query result plus two derived helpers:
+ * - `isActive` — true when the subscription is "active" or in "grace_period"
+ * - `isPro` — true only when the subscription is "active"
+ *
+ * @returns TanStack Query result with subscription info and helpers
+ *
+ * @example
+ * ```tsx
+ * function PremiumBadge() {
+ *   const { isPro, isLoading } = useSubscription();
+ *
+ *   if (isLoading || !isPro) return null;
+ *
+ *   return <Badge label="PRO" />;
+ * }
+ * ```
+ */
+export function useSubscription() {
+  const query = useQuery<SubscriptionInfo, Error>({
+    queryKey: ["subscription-status"],
+    queryFn: () => Payments.getSubscriptionStatus(),
+    staleTime: 1000 * 60, // 1 minute
+  });
+
+  const status = query.data?.status;
+
+  return {
+    ...query,
+    /** True when subscription is active or in grace period */
+    isActive: status === "active" || status === "grace_period",
+    /** True only when subscription is fully active */
+    isPro: status === "active",
+  };
+}

package/hooks/useTrackEvent.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Custom event tracking hook
+ * Returns a stable, memoized `track` function that delegates to the
+ * analytics adapter manager.
+ * @module hooks/useTrackEvent
+ */
+
+import { useCallback } from "react";
+
+import { Analytics } from "@/services/analytics/analytics-adapter";
+
+/**
+ * Return type for the useTrackEvent hook.
+ */
+export interface UseTrackEventReturn {
+  /** Fire an analytics event with optional properties */
+  track: (event: string, properties?: Record<string, unknown>) => void;
+}
+
+/**
+ * Provides a memoized `track` function for firing analytics events.
+ *
+ * The returned function is referentially stable (via `useCallback`) so it
+ * is safe to pass as a prop or include in dependency arrays without causing
+ * unnecessary re-renders.
+ *
+ * @returns Object containing the stable `track` function
+ *
+ * @example
+ * ```tsx
+ * function CheckoutButton() {
+ *   const { track } = useTrackEvent();
+ *
+ *   const handlePress = () => {
+ *     track("Checkout Started", { cartSize: 3 });
+ *     navigateToCheckout();
+ *   };
+ *
+ *   return <Button onPress={handlePress} title="Checkout" />;
+ * }
+ * ```
+ */
+export function useTrackEvent(): UseTrackEventReturn {
+  const track = useCallback(
+    (event: string, properties?: Record<string, unknown>) => {
+      Analytics.track(event, properties);
+    },
+    []
+  );
+
+  return { track };
+}

package/hooks/useTrackScreen.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Automatic screen tracking hook for Expo Router
+ * Listens to route changes via usePathname / useSegments and fires
+ * an analytics screen event on every navigation.
+ * @module hooks/useTrackScreen
+ */
+
+import { useEffect, useRef } from "react";
+import { usePathname, useSegments } from "expo-router";
+
+import { Analytics } from "@/services/analytics/analytics-adapter";
+
+/**
+ * Automatically tracks screen views whenever the Expo Router pathname changes.
+ *
+ * Place this hook once in your root layout or `AnalyticsProvider` so that every
+ * navigation event is recorded without manual instrumentation.
+ *
+ * @example
+ * ```tsx
+ * function RootLayout() {
+ *   useTrackScreen();
+ *   return <Slot />;
+ * }
+ * ```
+ */
+export function useTrackScreen(): void {
+  const pathname = usePathname();
+  const segments = useSegments();
+  const previousPathname = useRef<string | null>(null);
+
+  useEffect(() => {
+    // Only fire when the pathname actually changes (avoids duplicate on mount)
+    if (pathname && pathname !== previousPathname.current) {
+      Analytics.screen(pathname, { segments });
+      previousPathname.current = pathname;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- segments is derived from pathname; using pathname as the sole trigger avoids duplicate fires
+  }, [pathname]);
+}