@chainloyalty/react 1.0.0

package/src/useTrackEvent.ts

@@ -0,0 +1,273 @@
+/**
+ * @chainloyalty/react - useTrackEvent Hook
+ * 
+ * Purpose:
+ * This hook provides a simple way to track user events in ChainLoyalty.
+ * It automatically captures the connected wallet address and handles:
+ * - Multiple event types (subscription, referral, feature_usage, milestone, purchase)
+ * - Loading, success, and error states
+ * - Toast notifications for user feedback
+ * - Returning structured responses
+ * 
+ * Functionality:
+ * - useTrackEvent: React hook for tracking events within components
+ * - trackEvent: Standalone async function for tracking events programmatically
+ * - Automatic wallet address attachment
+ * - Built-in error handling and user notifications
+ */
+
+import { useState, useCallback } from 'react';
+
+// ============================================================================
+// Types & Interfaces
+// ============================================================================
+
+export type EventType = 'subscription' | 'referral' | 'feature_usage' | 'milestone' | 'purchase';
+
+export interface EventData {
+  type: EventType;
+  metadata?: Record<string, any>;
+  value?: number;
+  description?: string;
+}
+
+export interface TrackEventResponse {
+  success: boolean;
+  eventId?: string;
+  message: string;
+  data?: Record<string, any>;
+  error?: string;
+}
+
+export interface UseTrackEventState {
+  loading: boolean;
+  error: string | null;
+  success: boolean;
+}
+
+// ============================================================================
+// Mock Toast Notification System (Production: replace with your toast library)
+// ============================================================================
+
+const showToast = (message: string, type: 'success' | 'error' = 'success') => {
+  // In production, use react-hot-toast, sonner, or similar
+  console.log(`[${type.toUpperCase()}]`, message);
+  
+  // Create a simple visual toast for demo
+  const toast = document.createElement('div');
+  toast.style.cssText = `
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    padding: 12px 20px;
+    border-radius: 6px;
+    background-color: ${type === 'success' ? '#3FB950' : '#f85149'};
+    color: white;
+    font-size: 14px;
+    font-weight: 500;
+    z-index: 9999;
+    animation: slideInUp 0.3s ease-out;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  `;
+  toast.textContent = message;
+  document.body.appendChild(toast);
+  
+  setTimeout(() => {
+    toast.style.animation = 'slideOutDown 0.3s ease-in';
+    setTimeout(() => toast.remove(), 300);
+  }, 3000);
+};
+
+// ============================================================================
+// Mock API Call Function
+// ============================================================================
+
+const callEventIngestionAPI = async (
+  eventData: EventData & { walletAddress: string }
+): Promise<TrackEventResponse> => {
+  // In production, replace this with actual API call:
+  // return fetch('/api/events/track', {
+  //   method: 'POST',
+  //   headers: { 'Content-Type': 'application/json' },
+  //   body: JSON.stringify(eventData),
+  // }).then(res => res.json());
+
+  // Mock API call with realistic delay
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      const eventId = `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      resolve({
+        success: true,
+        eventId,
+        message: `Event "${eventData.type}" tracked successfully`,
+        data: {
+          type: eventData.type,
+          walletAddress: eventData.walletAddress,
+          timestamp: new Date().toISOString(),
+          eventId,
+        },
+      });
+    }, 500);
+  });
+};
+
+// ============================================================================
+// Standalone trackEvent Function
+// ============================================================================
+
+/**
+ * Standalone function to track an event programmatically.
+ * Can be called outside of React components.
+ * 
+ * @param eventData - Event details (type, metadata, value, description)
+ * @param walletAddress - Connected wallet address (required)
+ * @returns Promise with tracking result
+ */
+export const trackEvent = async (
+  eventData: EventData,
+  walletAddress: string
+): Promise<TrackEventResponse> => {
+  try {
+    if (!walletAddress) {
+      const error = 'Wallet address is required to track events';
+      showToast(error, 'error');
+      return {
+        success: false,
+        message: error,
+        error,
+      };
+    }
+
+    // Validate event type
+    const validEventTypes: EventType[] = [
+      'subscription',
+      'referral',
+      'feature_usage',
+      'milestone',
+      'purchase',
+    ];
+    if (!validEventTypes.includes(eventData.type)) {
+      const error = `Invalid event type: ${eventData.type}`;
+      showToast(error, 'error');
+      return {
+        success: false,
+        message: error,
+        error,
+      };
+    }
+
+    // Call API
+    const response = await callEventIngestionAPI({
+      ...eventData,
+      walletAddress,
+    });
+
+    // Show success notification
+    if (response.success) {
+      showToast(response.message, 'success');
+    } else {
+      showToast(response.message || 'Failed to track event', 'error');
+    }
+
+    return response;
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : 'Failed to track event';
+    showToast(errorMessage, 'error');
+    return {
+      success: false,
+      message: errorMessage,
+      error: errorMessage,
+    };
+  }
+};
+
+// ============================================================================
+// useTrackEvent Hook
+// ============================================================================
+
+/**
+ * React hook for tracking events within components.
+ * Provides loading, error, and success states.
+ * Automatically manages wallet state.
+ * 
+ * @param walletAddress - Connected wallet address (required)
+ * @returns Object with track function and state
+ */
+export const useTrackEvent = (walletAddress: string | null) => {
+  const [state, setState] = useState<UseTrackEventState>({
+    loading: false,
+    error: null,
+    success: false,
+  });
+
+  const track = useCallback(
+    async (eventData: EventData): Promise<TrackEventResponse> => {
+      // Reset state
+      setState({ loading: true, error: null, success: false });
+
+      try {
+        if (!walletAddress) {
+          throw new Error('Wallet not connected. Please connect your wallet first.');
+        }
+
+        // Call tracking function
+        const response = await trackEvent(eventData, walletAddress);
+
+        // Update state based on response
+        if (response.success) {
+          setState({ loading: false, error: null, success: true });
+        } else {
+          setState({
+            loading: false,
+            error: response.error || response.message,
+            success: false,
+          });
+        }
+
+        return response;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+        setState({
+          loading: false,
+          error: errorMessage,
+          success: false,
+        });
+        showToast(errorMessage, 'error');
+        return {
+          success: false,
+          message: errorMessage,
+          error: errorMessage,
+        };
+      }
+    },
+    [walletAddress]
+  );
+
+  return {
+    track,
+    loading: state.loading,
+    error: state.error,
+    success: state.success,
+  };
+};
+
+// ============================================================================
+// Example Usage Hook (for documentation)
+// ============================================================================
+
+/**
+ * Example of how to use useTrackEvent in a component:
+ * 
+ * const { track, loading, error, success } = useTrackEvent(walletAddress);
+ * 
+ * const handlePurchase = async () => {
+ *   const response = await track({
+ *     type: 'purchase',
+ *     value: 99.99,
+ *     description: 'Premium subscription',
+ *     metadata: { productId: 'prod_123' },
+ *   });
+ * };
+ */
+
+export default useTrackEvent;

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "types": ["react/jsx-runtime"]
+  },
+  "include": ["src"]
+}