@mixpeek/prebid 1.0.0

package/src/api/mixpeekClient.js

@@ -0,0 +1,303 @@
+/**
+ * Mixpeek Context Adapter - API Client
+ * @module api/mixpeekClient
+ */
+
+import {
+  DEFAULT_API_ENDPOINT,
+  DEFAULT_TIMEOUT,
+  DEFAULT_RETRY_ATTEMPTS,
+  ENDPOINTS,
+  HEADERS,
+  USER_AGENT,
+  ERROR_CODES
+} from '../config/constants.js'
+import { withTimeout, retryWithBackoff, generateUUID } from '../utils/helpers.js'
+import logger from '../utils/logger.js'
+
+class MixpeekClient {
+  constructor(config = {}) {
+    this.apiKey = config.apiKey || ''
+    this.endpoint = config.endpoint || DEFAULT_API_ENDPOINT
+    this.namespace = config.namespace || null
+    this.timeout = config.timeout || DEFAULT_TIMEOUT
+    this.retryAttempts = config.retryAttempts || DEFAULT_RETRY_ATTEMPTS
+  }
+
+  /**
+   * Configure the client
+   * @param {object} config - Configuration object
+   */
+  configure(config) {
+    Object.assign(this, config)
+  }
+
+  /**
+   * Build headers for API request
+   * @private
+   * @returns {object} Headers object
+   */
+  _buildHeaders() {
+    const headers = {
+      [HEADERS.CONTENT_TYPE]: 'application/json',
+      [HEADERS.AUTHORIZATION]: `Bearer ${this.apiKey}`,
+      [HEADERS.USER_AGENT]: USER_AGENT
+    }
+
+    if (this.namespace) {
+      headers[HEADERS.NAMESPACE] = this.namespace
+    }
+
+    return headers
+  }
+
+  /**
+   * Make API request
+   * @private
+   * @param {string} path - API path
+   * @param {object} options - Fetch options
+   * @returns {Promise} Response data
+   */
+  async _request(path, options = {}) {
+    const url = `${this.endpoint}${path}`
+    const headers = this._buildHeaders()
+
+    const fetchOptions = {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers
+      }
+    }
+
+    logger.info(`API Request: ${options.method || 'GET'} ${url}`)
+    logger.time(`API Request: ${path}`)
+
+    try {
+      const response = await withTimeout(
+        fetch(url, fetchOptions),
+        this.timeout
+      )
+
+      logger.timeEnd(`API Request: ${path}`)
+
+      if (!response.ok) {
+        const error = await this._handleErrorResponse(response)
+        throw error
+      }
+
+      const data = await response.json()
+      logger.info('API Response:', { status: response.status, path })
+      return data
+    } catch (error) {
+      logger.timeEnd(`API Request: ${path}`)
+      
+      if (error.message === 'Timeout') {
+        throw {
+          code: ERROR_CODES.API_TIMEOUT,
+          message: `Request timeout after ${this.timeout}ms`,
+          path
+        }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Handle error response
+   * @private
+   * @param {Response} response - Fetch response
+   * @returns {object} Error object
+   */
+  async _handleErrorResponse(response) {
+    let errorMessage = `API error: ${response.status} ${response.statusText}`
+    
+    try {
+      const errorData = await response.json()
+      errorMessage = errorData.message || errorData.error || errorMessage
+    } catch (e) {
+      // Response body is not JSON
+    }
+
+    return {
+      code: ERROR_CODES.API_ERROR,
+      message: errorMessage,
+      status: response.status
+    }
+  }
+
+  /**
+   * Create a document in a collection
+   * @param {string} collectionId - Collection ID
+   * @param {object} payload - Document payload
+   * @returns {Promise} Document data
+   */
+  async createDocument(collectionId, payload) {
+    const path = ENDPOINTS.DOCUMENTS.replace('{collectionId}', collectionId)
+    
+    const requestPayload = {
+      object_id: payload.objectId || generateUUID(),
+      metadata: payload.metadata || {},
+      features: payload.features || []
+    }
+
+    return retryWithBackoff(
+      () => this._request(path, {
+        method: 'POST',
+        body: JSON.stringify(requestPayload)
+      }),
+      this.retryAttempts
+    )
+  }
+
+  /**
+   * Get document by ID
+   * @param {string} collectionId - Collection ID
+   * @param {string} documentId - Document ID
+   * @returns {Promise} Document data
+   */
+  async getDocument(collectionId, documentId) {
+    const path = `${ENDPOINTS.DOCUMENTS.replace('{collectionId}', collectionId)}/${documentId}`
+    return this._request(path, { method: 'GET' })
+  }
+
+  /**
+   * Process content with feature extractors
+   * @param {string} collectionId - Collection ID
+   * @param {object} content - Content to process
+   * @param {array} featureExtractors - Feature extractors to use
+   * @returns {Promise} Enriched document
+   */
+  async processContent(collectionId, content, featureExtractors = []) {
+    logger.group('Processing content with Mixpeek')
+    logger.info('Collection:', collectionId)
+    logger.info('Feature Extractors:', featureExtractors)
+
+    try {
+      // Build features array from extractors
+      const features = featureExtractors.map(extractor => {
+        const feature = {
+          feature_extractor_id: typeof extractor === 'string' ? extractor : extractor.feature_extractor_id
+        }
+
+        // Add payload if provided
+        if (typeof extractor === 'object' && extractor.payload) {
+          feature.payload = extractor.payload
+        } else {
+          // Build payload from content
+          feature.payload = this._buildFeaturePayload(content)
+        }
+
+        return feature
+      })
+
+      // Create document with features
+      const document = await this.createDocument(collectionId, {
+        objectId: this._generateContentId(content),
+        metadata: {
+          url: content.url,
+          title: content.title,
+          timestamp: Date.now()
+        },
+        features
+      })
+
+      logger.info('Document created:', document.document_id)
+      logger.groupEnd()
+
+      return document
+    } catch (error) {
+      logger.error('Error processing content:', error)
+      logger.groupEnd()
+      throw error
+    }
+  }
+
+  /**
+   * Build feature payload from content
+   * @private
+   * @param {object} content - Content object
+   * @returns {object} Feature payload
+   */
+  _buildFeaturePayload(content) {
+    const payload = {}
+
+    // Add text content
+    if (content.text) {
+      payload.text = content.text
+    }
+
+    // Add URL
+    if (content.url) {
+      payload.url = content.url
+    }
+
+    // Add video URL
+    if (content.src && content.duration !== undefined) {
+      // This is video content
+      payload.video_url = content.src
+      payload.title = content.title
+      payload.description = content.description
+    }
+
+    // Add image URL
+    if (content.src && content.width && content.height && !content.duration) {
+      // This is image content
+      payload.image_url = content.src
+      payload.alt_text = content.alt
+    }
+
+    // Add metadata
+    if (content.metadata) {
+      payload.metadata = content.metadata
+    }
+
+    return payload
+  }
+
+  /**
+   * Generate content ID for caching
+   * @private
+   * @param {object} content - Content object
+   * @returns {string} Content ID
+   */
+  _generateContentId(content) {
+    if (content.url) {
+      return `url_${content.url.split('?')[0]}` // Remove query params
+    }
+    if (content.src) {
+      return `src_${content.src.split('?')[0]}`
+    }
+    return generateUUID()
+  }
+
+  /**
+   * List available feature extractors
+   * @returns {Promise} Feature extractors list
+   */
+  async listFeatureExtractors() {
+    return this._request(ENDPOINTS.FEATURE_EXTRACTORS, { method: 'GET' })
+  }
+
+  /**
+   * Get feature extractor details
+   * @param {string} extractorId - Feature extractor ID
+   * @returns {Promise} Feature extractor details
+   */
+  async getFeatureExtractor(extractorId) {
+    const path = ENDPOINTS.FEATURE_EXTRACTORS + `/${extractorId}`
+    return this._request(path, { method: 'GET' })
+  }
+
+  /**
+   * Health check
+   * @returns {Promise} Health status
+   */
+  async healthCheck() {
+    return this._request('/v1/health', { method: 'GET' })
+  }
+}
+
+export default MixpeekClient
+

package/src/cache/cacheManager.js

@@ -0,0 +1,245 @@
+/**
+ * Mixpeek Context Adapter - Cache Manager
+ * @module cache/cacheManager
+ */
+
+import { CACHE_KEYS, DEFAULT_CACHE_TTL } from '../config/constants.js'
+import { getTimestamp, isExpired, safeJSONParse } from '../utils/helpers.js'
+import logger from '../utils/logger.js'
+
+class CacheManager {
+  constructor() {
+    this.memoryCache = new Map()
+    this.useLocalStorage = this._checkLocalStorageAvailable()
+    this.ttl = DEFAULT_CACHE_TTL
+  }
+
+  /**
+   * Check if localStorage is available
+   * @private
+   * @returns {boolean}
+   */
+  _checkLocalStorageAvailable() {
+    try {
+      const test = '__mixpeek_test__'
+      localStorage.setItem(test, test)
+      localStorage.removeItem(test)
+      return true
+    } catch (e) {
+      logger.warn('localStorage not available, using memory cache only')
+      return false
+    }
+  }
+
+  /**
+   * Generate cache key
+   * @private
+   * @param {string} key - Key
+   * @returns {string} Cache key
+   */
+  _getCacheKey(key) {
+    return `${CACHE_KEYS.PREFIX}${CACHE_KEYS.VERSION}_${key}`
+  }
+
+  /**
+   * Set TTL
+   * @param {number} ttl - TTL in seconds
+   */
+  setTTL(ttl) {
+    this.ttl = ttl
+  }
+
+  /**
+   * Get item from cache
+   * @param {string} key - Cache key
+   * @returns {object|null} Cached value or null
+   */
+  get(key) {
+    const cacheKey = this._getCacheKey(key)
+    
+    // Try memory cache first
+    if (this.memoryCache.has(cacheKey)) {
+      const item = this.memoryCache.get(cacheKey)
+      if (!isExpired(item.timestamp, this.ttl)) {
+        logger.info('Cache hit (memory):', key)
+        return item.data
+      } else {
+        logger.info('Cache expired (memory):', key)
+        this.memoryCache.delete(cacheKey)
+      }
+    }
+
+    // Try localStorage
+    if (this.useLocalStorage) {
+      try {
+        const item = localStorage.getItem(cacheKey)
+        if (item) {
+          const parsed = safeJSONParse(item)
+          if (parsed && !isExpired(parsed.timestamp, this.ttl)) {
+            logger.info('Cache hit (localStorage):', key)
+            // Promote to memory cache
+            this.memoryCache.set(cacheKey, parsed)
+            return parsed.data
+          } else {
+            logger.info('Cache expired (localStorage):', key)
+            localStorage.removeItem(cacheKey)
+          }
+        }
+      } catch (e) {
+        logger.warn('Error reading from localStorage:', e)
+      }
+    }
+
+    logger.info('Cache miss:', key)
+    return null
+  }
+
+  /**
+   * Set item in cache
+   * @param {string} key - Cache key
+   * @param {*} data - Data to cache
+   * @returns {boolean} Success
+   */
+  set(key, data) {
+    const cacheKey = this._getCacheKey(key)
+    const item = {
+      data,
+      timestamp: getTimestamp()
+    }
+
+    try {
+      // Store in memory cache
+      this.memoryCache.set(cacheKey, item)
+
+      // Store in localStorage
+      if (this.useLocalStorage) {
+        localStorage.setItem(cacheKey, JSON.stringify(item))
+      }
+
+      logger.info('Cached:', key)
+      return true
+    } catch (e) {
+      logger.warn('Error setting cache:', e)
+      return false
+    }
+  }
+
+  /**
+   * Remove item from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} Success
+   */
+  remove(key) {
+    const cacheKey = this._getCacheKey(key)
+    
+    try {
+      this.memoryCache.delete(cacheKey)
+      if (this.useLocalStorage) {
+        localStorage.removeItem(cacheKey)
+      }
+      logger.info('Cache removed:', key)
+      return true
+    } catch (e) {
+      logger.warn('Error removing cache:', e)
+      return false
+    }
+  }
+
+  /**
+   * Clear all cache
+   * @returns {boolean} Success
+   */
+  clear() {
+    try {
+      this.memoryCache.clear()
+      
+      if (this.useLocalStorage) {
+        const keys = Object.keys(localStorage)
+        keys.forEach(key => {
+          if (key.startsWith(CACHE_KEYS.PREFIX)) {
+            localStorage.removeItem(key)
+          }
+        })
+      }
+      
+      logger.info('Cache cleared')
+      return true
+    } catch (e) {
+      logger.warn('Error clearing cache:', e)
+      return false
+    }
+  }
+
+  /**
+   * Get cache stats
+   * @returns {object} Cache statistics
+   */
+  getStats() {
+    let localStorageSize = 0
+    let localStorageCount = 0
+
+    if (this.useLocalStorage) {
+      try {
+        const keys = Object.keys(localStorage)
+        keys.forEach(key => {
+          if (key.startsWith(CACHE_KEYS.PREFIX)) {
+            localStorageCount++
+            localStorageSize += localStorage.getItem(key).length
+          }
+        })
+      } catch (e) {
+        logger.warn('Error getting cache stats:', e)
+      }
+    }
+
+    return {
+      memoryCount: this.memoryCache.size,
+      localStorageCount,
+      localStorageSize,
+      ttl: this.ttl
+    }
+  }
+
+  /**
+   * Prune expired items
+   * @returns {number} Number of items pruned
+   */
+  prune() {
+    let pruned = 0
+
+    // Prune memory cache
+    for (const [key, item] of this.memoryCache.entries()) {
+      if (isExpired(item.timestamp, this.ttl)) {
+        this.memoryCache.delete(key)
+        pruned++
+      }
+    }
+
+    // Prune localStorage
+    if (this.useLocalStorage) {
+      try {
+        const keys = Object.keys(localStorage)
+        keys.forEach(key => {
+          if (key.startsWith(CACHE_KEYS.PREFIX)) {
+            const item = safeJSONParse(localStorage.getItem(key))
+            if (item && isExpired(item.timestamp, this.ttl)) {
+              localStorage.removeItem(key)
+              pruned++
+            }
+          }
+        })
+      } catch (e) {
+        logger.warn('Error pruning cache:', e)
+      }
+    }
+
+    if (pruned > 0) {
+      logger.info(`Pruned ${pruned} expired cache items`)
+    }
+
+    return pruned
+  }
+}
+
+export default new CacheManager()
+

package/src/config/constants.js

@@ -0,0 +1,125 @@
+/**
+ * Mixpeek Context Adapter - Constants
+ * @module config/constants
+ */
+
+export const MIXPEEK_MODULE_NAME = 'mixpeek'
+export const MIXPEEK_VERSION = '1.0.0'
+
+// API Configuration
+// Use MIXPEEK_API_ENDPOINT environment variable or default to production
+export const DEFAULT_API_ENDPOINT = typeof process !== 'undefined' && process.env && process.env.MIXPEEK_API_ENDPOINT
+  ? process.env.MIXPEEK_API_ENDPOINT
+  : (typeof window !== 'undefined' && window.MIXPEEK_API_ENDPOINT
+    ? window.MIXPEEK_API_ENDPOINT
+    : 'https://api.mixpeek.com')
+
+// Alternative endpoints
+export const API_ENDPOINTS = {
+  PRODUCTION: 'https://api.mixpeek.com',
+  DEVELOPMENT: 'https://server-xb24.onrender.com',
+  LOCAL: 'http://localhost:8000'
+}
+
+export const DEFAULT_TIMEOUT = 250 // milliseconds
+export const DEFAULT_CACHE_TTL = 300 // seconds
+export const DEFAULT_RETRY_ATTEMPTS = 2
+export const DEFAULT_BATCH_SIZE = 1
+
+// API Endpoints
+export const ENDPOINTS = {
+  COLLECTIONS: '/v1/collections',
+  DOCUMENTS: '/v1/collections/{collectionId}/documents',
+  FEATURES: '/v1/collections/{collectionId}/documents/{documentId}/features',
+  FEATURE_EXTRACTORS: '/v1/collections/features/extractors',
+  RETRIEVERS: '/v1/retrievers/debug-inference'
+}
+
+// Content Modes
+export const CONTENT_MODES = {
+  AUTO: 'auto',
+  PAGE: 'page',
+  VIDEO: 'video',
+  IMAGE: 'image'
+}
+
+// Feature Extractors
+export const FEATURE_EXTRACTORS = {
+  TAXONOMY: 'taxonomy',
+  BRAND_SAFETY: 'brand-safety',
+  KEYWORDS: 'keywords',
+  SENTIMENT: 'sentiment',
+  CLUSTERING: 'clustering',
+  EMBEDDING: 'embedding'
+}
+
+// Targeting Key Prefixes
+export const TARGETING_KEYS = {
+  TAXONOMY: 'hb_mixpeek_taxonomy',
+  CATEGORY: 'hb_mixpeek_category',
+  NODE: 'hb_mixpeek_node',
+  PATH: 'hb_mixpeek_path',
+  SCORE: 'hb_mixpeek_score',
+  SAFETY: 'hb_mixpeek_safety',
+  KEYWORDS: 'hb_mixpeek_keywords',
+  EMBED: 'hb_mixpeek_embed',
+  SENTIMENT: 'hb_mixpeek_sentiment',
+  // Previous ad context
+  PREV_AD_CREATIVE_ID: 'hb_mixpeek_prev_creative',
+  PREV_AD_BIDDER: 'hb_mixpeek_prev_bidder',
+  PREV_AD_ADUNIT: 'hb_mixpeek_prev_adunit',
+  PREV_AD_CAT: 'hb_mixpeek_prev_cat'
+}
+
+// Error Codes
+export const ERROR_CODES = {
+  INVALID_CONFIG: 'INVALID_CONFIG',
+  API_TIMEOUT: 'API_TIMEOUT',
+  API_ERROR: 'API_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  INVALID_RESPONSE: 'INVALID_RESPONSE',
+  MISSING_CONTENT: 'MISSING_CONTENT',
+  CACHE_ERROR: 'CACHE_ERROR'
+}
+
+// Cache Configuration
+export const CACHE_KEYS = {
+  PREFIX: 'mixpeek_ctx_',
+  VERSION: 'v1'
+}
+
+// Performance Thresholds
+export const PERFORMANCE = {
+  MAX_LATENCY: 250, // ms
+  WARN_LATENCY: 100, // ms
+  MAX_CONTENT_SIZE: 50000 // characters
+}
+
+// Default Feature Extractor Configurations
+export const DEFAULT_EXTRACTORS = [
+  {
+    type: FEATURE_EXTRACTORS.TAXONOMY,
+    enabled: true
+  }
+]
+
+// Event Names
+export const EVENTS = {
+  CONTEXT_READY: 'mixpeekContextReady',
+  CONTEXT_ERROR: 'mixpeekContextError',
+  CONTEXT_CACHED: 'mixpeekContextCached',
+  API_REQUEST: 'mixpeekApiRequest',
+  API_RESPONSE: 'mixpeekApiResponse'
+}
+
+// HTTP Headers
+export const HEADERS = {
+  AUTHORIZATION: 'Authorization',
+  NAMESPACE: 'X-Namespace',
+  CONTENT_TYPE: 'Content-Type',
+  USER_AGENT: 'User-Agent'
+}
+
+// User Agent
+export const USER_AGENT = `Mixpeek-Prebid-Adapter/${MIXPEEK_VERSION}`
+