@hyve-sdk/js 2.11.0 → 2.11.1

package/dist/index.d.mts

@@ -33,8 +33,8 @@ interface TelemetryEvent {
     event_action: string;
     /** Sub-action for detailed tracking (optional) */
     event_sub_action?: string | null;
-    /** Event details as JSON string or object (optional) */
-    event_details?: Record<string, any> | string | null;
+    /** Event details as object (optional) */
+    event_details?: Record<string, unknown> | null;
     /** Mapping details as JSON string or object (optional) */
     mapping_details?: Record<string, any> | string | null;
 }

package/dist/index.d.ts

@@ -33,8 +33,8 @@ interface TelemetryEvent {
     event_action: string;
     /** Sub-action for detailed tracking (optional) */
     event_sub_action?: string | null;
-    /** Event details as JSON string or object (optional) */
-    event_details?: Record<string, any> | string | null;
+    /** Event details as object (optional) */
+    event_details?: Record<string, unknown> | null;
     /** Mapping details as JSON string or object (optional) */
     mapping_details?: Record<string, any> | string | null;
 }

package/dist/index.js

@@ -448,6 +448,309 @@ function generateUUID() {
   return (0, import_uuid.v4)();
 }
 
+// src/utils/device-info.ts
+function detectBrowser(ua) {
+  if (/Edg\/(\d+)/.test(ua)) return { name: "Edge", major: RegExp.$1 };
+  if (/OPR\/(\d+)/.test(ua)) return { name: "Opera", major: RegExp.$1 };
+  if (/Chrome\/(\d+)/.test(ua)) return { name: "Chrome", major: RegExp.$1 };
+  if (/Firefox\/(\d+)/.test(ua)) return { name: "Firefox", major: RegExp.$1 };
+  if (/Version\/(\d+).*Safari/.test(ua)) return { name: "Safari", major: RegExp.$1 };
+  return { name: "unknown", major: "" };
+}
+function detectOS(ua) {
+  if (/Windows NT ([\d.]+)/.test(ua)) return { name: "Windows", version: RegExp.$1 };
+  if (/Mac OS X ([\d_]+)/.test(ua)) return { name: "macOS", version: RegExp.$1.replace(/_/g, ".") };
+  if (/Android ([\d.]+)/.test(ua)) return { name: "Android", version: RegExp.$1 };
+  if (/iPhone OS ([\d_]+)/.test(ua)) return { name: "iOS", version: RegExp.$1.replace(/_/g, ".") };
+  if (/iPad.*OS ([\d_]+)/.test(ua)) return { name: "iOS", version: RegExp.$1.replace(/_/g, ".") };
+  if (/CrOS/.test(ua)) return { name: "Chrome OS", version: "" };
+  if (/Linux/.test(ua)) return { name: "Linux", version: "" };
+  return { name: "unknown", version: "" };
+}
+function detectDeviceType(ua) {
+  if (/Mobi|Android(?!.*Tablet)|iPhone|iPod/i.test(ua)) return "mobile";
+  if (/Tablet|iPad|Android.*Tablet/i.test(ua)) return "tablet";
+  return "desktop";
+}
+var _cache = null;
+function getEssentialDeviceInfo() {
+  if (_cache) return _cache;
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    return {
+      browser: "unknown",
+      os: "unknown",
+      device_type: null,
+      viewport: "0x0",
+      screen: "0x0",
+      pixel_ratio: null,
+      language: null,
+      timezone: null,
+      country_code: null
+    };
+  }
+  const ua = navigator.userAgent;
+  const browser = detectBrowser(ua);
+  const os = detectOS(ua);
+  const deviceType = detectDeviceType(ua);
+  let timezone = null;
+  try {
+    timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+  }
+  const language = navigator.language || null;
+  let country_code = null;
+  if (language) {
+    const parts = language.split("-");
+    if (parts.length > 1) {
+      country_code = parts[parts.length - 1].toUpperCase();
+    }
+  }
+  _cache = {
+    browser: browser.major ? `${browser.name} ${browser.major}` : browser.name,
+    os: os.version ? `${os.name} ${os.version}` : os.name,
+    device_type: deviceType,
+    viewport: `${window.innerWidth ?? 0}x${window.innerHeight ?? 0}`,
+    screen: `${window.screen?.width ?? 0}x${window.screen?.height ?? 0}`,
+    pixel_ratio: window.devicePixelRatio || null,
+    language,
+    timezone,
+    country_code
+  };
+  return _cache;
+}
+
+// src/utils/attribution.ts
+var EMBEDDING_PLATFORM_PATTERNS = {
+  twitter: [/t\.co/i, /twitter\.com/i, /x\.com/i, /mobile\.twitter\.com/i, /mobile\.x\.com/i],
+  discord: [/discord\.com/i, /discordapp\.com/i, /discord\.gg/i],
+  telegram: [/telegram\.org/i, /telegram\.me/i, /t\.me/i, /web\.telegram\.org/i],
+  facebook: [/facebook\.com/i, /fb\.com/i, /m\.facebook\.com/i, /mobile\.facebook\.com/i, /meta\.com/i],
+  reddit: [/reddit\.com/i, /redd\.it/i, /old\.reddit\.com/i, /www\.reddit\.com/i],
+  linkedin: [/linkedin\.com/i, /lnkd\.in/i],
+  instagram: [/instagram\.com/i, /instagr\.am/i],
+  youtube: [/youtube\.com/i, /youtu\.be/i, /m\.youtube\.com/i],
+  twitch: [/twitch\.tv/i, /m\.twitch\.tv/i],
+  farcaster: [/warpcast\.com/i, /farcaster\.xyz/i, /miniapps\.farcaster\.xyz/i],
+  worldapp: [/world\.app/i, /worldcoin\.org/i],
+  tiktok: [/tiktok\.com/i, /vm\.tiktok\.com/i]
+};
+var AttributionManager = class _AttributionManager {
+  static instance;
+  cachedData = null;
+  STORAGE_KEY = "hyve_attribution";
+  SESSION_COUNT_KEY = "hyve_session_count";
+  static getInstance() {
+    if (!_AttributionManager.instance) {
+      _AttributionManager.instance = new _AttributionManager();
+    }
+    return _AttributionManager.instance;
+  }
+  captureAttribution() {
+    if (typeof window === "undefined") return this.getEmptyAttribution();
+    if (this.cachedData) return this.cachedData;
+    const urlParams = new URLSearchParams(window.location.search);
+    const referrerUrl = document.referrer;
+    const referrerDomain = this.extractDomain(referrerUrl);
+    const platformDetection = this.detectEmbeddingPlatform(urlParams, referrerUrl);
+    const attribution = {
+      utm_source: urlParams.get("utm_source"),
+      utm_medium: urlParams.get("utm_medium"),
+      utm_campaign: urlParams.get("utm_campaign"),
+      utm_term: urlParams.get("utm_term"),
+      utm_content: urlParams.get("utm_content"),
+      utm_id: urlParams.get("utm_id"),
+      utm_source_platform: urlParams.get("utm_source_platform"),
+      platform_id: platformDetection.platform,
+      is_embedded: platformDetection.isEmbedded,
+      referrer_url: referrerUrl || null,
+      referrer_domain: referrerDomain,
+      referrer_source: this.categorizeReferrer(referrerUrl),
+      is_first_party_referrer: this.isFirstPartyReferrer(referrerDomain),
+      traffic_type: this.classifyTrafficType(urlParams, referrerUrl),
+      first_visit_timestamp: Date.now(),
+      session_count: this.getSessionCount() + 1,
+      is_bot: this.detectBot(),
+      attribution_confidence: this.calculateConfidence(urlParams, referrerUrl)
+    };
+    this.cachedData = attribution;
+    this.storeAttribution(attribution);
+    return attribution;
+  }
+  getAttribution() {
+    if (this.cachedData) return this.cachedData;
+    if (typeof window === "undefined") return this.getEmptyAttribution();
+    const stored = sessionStorage.getItem(this.STORAGE_KEY);
+    if (stored) {
+      try {
+        const parsed = JSON.parse(stored);
+        if (this.isValidAttributionData(parsed)) {
+          this.cachedData = parsed;
+          return parsed;
+        }
+      } catch {
+      }
+    }
+    return this.captureAttribution();
+  }
+  classifyTrafficType(urlParams, referrerUrl) {
+    if (urlParams.get("utm_source")) return "campaign";
+    if (!referrerUrl) return "direct";
+    const domain = this.extractDomain(referrerUrl);
+    if (this.isSearchEngine(domain)) return "search";
+    if (this.isSocialPlatform(domain)) return "social";
+    if (this.isEmailClient(domain)) return "email";
+    if (this.isFirstPartyReferrer(domain)) return "direct";
+    return "referral";
+  }
+  isCdnUrl(url) {
+    if (!url) return false;
+    return [/cloudfront\.net/i, /cdn\.[\w-]+\.com/i, /\.cdn\./i, /fastly\.net/i, /akamai/i, /\.cloudflare\./i].some(
+      (p) => p.test(url)
+    );
+  }
+  detectEmbeddingPlatform(urlParams, referrerUrl) {
+    let isEmbedded = false;
+    try {
+      isEmbedded = window.self !== window.top;
+    } catch {
+      isEmbedded = true;
+    }
+    if (!isEmbedded) return { platform: "web", isEmbedded: false };
+    const platformParam = urlParams.get("platform")?.toLowerCase().trim();
+    if (platformParam && /^[a-z0-9_-]+$/.test(platformParam)) {
+      return { platform: platformParam, isEmbedded: true };
+    }
+    if (!referrerUrl || this.isCdnUrl(referrerUrl)) {
+      return { platform: "unknown", isEmbedded: true };
+    }
+    const normalizedRef = referrerUrl.toLowerCase();
+    for (const [platform, patterns] of Object.entries(EMBEDDING_PLATFORM_PATTERNS)) {
+      if (patterns.some((p) => p.test(normalizedRef))) {
+        return { platform, isEmbedded: true };
+      }
+    }
+    try {
+      if (window.location.ancestorOrigins?.length > 0) {
+        const parentOrigin = window.location.ancestorOrigins[0];
+        if (parentOrigin && !this.isCdnUrl(parentOrigin)) {
+          for (const [platform, patterns] of Object.entries(EMBEDDING_PLATFORM_PATTERNS)) {
+            if (patterns.some((p) => p.test(parentOrigin))) {
+              return { platform, isEmbedded: true };
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    return { platform: "unknown", isEmbedded: true };
+  }
+  categorizeReferrer(referrerUrl) {
+    if (!referrerUrl) return "direct";
+    const r = referrerUrl.toLowerCase();
+    if (r.includes("checkout.stripe.com")) return "direct";
+    if (r.includes("t.co") || r.includes("x.com") || r.includes("twitter.com")) return "twitter";
+    if (r.includes("farcaster.xyz") || r.includes("warpcast.com")) return "farcaster";
+    if (r.includes("discord.com") || r.includes("discord.gg")) return "discord";
+    if (r.includes("t.me") || r.includes("telegram.me") || r.includes("telegram.org")) return "telegram";
+    if (r.includes("reddit.com") || r.includes("old.reddit.com")) return "reddit";
+    if (r.includes("facebook.com") || r.includes("fb.com") || r.includes("meta.com")) return "facebook";
+    if (r.includes("linkedin.com")) return "linkedin";
+    if (r.includes("youtube.com") || r.includes("youtu.be")) return "youtube";
+    if (r.includes("google.com")) return "google";
+    if (r.includes("bing.com")) return "bing";
+    if (r.includes("duckduckgo.com")) return "duckduckgo";
+    if (r.includes("yahoo.com")) return "yahoo";
+    if (r.includes("world.app")) return "worldapp";
+    if (r.includes("instagram.com")) return "instagram";
+    if (r.includes("tiktok.com")) return "tiktok";
+    return this.extractDomain(referrerUrl) || "unknown";
+  }
+  detectBot() {
+    if (typeof navigator === "undefined") return false;
+    const ua = navigator.userAgent.toLowerCase();
+    return ["bot", "crawler", "spider", "scraper", "headless", "phantom", "selenium", "puppeteer", "playwright", "googlebot", "bingbot", "slurp", "duckduckbot"].some(
+      (indicator) => ua.includes(indicator)
+    );
+  }
+  calculateConfidence(urlParams, referrerUrl) {
+    let confidence = 0.5;
+    if (urlParams.get("utm_source")) confidence += 0.3;
+    if (urlParams.get("utm_campaign")) confidence += 0.2;
+    if (urlParams.get("utm_medium")) confidence += 0.1;
+    if (referrerUrl && !this.isFirstPartyReferrer(this.extractDomain(referrerUrl))) confidence += 0.2;
+    if (this.detectBot()) confidence -= 0.5;
+    if (urlParams.get("utm_source") === "test" || urlParams.get("utm_campaign") === "test") confidence -= 0.2;
+    return Math.max(0, Math.min(1, confidence));
+  }
+  extractDomain(url) {
+    if (!url) return "";
+    try {
+      return new URL(url).hostname.toLowerCase();
+    } catch {
+      return "";
+    }
+  }
+  isFirstPartyReferrer(domain) {
+    return ["hyve.gg", "dev.hyve.gg", "localhost"].some((d) => domain.includes(d));
+  }
+  isSearchEngine(domain) {
+    return ["google.com", "bing.com", "duckduckgo.com", "yahoo.com", "yandex.com"].some((e) => domain.includes(e));
+  }
+  isSocialPlatform(domain) {
+    return ["twitter.com", "x.com", "facebook.com", "meta.com", "linkedin.com", "reddit.com", "instagram.com", "tiktok.com", "youtube.com", "discord.com", "telegram.org", "farcaster.xyz", "warpcast.com", "t.me", "world.app"].some(
+      (p) => domain.includes(p)
+    );
+  }
+  isEmailClient(domain) {
+    return ["mail.google.com", "outlook.live.com", "mail.yahoo.com", "mail.aol.com"].some((c) => domain.includes(c));
+  }
+  getSessionCount() {
+    if (typeof window === "undefined") return 0;
+    try {
+      const stored = localStorage.getItem(this.SESSION_COUNT_KEY);
+      return stored ? parseInt(stored, 10) : 0;
+    } catch {
+      return 0;
+    }
+  }
+  storeAttribution(attribution) {
+    if (typeof window === "undefined") return;
+    try {
+      sessionStorage.setItem(this.STORAGE_KEY, JSON.stringify(attribution));
+      localStorage.setItem(this.SESSION_COUNT_KEY, attribution.session_count.toString());
+    } catch {
+    }
+  }
+  isValidAttributionData(data) {
+    return data !== null && typeof data === "object" && "traffic_type" in data && "attribution_confidence" in data && "platform_id" in data && "is_embedded" in data;
+  }
+  getEmptyAttribution() {
+    return {
+      utm_source: null,
+      utm_medium: null,
+      utm_campaign: null,
+      utm_term: null,
+      utm_content: null,
+      utm_id: null,
+      utm_source_platform: null,
+      platform_id: "web",
+      is_embedded: false,
+      referrer_url: null,
+      referrer_domain: null,
+      referrer_source: null,
+      is_first_party_referrer: false,
+      traffic_type: "direct",
+      first_visit_timestamp: 0,
+      session_count: 0,
+      is_bot: false,
+      attribution_confidence: 0
+    };
+  }
+};
+function getAttributionData() {
+  return AttributionManager.getInstance().getAttribution();
+}
+
 // src/services/ads.ts
 var AdsService = class {
   config = {
@@ -1758,20 +2061,39 @@ var HyveClient = class {
           return false;
         }
       }
-      const toJsonString = (data) => {
-        if (!data) return null;
-        return typeof data === "string" ? data : JSON.stringify(data);
+      let parsedEventDetails = {};
+      if (eventDetails) {
+        if (typeof eventDetails === "string") {
+          try {
+            parsedEventDetails = JSON.parse(eventDetails);
+          } catch {
+          }
+        } else {
+          parsedEventDetails = eventDetails;
+        }
+      }
+      const attribution = getAttributionData();
+      const enrichedEventDetails = {
+        // Device info
+        ...getEssentialDeviceInfo(),
+        // Attribution data
+        ...attribution,
+        // Timestamp and session context
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        session_id: this.sessionId,
+        // Event-specific details can override any of the above
+        ...parsedEventDetails
       };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
-        platform_id: platformId || null,
+        platform_id: platformId || attribution.platform_id || null,
         event_location: eventLocation,
         event_category: eventCategory,
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: toJsonString(eventDetails)
+        event_details: enrichedEventDetails
       };
       logger.debug("Sending telemetry event:", telemetryEvent);
       const telemetryUrl = `${this.apiBaseUrl}/api/v1/analytics/send`;