@el7ven/cookie-kit 0.3.1 → 0.3.2

package/src/core/StorageAdapter.js

@@ -0,0 +1,179 @@
+/**
+ * Safe Storage Adapter — handles localStorage failures (Safari private mode, quota exceeded)
+ * @module StorageAdapter
+ */
+
+export class StorageAdapter {
+  constructor(config = {}) {
+    this.storageType = config.storageType || 'localStorage'
+    this.storageKey = config.storageKey || 'cookie_consent'
+    this.cookieExpireDays = config.consentExpireDays || 365
+    this._testStorage()
+  }
+
+  /**
+   * Test if storage is available (Safari private mode blocks localStorage)
+   */
+  _testStorage() {
+    this.isLocalStorageAvailable = false
+    this.isCookieAvailable = false
+
+    // Test localStorage
+    if (typeof window !== 'undefined' && window.localStorage) {
+      try {
+        const testKey = '__storage_test__'
+        localStorage.setItem(testKey, 'test')
+        localStorage.removeItem(testKey)
+        this.isLocalStorageAvailable = true
+      } catch (e) {
+        console.warn('[StorageAdapter] localStorage not available:', e.message)
+      }
+    }
+
+    // Test cookies
+    if (typeof document !== 'undefined') {
+      try {
+        document.cookie = '__cookie_test__=test; path=/; SameSite=Lax'
+        this.isCookieAvailable = document.cookie.includes('__cookie_test__')
+        document.cookie = '__cookie_test__=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;'
+      } catch (e) {
+        console.warn('[StorageAdapter] Cookies not available:', e.message)
+      }
+    }
+  }
+
+  /**
+   * Get data from storage
+   */
+  get(key = null) {
+    const storageKey = key || this.storageKey
+
+    try {
+      // Try localStorage first
+      if (this.storageType === 'localStorage' || this.storageType === 'both') {
+        if (this.isLocalStorageAvailable) {
+          const value = localStorage.getItem(storageKey)
+          if (value) return value
+        }
+      }
+
+      // Fallback to cookies
+      if (this.storageType === 'cookie' || this.storageType === 'both') {
+        if (this.isCookieAvailable) {
+          return this._readCookie(storageKey)
+        }
+      }
+
+      return null
+    } catch (e) {
+      console.error('[StorageAdapter] Error reading storage:', e)
+      return null
+    }
+  }
+
+  /**
+   * Set data to storage
+   */
+  set(key, value) {
+    const storageKey = typeof key === 'string' ? key : this.storageKey
+    const data = typeof key === 'string' ? value : key
+
+    // Validate data before saving
+    if (data === null || data === undefined) {
+      console.warn('[StorageAdapter] Attempted to save null/undefined data, skipping')
+      return false
+    }
+    
+    if (typeof data === 'string' && (data === 'null' || data === 'undefined')) {
+      console.warn('[StorageAdapter] Attempted to save literal "null"/"undefined" string, skipping')
+      return false
+    }
+
+    try {
+      // Try localStorage
+      if (this.storageType === 'localStorage' || this.storageType === 'both') {
+        if (this.isLocalStorageAvailable) {
+          try {
+            localStorage.setItem(storageKey, data)
+          } catch (e) {
+            // Quota exceeded — try to clear old data
+            if (e.name === 'QuotaExceededError') {
+              console.warn('[StorageAdapter] localStorage quota exceeded, falling back to cookies')
+              this.isLocalStorageAvailable = false
+            }
+          }
+        }
+      }
+
+      // Fallback to cookies
+      if (this.storageType === 'cookie' || this.storageType === 'both') {
+        if (this.isCookieAvailable) {
+          this._writeCookie(storageKey, data, this.cookieExpireDays)
+        }
+      }
+
+      return true
+    } catch (e) {
+      console.error('[StorageAdapter] Error writing storage:', e)
+      return false
+    }
+  }
+
+  /**
+   * Remove data from storage
+   */
+  remove(key = null) {
+    const storageKey = key || this.storageKey
+
+    try {
+      // Remove from localStorage
+      if (this.storageType === 'localStorage' || this.storageType === 'both') {
+        if (this.isLocalStorageAvailable) {
+          localStorage.removeItem(storageKey)
+        }
+      }
+
+      // Remove from cookies
+      if (this.storageType === 'cookie' || this.storageType === 'both') {
+        if (this.isCookieAvailable) {
+          this._writeCookie(storageKey, '', -1)
+        }
+      }
+
+      return true
+    } catch (e) {
+      console.error('[StorageAdapter] Error removing storage:', e)
+      return false
+    }
+  }
+
+  /**
+   * Check if storage is available
+   */
+  isAvailable() {
+    return this.isLocalStorageAvailable || this.isCookieAvailable
+  }
+
+  /**
+   * Get storage type being used
+   */
+  getActiveStorageType() {
+    if (this.isLocalStorageAvailable) return 'localStorage'
+    if (this.isCookieAvailable) return 'cookie'
+    return 'none'
+  }
+
+  // --- Cookie helpers ---
+
+  _readCookie(name) {
+    if (typeof document === 'undefined') return null
+    const match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'))
+    return match ? decodeURIComponent(match[2]) : null
+  }
+
+  _writeCookie(name, value, days) {
+    if (typeof document === 'undefined') return
+    const expires = new Date(Date.now() + days * 864e5).toUTCString()
+    document.cookie = `${name}=${encodeURIComponent(value)}; expires=${expires}; path=/; SameSite=Lax`
+  }
+}

package/src/geo/GeoDetector.js

@@ -0,0 +1,536 @@
+/**
+ * GeoDetector — detect user's geographic region
+ * @module GeoDetector
+ */
+
+import { getRegion, requiresConsentBanner } from './RegionRules.js'
+
+export class GeoDetector {
+  constructor(config = {}) {
+    this.config = {
+      mode: 'auto', // 'auto' | 'eu-only' | 'always' | 'never'
+
+      // Detection methods (in order of preference)
+      useEdgeHeaders: true,    // CF-IPCountry, X-Vercel-IP-Country, etc
+      useIPAPI: true,           // ipapi.co, ipinfo.io (requires API call)
+      useTimezoneFallback: true, // Browser timezone (approximate)
+
+      // IP API settings
+      ipApiUrl: 'https://ipinfo.io/json',
+      ipApiTimeout: 3000,
+      ipApiToken: null, // Add an API key to increase limits
+
+      // Backup IP APIs
+      backupIpApiUrl: 'https://ipinfo.io/json',
+      freeGeoIpUrl: 'https://freegeoip.app/json/',
+      ipApiComUrl: 'https://ip-api.com/json/',
+
+      // Cache settings
+      cacheRegion: true,
+      cacheKey: 'cmp_user_region',
+      cacheDuration: 24 * 60 * 60 * 1000, // 24h for production
+
+      debug: false,
+      ...config
+    }
+
+    this.detectedRegion = null
+    this.detectionMethod = null
+  }
+
+  /**
+   * Detect user's region
+   * @returns {Promise<string>} Region code (EU, UK, US_CA, ROW, etc)
+   */
+  async detect() {
+    this._debug('Starting geo detection...')
+
+    // Check cache first
+    if (this.config.cacheRegion) {
+      const cached = this._getCachedRegion()
+      if (cached) {
+        this._debug('Using cached region:', cached)
+        this.detectedRegion = cached.region
+        this.detectionMethod = 'cache'
+        return cached.region
+      }
+    }
+
+    let countryCode = null
+    let stateCode = null
+
+    // 1. Try edge headers (fastest, most accurate)
+    if (this.config.useEdgeHeaders) {
+      const edgeResult = this._detectFromEdgeHeaders()
+      if (edgeResult) {
+        countryCode = edgeResult.country
+        stateCode = edgeResult.state
+        this.detectionMethod = 'edge-headers'
+        this._debug('Detected from edge headers:', countryCode)
+      }
+    }
+
+    // 2. Try IP API (requires network request)
+    if (!countryCode && this.config.useIPAPI) {
+      // Try primary API (ipinfo.io)
+      try {
+        const ipResult = await this._detectFromIPAPI()
+        if (ipResult) {
+          countryCode = ipResult.country
+          stateCode = ipResult.state
+          this.detectionMethod = 'ip-api'
+          this._debug('Detected from IP API:', countryCode)
+        }
+      } catch (error) {
+        this._debug('Primary IP API failed:', error)
+
+        // Try freegeoip.app
+        try {
+          const freeResult = await this._detectFromFreeGeoIp()
+          if (freeResult) {
+            countryCode = freeResult.country
+            stateCode = freeResult.state
+            this.detectionMethod = 'free-geo-ip'
+            this._debug('Detected from freegeoip.app:', countryCode)
+          }
+        } catch (freeError) {
+          this._debug('freegeoip.app failed:', freeError)
+
+          // Try ip-api.com
+          try {
+            const comResult = await this._detectFromIpApiCom()
+            if (comResult) {
+              countryCode = comResult.country
+              stateCode = comResult.state
+              this.detectionMethod = 'ip-api-com'
+              this._debug('Detected from ip-api.com:', countryCode)
+            }
+          } catch (comError) {
+            this._debug('ip-api.com also failed:', comError)
+          }
+        }
+      }
+    }
+
+    // 3. Fallback to timezone (approximate)
+    if (!countryCode && this.config.useTimezoneFallback) {
+      countryCode = this._detectFromTimezone()
+      this.detectionMethod = 'timezone-fallback'
+      this._debug('Detected from timezone (approximate):', countryCode)
+    }
+
+    // Get region from country code
+    const region = countryCode ? getRegion(countryCode, stateCode) : 'ROW'
+    this.detectedRegion = region
+
+    this._debug(`Country: ${countryCode}, State: ${stateCode}, Region: ${region}`)
+
+    // Cache result
+    if (this.config.cacheRegion) {
+      this._cacheRegion(region)
+    }
+
+    this._debug(`Region detected: ${region} (method: ${this.detectionMethod})`)
+    return region
+  }
+
+  /**
+   * Check if consent banner should be shown
+   * @returns {Promise<boolean>}
+   */
+  async shouldShowBanner() {
+    const mode = this.config.mode
+
+    // Mode overrides
+    if (mode === 'always') return true
+    if (mode === 'never') return false
+
+    // Detect region
+    const region = await this.detect()
+
+    if (mode === 'eu-only') {
+      // Show only for EU/EEA/UK/CH
+      return ['EU', 'EEA', 'UK', 'CH'].includes(region)
+    }
+
+    // Auto mode: show if region requires consent
+    return requiresConsentBanner(region)
+  }
+
+  /**
+   * Get detected region (without re-detecting)
+   * @returns {string|null}
+   */
+  getRegion() {
+    return this.detectedRegion
+  }
+
+  /**
+   * Get detection method used
+   * @returns {string|null}
+   */
+  getDetectionMethod() {
+    return this.detectionMethod
+  }
+
+  /**
+   * Clear cached region
+   */
+  clearCache() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem(this.config.cacheKey)
+    }
+  }
+
+  /**
+   * Force refresh region (bypass cache)
+   * @returns {Promise<string>}
+   */
+  async forceRefresh() {
+    this.clearCache()
+    this.detectedRegion = null
+    this.detectionMethod = null
+    return this.detect()
+  }
+
+  // --- Detection Methods ---
+
+  /**
+   * Detect from edge/CDN headers
+   * @private
+   * @returns {Object|null} { country, state }
+   */
+  _detectFromEdgeHeaders() {
+    // This only works server-side or with edge functions
+    // In browser, we can't access these headers directly
+    // This is a placeholder for SSR/Edge implementation
+
+    if (typeof window === 'undefined') {
+      // Server-side: check request headers
+      // Example: req.headers['cf-ipcountry']
+      return null
+    }
+
+    // Browser: not available
+    return null
+  }
+
+  /**
+   * Detect from IP API
+   * @private
+   * @returns {Promise<Object|null>} { country, state }
+   */
+  async _detectFromIPAPI() {
+    if (typeof fetch === 'undefined') {
+      return null
+    }
+
+    try {
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), this.config.ipApiTimeout)
+
+      const url = this.config.ipApiToken
+        ? `${this.config.ipApiUrl}?token=${this.config.ipApiToken}`
+        : this.config.ipApiUrl
+
+      const response = await fetch(url, {
+        signal: controller.signal
+      })
+
+      clearTimeout(timeoutId)
+
+      if (!response.ok) {
+        throw new Error(`IP API returned ${response.status}`)
+      }
+
+      const data = await response.json()
+
+      this._debug('IP API response:', data)
+
+      return {
+        country: data.country_code || data.country,
+        state: data.region_code || this._mapUSState(data.region) // Map full state name to state code
+      }
+    } catch (error) {
+      this._debug('IP API error:', error.message)
+      return null
+    }
+  }
+
+  /**
+   * Map US state names to codes
+   * @private
+   */
+  _mapUSState(stateName) {
+    if (!stateName) return null
+
+    const stateMap = {
+      'Alabama': 'AL', 'Alaska': 'AK', 'Arizona': 'AZ', 'Arkansas': 'AR',
+      'California': 'CA', 'Colorado': 'CO', 'Connecticut': 'CT', 'Delaware': 'DE',
+      'Florida': 'FL', 'Georgia': 'GA', 'Hawaii': 'HI', 'Idaho': 'ID',
+      'Illinois': 'IL', 'Indiana': 'IN', 'Iowa': 'IA', 'Kansas': 'KS',
+      'Kentucky': 'KY', 'Louisiana': 'LA', 'Maine': 'ME', 'Maryland': 'MD',
+      'Massachusetts': 'MA', 'Michigan': 'MI', 'Minnesota': 'MN', 'Mississippi': 'MS',
+      'Missouri': 'MO', 'Montana': 'MT', 'Nebraska': 'NE', 'Nevada': 'NV',
+      'New Hampshire': 'NH', 'New Jersey': 'NJ', 'New Mexico': 'NM', 'New York': 'NY',
+      'North Carolina': 'NC', 'North Dakota': 'ND', 'Ohio': 'OH', 'Oklahoma': 'OK',
+      'Oregon': 'OR', 'Pennsylvania': 'PA', 'Rhode Island': 'RI', 'South Carolina': 'SC',
+      'South Dakota': 'SD', 'Tennessee': 'TN', 'Texas': 'TX', 'Utah': 'UT',
+      'Vermont': 'VT', 'Virginia': 'VA', 'Washington': 'WA', 'West Virginia': 'WV',
+      'Wisconsin': 'WI', 'Wyoming': 'WY'
+    }
+
+    return stateMap[stateName] || null
+  }
+
+  /**
+   * Detect from freegeoip.app
+   * @private
+   * @returns {Promise<Object|null>} { country, state }
+   */
+  async _detectFromFreeGeoIp() {
+    if (typeof fetch === 'undefined') {
+      return null
+    }
+
+    try {
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), this.config.ipApiTimeout)
+
+      const response = await fetch(this.config.freeGeoIpUrl, {
+        signal: controller.signal
+      })
+
+      clearTimeout(timeoutId)
+
+      if (!response.ok) {
+        throw new Error(`freegeoip.app returned ${response.status}`)
+      }
+
+      const data = await response.json()
+
+      this._debug('freegeoip.app response:', data)
+
+      // freegeoip.app format: {country_code: "US", region_name: "Florida"}
+      return {
+        country: data.country_code,
+        state: this._mapUSState(data.region_name)
+      }
+    } catch (error) {
+      this._debug('freegeoip.app error:', error.message)
+      return null
+    }
+  }
+
+  /**
+   * Detect from ip-api.com
+   * @private
+   * @returns {Promise<Object|null>} { country, state }
+   */
+  async _detectFromIpApiCom() {
+    if (typeof fetch === 'undefined') {
+      return null
+    }
+
+    try {
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), this.config.ipApiTimeout)
+
+      const response = await fetch(this.config.ipApiComUrl, {
+        signal: controller.signal
+      })
+
+      clearTimeout(timeoutId)
+
+      if (!response.ok) {
+        throw new Error(`ip-api.com returned ${response.status}`)
+      }
+
+      const data = await response.json()
+
+      this._debug('ip-api.com response:', data)
+
+      // ip-api.com format: {countryCode: "US", regionName: "Florida"}
+      return {
+        country: data.countryCode,
+        state: this._mapUSState(data.regionName)
+      }
+    } catch (error) {
+      this._debug('ip-api.com error:', error.message)
+      return null
+    }
+  }
+
+  /**
+   * Detect from backup IP API (ipinfo.io)
+   * @private
+   * @returns {Promise<Object|null>} { country, state }
+   */
+  async _detectFromBackupIPAPI() {
+    if (typeof fetch === 'undefined') {
+      return null
+    }
+
+    try {
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), this.config.ipApiTimeout)
+
+      const response = await fetch(this.config.backupIpApiUrl, {
+        signal: controller.signal
+      })
+
+      clearTimeout(timeoutId)
+
+      if (!response.ok) {
+        throw new Error(`Backup IP API returned ${response.status}`)
+      }
+
+      const data = await response.json()
+
+      this._debug('Backup IP API response:', data)
+
+      // ipinfo.io format: { country: "US", region: "Florida" }
+      return {
+        country: data.country,
+        state: this._mapUSState(data.region) // Map full state name to state code
+      }
+    } catch (error) {
+      this._debug('Backup IP API error:', error.message)
+      return null
+    }
+  }
+
+  /**
+   * Detect from browser timezone (approximate)
+   * @private
+   * @returns {string|null} Country code
+   */
+  _detectFromTimezone() {
+    if (typeof Intl === 'undefined') {
+      return null
+    }
+
+    try {
+      const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+
+      // Approximate mapping: timezone → country
+      const timezoneMap = {
+        // Europe
+        'Europe/London': 'GB',
+        'Europe/Dublin': 'IE',
+        'Europe/Paris': 'FR',
+        'Europe/Berlin': 'DE',
+        'Europe/Rome': 'IT',
+        'Europe/Madrid': 'ES',
+        'Europe/Amsterdam': 'NL',
+        'Europe/Brussels': 'BE',
+        'Europe/Vienna': 'AT',
+        'Europe/Stockholm': 'SE',
+        'Europe/Copenhagen': 'DK',
+        'Europe/Helsinki': 'FI',
+        'Europe/Oslo': 'NO',
+        'Europe/Warsaw': 'PL',
+        'Europe/Prague': 'CZ',
+        'Europe/Budapest': 'HU',
+        'Europe/Bucharest': 'RO',
+        'Europe/Athens': 'GR',
+        'Europe/Lisbon': 'PT',
+        'Europe/Zurich': 'CH',
+
+        // Americas
+        'America/New_York': 'US',
+        'America/Chicago': 'US',
+        'America/Denver': 'US',
+        'America/Los_Angeles': 'US',
+        'America/Sao_Paulo': 'BR',
+        'America/Mexico_City': 'MX',
+        'America/Toronto': 'CA',
+
+        // Asia
+        'Asia/Tokyo': 'JP',
+        'Asia/Shanghai': 'CN',
+        'Asia/Hong_Kong': 'HK',
+        'Asia/Singapore': 'SG',
+        'Asia/Dubai': 'AE',
+        'Asia/Kolkata': 'IN',
+
+        // Australia
+        'Australia/Sydney': 'AU',
+        'Australia/Melbourne': 'AU'
+      }
+
+      const countryCode = timezoneMap[timezone]
+
+      if (countryCode) {
+        return countryCode
+      }
+
+      // Fallback: check timezone prefix
+      if (timezone.startsWith('Europe/')) {
+        // Return a representative EU country instead of 'EU'
+        // This ensures getRegion() works correctly
+        return 'DE' // Germany as default EU country
+      }
+
+      return null
+    } catch (error) {
+      this._debug('Timezone detection error:', error)
+      return null
+    }
+  }
+
+  /**
+   * Get cached region
+   * @private
+   */
+  _getCachedRegion() {
+    if (typeof localStorage === 'undefined') {
+      return null
+    }
+
+    try {
+      const cached = localStorage.getItem(this.config.cacheKey)
+      if (!cached) return null
+
+      const data = JSON.parse(cached)
+      const age = Date.now() - data.timestamp
+
+      if (age > this.config.cacheDuration) {
+        // Cache expired
+        localStorage.removeItem(this.config.cacheKey)
+        return null
+      }
+
+      return data
+    } catch (error) {
+      return null
+    }
+  }
+
+  /**
+   * Cache region
+   * @private
+   */
+  _cacheRegion(region) {
+    if (typeof localStorage === 'undefined') {
+      return
+    }
+
+    try {
+      const data = {
+        region,
+        timestamp: Date.now(),
+        method: this.detectionMethod
+      }
+      localStorage.setItem(this.config.cacheKey, JSON.stringify(data))
+    } catch (error) {
+      this._debug('Failed to cache region:', error)
+    }
+  }
+
+  _debug(...args) {
+    if (this.config.debug) {
+      console.log('[GeoDetector]', ...args)
+    }
+  }
+}