@thead-vantage/react 2.1.0 → 2.1.2

package/README.md

@@ -1,84 +1,429 @@
-# @thead-vantage/react
-
-React component library for TheAd Vantage advertising platform.
-
-## Installation
-
-```bash
-npm install @thead-vantage/react
-```
-
-## Usage
-
-```tsx
-import { AdBanner } from "@thead-vantage/react"
-
-function App() {
-    return (
-        <AdBanner
-            apiKey="your-api-key"
-            platformId="your-platform-id"
-            size="banner"
-            userId="user123" // Optional: Platform-specific user ID
-            userSegment="premium" // Optional: User segment/category
-            viewabilityThreshold={50} // Optional: Percentage of ad that must be visible (default: 50%)
-            viewabilityTimeThreshold={1000} // Optional: Time in ms that ad must be visible (default: 1000ms)
-            onImpression={(data) => {
-                console.log("Ad impression recorded:", data)
-                // data.viewability contains detailed viewability metrics
-            }}
-            onClick={(data) => {
-                console.log("Ad clicked:", data)
-            }}
-        />
-    )
-}
-```
-
-## Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `apiKey` | string | Yes | Your platform's API key |
-| `platformId` | string | No | Your platform ID (default: "1") |
-| `size` | "banner" \| "sidebar" \| "leaderboard" | No | Ad size (default: "banner") |
-| `className` | string | No | Additional CSS classes |
-| `userId` | string | No | Platform-specific user ID for tracking |
-| `userSegment` | string | No | User segment/category for targeting |
-| `viewabilityThreshold` | number | No | Percentage of ad that must be visible to count as viewed (default: 50) |
-| `viewabilityTimeThreshold` | number | No | Time in milliseconds that ad must be visible to count as viewed (default: 1000) |
-| `onImpression` | (data: { campaignId: string; platformId: string; userId?: string; viewability: ViewabilityMetrics }) => void | No | Callback when ad impression is recorded |
-| `onClick` | (data: { campaignId: string; platformId: string; userId?: string }) => void | No | Callback when ad is clicked |
-
-## Viewability Tracking
-
-The component implements IAB/MRC viewability standards:
-
-- Tracks when the ad is visible in the viewport
-- Measures the percentage of the ad that is visible
-- Records the total time the ad is visible
-- Only counts impressions when both visibility percentage and time thresholds are met
-- Provides detailed viewability metrics in the impression callback
-
-## Features
-
-- Multiple ad sizes (banner, sidebar, leaderboard)
-- User tracking and targeting
-- Impression and click tracking
-- Viewability tracking (IAB/MRC compliant)
-- Support for image and video ads
-- Responsive design
-- Loading and error states
-- Customizable styling
-- Lazy loading of images
-- Automatic cleanup of observers and timers
-
-## Ad Sizes
-
-- Banner: Full width, 90px height
-- Sidebar: 300px width, 250px height
-- Leaderboard: Full width, 250px height
-
-## License
-
-MIT
+# TheAd Vantage React Library
+
+This is a [Next.js](https://nextjs.org) project that integrates with TheAd Vantage platform for ad serving. The integration supports three distinct development modes to accommodate different development and production scenarios.
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+---
+
+## TheAd Vantage Integration - Three Development Modes
+
+The TheAd Vantage integration supports three distinct modes of operation:
+
+### 1. Production Mode (Default)
+
+**Use Case**: Platform developers using the component in production or their own development environments.
+
+**Behavior**: 
+- Connects to `https://thead-vantage.com/api/ads` by default
+- Full tracking enabled (impressions and clicks are recorded)
+- No configuration required
+
+**Configuration**: None needed - this is the default behavior.
+
+**Example Usage**:
+```tsx
+import { AdBanner } from '@/components/AdBanner';
+
+export default function MyPage() {
+  return (
+    <AdBanner
+      platformId="10"
+      apiKey="your-api-key-here"
+      size="leaderboard"
+    />
+  );
+}
+```
+
+### 2. Platform Developer Dev Mode
+
+**Use Case**: Platform developers testing locally with their own platform instance.
+
+**Behavior**:
+- Connects to a custom API URL (your platform's API endpoint)
+- Full tracking enabled (impressions and clicks are recorded)
+- Allows testing with your own platform without affecting production
+
+**Configuration**: Set the `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` environment variable in `.env.local`:
+
+```env
+# .env.local
+NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
+```
+
+**Example Usage**:
+```tsx
+// Option 1: Use environment variable (recommended)
+<AdBanner
+  platformId="10"
+  apiKey="your-api-key"
+  size="leaderboard"
+/>
+
+// Option 2: Override directly in component
+<AdBanner
+  platformId="10"
+  apiKey="your-api-key"
+  size="leaderboard"
+  apiUrl="https://your-platform.com/api/ads"
+/>
+```
+
+### 3. TheAd Vantage Dev Mode
+
+**Use Case**: TheAd Vantage developers testing the component with a local platform instance.
+
+**Behavior**:
+- Connects to `http://localhost:3001/api/ads`
+- Tracking disabled (impressions and clicks are NOT recorded)
+- Returns mock data if local platform is unavailable
+- Shows dev mode indicators in the UI
+
+**Configuration**: Set the `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE` environment variable in `.env.local`:
+
+```env
+# .env.local
+NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true
+```
+
+**Example Usage**:
+```tsx
+// Automatically uses localhost:3001 when dev mode is enabled
+<AdBanner
+  platformId="10"
+  apiKey="your-api-key"
+  size="leaderboard"
+/>
+```
+
+---
+
+## Component API
+
+### AdBanner Component
+
+The main component for displaying ads from TheAd Vantage.
+
+**Props**:
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `platformId` | `string` | Yes | - | Your platform ID from TheAd Vantage |
+| `apiKey` | `string` | Yes | - | Your API key from TheAd Vantage |
+| `size` | `'leaderboard' \| 'medium-rectangle' \| 'wide-skyscraper' \| 'banner'` | No | `'banner'` | Ad size specification |
+| `apiUrl` | `string` | No | - | Override API endpoint URL (highest priority) |
+| `userId` | `string \| null` | No | `null` | User ID for ad targeting |
+| `userSegment` | `string \| null` | No | `null` | User segment for ad targeting |
+| `className` | `string` | No | `''` | Additional CSS classes |
+
+**Example**:
+```tsx
+import { AdBanner } from '@/components/AdBanner';
+
+export default function ArticlePage() {
+  return (
+    <div>
+      <article>
+        <h1>My Article</h1>
+        <p>Article content...</p>
+      </article>
+      
+      <aside>
+        <AdBanner
+          platformId="10"
+          apiKey="abc123xyz"
+          size="medium-rectangle"
+          userId="user-123"
+          userSegment="premium"
+          className="my-4"
+        />
+      </aside>
+    </div>
+  );
+}
+```
+
+### Utility Functions
+
+You can also use the utility functions directly:
+
+```tsx
+import { fetchAdBanner, trackImpression, trackClick } from '@/lib/ads';
+
+// Fetch an ad
+const response = await fetchAdBanner({
+  platformId: '10',
+  apiKey: 'your-api-key',
+  size: 'leaderboard',
+  userId: 'user-123',
+  userSegment: 'premium',
+});
+
+// Track events (automatically skipped in TheAd Vantage dev mode)
+trackImpression(adId);
+trackClick(adId);
+```
+
+---
+
+## Environment Variables
+
+### For Platform Developers
+
+```env
+# .env.local
+# Optional: Point to your own platform instance
+NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
+```
+
+### For TheAd Vantage Developers
+
+```env
+# .env.local
+# Enable TheAd Vantage dev mode (uses localhost:3001, disables tracking)
+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)
+
+---
+
+## API Routes
+
+The integration includes Next.js API routes that proxy requests to TheAd Vantage:
+
+- **`GET /api/ads`** - Fetches ads from TheAd Vantage platform
+  - Automatically handles all three modes
+  - Adds `dev_mode`, `no_track`, and `no_click_track` parameters in dev mode
+  - Returns mock data if platform is unavailable in TheAd Vantage dev mode
+
+- **`POST /api/ads`** - Tracks ad impressions/clicks
+  - Automatically skipped in TheAd Vantage dev mode
+  - Logs dev mode messages when tracking is skipped
+
+---
+
+## Development Mode Features
+
+When in **TheAd Vantage Dev Mode** (`NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true`):
+
+- ✅ **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
+- ✅ **Console Logging**: Dev mode actions are logged to console
+- ✅ **Error Resilience**: Connection failures won't break your development workflow
+
+---
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+---
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+
+---
+
+# AI Agent Implementation Guide
+
+> **For AI Agents (Cursor, GitHub Copilot, etc.)**: This section provides comprehensive instructions for implementing and using TheAd Vantage integration in this codebase.
+
+## System Architecture
+
+The TheAd Vantage integration uses a three-mode 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
+
+## Key Files and Their Purposes
+
+### Configuration
+- **`src/lib/thead-vantage-config.ts`**: Core configuration utility that determines API URL based on mode priority
+  - `getApiBaseUrl(explicitApiUrl?)`: Returns the appropriate API base URL
+  - `isTheadVantageDevMode()`: Checks if TheAd Vantage dev mode is active
+  - `setTheadVantageConfig(config)`: Runtime configuration for browser contexts
+
+### API Routes
+- **`src/app/api/ads/route.ts`**: Next.js API route that proxies requests to TheAd Vantage
+  - `GET /api/ads`: Fetches ads, handles all three modes, adds dev flags when needed
+  - `POST /api/ads`: Tracks impressions/clicks, skips tracking in dev mode
+
+### Components
+- **`src/components/AdBanner.tsx`**: Main React component for displaying ads
+  - Props: `platformId`, `apiKey`, `size`, `apiUrl?`, `userId?`, `userSegment?`, `className?`
+  - Automatically handles loading, error states, and dev mode indicators
+
+### Utilities
+- **`src/lib/ads.ts`**: Utility functions for fetching and tracking ads
+  - `fetchAdBanner(params)`: Fetches ads with full parameter support
+  - `trackImpression(adId)`: Tracks ad impressions (skipped in dev mode)
+  - `trackClick(adId)`: Tracks ad clicks (skipped in dev mode)
+
+## Implementation Instructions for AI Agents
+
+### When Adding TheAd Vantage Integration to a New Component
+
+1. **Import the AdBanner component**:
+   ```tsx
+   import { AdBanner } from '@/components/AdBanner';
+   ```
+
+2. **Use the component with required props**:
+   ```tsx
+   <AdBanner
+     platformId="10"
+     apiKey="your-api-key"
+     size="leaderboard"
+   />
+   ```
+
+3. **For platform developers using custom API**: Ensure they set `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` in `.env.local`
+
+4. **For TheAd Vantage developers**: Ensure they set `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` in `.env.local`
+
+### When Debugging Ad Loading Issues
+
+1. **Check environment variables**: Verify `.env.local` has correct configuration
+2. **Check console logs**: Look for `[AdBanner]` prefixed messages
+3. **Verify API URL resolution**: The `getApiBaseUrl()` function logs which mode is active
+4. **Check network tab**: Verify requests are going to the correct endpoint
+
+### When Implementing Custom Ad Fetching
+
+1. **Use `fetchAdBanner()` utility** instead of direct fetch calls
+2. **Pass `apiUrl` parameter** if you need to override the default
+3. **Handle `dev_mode` flag** in response to show appropriate UI indicators
+4. **Use `trackImpression()` and `trackClick()`** for tracking (automatically skipped in dev mode)
+
+### Mode Detection Priority (Important for AI Agents)
+
+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
+
+### Common Patterns
+
+**Pattern 1: Basic Ad Display**
+```tsx
+<AdBanner platformId="10" apiKey="key" size="banner" />
+```
+
+**Pattern 2: Ad with User Targeting**
+```tsx
+<AdBanner 
+  platformId="10" 
+  apiKey="key" 
+  size="leaderboard"
+  userId={user?.id}
+  userSegment={user?.segment}
+/>
+```
+
+**Pattern 3: Custom API URL Override**
+```tsx
+<AdBanner 
+  platformId="10" 
+  apiKey="key" 
+  size="banner"
+  apiUrl="https://custom-api.com/ads"
+/>
+```
+
+**Pattern 4: Programmatic Ad Fetching**
+```tsx
+const response = await fetchAdBanner({
+  platformId: '10',
+  apiKey: 'key',
+  size: 'medium-rectangle',
+  apiUrl: customUrl, // Optional override
+});
+```
+
+### Error Handling
+
+- The component automatically handles loading and error states
+- In TheAd Vantage dev mode, connection failures return mock data instead of errors
+- Tracking failures are logged but don't throw errors (non-blocking)
+
+### Testing Checklist for AI Agents
+
+When implementing or modifying TheAd Vantage integration:
+
+- [ ] Verify production mode connects to https://thead-vantage.com/api/ads
+- [ ] Verify platform dev mode respects `NEXT_PUBLIC_THEAD_VANTAGE_API_URL`
+- [ ] Verify TheAd Vantage dev mode uses localhost:3001 when flag is set
+- [ ] Verify tracking is disabled in TheAd Vantage dev mode
+- [ ] Verify mock data is returned when platform is unavailable in dev mode
+- [ ] Verify explicit `apiUrl` prop overrides all other settings
+- [ ] Verify component handles loading states correctly
+- [ ] Verify component handles error states gracefully
+- [ ] Verify dev mode indicators show in UI when appropriate
+
+### Environment Variable Reference
+
+```env
+# Platform Developer Dev Mode
+NEXT_PUBLIC_THEAD_VANTAGE_API_URL=https://your-platform.com/api/ads
+
+# TheAd Vantage Dev Mode
+NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true
+```
+
+### TypeScript Types
+
+Key types for reference:
+- `AdBannerProps`: Component props interface
+- `Ad`: Ad data structure
+- `AdsResponse`: API response structure
+- `FetchAdBannerParams`: Parameters for `fetchAdBanner()` function
+
+All types are exported from `@/lib/ads` and `@/components/AdBanner`.
+
+---
+
+## Quick Reference
+
+**Default Behavior**: Connects to `https://thead-vantage.com/api/ads` (production)
+
+**Platform Developer Setup**: Add `NEXT_PUBLIC_THEAD_VANTAGE_API_URL` to `.env.local`
+
+**TheAd Vantage Developer Setup**: Add `NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true` to `.env.local`
+
+**Component Import**: `import { AdBanner } from '@/components/AdBanner';`
+
+**Utility Import**: `import { fetchAdBanner, trackImpression, trackClick } from '@/lib/ads';`

package/package.json

@@ -1,49 +1,71 @@
-{
-    "name": "@thead-vantage/react",
-    "version": "2.1.0",
-    "description": "React component library for TheAd Vantage advertising platform",
-    "main": "dist/index.js",
-    "module": "dist/index.esm.js",
-    "types": "dist/index.d.ts",
-    "files": [
-        "dist"
-    ],
-    "exports": {
-        ".": {
-            "import": "./dist/index.esm.js",
-            "require": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "scripts": {
-        "build": "rollup -c",
-        "test": "jest",
-        "prepublishOnly": "npm run build"
-    },
-    "keywords": [
-        "react",
-        "advertising",
-        "ad",
-        "banner",
-        "thead-vantage"
-    ],
-    "author": "TheAd Vantage Team",
-    "license": "MIT",
-    "peerDependencies": {
-        "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
-        "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
-    },
-    "devDependencies": {
-        "@rollup/plugin-commonjs": "^22.0.2",
-        "@rollup/plugin-node-resolve": "^13.3.0",
-        "@rollup/plugin-typescript": "^8.5.0",
-        "@types/react": "^19.0.0",
-        "rollup": "^2.79.2",
-        "rollup-plugin-peer-deps-external": "^2.2.4",
-        "rollup-plugin-terser": "^7.0.2",
-        "typescript": "^4.7.3"
-    },
-    "dependencies": {
-        "@thead-vantage/react": "^1.9.0"
-    }
-}
+{
+  "name": "@thead-vantage/react",
+  "version": "2.1.2",
+  "description": "React components and utilities for TheAd Vantage ad platform integration",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./components/AdBanner": {
+      "import": "./src/components/AdBanner.tsx",
+      "require": "./src/components/AdBanner.tsx",
+      "types": "./src/components/AdBanner.tsx"
+    },
+    "./components/AdDisplay": {
+      "import": "./src/components/AdDisplay.tsx",
+      "require": "./src/components/AdDisplay.tsx",
+      "types": "./src/components/AdDisplay.tsx"
+    },
+    "./lib/ads": {
+      "import": "./src/lib/ads.ts",
+      "require": "./src/lib/ads.ts",
+      "types": "./src/lib/ads.ts"
+    },
+    "./lib/thead-vantage-config": {
+      "import": "./src/lib/thead-vantage-config.ts",
+      "require": "./src/lib/thead-vantage-config.ts",
+      "types": "./src/lib/thead-vantage-config.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "ads",
+    "advertising",
+    "thead-vantage",
+    "nextjs"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "next": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"
+  },
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "next": "^16.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}