@tryghost/referrer-parser 0.1.15 → 0.1.17

package/dist/lib/ReferrerParser.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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
+     * @param referrerSource - Source of the referrer
+     * @param referrerMedium - Medium of the referrer
+     * @returns Parsed referrer data with source, medium and URL. Internal referrers return null values.
+     */
+    parse(referrerUrlStr: string, referrerSource?: string, referrerMedium?: 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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/referrer-parser",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Simple library for parsing referrer URLs",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -47,19 +47,18 @@
   },
   "homepage": "https://ghost.org",
   "devDependencies": {
-    "@types/node": "24.12.0",
+    "@types/node": "24.12.3",
     "@types/should": "13.0.0",
-    "@types/sinon": "21.0.0",
-    "@typescript-eslint/eslint-plugin": "8.57.0",
-    "@typescript-eslint/parser": "8.57.0",
-    "@vitest/coverage-v8": "4.1.0",
-    "eslint": "10.0.3",
+    "@types/sinon": "21.0.1",
+    "@typescript-eslint/eslint-plugin": "8.59.2",
+    "@typescript-eslint/parser": "8.59.2",
+    "@vitest/coverage-v8": "4.1.5",
     "should": "13.2.3",
-    "sinon": "21.0.2",
+    "sinon": "22.0.0",
     "typescript": "5.9.3",
-    "vite": "7.3.1",
-    "vite-plugin-dts": "4.5.4",
-    "vitest": "4.1.0"
+    "vite": "8.0.11",
+    "vite-plugin-dts": "5.0.0",
+    "vitest": "4.1.5"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -67,5 +66,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9cc8428821b292029029019e1af6fb24a75709ad"
+  "gitHead": "c938d752eb5b9cfd4bf4110f16153a3594db3a00"
 }