@mixpeek/prebid 1.0.0

package/src/modules/mixpeekRtdProvider.js

@@ -0,0 +1,305 @@
+/**
+ * Mixpeek Real-Time Data (RTD) Provider for Prebid.js
+ * @module modules/mixpeekRtdProvider
+ * 
+ * This module implements the official Prebid RTD submodule interface
+ * to enrich bid requests with Mixpeek's multimodal contextual data.
+ * 
+ * References:
+ * - Prebid RTD Module Docs: https://docs.prebid.org/dev-docs/add-rtd-submodule.html
+ * - Qortex Implementation: https://github.com/prebid/Prebid.js/blob/master/modules/qortexRtdProvider.js
+ * - OpenRTB 2.6 Spec: https://www.iab.com/wp-content/uploads/2020/09/OpenRTB_2-6_FINAL.pdf
+ */
+
+import adapter from './mixpeekContextAdapter.js'
+import { logInfo, logWarn, logError } from '../utils/logger.js'
+import { isBrowser } from '../utils/helpers.js'
+
+/**
+ * Module name (used for registration)
+ */
+const MODULE_NAME = 'mixpeek'
+
+/**
+ * Mixpeek RTD Submodule
+ * 
+ * Implements the standard Prebid RTD interface:
+ * - init(): Initialize the module with configuration
+ * - getBidRequestData(): Enrich bid requests with contextual data
+ * - getTargetingData(): Provide targeting key-values for ad server
+ */
+export const mixpeekSubmodule = {
+  name: MODULE_NAME,
+  
+  /**
+   * Initialize the Mixpeek RTD module
+   * 
+   * @param {Object} config - Module configuration from realTimeData.dataProviders[]
+   * @param {Object} config.params - Mixpeek-specific parameters
+   * @param {string} config.params.apiKey - Mixpeek API key
+   * @param {string} config.params.collectionId - Mixpeek collection ID
+   * @param {string} [config.params.endpoint] - API endpoint
+   * @param {string} [config.params.namespace] - Namespace for data isolation
+   * @param {string} [config.params.mode='auto'] - Content mode (auto, page, video, image)
+   * @param {Array<string>} [config.params.featureExtractors] - Feature extractors to use
+   * @param {number} [config.params.timeout=250] - API timeout in ms
+   * @param {number} [config.params.cacheTTL=300] - Cache TTL in seconds
+   * @param {boolean} [config.params.enableCache=true] - Enable caching
+   * @param {boolean} [config.params.debug=false] - Debug mode
+   * @param {Object} userConsent - User consent data (GDPR, USP)
+   * @param {Object} [userConsent.gdpr] - GDPR consent data
+   * @param {boolean} [userConsent.gdpr.gdprApplies] - Whether GDPR applies
+   * @param {Object} [userConsent.gdpr.purposeConsents] - Purpose consents
+   * @param {string} [userConsent.usp] - USP consent string
+   * @returns {boolean} True if initialization successful
+   */
+  init: function(config, userConsent) {
+    logInfo(`[${MODULE_NAME}] Initializing Mixpeek RTD module`)
+    
+    // Validate configuration
+    if (!config || !config.params) {
+      logError(`[${MODULE_NAME}] Configuration is required`)
+      return false
+    }
+    
+    const params = config.params
+    
+    // Validate required parameters
+    if (!params.apiKey) {
+      logError(`[${MODULE_NAME}] apiKey is required`)
+      return false
+    }
+    
+    if (!params.collectionId) {
+      logError(`[${MODULE_NAME}] collectionId is required`)
+      return false
+    }
+    
+    // Log consent state (for transparency and debugging)
+    if (userConsent) {
+      if (userConsent.gdpr) {
+        logInfo(`[${MODULE_NAME}] GDPR applies: ${userConsent.gdpr.gdprApplies}`)
+        if (userConsent.gdpr.gdprApplies && params.debug) {
+          logInfo(`[${MODULE_NAME}] Purpose consents:`, userConsent.gdpr.purposeConsents)
+        }
+      }
+      
+      if (userConsent.usp) {
+        logInfo(`[${MODULE_NAME}] USP consent string: ${userConsent.usp}`)
+      }
+    }
+    
+    // Note: Contextual analysis doesn't require user consent as it only
+    // analyzes page content, not user behavior. However, we respect the
+    // consent framework and log the state for transparency.
+    
+    // Initialize the adapter
+    try {
+      const success = adapter.init(params)
+      
+      if (success) {
+        logInfo(`[${MODULE_NAME}] Successfully initialized`)
+      } else {
+        logError(`[${MODULE_NAME}] Initialization failed`)
+      }
+      
+      return success
+    } catch (error) {
+      logError(`[${MODULE_NAME}] Initialization error:`, error)
+      return false
+    }
+  },
+  
+  /**
+   * Get real-time data and enrich bid request
+   * 
+   * This is the core method that:
+   * 1. Extracts page/video content
+   * 2. Calls Mixpeek API (with caching)
+   * 3. Formats response as OpenRTB 2.6 data
+   * 4. Injects into ortb2Fragments (site-level) and ortb2Imp (impression-level)
+   * 5. Calls callback to release the auction
+   * 
+   * @param {Object} reqBidsConfigObj - Bid request configuration
+   * @param {Array} reqBidsConfigObj.adUnits - Ad units for the auction
+   * @param {Object} reqBidsConfigObj.ortb2Fragments - ortb2 data fragments
+   * @param {Function} callback - Callback to call when done (REQUIRED)
+   * @param {Object} config - Module configuration
+   * @param {Object} userConsent - User consent data
+   */
+  getBidRequestData: function(reqBidsConfigObj, callback, config, userConsent) {
+    logInfo(`[${MODULE_NAME}] getBidRequestData called`)
+    
+    // Ensure we have a callback
+    if (typeof callback !== 'function') {
+      logError(`[${MODULE_NAME}] Callback is required`)
+      return
+    }
+    
+    // Check if adapter is initialized
+    if (!adapter.initialized) {
+      logWarn(`[${MODULE_NAME}] Adapter not initialized, skipping enrichment`)
+      callback()
+      return
+    }
+    
+    // Check if in browser environment
+    if (!isBrowser()) {
+      logWarn(`[${MODULE_NAME}] Not in browser environment, skipping enrichment`)
+      callback()
+      return
+    }
+    
+    // Get context from adapter (async)
+    adapter.getContext()
+      .then(context => {
+        if (!context) {
+          logWarn(`[${MODULE_NAME}] No context data available`)
+          callback()
+          return
+        }
+        
+        logInfo(`[${MODULE_NAME}] Context retrieved successfully`)
+        
+        // Format for ortb2Fragments (site-level global data)
+        const ortb2Fragments = adapter.formatForOrtb2Fragments(context)
+        
+        if (ortb2Fragments) {
+          // Initialize ortb2Fragments if needed
+          if (!reqBidsConfigObj.ortb2Fragments) {
+            reqBidsConfigObj.ortb2Fragments = {}
+          }
+          if (!reqBidsConfigObj.ortb2Fragments.global) {
+            reqBidsConfigObj.ortb2Fragments.global = {}
+          }
+          
+          // Merge site.content data
+          if (ortb2Fragments.global.site) {
+            if (!reqBidsConfigObj.ortb2Fragments.global.site) {
+              reqBidsConfigObj.ortb2Fragments.global.site = {}
+            }
+            
+            // Merge content data (deep merge to preserve existing data)
+            Object.assign(
+              reqBidsConfigObj.ortb2Fragments.global.site,
+              ortb2Fragments.global.site
+            )
+            
+            logInfo(`[${MODULE_NAME}] Injected site.content data:`, 
+              reqBidsConfigObj.ortb2Fragments.global.site.content)
+          }
+        }
+        
+        // Also enrich ad units (impression-level data)
+        if (reqBidsConfigObj.adUnits && Array.isArray(reqBidsConfigObj.adUnits)) {
+          try {
+            reqBidsConfigObj.adUnits = adapter._injectTargetingKeys(
+              reqBidsConfigObj.adUnits,
+              context
+            )
+            
+            logInfo(`[${MODULE_NAME}] Enriched ${reqBidsConfigObj.adUnits.length} ad units`)
+          } catch (error) {
+            logError(`[${MODULE_NAME}] Error enriching ad units:`, error)
+          }
+        }
+        
+        // Success - release auction
+        callback()
+      })
+      .catch(error => {
+        logError(`[${MODULE_NAME}] Error getting context:`, error)
+        
+        // Don't block the auction on error - graceful degradation
+        callback()
+      })
+  },
+  
+  /**
+   * Get targeting data for ad server
+   * 
+   * This method is called after the auction to get key-value pairs
+   * that should be sent to the ad server (e.g., GAM, AppNexus).
+   * 
+   * @param {Array<string>} adUnitsCodes - Ad unit codes to get targeting for
+   * @param {Object} config - Module configuration
+   * @returns {Object} Targeting data object keyed by ad unit code
+   */
+  getTargetingData: function(adUnitsCodes, config) {
+    logInfo(`[${MODULE_NAME}] getTargetingData called for ${adUnitsCodes?.length || 0} ad units`)
+    
+    // Get current context data
+    const context = adapter.getContextData()
+    
+    if (!context) {
+      logWarn(`[${MODULE_NAME}] No context data available for targeting`)
+      return {}
+    }
+    
+    // Build targeting key-values
+    const targetingKeys = adapter._buildTargetingKeys(context)
+    
+    // Return same targeting for all ad units (site-level context)
+    // Format: { adUnitCode1: { key: value }, adUnitCode2: { key: value } }
+    const targetingData = {}
+    
+    if (Array.isArray(adUnitsCodes)) {
+      adUnitsCodes.forEach(code => {
+        targetingData[code] = targetingKeys
+      })
+    }
+    
+    logInfo(`[${MODULE_NAME}] Returning targeting data for ${Object.keys(targetingData).length} ad units`)
+    
+    return targetingData
+  }
+}
+
+/**
+ * Register submodule with Prebid
+ * 
+ * This is called when the module is loaded. It registers the mixpeekSubmodule
+ * with Prebid's Real-Time Data module system.
+ * 
+ * Note: This requires Prebid.js to have the realTimeData module included.
+ */
+function registerSubmodule() {
+  if (typeof window !== 'undefined' && window.pbjs) {
+    // Check if RTD module is loaded
+    if (!window.pbjs.registerRtdSubmodule) {
+      logError(`[${MODULE_NAME}] Prebid RTD module not loaded. Please include realTimeData module in your Prebid build.`)
+      return false
+    }
+    
+    try {
+      window.pbjs.registerRtdSubmodule(mixpeekSubmodule)
+      logInfo(`[${MODULE_NAME}] RTD submodule registered successfully`)
+      return true
+    } catch (error) {
+      logError(`[${MODULE_NAME}] Failed to register RTD submodule:`, error)
+      return false
+    }
+  } else {
+    // Not in browser or Prebid not loaded yet
+    // This is normal during build/test
+    return false
+  }
+}
+
+// Auto-register when loaded in browser
+if (isBrowser()) {
+  // Use Prebid's queue to ensure Prebid is loaded
+  window.pbjs = window.pbjs || {}
+  window.pbjs.que = window.pbjs.que || []
+  window.pbjs.que.push(function() {
+    registerSubmodule()
+  })
+}
+
+// Export for testing and direct usage
+export default {
+  name: MODULE_NAME,
+  submodule: mixpeekSubmodule,
+  registerSubmodule
+}
+

package/src/prebid/prebidIntegration.js

@@ -0,0 +1,117 @@
+/**
+ * Prebid.js Integration Module
+ * @module prebid/prebidIntegration
+ * 
+ * This module registers the Mixpeek Context Adapter with Prebid.js and
+ * hooks into the bidding lifecycle to enrich requests with contextual data.
+ */
+
+import adapter from '../modules/mixpeekContextAdapter.js'
+import logger from '../utils/logger.js'
+import previousAdTracker from '../utils/previousAdTracker.js'
+
+/**
+ * Register Mixpeek adapter with Prebid.js
+ */
+export function registerWithPrebid() {
+  if (typeof window === 'undefined' || !window.pbjs) {
+    logger.error('Prebid.js not found. Make sure Prebid.js is loaded before the Mixpeek adapter.')
+    return false
+  }
+
+  const pbjs = window.pbjs
+
+  logger.info('Registering Mixpeek Context Adapter with Prebid.js')
+
+  // Hook into Prebid configuration
+  pbjs.que = pbjs.que || []
+  pbjs.que.push(function() {
+    // Listen for setConfig events
+    pbjs.onEvent('setConfig', function(config) {
+      if (config.mixpeek) {
+        logger.info('Mixpeek configuration detected')
+        adapter.init(config.mixpeek)
+      }
+    })
+
+    // Hook into beforeRequestBids
+    pbjs.onEvent('beforeRequestBids', async function(bidRequest) {
+      logger.info('beforeRequestBids triggered')
+      
+      if (!adapter.initialized) {
+        logger.warn('Adapter not initialized, skipping enrichment')
+        return
+      }
+
+      try {
+        // Enrich ad units
+        const enrichedAdUnits = await adapter.enrichAdUnits(bidRequest.adUnits || [])
+        
+        // Update bid request
+        if (bidRequest.adUnits) {
+          bidRequest.adUnits = enrichedAdUnits
+        }
+      } catch (error) {
+        logger.error('Error in beforeRequestBids:', error)
+        // Don't block the auction
+      }
+    })
+
+    // Hook into bidResponse to add analytics
+    pbjs.onEvent('bidResponse', function(bidResponse) {
+      // Record previous ad for adjacency/frequency awareness
+      try {
+        previousAdTracker.record(bidResponse)
+      } catch (e) {
+        // non-blocking
+      }
+
+      const context = adapter.getContextData()
+      if (context) {
+        // Add context data to bid response for analytics
+        bidResponse.mixpeekContext = {
+          taxonomy: context.taxonomy?.label,
+          score: context.taxonomy?.score,
+          brandSafety: context.brandSafety
+        }
+      }
+    })
+
+    logger.info('Mixpeek Context Adapter registered with Prebid.js')
+  })
+
+  return true
+}
+
+/**
+ * Initialize Mixpeek with Prebid config
+ * @param {object} config - Configuration object
+ */
+export function initialize(config) {
+  if (!config) {
+    logger.error('Configuration is required')
+    return false
+  }
+
+  // Initialize adapter
+  const success = adapter.init(config)
+  
+  if (success) {
+    // Register with Prebid
+    registerWithPrebid()
+  }
+
+  return success
+}
+
+// Auto-register if Prebid is already loaded
+if (typeof window !== 'undefined' && window.pbjs) {
+  registerWithPrebid()
+}
+
+export default {
+  initialize,
+  registerWithPrebid,
+  adapter
+}
+

package/src/utils/helpers.js

@@ -0,0 +1,261 @@
+/**
+ * Mixpeek Context Adapter - Helper Utilities
+ * @module utils/helpers
+ */
+
+import { ERROR_CODES, PERFORMANCE } from '../config/constants.js'
+import logger from './logger.js'
+
+/**
+ * Generate a unique identifier
+ * @returns {string} UUID v4
+ */
+export function generateUUID() {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+    const r = Math.random() * 16 | 0
+    const v = c === 'x' ? r : (r & 0x3 | 0x8)
+    return v.toString(16)
+  })
+}
+
+/**
+ * Generate a hash from a string
+ * @param {string} str - String to hash
+ * @returns {string} Hash
+ */
+export function hashString(str) {
+  let hash = 0
+  if (str.length === 0) return hash.toString()
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i)
+    hash = ((hash << 5) - hash) + char
+    hash = hash & hash // Convert to 32bit integer
+  }
+  return Math.abs(hash).toString(36)
+}
+
+/**
+ * Check if a value is a valid object
+ * @param {*} value - Value to check
+ * @returns {boolean}
+ */
+export function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Deep merge two objects
+ * @param {object} target - Target object
+ * @param {object} source - Source object
+ * @returns {object} Merged object
+ */
+export function deepMerge(target, source) {
+  const output = Object.assign({}, target)
+  if (isObject(target) && isObject(source)) {
+    Object.keys(source).forEach(key => {
+      if (isObject(source[key])) {
+        if (!(key in target)) {
+          Object.assign(output, { [key]: source[key] })
+        } else {
+          output[key] = deepMerge(target[key], source[key])
+        }
+      } else {
+        Object.assign(output, { [key]: source[key] })
+      }
+    })
+  }
+  return output
+}
+
+/**
+ * Validate configuration
+ * @param {object} config - Configuration object
+ * @returns {object} Validation result
+ */
+export function validateConfig(config) {
+  const errors = []
+
+  if (!config.apiKey || typeof config.apiKey !== 'string') {
+    errors.push('apiKey is required and must be a string')
+  }
+
+  if (!config.collectionId || typeof config.collectionId !== 'string') {
+    errors.push('collectionId is required and must be a string')
+  }
+
+  if (config.timeout && (typeof config.timeout !== 'number' || config.timeout < 0)) {
+    errors.push('timeout must be a positive number')
+  }
+
+  if (config.cacheTTL && (typeof config.cacheTTL !== 'number' || config.cacheTTL < 0)) {
+    errors.push('cacheTTL must be a positive number')
+  }
+
+  if (errors.length > 0) {
+    return {
+      valid: false,
+      errors,
+      code: ERROR_CODES.INVALID_CONFIG
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Truncate text to max length
+ * @param {string} text - Text to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated text
+ */
+export function truncateText(text, maxLength = PERFORMANCE.MAX_CONTENT_SIZE) {
+  if (!text || text.length <= maxLength) return text
+  logger.warn(`Content truncated from ${text.length} to ${maxLength} characters`)
+  return text.substring(0, maxLength)
+}
+
+/**
+ * Extract domain from URL
+ * @param {string} url - URL to extract domain from
+ * @returns {string} Domain
+ */
+export function extractDomain(url) {
+  try {
+    const urlObj = new URL(url)
+    return urlObj.hostname
+  } catch (e) {
+    return ''
+  }
+}
+
+/**
+ * Sanitize text content
+ * @param {string} text - Text to sanitize
+ * @returns {string} Sanitized text
+ */
+export function sanitizeText(text) {
+  if (!text) return ''
+  return text
+    .replace(/\s+/g, ' ') // Normalize whitespace
+    .replace(/[\r\n\t]/g, ' ') // Remove newlines and tabs
+    .trim()
+}
+
+/**
+ * Check if running in browser environment
+ * @returns {boolean}
+ */
+export function isBrowser() {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+/**
+ * Parse JSON safely
+ * @param {string} json - JSON string
+ * @param {*} fallback - Fallback value
+ * @returns {*} Parsed JSON or fallback
+ */
+export function safeJSONParse(json, fallback = null) {
+  try {
+    return JSON.parse(json)
+  } catch (e) {
+    logger.warn('Failed to parse JSON:', e)
+    return fallback
+  }
+}
+
+/**
+ * Retry a function with exponential backoff
+ * @param {Function} fn - Function to retry
+ * @param {number} maxAttempts - Maximum number of attempts
+ * @param {number} delay - Initial delay in ms
+ * @returns {Promise} Result of function
+ */
+export async function retryWithBackoff(fn, maxAttempts = 3, delay = 100) {
+  let lastError
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (attempt < maxAttempts) {
+        const backoffDelay = delay * Math.pow(2, attempt - 1)
+        logger.warn(`Attempt ${attempt} failed, retrying in ${backoffDelay}ms...`)
+        await new Promise(resolve => setTimeout(resolve, backoffDelay))
+      }
+    }
+  }
+  throw lastError
+}
+
+/**
+ * Create a timeout promise
+ * @param {number} ms - Timeout in milliseconds
+ * @returns {Promise} Timeout promise
+ */
+export function timeout(ms) {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error('Timeout')), ms)
+  })
+}
+
+/**
+ * Race a promise against a timeout
+ * @param {Promise} promise - Promise to race
+ * @param {number} ms - Timeout in milliseconds
+ * @returns {Promise} Result or timeout error
+ */
+export function withTimeout(promise, ms) {
+  return Promise.race([promise, timeout(ms)])
+}
+
+/**
+ * Format taxonomy path
+ * @param {array} path - Taxonomy path array
+ * @returns {string} Formatted path
+ */
+export function formatTaxonomyPath(path) {
+  if (!Array.isArray(path) || path.length === 0) return ''
+  return path.join('/')
+}
+
+/**
+ * Extract keywords from text
+ * @param {string} text - Text to extract keywords from
+ * @param {number} maxKeywords - Maximum number of keywords
+ * @returns {array} Array of keywords
+ */
+export function extractKeywords(text, maxKeywords = 10) {
+  if (!text) return []
+  
+  // Simple keyword extraction (in production, use NLP libraries)
+  const words = text.toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(word => word.length > 3)
+  
+  // Get unique words
+  const uniqueWords = [...new Set(words)]
+  
+  // Return top N keywords
+  return uniqueWords.slice(0, maxKeywords)
+}
+
+/**
+ * Get current timestamp
+ * @returns {number} Timestamp in seconds
+ */
+export function getTimestamp() {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ * Check if value is expired
+ * @param {number} timestamp - Timestamp in seconds
+ * @param {number} ttl - TTL in seconds
+ * @returns {boolean} True if expired
+ */
+export function isExpired(timestamp, ttl) {
+  return getTimestamp() - timestamp > ttl
+}
+