@grainql/analytics-web 2.2.1 → 2.4.0

package/dist/esm/attribution.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Attribution and Referral Tracking for Grain Analytics
+ * Handles referral categorization and first-touch attribution
+ */
+export type ReferrerCategory = 'organic' | 'paid' | 'social' | 'direct' | 'email' | 'referral';
+export interface UTMParameters {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+export interface FirstTouchAttribution {
+    source: string;
+    medium: string;
+    campaign: string;
+    referrer: string;
+    referrer_category: ReferrerCategory;
+    timestamp: number;
+}
+/**
+ * Categorize referrer based on domain and parameters
+ */
+export declare function categorizeReferrer(referrer: string, currentUrl?: string): ReferrerCategory;
+/**
+ * Parse UTM parameters from URL
+ */
+export declare function parseUTMParameters(url: string): UTMParameters;
+/**
+ * Get first-touch attribution from localStorage
+ */
+export declare function getFirstTouchAttribution(tenantId: string): FirstTouchAttribution | null;
+/**
+ * Set first-touch attribution in localStorage
+ */
+export declare function setFirstTouchAttribution(tenantId: string, attribution: FirstTouchAttribution): void;
+/**
+ * Get or create first-touch attribution
+ */
+export declare function getOrCreateFirstTouchAttribution(tenantId: string, referrer: string, currentUrl: string, utmParams: UTMParameters): FirstTouchAttribution;
+export declare function getSessionUTMParameters(): UTMParameters | null;
+export declare function setSessionUTMParameters(params: UTMParameters): void;
+/**
+ * Clear session UTM parameters
+ */
+export declare function clearSessionUTMParameters(): void;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/esm/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/attribution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/F,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAkFD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,MAAW,GAAG,gBAAgB,CAsC9F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAqB7D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAgBvF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAWN;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,aAAa,GACvB,qBAAqB,CAwBvB;AAOD,wBAAgB,uBAAuB,IAAI,aAAa,GAAG,IAAI,CAE9D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAEnE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/esm/attribution.js

@@ -0,0 +1,218 @@
+/**
+ * Attribution and Referral Tracking for Grain Analytics
+ * Handles referral categorization and first-touch attribution
+ */
+/**
+ * Known paid search parameters
+ */
+const PAID_SEARCH_PARAMS = [
+    'gclid', // Google Ads
+    'msclkid', // Microsoft Ads
+    'fbclid', // Facebook Ads
+    'ttclid', // TikTok Ads
+    'li_fat_id', // LinkedIn Ads
+    'twclid', // Twitter Ads
+    'ScCid', // Snapchat Ads
+];
+/**
+ * Known social media domains
+ */
+const SOCIAL_DOMAINS = [
+    'facebook.com',
+    'twitter.com',
+    'x.com',
+    'linkedin.com',
+    'instagram.com',
+    'pinterest.com',
+    'reddit.com',
+    'tiktok.com',
+    'youtube.com',
+    'snapchat.com',
+    't.co', // Twitter short links
+    'fb.me', // Facebook short links
+    'lnkd.in', // LinkedIn short links
+];
+/**
+ * Known organic search engines
+ */
+const SEARCH_ENGINES = [
+    'google.',
+    'bing.com',
+    'yahoo.com',
+    'duckduckgo.com',
+    'baidu.com',
+    'yandex.com',
+    'ecosia.org',
+    'ask.com',
+];
+/**
+ * Email client domains
+ */
+const EMAIL_DOMAINS = [
+    'mail.google.com',
+    'outlook.live.com',
+    'mail.yahoo.com',
+    'mail.aol.com',
+];
+/**
+ * Extract domain from URL
+ */
+function extractDomain(url) {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Check if URL contains paid search parameters
+ */
+function hasPaidSearchParams(url) {
+    try {
+        const urlObj = new URL(url);
+        return PAID_SEARCH_PARAMS.some(param => urlObj.searchParams.has(param));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Categorize referrer based on domain and parameters
+ */
+export function categorizeReferrer(referrer, currentUrl = '') {
+    // Direct traffic (no referrer)
+    if (!referrer || referrer.trim() === '') {
+        return 'direct';
+    }
+    const domain = extractDomain(referrer);
+    // Same domain = direct
+    if (currentUrl) {
+        const currentDomain = extractDomain(currentUrl);
+        if (domain === currentDomain) {
+            return 'direct';
+        }
+    }
+    // Check for paid search parameters
+    if (hasPaidSearchParams(referrer) || hasPaidSearchParams(currentUrl)) {
+        return 'paid';
+    }
+    // Email clients
+    if (EMAIL_DOMAINS.some(emailDomain => domain.includes(emailDomain))) {
+        return 'email';
+    }
+    // Social media
+    if (SOCIAL_DOMAINS.some(socialDomain => domain.includes(socialDomain))) {
+        return 'social';
+    }
+    // Organic search engines
+    if (SEARCH_ENGINES.some(searchEngine => domain.includes(searchEngine))) {
+        return 'organic';
+    }
+    // Everything else is referral
+    return 'referral';
+}
+/**
+ * Parse UTM parameters from URL
+ */
+export function parseUTMParameters(url) {
+    try {
+        const urlObj = new URL(url);
+        const params = {};
+        const utmSource = urlObj.searchParams.get('utm_source');
+        const utmMedium = urlObj.searchParams.get('utm_medium');
+        const utmCampaign = urlObj.searchParams.get('utm_campaign');
+        const utmTerm = urlObj.searchParams.get('utm_term');
+        const utmContent = urlObj.searchParams.get('utm_content');
+        if (utmSource)
+            params.utm_source = utmSource;
+        if (utmMedium)
+            params.utm_medium = utmMedium;
+        if (utmCampaign)
+            params.utm_campaign = utmCampaign;
+        if (utmTerm)
+            params.utm_term = utmTerm;
+        if (utmContent)
+            params.utm_content = utmContent;
+        return params;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Get first-touch attribution from localStorage
+ */
+export function getFirstTouchAttribution(tenantId) {
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return null;
+    }
+    try {
+        const key = `_grain_first_touch_${tenantId}`;
+        const stored = localStorage.getItem(key);
+        if (stored) {
+            return JSON.parse(stored);
+        }
+    }
+    catch (error) {
+        console.warn('[Grain Attribution] Failed to retrieve first-touch attribution:', error);
+    }
+    return null;
+}
+/**
+ * Set first-touch attribution in localStorage
+ */
+export function setFirstTouchAttribution(tenantId, attribution) {
+    if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+        return;
+    }
+    try {
+        const key = `_grain_first_touch_${tenantId}`;
+        localStorage.setItem(key, JSON.stringify(attribution));
+    }
+    catch (error) {
+        console.warn('[Grain Attribution] Failed to store first-touch attribution:', error);
+    }
+}
+/**
+ * Get or create first-touch attribution
+ */
+export function getOrCreateFirstTouchAttribution(tenantId, referrer, currentUrl, utmParams) {
+    // Try to get existing first-touch
+    const existing = getFirstTouchAttribution(tenantId);
+    if (existing) {
+        return existing;
+    }
+    // Create new first-touch attribution
+    const referrerCategory = categorizeReferrer(referrer, currentUrl);
+    const referrerDomain = extractDomain(referrer);
+    const firstTouch = {
+        source: utmParams.utm_source || referrerDomain || 'direct',
+        medium: utmParams.utm_medium || referrerCategory,
+        campaign: utmParams.utm_campaign || 'none',
+        referrer: referrer || 'direct',
+        referrer_category: referrerCategory,
+        timestamp: Date.now(),
+    };
+    // Store it
+    setFirstTouchAttribution(tenantId, firstTouch);
+    return firstTouch;
+}
+/**
+ * Get session UTM parameters (memory-only, not persisted across page loads)
+ */
+let sessionUTMParams = null;
+export function getSessionUTMParameters() {
+    return sessionUTMParams;
+}
+export function setSessionUTMParameters(params) {
+    sessionUTMParams = params;
+}
+/**
+ * Clear session UTM parameters
+ */
+export function clearSessionUTMParameters() {
+    sessionUTMParams = null;
+}
+//# sourceMappingURL=attribution.js.map

package/dist/esm/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/attribution.ts"],"names":[],"mappings":"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"}

package/dist/esm/countries.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Get full country name from user's timezone
+ * @returns Full country name or null if timezone is unavailable
+ */
+export declare function getCountry(): string | null;
+/**
+ * Get country code (ISO 3166-1 alpha-2) from user's timezone
+ * Privacy-friendly alternative to IP geolocation
+ * @returns ISO 3166-1 alpha-2 country code (e.g., "US", "GB") or "Unknown"
+ */
+export declare function getCountryCodeFromTimezone(): string;
+export declare function getState(): string | null;
+//# sourceMappingURL=countries.d.ts.map

package/dist/esm/countries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"countries.d.ts","sourceRoot":"","sources":["../../src/countries.ts"],"names":[],"mappings":"AAyyFA;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAe1C;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAanD;AAED,wBAAgB,QAAQ,IAAI,MAAM,GAAG,IAAI,CAUxC"}