@croacroa/react-native-template 2.1.0 → 3.2.0

package/services/payments/types.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Payment and subscription type definitions
+ * Defines the adapter interface, product/purchase models, and subscription types
+ * for the payment system.
+ * @module services/payments/types
+ */
+
+// ============================================================================
+// Product Types
+// ============================================================================
+
+/** The type of in-app product */
+export type ProductType = "consumable" | "non_consumable" | "subscription";
+
+/** Subscription billing period */
+export type SubscriptionPeriod = "weekly" | "monthly" | "quarterly" | "yearly";
+
+/**
+ * Represents a purchasable product from the app store.
+ */
+export interface Product {
+  /** Unique product identifier (matches store product ID) */
+  id: string;
+  /** Display title of the product */
+  title: string;
+  /** Short description of the product */
+  description: string;
+  /** Numeric price in the smallest currency unit */
+  price: number;
+  /** Localized price string for display (e.g. "$9.99") */
+  priceString: string;
+  /** ISO 4217 currency code (e.g. "USD") */
+  currency: string;
+  /** The type of product */
+  type: ProductType;
+  /** Billing period for subscription products */
+  subscriptionPeriod?: SubscriptionPeriod;
+}
+
+// ============================================================================
+// Purchase Types
+// ============================================================================
+
+/**
+ * Represents a completed purchase transaction.
+ */
+export interface Purchase {
+  /** Unique purchase/transaction identifier */
+  id: string;
+  /** The product that was purchased */
+  productId: string;
+  /** ISO 8601 date string of the transaction */
+  transactionDate: string;
+  /** Optional receipt data for server-side validation */
+  transactionReceipt?: string;
+}
+
+// ============================================================================
+// Subscription Types
+// ============================================================================
+
+/** Current status of a user's subscription */
+export type SubscriptionStatus =
+  | "active"
+  | "expired"
+  | "cancelled"
+  | "grace_period"
+  | "none";
+
+/**
+ * Detailed information about a user's subscription.
+ */
+export interface SubscriptionInfo {
+  /** Current subscription status */
+  status: SubscriptionStatus;
+  /** The subscribed product ID, or null if no subscription */
+  productId: string | null;
+  /** ISO 8601 expiration date, or null if no subscription */
+  expiresAt: string | null;
+  /** Whether the subscription will auto-renew */
+  willRenew: boolean;
+}
+
+// ============================================================================
+// Adapter Interface
+// ============================================================================
+
+/**
+ * Interface that all payment adapters must implement.
+ * Swap adapters to switch between providers (RevenueCat, Qonversion, etc.)
+ * without changing application code.
+ */
+export interface PaymentAdapter {
+  /**
+   * Initialize the payment provider.
+   * Called once when the app starts.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Fetch available products by their store IDs.
+   *
+   * @param ids - Array of product identifiers to fetch
+   * @returns Array of available products
+   */
+  getProducts(ids: string[]): Promise<Product[]>;
+
+  /**
+   * Initiate a purchase for the given product.
+   *
+   * @param productId - The product to purchase
+   * @returns The completed purchase record
+   * @throws Error if the purchase fails or is cancelled
+   */
+  purchase(productId: string): Promise<Purchase>;
+
+  /**
+   * Restore previously completed purchases.
+   * Useful when a user reinstalls the app or switches devices.
+   *
+   * @returns Array of restored purchases
+   */
+  restorePurchases(): Promise<Purchase[]>;
+
+  /**
+   * Get the current subscription status for the user.
+   *
+   * @returns Current subscription information
+   */
+  getSubscriptionStatus(): Promise<SubscriptionInfo>;
+}

package/services/permissions/permission-manager.ts

@@ -0,0 +1,284 @@
+/**
+ * @fileoverview Centralized permission management service
+ * Provides a unified API for checking, requesting, and tracking permissions
+ * across different Expo modules.
+ * @module services/permissions/permission-manager
+ */
+
+import { Platform, Linking } from "react-native";
+import { Camera } from "expo-camera";
+import * as Location from "expo-location";
+import * as Contacts from "expo-contacts";
+import * as MediaLibrary from "expo-media-library";
+import * as Notifications from "expo-notifications";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+import { STORAGE_KEYS } from "@/constants/config";
+import type {
+  PermissionType,
+  PermissionResult,
+  PermissionStatus,
+} from "./types";
+
+/** AsyncStorage key prefix for tracking asked permissions */
+const PERMISSION_ASKED_PREFIX = STORAGE_KEYS.PERMISSION_PREFIX;
+
+/**
+ * Normalize native Expo permission status to our unified PermissionStatus.
+ * Handles the various status strings returned by different Expo modules.
+ *
+ * @param nativeStatus - The status string from an Expo permission response
+ * @param canAskAgain - Whether the system allows re-requesting the permission
+ * @returns Normalized PermissionStatus
+ */
+export function normalizeStatus(
+  nativeStatus: string,
+  canAskAgain: boolean
+): PermissionStatus {
+  switch (nativeStatus) {
+    case "granted":
+      return "granted";
+    case "undetermined":
+      return "undetermined";
+    case "denied":
+      return canAskAgain ? "denied" : "blocked";
+    default:
+      return "undetermined";
+  }
+}
+
+/**
+ * Permission handler interface for each permission type.
+ * Each handler provides check and request methods that return
+ * a normalized PermissionResult.
+ */
+interface PermissionHandler {
+  check: () => Promise<PermissionResult>;
+  request: () => Promise<PermissionResult>;
+}
+
+/**
+ * Map of permission handlers for each supported PermissionType.
+ * Each handler wraps the corresponding Expo module's permission API.
+ */
+const permissionHandlers: Record<PermissionType, PermissionHandler> = {
+  camera: {
+    check: async () => {
+      const result = await Camera.getCameraPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Camera.requestCameraPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  location: {
+    check: async () => {
+      const result = await Location.getForegroundPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Location.requestForegroundPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  locationAlways: {
+    check: async () => {
+      const result = await Location.getBackgroundPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Location.requestBackgroundPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  contacts: {
+    check: async () => {
+      const result = await Contacts.getPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Contacts.requestPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  mediaLibrary: {
+    check: async () => {
+      const result = await MediaLibrary.getPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await MediaLibrary.requestPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  microphone: {
+    check: async () => {
+      const result = await Camera.getMicrophonePermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Camera.requestMicrophonePermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+
+  notifications: {
+    check: async () => {
+      const result = await Notifications.getPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+    request: async () => {
+      const result = await Notifications.requestPermissionsAsync();
+      return {
+        status: normalizeStatus(result.status, result.canAskAgain),
+        canAskAgain: result.canAskAgain,
+      };
+    },
+  },
+};
+
+/**
+ * Centralized permission manager.
+ * Provides a unified API for all permission operations across the app.
+ *
+ * @example
+ * ```ts
+ * import { PermissionManager } from '@/services/permissions/permission-manager';
+ *
+ * // Check camera permission
+ * const result = await PermissionManager.check('camera');
+ * if (result.status === 'granted') {
+ *   // Camera is available
+ * }
+ *
+ * // Request notification permission
+ * const notifResult = await PermissionManager.request('notifications');
+ * if (notifResult.status === 'blocked') {
+ *   await PermissionManager.openSettings();
+ * }
+ * ```
+ */
+export const PermissionManager = {
+  /**
+   * Check the current status of a permission without requesting it.
+   *
+   * @param type - The permission type to check
+   * @returns The current permission result
+   */
+  async check(type: PermissionType): Promise<PermissionResult> {
+    try {
+      const handler = permissionHandlers[type];
+      return await handler.check();
+    } catch (error) {
+      console.error(`[PermissionManager] Failed to check ${type}:`, error);
+      return { status: "undetermined", canAskAgain: true };
+    }
+  },
+
+  /**
+   * Request a permission from the user.
+   * Records that the permission has been asked in AsyncStorage.
+   *
+   * @param type - The permission type to request
+   * @returns The permission result after the request
+   */
+  async request(type: PermissionType): Promise<PermissionResult> {
+    try {
+      const handler = permissionHandlers[type];
+      const result = await handler.request();
+
+      // Track that we've asked for this permission
+      await AsyncStorage.setItem(`${PERMISSION_ASKED_PREFIX}${type}`, "true");
+
+      return result;
+    } catch (error) {
+      console.error(`[PermissionManager] Failed to request ${type}:`, error);
+      return { status: "undetermined", canAskAgain: true };
+    }
+  },
+
+  /**
+   * Open the device settings so the user can manually change permissions.
+   * On iOS, opens the app-specific settings page.
+   * On Android, uses Linking.openSettings() to open app info.
+   */
+  async openSettings(): Promise<void> {
+    try {
+      if (Platform.OS === "ios") {
+        await Linking.openURL("app-settings:");
+      } else {
+        await Linking.openSettings();
+      }
+    } catch (error) {
+      console.error("[PermissionManager] Failed to open settings:", error);
+    }
+  },
+
+  /**
+   * Check whether a permission has been previously asked.
+   * Useful for determining whether to show a pre-permission explanation
+   * before the system dialog.
+   *
+   * @param type - The permission type to check
+   * @returns Whether the permission has been previously requested
+   */
+  async hasBeenAsked(type: PermissionType): Promise<boolean> {
+    try {
+      const value = await AsyncStorage.getItem(
+        `${PERMISSION_ASKED_PREFIX}${type}`
+      );
+      return value === "true";
+    } catch (error) {
+      console.error(
+        `[PermissionManager] Failed to check if ${type} was asked:`,
+        error
+      );
+      return false;
+    }
+  },
+};

package/services/permissions/types.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Permission types and default configurations
+ * Centralized type definitions for the permission management system.
+ * @module services/permissions/types
+ */
+
+/**
+ * Supported permission types across the app.
+ * Maps to corresponding Expo permission modules.
+ */
+export type PermissionType =
+  | "camera"
+  | "location"
+  | "locationAlways"
+  | "contacts"
+  | "mediaLibrary"
+  | "microphone"
+  | "notifications";
+
+/**
+ * Normalized permission status across platforms.
+ * - 'undetermined': Permission has not been requested yet
+ * - 'granted': Permission has been granted
+ * - 'denied': Permission was denied but can be requested again
+ * - 'blocked': Permission was denied and cannot be requested again (must open Settings)
+ */
+export type PermissionStatus =
+  | "undetermined"
+  | "granted"
+  | "denied"
+  | "blocked";
+
+/**
+ * Result of a permission check or request
+ */
+export interface PermissionResult {
+  /** Normalized permission status */
+  status: PermissionStatus;
+  /** Whether the system will show the permission dialog if requested again */
+  canAskAgain: boolean;
+}
+
+/**
+ * Configuration for permission request UI
+ */
+export interface PermissionConfig {
+  /** Title shown in the permission request UI */
+  title: string;
+  /** Descriptive message explaining why the permission is needed */
+  message: string;
+  /** Ionicons icon name to display */
+  icon: string;
+}
+
+/**
+ * Default UI configurations for each permission type.
+ * These can be overridden per-usage via the usePermission hook or PermissionGate component.
+ */
+export const DEFAULT_PERMISSION_CONFIGS: Record<
+  PermissionType,
+  PermissionConfig
+> = {
+  camera: {
+    title: "Camera Access",
+    message: "We need access to your camera to take photos and scan codes.",
+    icon: "camera-outline",
+  },
+  location: {
+    title: "Location Access",
+    message:
+      "We need access to your location to provide location-based features.",
+    icon: "location-outline",
+  },
+  locationAlways: {
+    title: "Background Location",
+    message:
+      "We need background location access to provide continuous location-based services.",
+    icon: "navigate-outline",
+  },
+  contacts: {
+    title: "Contacts Access",
+    message:
+      "We need access to your contacts to help you connect with friends.",
+    icon: "people-outline",
+  },
+  mediaLibrary: {
+    title: "Photo Library Access",
+    message:
+      "We need access to your photo library to let you select and save photos.",
+    icon: "images-outline",
+  },
+  microphone: {
+    title: "Microphone Access",
+    message:
+      "We need access to your microphone for audio recording and voice features.",
+    icon: "mic-outline",
+  },
+  notifications: {
+    title: "Push Notifications",
+    message:
+      "We need permission to send you notifications about important updates and messages.",
+    icon: "notifications-outline",
+  },
+};

package/services/realtime/types.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview WebSocket and real-time communication type definitions
+ * Provides shared types for the WebSocket manager and React hooks.
+ * @module services/realtime/types
+ */
+
+/**
+ * Possible states of a WebSocket connection.
+ * - 'connecting': Initial connection attempt in progress
+ * - 'connected': Connection is open and ready to send/receive
+ * - 'disconnected': Connection is closed (either intentionally or due to error)
+ * - 'reconnecting': Attempting to re-establish a lost connection
+ */
+export type ConnectionStatus =
+  | "connecting"
+  | "connected"
+  | "disconnected"
+  | "reconnecting";
+
+/**
+ * A typed WebSocket message with metadata.
+ * All messages sent or received through the WebSocket system use this envelope.
+ *
+ * @typeParam T - The shape of the message payload
+ */
+export interface WebSocketMessage<T = unknown> {
+  /** Message type identifier (e.g. 'chat:message', 'presence_join') */
+  type: string;
+  /** Optional channel this message belongs to */
+  channel?: string;
+  /** The message payload */
+  payload: T;
+  /** ISO 8601 timestamp of when the message was created */
+  timestamp: string;
+}
+
+/**
+ * Configuration for the WebSocket connection.
+ */
+export interface WebSocketConfig {
+  /** WebSocket server URL (ws:// or wss://) */
+  url: string;
+  /**
+   * Async function that returns an auth token.
+   * If provided, the token is appended as a query parameter on connect.
+   */
+  getToken?: () => Promise<string | null>;
+  /**
+   * Whether to automatically reconnect on unexpected disconnection.
+   * @default true
+   */
+  autoReconnect?: boolean;
+  /**
+   * Maximum number of reconnection attempts before giving up.
+   * @default 10
+   */
+  maxReconnectAttempts?: number;
+  /**
+   * Base delay in milliseconds for exponential backoff reconnection.
+   * The actual delay is `min(baseDelay * 2^attempt, 30000)`.
+   * @default 1000
+   */
+  reconnectBaseDelay?: number;
+  /**
+   * Interval in milliseconds between heartbeat (ping) messages.
+   * @default 30000
+   */
+  heartbeatInterval?: number;
+  /**
+   * Timeout in milliseconds for the initial connection attempt.
+   * @default 10000
+   */
+  connectionTimeout?: number;
+}
+
+/**
+ * Handler callback for typed WebSocket messages.
+ *
+ * @typeParam T - The shape of the message payload
+ */
+export type MessageHandler<T = unknown> = (
+  message: WebSocketMessage<T>
+) => void;
+
+/**
+ * Handler callback for connection status changes.
+ */
+export type StatusHandler = (status: ConnectionStatus) => void;
+
+/**
+ * User presence information for real-time presence tracking.
+ */
+export interface PresenceUser {
+  /** Unique user identifier */
+  id: string;
+  /** Optional display name */
+  name?: string;
+  /** ISO 8601 timestamp of the user's last known activity */
+  lastSeen: string;
+}