@mixpeek/prebid 1.0.0 → 1.0.1

package/README.md

@@ -1,439 +1,317 @@
-# Mixpeek Contextual Adapter for Prebid.js
+
+<p align="center">
+  <img src="assets/header.png" alt="Mixpeek Multimodal Contextual Targeting Adapter" />
+</p>
+
+# Mixpeek RTD (Real-Time Data) Adapter for Prebid.js
+
+**This is a Real-Time Data (RTD) module for Prebid.js that replaces cookie-based targeting with sub-100ms contextual signals.**
 
 [![npm version](https://img.shields.io/npm/v/@mixpeek/prebid.svg)](https://www.npmjs.com/package/@mixpeek/prebid)
 [![npm downloads](https://img.shields.io/npm/dm/@mixpeek/prebid.svg)](https://www.npmjs.com/package/@mixpeek/prebid)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Node Version](https://img.shields.io/node/v/@mixpeek/prebid.svg)](https://www.npmjs.com/package/@mixpeek/prebid)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@mixpeek/prebid)](https://bundlephobia.com/package/@mixpeek/prebid)
-[![Dependencies](https://img.shields.io/librariesio/release/npm/@mixpeek/prebid)](https://www.npmjs.com/package/@mixpeek/prebid)
-[![GitHub Stars](https://img.shields.io/github/stars/mixpeek/prebid?style=social)](https://github.com/mixpeek/prebid)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/mixpeek/prebid/pulls)
+[![Status](https://img.shields.io/badge/Status-Production--Ready-brightgreen.svg)](https://www.npmjs.com/package/@mixpeek/prebid)
 
-## 🎯 Overview
+---
 
-The Mixpeek Contextual Adapter enables publishers and SSPs using **Prebid.js** to enrich bid requests with real-time contextual data powered by Mixpeek's multimodal AI engine. This adapter provides:
+## What This Is
 
-- **Privacy-First Targeting**: No cookies, just content-based context
-- **Multimodal Analysis**: Text, images, video, and audio processing
-- **IAB Taxonomy**: Automatic classification into IAB content categories
-- **Brand Safety**: Real-time brand safety scoring
-- **Ad Adjacency Awareness**: Tracks previous ad to avoid repetition and improve user experience
-- **Sub-100ms Performance**: Optimized for header bidding speed requirements
-- **Graceful Fallbacks**: Never blocks the auction
+| Type | Status |
+|------|--------|
+| **RTD Module** (bid enrichment) | Supported |
+| Bidder Adapter | Not a bidder |
+| Analytics Adapter | Not analytics |
+| Identity Module | Not identity |
 
-## 🚀 Quick Start
+---
 
-### Installation
+## Why Use This
 
-```bash
-npm install @mixpeek/prebid
-```
+1. **Ad Adjacency Awareness** - Competitive separation, no repeat creatives
+2. **Privacy-First Contextual Targeting** - No cookies, no user tracking
+3. **IAB Taxonomy Classification** - Content categorization (v3.0)
+4. **Brand Safety Scoring** - Real-time sentiment analysis
+5. **Multimodal Analysis** - Text, image, video content understanding
+6. **Sub-100ms RTD Performance** - Optimized for header bidding latency
+
+---
 
-### Basic Setup
+## Minimal Setup (Copy-Paste Ready)
 
 ```javascript
-// 1. Include the Mixpeek RTD module
 import '@mixpeek/prebid'
 
-// 2. Configure Mixpeek as an RTD provider
 pbjs.setConfig({
   realTimeData: {
-    auctionDelay: 250,  // Max time to wait for contextual data (ms)
     dataProviders: [{
       name: 'mixpeek',
-      waitForIt: true,  // Wait for Mixpeek before starting auction
       params: {
-        apiKey: 'YOUR_MIXPEEK_API_KEY',
-        collectionId: 'your-collection-id',
-        
-        // Use development server (temporary)
-        endpoint: 'https://server-xb24.onrender.com',
-        // Or production: endpoint: 'https://api.mixpeek.com',
-        
-        namespace: 'your-namespace', // optional
-        featureExtractors: ['taxonomy', 'brand-safety'],
-        mode: 'page', // 'page', 'video', or 'auto'
-        timeout: 5000, // ms - higher for dev server
-        cacheTTL: 300 // seconds
+        apiKey: 'YOUR_API_KEY',
+        collectionId: 'YOUR_COLLECTION_ID',
+        namespace: 'YOUR_NAMESPACE'
       }
     }]
   }
 })
-
-// 3. The RTD module automatically enriches bid requests!
-pbjs.requestBids({
-  adUnits: [...],
-  bidsBackHandler: function(bids) {
-    // Bids now include Mixpeek contextual data in ortb2
-  }
-})
 ```
 
-## 📋 Prerequisites
-
-1. **Mixpeek Account**: Sign up at [mixpeek.com](https://mixpeek.com/start)
-2. **API Key**: Generate an API key in your Mixpeek dashboard
-3. **Collection**: Create a collection with feature extractors configured
-4. **Prebid.js**: Version 6.0.0 or higher
+That's it. The RTD module automatically enriches all bid requests.
 
-## 🔧 Configuration Options
+---
 
-### RTD Configuration
+## Installation
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `realTimeData.auctionDelay` | number | ❌ | 250 | Max time to wait for all RTD providers (ms) |
-| `realTimeData.dataProviders[].name` | string | ✅ | - | Must be `'mixpeek'` |
-| `realTimeData.dataProviders[].waitForIt` | boolean | ❌ | false | Wait for Mixpeek before starting auction |
-
-### Mixpeek Parameters
+```bash
+npm install @mixpeek/prebid
+```
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `params.apiKey` | string | ✅ | - | Your Mixpeek API key |
-| `params.collectionId` | string | ✅ | - | Mixpeek collection ID for document processing |
-| `params.endpoint` | string | ❌ | `https://server-xb24.onrender.com` | Mixpeek API endpoint (dev server default) |
-| `params.namespace` | string | ❌ | - | Optional namespace for data isolation |
-| `params.featureExtractors` | array | ❌ | `['taxonomy']` | Feature extractors to use (taxonomy, brand-safety, etc.) |
-| `params.mode` | string | ❌ | `auto` | Content mode: `page`, `video`, `image`, or `auto` |
-| `params.timeout` | number | ❌ | 250 | API request timeout in milliseconds |
-| `params.cacheTTL` | number | ❌ | 300 | Cache TTL in seconds |
-| `params.enableCache` | boolean | ❌ | `true` | Enable local caching |
-| `params.debug` | boolean | ❌ | `false` | Enable debug logging |
-| `params.batchSize` | number | ❌ | 1 | Number of concurrent requests |
-| `params.retryAttempts` | number | ❌ | 2 | Number of retry attempts on failure |
+## Prerequisites
 
-## 📊 Output: OpenRTB 2.6 Data Structure
+1. **Mixpeek Account** - Sign up at [mixpeek.com](https://mixpeek.com/start)
+2. **API Key** - Generate in your Mixpeek dashboard
+3. **Collection** - Create a collection with feature extractors
+4. **Namespace** - Your namespace ID (format: `ns_xxxxx`)
+5. **Prebid.js** - Version 6.0.0 or higher
 
-The RTD module injects contextual data into your bid requests using the OpenRTB 2.6 standard:
+---
 
-### Site-Level Data (`ortb2.site.content`)
-```javascript
-{
-  "ortb2": {
-    "site": {
-      "content": {
-        "cat": ["IAB19-11"],              // IAB Content Categories
-        "cattax": 6,                       // IAB Content Taxonomy v3.0
-        "genre": "Technology - AI",        // Human-readable category
-        "keywords": "ai,technology,ml",    // Extracted keywords
-        "language": "en",                  // Content language
-        "title": "Article Title",          // Page title
-        "url": "https://example.com",      // Page URL
-        "ext": {
-          "data": {
-            "mixpeek": {
-              "score": 0.94,               // Confidence score
-              "brandSafety": 0.98,         // Brand safety score
-              "sentiment": "positive",      // Content sentiment
-              "embeddingId": "emb_abc123"  // Embedding ID
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
+## Full Configuration
 
-### Impression-Level Data (`ortb2Imp.ext.data`)
 ```javascript
-{
-  // Current page context
-  "hb_mixpeek_taxonomy": "IAB19-11",       // Primary IAB taxonomy code
-  "hb_mixpeek_category": "Technology > AI", // Human-readable category
-  "hb_mixpeek_node": "node_tech_ai",       // Taxonomy node ID
-  "hb_mixpeek_path": "tech/ai/ml",         // Hierarchical path
-  "hb_mixpeek_score": "0.94",              // Confidence score
-  "hb_mixpeek_safety": "0.98",             // Brand safety score
-  "hb_mixpeek_keywords": "AI,ML,tech",     // Extracted keywords
-  "hb_mixpeek_embed": "emb_abc123",        // Embedding ID for retrieval
-  
-  // Previous ad context (adjacency awareness)
-  "hb_mixpeek_prev_creative": "12345",     // Last creative ID shown
-  "hb_mixpeek_prev_bidder": "appnexus",    // Last bidder that won
-  "hb_mixpeek_prev_adunit": "sidebar-1",   // Last ad unit code
-  "hb_mixpeek_prev_cat": "IAB18-1,IAB12-3" // Last ad categories
-}
-```
-
-## 🎥 Usage Examples
-
-### Page Context (Articles, Blogs)
+import '@mixpeek/prebid'
 
-```javascript
 pbjs.setConfig({
   realTimeData: {
-    auctionDelay: 250,
+    auctionDelay: 250,  // Max wait for contextual data (ms)
     dataProviders: [{
       name: 'mixpeek',
-      waitForIt: true,
+      waitForIt: true,  // Wait for Mixpeek before auction
       params: {
-        apiKey: 'sk_your_api_key',
-        collectionId: 'col_articles',
-        mode: 'page',
-        featureExtractors: ['taxonomy', 'brand-safety', 'keywords']
+        // Required
+        apiKey: 'YOUR_API_KEY',
+        collectionId: 'YOUR_COLLECTION_ID',
+        namespace: 'YOUR_NAMESPACE',  // e.g., 'ns_abc123'
+
+        // Optional
+        endpoint: 'https://api.mixpeek.com',  // Default
+        mode: 'auto',        // 'page', 'video', 'image', or 'auto'
+        timeout: 250,        // API timeout in ms
+        cacheTTL: 300,       // Cache TTL in seconds
+        enableCache: true,   // Enable local caching
+        debug: false         // Enable debug logging
       }
     }]
   }
 })
-```
-
-### Video Context (Pre-roll, Mid-roll)
 
-```javascript
-pbjs.setConfig({
-  realTimeData: {
-    auctionDelay: 300,  // Longer delay for video processing
-    dataProviders: [{
-      name: 'mixpeek',
-      waitForIt: true,
-      params: {
-        apiKey: 'sk_your_api_key',
-        collectionId: 'col_videos',
-        mode: 'video',
-        videoSelector: '#main-video', // CSS selector for video element
-        featureExtractors: ['taxonomy', 'scene-detection']
-      }
-    }]
+// Bids are automatically enriched with contextual data
+pbjs.requestBids({
+  adUnits: [...],
+  bidsBackHandler: function(bids) {
+    // Bids now include Mixpeek contextual data in ortb2
   }
 })
 ```
 
-### Multi-Content Auto-Detection
+---
 
-```javascript
-pbjs.setConfig({
-  realTimeData: {
-    auctionDelay: 250,
-    dataProviders: [{
-      name: 'mixpeek',
-      waitForIt: true,
-      params: {
-        apiKey: 'sk_your_api_key',
-        collectionId: 'col_mixed',
-        mode: 'auto', // Automatically detects page, video, or image content
-        featureExtractors: ['taxonomy', 'brand-safety', 'clustering']
-      }
-    }]
-  }
-})
-```
+## Ad Adjacency Awareness (Key Feature)
 
-## 🏗️ How It Works
-
-```mermaid
-sequenceDiagram
-    participant Publisher
-    participant Prebid
-    participant MixpeekAdapter
-    participant MixpeekAPI
-    participant SSP
-
-    Publisher->>Prebid: Request Bids
-    Prebid->>MixpeekAdapter: beforeRequestBids event
-    MixpeekAdapter->>MixpeekAdapter: Extract page/video content
-    MixpeekAdapter->>MixpeekAdapter: Check cache
-    alt Cache Miss
-        MixpeekAdapter->>MixpeekAPI: POST /collections/{id}/documents
-        MixpeekAPI->>MixpeekAPI: Process with feature extractors
-        MixpeekAPI-->>MixpeekAdapter: Return enrichments
-        MixpeekAdapter->>MixpeekAdapter: Cache result
-    end
-    MixpeekAdapter->>Prebid: Inject contextual key-values
-    Prebid->>SSP: Send enriched bid request
-    SSP-->>Prebid: Return bids
-    Prebid-->>Publisher: Render ad
-```
+The adapter automatically tracks previously served ads to enable:
 
-## 🧪 Testing
+- **Competitive Separation** - Avoid showing competing brands consecutively
+- **Creative Frequency** - Prevent the same ad from showing repeatedly
+- **Category Diversity** - Improve ad variety for better user experience
 
-```bash
-# Run all tests
-npm test
+### How SSPs/DSPs Use It
 
-# Run with coverage
-npm run test:coverage
+```javascript
+// Data automatically injected into ortb2Imp.ext.data:
+{
+  "hb_mixpeek_prev_creative": "12345",     // Last creative ID
+  "hb_mixpeek_prev_bidder": "appnexus",    // Last winning bidder
+  "hb_mixpeek_prev_adunit": "sidebar-1",   // Last ad unit
+  "hb_mixpeek_prev_cat": "IAB18-1,IAB12-3" // Last ad categories
+}
 
-# Watch mode
-npm run test:watch
+// DSP can use for competitive separation:
+if (prevCategories.includes('IAB18-1') && currentAd.category === 'IAB18-1') {
+  // Don't show competing fashion ads back-to-back
+}
 ```
 
-## 📖 Advanced Configuration
+### Privacy Safe
 
-### Custom Feature Extractors
+- No user tracking or identifiers
+- Only ad metadata stored (< 200 bytes)
+- Session-scoped, localStorage with memory fallback
+- GDPR/CCPA compliant (contextual, not behavioral)
 
-```javascript
-pbjs.setConfig({
-  realTimeData: {
-    auctionDelay: 250,
-    dataProviders: [{
-      name: 'mixpeek',
-      waitForIt: true,
-      params: {
-        apiKey: 'sk_your_api_key',
-        collectionId: 'col_custom',
-        customExtractors: [
-          {
-            feature_extractor_id: 'sentiment-analyzer',
-            payload: {
-              model: 'sentiment-v2',
-              threshold: 0.7
-            }
-          }
-        ]
-      }
-    }]
-  }
-})
-```
+---
 
-### Conditional Loading
+## OpenRTB 2.6 Output
+
+### Site-Level Data (`ortb2.site.content`)
 
 ```javascript
-// Only enrich on specific pages
-if (window.location.pathname.startsWith('/articles/')) {
-  pbjs.setConfig({
-    realTimeData: {
-      auctionDelay: 250,
-      dataProviders: [{
-        name: 'mixpeek',
-        waitForIt: true,
-        params: {
-          apiKey: 'sk_your_api_key',
-          collectionId: 'col_articles',
-          mode: 'page'
+{
+  "site": {
+    "content": {
+      "cat": ["IAB19-11"],              // IAB Content Categories
+      "cattax": 6,                       // IAB Taxonomy v3.0
+      "genre": "Technology",             // Human-readable category
+      "keywords": "ai,technology,ml",    // Extracted keywords
+      "language": "en",                  // Content language
+      "ext": {
+        "data": {
+          "mixpeek": {
+            "score": 0.94,               // Classification confidence
+            "brandSafety": 0.98,         // Brand safety score
+            "sentiment": "positive"       // Content sentiment
+          }
         }
-      }]
+      }
     }
-  })
+  }
 }
 ```
 
-### Event Callbacks
+### Impression-Level Keys (`ortb2Imp.ext.data`)
 
-```javascript
-pbjs.onEvent('mixpeekContextReady', function(context) {
-  console.log('Mixpeek context loaded:', context)
-  // Custom analytics or modifications
-})
+| Key | Description | Example |
+|-----|-------------|---------|
+| `hb_mixpeek_category` | Content category | `"Technology"` |
+| `hb_mixpeek_score` | Classification confidence | `"0.94"` |
+| `hb_mixpeek_safety` | Brand safety score | `"0.98"` |
+| `hb_mixpeek_keywords` | Extracted keywords | `"AI,ML,tech"` |
+| `hb_mixpeek_sentiment` | Content sentiment | `"positive"` |
+| `hb_mixpeek_prev_creative` | Last creative ID | `"12345"` |
+| `hb_mixpeek_prev_bidder` | Last winning bidder | `"appnexus"` |
+| `hb_mixpeek_prev_cat` | Last ad categories | `"IAB18-1"` |
 
-pbjs.onEvent('mixpeekContextError', function(error) {
-  console.error('Mixpeek context error:', error)
-  // Custom error handling
-})
-```
+---
 
-## 🔄 Previous Ad Tracking (Adjacency Awareness)
+## How It Works
 
-The adapter automatically tracks the most recently served ad to enable adjacency-aware targeting. This helps:
+```
+USER → WEBSITE → PREBID.JS
+                    │
+                    ├──→ MIXPEEK RTD Module
+                    │    (Extract page content)
+                    │    (Get previous ad info)
+                    │    ↓
+                    │    Returns: categories, keywords, sentiment
+                    │    ↓
+                 (enrich bid request with ortb2)
+                    │
+                    ├──→ SSP 1 ──→ DSPs (use contextual signals)
+                    ├──→ SSP 2 ──→ DSPs (use adjacency data)
+                    └──→ SSP N
+
+                 (collect bids)
+                    │
+                    ▼
+                AD SERVER
+                    │
+                    ▼
+               RELEVANT AD
+```
 
-- **Avoid Ad Repetition**: Prevent showing the same creative or category repeatedly
-- **Frequency Capping**: Build frequency cap rules based on previous impressions
-- **Competitive Separation**: Avoid showing competing brands consecutively
-- **Enhanced User Experience**: Improve ad diversity and relevance
+---
 
-### How It Works
+## Content Modes
 
-1. **Automatic Tracking**: On every `bidResponse` event, the adapter stores minimal information about the winning ad
-2. **Lightweight Storage**: Data is stored in memory + localStorage (privacy-safe, no PII)
-3. **Targeting Keys**: Previous ad data is automatically injected into subsequent bid requests
+### Page Context (Default)
 
-### Data Tracked
+```javascript
+params: {
+  mode: 'page',  // Analyze article/page content
+  // ...
+}
+```
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `creativeId` | Winning creative ID | `"12345"` |
-| `bidder` | Winning bidder code | `"appnexus"` |
-| `adUnitCode` | Ad unit that served the ad | `"sidebar-1"` |
-| `categories` | IAB categories of the ad | `["IAB18-1", "IAB12-3"]` |
-| `timestamp` | When the ad was served | `1697123456789` |
+### Video Context
 
-### Targeting Keys Injected
+```javascript
+params: {
+  mode: 'video',
+  videoSelector: '#main-video',  // CSS selector
+  // ...
+}
+```
 
-The following keys are automatically added to `ortb2Imp.ext.data`:
+### Auto-Detection
 
-- `hb_mixpeek_prev_creative` - Last creative ID
-- `hb_mixpeek_prev_bidder` - Last winning bidder
-- `hb_mixpeek_prev_adunit` - Last ad unit code
-- `hb_mixpeek_prev_cat` - Last ad categories (comma-separated)
+```javascript
+params: {
+  mode: 'auto',  // Automatically detect content type
+  // ...
+}
+```
 
-### SSP/DSP Usage
+---
 
-SSPs and DSPs can use these keys for advanced targeting rules:
+## Event Callbacks
 
 ```javascript
-// Example: Avoid showing the same creative twice in a row
-if (bidRequest.ortb2Imp.ext.data.hb_mixpeek_prev_creative === currentCreative.id) {
-  // Skip this creative or reduce bid
-}
-
-// Example: Competitive separation
-const prevCategories = bidRequest.ortb2Imp.ext.data.hb_mixpeek_prev_cat?.split(',') || []
-if (prevCategories.includes('IAB18-1') && currentAd.category === 'IAB18-1') {
-  // Don't show competing fashion ads back-to-back
-}
-```
+// Context ready
+pbjs.onEvent('mixpeekContextReady', function(context) {
+  console.log('Category:', context.taxonomy?.label)
+  console.log('Keywords:', context.keywords)
+})
 
-### Privacy & Storage
+// Error handling
+pbjs.onEvent('mixpeekContextError', function(error) {
+  // Errors don't block auction (graceful degradation)
+  console.error('Mixpeek error:', error)
+})
 
-- **No User Tracking**: Only ad metadata is stored, no user identifiers or behavior
-- **Session-Scoped**: Data persists across page views within a session
-- **Local Storage**: Falls back to memory-only if localStorage is unavailable
-- **Minimal Data**: Only essential fields are stored (< 200 bytes)
-- **GDPR/CCPA Compliant**: No consent required as it doesn't track users
+// Cache hit
+pbjs.onEvent('mixpeekContextCached', function(data) {
+  console.log('Using cached context')
+})
+```
 
-### Programmatic Control
+---
 
-You can access the previous ad tracker directly if needed:
+## Testing
 
-```javascript
-import previousAdTracker from '@mixpeek/prebid/utils/previousAdTracker'
+```bash
+# Run all tests
+npm test
 
-// Get last ad info
-const lastAd = previousAdTracker.getLast()
-console.log('Last creative:', lastAd?.creativeId)
+# Run with live API (requires credentials)
+MIXPEEK_API_KEY=your_key \
+MIXPEEK_NAMESPACE=ns_xxxxx \
+MIXPEEK_COLLECTION_ID=col_xxxxx \
+npm run test:live
 
-// Clear history (e.g., on user logout or page type change)
-previousAdTracker.clear()
+# Coverage report
+npm run test:coverage
 ```
 
-## 🔒 Security & Privacy
-
-- **No PII**: The adapter never sends user identifiers or cookies
-- **Content-Only**: Only page/video content is analyzed
-- **HTTPS**: All API calls use TLS encryption
-- **API Key Safety**: Store API keys securely (environment variables, server-side rendering)
-- **GDPR/CCPA Compliant**: Contextual targeting doesn't require user consent
+---
 
-## 📚 Documentation
+## Documentation
 
-### User Guides
 - [Quick Start](QUICKSTART.md) - Get running in 5 minutes
-- [Integration Guide](docs/integration-guide.md) - Step-by-step integration
-- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Integration Guide](docs/integration-guide.md) - Step-by-step setup
+- [API Reference](docs/api-reference.md) - Complete API docs
 - [Testing Guide](TESTING.md) - How to test the adapter
-- [Endpoint Configuration](ENDPOINTS.md) - Configure API endpoints
-- [Health Check](docs/health-check.md) - Health check configuration
 
-### Developer Resources
-- [Mixpeek API Docs](https://docs.mixpeek.com) - Platform documentation
-- [Internal Planning](tasks/) - Gap analysis & implementation plans (internal)
+---
 
-## 🤝 Support
+## Support
 
-- **Email**: support@mixpeek.com
-- **GitHub Issues**: [Create an issue](https://github.com/mixpeek/prebid/issues)
 - **Documentation**: [docs.mixpeek.com](https://docs.mixpeek.com)
-- **Slack Community**: [Join our Slack](https://mixpeek.com/slack)
-
-## 📄 License
-
-Apache 2.0 - see [LICENSE](LICENSE) file for details.
+- **GitHub Issues**: [Create an issue](https://github.com/mixpeek/prebid/issues)
+- **Email**: support@mixpeek.com
 
-## 🙏 Credits
+---
 
-Built with ❤️ by [Mixpeek](https://mixpeek.com)
+## License
 
-Integrates with [Prebid.js](https://prebid.org) - an open-source header bidding solution
+Apache 2.0 - see [LICENSE](LICENSE)
 
+Built by [Mixpeek](https://mixpeek.com) | Integrates with [Prebid.js](https://prebid.org)