@huloglobal/vendure-plugin-visitor-analytics 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -5,6 +5,87 @@ 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.8.0] — 2026-07-04
+
+### Added
+
+**Cart abandonment — end-to-end.**
+- New `AbandonedCart` entity, keyed on session id. One row per
+  abandoned session, refreshed in place until it either converts
+  (order placed) or expires (recovery window elapses).
+- `AbandonedCartService.scan()` — periodic sweep finds sessions with
+  `cart_snapshot` events but no `checkout_completed` in the
+  abandonment window (default 30 min). Auto-promotes previously
+  abandoned rows to `converted` when the customer later checks out.
+- Ships with a boot-time timer (worker-only, 5-minute cadence).
+  Idempotent — safe to horizontally scale, only the worker runs it.
+- Signed recovery links — `POST /ees/abandoned-carts/:id/recovery-link`
+  returns a time-bounded opaque token the storefront exchanges via
+  `GET /ees/recover-cart?t=…` to rebuild the exact cart. Storefront
+  never sees the underlying items until the token is presented.
+- Slack notification for high-value abandonments — configurable
+  threshold and webhook via the `abandonment` plugin option.
+- Admin API:
+  - `GET  /ees/abandoned-carts` — paginated list with status,
+    value and email filters.
+  - `GET  /ees/abandoned-carts/summary` — totals, recovery rate,
+    recovered vs. lost value in the window.
+  - `GET  /ees/abandoned-carts/:id` — detail incl. parsed items.
+  - `POST /ees/abandoned-carts/:id/status` — mark recovered /
+    dismissed / re-open.
+  - `GET  /ees/abandoned-carts/export.csv` — CSV export.
+
+**Co-view product recommendations.**
+- New `ProductCoView` aggregate table. Scanner walks recent
+  `product_view` events per session, extracts every ordered pair,
+  and increments a per-triple counter. Bounded to 20 events per
+  session so runaway bot sessions can't skew the table.
+- Denormalised — both `(A, B)` and `(B, A)` stored — so read-side
+  lookups are one indexed scan.
+- Runs every 6 hours on the worker; also exposed as
+  `GET /ees/recommendations/aggregate-now` for admins to kick a
+  fresh run after a data backfill.
+- Public read endpoints (safe from the storefront):
+  - `GET /ees/recommendations/also-viewed?productId=…` — the
+    "customers who viewed X also viewed…" rail on a product page.
+  - `GET /ees/recommendations/personal?visitorId=…` — personalised
+    recs for a returning visitor, from their last 10 product views
+    over 30 days. Excludes seeds.
+  - `GET /ees/recommendations/trending?hours=24` — most-viewed
+    products in the window. Reflects real interest, not search-
+    console clicks.
+
+**Site search analytics.**
+- Reads back over `visitor_event` where the storefront has fired
+  `hulo.search(query, resultsCount)`. Zero new schema.
+- `GET /ees/search-analytics/top` — top queries by volume with
+  average results count.
+- `GET /ees/search-analytics/no-results` — top zero-result queries.
+  Direct catalogue-gap intel.
+- `GET /ees/search-analytics/conversion` — of sessions that
+  searched, what fraction went on to fire `add_to_cart`.
+
+**Journey drawer buffs.**
+- Rage-click + dead-click aggregation, keyed on URL. Store-wide
+  hot-spot lists for pages where visitors are stuck or frustrated.
+- Per-visitor session summary with a heuristic `intent` label
+  (`purchase` / `abandon` / `frustrate` / `consider` / `browse` /
+  `bounce`) computed from event history — one glance per session
+  in the Journey drawer instead of scrolling event rows.
+
+**Storefront helper events (documented in the README).**
+- `hulo.cartSnapshot({ currency, totalMinor, itemCount, items, email })`
+- `hulo.productView(productId, productVariantId?)`
+- `hulo.search(query, resultsCount)`
+- `hulo.rageClick(url, selector?)` / `hulo.deadClick(url, selector)`
+- `hulo.checkoutCompleted()`
+- All flow into the existing `POST /ees/track` endpoint with a
+  standard shape, so admins can also fire them from any language.
+
+### Changed
+- `checkout_completed` is now a first-class recognised event type
+  — the abandonment scanner uses it to auto-close matched rows.
+
 ## [0.7.0] — 2026-07-04
 
 ### Added
@@ -149,6 +230,7 @@ adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
 - Licence verification via `@huloglobal/vendure-licence-sdk` with
   revocation polling.
 
+[0.8.0]: https://github.com/exceeded/vendure-plugin-visitor-analytics/releases/tag/v0.8.0
 [0.7.0]: https://github.com/exceeded/vendure-plugin-visitor-analytics/releases/tag/v0.7.0
 [0.6.0]: https://github.com/exceeded/vendure-plugin-visitor-analytics/releases/tag/v0.6.0
 [0.5.0]: https://github.com/exceeded/vendure-plugin-visitor-analytics/releases/tag/v0.5.0

package/README.md

@@ -7,6 +7,14 @@ and a per-visitor profile drawer with parsed user-agent and MaxMind
 geo. Privacy-first defaults: DNT, IP anonymisation, optional consent
 gate.
 
+Since 0.8.0 the plugin also ships **cart abandonment** (detection,
+signed recovery links, Slack notification, admin dashboard),
+**co-view product recommendations** (`also-viewed` / `personal` /
+`trending`), **site search analytics** (top queries, zero-result
+queries, search-to-cart conversion) and **journey-drawer buffs**
+(rage-click + dead-click hot-spot lists, per-session `intent`
+labels).
+
 Maintained by Wayne Garrison.
 
 ## Buy
@@ -45,55 +53,111 @@ export const config: VendureConfig = {
 
             // -- Retention (opt-in) --
             retention: { days: 365, maxRows: 50_000_000 },
+
+            // -- Cart abandonment (opt-in, since 0.8.0) --
+            // Storefront must fire cart_snapshot events (see below).
+            abandonment: {
+                windowMinutes: 30,
+                slackMinValueMinor: 5000,
+                slackWebhookUrl: process.env.HULO_ABANDONMENT_SLACK_URL,
+                recoveryLinkSecret: process.env.HULO_ABANDONMENT_SECRET,
+                recoveryLinkTtlHours: 72,
+                storefrontBaseUrl: 'https://shop.example.com',
+            },
         }),
     ],
 };
 ```
 
 Add `VisitorAnalyticsPlugin.uiExtensions` to your `compileUiExtensions`
-config.
+config to pick up the Abandoned Carts + Analytics Insights admin pages.
+
+## Storefront helpers
+
+The plugin ships a **drop-in JS helper** at `/ees/hulo.js` — one script
+tag and every event API below is available on `window.hulo`. It handles
+batching, `sendBeacon` on unload, auto rage-click + dead-click
+detection, and an on-mount `pageview`. Bare minimum:
+
+```html
+<script src="https://shop.example.com/ees/hulo.js" defer></script>
+```
 
-## Storefront snippet
+For a first-party integration (recommended — one bundle instead of a
+second script tag), copy the equivalent typed helpers into your
+storefront. The [elite.charity Qwik storefront](https://elite-software.co.uk)
+uses this pattern. Every helper below is a thin wrapper around
+`POST /ees/track` with a specific `meta.eventType` — the plugin's
+server-side scanners look those event types up by name.
+
+| Helper | When to call | What it feeds |
+| --- | --- | --- |
+| `hulo.pageview()` | first mount + every route change | pageview funnel, exit-page report |
+| `hulo.productView(productId, variantId?)` | on the PDP | co-view aggregation, `also-viewed`, `trending`, `personal` recs |
+| `hulo.addToCart(variantId, qty, unitPriceMinor)` | on the "add" button | search-to-cart conversion |
+| `hulo.cartSnapshot({ currency, totalMinor, itemCount, items, email? })` | every cart change (add / remove / qty) | **cart abandonment detection** |
+| `hulo.search(query, resultsCount)` | on every executed search | top-queries, zero-result queries |
+| `hulo.checkoutCompleted(orderCode, totalMinor)` | on the thank-you page | closes any open `abandoned_cart` row for this session |
+| `hulo.rageClick(selector)` / `hulo.deadClick(selector)` | fire yourself if you have a better signal than the auto-detector | rage-click / dead-click hot-spot lists |
+| `hulo.restoreCart(token)` | on your `/cart/restore?t=...` route | rebuild a cart from a signed recovery link |
+
+Full payload shapes:
 
 ```ts
-// utils/visitor-tracking.ts
-const ENDPOINT = 'https://shop.example.com/ees/track';
-const CHANNEL_ID = 1;
-let queue: any[] = [];
-let flushTimer: any;
-
-export function recordPageview(url: string, title: string) {
-    queue.push({ type: 'pageview', url, title, clientTs: Date.now() });
-    scheduleFlush();
-}
-
-export function recordEvent(type: string, meta: any) {
-    queue.push({
-        type, url: location.pathname + location.search,
-        meta, clientTs: Date.now(),
-    });
-    scheduleFlush();
-}
-
-function scheduleFlush() {
-    clearTimeout(flushTimer);
-    flushTimer = setTimeout(flush, 1000);
-}
-function flush() {
-    if (!queue.length) return;
-    const body = JSON.stringify({ channelId: CHANNEL_ID, events: queue });
-    queue = [];
-    navigator.sendBeacon?.(ENDPOINT, body) ||
-        fetch(ENDPOINT, {
-            method: 'POST', body,
-            headers: { 'content-type': 'application/json' }, keepalive: true,
-        });
-}
+hulo.cartSnapshot({
+    currency: 'GBP',              // ISO-4217
+    totalMinor: 4995,             // in pence / cents
+    itemCount: 2,
+    items: [
+        { variantId: 42, name: 'Blue T-shirt (M)', qty: 1, unitPriceMinor: 1995, sku: 'BT-M' },
+        { variantId: 88, name: 'Wool socks',        qty: 1, unitPriceMinor: 3000 },
+    ],
+    email: 'buyer@example.com',   // optional — captured at checkout step 1
+    countryCode: 'GB',            // optional
+});
+
+hulo.productView(product.id, selectedVariant.id);
+hulo.search('rgb keyboard', 42);           // (query, resultsCount)
+hulo.checkoutCompleted('S2BZ54TEK', 12500); // (orderCode, totalMinor)
 ```
 
-Call `recordPageview()` on every route change. For custom events
-(add-to-cart, search, signup, …) call `recordEvent(type, meta)` at the
-appropriate point.
+### Cart-restore route
+
+The recovery link the admin mints (see below) lands on
+`https://shop.example.com/cart/restore?t=<token>`. Your storefront
+needs a route that:
+
+1. Reads `?t=` from the URL
+2. Calls `GET /ees/recover-cart?t=<token>` to fetch `{ items: [...] }`
+3. Re-adds each `{ variantId, qty }` via your Vendure order API (usually
+   `addItemToOrder(productVariantId, quantity)`)
+4. Navigates to `/cart` when done
+
+Guard against silently overwriting a live cart — if the visitor
+already has items, show a "you already have items in your cart"
+message and let them reconcile. See
+[elite.charity's `src/routes/cart/restore/index.tsx`](https://github.com/exceeded/elite-software-frontend/blob/main/src/routes/cart/restore/index.tsx)
+for a working reference implementation.
+
+### Legacy: hand-rolled tracker
+
+If you prefer to skip `/ees/hulo.js`, the raw POST shape is unchanged:
+
+```ts
+const body = JSON.stringify({
+    channelId: 1,
+    events: [{
+        type: 'event',
+        url: location.href,
+        meta: { eventType: 'product_view', productId: 42 },
+    }],
+});
+navigator.sendBeacon('/ees/track', body) ||
+    fetch('/ees/track', {
+        method: 'POST', body, credentials: 'include',
+        headers: { 'content-type': 'application/json' }, keepalive: true,
+    });
+```
 
 ## Feature tour
 
@@ -143,6 +207,89 @@ Stats at `GET /ees/goals/stats?days=30&channelId=1`.
   body field or an `ees_consent=1` cookie before ingest.
 - `dropBotEvents: false` (default) — flip on to skip bot UAs entirely.
 
+### Cart abandonment (since 0.8.0)
+
+Detects sessions that got as far as putting items in the cart but
+never fired `checkout_completed`. Turns them into `AbandonedCart` rows
+you can send a recovery email against.
+
+**How detection works.**
+The plugin runs a worker-only sweep every 5 minutes. It looks at every
+session that fired at least one `cart_snapshot` event, and:
+
+- If a `checkout_completed` landed later — do nothing (or if an
+  `abandoned_cart` row already exists, promote it to `converted`).
+- If the last `cart_snapshot` is older than `abandonment.windowMinutes`
+  (default 30) — open an `abandoned_cart` row, keyed on `sessionId`
+  (unique — you can't double-open the same session).
+- Otherwise leave the session alone. It may still convert.
+
+**Recovery link.**
+`POST /ees/abandoned-carts/:id/recovery-link` mints a signed opaque
+token and returns `{ ok: true, url: '<storefront>/cart/restore?t=...' }`.
+The token is time-bounded (`recoveryLinkTtlHours`, default 72) and
+non-reusable. The storefront exchanges it via
+`GET /ees/recover-cart?t=<token>` to get back the persisted item list.
+
+Set `abandonment.recoveryLinkSecret` in plugin options to enable this —
+without it, the endpoint returns `{ error: 'recovery-disabled-or-not-found' }`.
+
+**Slack notification.**
+`abandonment.slackWebhookUrl` + `abandonment.slackMinValueMinor`
+control an at-most-once Slack post per abandonment above the value
+threshold. Useful for sales teams that follow up on high-value drops
+manually.
+
+**Admin dashboard.**
+Under **Analytics → Abandoned carts**. Filters by status / min value /
+email / window. Actions per row: mint recovery link (copies URL to
+clipboard), mark recovered manually, dismiss. CSV export.
+
+### Product recommendations (since 0.8.0)
+
+A `ProductCoView` aggregate table holds a per-triple counter
+`(productIdA, productIdB, channelId) → viewsTogether`. Rebuilt every 6
+hours from the last 24h of `product_view` events, bounded to 20 events
+per session so runaway bot sessions can't skew the table.
+Denormalised — we store both `(A, B)` and `(B, A)` — so read-side
+lookups are one indexed scan.
+
+Three endpoints, all safe from the storefront (no PII):
+
+| Endpoint | Use |
+| --- | --- |
+| `GET /ees/recommendations/also-viewed?productId=42&limit=10` | product-page rail: "customers who viewed X also viewed…" |
+| `GET /ees/recommendations/personal?visitorId=abc&limit=10` | homepage / cart recs for a returning visitor. Uses their last 10 `product_view` events over 30 days, excludes the seeds so the same product never appears |
+| `GET /ees/recommendations/trending?hours=24&limit=10` | homepage rail: most-viewed products in the window. Reflects real intent (not search-console clicks) |
+
+`GET /ees/recommendations/aggregate-now` (SuperAdmin only) forces a
+sweep — useful after a big backfill or spike.
+
+### Site search analytics (since 0.8.0)
+
+Zero-schema-cost queries over the existing `visitor_event` table where
+the storefront has fired `hulo.search(query, resultsCount)` events.
+
+| Endpoint | Use |
+| --- | --- |
+| `GET /ees/search-analytics/top?days=7` | top queries by volume with average results count |
+| `GET /ees/search-analytics/no-results?days=7` | queries that returned zero hits — direct catalogue-gap intel |
+| `GET /ees/search-analytics/conversion?days=7` | of sessions that searched, what fraction went on to `add_to_cart` |
+
+### Journey drawer buffs (since 0.8.0)
+
+| Endpoint | Use |
+| --- | --- |
+| `GET /ees/journey/rage-clicks?days=7` | rage-click hot-spot list per URL. Pages where visitors are frustrated |
+| `GET /ees/journey/dead-clicks?days=7` | dead-click hot-spot list per URL. Elements that LOOK clickable but aren't |
+| `GET /ees/journey/session-summary?visitorId=abc` | per-session summary with a heuristic `intent` label (`purchase` / `abandon` / `frustrate` / `consider` / `browse` / `bounce`) |
+
+Rage-click auto-detector fires on ≥3 pointerdown events within 500ms
+and a 20-pixel radius. Dead-click auto-detector fires when a click
+lands on a non-interactive element and no navigation / significant
+scroll follows within 400ms. Both are conservative heuristics — the
+signal is direction-of-frustration, not a metric to optimise against.
+
 ### Live-now widget
 
 SSE stream at `GET /ees/visitors/live` pushes the active-visitor count
@@ -160,25 +307,52 @@ events with full enrichment.
 
 ## HTTP endpoints
 
-| Method | Path | Auth | Purpose |
-| --- | --- | --- | --- |
-| `POST` | `/ees/track` | public | ingest batch of events |
-| `GET` | `/ees/visitors/summary` | admin | top-line + daily series |
-| `GET` | `/ees/visitors/sources` | admin | top sources by visits |
-| `GET` | `/ees/visitors/top-pages` | admin | most-visited URLs |
-| `GET` | `/ees/visitors/funnel` | admin | configurable funnel |
-| `GET` | `/ees/visitors/exit-pages` | admin | top exit pages |
-| `GET` | `/ees/visitors/top-events` | admin | top custom events |
-| `GET` | `/ees/visitors/live` | admin | SSE live-now stream |
-| `GET` | `/ees/visitors/journey/:visitorId` | admin | per-visitor timeline |
-| `GET` | `/ees/visitors/recent` | admin | recent events |
-| `GET` | `/ees/visitors/export.csv` | admin | CSV export |
-| `GET` | `/ees/goals` | admin | list conversion goals |
-| `POST` | `/ees/goals` | admin | create a goal |
-| `PUT` | `/ees/goals/:id` | admin | update a goal |
-| `DELETE` | `/ees/goals/:id` | admin | delete a goal |
-| `GET` | `/ees/goals/stats` | admin | per-goal completion stats |
-| `GET` | `/ees/visitors/status` | admin | version + update status |
+**Public** (no auth — CORS-permissive for browser calls from any
+storefront origin):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/ees/track` | ingest a batch of visitor events |
+| `GET`  | `/ees/hulo.js` | typed storefront helper JS (since 0.8.1) |
+| `GET`  | `/ees/recover-cart?t=<token>` | resolve a recovery token → items |
+| `GET`  | `/ees/recommendations/also-viewed?productId=…` | co-view recs |
+| `GET`  | `/ees/recommendations/personal?visitorId=…` | personalised recs |
+| `GET`  | `/ees/recommendations/trending?hours=…` | most-viewed products |
+
+**Admin** (Vendure `ReadCustomer` unless noted; requires a
+Vendure admin session cookie):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET`  | `/ees/visitors/summary` | top-line + daily series |
+| `GET`  | `/ees/visitors/sources` | top sources by visits |
+| `GET`  | `/ees/visitors/top-pages` | most-visited URLs |
+| `GET`  | `/ees/visitors/funnel` | configurable funnel |
+| `GET`  | `/ees/visitors/exit-pages` | top exit pages |
+| `GET`  | `/ees/visitors/top-events` | top custom events |
+| `GET`  | `/ees/visitors/live` | SSE live-now stream |
+| `GET`  | `/ees/visitors/journey/:visitorId` | per-visitor timeline |
+| `GET`  | `/ees/visitors/recent` | recent events |
+| `GET`  | `/ees/visitors/export.csv` | CSV export |
+| `GET`  | `/ees/goals` | list conversion goals |
+| `POST` | `/ees/goals` | create a goal |
+| `PUT`  | `/ees/goals/:id` | update a goal |
+| `DELETE`| `/ees/goals/:id` | delete a goal |
+| `GET`  | `/ees/goals/stats` | per-goal completion stats |
+| `GET`  | `/ees/visitors/status` | version + update status |
+| `GET`  | `/ees/abandoned-carts` | paginated list w/ filters (0.8.0) |
+| `GET`  | `/ees/abandoned-carts/summary` | totals + recovery rate (0.8.0) |
+| `GET`  | `/ees/abandoned-carts/:id` | detail incl. parsed items (0.8.0) |
+| `POST` | `/ees/abandoned-carts/:id/recovery-link` | mint signed URL (0.8.0, `UpdateCustomer`) |
+| `POST` | `/ees/abandoned-carts/:id/status` | mark recovered/dismissed (0.8.0, `UpdateCustomer`) |
+| `GET`  | `/ees/abandoned-carts/export.csv` | CSV export (0.8.0) |
+| `GET`  | `/ees/recommendations/aggregate-now` | force co-view sweep (0.8.0, `SuperAdmin`) |
+| `GET`  | `/ees/search-analytics/top` | top queries (0.8.0) |
+| `GET`  | `/ees/search-analytics/no-results` | zero-result queries (0.8.0) |
+| `GET`  | `/ees/search-analytics/conversion` | search→cart rate (0.8.0) |
+| `GET`  | `/ees/journey/rage-clicks` | rage-click hot spots (0.8.0) |
+| `GET`  | `/ees/journey/dead-clicks` | dead-click hot spots (0.8.0) |
+| `GET`  | `/ees/journey/session-summary?visitorId=…` | per-session intent labels (0.8.0) |
 
 ## Documentation
 

package/dist/hulo-storefront.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The single-file storefront helper the plugin serves at /ees/hulo.js.
+ *
+ * Written as a string constant (not a bundled module) because:
+ *   - It's tiny (< 6kB minified) — a bundler adds more than the code
+ *   - It ships to the browser verbatim, no compile step
+ *   - Customers can inspect / audit it without a source map
+ *   - It has ZERO npm dependencies at runtime
+ *
+ * The controller wraps this in a small template that injects the
+ * public base URL and a default channel id, so a storefront paste
+ * of `<script src="https://backend/ees/hulo.js"></script>` Just Works
+ * with no config. Advanced users can call `hulo.configure({ ... })`
+ * to override.
+ */
+export declare const HULO_STOREFRONT_JS: (backendBaseUrl: string, defaultChannelId?: number) => string;
+//# sourceMappingURL=hulo-storefront.d.ts.map

package/dist/hulo-storefront.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hulo-storefront.d.ts","sourceRoot":"","sources":["../src/hulo-storefront.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,MAAM,EAAE,yBAAoB,KAAG,MA4QjF,CAAC"}

package/dist/hulo-storefront.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HULO_STOREFRONT_JS = void 0;
+/**
+ * The single-file storefront helper the plugin serves at /ees/hulo.js.
+ *
+ * Written as a string constant (not a bundled module) because:
+ *   - It's tiny (< 6kB minified) — a bundler adds more than the code
+ *   - It ships to the browser verbatim, no compile step
+ *   - Customers can inspect / audit it without a source map
+ *   - It has ZERO npm dependencies at runtime
+ *
+ * The controller wraps this in a small template that injects the
+ * public base URL and a default channel id, so a storefront paste
+ * of `<script src="https://backend/ees/hulo.js"></script>` Just Works
+ * with no config. Advanced users can call `hulo.configure({ ... })`
+ * to override.
+ */
+const HULO_STOREFRONT_JS = (backendBaseUrl, defaultChannelId = 1) => `
+// hulo storefront helper — @huloglobal/vendure-plugin-visitor-analytics
+// Public domain when served from your own store; do not resell.
+(function (global) {
+  var CONFIG = {
+    endpoint: ${JSON.stringify(backendBaseUrl.replace(/\/$/, '') + '/ees/track')},
+    recoverEndpoint: ${JSON.stringify(backendBaseUrl.replace(/\/$/, '') + '/ees/recover-cart')},
+    channelId: ${defaultChannelId},
+    debug: false,
+    autoRageClick: true,
+    autoDeadClick: true,
+    autoScroll: false,   // not implemented yet — flag reserved
+  };
+
+  // ── queue + batched send ─────────────────────────────────────────
+  // Every helper below pushes into a queue. Flush on requestIdleCallback
+  // or 2s max. Coalesces bursts of events into one HTTP roundtrip.
+  var QUEUE = [];
+  var FLUSH_TIMER = null;
+  function enqueue(event) {
+    event.url = event.url || location.href;
+    event.channelId = event.channelId || CONFIG.channelId;
+    QUEUE.push(event);
+    scheduleFlush();
+    if (CONFIG.debug) console.log('[hulo]', event);
+  }
+  function scheduleFlush() {
+    if (FLUSH_TIMER) return;
+    FLUSH_TIMER = setTimeout(flush, 1500);
+  }
+  function flush() {
+    FLUSH_TIMER = null;
+    if (!QUEUE.length) return;
+    var batch = QUEUE.splice(0, QUEUE.length);
+    var payload = JSON.stringify({ events: batch });
+    // Prefer sendBeacon on unload (survives page transitions) and
+    // fall back to fetch keepalive for normal calls.
+    try {
+      if (navigator.sendBeacon) {
+        var blob = new Blob([payload], { type: 'application/json' });
+        if (navigator.sendBeacon(CONFIG.endpoint, blob)) return;
+      }
+    } catch (_e) {}
+    try {
+      fetch(CONFIG.endpoint, {
+        method: 'POST', credentials: 'include', keepalive: true,
+        headers: { 'content-type': 'application/json' },
+        body: payload,
+      }).catch(function () { /* silent */ });
+    } catch (_e) {}
+  }
+  // Flush before the page dies.
+  window.addEventListener('pagehide', flush, { capture: true });
+  window.addEventListener('beforeunload', flush, { capture: true });
+
+  // ── public API ───────────────────────────────────────────────────
+  var hulo = {
+    configure: function (opts) { Object.assign(CONFIG, opts || {}); },
+    flush: flush,
+
+    /** Fire once per pageview. Optional — the ingest endpoint infers
+     *  pageviews from the referrer / URL, but calling this explicitly
+     *  captures the title too. */
+    pageview: function (extra) {
+      enqueue(Object.assign({ type: 'pageview', title: document.title }, extra || {}));
+    },
+
+    /** Product detail viewed. Store the product id you would use to
+     *  fetch the product server-side (Vendure product.id). If your
+     *  storefront uses variants primarily, pass variantId too. */
+    productView: function (productId, productVariantId) {
+      if (!productId && productId !== 0) return;
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify({
+          eventType: 'product_view',
+          productId: Number(productId),
+          productVariantId: productVariantId != null ? Number(productVariantId) : undefined,
+        }),
+      });
+    },
+
+    /** Item added to cart. Fire on every add — not just the first. */
+    addToCart: function (variantId, qty, unitPriceMinor) {
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify({
+          eventType: 'add_to_cart',
+          variantId: variantId != null ? Number(variantId) : undefined,
+          qty: qty != null ? Number(qty) : 1,
+          unitPriceMinor: unitPriceMinor != null ? Number(unitPriceMinor) : undefined,
+        }),
+      });
+    },
+
+    /** Cart snapshot — fire on every cart change (add / remove / qty).
+     *  The abandonment scanner reads only this event, so fire it
+     *  liberally. Payload shape:
+     *   { currency, totalMinor, itemCount, items: [{ variantId, name, qty, unitPriceMinor }], email? } */
+    cartSnapshot: function (cart) {
+      if (!cart || !cart.items || !cart.items.length) return;
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify({
+          eventType: 'cart_snapshot',
+          currency: (cart.currency || 'GBP').toUpperCase().slice(0, 3),
+          totalMinor: Number(cart.totalMinor || 0),
+          itemCount: Number(cart.itemCount || cart.items.length),
+          items: cart.items.map(function (i) {
+            return {
+              variantId: i.variantId != null ? Number(i.variantId) : undefined,
+              productId: i.productId != null ? Number(i.productId) : undefined,
+              name: i.name != null ? String(i.name).slice(0, 200) : undefined,
+              qty: Number(i.qty != null ? i.qty : (i.quantity != null ? i.quantity : 1)),
+              unitPriceMinor: Number(i.unitPriceMinor != null ? i.unitPriceMinor : (i.unitPrice != null ? i.unitPrice : 0)),
+              sku: i.sku != null ? String(i.sku).slice(0, 100) : undefined,
+            };
+          }).slice(0, 100),
+          email: cart.email || undefined,
+          countryCode: cart.countryCode || undefined,
+        }),
+      });
+    },
+
+    /** Storefront site search executed. Pass the raw query + the
+     *  resulting hit count so no-result queries can be aggregated. */
+    search: function (query, resultsCount) {
+      var q = String(query || '').trim();
+      if (!q) return;
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify({
+          eventType: 'search',
+          query: q.slice(0, 200),
+          resultsCount: Math.max(0, Number(resultsCount || 0)),
+        }),
+      });
+    },
+
+    /** Checkout finished — fires the counter that closes any open
+     *  abandoned-cart row for this session. Call from your thank-you
+     *  page. Optionally pass the order code + total. */
+    checkoutCompleted: function (orderCode, totalMinor) {
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify({
+          eventType: 'checkout_completed',
+          orderCode: orderCode ? String(orderCode).slice(0, 64) : undefined,
+          totalMinor: totalMinor != null ? Number(totalMinor) : undefined,
+        }),
+      });
+      flush(); // don't wait — the visitor may close the tab immediately
+    },
+
+    /** Rage-click event — fire it yourself if you have a better signal
+     *  than the built-in detector. */
+    rageClick: function (selector, extraMeta) {
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify(Object.assign({
+          eventType: 'rage_click',
+          selector: selector ? String(selector).slice(0, 200) : undefined,
+        }, extraMeta || {})),
+      });
+    },
+
+    /** Click landed on a non-interactive element. */
+    deadClick: function (selector, extraMeta) {
+      enqueue({
+        type: 'event',
+        meta: JSON.stringify(Object.assign({
+          eventType: 'dead_click',
+          selector: selector ? String(selector).slice(0, 200) : undefined,
+        }, extraMeta || {})),
+      });
+    },
+
+    /**
+     * Restore a cart from a signed recovery token. Fetches the items
+     * from the backend and returns them. Your storefront is responsible
+     * for calling its own Vendure order API to actually re-add them,
+     * because different storefronts frame that call differently.
+     */
+    restoreCart: function (token) {
+      var t = String(token || '').trim();
+      if (!t) return Promise.reject(new Error('missing-token'));
+      return fetch(CONFIG.recoverEndpoint + '?t=' + encodeURIComponent(t), {
+        credentials: 'include',
+      }).then(function (r) { return r.json(); });
+    },
+  };
+
+  // ── auto rage-click detector ─────────────────────────────────────
+  // Any pointerdown ≥ 3 within 500ms in a 20x20px zone counts.
+  if (CONFIG.autoRageClick) {
+    var recent = [];
+    document.addEventListener('pointerdown', function (e) {
+      var now = Date.now();
+      recent = recent.filter(function (r) { return now - r.t < 500; });
+      recent.push({ t: now, x: e.clientX, y: e.clientY, target: e.target });
+      var close = recent.filter(function (r) {
+        return Math.abs(r.x - e.clientX) < 20 && Math.abs(r.y - e.clientY) < 20;
+      });
+      if (close.length >= 3) {
+        hulo.rageClick(cssPathOf(e.target));
+        recent = []; // reset so we don't fire again on the 4th, 5th, etc.
+      }
+    }, { capture: true, passive: true });
+  }
+
+  // ── auto dead-click detector ─────────────────────────────────────
+  // A click that lands on an element with no href / not a button /
+  // not a form control and doesn't produce a navigation within 400ms.
+  if (CONFIG.autoDeadClick) {
+    document.addEventListener('click', function (e) {
+      var target = e.target;
+      if (!target || target.nodeType !== 1) return;
+      if (isInteractive(target)) return;
+      var beforeUrl = location.href;
+      var beforeScroll = window.scrollY;
+      setTimeout(function () {
+        if (location.href !== beforeUrl) return;
+        if (Math.abs(window.scrollY - beforeScroll) > 50) return;
+        // Was there an ancestor with a click handler? Best-effort:
+        // walk up and check for onclick, role='button', tabindex.
+        var node = target;
+        for (var i = 0; i < 4 && node; i++) {
+          if (isInteractive(node) || node.onclick) return;
+          node = node.parentElement;
+        }
+        hulo.deadClick(cssPathOf(target));
+      }, 400);
+    }, { capture: true, passive: true });
+  }
+
+  function isInteractive(el) {
+    if (!el || !el.tagName) return false;
+    var tag = el.tagName.toLowerCase();
+    if (tag === 'a' || tag === 'button' || tag === 'input' || tag === 'select'
+        || tag === 'textarea' || tag === 'label' || tag === 'summary'
+        || tag === 'details') return true;
+    if (el.getAttribute && (el.getAttribute('role') === 'button'
+        || el.getAttribute('role') === 'link'
+        || el.hasAttribute('tabindex'))) return true;
+    return false;
+  }
+
+  function cssPathOf(el) {
+    if (!el || el.nodeType !== 1) return '';
+    var parts = [];
+    while (el && el.nodeType === 1 && parts.length < 5) {
+      var p = el.tagName.toLowerCase();
+      if (el.id) { p += '#' + el.id; parts.unshift(p); break; }
+      if (el.className && typeof el.className === 'string') {
+        var cls = el.className.trim().split(/\\s+/).slice(0, 2).join('.');
+        if (cls) p += '.' + cls;
+      }
+      parts.unshift(p);
+      el = el.parentElement;
+    }
+    return parts.join(' > ');
+  }
+
+  global.hulo = hulo;
+  // Auto pageview on load — most callers want it.
+  if (document.readyState === 'complete') hulo.pageview();
+  else window.addEventListener('load', function () { hulo.pageview(); });
+})(window);
+`;
+exports.HULO_STOREFRONT_JS = HULO_STOREFRONT_JS;
+//# sourceMappingURL=hulo-storefront.js.map

package/dist/hulo-storefront.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hulo-storefront.js","sourceRoot":"","sources":["../src/hulo-storefront.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACI,MAAM,kBAAkB,GAAG,CAAC,cAAsB,EAAE,gBAAgB,GAAG,CAAC,EAAU,EAAE,CAAC;;;;;gBAK5E,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC;uBACzD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,mBAAmB,CAAC;iBAC7E,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqQhC,CAAC;AA5QW,QAAA,kBAAkB,sBA4Q7B"}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,IAAI,EAAiB,MAAM,eAAe,CAAC;AACxE,OAAO,EAAmC,aAAa,EAAE,gBAAgB,EAAqB,aAAa,EAA4C,MAAM,iCAAiC,CAAC;AAM/L,OAAO,EAAwB,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAgBpF,MAAM,WAAW,6BAA6B;IAC1C,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB;;;gDAG4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB;6EACyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;yEAEqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;qEAEiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;6CAEyC;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;IAGxB,mDAAmD;IACnD,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;yEAEqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;2EAEuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAG9B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAG7B;;4DAEwD;IACxD,WAAW,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAgBD,QAAA,MAAM,eAAe,EAAE,6BAMtB,CAAC;AAGF,wBAAgB,UAAU,IAAI,OAAO,eAAe,GAAG,6BAA6B,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,qBAyBa,sBAAsB;IAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAkC;IAC3D,OAAO,CAAC,MAAM,CAAC,aAAa,CAA8B;IAC1D,OAAO,CAAC,MAAM,CAAC,SAAS,CAA0B;IAClD,OAAO,CAAC,MAAM,CAAC,aAAa,CAA8B;IAE1D,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAC/C,MAAM,CAAC,iBAAiB,IAAI,MAAM;IAClC,MAAM,CAAC,cAAc,IAAI,MAAM;IAC/B,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAE/C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAAC,sBAAsB,CAAC;IAoDjF,MAAM,CAAC,YAAY;;;;;;;;MAUjB;CACL"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,IAAI,EAAiB,MAAM,eAAe,CAAC;AACxE,OAAO,EAAmC,aAAa,EAAE,gBAAgB,EAAqB,aAAa,EAA4C,MAAM,iCAAiC,CAAC;AAM/L,OAAO,EAAwB,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAiBpF,MAAM,WAAW,6BAA6B;IAC1C,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB;;;gDAG4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB;6EACyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;yEAEqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;qEAEiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;6CAEyC;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;IAGxB,mDAAmD;IACnD,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;yEAEqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;2EAEuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAG9B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAG7B;;4DAEwD;IACxD,WAAW,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAgBD,QAAA,MAAM,eAAe,EAAE,6BAMtB,CAAC;AAGF,wBAAgB,UAAU,IAAI,OAAO,eAAe,GAAG,6BAA6B,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,qBA0Ba,sBAAsB;IAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAkC;IAC3D,OAAO,CAAC,MAAM,CAAC,aAAa,CAA8B;IAC1D,OAAO,CAAC,MAAM,CAAC,SAAS,CAA0B;IAClD,OAAO,CAAC,MAAM,CAAC,aAAa,CAA8B;IAE1D,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAC/C,MAAM,CAAC,iBAAiB,IAAI,MAAM;IAClC,MAAM,CAAC,cAAc,IAAI,MAAM;IAC/B,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAE/C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAAC,sBAAsB,CAAC;IAoDjF,MAAM,CAAC,YAAY;;;;;;;;MAUjB;CACL"}

package/dist/plugin.js

@@ -27,6 +27,7 @@ const abandoned_cart_controller_1 = require("./abandoned-cart.controller");
 const recommendations_controller_1 = require("./recommendations.controller");
 const search_analytics_controller_1 = require("./search-analytics.controller");
 const journey_buffs_controller_1 = require("./journey-buffs.controller");
+const storefront_helper_controller_1 = require("./storefront-helper.controller");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const PKG_VERSION = require('../package.json').version;
 const PKG_NAME = '@huloglobal/vendure-plugin-visitor-analytics';
@@ -148,6 +149,7 @@ exports.VisitorAnalyticsPlugin = VisitorAnalyticsPlugin = VisitorAnalyticsPlugin
             recommendations_controller_1.RecommendationsController,
             search_analytics_controller_1.SearchAnalyticsController,
             journey_buffs_controller_1.JourneyBuffsController,
+            storefront_helper_controller_1.StorefrontHelperController,
         ],
         entities: [visitor_event_entity_1.VisitorEvent, conversion_goal_entity_1.ConversionGoal, abandoned_cart_entity_1.AbandonedCart, product_co_view_entity_1.ProductCoView],
         compatibility: '^3.0.0',

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":";;;;;;;;;;AA+FA,gCAEC;AAjGD,wCAAwE;AACxE,yEAA+L;AAC/L,qEAA0D;AAC1D,iEAAsD;AACtD,mEAAwD;AACxD,qEAAyD;AACzD,yEAAoE;AACpE,qEAAoF;AACpF,uEAAmE;AACnE,yEAAoE;AACpE,mEAA8D;AAC9D,qEAAgE;AAChE,2CAA4F;AAC5F,+EAA0E;AAC1E,2EAAsE;AACtE,6EAAyE;AACzE,+EAA0E;AAC1E,yEAAoE;AAEpE,8DAA8D;AAC9D,MAAM,WAAW,GAAW,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC;AAC/D,MAAM,QAAQ,GAAG,8CAA8C,CAAC;AAmDhE,MAAM,eAAe,GAAG;;;;;;;;yBAQC,CAAC;AAE1B,MAAM,SAAS,GAAG,kCAAkC,CAAC;AACrD,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B;OACvD,4CAA4C,CAAC;AAEpD,MAAM,eAAe,GAAkC;IACnD,aAAa,EAAE,uBAAuB;IACtC,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;CACvB,CAAC;AAEF,IAAI,aAAa,GAAkC,eAAsB,CAAC;AAC1E,SAAgB,UAAU;IACtB,OAAO,EAAE,GAAG,eAAe,EAAE,GAAG,aAAa,EAAS,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;GAWG;AA0BI,IAAM,sBAAsB,8BAA5B,MAAM,sBAAsB;IAM/B,MAAM,CAAC,gBAAgB,KAA2B,OAAO,wBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC;IAChG,MAAM,CAAC,iBAAiB,KAAa,OAAO,WAAW,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,cAAc,KAAa,OAAO,QAAQ,CAAC,CAAC,CAAC;IACpD,MAAM,CAAC,gBAAgB,KAA2B,OAAO,wBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC;IAEhG,MAAM,CAAC,IAAI,CAAC,OAAsC;QAC9C,aAAa,GAAG,OAAO,CAAC;QAExB,yDAAyD;QACzD,iDAAiD;QACjD,IAAA,+CAAyB,EAAC;YACtB,iBAAiB,EAAE,QAAQ;YAC3B,oBAAoB,EAAE,WAAW;YACjC,cAAc,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;SACjD,CAAC,CAAC;QAEH,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;QACD,IAAI,CAAC,wBAAsB,CAAC,aAAa,EAAE,CAAC;YACxC,wBAAsB,CAAC,aAAa,GAAG,IAAI,mCAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YAChF,wBAAsB,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QACjD,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;QACH,wBAAsB,CAAC,aAAa,GAAG,MAAM,CAAC;QAE9C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAChB,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACR,kDAAkD,MAAM,CAAC,OAAO,EAAE;gBAClE,2KAA2K,SAAS,EAAE,CACzL,CAAC;QACN,CAAC;QAED,IAAI,CAAC,wBAAsB,CAAC,SAAS,EAAE,CAAC;YACpC,wBAAsB,CAAC,SAAS,GAAG,IAAI,+BAAS,CAAC;gBAC7C,WAAW,EAAE,QAAQ;gBACrB,cAAc,EAAE,WAAW;gBAC3B,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,oBAAoB,EAAE,IAAA,0CAAoB,EAAC,eAAe,CAAC;aAC9D,CAAC,CAAC;YACH,wBAAsB,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC7C,CAAC;QAED,OAAO,wBAAsB,CAAC;IAClC,CAAC;;AA7DQ,wDAAsB;AAChB,iCAAU,GAA6B,IAAI,AAAjC,CAAkC;AAC5C,oCAAa,GAAyB,IAAI,AAA7B,CAA8B;AAC3C,gCAAS,GAAqB,IAAI,AAAzB,CAA0B;AACnC,oCAAa,GAAyB,IAAI,AAA7B,CAA8B;AA2DnD,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;iCAzEO,sBAAsB;IAzBlC,IAAA,oBAAa,EAAC;QACX,OAAO,EAAE,CAAC,yBAAkB,CAAC;QAC7B,SAAS,EAAE;YACP,iDAAsB;YACtB,yCAA6B;YAC7B,6CAAoB;YACpB,gDAAsB;YACtB,iDAAsB;YACtB,2CAAmB;YACnB,6CAAoB;SACvB;QACD,WAAW,EAAE;YACT,uDAAyB;YACzB,mDAAuB;YACvB,sDAAyB;YACzB,uDAAyB;YACzB,iDAAsB;SACzB;QACD,QAAQ,EAAE,CAAC,mCAAY,EAAE,uCAAc,EAAE,qCAAa,EAAE,sCAAa,CAAC;QACtE,aAAa,EAAE,QAAQ;QACvB,kBAAkB,EAAE;YAChB,MAAM,EAAE,0CAA8B;YACtC,SAAS,EAAE,CAAC,yCAA6B,CAAC;SAC7C;KACJ,CAAC;GACW,sBAAsB,CA0ElC"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/storefront-helper.controller.d.ts

@@ -0,0 +1,16 @@
+import { Request, Response } from 'express';
+/**
+ * Serves the storefront helper at `/ees/hulo.js`. Storefronts embed
+ * one script tag and every helper (cartSnapshot, productView, search,
+ * rageClick+deadClick auto-detectors, checkoutCompleted, restoreCart)
+ * is available on `window.hulo`.
+ *
+ * Cache: 10-minute browser TTL + 24-hour SWR. The file's content is
+ * a function of plugin options; storefronts don't need to bust the
+ * cache to see config changes because the URL stays stable and 10
+ * minutes is short enough that dashboard tweaks propagate promptly.
+ */
+export declare class StorefrontHelperController {
+    hulo(req: Request, res: Response): void;
+}
+//# sourceMappingURL=storefront-helper.controller.d.ts.map

package/dist/storefront-helper.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefront-helper.controller.d.ts","sourceRoot":"","sources":["../src/storefront-helper.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;;;;;;;GAUG;AACH,qBACa,0BAA0B;IAEnC,IAAI,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ;CAYjD"}

package/dist/storefront-helper.controller.js

@@ -0,0 +1,56 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorefrontHelperController = void 0;
+const common_1 = require("@nestjs/common");
+const hulo_storefront_1 = require("./hulo-storefront");
+const plugin_1 = require("./plugin");
+/**
+ * Serves the storefront helper at `/ees/hulo.js`. Storefronts embed
+ * one script tag and every helper (cartSnapshot, productView, search,
+ * rageClick+deadClick auto-detectors, checkoutCompleted, restoreCart)
+ * is available on `window.hulo`.
+ *
+ * Cache: 10-minute browser TTL + 24-hour SWR. The file's content is
+ * a function of plugin options; storefronts don't need to bust the
+ * cache to see config changes because the URL stays stable and 10
+ * minutes is short enough that dashboard tweaks propagate promptly.
+ */
+let StorefrontHelperController = class StorefrontHelperController {
+    hulo(req, res) {
+        const opts = (0, plugin_1.getOptions)();
+        const base = opts.publicBaseUrl
+            || `https://${req.headers.host || 'localhost'}`;
+        const js = (0, hulo_storefront_1.HULO_STOREFRONT_JS)(base, 1);
+        res.setHeader('content-type', 'application/javascript; charset=utf-8');
+        res.setHeader('cache-control', 'public, max-age=600, stale-while-revalidate=86400');
+        // Storefront lives on a different origin from the backend —
+        // static-JS CORS is safe (no credentials) but be explicit.
+        res.setHeader('access-control-allow-origin', '*');
+        res.send(js);
+    }
+};
+exports.StorefrontHelperController = StorefrontHelperController;
+__decorate([
+    (0, common_1.Get)('hulo.js'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], StorefrontHelperController.prototype, "hulo", null);
+exports.StorefrontHelperController = StorefrontHelperController = __decorate([
+    (0, common_1.Controller)('ees')
+], StorefrontHelperController);
+//# sourceMappingURL=storefront-helper.controller.js.map

package/dist/storefront-helper.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefront-helper.controller.js","sourceRoot":"","sources":["../src/storefront-helper.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA2D;AAE3D,uDAAuD;AACvD,qCAAsC;AAEtC;;;;;;;;;;GAUG;AAEI,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IAEnC,IAAI,CAAQ,GAAY,EAAS,GAAa;QAC1C,MAAM,IAAI,GAAG,IAAA,mBAAU,GAAE,CAAC;QAC1B,MAAM,IAAI,GAAI,IAAY,CAAC,aAAa;eACjC,WAAW,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;QACpD,MAAM,EAAE,GAAG,IAAA,oCAAkB,EAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvC,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,uCAAuC,CAAC,CAAC;QACvE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,mDAAmD,CAAC,CAAC;QACpF,4DAA4D;QAC5D,2DAA2D;QAC3D,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;CACJ,CAAA;AAdY,gEAA0B;AAEnC;IADC,IAAA,YAAG,EAAC,SAAS,CAAC;IACT,WAAA,IAAA,YAAG,GAAE,CAAA;IAAgB,WAAA,IAAA,YAAG,GAAE,CAAA;;;;sDAW/B;qCAbQ,0BAA0B;IADtC,IAAA,mBAAU,EAAC,KAAK,CAAC;GACL,0BAA0B,CActC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huloglobal/vendure-plugin-visitor-analytics",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Full-funnel visitor analytics for Vendure storefronts \u2014 pageviews, time-on-page, session journey, exit pages, funnel drop-off, and per-visitor profile drawer with parsed user-agent + MaxMind GeoLite2 enrichment. Auto-issues visitor + session cookies on first request; logs guest and signed-in events against the same visitor id so the journey survives login.",
   "license": "AGPL-3.0-or-later",
   "author": "Wayne Garrison <wayne@garrison.me.uk>",