@stacksjs/ts-analytics 0.1.6

package/src/utils/response.ts

@@ -0,0 +1,180 @@
+/**
+ * Response utilities for the analytics API
+ */
+
+export interface ApiResponse {
+  statusCode: number
+  headers: Record<string, string>
+  body: string
+}
+
+/**
+ * Create a standardized JSON response
+ */
+export function jsonResponse(body: unknown, statusCode = 200, headers: Record<string, string> = {}): Response {
+  return new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+    status: statusCode,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+      ...headers,
+    },
+  })
+}
+
+/**
+ * 204 No Content with CORS — for the public collect / tracking endpoints, which
+ * every host site POSTs to cross-origin. Without Access-Control-Allow-Origin the
+ * browser blocks the beacon (and logs a CORS error) even though the write
+ * succeeded, so the bare `new Response(null, { status: 204 })` must not be used.
+ */
+export function noContentResponse(request?: Request, headers: Record<string, string> = {}): Response {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      ...corsOriginHeaders(request),
+      ...headers,
+    },
+  })
+}
+
+/**
+ * Create an HTML response
+ */
+export function htmlResponse(body: string, statusCode = 200, headers: Record<string, string> = {}): Response {
+  return new Response(body, {
+    status: statusCode,
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Access-Control-Allow-Origin': '*',
+      ...headers,
+    },
+  })
+}
+
+/**
+ * Create a JavaScript response.
+ *
+ * Carries an ETag (#179) so tracker updates roll out on the next
+ * revalidation instead of a hard 1-hour cache-expiry wait: pass the request
+ * and a matching If-None-Match short-circuits to 304.
+ * stale-while-revalidate keeps page loads fast while the check happens in
+ * the background. Cache-bust hard with a ?v= query when needed.
+ */
+export function jsResponse(body: string, headers: Record<string, string> = {}, request?: Request): Response {
+  const etag = `W/"${Bun.hash(body).toString(36)}"`
+  const baseHeaders = {
+    'Content-Type': 'application/javascript',
+    'Cache-Control': 'public, max-age=3600, stale-while-revalidate=86400',
+    'Access-Control-Allow-Origin': '*',
+    'ETag': etag,
+    ...headers,
+  }
+  if (request?.headers.get('if-none-match') === etag) {
+    return new Response(null, { status: 304, headers: baseHeaders })
+  }
+  return new Response(body, { status: 200, headers: baseHeaders })
+}
+
+/**
+ * CORS origin headers for the public collect endpoints. sendBeacon always
+ * sends with credentials mode 'include' (per spec), and credentialed CORS
+ * rejects the wildcard — so when the request carries an Origin, echo it and
+ * allow credentials; fall back to '*' otherwise.
+ */
+export function corsOriginHeaders(request?: Request): Record<string, string> {
+  const origin = request?.headers?.get?.('origin')
+  if (!origin)
+    return { 'Access-Control-Allow-Origin': '*' }
+  return {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Credentials': 'true',
+    'Vary': 'Origin',
+  }
+}
+
+/**
+ * CORS preflight response for the public collect endpoints (#86).
+ *
+ * Cross-domain installs preflight every beacon: the tracker posts JSON
+ * (non-simple content type) and the error SDK adds X-Analytics-Token, so the
+ * browser sends OPTIONS first. Without this, preflights 404 and the browser
+ * silently drops the POST. The origin is echoed (not wildcarded) because
+ * sendBeacon requests are always credentialed.
+ */
+export function preflightResponse(request?: Request): Response {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      ...corsOriginHeaders(request),
+      'Access-Control-Allow-Methods': 'POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, X-Analytics-Token',
+      'Access-Control-Max-Age': '86400',
+    },
+  })
+}
+
+/**
+ * Create an error response
+ */
+export function errorResponse(message: string, statusCode = 500): Response {
+  return jsonResponse({ error: message }, statusCode)
+}
+
+/**
+ * Create a not found response
+ */
+export function notFoundResponse(message = 'Not found'): Response {
+  return jsonResponse({ error: message }, 404)
+}
+
+/**
+ * Legacy response helper for backwards compatibility during migration
+ * Returns the old format expected by the Lambda handler
+ */
+export function legacyResponse(body: unknown, statusCode = 200, headers: Record<string, string> = {}): ApiResponse {
+  return {
+    statusCode,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+      ...headers,
+    },
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+  }
+}
+
+/**
+ * Split-domain credentialed CORS (#118).
+ *
+ * When the dashboard runs on a DIFFERENT origin than the API
+ * (STX_PUBLIC_API_ENDPOINT), its credentialed fetches need the API to echo the
+ * request Origin with Access-Control-Allow-Credentials — browsers forbid the
+ * wildcard with credentials. The allowlist comes from CORS_ORIGINS
+ * (comma-separated origins). Unset = same-origin installs (the dev proxy,
+ * #116) — no echo, wildcard responses stay as-is.
+ */
+export function allowedCorsOrigins(): string[] {
+  return (process.env.CORS_ORIGINS || '')
+    .split(',')
+    .map(o => o.trim().replace(/\/$/, ''))
+    .filter(o => o.length > 0 && o !== '*')
+}
+
+/** The echoed CORS headers for an allowlisted Origin, or null. */
+export function credentialedCorsHeaders(request: Request): Record<string, string> | null {
+  const origin = request.headers.get('origin')
+  if (!origin)
+    return null
+  if (!allowedCorsOrigins().includes(origin.replace(/\/$/, '')))
+    return null
+  return {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Credentials': 'true',
+    'Vary': 'Origin',
+  }
+}

package/src/utils/timezone-country.ts

@@ -0,0 +1,242 @@
+/**
+ * Country from the browser's IANA timezone (Fathom-privacy geolocation).
+ *
+ * The tracker sends `Intl.DateTimeFormat().resolvedOptions().timeZone` (e.g.
+ * "Asia/Manila") and we map it to a country server-side. Nothing about the
+ * visitor leaves their machine except a coarse timezone string, no IP is used
+ * or shipped to a third party, and only the derived country is stored — the
+ * raw timezone is discarded. Works in any deployment (no CDN geo headers
+ * needed), so it's the default fallback after CloudFront/Cloudflare headers.
+ *
+ * Mapping data follows the IANA tz database's zone-to-country table
+ * (zone1970.tab) plus the common legacy aliases browsers still emit
+ * (Asia/Calcutta, Europe/Kiev, US/Eastern, …). Zones with no single country
+ * (UTC, Etc/*) intentionally resolve to nothing.
+ */
+import { COUNTRY_NAMES } from './geolocation'
+
+const TIMEZONE_COUNTRY: Record<string, string> = {
+  // Africa
+  'Africa/Abidjan': 'CI', 'Africa/Accra': 'GH', 'Africa/Addis_Ababa': 'ET',
+  'Africa/Algiers': 'DZ', 'Africa/Asmara': 'ER', 'Africa/Asmera': 'ER',
+  'Africa/Bamako': 'ML', 'Africa/Bangui': 'CF', 'Africa/Banjul': 'GM',
+  'Africa/Bissau': 'GW', 'Africa/Blantyre': 'MW', 'Africa/Brazzaville': 'CG',
+  'Africa/Bujumbura': 'BI', 'Africa/Cairo': 'EG', 'Africa/Casablanca': 'MA',
+  'Africa/Ceuta': 'ES', 'Africa/Conakry': 'GN', 'Africa/Dakar': 'SN',
+  'Africa/Dar_es_Salaam': 'TZ', 'Africa/Djibouti': 'DJ', 'Africa/Douala': 'CM',
+  'Africa/El_Aaiun': 'EH', 'Africa/Freetown': 'SL', 'Africa/Gaborone': 'BW',
+  'Africa/Harare': 'ZW', 'Africa/Johannesburg': 'ZA', 'Africa/Juba': 'SS',
+  'Africa/Kampala': 'UG', 'Africa/Khartoum': 'SD', 'Africa/Kigali': 'RW',
+  'Africa/Kinshasa': 'CD', 'Africa/Lagos': 'NG', 'Africa/Libreville': 'GA',
+  'Africa/Lome': 'TG', 'Africa/Luanda': 'AO', 'Africa/Lubumbashi': 'CD',
+  'Africa/Lusaka': 'ZM', 'Africa/Malabo': 'GQ', 'Africa/Maputo': 'MZ',
+  'Africa/Maseru': 'LS', 'Africa/Mbabane': 'SZ', 'Africa/Mogadishu': 'SO',
+  'Africa/Monrovia': 'LR', 'Africa/Nairobi': 'KE', 'Africa/Ndjamena': 'TD',
+  'Africa/Niamey': 'NE', 'Africa/Nouakchott': 'MR', 'Africa/Ouagadougou': 'BF',
+  'Africa/Porto-Novo': 'BJ', 'Africa/Sao_Tome': 'ST', 'Africa/Timbuktu': 'ML',
+  'Africa/Tripoli': 'LY', 'Africa/Tunis': 'TN', 'Africa/Windhoek': 'NA',
+
+  // America — US
+  'America/Adak': 'US', 'America/Anchorage': 'US', 'America/Boise': 'US',
+  'America/Chicago': 'US', 'America/Denver': 'US', 'America/Detroit': 'US',
+  'America/Indiana/Indianapolis': 'US', 'America/Indiana/Knox': 'US',
+  'America/Indiana/Marengo': 'US', 'America/Indiana/Petersburg': 'US',
+  'America/Indiana/Tell_City': 'US', 'America/Indiana/Vevay': 'US',
+  'America/Indiana/Vincennes': 'US', 'America/Indiana/Winamac': 'US',
+  'America/Indianapolis': 'US', 'America/Fort_Wayne': 'US', 'America/Knox_IN': 'US',
+  'America/Juneau': 'US', 'America/Kentucky/Louisville': 'US',
+  'America/Kentucky/Monticello': 'US', 'America/Louisville': 'US',
+  'America/Los_Angeles': 'US', 'America/Menominee': 'US', 'America/Metlakatla': 'US',
+  'America/New_York': 'US', 'America/Nome': 'US',
+  'America/North_Dakota/Beulah': 'US', 'America/North_Dakota/Center': 'US',
+  'America/North_Dakota/New_Salem': 'US', 'America/Phoenix': 'US',
+  'America/Shiprock': 'US', 'America/Sitka': 'US', 'America/Yakutat': 'US',
+  'America/Atka': 'US',
+  'US/Alaska': 'US', 'US/Aleutian': 'US', 'US/Arizona': 'US', 'US/Central': 'US',
+  'US/East-Indiana': 'US', 'US/Eastern': 'US', 'US/Hawaii': 'US',
+  'US/Indiana-Starke': 'US', 'US/Michigan': 'US', 'US/Mountain': 'US', 'US/Pacific': 'US',
+  'Pacific/Honolulu': 'US',
+
+  // America — Canada
+  'America/Atikokan': 'CA', 'America/Blanc-Sablon': 'CA', 'America/Cambridge_Bay': 'CA',
+  'America/Coral_Harbour': 'CA', 'America/Creston': 'CA', 'America/Dawson': 'CA',
+  'America/Dawson_Creek': 'CA', 'America/Edmonton': 'CA', 'America/Fort_Nelson': 'CA',
+  'America/Glace_Bay': 'CA', 'America/Goose_Bay': 'CA', 'America/Halifax': 'CA',
+  'America/Inuvik': 'CA', 'America/Iqaluit': 'CA', 'America/Moncton': 'CA',
+  'America/Montreal': 'CA', 'America/Nipigon': 'CA', 'America/Pangnirtung': 'CA',
+  'America/Rainy_River': 'CA', 'America/Rankin_Inlet': 'CA', 'America/Regina': 'CA',
+  'America/Resolute': 'CA', 'America/St_Johns': 'CA', 'America/Swift_Current': 'CA',
+  'America/Thunder_Bay': 'CA', 'America/Toronto': 'CA', 'America/Vancouver': 'CA',
+  'America/Whitehorse': 'CA', 'America/Winnipeg': 'CA', 'America/Yellowknife': 'CA',
+  'Canada/Atlantic': 'CA', 'Canada/Central': 'CA', 'Canada/Eastern': 'CA',
+  'Canada/Mountain': 'CA', 'Canada/Newfoundland': 'CA', 'Canada/Pacific': 'CA',
+  'Canada/Saskatchewan': 'CA', 'Canada/Yukon': 'CA',
+
+  // America — Mexico
+  'America/Bahia_Banderas': 'MX', 'America/Cancun': 'MX', 'America/Chihuahua': 'MX',
+  'America/Ciudad_Juarez': 'MX', 'America/Ensenada': 'MX', 'America/Hermosillo': 'MX',
+  'America/Matamoros': 'MX', 'America/Mazatlan': 'MX', 'America/Merida': 'MX',
+  'America/Mexico_City': 'MX', 'America/Monterrey': 'MX', 'America/Ojinaga': 'MX',
+  'America/Santa_Isabel': 'MX', 'America/Tijuana': 'MX',
+  'Mexico/BajaNorte': 'MX', 'Mexico/BajaSur': 'MX', 'Mexico/General': 'MX',
+
+  // America — Brazil
+  'America/Araguaina': 'BR', 'America/Bahia': 'BR', 'America/Belem': 'BR',
+  'America/Boa_Vista': 'BR', 'America/Campo_Grande': 'BR', 'America/Cuiaba': 'BR',
+  'America/Eirunepe': 'BR', 'America/Fortaleza': 'BR', 'America/Maceio': 'BR',
+  'America/Manaus': 'BR', 'America/Noronha': 'BR', 'America/Porto_Acre': 'BR',
+  'America/Porto_Velho': 'BR', 'America/Recife': 'BR', 'America/Rio_Branco': 'BR',
+  'America/Santarem': 'BR', 'America/Sao_Paulo': 'BR',
+  'Brazil/Acre': 'BR', 'Brazil/DeNoronha': 'BR', 'Brazil/East': 'BR', 'Brazil/West': 'BR',
+
+  // America — Argentina
+  'America/Argentina/Buenos_Aires': 'AR', 'America/Argentina/Catamarca': 'AR',
+  'America/Argentina/ComodRivadavia': 'AR', 'America/Argentina/Cordoba': 'AR',
+  'America/Argentina/Jujuy': 'AR', 'America/Argentina/La_Rioja': 'AR',
+  'America/Argentina/Mendoza': 'AR', 'America/Argentina/Rio_Gallegos': 'AR',
+  'America/Argentina/Salta': 'AR', 'America/Argentina/San_Juan': 'AR',
+  'America/Argentina/San_Luis': 'AR', 'America/Argentina/Tucuman': 'AR',
+  'America/Argentina/Ushuaia': 'AR', 'America/Buenos_Aires': 'AR',
+  'America/Catamarca': 'AR', 'America/Cordoba': 'AR', 'America/Jujuy': 'AR',
+  'America/Mendoza': 'AR', 'America/Rosario': 'AR',
+
+  // America — rest
+  'America/Anguilla': 'AI', 'America/Antigua': 'AG', 'America/Aruba': 'AW',
+  'America/Asuncion': 'PY', 'America/Barbados': 'BB', 'America/Belize': 'BZ',
+  'America/Bogota': 'CO', 'America/Caracas': 'VE', 'America/Cayenne': 'GF',
+  'America/Cayman': 'KY', 'America/Costa_Rica': 'CR', 'America/Curacao': 'CW',
+  'America/Danmarkshavn': 'GL', 'America/Dominica': 'DM', 'America/El_Salvador': 'SV',
+  'America/Godthab': 'GL', 'America/Grand_Turk': 'TC', 'America/Grenada': 'GD',
+  'America/Guadeloupe': 'GP', 'America/Guatemala': 'GT', 'America/Guayaquil': 'EC',
+  'America/Guyana': 'GY', 'America/Havana': 'CU', 'America/Jamaica': 'JM',
+  'America/Kralendijk': 'BQ', 'America/La_Paz': 'BO', 'America/Lima': 'PE',
+  'America/Lower_Princes': 'SX', 'America/Managua': 'NI', 'America/Marigot': 'MF',
+  'America/Martinique': 'MQ', 'America/Miquelon': 'PM', 'America/Montevideo': 'UY',
+  'America/Montserrat': 'MS', 'America/Nassau': 'BS', 'America/Nuuk': 'GL',
+  'America/Panama': 'PA', 'America/Paramaribo': 'SR', 'America/Port-au-Prince': 'HT',
+  'America/Port_of_Spain': 'TT', 'America/Puerto_Rico': 'PR', 'America/Punta_Arenas': 'CL',
+  'America/Santiago': 'CL', 'America/Santo_Domingo': 'DO', 'America/Scoresbysund': 'GL',
+  'America/St_Barthelemy': 'BL', 'America/St_Kitts': 'KN', 'America/St_Lucia': 'LC',
+  'America/St_Thomas': 'VI', 'America/St_Vincent': 'VC', 'America/Tegucigalpa': 'HN',
+  'America/Thule': 'GL', 'America/Tortola': 'VG', 'America/Virgin': 'VI',
+  'America/Coyhaique': 'CL',
+  'Chile/Continental': 'CL', 'Chile/EasterIsland': 'CL', 'Cuba': 'CU', 'Jamaica': 'JM',
+
+  // Antarctica (research stations — no meaningful country; map to AQ)
+  'Antarctica/Casey': 'AQ', 'Antarctica/Davis': 'AQ', 'Antarctica/DumontDUrville': 'AQ',
+  'Antarctica/Macquarie': 'AU', 'Antarctica/Mawson': 'AQ', 'Antarctica/McMurdo': 'AQ',
+  'Antarctica/Palmer': 'AQ', 'Antarctica/Rothera': 'AQ', 'Antarctica/South_Pole': 'AQ',
+  'Antarctica/Syowa': 'AQ', 'Antarctica/Troll': 'AQ', 'Antarctica/Vostok': 'AQ',
+
+  // Asia
+  'Asia/Aden': 'YE', 'Asia/Almaty': 'KZ', 'Asia/Amman': 'JO', 'Asia/Anadyr': 'RU',
+  'Asia/Aqtau': 'KZ', 'Asia/Aqtobe': 'KZ', 'Asia/Ashgabat': 'TM', 'Asia/Ashkhabad': 'TM',
+  'Asia/Atyrau': 'KZ', 'Asia/Baghdad': 'IQ', 'Asia/Bahrain': 'BH', 'Asia/Baku': 'AZ',
+  'Asia/Bangkok': 'TH', 'Asia/Barnaul': 'RU', 'Asia/Beirut': 'LB', 'Asia/Bishkek': 'KG',
+  'Asia/Brunei': 'BN', 'Asia/Calcutta': 'IN', 'Asia/Chita': 'RU', 'Asia/Choibalsan': 'MN',
+  'Asia/Chongqing': 'CN', 'Asia/Chungking': 'CN', 'Asia/Colombo': 'LK', 'Asia/Dacca': 'BD',
+  'Asia/Damascus': 'SY', 'Asia/Dhaka': 'BD', 'Asia/Dili': 'TL', 'Asia/Dubai': 'AE',
+  'Asia/Dushanbe': 'TJ', 'Asia/Famagusta': 'CY', 'Asia/Gaza': 'PS', 'Asia/Harbin': 'CN',
+  'Asia/Hebron': 'PS', 'Asia/Ho_Chi_Minh': 'VN', 'Asia/Hong_Kong': 'HK', 'Asia/Hovd': 'MN',
+  'Asia/Irkutsk': 'RU', 'Asia/Istanbul': 'TR', 'Asia/Jakarta': 'ID', 'Asia/Jayapura': 'ID',
+  'Asia/Jerusalem': 'IL', 'Asia/Kabul': 'AF', 'Asia/Kamchatka': 'RU', 'Asia/Karachi': 'PK',
+  'Asia/Kashgar': 'CN', 'Asia/Kathmandu': 'NP', 'Asia/Katmandu': 'NP', 'Asia/Khandyga': 'RU',
+  'Asia/Kolkata': 'IN', 'Asia/Krasnoyarsk': 'RU', 'Asia/Kuala_Lumpur': 'MY',
+  'Asia/Kuching': 'MY', 'Asia/Kuwait': 'KW', 'Asia/Macao': 'MO', 'Asia/Macau': 'MO',
+  'Asia/Magadan': 'RU', 'Asia/Makassar': 'ID', 'Asia/Manila': 'PH', 'Asia/Muscat': 'OM',
+  'Asia/Nicosia': 'CY', 'Asia/Novokuznetsk': 'RU', 'Asia/Novosibirsk': 'RU',
+  'Asia/Omsk': 'RU', 'Asia/Oral': 'KZ', 'Asia/Phnom_Penh': 'KH', 'Asia/Pontianak': 'ID',
+  'Asia/Pyongyang': 'KP', 'Asia/Qatar': 'QA', 'Asia/Qostanay': 'KZ', 'Asia/Qyzylorda': 'KZ',
+  'Asia/Rangoon': 'MM', 'Asia/Riyadh': 'SA', 'Asia/Saigon': 'VN', 'Asia/Sakhalin': 'RU',
+  'Asia/Samarkand': 'UZ', 'Asia/Seoul': 'KR', 'Asia/Shanghai': 'CN', 'Asia/Singapore': 'SG',
+  'Asia/Srednekolymsk': 'RU', 'Asia/Taipei': 'TW', 'Asia/Tashkent': 'UZ',
+  'Asia/Tbilisi': 'GE', 'Asia/Tehran': 'IR', 'Asia/Tel_Aviv': 'IL', 'Asia/Thimbu': 'BT',
+  'Asia/Thimphu': 'BT', 'Asia/Tokyo': 'JP', 'Asia/Tomsk': 'RU', 'Asia/Ujung_Pandang': 'ID',
+  'Asia/Ulaanbaatar': 'MN', 'Asia/Ulan_Bator': 'MN', 'Asia/Urumqi': 'CN',
+  'Asia/Ust-Nera': 'RU', 'Asia/Vientiane': 'LA', 'Asia/Vladivostok': 'RU',
+  'Asia/Yakutsk': 'RU', 'Asia/Yangon': 'MM', 'Asia/Yekaterinburg': 'RU', 'Asia/Yerevan': 'AM',
+  'Hongkong': 'HK', 'Israel': 'IL', 'Iran': 'IR', 'Japan': 'JP', 'Singapore': 'SG',
+  'ROC': 'TW', 'ROK': 'KR', 'PRC': 'CN', 'Turkey': 'TR', 'Egypt': 'EG', 'Libya': 'LY',
+
+  // Atlantic
+  'Atlantic/Azores': 'PT', 'Atlantic/Bermuda': 'BM', 'Atlantic/Canary': 'ES',
+  'Atlantic/Cape_Verde': 'CV', 'Atlantic/Faeroe': 'FO', 'Atlantic/Faroe': 'FO',
+  'Atlantic/Jan_Mayen': 'SJ', 'Atlantic/Madeira': 'PT', 'Atlantic/Reykjavik': 'IS',
+  'Atlantic/South_Georgia': 'GS', 'Atlantic/St_Helena': 'SH', 'Atlantic/Stanley': 'FK',
+  'Iceland': 'IS',
+
+  // Australia
+  'Australia/ACT': 'AU', 'Australia/Adelaide': 'AU', 'Australia/Brisbane': 'AU',
+  'Australia/Broken_Hill': 'AU', 'Australia/Canberra': 'AU', 'Australia/Currie': 'AU',
+  'Australia/Darwin': 'AU', 'Australia/Eucla': 'AU', 'Australia/Hobart': 'AU',
+  'Australia/LHI': 'AU', 'Australia/Lindeman': 'AU', 'Australia/Lord_Howe': 'AU',
+  'Australia/Melbourne': 'AU', 'Australia/NSW': 'AU', 'Australia/North': 'AU',
+  'Australia/Perth': 'AU', 'Australia/Queensland': 'AU', 'Australia/South': 'AU',
+  'Australia/Sydney': 'AU', 'Australia/Tasmania': 'AU', 'Australia/Victoria': 'AU',
+  'Australia/West': 'AU', 'Australia/Yancowinna': 'AU',
+
+  // Europe
+  'Europe/Amsterdam': 'NL', 'Europe/Andorra': 'AD', 'Europe/Astrakhan': 'RU',
+  'Europe/Athens': 'GR', 'Europe/Belfast': 'GB', 'Europe/Belgrade': 'RS',
+  'Europe/Berlin': 'DE', 'Europe/Bratislava': 'SK', 'Europe/Brussels': 'BE',
+  'Europe/Bucharest': 'RO', 'Europe/Budapest': 'HU', 'Europe/Busingen': 'DE',
+  'Europe/Chisinau': 'MD', 'Europe/Copenhagen': 'DK', 'Europe/Dublin': 'IE',
+  'Europe/Gibraltar': 'GI', 'Europe/Guernsey': 'GG', 'Europe/Helsinki': 'FI',
+  'Europe/Isle_of_Man': 'IM', 'Europe/Istanbul': 'TR', 'Europe/Jersey': 'JE',
+  'Europe/Kaliningrad': 'RU', 'Europe/Kiev': 'UA', 'Europe/Kirov': 'RU',
+  'Europe/Kyiv': 'UA', 'Europe/Lisbon': 'PT', 'Europe/Ljubljana': 'SI',
+  'Europe/London': 'GB', 'Europe/Luxembourg': 'LU', 'Europe/Madrid': 'ES',
+  'Europe/Malta': 'MT', 'Europe/Mariehamn': 'AX', 'Europe/Minsk': 'BY',
+  'Europe/Monaco': 'MC', 'Europe/Moscow': 'RU', 'Europe/Nicosia': 'CY',
+  'Europe/Oslo': 'NO', 'Europe/Paris': 'FR', 'Europe/Podgorica': 'ME',
+  'Europe/Prague': 'CZ', 'Europe/Riga': 'LV', 'Europe/Rome': 'IT',
+  'Europe/Samara': 'RU', 'Europe/San_Marino': 'SM', 'Europe/Sarajevo': 'BA',
+  'Europe/Saratov': 'RU', 'Europe/Simferopol': 'UA', 'Europe/Skopje': 'MK',
+  'Europe/Sofia': 'BG', 'Europe/Stockholm': 'SE', 'Europe/Tallinn': 'EE',
+  'Europe/Tirane': 'AL', 'Europe/Tiraspol': 'MD', 'Europe/Ulyanovsk': 'RU',
+  'Europe/Uzhgorod': 'UA', 'Europe/Vaduz': 'LI', 'Europe/Vatican': 'VA',
+  'Europe/Vienna': 'AT', 'Europe/Vilnius': 'LT', 'Europe/Volgograd': 'RU',
+  'Europe/Warsaw': 'PL', 'Europe/Zagreb': 'HR', 'Europe/Zaporozhye': 'UA',
+  'Europe/Zurich': 'CH',
+  'Arctic/Longyearbyen': 'SJ',
+  'Eire': 'IE', 'GB': 'GB', 'GB-Eire': 'GB', 'Poland': 'PL', 'Portugal': 'PT',
+  'W-SU': 'RU',
+
+  // Indian Ocean
+  'Indian/Antananarivo': 'MG', 'Indian/Chagos': 'IO', 'Indian/Christmas': 'CX',
+  'Indian/Cocos': 'CC', 'Indian/Comoro': 'KM', 'Indian/Kerguelen': 'TF',
+  'Indian/Mahe': 'SC', 'Indian/Maldives': 'MV', 'Indian/Mauritius': 'MU',
+  'Indian/Mayotte': 'YT', 'Indian/Reunion': 'RE',
+
+  // Pacific
+  'Pacific/Apia': 'WS', 'Pacific/Auckland': 'NZ', 'Pacific/Bougainville': 'PG',
+  'Pacific/Chatham': 'NZ', 'Pacific/Chuuk': 'FM', 'Pacific/Easter': 'CL',
+  'Pacific/Efate': 'VU', 'Pacific/Enderbury': 'KI', 'Pacific/Fakaofo': 'TK',
+  'Pacific/Fiji': 'FJ', 'Pacific/Funafuti': 'TV', 'Pacific/Galapagos': 'EC',
+  'Pacific/Gambier': 'PF', 'Pacific/Guadalcanal': 'SB', 'Pacific/Guam': 'GU',
+  'Pacific/Johnston': 'UM', 'Pacific/Kanton': 'KI', 'Pacific/Kiritimati': 'KI',
+  'Pacific/Kosrae': 'FM', 'Pacific/Kwajalein': 'MH', 'Pacific/Majuro': 'MH',
+  'Pacific/Marquesas': 'PF', 'Pacific/Midway': 'UM', 'Pacific/Nauru': 'NR',
+  'Pacific/Niue': 'NU', 'Pacific/Norfolk': 'NF', 'Pacific/Noumea': 'NC',
+  'Pacific/Pago_Pago': 'AS', 'Pacific/Palau': 'PW', 'Pacific/Pitcairn': 'PN',
+  'Pacific/Pohnpei': 'FM', 'Pacific/Ponape': 'FM', 'Pacific/Port_Moresby': 'PG',
+  'Pacific/Rarotonga': 'CK', 'Pacific/Saipan': 'MP', 'Pacific/Samoa': 'AS',
+  'Pacific/Tahiti': 'PF', 'Pacific/Tarawa': 'KI', 'Pacific/Tongatapu': 'TO',
+  'Pacific/Truk': 'FM', 'Pacific/Wake': 'UM', 'Pacific/Wallis': 'WF',
+  'Pacific/Yap': 'FM',
+  'Kwajalein': 'MH', 'NZ': 'NZ', 'NZ-CHAT': 'NZ', 'Navajo': 'US',
+}
+
+/**
+ * Resolve a browser IANA timezone to the stored country value (display name
+ * when known, ISO code otherwise — same convention as the header-based path).
+ * Unknown / global zones (UTC, Etc/*) resolve to undefined.
+ */
+export function getCountryFromTimezone(tz?: string): string | undefined {
+  if (!tz || typeof tz !== 'string' || tz.length > 64)
+    return undefined
+  const code = TIMEZONE_COUNTRY[tz.trim()]
+  if (!code)
+    return undefined
+  return COUNTRY_NAMES[code] || code
+}

package/src/utils/user-agent.ts

@@ -0,0 +1,110 @@
+/**
+ * User agent parsing utilities
+ */
+
+export interface ParsedUserAgent {
+  deviceType: 'desktop' | 'mobile' | 'tablet'
+  browser: string
+  os: string
+}
+
+/**
+ * Parse user agent string to extract device, browser, and OS info
+ */
+export function parseUserAgent(ua: string): ParsedUserAgent {
+  if (!ua || ua === 'unknown') {
+    return { deviceType: 'desktop', browser: 'Unknown', os: 'Unknown' }
+  }
+
+  // Detect device type
+  let deviceType: 'desktop' | 'mobile' | 'tablet' = 'desktop'
+  if (/mobile|android|iphone|ipod|blackberry|iemobile|opera mini/i.test(ua)) {
+    deviceType = 'mobile'
+  }
+else if (/ipad|tablet|playbook|silk/i.test(ua)) {
+    deviceType = 'tablet'
+  }
+
+  // Detect browser - order matters (more specific first)
+  // Chromium-based browsers should be detected before Chrome
+  let browser = 'Unknown'
+  // Dia browser - check various possible formats
+  if (/\bdia\b|diahq|diabrowser/i.test(ua)) browser = 'Dia'
+  else if (/arc\//i.test(ua)) browser = 'Arc'
+  else if (/edg/i.test(ua)) browser = 'Edge'
+  else if (/opr\b|opera/i.test(ua)) browser = 'Opera'
+  else if (/brave/i.test(ua)) browser = 'Brave'
+  else if (/vivaldi/i.test(ua)) browser = 'Vivaldi'
+  else if (/yabrowser/i.test(ua)) browser = 'Yandex'
+  else if (/whale/i.test(ua)) browser = 'Whale'
+  else if (/puffin/i.test(ua)) browser = 'Puffin'
+  else if (/qqbrowser/i.test(ua)) browser = 'QQ Browser'
+  else if (/ucbrowser/i.test(ua)) browser = 'UC Browser'
+  else if (/samsungbrowser/i.test(ua)) browser = 'Samsung Internet'
+  else if (/silk/i.test(ua)) browser = 'Amazon Silk'
+  else if (/duckduckgo/i.test(ua)) browser = 'DuckDuckGo'
+  else if (/firefox|fxios/i.test(ua)) browser = 'Firefox'
+  else if (/chrome|chromium|crios/i.test(ua)) browser = 'Chrome'
+  else if (/safari/i.test(ua) && !/chrome|chromium/i.test(ua)) browser = 'Safari'
+  else if (/trident|msie/i.test(ua)) browser = 'IE'
+  else if (/bot|crawl|spider|slurp|bingpreview/i.test(ua)) browser = 'Bot'
+
+  // Detect OS
+  let os = 'Unknown'
+  if (/windows nt 10/i.test(ua)) os = 'Windows 10'
+  else if (/windows nt 11/i.test(ua)) os = 'Windows 11'
+  else if (/windows/i.test(ua)) os = 'Windows'
+  else if (/mac os x|macintosh/i.test(ua)) os = 'macOS'
+  else if (/iphone|ipad|ipod/i.test(ua)) os = 'iOS'
+  else if (/android/i.test(ua)) os = 'Android'
+  else if (/linux/i.test(ua)) os = 'Linux'
+  else if (/cros/i.test(ua)) os = 'Chrome OS'
+
+  return { deviceType, browser, os }
+}
+
+/**
+ * Whether a user agent is a bot / non-human client (#166).
+ *
+ * Three signals, applied at ingestion so bots never pollute the numbers
+ * (Fathom-style):
+ * 1. A MISSING or unrecognizably short UA — real browsers always send one;
+ *    UA-less curl/scripts previously counted as human visitors.
+ * 2. Generic bot markers (bot/crawl/spider/preview...).
+ * 3. Known non-human client families: headless browsers, HTTP libraries,
+ *    monitoring agents, and AI scrapers.
+ */
+const BOT_UA_PATTERN = new RegExp([
+  // generic markers
+  'bot|crawl|spider|slurp|preview|scan|probe|monitor(?:ing)?|checker|validator',
+  // headless / automation
+  'headless|phantomjs|puppeteer|playwright|selenium|webdriver|electron',
+  // http libraries & CLI clients
+  'curl|wget|python-requests|python-urllib|aiohttp|httpx|go-http-client|okhttp',
+  'java/|libwww|lwp::|php/|guzzle|axios|node-fetch|undici|bun/',
+  // feed/link expanders, previews, misc known agents
+  'facebookexternalhit|whatsapp|telegrambot|discordbot|slackbot|twitterbot',
+  'pingdom|uptimerobot|statuscake|newrelic|datadog|site24x7',
+  // AI scrapers
+  'gptbot|claudebot|ccbot|bytespider|amazonbot|anthropic|perplexity',
+].join('|'), 'i')
+
+export function isBot(ua: string): boolean {
+  // No/garbage UA: every real browser sends a UA string. Treat absent or
+  // implausibly short values as non-human instead of counting them as
+  // visitors (previously `if (!ua) return false` let them ALL through).
+  if (!ua || ua === 'unknown' || ua.length < 12)
+    return true
+  return BOT_UA_PATTERN.test(ua)
+}
+
+/**
+ * Get browser family (simplifies browser name to family)
+ */
+export function getBrowserFamily(browser: string): string {
+  const chromiumBased = ['Chrome', 'Edge', 'Opera', 'Brave', 'Vivaldi', 'Arc', 'Dia', 'Whale', 'Samsung Internet']
+  if (chromiumBased.includes(browser)) return 'Chromium'
+  if (browser === 'Firefox') return 'Firefox'
+  if (browser === 'Safari') return 'Safari'
+  return 'Other'
+}

package/src/version.ts

@@ -0,0 +1,7 @@
+/**
+ * Tracker/library version (#179) — embedded in the generated script, sent on
+ * every beacon (`v`), and aggregated into the hourly ingest counters, so
+ * support can tell exactly which tracker build a site is running instead of
+ * guessing at cache states. Kept in sync with package.json by a test.
+ */
+export const TRACKER_VERSION: string = '0.1.0'