@l.x/analytics 0.0.0

package/.depcheckrc

@@ -0,0 +1,9 @@
+ignores: [
+    # Dependencies that depcheck incorrectly marks as unused
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+
+    # Internal packages / workspaces
+    "analytics",
+  ]

package/.eslintrc.js

@@ -0,0 +1,16 @@
+module.exports = {
+  extends: ['@luxfi/eslint-config/lib'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': 'off',
+        // track(event, properties, serverContext) is a natural 3-param signature for analytics.
+        'max-params': ['error', { max: 3 }],
+      },
+    },
+  ],
+}

package/LICENSE

@@ -0,0 +1,122 @@
+Lux Ecosystem License
+Version 1.2, December 2025
+
+Copyright (c) 2020-2025 Lux Industries Inc.
+All rights reserved.
+
+TECHNOLOGY PORTFOLIO - PATENT APPLICATIONS PLANNED
+Contact: licensing@lux.network
+
+================================================================================
+                          TERMS AND CONDITIONS
+================================================================================
+
+1. DEFINITIONS
+
+   "Lux Primary Network" means the official Lux blockchain with Network ID=1
+   and EVM Chain ID=96369.
+   
+   "Authorized Network" means the Lux Primary Network, official testnets/devnets,
+   and any L1/L2/L3 chain descending from the Lux Primary Network.
+   
+   "Descending Chain" means an L1/L2/L3 chain built on, anchored to, or deriving
+   security from the Lux Primary Network or its authorized testnets.
+   
+   "Research Use" means non-commercial academic research, education, personal
+   study, or evaluation purposes.
+   
+   "Commercial Use" means any use in connection with a product or service
+   offered for sale or fee, internal use by a for-profit entity, or any use
+   to generate revenue.
+
+2. GRANT OF LICENSE
+
+   Subject to these terms, Lux Industries Inc grants you a non-exclusive,
+   royalty-free license to:
+   
+   (a) Use for Research Use without restriction;
+   
+   (b) Operate on the Lux Primary Network (Network ID=1, EVM Chain ID=96369);
+   
+   (c) Operate on official Lux testnets and devnets;
+   
+   (d) Operate L1/L2/L3 chains descending from the Lux Primary Network;
+   
+   (e) Build applications within the Lux ecosystem;
+   
+   (f) Contribute improvements back to the original repositories.
+
+3. RESTRICTIONS
+
+   Without a commercial license from Lux Industries Inc, you may NOT:
+   
+   (a) Fork the Lux Network or any Lux software;
+   
+   (b) Create competing networks not descending from Lux Primary Network;
+   
+   (c) Use for Commercial Use outside the Lux ecosystem;
+   
+   (d) Sublicense or transfer rights outside the Lux ecosystem;
+   
+   (e) Use to create competing blockchain networks, exchanges, custody
+       services, or cryptographic systems outside the Lux ecosystem.
+
+4. NO FORKS POLICY
+
+   Lux Industries Inc maintains ZERO TOLERANCE for unauthorized forks.
+   Any fork or deployment on an unauthorized network constitutes:
+   
+   (a) Breach of this license;
+   (b) Grounds for immediate legal action.
+
+5. RIGHTS RESERVATION
+
+   All rights not explicitly granted are reserved by Lux Industries Inc.
+   
+   We plan to apply for patent protection for the technology in this
+   repository. Any implementation outside the Lux ecosystem may require
+   a separate commercial license.
+
+6. DISCLAIMER OF WARRANTY
+
+   THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+7. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LUX INDUSTRIES INC BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+8. TERMINATION
+
+   This license terminates immediately upon any breach, including but not
+   limited to deployment on unauthorized networks or creation of forks.
+
+9. GOVERNING LAW
+
+   This License shall be governed by the laws of the State of Delaware.
+
+10. COMMERCIAL LICENSING
+
+    For commercial use outside the Lux ecosystem:
+    
+    Lux Industries Inc.
+    Email: licensing@lux.network
+    Subject: Commercial License Request
+
+================================================================================
+                              TL;DR
+================================================================================
+
+- Research/academic use = OK
+- Lux Primary Network (Network ID=1, Chain ID=96369) = OK
+- L1/L2/L3 chains descending from Lux Primary Network = OK
+- Commercial products outside Lux ecosystem = Contact licensing@lux.network
+- Forks = Absolutely not
+
+================================================================================
+
+See LP-0012 for full licensing documentation:
+https://github.com/luxfi/lps/blob/main/LPs/lp-0012-ecosystem-licensing.md

package/README.md

@@ -0,0 +1,3 @@
+# @universe/analytics
+
+// TODO

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@l.x/analytics",
+  "version": "0.0.0",
+  "dependencies": {
+    "@amplitude/analytics-node": "1.5.36"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.1",
+    "@typescript/native-preview": "7.0.0-dev.20260311.1",
+    "depcheck": "1.4.7",
+    "eslint": "8.57.1",
+    "typescript": "5.8.3",
+    "@luxfi/eslint-config": "^1.0.5"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "main": "src/index.ts",
+  "private": false,
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "nx typecheck analytics",
+    "typecheck:tsgo": "nx typecheck:tsgo analytics",
+    "lint": "nx lint analytics",
+    "lint:fix": "nx lint:fix analytics",
+    "lint:biome": "nx lint:biome analytics",
+    "lint:biome:fix": "nx lint:biome:fix analytics",
+    "lint:eslint": "nx lint:eslint analytics",
+    "lint:eslint:fix": "nx lint:eslint:fix analytics",
+    "check:deps:usage": "nx check:deps:usage analytics"
+  }
+}

package/project.json

@@ -0,0 +1,18 @@
+{
+  "name": "@l.x/analytics",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "pkgs/analytics/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "typecheck": {},
+    "typecheck:tsgo": {},
+    "lint:biome": {},
+    "lint:biome:fix": {},
+    "lint:eslint": {},
+    "lint:eslint:fix": {},
+    "lint": {},
+    "lint:fix": {},
+    "check:deps:usage": {}
+  }
+}

package/src/ai-traffic.ts

@@ -0,0 +1,137 @@
+/**
+ * AI Traffic Classification & Tracking
+ *
+ * Classifies incoming requests into traffic types (crawler, signed-agent, ai-tool, human)
+ * and fires Amplitude events for non-human traffic.
+ *
+ * Three detection layers:
+ * 1. User-Agent matching for known AI crawlers (ClaudeBot, GPTBot, etc.)
+ * 2. RFC 9421 HTTP Message Signatures (ChatGPT browser agent)
+ * 3. Heuristic signals (Accept: text/markdown, non-browser UAs like axios/curl)
+ */
+
+import type { AnalyticsService, ServerEventContext } from './service'
+
+export type TrafficType = 'crawler' | 'signed-agent' | 'ai-tool' | 'human'
+
+export interface TrafficClassification {
+  type: TrafficType
+  agent?: string
+  signals: string[]
+}
+
+const CRAWLER_PATTERNS: Record<string, string> = {
+  ClaudeBot: 'anthropic-training',
+  'Claude-User': 'anthropic-user-fetch',
+  'Claude-SearchBot': 'anthropic-search',
+  'Claude-Web': 'anthropic-web',
+  'anthropic-ai': 'anthropic',
+  GPTBot: 'openai-training',
+  'ChatGPT-User': 'openai-user-fetch',
+  'OAI-SearchBot': 'openai-search',
+  PerplexityBot: 'perplexity',
+  'Perplexity-User': 'perplexity-user',
+  'Google-Extended': 'google-ai',
+  CCBot: 'common-crawl',
+  Bytespider: 'bytedance',
+}
+
+export function classifyTraffic(request: Request): TrafficClassification {
+  const ua = request.headers.get('user-agent') ?? ''
+  const accept = request.headers.get('accept') ?? ''
+  const signatureAgent = request.headers.get('signature-agent')
+
+  // Layer 1: Known AI crawlers (self-identifying via User-Agent)
+  for (const [pattern, agent] of Object.entries(CRAWLER_PATTERNS)) {
+    if (ua.includes(pattern)) {
+      return { type: 'crawler', agent, signals: [pattern] }
+    }
+  }
+
+  // Layer 2: Signed agents (RFC 9421 — ChatGPT browser agent)
+  if (signatureAgent) {
+    return {
+      type: 'signed-agent',
+      agent: signatureAgent.replace(/^"|"$/g, ''),
+      signals: ['signature-agent'],
+    }
+  }
+
+  // Layer 3: Heuristic signals for AI tools / non-browser clients
+  const signals: string[] = []
+
+  if (accept.includes('text/markdown') || accept.includes('text/x-markdown')) {
+    signals.push('accept-markdown')
+  }
+
+  if (ua.startsWith('curl/')) {
+    signals.push('curl')
+  }
+  if (ua.startsWith('Wget/')) {
+    signals.push('wget')
+  }
+  if (ua.includes('HTTPie/')) {
+    signals.push('httpie')
+  }
+  if (ua.startsWith('node-fetch') || ua.startsWith('undici')) {
+    signals.push('node-http')
+  }
+  if (ua.startsWith('python-requests') || ua.startsWith('python-httpx')) {
+    signals.push('python-http')
+  }
+  if (ua.startsWith('axios/')) {
+    signals.push('axios')
+  }
+  if (!ua) {
+    signals.push('no-ua')
+  }
+
+  if (signals.length > 0) {
+    return { type: 'ai-tool', signals }
+  }
+
+  return { type: 'human', signals: [] }
+}
+
+interface AITrafficTrackerDeps {
+  analyticsService: AnalyticsService
+  serverContext: ServerEventContext
+  eventName: string
+}
+
+interface AITrafficInput {
+  classification: TrafficClassification
+  path: string
+  request: Request
+}
+
+/**
+ * Create a tracker for non-human traffic events.
+ *
+ * Dependencies are bound once at the boundary (Hono middleware); the returned
+ * function only takes per-request input. Fire-and-forget — never throws.
+ */
+export function createAITrafficTracker({ analyticsService, serverContext, eventName }: AITrafficTrackerDeps) {
+  return ({ classification, path, request }: AITrafficInput): void => {
+    if (classification.type === 'human') {
+      return
+    }
+
+    try {
+      analyticsService.track(
+        eventName,
+        {
+          traffic_type: classification.type,
+          agent: classification.agent,
+          signals: classification.signals.join(','),
+          path,
+          user_agent: request.headers.get('user-agent') ?? '',
+          accept_header: request.headers.get('accept') ?? '',
+        },
+        serverContext,
+      )
+    } catch {
+      // Fire and forget — tracking failures must never affect request handling
+    }
+  }
+}

package/src/client-identity.ts

@@ -0,0 +1,71 @@
+/**
+ * Client Identity Forwarding
+ *
+ * During SSR, backend API calls originate from the server, not the browser.
+ * Without explicit forwarding, backends see the server's IP and User-Agent,
+ * causing issues like OTP emails showing server location instead of the user's.
+ *
+ * This module extracts client identity from the incoming request once at the
+ * boundary and provides it for explicit forwarding to all outbound API calls.
+ */
+
+/**
+ * Headers that identify the real client behind SSR requests.
+ * Uses cf-connecting-ip for backend compatibility (matches apps/web pattern).
+ */
+export interface ClientIdentityHeaders {
+  'cf-connecting-ip'?: string
+  'User-Agent'?: string
+}
+
+/**
+ * Extract the client's IP address from the request.
+ *
+ * IP resolution priority (most trusted first):
+ * 1. x-real-ip — set by Vercel/infra at the TCP level, cannot be spoofed by clients
+ * 2. cf-connecting-ip — set by Cloudflare edge
+ * 3. x-forwarded-for — first entry, least trusted (can be spoofed)
+ *
+ * Use for rate limiting, logging, and any context where you need just the IP string.
+ */
+export function getClientIp(request: Request): string {
+  return (
+    request.headers.get('x-real-ip') ??
+    request.headers.get('cf-connecting-ip') ??
+    request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+    'unknown'
+  )
+}
+
+/**
+ * Extract the client's country from edge-injected headers.
+ *
+ * Resolution priority:
+ * 1. x-vercel-ip-country — set by Vercel at the edge
+ * 2. cf-ipcountry — set by Cloudflare at the edge
+ */
+export function getClientCountry(request: Request): string | undefined {
+  return request.headers.get('x-vercel-ip-country') ?? request.headers.get('cf-ipcountry') ?? undefined
+}
+
+/**
+ * Extract full client identity headers for forwarding to backend APIs.
+ *
+ * Forwarded as cf-connecting-ip to match the header the backend already reads.
+ * This is the same pattern apps/web uses (see apps/web/functions/app.ts).
+ */
+export function extractClientIdentity(request: Request): ClientIdentityHeaders {
+  const headers: ClientIdentityHeaders = {}
+
+  const ip = getClientIp(request)
+  if (ip !== 'unknown') {
+    headers['cf-connecting-ip'] = ip
+  }
+
+  const userAgent = request.headers.get('User-Agent')
+  if (userAgent) {
+    headers['User-Agent'] = userAgent
+  }
+
+  return headers
+}

package/src/context.ts

@@ -0,0 +1,33 @@
+import { getClientCountry } from './client-identity'
+import type { ServerEventContext } from './service'
+import { extractDomain, stripQueryParams } from './url-utils'
+
+interface ServerContextExtractorDeps {
+  getAuthSession: (request?: Request) => Promise<{ session?: { userId?: string; provider?: string } | null }>
+  getDeviceId: (request: Request) => Promise<string | null>
+}
+
+/**
+ * Create a server context extractor with auth deps injected.
+ *
+ * The boundary (middleware, loader, tRPC context) owns the wiring;
+ * the returned function only needs the raw request.
+ */
+export function createServerContextExtractor({ getAuthSession, getDeviceId }: ServerContextExtractorDeps) {
+  return async (request: Request): Promise<ServerEventContext> => {
+    const [authResult, deviceId] = await Promise.all([getAuthSession(request), getDeviceId(request)])
+    const session = authResult.session
+    const rawReferrer = request.headers.get('Referer') ?? undefined
+    const referrer = rawReferrer ? stripQueryParams(rawReferrer) : undefined
+
+    return {
+      userId: session?.userId,
+      deviceId: deviceId ?? undefined,
+      provider: session?.provider,
+      language: request.headers.get('Accept-Language')?.split(',')[0]?.trim() ?? undefined,
+      country: getClientCountry(request),
+      referrer,
+      referringDomain: rawReferrer ? extractDomain(rawReferrer) : undefined,
+    }
+  }
+}

package/src/first-visit.ts

@@ -0,0 +1,144 @@
+/**
+ * First-Visit Attribution Capture
+ *
+ * Captures UTM params, referrer, browser, and country on the first visit.
+ * Persists UTM in a cookie (first-touch attribution) and fires an Amplitude
+ * `identify` call to set user properties.
+ *
+ * Called from the root loader — runs on every SSR page load but only
+ * identifies when there's new attribution data to capture.
+ */
+
+import { getClientCountry } from './client-identity'
+import type { AnalyticsService, UserTraits } from './service'
+import { extractDomain, stripQueryParams } from './url-utils'
+
+const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content'] as const
+
+export interface AttributionData {
+  utmSource?: string
+  utmMedium?: string
+  utmCampaign?: string
+  utmContent?: string
+  referrer?: string
+  referringDomain?: string
+  country?: string
+  browser?: string
+}
+
+/**
+ * Adapter for cookie parse/serialize — lets consumers bring their own
+ * cookie implementation (react-router createCookie, hono cookie, etc.).
+ */
+export interface CookieAdapter {
+  parse(cookieHeader: string | null): Promise<Record<string, string> | null>
+  serialize(value: Record<string, string>): Promise<string>
+}
+
+/**
+ * Parse browser family from User-Agent string.
+ * Intentionally simple — covers the major browsers.
+ */
+function parseBrowser(ua: string): string {
+  if (ua.includes('Edg/')) {
+    return 'Edge'
+  }
+  if (ua.includes('OPR/') || ua.includes('Opera')) {
+    return 'Opera'
+  }
+  if (ua.includes('Chrome/') && !ua.includes('Chromium/')) {
+    return 'Chrome'
+  }
+  if (ua.includes('Firefox/')) {
+    return 'Firefox'
+  }
+  if (ua.includes('Safari/') && !ua.includes('Chrome/')) {
+    return 'Safari'
+  }
+  if (ua.includes('MSIE') || ua.includes('Trident/')) {
+    return 'IE'
+  }
+  return 'Other'
+}
+
+interface AttributionTrackerDeps {
+  analyticsService: AnalyticsService
+  cookie: CookieAdapter
+}
+
+interface AttributionInput {
+  request: Request
+  userId: string | undefined
+}
+
+/**
+ * Create an attribution tracker with the analytics service injected.
+ *
+ * The boundary (root loader) owns the wiring; the returned function
+ * only takes per-request input. Returns a Set-Cookie header for UTM
+ * persistence on first-touch, and fires an Amplitude identify call.
+ */
+export function createAttributionTracker({ analyticsService, cookie }: AttributionTrackerDeps) {
+  return async ({ request, userId }: AttributionInput): Promise<{ setCookieHeader: string | null }> => {
+    if (!userId) {
+      return { setCookieHeader: null }
+    }
+
+    const url = new URL(request.url)
+    const ua = request.headers.get('user-agent') ?? ''
+    const referrer = request.headers.get('Referer') ?? undefined
+
+    // Extract UTM from query params
+    const utmData: Record<string, string> = {}
+    for (const param of UTM_PARAMS) {
+      const value = url.searchParams.get(param)
+      if (value) {
+        utmData[param] = value
+      }
+    }
+
+    const hasUtm = Object.keys(utmData).length > 0
+    const existingUtm = await cookie.parse(request.headers.get('Cookie'))
+    const isFirstUtm = hasUtm && !existingUtm
+
+    // Build traits — setOnce in the service means these won't overwrite
+    const traits: UserTraits = {}
+    const country = getClientCountry(request)
+    const browser = parseBrowser(ua)
+
+    if (browser !== 'Other') {
+      traits.browser = browser
+    }
+    if (country) {
+      traits.country = country
+    }
+    if (referrer) {
+      traits.referrer = stripQueryParams(referrer)
+      traits.referringDomain = extractDomain(referrer)
+    }
+    if (hasUtm) {
+      if (utmData['utm_source']) {
+        traits.utmSource = utmData['utm_source']
+      }
+      if (utmData['utm_medium']) {
+        traits.utmMedium = utmData['utm_medium']
+      }
+      if (utmData['utm_campaign']) {
+        traits.utmCampaign = utmData['utm_campaign']
+      }
+      if (utmData['utm_content']) {
+        traits.utmContent = utmData['utm_content']
+      }
+    }
+
+    // Only identify if we have something meaningful to set
+    const hasTraits = Object.keys(traits).length > 0
+    if (hasTraits) {
+      analyticsService.identify(userId, traits)
+    }
+
+    return {
+      setCookieHeader: isFirstUtm ? await cookie.serialize(utmData) : null,
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Traffic classification
+export type { TrafficClassification, TrafficType } from './ai-traffic'
+export { classifyTraffic, createAITrafficTracker } from './ai-traffic'
+
+// Client identity (HTTP header extraction)
+export type { ClientIdentityHeaders } from './client-identity'
+export { extractClientIdentity, getClientCountry, getClientIp } from './client-identity'
+
+// Context extraction
+export { createServerContextExtractor } from './context'
+
+// Attribution
+export type { AttributionData, CookieAdapter } from './first-visit'
+export { createAttributionTracker } from './first-visit'
+
+// Service
+export type { AnalyticsService, ServerEventContext, UserTraits } from './service'
+export { AmplitudeAnalyticsService, NoopAnalyticsService } from './service'
+
+// URL utilities
+export { extractDomain, stripQueryParams } from './url-utils'

package/src/service.ts

@@ -0,0 +1,108 @@
+import * as amplitude from '@amplitude/analytics-node'
+
+export interface ServerEventContext {
+  userId?: string
+  deviceId?: string
+  provider?: string
+  language?: string
+  country?: string
+  referrer?: string
+  referringDomain?: string
+}
+
+export interface UserTraits {
+  loginMethod?: string
+  apiKeyCount?: number
+  browser?: string
+  country?: string
+  referrer?: string
+  referringDomain?: string
+  utmSource?: string
+  utmMedium?: string
+  utmCampaign?: string
+  utmContent?: string
+}
+
+export interface AnalyticsService<E extends string = string> {
+  track(event: E, properties: Record<string, unknown>, serverContext: ServerEventContext): void
+  identify(userId: string, traits: UserTraits): void
+  flush(): Promise<void>
+}
+
+export class AmplitudeAnalyticsService<E extends string = string> implements AnalyticsService<E> {
+  private static initialized = false
+  private readonly platform: string
+
+  constructor(apiKey: string, platform: string) {
+    this.platform = platform
+
+    // Amplitude's Node SDK is a singleton; subsequent instances share this initialization.
+    if (!AmplitudeAnalyticsService.initialized) {
+      amplitude.init(apiKey, { flushIntervalMillis: 10_000 })
+      AmplitudeAnalyticsService.initialized = true
+    }
+  }
+
+  track(event: E, properties: Record<string, unknown>, serverContext: ServerEventContext): void {
+    amplitude.track({
+      event_type: event,
+      event_properties: { ...properties },
+      user_id: serverContext.userId,
+      device_id: serverContext.deviceId,
+      language: serverContext.language,
+      platform: this.platform,
+      user_properties: serverContext.provider ? { provider: serverContext.provider } : undefined,
+    })
+  }
+
+  identify(userId: string, traits: UserTraits): void {
+    const identifyEvent = new amplitude.Identify()
+    if (traits.loginMethod) {
+      identifyEvent.set('loginMethod', traits.loginMethod)
+    }
+    if (traits.apiKeyCount !== undefined) {
+      identifyEvent.set('apiKeyCount', traits.apiKeyCount)
+    }
+    if (traits.browser) {
+      identifyEvent.set('browser', traits.browser)
+    }
+    if (traits.country) {
+      identifyEvent.set('country', traits.country)
+    }
+    if (traits.referrer) {
+      identifyEvent.setOnce('referrer', traits.referrer)
+    }
+    if (traits.referringDomain) {
+      identifyEvent.setOnce('referringDomain', traits.referringDomain)
+    }
+    if (traits.utmSource) {
+      identifyEvent.setOnce('utmSource', traits.utmSource)
+    }
+    if (traits.utmMedium) {
+      identifyEvent.setOnce('utmMedium', traits.utmMedium)
+    }
+    if (traits.utmCampaign) {
+      identifyEvent.setOnce('utmCampaign', traits.utmCampaign)
+    }
+    if (traits.utmContent) {
+      identifyEvent.setOnce('utmContent', traits.utmContent)
+    }
+    amplitude.identify(identifyEvent, { user_id: userId })
+  }
+
+  async flush(): Promise<void> {
+    await amplitude.flush()
+  }
+}
+
+export class NoopAnalyticsService implements AnalyticsService {
+  track(): void {
+    // No-op
+  }
+  identify(): void {
+    // No-op
+  }
+  async flush(): Promise<void> {
+    // No-op
+  }
+}

package/src/url-utils.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared URL helpers for analytics modules.
+ */
+
+/** Extract the hostname from a URL (e.g. "https://google.com/search?q=..." → "google.com"). */
+export function extractDomain(url: string): string | undefined {
+  try {
+    return new URL(url).hostname
+  } catch {
+    return undefined
+  }
+}
+
+/** Strip query params from a URL to avoid leaking PII. */
+export function stripQueryParams(url: string): string | undefined {
+  try {
+    const parsed = new URL(url)
+    return `${parsed.origin}${parsed.pathname}`
+  } catch {
+    return undefined
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "extends": "../../config/tsconfig/app.json",
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.json",
+    "src/global.d.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx"
+  ],
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "types": ["node"],
+    "paths": {}
+  },
+  "references": [
+    {
+      "path": "../eslint-config"
+    }
+  ]
+}

package/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "preserveSymlinks": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", "**/*.json"],
+  "exclude": ["node_modules"]
+}