@huloglobal/vendure-plugin-visitor-analytics 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@huloglobal/vendure-plugin-visitor-analytics` are
+documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this
+project adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — Unreleased
+
+### Added
+- **UTM attribution** — `utmSource` / `utmMedium` / `utmCampaign` /
+  `utmTerm` / `utmContent` and `referrerDomain` columns parsed from every
+  incoming pageview URL. New `GET /ees/visitors/sources` admin endpoint
+  groups visitors by `(source, medium)` plus per-source conversion
+  counts (reached product page, reached cart/checkout).
+- **Live-now widget** — Server-Sent Events stream at
+  `GET /ees/visitors/live` pushing the active-visitor count and the
+  20 most recent URLs every 5 seconds. SSE clients auto-reconnect.
+- **Top events** admin endpoint at `GET /ees/visitors/top-events`,
+  paginated.
+- **Custom event recipes** — README section with copy-paste storefront
+  snippets for add-to-cart, search, quote-request, newsletter signup.
+
+## [0.1.0] — Unreleased
+
+### Added
+- `VisitorAnalyticsPlugin` — ingest endpoint + admin dashboards.
+- `VisitorEvent` entity capturing pageview / unload / event rows with
+  full UA parse, MaxMind geo enrichment, raw + hashed IP.
+- Proxy-aware IP / country / region extraction (Cloudflare, Akamai,
+  Fastly headers all detected; falls back to MaxMind only if the
+  upstream didn't already resolve country).
+- Admin endpoints: summary, top pages (paginated), exit pages
+  (paginated), funnel, recent visitors (paginated), per-visitor
+  profile + journey.
+- Admin UI: summary tiles, funnel bars, top + exit page tables,
+  recent visitors table with clickable profile drawer.
+- Licence verification via `@huloglobal/vendure-licence-sdk` with revocation
+  polling.

package/LICENSE

@@ -0,0 +1,34 @@
+HULO Global Limited — Commercial Plugin Licence
+
+Copyright (c) 2026 HULO Global Limited. All rights reserved.
+
+This software is licensed, not sold, and is made available only to users
+who hold a valid, active subscription or perpetual licence purchased
+from HULO Global Limited.
+
+Permitted use:
+
+  1. The software may be installed and run on a single Vendure
+     instance per active subscription (or per perpetual licence). Each
+     licence is bound to one or more hostnames named at purchase time.
+
+  2. The source code is published only so that customers may audit it
+     for security review. Modification of the source for production use
+     is permitted, but redistribution of the modified source or of any
+     derivative work — in whole or in part — is not permitted.
+
+Prohibited use:
+
+  - Use without a valid, active licence key, except for non-production
+    evaluation under the plugin's "unlicensed mode" (which writes basic
+    delivery rows but disables the open/click endpoints).
+  - Use of the package to circumvent the licence verification routine,
+    or to extract or replace the embedded RSA public key.
+  - Resale, sublicensing, or distribution of the package outside of an
+    application that itself holds a valid HULO Vendure plugin licence.
+
+No warranty. To the maximum extent permitted by law, HULO Global Limited
+disclaims all warranties and all liability arising from use of this
+software.
+
+For commercial licensing enquiries: sales@eliteenterprisesoftware.com

package/README.md

@@ -0,0 +1,167 @@
+# @huloglobal/vendure-plugin-visitor-analytics
+
+Full-funnel visitor analytics for Vendure storefronts. Captures every
+pageview, time-on-page, and exit point; bundles a per-visitor profile
+drawer with parsed user-agent, MaxMind geo enrichment and a complete
+event timeline; stitches guest browsing to signed-in browsing across
+sessions so the journey survives login.
+
+Maintained by Wayne Garrison.
+
+## What you get
+
+- **Ingest endpoint** at `POST /ees/track` that takes a small batch of
+  events from the storefront. Issues a long-lived visitor cookie
+  (`ees_vid`, 2 years) and a sliding session cookie (`ees_sid`,
+  30-minute idle).
+- **Auto-enrichment** at ingest time:
+  - User-agent parsed via `ua-parser-js` → browser / browser version /
+    OS / OS version / device type. Bots auto-detected.
+  - IP-to-geo via MaxMind GeoLite2-City (no MaxMind account required,
+    DB fetched at install via `geolite2-redist`). Or use the upstream
+    proxy's resolved country / region when Cloudflare / Akamai /
+    Fastly is in front — saves the lookup.
+  - Raw IP is kept; a SHA-256 salted hash is stored alongside for
+    spot-the-same-bot work.
+- **Admin endpoints**: summary tiles, top pages, exit pages, funnel,
+  recent visitors, per-visitor profile + journey timeline. All
+  paginated.
+- **Admin UI**: top-line tiles, funnel bars, top + exit page tables,
+  recent visitors with a clickable profile drawer showing every field
+  + per-session breakdown + the full event timeline.
+
+## Install
+
+```bash
+yarn add @huloglobal/vendure-plugin-visitor-analytics
+```
+
+## Wire up
+
+```ts
+import { VisitorAnalyticsPlugin } from '@huloglobal/vendure-plugin-visitor-analytics';
+
+export const config: VendureConfig = {
+  plugins: [
+    VisitorAnalyticsPlugin.init({
+      publicBaseUrl: 'https://shop.example.com',
+      licenceKey: process.env.HULO_LICENCE_KEY,
+    }),
+  ],
+};
+```
+
+Add to your admin-ui compile step:
+
+```ts
+import { VisitorAnalyticsPlugin } from '@huloglobal/vendure-plugin-visitor-analytics';
+
+compileUiExtensions({
+  outputPath: 'admin-ui',
+  extensions: [VisitorAnalyticsPlugin.uiExtensions /* + your other extensions */],
+});
+```
+
+## Storefront integration
+
+The plugin ships only the backend; the storefront emits events. A Qwik
+storefront example:
+
+```ts
+// utils/tracker.ts
+const TRACK_URL = 'https://shop.example.com/ees/track';
+let lastPath = '';
+let pageOpenedAt = 0;
+
+export function recordPageView(): void {
+  const url = location.pathname + location.search;
+  const events: any[] = [];
+  if (lastPath && lastPath !== url) {
+    events.push({ type: 'unload', url: lastPath, timeOnPageMs: Date.now() - pageOpenedAt });
+  }
+  events.push({ type: 'pageview', url, title: document.title, referrer: document.referrer });
+  lastPath = url;
+  pageOpenedAt = Date.now();
+  fetch(TRACK_URL, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ channelId: 1, events }),
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+// On unload, prefer sendBeacon — it survives tab-close.
+window.addEventListener('pagehide', () => {
+  const blob = new Blob([JSON.stringify({
+    channelId: 1,
+    events: [{ type: 'unload', url: lastPath, timeOnPageMs: Date.now() - pageOpenedAt }],
+  })], { type: 'application/json' });
+  navigator.sendBeacon(TRACK_URL, blob);
+});
+```
+
+## Custom events
+
+Fire a `recordEvent(type, meta?)` call from your storefront whenever a
+visitor does something interesting — add-to-cart, search, signup,
+quote-request — and the event shows up in the admin "Top events" table
+straight away.
+
+```ts
+function recordEvent(type, meta) {
+  navigator.sendBeacon(TRACK_URL, new Blob([JSON.stringify({
+    channelId: 1,
+    events: [{ type, url: location.pathname + location.search, meta }],
+  })], { type: 'application/json' }));
+}
+
+// Add to cart
+recordEvent('add_to_cart', { sku: 'WIN11-PRO', priceWithTax: 28900 });
+
+// Search query submitted
+recordEvent('search', { query: 'windows server 2022' });
+
+// Quote request from the contact form
+recordEvent('quote_request', { customerEmail });
+
+// Newsletter signup
+recordEvent('newsletter_signup', { source: 'footer' });
+```
+
+The full meta blob is persisted as JSON on the event row so you can
+slice on it later from the admin UI.
+
+## UTM attribution
+
+The plugin parses `utm_source` / `utm_medium` / `utm_campaign` /
+`utm_term` / `utm_content` from the URL of every incoming event and
+captures the referrer domain alongside. The admin "Traffic sources"
+table groups visitors by `(source, medium)` so you can see which
+campaigns convert.
+
+Drop `?utm_source=google&utm_medium=cpc&utm_campaign=spring24` onto any
+inbound link and it surfaces automatically — no extra config.
+
+## Live now widget
+
+The admin dashboard's top tile streams the currently-active visitor
+count + the URLs they're on in real time via Server-Sent Events
+(`GET /ees/visitors/live`). Updates every 5 seconds, reconnects
+automatically if the connection drops. Active = at least one event in
+the last 5 minutes.
+
+## Init options
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `publicBaseUrl` | `string` | yes | Public hostname of your Vendure server (must match licence). |
+| `licenceKey` | `string` | no* | JWT licence key. Without it ingest works but the admin dashboards return 403. |
+
+\* Required for production use. Buy at
+`https://elite-software.co.uk/licence/buy/vendure-plugin-visitor-analytics`.
+
+## Licence
+
+Commercial — see [LICENSE](./LICENSE). Requires an active subscription
+($9.95/mo) or a perpetual licence.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@huloglobal/vendure-plugin-visitor-analytics` — public exports.
+ */
+export { VisitorAnalyticsPlugin, VisitorAnalyticsPluginOptions } from './plugin';
+export { VisitorTrackingService } from './visitor-tracking.service';
+export { VisitorEvent } from './visitor-event.entity';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,UAAU,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * `@huloglobal/vendure-plugin-visitor-analytics` — public exports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisitorEvent = exports.VisitorTrackingService = exports.VisitorAnalyticsPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "VisitorAnalyticsPlugin", { enumerable: true, get: function () { return plugin_1.VisitorAnalyticsPlugin; } });
+var visitor_tracking_service_1 = require("./visitor-tracking.service");
+Object.defineProperty(exports, "VisitorTrackingService", { enumerable: true, get: function () { return visitor_tracking_service_1.VisitorTrackingService; } });
+var visitor_event_entity_1 = require("./visitor-event.entity");
+Object.defineProperty(exports, "VisitorEvent", { enumerable: true, get: function () { return visitor_event_entity_1.VisitorEvent; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,mCAAiF;AAAxE,gHAAA,sBAAsB,OAAA;AAC/B,uEAAoE;AAA3D,kIAAA,sBAAsB,OAAA;AAC/B,+DAAsD;AAA7C,oHAAA,YAAY,OAAA"}

package/dist/plugin.d.ts

@@ -0,0 +1,47 @@
+import { Type } from '@vendure/core';
+export interface VisitorAnalyticsPluginOptions {
+    /** Public host of the Vendure server. Used in licence host-match. */
+    publicBaseUrl: string;
+    /** JWT licence key. Without it the ingest endpoint accepts events
+     *  and writes basic rows, but the admin analytics endpoints return
+     *  403 — i.e. data collection works for evaluation but you can't
+     *  read the dashboard without a licence. */
+    licenceKey?: string;
+}
+/**
+ * `@huloglobal/vendure-plugin-visitor-analytics`
+ *
+ * Full-funnel visitor analytics: page views, time-on-page, exit pages,
+ * a configurable funnel, and a per-visitor profile drawer with
+ * parsed user-agent + MaxMind GeoLite2 geo enrichment. Survives login
+ * — guest events and signed-in events share the same `visitorId`.
+ *
+ * Add to your Vendure config:
+ *
+ * ```ts
+ * import { VisitorAnalyticsPlugin } from '@huloglobal/vendure-plugin-visitor-analytics';
+ *
+ * export const config: VendureConfig = {
+ *   plugins: [
+ *     VisitorAnalyticsPlugin.init({
+ *       publicBaseUrl: 'https://shop.example.com',
+ *       licenceKey: process.env.HULO_LICENCE_KEY,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare class VisitorAnalyticsPlugin {
+    private static revocation;
+    static init(options: VisitorAnalyticsPluginOptions): Type<VisitorAnalyticsPlugin>;
+    static uiExtensions: {
+        extensionPath: string;
+        ngModules: {
+            type: "lazy";
+            route: string;
+            ngModuleFileName: string;
+            ngModuleName: string;
+        }[];
+    };
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,IAAI,EAAiB,MAAM,eAAe,CAAC;AAMxE,MAAM,WAAW,6BAA6B;IAC1C,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB;;;gDAG4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAgBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAOa,sBAAsB;IAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAkC;IAE3D,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAAC,sBAAsB,CAAC;IA2BjF,MAAM,CAAC,YAAY;;;;;;;;MAUjB;CACL"}

package/dist/plugin.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var VisitorAnalyticsPlugin_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisitorAnalyticsPlugin = void 0;
+const core_1 = require("@vendure/core");
+const vendure_licence_sdk_1 = require("@huloglobal/vendure-licence-sdk");
+const visitor_event_entity_1 = require("./visitor-event.entity");
+const visitor_tracking_service_1 = require("./visitor-tracking.service");
+const visitor_tracking_controller_1 = require("./visitor-tracking.controller");
+const HULO_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoLmNM5UljRqe71drM6lR
+Ba5vXrLOcV3GAHkYvnVFQSqdE0avrge/jsD7WdA6x8qQFNRugxQcxDJa2l0+C+BH
+SbU9TimGwhA1yusHHfuz9LAXks5IQ48+2e6Pulh7iThXPJUnIKqKZUN5HhL79aaK
+vrZKIgSfVhwE5PMPXWZ+Ij5IRf74PLIUn1Er75qhBXlDJ4vF8y8/3owURNC1XiUB
+DGElwV/LYNoqAQei4oixe4EAxPGvFi11pgHiGuRxuWckA88y6ZHLt6urfAY9sCkj
+kF+2dc2yS3j7lD+SYAaV5LQYYjePP1CYvxCZ7HHRKqthHopxY1hsK2tBtni3f7/c
+UwIDAQAB
+-----END PUBLIC KEY-----`;
+const PLUGIN_ID = 'vendure-plugin-visitor-analytics';
+const REVOCATION_URL = process.env.HULO_LICENCE_REVOCATION_URL
+    || 'https://elite.charity/licence/revoked.json';
+/**
+ * `@huloglobal/vendure-plugin-visitor-analytics`
+ *
+ * Full-funnel visitor analytics: page views, time-on-page, exit pages,
+ * a configurable funnel, and a per-visitor profile drawer with
+ * parsed user-agent + MaxMind GeoLite2 geo enrichment. Survives login
+ * — guest events and signed-in events share the same `visitorId`.
+ *
+ * Add to your Vendure config:
+ *
+ * ```ts
+ * import { VisitorAnalyticsPlugin } from '@huloglobal/vendure-plugin-visitor-analytics';
+ *
+ * export const config: VendureConfig = {
+ *   plugins: [
+ *     VisitorAnalyticsPlugin.init({
+ *       publicBaseUrl: 'https://shop.example.com',
+ *       licenceKey: process.env.HULO_LICENCE_KEY,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+let VisitorAnalyticsPlugin = VisitorAnalyticsPlugin_1 = class VisitorAnalyticsPlugin {
+    static init(options) {
+        if (!VisitorAnalyticsPlugin_1.revocation) {
+            VisitorAnalyticsPlugin_1.revocation = new vendure_licence_sdk_1.RevocationChecker(REVOCATION_URL);
+            VisitorAnalyticsPlugin_1.revocation.start();
+        }
+        const host = (options.publicBaseUrl || '')
+            .replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+        const status = (0, vendure_licence_sdk_1.verifyLicence)({
+            licenceKey: options.licenceKey,
+            pluginId: PLUGIN_ID,
+            host,
+            publicKey: HULO_PUBLIC_KEY,
+            revokedIds: VisitorAnalyticsPlugin_1.revocation.getRevokedIds(),
+        });
+        if (!status.valid) {
+            // eslint-disable-next-line no-console
+            console.warn(`[@huloglobal/vendure-plugin-visitor-analytics] ${status.message}` +
+                ` — Running in unlicensed mode (ingest works, admin dashboards disabled). Purchase a key at https://elite-software.co.uk/licence/buy/${PLUGIN_ID}`);
+        }
+        return VisitorAnalyticsPlugin_1;
+    }
+};
+exports.VisitorAnalyticsPlugin = VisitorAnalyticsPlugin;
+VisitorAnalyticsPlugin.revocation = null;
+VisitorAnalyticsPlugin.uiExtensions = {
+    extensionPath: __dirname + '/../ui',
+    ngModules: [
+        {
+            type: 'lazy',
+            route: 'visitors',
+            ngModuleFileName: 'visitors.module.ts',
+            ngModuleName: 'VisitorsModule',
+        },
+    ],
+};
+exports.VisitorAnalyticsPlugin = VisitorAnalyticsPlugin = VisitorAnalyticsPlugin_1 = __decorate([
+    (0, core_1.VendurePlugin)({
+        imports: [core_1.PluginCommonModule],
+        providers: [visitor_tracking_service_1.VisitorTrackingService],
+        controllers: [visitor_tracking_controller_1.VisitorTrackingController],
+        entities: [visitor_event_entity_1.VisitorEvent],
+        compatibility: '^3.0.0',
+    })
+], VisitorAnalyticsPlugin);
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,wCAAwE;AACxE,yEAAmF;AACnF,iEAAsD;AACtD,yEAAoE;AACpE,+EAA0E;AAY1E,MAAM,eAAe,GAAG;;;;;;;;yBAQC,CAAC;AAE1B,MAAM,SAAS,GAAG,kCAAkC,CAAC;AACrD,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B;OACvD,4CAA4C,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQI,IAAM,sBAAsB,8BAA5B,MAAM,sBAAsB;IAG/B,MAAM,CAAC,IAAI,CAAC,OAAsC;QAC9C,IAAI,CAAC,wBAAsB,CAAC,UAAU,EAAE,CAAC;YACrC,wBAAsB,CAAC,UAAU,GAAG,IAAI,uCAAiB,CAAC,cAAc,CAAC,CAAC;YAC1E,wBAAsB,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAC9C,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;aACrC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,IAAA,mCAAa,EAAC;YACzB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,QAAQ,EAAE,SAAS;YACnB,IAAI;YACJ,SAAS,EAAE,eAAe;YAC1B,UAAU,EAAE,wBAAsB,CAAC,UAAU,CAAC,aAAa,EAAE;SAChE,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAChB,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACR,kDAAkD,MAAM,CAAC,OAAO,EAAE;gBAClE,uIAAuI,SAAS,EAAE,CACrJ,CAAC;QACN,CAAC;QAED,OAAO,wBAAsB,CAAC;IAClC,CAAC;;AA5BQ,wDAAsB;AAChB,iCAAU,GAA6B,IAAI,AAAjC,CAAkC;AA6BpD,mCAAY,GAAG;IAClB,aAAa,EAAE,SAAS,GAAG,QAAQ;IACnC,SAAS,EAAE;QACP;YACI,IAAI,EAAE,MAAe;YACrB,KAAK,EAAE,UAAU;YACjB,gBAAgB,EAAE,oBAAoB;YACtC,YAAY,EAAE,gBAAgB;SACjC;KACJ;CACJ,AAVkB,CAUjB;iCAxCO,sBAAsB;IAPlC,IAAA,oBAAa,EAAC;QACX,OAAO,EAAE,CAAC,yBAAkB,CAAC;QAC7B,SAAS,EAAE,CAAC,iDAAsB,CAAC;QACnC,WAAW,EAAE,CAAC,uDAAyB,CAAC;QACxC,QAAQ,EAAE,CAAC,mCAAY,CAAC;QACxB,aAAa,EAAE,QAAQ;KAC1B,CAAC;GACW,sBAAsB,CAyClC"}

package/dist/proxy-headers.d.ts

@@ -0,0 +1,37 @@
+import { Request } from 'express';
+/**
+ * Reverse-proxy aware visitor IP extraction.
+ *
+ * Order of precedence:
+ *   1. Cloudflare's `CF-Connecting-IP` (always the real client IP,
+ *      regardless of how many proxies sit in front of the worker).
+ *   2. `True-Client-IP` (Akamai / Cloudflare Enterprise).
+ *   3. `X-Real-IP` (nginx / Caddy default when proxying).
+ *   4. First entry in `X-Forwarded-For` (RFC 7239 ancestor; the
+ *      left-most entry is the original client when the upstream proxy
+ *      is trusted).
+ *   5. Express's `req.ip` — only useful when `app.set('trust proxy', ...)`
+ *      has been set on the Vendure host, otherwise this is the socket
+ *      address of the last hop.
+ *
+ * Returns `null` if none of the headers are populated and `req.ip`
+ * isn't available — the caller should treat this as "unknown" and
+ * skip IP-dependent enrichment rather than fail.
+ */
+export declare function getRealIp(req: Request): string | null;
+/**
+ * Cloudflare / Akamai populate the visitor's resolved country on the
+ * inbound request when the corresponding feature is enabled. Reading
+ * the upstream value avoids a per-request GeoIP lookup. Returns the
+ * ISO 3166-1 alpha-2 country code or `null` if no proxy header is
+ * present.
+ */
+export declare function getResolvedCountry(req: Request): string | null;
+/**
+ * Cloudflare's `cf-region-code` carries the ISO 3166-2 subdivision
+ * (e.g. `ENG`, `SCT`, `CA`) when the "Send subdivision data" option is
+ * enabled in the dashboard. Returns the bare code without the country
+ * prefix, or `null` if unavailable.
+ */
+export declare function getResolvedRegion(req: Request): string | null;
+//# sourceMappingURL=proxy-headers.d.ts.map

package/dist/proxy-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-headers.d.ts","sourceRoot":"","sources":["../src/proxy-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkBrD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK7D"}

package/dist/proxy-headers.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRealIp = getRealIp;
+exports.getResolvedCountry = getResolvedCountry;
+exports.getResolvedRegion = getResolvedRegion;
+/**
+ * Reverse-proxy aware visitor IP extraction.
+ *
+ * Order of precedence:
+ *   1. Cloudflare's `CF-Connecting-IP` (always the real client IP,
+ *      regardless of how many proxies sit in front of the worker).
+ *   2. `True-Client-IP` (Akamai / Cloudflare Enterprise).
+ *   3. `X-Real-IP` (nginx / Caddy default when proxying).
+ *   4. First entry in `X-Forwarded-For` (RFC 7239 ancestor; the
+ *      left-most entry is the original client when the upstream proxy
+ *      is trusted).
+ *   5. Express's `req.ip` — only useful when `app.set('trust proxy', ...)`
+ *      has been set on the Vendure host, otherwise this is the socket
+ *      address of the last hop.
+ *
+ * Returns `null` if none of the headers are populated and `req.ip`
+ * isn't available — the caller should treat this as "unknown" and
+ * skip IP-dependent enrichment rather than fail.
+ */
+function getRealIp(req) {
+    var _a;
+    const headers = req.headers || {};
+    const cfIp = String(headers['cf-connecting-ip'] || '').trim();
+    if (cfIp)
+        return cfIp;
+    const trueClient = String(headers['true-client-ip'] || '').trim();
+    if (trueClient)
+        return trueClient;
+    const realIp = String(headers['x-real-ip'] || '').trim();
+    if (realIp)
+        return realIp;
+    const xff = String(headers['x-forwarded-for'] || '').trim();
+    if (xff) {
+        const first = (_a = xff.split(',')[0]) === null || _a === void 0 ? void 0 : _a.trim();
+        if (first)
+            return first;
+    }
+    return req.ip || null;
+}
+/**
+ * Cloudflare / Akamai populate the visitor's resolved country on the
+ * inbound request when the corresponding feature is enabled. Reading
+ * the upstream value avoids a per-request GeoIP lookup. Returns the
+ * ISO 3166-1 alpha-2 country code or `null` if no proxy header is
+ * present.
+ */
+function getResolvedCountry(req) {
+    const headers = req.headers || {};
+    const cf = String(headers['cf-ipcountry'] || '').trim().toUpperCase();
+    if (cf && cf !== 'XX' && cf !== 'T1')
+        return cf;
+    const akamai = String(headers['x-akamai-edgescape'] || '').trim();
+    if (akamai) {
+        const m = akamai.match(/country_code=([A-Z]{2})/i);
+        if (m)
+            return m[1].toUpperCase();
+    }
+    const fastly = String(headers['x-country-code'] || '').trim().toUpperCase();
+    if (fastly && /^[A-Z]{2}$/.test(fastly))
+        return fastly;
+    return null;
+}
+/**
+ * Cloudflare's `cf-region-code` carries the ISO 3166-2 subdivision
+ * (e.g. `ENG`, `SCT`, `CA`) when the "Send subdivision data" option is
+ * enabled in the dashboard. Returns the bare code without the country
+ * prefix, or `null` if unavailable.
+ */
+function getResolvedRegion(req) {
+    const headers = req.headers || {};
+    const cf = String(headers['cf-region-code'] || '').trim().toUpperCase();
+    if (cf && /^[A-Z0-9]{1,4}$/.test(cf))
+        return cf;
+    return null;
+}
+//# sourceMappingURL=proxy-headers.js.map

package/dist/proxy-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-headers.js","sourceRoot":"","sources":["../src/proxy-headers.ts"],"names":[],"mappings":";;AAqBA,8BAkBC;AASD,gDAeC;AAQD,8CAKC;AA1ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,SAAS,CAAC,GAAY;;IAClC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9D,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAElC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,IAAI,GAAG,EAAE,CAAC;QACN,MAAM,KAAK,GAAG,MAAA,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,0CAAE,IAAI,EAAE,CAAC;QACxC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC5B,CAAC;IAED,OAAQ,GAAW,CAAC,EAAE,IAAI,IAAI,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,GAAY;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAEhD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,MAAM,EAAE,CAAC;QACT,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QACnD,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5E,IAAI,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAEvD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxE,IAAI,EAAE,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAChD,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/visitor-event.entity.d.ts

@@ -0,0 +1,68 @@
+import { DeepPartial, VendureEntity } from '@vendure/core';
+/**
+ * Stores a single visitor analytics event — used to map the customer
+ * journey across the storefront, including for visitors who never log in.
+ *
+ *   type='pageview' — a new page was opened (one row per navigation)
+ *   type='unload'   — a page was closed / hidden; `timeOnPageMs` is the
+ *                     time the visitor spent on it before leaving
+ *   type='event'    — a custom event raised by the frontend (e.g. an
+ *                     add-to-cart click); the payload lives in `meta`
+ *
+ * `visitorId` is a long-lived cookie UUID (2 years) — identifies the
+ * device across sessions. `sessionId` is a short-lived cookie UUID
+ * (30-minute idle expiry) — identifies a single browsing burst.
+ *
+ * `customerId` is set when the visitor is logged in; the same
+ * `visitorId` can carry guest events first and then customer events
+ * once the visitor signs in / signs up — that's what makes the funnel
+ * analysis work.
+ */
+export declare class VisitorEvent extends VendureEntity {
+    constructor(input?: DeepPartial<VisitorEvent>);
+    visitorId: string;
+    sessionId: string;
+    customerId: number | null;
+    channelId: number;
+    type: 'pageview' | 'unload' | 'event' | string;
+    /** Pathname + search, no host. Capped at 2048 to fit Cloudflare's max URL. */
+    url: string;
+    /** Document title at the time of the event — useful for the journey
+     *  timeline so the admin sees "Product: Windows 11" instead of just
+     *  "/products/microsoft-windows-11-professional/". */
+    title: string | null;
+    referrer: string | null;
+    /** Set only on `unload` rows — milliseconds the visitor spent on the
+     *  page before leaving. */
+    timeOnPageMs: number | null;
+    /** Hash of the visitor's IP address — kept for spot-the-same-IP-bot
+     *  analysis even after the raw IP is purged. */
+    ipHash: string | null;
+    /** Raw client IP. Max length 45 chars covers full IPv6 + zone id. */
+    ip: string | null;
+    userAgent: string | null;
+    /** Parsed user-agent — populated server-side at ingest. */
+    browser: string | null;
+    browserVersion: string | null;
+    os: string | null;
+    osVersion: string | null;
+    device: string | null;
+    /** `Accept-Language` header, capped. */
+    acceptLanguage: string | null;
+    country: string | null;
+    region: string | null;
+    city: string | null;
+    timezone: string | null;
+    /** Arbitrary JSON payload for `type='event'` rows. */
+    meta: string | null;
+    utmSource: string | null;
+    utmMedium: string | null;
+    utmCampaign: string | null;
+    utmTerm: string | null;
+    utmContent: string | null;
+    /** Lowercased host of `referrer` (e.g. `google.com`, `facebook.com`).
+     *  Stored alongside the full referrer string so admin reports can
+     *  group by domain without parsing every URL at read time. */
+    referrerDomain: string | null;
+}
+//# sourceMappingURL=visitor-event.entity.d.ts.map

package/dist/visitor-event.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitor-event.entity.d.ts","sourceRoot":"","sources":["../src/visitor-event.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAMa,YAAa,SAAQ,aAAa;gBAC/B,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC;IAG7C,SAAS,EAAG,MAAM,CAAC;IAGnB,SAAS,EAAG,MAAM,CAAC;IAGnB,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAG3B,SAAS,EAAG,MAAM,CAAC;IAGnB,IAAI,EAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAEhD,8EAA8E;IAE9E,GAAG,EAAG,MAAM,CAAC;IAEb;;0DAEsD;IAEtD,KAAK,EAAG,MAAM,GAAG,IAAI,CAAC;IAGtB,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAEzB;+BAC2B;IAE3B,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAE7B;oDACgD;IAEhD,MAAM,EAAG,MAAM,GAAG,IAAI,CAAC;IAEvB,qEAAqE;IAErE,EAAE,EAAG,MAAM,GAAG,IAAI,CAAC;IAGnB,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAE1B,2DAA2D;IAE3D,OAAO,EAAG,MAAM,GAAG,IAAI,CAAC;IAGxB,cAAc,EAAG,MAAM,GAAG,IAAI,CAAC;IAG/B,EAAE,EAAG,MAAM,GAAG,IAAI,CAAC;IAGnB,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAG1B,MAAM,EAAG,MAAM,GAAG,IAAI,CAAC;IAEvB,wCAAwC;IAExC,cAAc,EAAG,MAAM,GAAG,IAAI,CAAC;IAG/B,OAAO,EAAG,MAAM,GAAG,IAAI,CAAC;IAGxB,MAAM,EAAG,MAAM,GAAG,IAAI,CAAC;IAGvB,IAAI,EAAG,MAAM,GAAG,IAAI,CAAC;IAGrB,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAEzB,sDAAsD;IAEtD,IAAI,EAAG,MAAM,GAAG,IAAI,CAAC;IAUrB,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAG1B,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAG1B,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAG5B,OAAO,EAAG,MAAM,GAAG,IAAI,CAAC;IAGxB,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAE3B;;kEAE8D;IAE9D,cAAc,EAAG,MAAM,GAAG,IAAI,CAAC;CAClC"}