@croacroa/react-native-template 2.0.1 → 3.2.0

package/services/feature-flags/adapters/mock.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Mock feature flag adapter for development
+ * Provides an in-memory flag store with configurable initial values.
+ * Use this adapter during development to test feature gates and experiments
+ * without a remote provider.
+ * @module services/feature-flags/adapters/mock
+ */
+
+import type { FeatureFlagAdapter } from "../types";
+
+// ============================================================================
+// Mock Adapter
+// ============================================================================
+
+/**
+ * Development adapter that stores flags and experiments in memory.
+ * Flags can be pre-seeded via the constructor or changed at runtime with
+ * the `setFlag()` and `setExperiment()` helpers -- useful for unit tests.
+ */
+export class MockFeatureFlagAdapter implements FeatureFlagAdapter {
+  /** In-memory flag store */
+  private flags: Map<string, unknown> = new Map();
+
+  /** In-memory experiment assignments */
+  private experiments: Map<string, string> = new Map();
+
+  /**
+   * Create a mock adapter with optional initial data.
+   *
+   * @param initialFlags - Pre-seeded flag key-value pairs
+   * @param initialExperiments - Pre-seeded experiment assignments
+   */
+  constructor(
+    initialFlags?: Record<string, unknown>,
+    initialExperiments?: Record<string, string>
+  ) {
+    if (initialFlags) {
+      for (const [key, value] of Object.entries(initialFlags)) {
+        this.flags.set(key, value);
+      }
+    }
+
+    if (initialExperiments) {
+      for (const [key, variant] of Object.entries(initialExperiments)) {
+        this.experiments.set(key, variant);
+      }
+    }
+  }
+
+  async initialize(): Promise<void> {
+    if (__DEV__) {
+      console.log(
+        `[FeatureFlags] Initialized (mock adapter — ${this.flags.size} flags, ${this.experiments.size} experiments)`
+      );
+    }
+  }
+
+  isEnabled(flag: string): boolean {
+    const value = this.flags.get(flag);
+    return typeof value === "boolean" ? value : false;
+  }
+
+  getValue<T>(flag: string, defaultValue: T): T {
+    if (!this.flags.has(flag)) return defaultValue;
+    return this.flags.get(flag) as T;
+  }
+
+  getExperimentVariant(experimentId: string): string | null {
+    return this.experiments.get(experimentId) ?? null;
+  }
+
+  identify(userId: string, attributes?: Record<string, unknown>): void {
+    if (__DEV__) {
+      console.log("[FeatureFlags] Identified user:", userId, attributes);
+    }
+  }
+
+  async refresh(): Promise<void> {
+    if (__DEV__) {
+      console.log("[FeatureFlags] Refreshed (mock adapter — no-op)");
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Test helpers
+  // --------------------------------------------------------------------------
+
+  /**
+   * Set or update a flag value at runtime.
+   * Useful for toggling flags during tests.
+   *
+   * @param flag - The flag key
+   * @param value - The value to set
+   */
+  setFlag(flag: string, value: unknown): void {
+    this.flags.set(flag, value);
+  }
+
+  /**
+   * Set or update an experiment assignment at runtime.
+   *
+   * @param experimentId - The experiment identifier
+   * @param variant - The variant name to assign
+   */
+  setExperiment(experimentId: string, variant: string): void {
+    this.experiments.set(experimentId, variant);
+  }
+}

package/services/feature-flags/feature-flag-adapter.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Feature flag adapter manager
+ * Singleton-style module that delegates all feature flag and A/B testing calls
+ * to a pluggable adapter. Defaults to the mock adapter so flag checks work out
+ * of the box in development without any extra setup.
+ *
+ * Usage:
+ *   import { FeatureFlags } from "@/services/feature-flags/feature-flag-adapter";
+ *
+ *   // Swap the adapter for production (e.g. LaunchDarkly)
+ *   FeatureFlags.setAdapter(new LaunchDarklyAdapter());
+ *
+ *   // Initialize at app start
+ *   await FeatureFlags.initialize();
+ *
+ *   // Check a flag
+ *   if (FeatureFlags.isEnabled("new_checkout")) { ... }
+ *
+ * @module services/feature-flags/feature-flag-adapter
+ */
+
+import type { FeatureFlagAdapter } from "./types";
+import { MockFeatureFlagAdapter } from "./adapters/mock";
+import { FEATURE_FLAGS } from "@/constants/config";
+
+// ============================================================================
+// Module-level state
+// ============================================================================
+
+/** The currently active feature flag adapter */
+let activeAdapter: FeatureFlagAdapter = new MockFeatureFlagAdapter();
+
+/** Handle for the auto-refresh interval, if running */
+let refreshInterval: ReturnType<typeof setInterval> | null = null;
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Central feature flags facade.
+ *
+ * Every method delegates to the active adapter so the underlying provider
+ * can be swapped without touching calling code.
+ */
+export const FeatureFlags = {
+  // --------------------------------------------------------------------------
+  // Configuration
+  // --------------------------------------------------------------------------
+
+  /**
+   * Replace the active feature flag adapter.
+   * Call this before `initialize()` to switch providers.
+   */
+  setAdapter(adapter: FeatureFlagAdapter): void {
+    activeAdapter = adapter;
+
+    if (__DEV__) {
+      console.log("[FeatureFlags] Adapter set:", adapter.constructor.name);
+    }
+  },
+
+  // --------------------------------------------------------------------------
+  // Lifecycle
+  // --------------------------------------------------------------------------
+
+  /** Initialize the active adapter. Should be called once at app start. */
+  async initialize(): Promise<void> {
+    if (!FEATURE_FLAGS.ENABLED) return;
+    await activeAdapter.initialize();
+  },
+
+  // --------------------------------------------------------------------------
+  // Flag evaluation
+  // --------------------------------------------------------------------------
+
+  /**
+   * Check whether a boolean feature flag is enabled.
+   *
+   * @param flag - The flag key
+   * @param defaultValue - Value to return when the adapter has no data
+   * @returns `true` if the flag is enabled
+   */
+  isEnabled(flag: string, defaultValue = false): boolean {
+    if (!FEATURE_FLAGS.ENABLED) return defaultValue;
+    return activeAdapter.isEnabled(flag);
+  },
+
+  /**
+   * Get the value of a feature flag with an arbitrary type.
+   *
+   * @param flag - The flag key
+   * @param defaultValue - Value to return when the flag is missing
+   * @returns The flag value or the default
+   */
+  getValue<T>(flag: string, defaultValue: T): T {
+    if (!FEATURE_FLAGS.ENABLED) return defaultValue;
+    return activeAdapter.getValue(flag, defaultValue);
+  },
+
+  // --------------------------------------------------------------------------
+  // Experiments
+  // --------------------------------------------------------------------------
+
+  /**
+   * Get the assigned variant for an A/B test experiment.
+   *
+   * @param experimentId - The experiment identifier
+   * @returns The variant name or `null` if the user is not enrolled
+   */
+  getExperimentVariant(experimentId: string): string | null {
+    if (!FEATURE_FLAGS.ENABLED) return null;
+    return activeAdapter.getExperimentVariant(experimentId);
+  },
+
+  // --------------------------------------------------------------------------
+  // User targeting
+  // --------------------------------------------------------------------------
+
+  /**
+   * Identify the current user for targeted flag evaluation.
+   *
+   * @param userId - Unique identifier for the user
+   * @param attributes - Optional targeting attributes
+   */
+  identify(userId: string, attributes?: Record<string, unknown>): void {
+    if (!FEATURE_FLAGS.ENABLED) return;
+    activeAdapter.identify(userId, attributes);
+  },
+
+  // --------------------------------------------------------------------------
+  // Refresh
+  // --------------------------------------------------------------------------
+
+  /** Refresh flag values from the remote provider. */
+  async refresh(): Promise<void> {
+    if (!FEATURE_FLAGS.ENABLED) return;
+    await activeAdapter.refresh();
+  },
+
+  /**
+   * Start auto-refreshing flags at the interval defined in config.
+   * Calls `refresh()` on the active adapter periodically.
+   */
+  startAutoRefresh(): void {
+    if (refreshInterval) return; // already running
+
+    refreshInterval = setInterval(() => {
+      activeAdapter.refresh().catch((err) => {
+        if (__DEV__) {
+          console.warn("[FeatureFlags] Auto-refresh failed:", err);
+        }
+      });
+    }, FEATURE_FLAGS.REFRESH_INTERVAL_MS);
+
+    if (__DEV__) {
+      console.log(
+        `[FeatureFlags] Auto-refresh started (every ${FEATURE_FLAGS.REFRESH_INTERVAL_MS}ms)`
+      );
+    }
+  },
+
+  /** Stop the auto-refresh interval. */
+  stopAutoRefresh(): void {
+    if (refreshInterval) {
+      clearInterval(refreshInterval);
+      refreshInterval = null;
+
+      if (__DEV__) {
+        console.log("[FeatureFlags] Auto-refresh stopped");
+      }
+    }
+  },
+};

package/services/feature-flags/types.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Feature flag and A/B testing type definitions
+ * Defines the adapter interface and configuration for the feature flag system.
+ * @module services/feature-flags/types
+ */
+
+// ============================================================================
+// Adapter Interface
+// ============================================================================
+
+/**
+ * Interface that all feature flag adapters must implement.
+ * Swap adapters to switch between providers (LaunchDarkly, Statsig, etc.)
+ * without changing application code.
+ */
+export interface FeatureFlagAdapter {
+  /**
+   * Initialize the feature flag provider.
+   * Called once when the app starts.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Check whether a boolean feature flag is enabled.
+   *
+   * @param flag - The flag key (e.g. "new_onboarding")
+   * @returns `true` if the flag is enabled, `false` otherwise
+   */
+  isEnabled(flag: string): boolean;
+
+  /**
+   * Get the value of a feature flag with an arbitrary type.
+   * Returns the provided default when the flag is not found.
+   *
+   * @param flag - The flag key
+   * @param defaultValue - Value to return if the flag is missing
+   * @returns The flag value or the default
+   */
+  getValue<T>(flag: string, defaultValue: T): T;
+
+  /**
+   * Get the assigned variant for an A/B test experiment.
+   *
+   * @param experimentId - The experiment identifier
+   * @returns The variant name (e.g. "control", "variant_a") or `null` if the
+   *          user is not enrolled
+   */
+  getExperimentVariant(experimentId: string): string | null;
+
+  /**
+   * Identify the current user so the provider can return
+   * user-targeted flags and experiments.
+   *
+   * @param userId - Unique identifier for the user
+   * @param attributes - Optional targeting attributes (plan, country, etc.)
+   */
+  identify(userId: string, attributes?: Record<string, unknown>): void;
+
+  /**
+   * Refresh flag values from the remote provider.
+   */
+  refresh(): Promise<void>;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Runtime configuration for the feature flag system.
+ */
+export interface FeatureFlagConfig {
+  /** Whether feature flag evaluation is enabled */
+  enabled: boolean;
+  /** How often (in ms) to auto-refresh flags from the remote provider */
+  refreshIntervalMs: number;
+  /** Whether to log debug information to the console */
+  debug: boolean;
+}

package/services/force-update.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Force update service for mandatory native app updates
+ * Checks a remote endpoint for the minimum required app version and
+ * determines whether the user must update before continuing.
+ * @module services/force-update
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ForceUpdateConfig {
+  /** API endpoint that returns { minimumVersion, storeUrl } */
+  checkUrl: string;
+  /** The currently running app version (e.g. "1.2.3") */
+  currentVersion: string;
+}
+
+export interface ForceUpdateResponse {
+  /** Minimum version the server requires */
+  minimumVersion: string;
+  /** App Store or Play Store URL for the update */
+  storeUrl: string;
+}
+
+export interface ForceUpdateResult {
+  /** Whether the user must update before using the app */
+  isUpdateRequired: boolean;
+  /** The version currently running */
+  currentVersion: string;
+  /** The minimum version required by the server */
+  minimumVersion: string;
+  /** Store URL to open for the update */
+  storeUrl: string;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Compare two semver-style version strings segment by segment.
+ * Returns true when `current` is older than `minimum`.
+ *
+ * @example
+ * isVersionLessThan("1.2.3", "1.3.0") // true
+ * isVersionLessThan("2.0.0", "1.9.9") // false
+ * isVersionLessThan("1.2.3", "1.2.3") // false
+ */
+export function isVersionLessThan(current: string, minimum: string): boolean {
+  const currentParts = current.split(".").map(Number);
+  const minimumParts = minimum.split(".").map(Number);
+
+  const length = Math.max(currentParts.length, minimumParts.length);
+
+  for (let i = 0; i < length; i++) {
+    const curr = currentParts[i] ?? 0;
+    const min = minimumParts[i] ?? 0;
+
+    if (curr < min) return true;
+    if (curr > min) return false;
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+const NO_UPDATE_RESULT: ForceUpdateResult = {
+  isUpdateRequired: false,
+  currentVersion: "",
+  minimumVersion: "",
+  storeUrl: "",
+};
+
+/**
+ * Check whether the app needs a mandatory native update.
+ *
+ * Fetches the `checkUrl`, compares the server-provided `minimumVersion`
+ * against `currentVersion` using semver-style comparison, and returns the
+ * result.
+ *
+ * - If `FORCE_UPDATE.ENABLED` is false or `CHECK_URL` is empty the caller
+ *   should skip the call entirely (handled in the hook).
+ * - Network / parsing errors are swallowed and return `isUpdateRequired: false`
+ *   so the app is never blocked by a transient failure.
+ *
+ * @param config - The force update configuration
+ * @returns The result of the version check
+ *
+ * @example
+ * ```ts
+ * const result = await checkForUpdate({
+ *   checkUrl: "https://api.example.com/app/version",
+ *   currentVersion: "1.0.0",
+ * });
+ *
+ * if (result.isUpdateRequired) {
+ *   // Show force-update screen
+ * }
+ * ```
+ */
+export async function checkForUpdate(
+  config: ForceUpdateConfig
+): Promise<ForceUpdateResult> {
+  const { checkUrl, currentVersion } = config;
+
+  if (!checkUrl) {
+    return NO_UPDATE_RESULT;
+  }
+
+  try {
+    const response = await fetch(checkUrl);
+
+    if (!response.ok) {
+      return NO_UPDATE_RESULT;
+    }
+
+    const data: ForceUpdateResponse = await response.json();
+    const { minimumVersion, storeUrl } = data;
+
+    if (!minimumVersion || !storeUrl) {
+      return NO_UPDATE_RESULT;
+    }
+
+    const isUpdateRequired = isVersionLessThan(currentVersion, minimumVersion);
+
+    return {
+      isUpdateRequired,
+      currentVersion,
+      minimumVersion,
+      storeUrl,
+    };
+  } catch {
+    // Network errors, JSON parse errors, etc. — never block the app.
+    return NO_UPDATE_RESULT;
+  }
+}

package/services/index.ts

@@ -1,54 +1,116 @@
-export { api, ApiClient } from "./api";
-export { storage, secureStorage } from "./storage";
-export {
-  initSentry,
-  captureException,
-  captureMessage,
-  setUser,
-  addBreadcrumb,
-} from "./sentry";
-export { authAdapter, mockAuthAdapter } from "./authAdapter";
-export type { AuthAdapter, AuthResult, AuthError } from "./authAdapter";
-export {
-  analytics,
-  track,
-  identify,
-  screen,
-  resetAnalytics,
-  setUserProperties,
-  trackRevenue,
-  AnalyticsEvents,
-} from "./analytics";
-export type { AnalyticsAdapter, AnalyticsEvent } from "./analytics";
-export {
-  getCertificatePins,
-  isSslPinningEnabled,
-  getSecurityHeaders,
-  isUrlAllowed,
-  sanitizeInput,
-  checkSecurityEnvironment,
-  SSL_PINNING_CONFIG,
-} from "./security";
-export {
-  queueMutation,
-  getMutationQueue,
-  removeMutation,
-  clearMutationQueue,
-  getPendingMutationCount,
-  processQueue,
-  registerBackgroundSync,
-  unregisterBackgroundSync,
-  isBackgroundSyncRegistered,
-  getBackgroundSyncStatus,
-  isNetworkError,
-  registerConflictResolver,
-  unregisterConflictResolver,
-  getPendingConflicts,
-  clearPendingConflict,
-} from "./backgroundSync";
-export type {
-  QueuedMutation,
-  ConflictResolutionStrategy,
-  SyncConflict,
-  ConflictResolver,
-} from "./backgroundSync";
+export { api, ApiClient } from "./api";
+export { storage, secureStorage } from "./storage";
+export {
+  initSentry,
+  captureException,
+  captureMessage,
+  setUser,
+  addBreadcrumb,
+} from "./sentry";
+export { authAdapter, mockAuthAdapter } from "./authAdapter";
+export type { AuthAdapter, AuthResult, AuthError } from "./authAdapter";
+export {
+  analytics,
+  track,
+  identify,
+  screen,
+  resetAnalytics,
+  setUserProperties,
+  trackRevenue,
+  AnalyticsEvents,
+} from "./analytics";
+export type { AnalyticsAdapter, AnalyticsEvent } from "./analytics";
+export {
+  getCertificatePins,
+  isSslPinningEnabled,
+  getSecurityHeaders,
+  isUrlAllowed,
+  sanitizeInput,
+  checkSecurityEnvironment,
+  SSL_PINNING_CONFIG,
+} from "./security";
+export {
+  queueMutation,
+  getMutationQueue,
+  removeMutation,
+  clearMutationQueue,
+  getPendingMutationCount,
+  processQueue,
+  registerBackgroundSync,
+  unregisterBackgroundSync,
+  isBackgroundSyncRegistered,
+  getBackgroundSyncStatus,
+  isNetworkError,
+  registerConflictResolver,
+  unregisterConflictResolver,
+  getPendingConflicts,
+  clearPendingConflict,
+} from "./backgroundSync";
+export type {
+  QueuedMutation,
+  ConflictResolutionStrategy,
+  SyncConflict,
+  ConflictResolver,
+} from "./backgroundSync";
+export {
+  PermissionManager,
+  normalizeStatus,
+} from "./permissions/permission-manager";
+export { DEFAULT_PERMISSION_CONFIGS } from "./permissions/types";
+export type {
+  PermissionType,
+  PermissionStatus,
+  PermissionResult,
+  PermissionConfig,
+} from "./permissions/types";
+export { Analytics } from "./analytics/analytics-adapter";
+export { ConsoleAnalyticsAdapter } from "./analytics/adapters/console";
+export type {
+  AnalyticsAdapter as AnalyticsAdapterInterface,
+  AnalyticsConfig,
+} from "./analytics/types";
+export { Payments } from "./payments/payment-adapter";
+export { MockPaymentAdapter, MOCK_PRODUCTS } from "./payments/adapters/mock";
+export type {
+  PaymentAdapter,
+  Product,
+  Purchase,
+  ProductType,
+  SubscriptionPeriod,
+  SubscriptionStatus,
+  SubscriptionInfo,
+} from "./payments/types";
+export { pickFromLibrary, pickFromCamera } from "./media/media-picker";
+export type { PickedMedia, PickOptions } from "./media/media-picker";
+export { compressImage } from "./media/compression";
+export type {
+  CompressionOptions,
+  CompressionResult,
+} from "./media/compression";
+export { uploadFile } from "./media/media-upload";
+export type {
+  UploadProgress,
+  UploadOptions,
+  UploadResult,
+} from "./media/media-upload";
+export { WebSocketManager } from "./realtime/websocket-manager";
+export type {
+  ConnectionStatus,
+  WebSocketConfig,
+  WebSocketMessage,
+  MessageHandler,
+  StatusHandler,
+  PresenceUser,
+} from "./realtime/types";
+export { checkForUpdate, isVersionLessThan } from "./force-update";
+export type {
+  ForceUpdateConfig,
+  ForceUpdateResponse,
+  ForceUpdateResult,
+} from "./force-update";
+export { FeatureFlags } from "./feature-flags/feature-flag-adapter";
+export { MockFeatureFlagAdapter } from "./feature-flags/adapters/mock";
+export type {
+  FeatureFlagAdapter,
+  FeatureFlagConfig,
+} from "./feature-flags/types";