@thead-vantage/react 2.3.0 → 2.5.0

package/README.md

@@ -22,20 +22,20 @@ This project uses [`next/font`](https://nextjs.org/docs/app/building-your-applic
 
 ---
 
-## TheAd Vantage Integration - Three Development Modes
+## TheAd Vantage Integration - Development Modes
 
-The TheAd Vantage integration supports three distinct modes of operation:
+The TheAd Vantage integration supports multiple modes of operation to accommodate different development and production scenarios:
 
 ### 1. Production Mode (Default)
 
-**Use Case**: Platform developers using the component in production or their own development environments.
+**Use Case**: Platform developers using the component in production deployments.
 
 **Behavior**: 
-- Connects to `https://thead-vantage.com/api/ads` by default
+- Connects to `https://thead-vantage.com/api/ads`
 - Full tracking enabled (impressions and clicks are recorded)
 - No configuration required
 
-**Configuration**: None needed - this is the default behavior.
+**Configuration**: None needed - this is the default behavior for production deployments.
 
 **Example Usage**:
 ```tsx
@@ -52,9 +52,26 @@ export default function MyPage() {
 }
 ```
 
-### 2. Platform Developer Dev Mode
+### 2. Localhost Development Mode (Automatic)
 
-**Use Case**: Platform developers testing locally with their own platform instance.
+**Use Case**: Platform developers testing locally on `localhost` (any port).
+
+**Behavior**:
+- **Automatically detected** when running on `localhost` (e.g., `localhost:3000`, `localhost:3001`, etc.)
+- Connects to `https://thead-vantage.com/api/ads` (production API)
+- **Dev flags automatically added**: `dev_mode=true`, `no_track=true`, `no_click_track=true`
+- **No tracking**: Impressions and clicks are NOT recorded (prevents polluting production data)
+- Perfect for platform developers testing locally without affecting production metrics
+
+**Configuration**: **No configuration needed!** The library automatically detects localhost and adds dev flags.
+
+**Note**: This mode is automatically used when:
+- Running on `localhost` or `127.0.0.1` (any port)
+- AND `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE` is NOT set to `true`
+
+### 3. Platform Developer Custom API Mode
+
+**Use Case**: Platform developers testing with their own custom platform instance.
 
 **Behavior**:
 - Connects to a custom API URL (your platform's API endpoint)
@@ -86,12 +103,12 @@ NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
 />
 ```
 
-### 3. TheAd Vantage Dev Mode
+### 4. TheAd Vantage Dev Mode
 
-**Use Case**: TheAd Vantage developers testing the component with a local platform instance.
+**Use Case**: TheAd Vantage developers testing the component with a local platform instance running on `localhost:3001`.
 
 **Behavior**:
-- Connects to `http://localhost:3001/api/ads`
+- Connects to `http://localhost:3001/api/ads` (local TheAd Vantage platform)
 - Tracking disabled (impressions and clicks are NOT recorded)
 - Returns mock data if local platform is unavailable
 - Shows dev mode indicators in the UI
@@ -113,6 +130,8 @@ NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true
 />
 ```
 
+**Important**: This mode **overrides** localhost detection. When `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`, the library will always use `localhost:3001` instead of the production API, even if you're running on localhost.
+
 ---
 
 ## Component API
@@ -187,9 +206,13 @@ trackClick(adId);
 
 ### For Platform Developers
 
+**No environment variables needed for localhost development!** The library automatically detects localhost and uses the production API with dev flags (no tracking).
+
+**Optional**: If you want to test with a custom platform instance:
+
 ```env
 # .env.local
-# Optional: Point to your own platform instance
+# Point to your own platform instance (full tracking enabled)
 NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
 ```
 
@@ -198,14 +221,25 @@ NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
 ```env
 # .env.local
 # Enable TheAd Vantage dev mode (uses localhost:3001, disables tracking)
+# This overrides localhost detection and always uses localhost:3001
 NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true
 ```
 
+### Summary Table
+
+| Scenario | API Endpoint | Tracking | Configuration |
+|----------|-------------|----------|--------------|
+| Production deployment | `https://thead-vantage.com/api/ads` | ✅ Enabled | None (default) |
+| Platform dev on localhost | `https://thead-vantage.com/api/ads` | ❌ Disabled (dev flags) | None (auto-detected) |
+| Custom platform URL | Custom URL | ✅ Enabled | `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` |
+| TheAd Vantage dev | `localhost:3001/api/ads` | ❌ Disabled | `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` |
+
 **Priority Order** (highest to lowest):
-1. Explicit `apiUrl` prop in component
-2. `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` environment variable
-3. `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` (uses localhost:3001)
-4. Production mode (default: https://thead-vantage.com/api/ads)
+1. **Explicit `apiUrl` prop** in component (highest priority)
+2. **`NEXT_PUBLIC_THEAD_VANTAGE_API_URL`** environment variable (custom platform)
+3. **`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`** → uses `localhost:3001` (TheAd Vantage developers)
+4. **Localhost detection** → uses `https://thead-vantage.com/api/ads` with dev flags (platform developers on localhost)
+5. **Production mode** (default: `https://thead-vantage.com/api/ads` with full tracking)
 
 ---
 
@@ -226,8 +260,20 @@ The integration includes Next.js API routes that proxy requests to TheAd Vantage
 
 ## Development Mode Features
 
-When in **TheAd Vantage Dev Mode** (`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`):
+### Localhost Development (Automatic)
+
+When running on **localhost** (any port, without `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`):
+
+- ✅ **Production API**: Connects to `https://thead-vantage.com/api/ads`
+- ✅ **No Tracking**: Dev flags automatically added (`dev_mode=true`, `no_track=true`, `no_click_track=true`)
+- ✅ **Real Ads**: Gets real ads from production (but doesn't record impressions/clicks)
+- ✅ **No Configuration**: Automatically detected - no setup needed!
+
+### TheAd Vantage Dev Mode
 
+When **`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`**:
+
+- ✅ **Local API**: Connects to `http://localhost:3001/api/ads`
 - ✅ **No Tracking**: Impressions and clicks are NOT recorded
 - ✅ **Mock Fallback**: If localhost:3001 is unavailable, uses mock ad data
 - ✅ **Dev Indicators**: UI shows "[DEV] No tracking active" message
@@ -261,11 +307,12 @@ Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/bui
 
 ## System Architecture
 
-The TheAd Vantage integration uses a three-mode system to support different development scenarios:
+The TheAd Vantage integration uses a smart mode detection system to support different development scenarios:
 
-1. **Production Mode**: Default behavior, connects to `https://thead-vantage.com/api/ads`
-2. **Platform Developer Dev Mode**: Custom API URL via `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` env var
-3. **TheAd Vantage Dev Mode**: Local development via `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` env var
+1. **Production Mode**: Default behavior, connects to `https://thead-vantage.com/api/ads` with full tracking
+2. **Localhost Development**: Automatically detected, uses `https://thead-vantage.com/api/ads` with dev flags (no tracking)
+3. **Custom Platform Mode**: Custom API URL via `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` env var
+4. **TheAd Vantage Dev Mode**: Local development via `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` env var → uses `localhost:3001`
 
 ## Key Files and Their Purposes
 
@@ -332,9 +379,16 @@ The TheAd Vantage integration uses a three-mode system to support different deve
 The system uses this priority order to determine which API URL to use:
 
 1. **Explicit `apiUrl` prop** (highest priority) - passed directly to component
-2. **`NEXT_PUBLIC_THEAD_VANTAGE_API_URL` env var** - for platform developers
-3. **`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`** - for TheAd Vantage developers (uses localhost:3001)
-4. **Production mode** (lowest priority) - default: https://thead-vantage.com/api/ads
+2. **`NEXT_PUBLIC_THEAD_VANTAGE_API_URL` env var** - for platform developers using custom platform
+3. **`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`** - for TheAd Vantage developers (uses `localhost:3001`)
+4. **Localhost detection** - automatically uses `https://thead-vantage.com/api/ads` with dev flags (no tracking)
+5. **Production mode** (lowest priority) - default: `https://thead-vantage.com/api/ads` with full tracking
+
+**Key Points for AI Agents**:
+- Localhost is automatically detected by checking `window.location.hostname` (browser) or `NODE_ENV === 'development'` (server)
+- When on localhost, dev flags (`dev_mode`, `no_track`, `no_click_track`) are automatically added to requests
+- TheAd Vantage dev mode (`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`) **overrides** localhost detection
+- Platform developers on localhost get real ads from production but don't pollute tracking data
 
 ### Common Patterns
 
@@ -384,11 +438,13 @@ const response = await fetchAdBanner({
 
 When implementing or modifying TheAd Vantage integration:
 
-- [ ] Verify production mode connects to https://thead-vantage.com/api/ads
+- [ ] Verify production mode connects to `https://thead-vantage.com/api/ads` with full tracking
+- [ ] Verify localhost detection automatically uses production API with dev flags (no tracking)
 - [ ] Verify platform dev mode respects `NEXT_PUBLIC_THEAD_VANTAGE_API_URL`
-- [ ] Verify TheAd Vantage dev mode uses localhost:3001 when flag is set
+- [ ] Verify TheAd Vantage dev mode uses `localhost:3001` when flag is set (overrides localhost detection)
+- [ ] Verify tracking is disabled when on localhost (dev flags added automatically)
 - [ ] Verify tracking is disabled in TheAd Vantage dev mode
-- [ ] Verify mock data is returned when platform is unavailable in dev mode
+- [ ] Verify mock data is returned when platform is unavailable in TheAd Vantage dev mode
 - [ ] Verify explicit `apiUrl` prop overrides all other settings
 - [ ] Verify component handles loading states correctly
 - [ ] Verify component handles error states gracefully
@@ -418,12 +474,39 @@ All types are exported from `@/lib/ads` and `@/components/AdBanner`.
 
 ## Quick Reference
 
-**Default Behavior**: Connects to `https://thead-vantage.com/api/ads` (production)
+### For Platform Developers
+
+**Default Behavior**: 
+- Production: Connects to `https://thead-vantage.com/api/ads` with full tracking
+- Localhost: Automatically uses `https://thead-vantage.com/api/ads` with dev flags (no tracking) - **no configuration needed!**
+
+**Optional Custom Platform**: Add `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` to `.env.local` if testing with custom platform
+
+**Component Import**: 
+```tsx
+import { AdBanner } from '@thead-vantage/react';
+// or
+import { AdBanner } from '@thead-vantage/react/components/AdBanner';
+```
+
+**Utility Import**: 
+```tsx
+import { fetchAdBanner, trackImpression, trackClick } from '@thead-vantage/react';
+// or
+import { fetchAdBanner, trackImpression, trackClick } from '@thead-vantage/react/lib/ads';
+```
+
+### For TheAd Vantage Developers
 
-**Platform Developer Setup**: Add `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` to `.env.local`
+**Setup**: Add `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` to `.env.local`
 
-**TheAd Vantage Developer Setup**: Add `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` to `.env.local`
+**Behavior**: Uses `localhost:3001/api/ads` (overrides localhost detection)
 
-**Component Import**: `import { AdBanner } from '@/components/AdBanner';`
+### Common Scenarios
 
-**Utility Import**: `import { fetchAdBanner, trackImpression, trackClick } from '@/lib/ads';`
+| You Are | Running On | API Used | Tracking | Config Needed |
+|---------|-----------|----------|----------|---------------|
+| Platform Developer | Production | `thead-vantage.com` | ✅ Yes | None |
+| Platform Developer | `localhost:3000` | `thead-vantage.com` | ❌ No (dev flags) | None (auto) |
+| Platform Developer | Custom platform | Custom URL | ✅ Yes | `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` |
+| TheAd Vantage Dev | `localhost:3000` | `localhost:3001` | ❌ No | `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thead-vantage/react",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "React components and utilities for TheAd Vantage ad platform integration",
   "main": "./src/index.ts",
   "module": "./src/index.ts",

package/src/components/AdBanner.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useState } from 'react';
 import Image from 'next/image';
-import { fetchAdBanner, trackImpression, trackClick, type Ad } from '@/lib/ads';
+import { fetchAdBanner, trackImpression, trackClick, type Ad } from '../lib/ads';
 
 export interface AdBannerProps {
   platformId: string;

package/src/components/AdDisplay.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useState } from 'react';
 import Image from 'next/image';
-import { fetchAds, trackImpression, trackClick, type AdData } from '@/lib/ads';
+import { fetchAds, trackImpression, trackClick, type AdData } from '../lib/ads';
 
 interface AdDisplayProps {
   position?: string;

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   getApiBaseUrl,
   isTheadVantageDevMode,
   isDevelopmentMode,
+  shouldUseDevFlags,
   setTheadVantageConfig,
   getTheadVantageConfig,
   type TheadVantageConfig,

package/src/lib/ads.ts

@@ -3,7 +3,7 @@
  * Automatically handles development mode to prevent tracking
  */
 
-import { getApiBaseUrl } from './thead-vantage-config';
+import { getApiBaseUrl, shouldUseDevFlags } from './thead-vantage-config';
 
 export interface AdData {
   id: string;
@@ -113,12 +113,25 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
       searchParams.append('user_segment', params.userSegment);
     }
 
-    // Add explicit API URL if provided
-    if (params.apiUrl) {
-      searchParams.append('apiUrl', params.apiUrl);
+    // Get the API base URL (handles dev mode, production, custom URLs)
+    const apiBaseUrl = getApiBaseUrl(params.apiUrl);
+    
+    // Add dev flags if we're in development (localhost but not TheAd Vantage dev mode)
+    // This prevents tracking when platform developers test locally
+    if (shouldUseDevFlags()) {
+      searchParams.set('dev_mode', 'true');
+      searchParams.set('no_track', 'true'); // Prevent impression tracking
+      searchParams.set('no_click_track', 'true'); // Prevent click tracking
     }
-
-    const url = `/api/ads?${searchParams.toString()}`;
+    
+    // Build the full URL - if apiBaseUrl already includes /api/ads, use it directly
+    // Otherwise append /api/ads
+    let fullApiUrl = apiBaseUrl;
+    if (!fullApiUrl.includes('/api/ads')) {
+      fullApiUrl = fullApiUrl.replace(/\/$/, '') + '/api/ads';
+    }
+    
+    const url = `${fullApiUrl}?${searchParams.toString()}`;
     
     // Log the request (without exposing the API key)
     const logUrl = url.replace(new RegExp(`api_key=${params.apiKey}`, 'g'), 'api_key=***');
@@ -128,6 +141,7 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
       method: 'GET',
       headers: {
         'Content-Type': 'application/json',
+        'Accept': 'application/json',
       },
     });
 

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

@@ -1,20 +1,34 @@
 /**
  * TheAd Vantage Configuration Utility
  * 
- * Handles three distinct modes of operation:
- * 1. Production Mode (default) - hits https://thead-vantage.com/api/ads
+ * Handles distinct modes of operation:
+ * 1. Production Mode (default) - hits https://thead-vantage.com/api/ads with full tracking
  * 2. Platform Developer Dev Mode - custom API URL via env var or prop
- * 3. TheAd Vantage Dev Mode - localhost:3001 for TheAd Vantage developers
+ * 3. TheAd Vantage Dev Mode - localhost:3001 for TheAd Vantage developers (NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true)
+ * 4. Localhost Development - hits https://thead-vantage.com/api/ads but with dev flags (no tracking)
  */
 
+/**
+ * Check if we're running on localhost (any port)
+ */
+function isLocalhost(): boolean {
+  if (typeof window !== 'undefined') {
+    const hostname = window.location.hostname;
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+  }
+  // Server-side: check if we're in development mode
+  return process.env.NODE_ENV === 'development';
+}
+
 /**
  * Get the base API URL based on the current configuration
  * 
  * Priority order:
  * 1. Explicit API URL override (passed as parameter)
  * 2. NEXT_PUBLIC_THEAD_VANTAGE_API_URL environment variable
- * 3. TheAd Vantage dev mode (NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true)
- * 4. Production mode (default)
+ * 3. TheAd Vantage dev mode (NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true) → localhost:3001
+ * 4. Localhost detection → https://thead-vantage.com (with dev flags, no tracking)
+ * 5. Production mode (default) → https://thead-vantage.com (full tracking)
  */
 export function getApiBaseUrl(explicitApiUrl?: string): string {
   // Priority 1: Explicit API URL override (highest priority)
@@ -39,18 +53,24 @@ export function getApiBaseUrl(explicitApiUrl?: string): string {
   }
 
   // Priority 3: TheAd Vantage dev mode
-  // Only for TheAd Vantage developers testing locally
-  const isDevMode = typeof window !== 'undefined'
+  // Only for TheAd Vantage developers testing locally with localhost:3001
+  const isTheadVantageDevMode = typeof window !== 'undefined'
     ? (window as any).__THEAD_VANTAGE_DEV_MODE__ === true ||
       process.env.NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE === 'true'
     : process.env.NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE === 'true';
 
-  if (isDevMode) {
+  if (isTheadVantageDevMode) {
     return 'http://localhost:3001/api/ads';
   }
 
-  // Priority 4: Production mode (default)
-  // Platform developers use this by default
+  // Priority 4: Localhost development (platform developers on localhost)
+  // Use production API but will add dev flags to prevent tracking
+  if (isLocalhost()) {
+    return 'https://thead-vantage.com/api/ads';
+  }
+
+  // Priority 5: Production mode (default)
+  // Platform developers use this by default in production
   return 'https://thead-vantage.com/api/ads';
 }
 
@@ -72,6 +92,33 @@ export function isDevelopmentMode(): boolean {
   return process.env.NODE_ENV === 'development';
 }
 
+/**
+ * Check if we should use dev flags (no tracking) even when hitting production API
+ * This is true when:
+ * - Running on localhost (platform developers testing locally)
+ * - OR in TheAd Vantage dev mode
+ * - OR in general development mode
+ */
+export function shouldUseDevFlags(): boolean {
+  // TheAd Vantage dev mode always uses dev flags
+  if (isTheadVantageDevMode()) {
+    return true;
+  }
+  
+  // If on localhost (but not TheAd Vantage dev mode), use dev flags
+  // This means platform developers testing locally won't record impressions
+  if (isLocalhost()) {
+    return true;
+  }
+  
+  // General development mode
+  if (isDevelopmentMode()) {
+    return true;
+  }
+  
+  return false;
+}
+
 /**
  * Runtime configuration interface
  */