Added url-referrer-parser package (#516)

ref https://linear.app/ghost/issue/PROD-4/

The URL parsing logic previously contained within TryGhost/Ghost's member-attribution package has been pulled out into a more generic library for url referrer parsing. This makes it available to ancillary services while maintaining the same mapping/logic across Ghost.

Author: 9larsons

package-lock.json

@@ -0,0 +1,26 @@
+module.exports = {
+    extends: [
+        'eslint:recommended',
+        'plugin:@typescript-eslint/recommended'
+    ],
+    parser: '@typescript-eslint/parser',
+    plugins: ['@typescript-eslint'],
+    parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+    },
+    env: {
+        node: true,
+        es2022: true
+    },
+    ignorePatterns: ['dist', '*.config.ts'],
+    rules: {
+        'no-console': 'warn',
+        '@typescript-eslint/explicit-function-return-type': 'off',
+        '@typescript-eslint/no-explicit-any': 'warn',
+        '@typescript-eslint/no-unused-vars': ['error', { 
+            'argsIgnorePattern': '^_',
+            'varsIgnorePattern': '^_' 
+        }]
+    }
+}; 

packages/url-referrer-parser/.eslintrc.js

@@ -0,0 +1,23 @@
+# Build output
+dist/
+
+# Coverage directory
+coverage/
+
+# Test artifacts
+.vitest/
+
+# Log files
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor directories and files
+.vscode/
+.idea/
+*.sublime-*
+
+# OS specific files
+.DS_Store
+Thumbs.db 

packages/url-referrer-parser/.gitignore

@@ -0,0 +1,33 @@
+# Source files
+*.ts
+!*.d.ts
+lib/*.ts
+!lib/*.d.ts
+
+# Development files
+test/
+coverage/
+.eslintrc.js
+.eslintcache
+tsconfig.json
+.editorconfig
+.github
+.npmignore
+.gitignore
+
+# GitHub files
+.github/
+*.md
+!README.md
+
+# Configuration
+.eslintignore
+.travis.yml
+.vscode
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log* 

packages/url-referrer-parser/.npmignore

@@ -0,0 +1,107 @@
+# Referrer Parser
+
+A simple library for parsing referrer URLs to identify their source and medium.
+
+## Installation
+
+```bash
+npm install @tryghost/referrer-parser
+# or
+yarn add @tryghost/referrer-parser
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const { parse } = require('@tryghost/referrer-parser');
+
+// Parse a referrer URL
+const result = parse('https://www.google.com/search?q=ghost+cms');
+console.log(result);
+// {
+//   referrerSource: 'Google',
+//   referrerMedium: 'search',
+//   referrerUrl: 'www.google.com'
+// }
+```
+
+### With Site Configuration
+
+```javascript
+const { parse } = require('@tryghost/referrer-parser');
+
+// Parse with site configuration to detect internal traffic
+const result = parse(
+  'https://example.com/blog?utm_source=newsletter&utm_medium=email',
+  { 
+    siteUrl: 'https://example.com',
+    adminUrl: 'https://example.com/ghost'
+  }
+);
+```
+
+### Using the ReferrerParser Class
+
+For more advanced usage, you can use the `ReferrerParser` class directly:
+
+```javascript
+const { ReferrerParser } = require('@tryghost/referrer-parser');
+
+// Create a parser instance
+const parser = new ReferrerParser({
+  siteUrl: 'https://example.com',
+  adminUrl: 'https://example.com/ghost'
+});
+
+// Parse multiple URLs with the same configuration
+const result1 = parser.parse('https://www.google.com/search?q=ghost+cms');
+const result2 = parser.parse('https://twitter.com/ghostcms');
+```
+
+## Features
+
+- Identifies sources and mediums from known referrers
+- Handles special cases for Ghost Explore and Ghost Newsletters
+- Detects UTM parameters
+- Works with or without site/admin URL configuration
+- TypeScript support
+
+## TypeScript Support
+
+This package is fully written in TypeScript and provides its own type definitions.
+
+```typescript
+import { parse, ReferrerParser, ReferrerData, ParserOptions } from '@tryghost/referrer-parser';
+
+// Parse a referrer URL with type safety
+const result: ReferrerData = parse('https://www.google.com/search?q=ghost+cms');
+console.log(result.referrerSource);  // 'Google'
+console.log(result.referrerMedium);  // 'search'
+console.log(result.referrerUrl);     // 'www.google.com'
+
+// Configure the parser with typed options
+const options: ParserOptions = {
+  siteUrl: 'https://example.com',
+  adminUrl: 'https://example.com/ghost'
+};
+
+// Create a parser instance with TypeScript
+const parser = new ReferrerParser(options);
+const customResult = parser.parse('https://example.com/blog?utm_source=newsletter');
+```
+
+## License
+
+MIT 
+
+## Testing
+
+Run the tests with:
+
+```bash
+yarn test
+```
+
+This will run the test suite using Mocha and report on test coverage. 

packages/url-referrer-parser/README.md

@@ -0,0 +1,35 @@
+import { ReferrerParser } from './lib/ReferrerParser';
+import type { ReferrerData, ParserOptions } from './lib/ReferrerParser';
+
+/**
+ * Parse a referrer URL to get source, medium and hostname
+ * 
+ * @param referrerUrl - URL of the referrer to parse
+ * @param options - Configuration options
+ * @returns Parsed referrer data with source, medium and URL
+ * 
+ * @example
+ * // Basic usage
+ * const result = parse('https://www.google.com/search?q=ghost+cms');
+ * // result: { referrerSource: 'Google', referrerMedium: 'search', referrerUrl: 'www.google.com' }
+ * 
+ * @example
+ * // With site configuration
+ * const result = parse('https://example.com/blog?utm_source=newsletter', {
+ *   siteUrl: 'https://example.com'
+ * });
+ */
+function parse(referrerUrl: string, options: ParserOptions = {}): ReferrerData {
+    const parser = new ReferrerParser(options);
+    return parser.parse(referrerUrl);
+}
+
+export {
+    parse,
+    ReferrerParser
+};
+
+export type {
+    ReferrerData,
+    ParserOptions
+};