@thead-vantage/react 2.1.0 → 2.1.2

package/src/app/api/ads/route.ts

@@ -0,0 +1,174 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getApiBaseUrl, isTheadVantageDevMode, isDevelopmentMode } from '@/lib/thead-vantage-config';
+
+/**
+ * API route that proxies ads requests to TheAd Vantage Platform
+ * Supports three modes:
+ * 1. Production Mode (default) - https://thead-vantage.com/api/ads
+ * 2. Platform Developer Dev Mode - custom URL via NEXT_PUBLIC_THEAD_VANTAGE_API_URL
+ * 3. TheAd Vantage Dev Mode - localhost:3001 (NEXT_PUBLIC_THEAD_VANTAGE_DEV_MODE=true)
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const isDevelopment = isDevelopmentMode();
+    const isTheadVantageDev = isTheadVantageDevMode();
+    
+    // Get explicit API URL from query params if provided
+    const explicitApiUrl = request.nextUrl.searchParams.get('apiUrl') || undefined;
+    
+    // Determine the base API URL using the three-mode system
+    const apiBaseUrl = getApiBaseUrl(explicitApiUrl);
+    
+    // Get query parameters from the request (excluding apiUrl which we already used)
+    const searchParams = request.nextUrl.searchParams;
+    const params = new URLSearchParams();
+    
+    // Copy all params except apiUrl
+    searchParams.forEach((value, key) => {
+      if (key !== 'apiUrl') {
+        params.append(key, value);
+      }
+    });
+    
+    // In TheAd Vantage dev mode or general development, add flags to prevent tracking
+    if (isTheadVantageDev || isDevelopment) {
+      params.set('dev_mode', 'true');
+      params.set('no_track', 'true'); // Prevent impression tracking
+      params.set('no_click_track', 'true'); // Prevent click tracking
+    }
+    
+    // Build the URL for TheAd Vantage platform
+    // If apiBaseUrl already includes /api/ads, use it directly, otherwise append
+    const advantageUrl = apiBaseUrl.includes('/api/ads') 
+      ? `${apiBaseUrl}?${params.toString()}`
+      : `${apiBaseUrl}/api/ads?${params.toString()}`;
+    
+    // Fetch from advantage platform
+    const response = await fetch(advantageUrl, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        // Forward any custom headers if needed
+        ...(request.headers.get('user-agent') && {
+          'User-Agent': request.headers.get('user-agent') || '',
+        }),
+      },
+      // Add cache control for development
+      cache: isDevelopment ? 'no-store' : 'default',
+    });
+    
+    if (!response.ok) {
+      // In TheAd Vantage dev mode, return a mock response instead of failing
+      if (isTheadVantageDev) {
+        return NextResponse.json({
+          success: true,
+          dev_mode: true,
+          ad: {
+            id: 'dev-ad-1',
+            imageUrl: '/placeholder-ad.png',
+            linkUrl: '#',
+            alt: 'Development Ad - No Tracking',
+            width: 300,
+            height: 250,
+          },
+          message: 'TheAd Vantage dev mode: Using mock ad (no tracking)',
+        }, { status: 200 });
+      }
+      
+      return NextResponse.json(
+        { error: 'Failed to fetch ads from TheAd Vantage platform' },
+        { status: response.status }
+      );
+    }
+    
+    const data = await response.json();
+    
+    // Add development mode indicator to response
+    if (isTheadVantageDev || isDevelopment) {
+      return NextResponse.json({
+        ...data,
+        dev_mode: true,
+        _dev_note: 'Development mode: Impressions and clicks are not being tracked',
+      });
+    }
+    
+    return NextResponse.json(data);
+  } catch (error) {
+    // In TheAd Vantage dev mode, return mock data instead of error
+    if (isTheadVantageDevMode()) {
+      console.warn('TheAd Vantage platform connection failed, using mock ad:', error);
+      return NextResponse.json({
+        success: true,
+        dev_mode: true,
+        ad: {
+          id: 'dev-ad-1',
+          imageUrl: '/placeholder-ad.png',
+          linkUrl: '#',
+          alt: 'Development Ad - No Tracking',
+          width: 300,
+          height: 250,
+        },
+        message: 'TheAd Vantage dev mode: Using mock ad (platform unavailable)',
+      }, { status: 200 });
+    }
+    
+    console.error('Error fetching ads:', error);
+    return NextResponse.json(
+      { error: 'Failed to fetch ads' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * Handle impression tracking (called when ad is viewed)
+ * In TheAd Vantage dev mode, this is a no-op
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const isTheadVantageDev = isTheadVantageDevMode();
+    const isDevelopment = isDevelopmentMode();
+    const body = await request.json();
+    const { action, adId } = body;
+    
+    // In TheAd Vantage dev mode or general development, don't track impressions or clicks
+    if (isTheadVantageDev || isDevelopment) {
+      return NextResponse.json({
+        success: true,
+        dev_mode: true,
+        message: `Development mode: ${action} tracking skipped for ad ${adId}`,
+      });
+    }
+    
+    // Get the API base URL to determine where to send tracking
+    const apiBaseUrl = getApiBaseUrl();
+    const trackingUrl = apiBaseUrl.includes('/api/ads')
+      ? apiBaseUrl.replace('/api/ads', '/api/ads/track')
+      : `${apiBaseUrl}/api/ads/track`;
+    
+    const response = await fetch(trackingUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ action, adId }),
+    });
+    
+    if (!response.ok) {
+      return NextResponse.json(
+        { error: 'Failed to track ad event' },
+        { status: response.status }
+      );
+    }
+    
+    const data = await response.json();
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error('Error tracking ad:', error);
+    return NextResponse.json(
+      { error: 'Failed to track ad' },
+      { status: 500 }
+    );
+  }
+}
+

package/src/app/globals.css

@@ -0,0 +1,26 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}

package/src/app/layout.tsx

@@ -0,0 +1,34 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}

package/src/app/page.tsx

@@ -0,0 +1,103 @@
+import Image from "next/image";
+
+export default function Home() {
+  return (
+    <div className="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20 font-[family-name:var(--font-geist-sans)]">
+      <main className="flex flex-col gap-[32px] row-start-2 items-center sm:items-start">
+        <Image
+          className="dark:invert"
+          src="/next.svg"
+          alt="Next.js logo"
+          width={180}
+          height={38}
+          priority
+        />
+        <ol className="list-inside list-decimal text-sm/6 text-center sm:text-left font-[family-name:var(--font-geist-mono)]">
+          <li className="mb-2 tracking-[-.01em]">
+            Get started by editing{" "}
+            <code className="bg-black/[.05] dark:bg-white/[.06] px-1 py-0.5 rounded font-[family-name:var(--font-geist-mono)] font-semibold">
+              src/app/page.tsx
+            </code>
+            .
+          </li>
+          <li className="tracking-[-.01em]">
+            Save and see your changes instantly.
+          </li>
+        </ol>
+
+        <div className="flex gap-4 items-center flex-col sm:flex-row">
+          <a
+            className="rounded-full border border-solid border-transparent transition-colors flex items-center justify-center bg-foreground text-background gap-2 hover:bg-[#383838] dark:hover:bg-[#ccc] font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 sm:w-auto"
+            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            <Image 
+              className="dark:invert"
+              src="/vercel.svg"
+              alt="Vercel logomark"
+              width={20}
+              height={20}
+            />
+            Deploy now
+          </a>
+          <a
+            className="rounded-full border border-solid border-black/[.08] dark:border-white/[.145] transition-colors flex items-center justify-center hover:bg-[#f2f2f2] dark:hover:bg-[#1a1a1a] hover:border-transparent font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 w-full sm:w-auto md:w-[158px]"
+            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Read our docs
+          </a>
+        </div>
+      </main>
+      <footer className="row-start-3 flex gap-[24px] flex-wrap items-center justify-center">
+        <a
+          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
+          href="https://nextjs.org/learn?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <Image
+            aria-hidden
+            src="/file.svg"
+            alt="File icon"
+            width={16}
+            height={16}
+          />
+          Learn
+        </a>
+        <a
+          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
+          href="https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <Image
+            aria-hidden
+            src="/window.svg"
+            alt="Window icon"
+            width={16}
+            height={16}
+          />
+          Examples
+        </a>
+        <a
+          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
+          href="https://nextjs.org?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <Image
+            aria-hidden
+            src="/globe.svg"
+            alt="Globe icon"
+            width={16}
+            height={16}
+          />
+          Go to nextjs.org →
+        </a>
+      </footer>
+    </div>
+  );
+}

package/src/components/AdBanner.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { useEffect, useState } 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;
+}
+
+export function AdBanner({
+  platformId,
+  apiKey,
+  size = 'banner',
+  apiUrl,
+  userId = null,
+  userSegment = null,
+  className = '',
+}: 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);
+
+  useEffect(() => {
+    const loadAd = async () => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const response = await fetchAdBanner({
+          platformId,
+          apiKey,
+          size,
+          apiUrl,
+          userId,
+          userSegment,
+        });
+
+        if (response.success && response.ad) {
+          setAd(response.ad);
+          setDevMode(response.dev_mode || false);
+
+          // Track impression (will be skipped in dev mode)
+          trackImpression(response.ad.id);
+        } else {
+          setError('No ads available');
+        }
+      } catch (err) {
+        console.error('[AdBanner] Error fetching ad:', err);
+        setError(err instanceof Error ? err.message : 'Failed to fetch ad');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadAd();
+  }, [platformId, apiKey, size, apiUrl, userId, userSegment]);
+
+  const handleClick = () => {
+    if (ad) {
+      trackClick(ad.id);
+      // 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={className}>
+      <a
+        href={ad.targetUrl}
+        onClick={handleClick}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="block"
+      >
+        {ad.type === 'image' ? (
+          <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>
+      {devMode && (
+        <p className="text-xs text-gray-500 mt-1">[DEV] No tracking active</p>
+      )}
+    </div>
+  );
+}
+

package/src/components/AdDisplay.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Image from 'next/image';
+import { fetchAds, trackImpression, trackClick, type AdData } from '@/lib/ads';
+
+interface AdDisplayProps {
+  position?: string;
+  className?: string;
+}
+
+export default function AdDisplay({ position, className = '' }: AdDisplayProps) {
+  const [ad, setAd] = useState<AdData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [devMode, setDevMode] = useState(false);
+
+  useEffect(() => {
+    async function loadAd() {
+      try {
+        setLoading(true);
+        setError(null);
+        
+        const params: Record<string, string> = {};
+        if (position) {
+          params.position = position;
+        }
+        
+        const response = await fetchAds(params);
+        
+        if (response.success && response.ad) {
+          setAd(response.ad);
+          setDevMode(response.dev_mode || false);
+          
+          // Track impression (will be skipped in dev mode)
+          trackImpression(response.ad.id);
+        } else {
+          setError('No ad available');
+        }
+      } catch (err) {
+        console.error('Error loading ad:', err);
+        setError('Failed to load ad');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    loadAd();
+  }, [position]);
+
+  const handleClick = () => {
+    if (ad) {
+      trackClick(ad.id);
+      // 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={className}>
+      <a
+        href={ad.linkUrl}
+        onClick={handleClick}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="block"
+      >
+        <Image
+          src={ad.imageUrl}
+          alt={ad.alt}
+          width={ad.width || 300}
+          height={ad.height || 250}
+          className="rounded"
+          unoptimized
+        />
+      </a>
+      {devMode && (
+        <p className="text-xs text-gray-500 mt-1">[DEV] No tracking active</p>
+      )}
+    </div>
+  );
+}
+

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @thead-vantage/react
+ * 
+ * Main entry point for TheAd Vantage React library
+ */
+
+// Export components
+export { AdBanner, type AdBannerProps } from './components/AdBanner';
+export { default as AdDisplay } from './components/AdDisplay';
+
+// Export utilities
+export {
+  fetchAds,
+  fetchAdBanner,
+  trackImpression,
+  trackClick,
+  type Ad,
+  type AdData,
+  type AdsResponse,
+  type AdBannerResponse,
+  type FetchAdBannerParams,
+} from './lib/ads';
+
+// Export configuration utilities
+export {
+  getApiBaseUrl,
+  isTheadVantageDevMode,
+  isDevelopmentMode,
+  setTheadVantageConfig,
+  getTheadVantageConfig,
+  type TheadVantageConfig,
+} from './lib/thead-vantage-config';
+