@thead-vantage/react 2.20.0 → 2.22.0

package/README.md

@@ -154,6 +154,7 @@ The main component for displaying ads from TheAd Vantage.
 | `clickMetadata` | `Record<string, unknown>` | No | - | Optional metadata to send with click tracking events |
 | `impressionMetadata` | `Record<string, unknown>` | No | - | Optional metadata to send with impression tracking events |
 | `showImpressionFinished` | `boolean` | No | `false` | Show spinning checkmark during impression timer (2s), then green checkmark when complete |
+| `development` | `boolean` | No | `false` | Explicitly enable development mode (disables tracking, handles CORS errors gracefully) |
 
 **Example**:
 ```tsx
@@ -262,6 +263,31 @@ The `showImpressionFinished` prop enables a visual indicator that shows when an
 
 This feature is useful for debugging and providing visual feedback that impressions are being tracked correctly.
 
+### Development Mode
+
+The `development` prop explicitly enables development mode, which:
+
+- **Disables tracking**: Impressions and clicks are not recorded (even if the API call succeeds)
+- **Handles CORS gracefully**: CORS errors are logged as warnings instead of breaking the component
+- **Prevents error display**: Network errors don't show error messages to users in development mode
+
+**Use Case**: When developing locally and you can't configure CORS for localhost, use this prop to prevent CORS errors from breaking your development workflow.
+
+**Example**:
+```tsx
+<AdBanner
+  platformId="10"
+  apiKey="abc123xyz"
+  size="banner"
+  development={process.env.NODE_ENV === 'development'}
+/>
+```
+
+**Note**: When `development={true}`, the component will:
+- Automatically skip all tracking (impressions and clicks)
+- Log CORS errors as warnings instead of throwing errors
+- Continue to work even if the API is unreachable (won't show error state)
+
 ### Utility Functions
 
 You can also use the utility functions directly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thead-vantage/react",
-  "version": "2.20.0",
+  "version": "2.22.0",
   "description": "React components and utilities for TheAd Vantage ad platform integration",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
-    "@types/node": "^20",
+    "@types/node": "^20.19.27",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "next": "^16.1.1",

package/src/components/AdBanner.tsx

@@ -1,245 +1,294 @@
-'use client';
-
-import { useEffect, useState, useRef } from 'react';
-import Image from 'next/image';
-import { fetchAdBanner, trackImpression, trackClick, type Ad } from '../lib/ads';
-
-export interface AdBannerProps {
-  platformId: string;
-  apiKey: string;
-  size?: 'leaderboard' | 'medium-rectangle' | 'wide-skyscraper' | 'banner';
-  apiUrl?: string; // Optional explicit API URL override
-  userId?: string | null;
-  userSegment?: string | null;
-  className?: string;
-  clickMetadata?: Record<string, unknown>; // Optional metadata to send with click events
-  impressionMetadata?: Record<string, unknown>; // Optional metadata to send with impression events
-  showImpressionFinished?: boolean; // Show spinning checkmark during impression timer, then green check when complete
-}
-
-export function AdBanner({
-  platformId,
-  apiKey,
-  size = 'banner',
-  apiUrl,
-  userId = null,
-  userSegment = null,
-  className = '',
-  clickMetadata,
-  impressionMetadata,
-  showImpressionFinished = false,
-}: AdBannerProps) {
-  const [ad, setAd] = useState<Ad | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [devMode, setDevMode] = useState(false);
-  const [impressionStatus, setImpressionStatus] = useState<'pending' | 'counting' | 'completed'>('pending');
-  const impressionTimerRef = useRef<NodeJS.Timeout | null>(null);
-  const hasTrackedImpressionRef = useRef<string | null>(null); // Track which ad ID we've already tracked
-
-  useEffect(() => {
-    const loadAd = async () => {
-      try {
-        setLoading(true);
-        setError(null);
-
-        const response = await fetchAdBanner({
-          platformId,
-          apiKey,
-          size,
-          apiUrl,
-          userId,
-          userSegment,
-        });
-
-        // Only log in development mode
-        if (process.env.NODE_ENV === 'development') {
-          console.log('[AdBanner] Processed response:', {
-            success: response.success,
-            hasAd: !!response.ad,
-            devMode: response.dev_mode,
-            message: response.message,
-            _dev_note: response._dev_note,
-            fullResponse: response,
-          });
-        }
-
-        if (response.success && response.ad) {
-          if (process.env.NODE_ENV === 'development') {
-            console.log('[AdBanner] Setting ad:', response.ad);
-          }
-          setAd(response.ad);
-          setDevMode(response.dev_mode || false);
-
-          // Only track impression once per ad - check if we've already tracked this ad ID
-          if (hasTrackedImpressionRef.current !== response.ad.id) {
-            hasTrackedImpressionRef.current = response.ad.id;
-
-            // Start impression timer if showImpressionFinished is enabled
-            if (showImpressionFinished) {
-              setImpressionStatus('counting');
-              // Standard impression timer: 2 seconds of view time
-              impressionTimerRef.current = setTimeout(() => {
-                setImpressionStatus('completed');
-                impressionTimerRef.current = null;
-              }, 2000);
-
-              // Track impression (will be skipped in dev mode)
-              // Note: We don't wait for the API call to complete - the timer determines when to show green check
-              trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata).catch(() => {
-                // Silently handle tracking errors - timer will still complete
-              });
-            } else {
-              // Track impression without timer UI
-              trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata);
-            }
-          }
-        } else {
-          // Create a more detailed error message
-          const errorDetails = [];
-          if (!response.success) errorDetails.push('API returned success=false');
-          if (!response.ad) errorDetails.push('No ad object in response');
-          if (response.message) errorDetails.push(`Message: ${response.message}`);
-          if (response._dev_note) errorDetails.push(`Note: ${response._dev_note}`);
-          
-          const errorMsg = errorDetails.length > 0 
-            ? `No ads available: ${errorDetails.join(', ')}`
-            : 'No ads available';
-          
-          console.error('[AdBanner] No ad available - Full details:', {
-            success: response.success,
-            hasAd: !!response.ad,
-            message: response.message,
-            _dev_note: response._dev_note,
-            fullResponse: response,
-            errorDetails,
-          });
-          setError(errorMsg);
-        }
-      } catch (err) {
-        console.error('[AdBanner] Error fetching ad:', err);
-        
-        // For CORS errors, show user-friendly message but log technical details
-        if (err instanceof Error && err.message.includes('CORS error')) {
-          console.error('[AdBanner] CORS Error Details:', {
-            message: err.message,
-            note: 'This is a server-side configuration issue. The thead-vantage.com server needs to handle OPTIONS requests without redirecting. See CORS_CONFIGURATION.md for implementation details.',
-          });
-          // Show generic message to end users
-          setError('Ad unavailable');
-        } else {
-          // For other errors, show the error message
-          setError(err instanceof Error ? err.message : 'Failed to fetch ad');
-        }
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    loadAd();
-
-    // Cleanup timer on unmount or when dependencies change
-    return () => {
-      if (impressionTimerRef.current) {
-        clearTimeout(impressionTimerRef.current);
-        impressionTimerRef.current = null;
-      }
-      // Reset impression tracking ref when component unmounts or key dependencies change
-      // This allows re-tracking if the ad ID changes (new ad loaded)
-      hasTrackedImpressionRef.current = null;
-    };
-  }, [platformId, apiKey, size, apiUrl, userId, userSegment, showImpressionFinished]);
-
-  const handleClick = () => {
-    if (ad) {
-      trackClick(ad.id, apiKey, apiUrl, clickMetadata);
-      // The link will handle navigation
-    }
-  };
-
-  if (loading) {
-    return (
-      <div className={`flex items-center justify-center bg-gray-100 dark:bg-gray-800 rounded ${className}`}>
-        <span className="text-sm text-gray-500">Loading ad...</span>
-      </div>
-    );
-  }
-
-  if (error || !ad) {
-    return (
-      <div className={`flex items-center justify-center bg-gray-100 dark:bg-gray-800 rounded ${className}`}>
-        <span className="text-sm text-gray-500">{error || 'Ad unavailable'}</span>
-      </div>
-    );
-  }
-
-  return (
-    <div className={`relative ${className}`}>
-      <a
-        href={ad.targetUrl}
-        onClick={handleClick}
-        target="_blank"
-        rel="noopener noreferrer"
-        className="block"
-      >
-        {(ad.type === 'image' || ad.type === 'standard') && ad.contentUrl ? (
-          <Image
-            src={ad.contentUrl}
-            alt={ad.name}
-            width={ad.width || 300}
-            height={ad.height || 250}
-            className="rounded"
-            unoptimized
-          />
-        ) : (
-          <div className="flex items-center justify-center bg-gray-200 dark:bg-gray-700 rounded" style={{ width: ad.width || 300, height: ad.height || 250 }}>
-            <span className="text-sm text-gray-500">Ad content</span>
-          </div>
-        )}
-      </a>
-      {showImpressionFinished && impressionStatus !== 'pending' && (
-        <div className="absolute top-2 right-2">
-          {impressionStatus === 'counting' ? (
-            <svg
-              className="w-5 h-5 text-gray-400 animate-spin"
-              xmlns="http://www.w3.org/2000/svg"
-              fill="none"
-              viewBox="0 0 24 24"
-            >
-              <circle
-                className="opacity-25"
-                cx="12"
-                cy="12"
-                r="10"
-                stroke="currentColor"
-                strokeWidth="4"
-              />
-              <path
-                className="opacity-75"
-                fill="currentColor"
-                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-              />
-            </svg>
-          ) : impressionStatus === 'completed' ? (
-            <svg
-              className="w-5 h-5 text-green-500"
-              xmlns="http://www.w3.org/2000/svg"
-              viewBox="0 0 20 20"
-              fill="currentColor"
-            >
-              <path
-                fillRule="evenodd"
-                d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z"
-                clipRule="evenodd"
-              />
-            </svg>
-          ) : null}
-        </div>
-      )}
-      {devMode && (
-        <p className="text-xs text-gray-500 mt-1">[DEV] No tracking active</p>
-      )}
-    </div>
-  );
-}
-
+'use client';
+
+import { useEffect, useState, useRef } from 'react';
+import Image from 'next/image';
+import { fetchAdBanner, trackImpression, trackClick, type Ad } from '../lib/ads';
+import { setTheadVantageConfig } from '../lib/thead-vantage-config';
+
+export interface AdBannerProps {
+  platformId: string;
+  apiKey: string;
+  size?: 'leaderboard' | 'medium-rectangle' | 'wide-skyscraper' | 'banner';
+  apiUrl?: string; // Optional explicit API URL override
+  userId?: string | null;
+  userSegment?: string | null;
+  className?: string;
+  clickMetadata?: Record<string, unknown>; // Optional metadata to send with click events
+  impressionMetadata?: Record<string, unknown>; // Optional metadata to send with impression events
+  showImpressionFinished?: boolean; // Show spinning checkmark during impression timer, then green check when complete
+  development?: boolean; // Explicitly enable development mode (disables tracking, handles CORS gracefully)
+}
+
+export function AdBanner({
+  platformId,
+  apiKey,
+  size = 'banner',
+  apiUrl,
+  userId = null,
+  userSegment = null,
+  className = '',
+  clickMetadata,
+  impressionMetadata,
+  showImpressionFinished = false,
+  development = false,
+}: AdBannerProps) {
+  const [ad, setAd] = useState<Ad | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [devMode, setDevMode] = useState(false);
+  const [impressionStatus, setImpressionStatus] = useState<'pending' | 'counting' | 'completed'>('pending');
+  const impressionTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const hasTrackedImpressionRef = useRef<string | null>(null); // Track which ad ID we've already tracked
+
+  // Set development mode in config if explicitly enabled
+  useEffect(() => {
+    if (development) {
+      setTheadVantageConfig({ devMode: true });
+    }
+  }, [development]);
+
+  useEffect(() => {
+    const loadAd = async () => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const response = await fetchAdBanner({
+          platformId,
+          apiKey,
+          size,
+          apiUrl,
+          userId,
+          userSegment,
+        });
+
+        // Only log in development mode
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[AdBanner] Processed response:', {
+            success: response.success,
+            hasAd: !!response.ad,
+            devMode: response.dev_mode,
+            message: response.message,
+            _dev_note: response._dev_note,
+            fullResponse: response,
+          });
+        }
+
+        if (response.success && response.ad) {
+          if (process.env.NODE_ENV === 'development') {
+            console.log('[AdBanner] Setting ad:', response.ad);
+          }
+          setAd(response.ad);
+          setDevMode(response.dev_mode || false);
+
+          // Only track impression once per ad - check if we've already tracked this ad ID
+          if (hasTrackedImpressionRef.current !== response.ad.id) {
+            hasTrackedImpressionRef.current = response.ad.id;
+
+            // Start impression timer if showImpressionFinished is enabled
+            if (showImpressionFinished) {
+              setImpressionStatus('counting');
+              // Standard impression timer: 2 seconds of view time
+              impressionTimerRef.current = setTimeout(() => {
+                setImpressionStatus('completed');
+                impressionTimerRef.current = null;
+              }, 2000);
+
+              // Track impression (will be skipped in dev mode)
+              // Note: We don't wait for the API call to complete - the timer determines when to show green check
+              trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata).catch(() => {
+                // Silently handle tracking errors - timer will still complete
+              });
+            } else {
+              // Track impression without timer UI
+              trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata);
+            }
+          }
+        } else {
+          // Create a more detailed error message
+          const errorDetails = [];
+          if (!response.success) errorDetails.push('API returned success=false');
+          if (!response.ad) errorDetails.push('No ad object in response');
+          if (response.message) errorDetails.push(`Message: ${response.message}`);
+          if (response._dev_note) errorDetails.push(`Note: ${response._dev_note}`);
+          
+          const errorMsg = errorDetails.length > 0 
+            ? `No ads available: ${errorDetails.join(', ')}`
+            : 'No ads available';
+          
+          console.error('[AdBanner] No ad available - Full details:', {
+            success: response.success,
+            hasAd: !!response.ad,
+            message: response.message,
+            _dev_note: response._dev_note,
+            fullResponse: response,
+            errorDetails,
+          });
+          setError(errorMsg);
+        }
+      } catch (err) {
+        console.error('[AdBanner] Error fetching ad:', err);
+        
+        // Check if we're on localhost
+        const isLocalhost = typeof window !== 'undefined' && 
+          (window.location.hostname === 'localhost' || 
+           window.location.hostname === '127.0.0.1' || 
+           window.location.hostname === '[::1]');
+        
+        // For CORS errors, handle differently in development mode or localhost
+        if (err instanceof Error && err.message.includes('CORS error')) {
+          if (development || isLocalhost) {
+            // In development mode or localhost, show TheAd Vantage logo as fallback ad
+            console.warn('[AdBanner] CORS error in development mode - showing TheAd Vantage fallback ad. Tracking is disabled.');
+            // Create a fallback ad with TheAd Vantage logo
+            setAd({
+              id: 'thead-vantage-fallback',
+              name: 'TheAd Vantage',
+              type: 'image',
+              contentUrl: '/TheAd-Vantage-Logo.png',
+              targetUrl: 'https://www.thead-vantage.com',
+              width: 300,
+              height: 250,
+            });
+            setDevMode(true);
+            setError(null); // Don't show error in dev mode
+          } else {
+            console.error('[AdBanner] CORS Error Details:', {
+              message: err.message,
+              note: 'This is a server-side configuration issue. The thead-vantage.com server needs to handle OPTIONS requests without redirecting. See CORS_CONFIGURATION.md for implementation details.',
+            });
+            // Show generic message to end users
+            setError('Ad unavailable');
+          }
+        } else {
+          // For other errors, show the error message (unless in development or localhost)
+          if (development || isLocalhost) {
+            console.warn('[AdBanner] Error in development mode - showing TheAd Vantage fallback ad:', err);
+            // Create a fallback ad with TheAd Vantage logo
+            setAd({
+              id: 'thead-vantage-fallback',
+              name: 'TheAd Vantage',
+              type: 'image',
+              contentUrl: '/TheAd-Vantage-Logo.png',
+              targetUrl: 'https://www.thead-vantage.com',
+              width: 300,
+              height: 250,
+            });
+            setDevMode(true);
+            setError(null); // Don't show errors in dev mode
+          } else {
+            setError(err instanceof Error ? err.message : 'Failed to fetch ad');
+          }
+        }
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadAd();
+
+    // Cleanup timer on unmount or when dependencies change
+    return () => {
+      if (impressionTimerRef.current) {
+        clearTimeout(impressionTimerRef.current);
+        impressionTimerRef.current = null;
+      }
+      // Reset impression tracking ref when component unmounts or key dependencies change
+      // This allows re-tracking if the ad ID changes (new ad loaded)
+      hasTrackedImpressionRef.current = null;
+    };
+  }, [platformId, apiKey, size, apiUrl, userId, userSegment, showImpressionFinished, development]);
+
+  const handleClick = () => {
+    if (ad) {
+      trackClick(ad.id, apiKey, apiUrl, clickMetadata);
+      // The link will handle navigation
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className={`flex items-center justify-center bg-gray-100 dark:bg-gray-800 rounded ${className}`}>
+        <span className="text-sm text-gray-500">Loading ad...</span>
+      </div>
+    );
+  }
+
+  if (error || !ad) {
+    return (
+      <div className={`flex items-center justify-center bg-gray-100 dark:bg-gray-800 rounded ${className}`}>
+        <span className="text-sm text-gray-500">{error || 'Ad unavailable'}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`relative ${className}`}>
+      <a
+        href={ad.targetUrl}
+        onClick={handleClick}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="block"
+      >
+        {(ad.type === 'image' || ad.type === 'standard') && ad.contentUrl ? (
+          <Image
+            src={ad.contentUrl}
+            alt={ad.name}
+            width={ad.width || 300}
+            height={ad.height || 250}
+            className="rounded"
+            unoptimized
+          />
+        ) : (
+          <div className="flex items-center justify-center bg-gray-200 dark:bg-gray-700 rounded" style={{ width: ad.width || 300, height: ad.height || 250 }}>
+            <span className="text-sm text-gray-500">Ad content</span>
+          </div>
+        )}
+      </a>
+      {showImpressionFinished && impressionStatus !== 'pending' && (
+        <div className="absolute top-2 right-2">
+          {impressionStatus === 'counting' ? (
+            <svg
+              className="w-5 h-5 text-gray-400 animate-spin"
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 24 24"
+            >
+              <circle
+                className="opacity-25"
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                strokeWidth="4"
+              />
+              <path
+                className="opacity-75"
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+              />
+            </svg>
+          ) : impressionStatus === 'completed' ? (
+            <svg
+              className="w-5 h-5 text-green-500"
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 20 20"
+              fill="currentColor"
+            >
+              <path
+                fillRule="evenodd"
+                d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z"
+                clipRule="evenodd"
+              />
+            </svg>
+          ) : null}
+        </div>
+      )}
+      {devMode && (
+        <p className="text-xs text-gray-500 mt-1">[DEV] No tracking active</p>
+      )}
+    </div>
+  );
+}
+

package/src/lib/ads.ts

@@ -321,8 +321,34 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
         message: data.message || 'No ads available in response',
       };
     } catch (error) {
+      // Check if we're on localhost (client-side only)
+      const isLocalhost = typeof window !== 'undefined' && 
+        (window.location.hostname === 'localhost' || 
+         window.location.hostname === '127.0.0.1' || 
+         window.location.hostname === '[::1]');
+      
       // Handle CORS errors specifically
       if (error instanceof TypeError && (error.message.includes('CORS') || error.message.includes('Failed to fetch'))) {
+        // On localhost, return TheAd Vantage fallback ad instead of throwing
+        if (isLocalhost) {
+          console.warn('[AdBanner] CORS error on localhost - returning TheAd Vantage fallback ad. Tracking is disabled.');
+          return {
+            success: true,
+            dev_mode: true,
+            ad: {
+              id: 'thead-vantage-fallback',
+              name: 'TheAd Vantage',
+              type: 'image',
+              contentUrl: '/TheAd-Vantage-Logo.png',
+              targetUrl: 'https://www.thead-vantage.com',
+              width: 300,
+              height: 250,
+            },
+            message: 'Localhost development: Using TheAd Vantage fallback ad due to CORS',
+            _dev_note: 'CORS error on localhost - showing fallback ad. This is expected in development.',
+          };
+        }
+        
         // Check if this might be a 308 redirect issue
         // Vercel redirects thead-vantage.com → www.thead-vantage.com at edge level
         // This breaks CORS preflight because browsers don't allow redirects on OPTIONS requests

package/src/lib/thead-vantage-config.ts

@@ -148,8 +148,21 @@ export function isDevelopmentMode(): boolean {
  * - Running on localhost (platform developers testing locally)
  * - OR in TheAd Vantage dev mode
  * - OR in general development mode
+ * - OR explicitly set via runtime config (development prop)
  */
 export function shouldUseDevFlags(): boolean {
+  // Check runtime config first (set via development prop)
+  if (typeof window !== 'undefined') {
+    const runtimeDevMode = (window as any).__THEAD_VANTAGE_DEV_MODE__;
+    if (runtimeDevMode === true) {
+      return true;
+    }
+  }
+  // Also check global config
+  if (globalConfig.devMode === true) {
+    return true;
+  }
+
   // TheAd Vantage dev mode always uses dev flags
   if (isTheadVantageDevMode()) {
     return true;