@tryghost/referrer-parser 0.0.2

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../lib/ReferrerParser.ts","../index.ts"],"sourcesContent":["/**\n * Interface for parsed referrer data\n */\nexport interface ReferrerData {\n    /** The identified source of the referral traffic */\n    referrerSource: string | null;\n    /** The identified medium of the referral traffic */\n    referrerMedium: string | null;\n    /** The hostname of the referral URL */\n    referrerUrl: string | null;\n}\n\n/**\n * Configuration options for the parser\n */\nexport interface ParserOptions {\n    /** URL of the site for identifying internal traffic */\n    siteUrl?: string;\n    /** URL of the admin panel for identifying admin traffic */\n    adminUrl?: string;\n}\n\n/**\n * Interface for referrer source data\n */\ninterface ReferrerSourceData {\n    source: string;\n    medium: string;\n}\n\n// Import known referrers data\nimport knownReferrers from './referrers.json';\n\n/**\n * Parses referrer URLs to determine source and medium\n */\nexport class ReferrerParser {\n    private adminUrl: URL | null;\n    private siteUrl: URL | null;\n\n    /**\n     * Creates a new referrer parser instance\n     * \n     * @param options - Configuration options\n     */\n    constructor(options: ParserOptions = {}) {\n        this.adminUrl = this.getUrlFromStr(options.adminUrl || '');\n        this.siteUrl = this.getUrlFromStr(options.siteUrl || '');\n    }\n\n    /**\n     * Parse a referrer URL to get source, medium and hostname\n     * \n     * @param referrerUrlStr - URL of the referrer\n     * @returns Parsed referrer data with source, medium and URL\n     */\n    parse(referrerUrlStr: string): ReferrerData {\n        if (!referrerUrlStr) {\n            return {\n                referrerSource: 'Direct',\n                referrerMedium: null,\n                referrerUrl: null\n            };\n        }\n\n        const referrerUrl = this.getUrlFromStr(referrerUrlStr);\n        if (!referrerUrl) {\n            return {\n                referrerSource: 'Direct',\n                referrerMedium: null,\n                referrerUrl: null\n            };\n        }\n\n        // Skip Stripe checkout URLs\n        if (referrerUrl.hostname === 'checkout.stripe.com') {\n            return {\n                referrerSource: 'Direct',\n                referrerMedium: null,\n                referrerUrl: null\n            };\n        }\n\n        // Check for source/medium in query parameters\n        const urlParams = new URLSearchParams(referrerUrl.search);\n        const referrerSource = urlParams.get('utm_source') || urlParams.get('source') || null;\n        const referrerMedium = urlParams.get('utm_medium') || urlParams.get('medium') || null;\n\n        // If referrer is Ghost Explore\n        if (this.isGhostExploreRef({referrerUrl, referrerSource})) {\n            return {\n                referrerSource: 'Ghost Explore',\n                referrerMedium: 'Ghost Network',\n                referrerUrl: referrerUrl?.hostname ?? null\n            };\n        }\n\n        // If referrer is Ghost.org\n        if (this.isGhostOrgUrl(referrerUrl)) {\n            return {\n                referrerSource: 'Ghost.org',\n                referrerMedium: 'Ghost Network',\n                referrerUrl: referrerUrl?.hostname\n            };\n        }\n\n        // Check for Ghost Newsletter\n        if (this.isGhostNewsletter({referrerSource})) {\n            return {\n                referrerSource: referrerSource!.replace(/-newsletter$/, ' newsletter'),\n                referrerMedium: 'Email',\n                referrerUrl: referrerUrl?.hostname ?? null\n            };\n        }\n\n        // If referrer source is available from parameters\n        if (referrerSource) {\n            const urlData = this.getDataFromUrl(referrerUrl);\n            const knownSource = Object.values(knownReferrers as Record<string, ReferrerSourceData>).find(referrer => \n                referrer.source.toLowerCase() === referrerSource.toLowerCase());\n            \n            return {\n                referrerSource: knownSource?.source || referrerSource,\n                referrerMedium: knownSource?.medium || referrerMedium || urlData?.medium || null,\n                referrerUrl: referrerUrl?.hostname ?? null\n            };\n        }\n\n        // If referrer is known external URL\n        if (!this.isSiteDomain(referrerUrl)) {\n            const urlData = this.getDataFromUrl(referrerUrl);\n\n            // Use known source/medium if available\n            if (urlData) {\n                return {\n                    referrerSource: urlData?.source ?? null,\n                    referrerMedium: urlData?.medium ?? null,\n                    referrerUrl: referrerUrl?.hostname ?? null\n                };\n            }\n            \n            // Use the hostname as a source\n            return {\n                referrerSource: referrerUrl?.hostname ?? null,\n                referrerMedium: null,\n                referrerUrl: referrerUrl?.hostname ?? null\n            };\n        }\n\n        return {\n            referrerSource: 'Direct',\n            referrerMedium: null,\n            referrerUrl: null\n        };\n    }\n\n    /**\n     * Fetches referrer data from known external URLs\n     * \n     * @param url - The URL to match against known referrers\n     * @returns Matched referrer data or null if not found\n     */\n    getDataFromUrl(url: URL | null): ReferrerSourceData | null {\n        // Handle null url case\n        if (!url) {\n            return null;\n        }\n\n        // Allow matching both \"google.ac/products\" and \"google.ac\" as a source\n        const urlHostPath = url.hostname + url.pathname;\n        const urlDataKey = Object.keys(knownReferrers as Record<string, ReferrerSourceData>).sort((a, b) => {\n            // The longer key has higher priority so google.ac/products is selected before google.ac\n            return b.length - a.length;\n        }).find((source) => {\n            return urlHostPath.startsWith(source);\n        });\n\n        return urlDataKey ? (knownReferrers as Record<string, ReferrerSourceData>)[urlDataKey] : null;\n    }\n\n    /**\n     * Return URL object for provided URL string\n     * \n     * @param url - URL string to parse\n     * @returns Parsed URL object or null if invalid\n     */\n    getUrlFromStr(url: string): URL | null {\n        if (!url) {\n            return null;\n        }\n        \n        try {\n            return new URL(url);\n        } catch (e) {\n            return null;\n        }\n    }\n\n    /**\n     * Determine whether the provided URL is a link to the site\n     * \n     * @param url - URL to check\n     * @returns True if the URL belongs to the configured site\n     */\n    isSiteDomain(url: URL | null): boolean {\n        try {\n            // If we don't have siteUrl configured, we can't detect internal traffic\n            if (!this.siteUrl) {\n                return false;\n            }\n\n            if (!url) {\n                return false;\n            }\n\n            if (this.siteUrl.hostname === url.hostname) {\n                if (url.pathname.startsWith(this.siteUrl.pathname)) {\n                    return true;\n                }\n                return false;\n            }\n            return false;\n        } catch (e) {\n            return false;\n        }\n    }\n\n    /**\n     * Determine whether referrer is a Ghost newsletter\n     * \n     * @param deps - Input parameters\n     * @returns True if the referrer is a Ghost newsletter\n     */\n    isGhostNewsletter({referrerSource}: {referrerSource: string | null}): boolean {\n        if (!referrerSource) {\n            return false;\n        }\n        // if referrer source ends with -newsletter\n        return referrerSource.endsWith('-newsletter');\n    }\n\n    /**\n     * Determine whether referrer is a Ghost.org URL\n     * \n     * @param referrerUrl - The referrer URL to check\n     * @returns True if the referrer is from Ghost.org\n     */\n    isGhostOrgUrl(referrerUrl: URL | null): boolean {\n        if (!referrerUrl) {\n            return false;\n        }\n        return referrerUrl.hostname === 'ghost.org';\n    }\n\n    /**\n     * Determine whether referrer is Ghost Explore\n     * \n     * @param deps - Input parameters\n     * @returns True if the referrer is from Ghost Explore\n     */\n    isGhostExploreRef({referrerUrl, referrerSource}: {referrerUrl: URL | null, referrerSource?: string | null}): boolean {\n        // Always check for ghost-explore source param\n        if (referrerSource === 'ghost-explore') {\n            return true;\n        }\n\n        if (!referrerUrl) {\n            return false;\n        }\n\n        // Check domain for explore.ghost.io and try.ghost.org/explore\n        if (referrerUrl.hostname === 'explore.ghost.io') {\n            return true;\n        }\n\n        if (referrerUrl.hostname === 'try.ghost.org' && referrerUrl.pathname.startsWith('/explore')) {\n            return true;\n        }\n\n        return false;\n    }\n} ","import { ReferrerParser } from './lib/ReferrerParser';\nimport type { ReferrerData, ParserOptions } from './lib/ReferrerParser';\n\n/**\n * Parse a referrer URL to get source, medium and hostname\n * \n * @param referrerUrl - URL of the referrer to parse\n * @param options - Configuration options\n * @returns Parsed referrer data with source, medium and URL\n * \n * @example\n * // Basic usage\n * const result = parse('https://www.google.com/search?q=ghost+cms');\n * // result: { referrerSource: 'Google', referrerMedium: 'search', referrerUrl: 'www.google.com' }\n * \n * @example\n * // With site configuration\n * const result = parse('https://example.com/blog?utm_source=newsletter', {\n *   siteUrl: 'https://example.com'\n * });\n */\nfunction parse(referrerUrl: string, options: ParserOptions = {}): ReferrerData {\n    const parser = new ReferrerParser(options);\n    return parser.parse(referrerUrl);\n}\n\nexport {\n    parse,\n    ReferrerParser\n};\n\nexport type {\n    ReferrerData,\n    ParserOptions\n}; "],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/lib/ReferrerParser.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Interface for parsed referrer data
+ */
+export interface ReferrerData {
+    /** The identified source of the referral traffic */
+    referrerSource: string | null;
+    /** The identified medium of the referral traffic */
+    referrerMedium: string | null;
+    /** The hostname of the referral URL */
+    referrerUrl: string | null;
+}
+/**
+ * Configuration options for the parser
+ */
+export interface ParserOptions {
+    /** URL of the site for identifying internal traffic */
+    siteUrl?: string;
+    /** URL of the admin panel for identifying admin traffic */
+    adminUrl?: string;
+}
+/**
+ * Interface for referrer source data
+ */
+interface ReferrerSourceData {
+    source: string;
+    medium: string;
+}
+/**
+ * Parses referrer URLs to determine source and medium
+ */
+export declare class ReferrerParser {
+    private adminUrl;
+    private siteUrl;
+    /**
+     * Creates a new referrer parser instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: ParserOptions);
+    /**
+     * Parse a referrer URL to get source, medium and hostname
+     *
+     * @param referrerUrlStr - URL of the referrer
+     * @returns Parsed referrer data with source, medium and URL
+     */
+    parse(referrerUrlStr: string): ReferrerData;
+    /**
+     * Fetches referrer data from known external URLs
+     *
+     * @param url - The URL to match against known referrers
+     * @returns Matched referrer data or null if not found
+     */
+    getDataFromUrl(url: URL | null): ReferrerSourceData | null;
+    /**
+     * Return URL object for provided URL string
+     *
+     * @param url - URL string to parse
+     * @returns Parsed URL object or null if invalid
+     */
+    getUrlFromStr(url: string): URL | null;
+    /**
+     * Determine whether the provided URL is a link to the site
+     *
+     * @param url - URL to check
+     * @returns True if the URL belongs to the configured site
+     */
+    isSiteDomain(url: URL | null): boolean;
+    /**
+     * Determine whether referrer is a Ghost newsletter
+     *
+     * @param deps - Input parameters
+     * @returns True if the referrer is a Ghost newsletter
+     */
+    isGhostNewsletter({ referrerSource }: {
+        referrerSource: string | null;
+    }): boolean;
+    /**
+     * Determine whether referrer is a Ghost.org URL
+     *
+     * @param referrerUrl - The referrer URL to check
+     * @returns True if the referrer is from Ghost.org
+     */
+    isGhostOrgUrl(referrerUrl: URL | null): boolean;
+    /**
+     * Determine whether referrer is Ghost Explore
+     *
+     * @param deps - Input parameters
+     * @returns True if the referrer is from Ghost Explore
+     */
+    isGhostExploreRef({ referrerUrl, referrerSource }: {
+        referrerUrl: URL | null;
+        referrerSource?: string | null;
+    }): boolean;
+}
+export {};