react-native-inapp-inspector 2.2.2 → 2.2.4

package/src/decorators/index.ts

@@ -0,0 +1,184 @@
+// ─── Method & Class Decorators for React Native In-App Inspector ─────────────
+//
+// Clean TypeScript decorators to seamlessly annotate methods, asynchronous actions,
+// and API services with automatic inspection, logging, timing, and error boundaries.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface InspectLogOptions {
+  tag?: string;
+  logArgs?: boolean;
+  logResult?: boolean;
+  logDuration?: boolean;
+}
+
+/**
+ * `@InspectLog`: Automatically logs method execution, arguments, duration, and return values
+ * to the In-App Inspector Console.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @InspectLog({ tag: 'API', logArgs: true, logDuration: true })
+ *   async fetchUser(id: string) {
+ *     return api.get(`/users/${id}`);
+ *   }
+ * }
+ * ```
+ */
+export function InspectLog(options: InspectLogOptions = {}) {
+  const {
+    tag = 'Inspect',
+    logArgs = true,
+    logResult = true,
+    logDuration = true,
+  } = options;
+
+  return function (
+    _target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = function (...args: any[]) {
+      const start = Date.now();
+      const prefix = `[${tag}] ${propertyKey}`;
+
+      if (logArgs && args.length > 0) {
+        console.log(`${prefix} called with arguments:`, ...args);
+      } else {
+        console.log(`${prefix} invoked`);
+      }
+
+      try {
+        const result = originalMethod.apply(this, args);
+
+        if (result && typeof result.then === 'function') {
+          return result
+            .then((asyncResult: any) => {
+              const elapsed = Date.now() - start;
+              if (logResult) {
+                console.log(
+                  `${prefix} resolved${logDuration ? ` in ${elapsed}ms` : ''}:`,
+                  asyncResult,
+                );
+              }
+              return asyncResult;
+            })
+            .catch((err: any) => {
+              const elapsed = Date.now() - start;
+              console.error(
+                `${prefix} rejected${logDuration ? ` in ${elapsed}ms` : ''}:`,
+                err,
+              );
+              throw err;
+            });
+        }
+
+        const elapsed = Date.now() - start;
+        if (logResult) {
+          console.log(
+            `${prefix} returned${logDuration ? ` in ${elapsed}ms` : ''}:`,
+            result,
+          );
+        }
+        return result;
+      } catch (error) {
+        const elapsed = Date.now() - start;
+        console.error(
+          `${prefix} failed${logDuration ? ` in ${elapsed}ms` : ''}:`,
+          error,
+        );
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * `@InspectTrackTime`: Measures and logs execution duration for critical functions.
+ *
+ * @example
+ * ```ts
+ * class FeedManager {
+ *   @InspectTrackTime('Feed Data Processing')
+ *   processFeedItems(items: FeedItem[]) { ... }
+ * }
+ * ```
+ */
+export function InspectTrackTime(label?: string) {
+  return function (
+    _target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+    const metricLabel = label || propertyKey;
+
+    descriptor.value = function (...args: any[]) {
+      const start = Date.now();
+      try {
+        const result = originalMethod.apply(this, args);
+        if (result && typeof result.then === 'function') {
+          return result.finally(() => {
+            const duration = Date.now() - start;
+            console.log(`[PERF] ⚡ ${metricLabel} took ${duration}ms`);
+          });
+        }
+        const duration = Date.now() - start;
+        console.log(`[PERF] ⚡ ${metricLabel} took ${duration}ms`);
+        return result;
+      } catch (err) {
+        const duration = Date.now() - start;
+        console.error(`[PERF] ⚡ ${metricLabel} failed after ${duration}ms:`, err);
+        throw err;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * `@InspectCatch`: Safely catches unhandled exceptions thrown inside the method,
+ * logs them to the In-App Inspector, and returns a fallback value.
+ *
+ * @example
+ * ```ts
+ * class AuthService {
+ *   @InspectCatch({ fallback: null, tag: 'AUTH' })
+ *   async getCachedToken() { ... }
+ * }
+ * ```
+ */
+export function InspectCatch(options: { fallback?: any; tag?: string } = {}) {
+  const { fallback = undefined, tag = 'Catch' } = options;
+
+  return function (
+    _target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = function (...args: any[]) {
+      try {
+        const result = originalMethod.apply(this, args);
+        if (result && typeof result.then === 'function') {
+          return result.catch((err: any) => {
+            console.error(`[${tag}] Error caught in ${propertyKey}:`, err);
+            return fallback;
+          });
+        }
+        return result;
+      } catch (err) {
+        console.error(`[${tag}] Error caught in ${propertyKey}:`, err);
+        return fallback;
+      }
+    };
+
+    return descriptor;
+  };
+}

package/src/helpers/gaAnalyticsRegistry.ts

@@ -0,0 +1,204 @@
+// ─── Google Analytics (GA4) & Firebase Analytics Dynamic Registry ─────────────
+//
+// Dynamically inspects GA4 / Firebase Analytics runtime schemas, auto-detects
+// standard GA4 event taxonomies, and supports dynamic GA plugins.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {GAEventCategory} from '../types/enums';
+
+export {GAEventCategory};
+
+export interface GAPlugin {
+  name: string;
+  resolveCategory?: (
+    eventName: string,
+    params?: Record<string, any>,
+  ) => GAEventCategory | string | null | undefined;
+}
+
+// ─── Official GA4 & Firebase Standard Event Sets ─────────────────────────────
+
+const GA4_PAGE_VIEW_EVENTS = new Set([
+  'screen_view',
+  'page_view',
+  'screen_active',
+  'screen_inactive',
+  'view_search_results',
+  'search',
+]);
+
+const GA4_ECOMMERCE_EVENTS = new Set([
+  'purchase',
+  'refund',
+  'add_to_cart',
+  'remove_from_cart',
+  'view_cart',
+  'begin_checkout',
+  'add_shipping_info',
+  'add_payment_info',
+  'view_item',
+  'view_item_list',
+  'select_item',
+  'select_promotion',
+  'view_promotion',
+  'add_to_wishlist',
+  'generate_lead',
+  'in_app_purchase',
+  'earn_virtual_currency',
+  'spend_virtual_currency',
+  'join_group',
+  'level_up',
+  'level_start',
+  'level_end',
+  'post_score',
+  'select_content',
+  'tutorial_begin',
+  'tutorial_complete',
+  'unlock_achievement',
+]);
+
+const GA4_SYSTEM_EVENTS = new Set([
+  'first_open',
+  'first_visit',
+  'session_start',
+  'user_engagement',
+  'app_clear_data',
+  'app_exception',
+  'app_remove',
+  'app_store_refund',
+  'app_store_subscription_cancel',
+  'app_store_subscription_convert',
+  'app_store_subscription_renew',
+  'app_update',
+  'os_update',
+  'notification_receive',
+  'notification_open',
+  'notification_dismiss',
+  'notification_foreground',
+  'dynamic_link_first_open',
+  'dynamic_link_app_open',
+  'dynamic_link_app_update',
+  'ad_impression',
+  'ad_click',
+  'ad_reward',
+  'ad_query',
+  'ad_exposure',
+]);
+
+// ─── Registered Dynamic Plugins ──────────────────────────────────────────────
+
+const registeredPlugins: GAPlugin[] = [];
+
+/**
+ * Register a dynamic Google Analytics / Firebase plugin or custom resolver.
+ */
+export const registerGAPlugin = (plugin: GAPlugin): void => {
+  if (!registeredPlugins.some(p => p.name === plugin.name)) {
+    registeredPlugins.push(plugin);
+  }
+};
+
+/**
+ * Attempt dynamic inspection of host runtime Firebase / Google Analytics modules.
+ */
+const tryInspectRuntimeFirebaseAnalytics = (): void => {
+  try {
+    const firebaseAnalytics = require('@react-native-firebase/analytics');
+    const mod = firebaseAnalytics?.default || firebaseAnalytics;
+    if (mod?.EventNames) {
+      Object.keys(mod.EventNames).forEach(k => {
+        const val = mod.EventNames[k]?.toLowerCase();
+        if (val) {
+          if (
+            val.includes('cart') ||
+            val.includes('checkout') ||
+            val.includes('purchase') ||
+            val.includes('item')
+          ) {
+            GA4_ECOMMERCE_EVENTS.add(val);
+          } else if (val.includes('screen') || val.includes('page')) {
+            GA4_PAGE_VIEW_EVENTS.add(val);
+          }
+        }
+      });
+    }
+  } catch {
+    // Optional dependency - safe fallback to built-in GA4 taxonomy
+  }
+};
+
+// Initialize dynamic runtime inspection once
+tryInspectRuntimeFirebaseAnalytics();
+
+/**
+ * Dynamically resolves the GA4 event category using:
+ * 1. Registered dynamic GA plugins
+ * 2. Runtime Firebase Analytics inspection
+ * 3. GA4 standard event taxonomies (O(1) Set lookup)
+ * 4. Semantic pattern & prefix analysis
+ */
+export const getEventCategory = (
+  name: string,
+  params?: Record<string, any>,
+): GAEventCategory => {
+  if (!name || typeof name !== 'string') return 'custom';
+  const cleanName = name.trim().toLowerCase();
+
+  // 1. Run through registered dynamic plugins
+  for (const plugin of registeredPlugins) {
+    if (plugin.resolveCategory) {
+      const category = plugin.resolveCategory(cleanName, params);
+      if (category) return category as GAEventCategory;
+    }
+  }
+
+  // 2. Exact GA4 taxonomy matching (O(1))
+  if (GA4_PAGE_VIEW_EVENTS.has(cleanName)) {
+    return 'page_view';
+  }
+
+  if (GA4_ECOMMERCE_EVENTS.has(cleanName)) {
+    return 'ecommerce';
+  }
+
+  if (GA4_SYSTEM_EVENTS.has(cleanName)) {
+    return 'system';
+  }
+
+  // 3. Prefix & namespace detection
+  if (
+    cleanName.startsWith('firebase_') ||
+    cleanName.startsWith('ga_') ||
+    cleanName.startsWith('gtag_') ||
+    cleanName.startsWith('_') ||
+    cleanName.startsWith('google_')
+  ) {
+    return 'system';
+  }
+
+  // 4. Semantic pattern matching
+  if (
+    cleanName.endsWith('_view') ||
+    cleanName.endsWith('_screen') ||
+    cleanName.startsWith('screen_') ||
+    cleanName.startsWith('page_') ||
+    cleanName.includes('screen_view') ||
+    cleanName.includes('page_view')
+  ) {
+    return 'page_view';
+  }
+
+  if (
+    cleanName.includes('cart') ||
+    cleanName.includes('checkout') ||
+    cleanName.includes('purchase') ||
+    cleanName.includes('payment') ||
+    cleanName.includes('order') ||
+    cleanName.includes('refund') ||
+    cleanName.includes('shipping')
+  ) {
+    return 'ecommerce';
+  }
+
+  return 'custom';
+};