@el7ven/cookie-kit 0.3.1 → 0.3.3

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)
+    }
+  }
+}

package/src/geo/RegionRules.js

@@ -0,0 +1,126 @@
+/**
+ * Region Rules — GDPR/CCPA region definitions
+ * @module RegionRules
+ */
+
+export const REGION_RULES = {
+  // European Union (GDPR)
+  EU: {
+    name: 'European Union',
+    countries: [
+      'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR',
+      'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL',
+      'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'MD'
+    ],
+    regulation: 'GDPR',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // European Economic Area (GDPR)
+  EEA: {
+    name: 'European Economic Area',
+    countries: ['IS', 'LI', 'NO'],
+    regulation: 'GDPR',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // United Kingdom (UK GDPR)
+  UK: {
+    name: 'United Kingdom',
+    countries: ['GB'],
+    regulation: 'UK GDPR',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // Switzerland (FADP)
+  CH: {
+    name: 'Switzerland',
+    countries: ['CH'],
+    regulation: 'FADP',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // United States (Federal)
+  US: {
+    name: 'United States',
+    countries: ['US'],
+    regulation: 'US Privacy Laws',
+    requiresConsent: true,
+    defaultMode: 'opt-out'
+  },
+
+  // Brazil (LGPD)
+  BR: {
+    name: 'Brazil',
+    countries: ['BR'],
+    regulation: 'LGPD',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // Canada (PIPEDA)
+  CA: {
+    name: 'Canada',
+    countries: ['CA'],
+    regulation: 'PIPEDA',
+    requiresConsent: true,
+    defaultMode: 'opt-in'
+  },
+
+  // Rest of World
+  ROW: {
+    name: 'Rest of World',
+    countries: [],
+    regulation: null,
+    requiresConsent: true, // Show essential modal
+    defaultMode: 'opt-out',
+    essentialOnly: true // Only necessary cookies
+  }
+}
+
+export function isEU(countryCode) {
+  return REGION_RULES.EU.countries.includes(countryCode)
+}
+
+export function isEEA(countryCode) {
+  return REGION_RULES.EEA.countries.includes(countryCode)
+}
+
+export function isUK(countryCode) {
+  return countryCode === 'GB'
+}
+
+export function requiresGDPR(countryCode) {
+  return isEU(countryCode) || isEEA(countryCode) || isUK(countryCode) || countryCode === 'CH'
+}
+
+export function getRegion(countryCode, stateCode = null) {
+  if (isEU(countryCode)) return 'EU'
+  if (isEEA(countryCode)) return 'EEA'
+  if (isUK(countryCode)) return 'UK'
+  if (countryCode === 'CH') return 'CH'
+  if (countryCode === 'BR') return 'BR'
+  if (countryCode === 'CA') return 'CA'
+  if (countryCode === 'US') return 'US' // All US states now use US region
+
+  return 'ROW'
+}
+
+export function requiresConsentBanner(region) {
+  const rule = REGION_RULES[region]
+  return rule ? rule.requiresConsent : false
+}
+
+export function getRegulation(region) {
+  const rule = REGION_RULES[region]
+  return rule ? rule.regulation : null
+}
+
+export function isEssentialOnly(region) {
+  const rule = REGION_RULES[region]
+  return rule ? rule.essentialOnly || false : false
+}

package/src/geo/index.js

@@ -0,0 +1,16 @@
+/**
+ * Geo Detection System — detect user's geographic region for GDPR/CCPA compliance
+ * @module geo
+ */
+
+export { GeoDetector } from './GeoDetector.js'
+export { 
+  REGION_RULES,
+  isEU,
+  isEEA,
+  isUK,
+  requiresGDPR,
+  getRegion,
+  requiresConsentBanner,
+  getRegulation
+} from './RegionRules.js'