Abandoned-cart reminder e-mails restyled to the shared HULO e-mail design: a 600px white card with the merchant's logo (or shop name) and a 3px accent bar, the basket with line prices and total in an info box, a Return to your basket button, a "Kind regards" sign-off with the shop name and support address, and a footer strip with the merchant's legal text and the unsubscribe link. Inline styles and tables only; the plain-text part carries the same content. Lists at most eight items and says how many more.
New optional design settings (Visitors → Settings → Carts): accent colour (default #155dfc), logo URL, support e-mail and footer text, with install-wide defaults from the new plugin option email: { accentColor, logoUrl, logoWidth, supportEmail, footerText }. Existing installs keep their settings; the new fields start empty.
Preview the reminder e-mail (GET /ees/settings/reminder-preview, ReadSettings): the e-mail rendered with the saved settings and a sample basket, served with a no-script Content-Security-Policy.
The unsubscribe page uses the same colours and type.
The unsubscribe confirm button showed raw JSON. The page's form POST now gets an HTML "You have been unsubscribed" page; RFC 8058 one-click POSTs from mail providers still get JSON.
Channel-scoped administrators could read and redirect the store-wide weekly report: change its recipient, send it to any address, preview it. Those routes now need an administrator of the default channel (or a SuperAdmin); the dashboard widget shows channel-scoped administrators no store-wide figures.
The public recommendation endpoints had no rate limit (also-viewed, personal, trending): 120 requests a minute per client IP across the three, then 429. visitorId is capped at 64 characters.
A shop name containing $& or $' was mangled in the reminder subject (string replacement patterns).
v0.20.0
New
Parity with HULO Visitor Analytics for WordPress.
Changed (tiers)
No daily cap on the free tier. Unlicensed installs used to stop recording after 100 events a UTC day; every event is now recorded. GET /ees/licence/status keeps capReached (always false).
The weekly report and the set-up checklist are licensed (licence or evaluation). On the free tier the scheduler sends nothing, Send me a test answers 402 and GET /ees/setup returns no items. Settings are kept; the report resumes when a licence is active.
PREMIUM_FEATURES lists what a licence adds now (no event cap; adds reminders, cart capture, goal types, weekly report and checklist).
Added — free
Cookieless mode (Visitors → Settings, off by default): no cookies or device storage; a daily-salted HMAC of address + browser + site identifies a visit, the salt is replaced (and the old one deleted) every UTC day. hulo.js stops using localStorage and sends no credentials in this mode.
Exclude staff (on by default): signed-in administrators record nothing. Excluded addresses (IPs and CIDR ranges, v4 and v6). ?hulo_exclude=1 excludes one browser in hulo.js.
Private URL parameter stripping (on by default): tokens, keys, passwords, e-mail addresses and mailing subscriber ids are removed from stored URLs and referrers; extra names configurable.
Reports: GET /ees/visitors/landing-pages (entry pages with sessions, bounce rate, conversions); sources now carry bounced, bounceRate, conversions, conversionRate (a conversion is a goal completion or a checkout_completed event in the session); breakdown adds oses.
Personal-data export and erase: GET /ees/privacy/export, POST /ees/privacy/erase, and a Personal data card in Settings.
Admin UI tabs: Reports (sources, landing and exit pages, events, audience, site search, rage and dead clicks — reports that were REST-only), Goals, Abandoned carts and Settings.
Added — licensed
Goal types: form goals (matched on form_submit events; hulo.js auto-tracks form submissions by form id / name, never field values) and payment goals (Vendure PaymentStateTransitionEvent → Settled, once per payment, worth what was paid when the goal has no fixed value). Per-goal completions UI. GET /ees/goals/suggestions.
Verified e-mail capture: carts record whether their address is verified (emailVerified, emailSource).
Server-side cart capture from Vendure order events (off by default).
Abandoned-cart reminder e-mails (off by default): verified addresses only, opt-outs honoured, at most two per cart (compare-and-set), one sequence per address per week, per-run cap, unsubscribe link and one-click List-Unsubscribe headers.
Fixed
hulo.js sends meta JSON-encoded; it was stored encoded twice, so the abandonment scanner never saw hulo.js cart snapshots or checkouts. String meta is now parsed and stored once.
Traffic sources are grouped by page views (an event without UTM no longer opens a (direct) row for a session that came from a campaign).
Goal create/update/delete check the admin's channel.
Docs
README: tiers table (no "403 on free"; licensed endpoints answer 402), Settings, goal types, cart reminders; the Settings tab now exists.
Upgrade notes
Columns added on boot (and by TypeORM synchronise): conversion_goal.type (default page) and target; abandoned_cart.emailVerified, emailSource, emailsSent, lastEmailAt. New tables va_goal_payment, va_order_cart. Settings live in hulo_plugin_prefs. No existing data changes.
v0.19.6
New
Security
Admin REST routes refuse a Shop-API session on Vendure 3.8+. Vendure 3.8 binds every session to the API it was created on and refuses Shop-API sessions on the Admin API (GHSA-5fpx-9m35-w745), but it does not check REST routes added by plugins: an administrator's storefront session still carried their admin permissions into the Visitor Analytics admin REST routes (visitors, exports, abandoned carts, journey, search analytics, recommendations). Those routes now also require a session created on the Admin API (isAdminApiSession from the licence SDK 0.15.6, the same rule as Vendure's own AuthGuard). The admin UI is unaffected; administrators logged in before the 3.8 upgrade log in again once, as Vendure already requires. No change on Vendure 3.5 to 3.7.
Compatibility
Tested with Vendure 3.8.2 (NestJS 12, @nestjs/graphql 14, Apollo Server 5), as well as 3.5 to 3.7. The peer range stays @vendure/core >=3.5.0 <4.0.0; nothing here needs 3.8.
Requires @huloglobal/vendure-licence-sdk ^0.15.6.
v0.19.5
New
Package metadata
The license field is now AGPL-3.0-only, matching LICENSE, which grants the GNU Affero General Public License version 3 (it said AGPL-3.0-or-later). Published npm builds remain under the separate commercial licence described in LICENSE. No code changes.
v0.19.4
New
Security
CSV exports are no longer kept by CDNs.GET /ees/visitors/export.csv and GET /ees/abandoned-carts/export.csv now send Cache-Control: private, no-store. They used to send no caching header, so a CDN that caches by file extension (Cloudflare caches .csv by default, even for a signed-in request) could store one admin's export, with visitor journeys or shoppers' e-mail addresses, and serve it to anyone who asked for the same URL. The refusals the handlers send themselves carry the header too: signed out, missing permission or no licence on the visitor export, and a channel the admin cannot read on the cart export. The cart export's 403 for a caller who is signed out or lacks ReadCustomer has no Cache-Control, because Vendure's permission check sends it before the handler runs; it carries no data. If your admin API is behind a CDN, purge any /ees/ CSV files it may already hold.
Fixed
PostgreSQL. The plugin now requires licence SDK ^0.15.4. With 0.15.3 or older on Postgres, removing an abandoned-cart opt-out always reported success, even when there was no such opt-out. The abandonment scan also logged 2 converted carts whatever it marked, and the first weekly report was skipped (it started a week late). MySQL and MariaDB were not affected.
PostgreSQL: a licence key activated in the admin is now stored. The plugin's licence store left out the conflict column that the Postgres upsert needs, so saving a key failed. Pasting a key into the admin applied it, answered with a server error and did not store it, so the plugin was unlicensed again after a restart. A key bought from the admin, which installs itself, was not stored either. The co-view sweep stores the end of its last window in the same table, and that save failed too, so GET /ees/recommendations/aggregate-now counted again the co-views that the 6-hourly sweep had already counted. MySQL and MariaDB were not affected.
Package metadata
homepage is now the product page, https://huloglobal.com/vendure-plugins/visitor-analytics/, instead of the GitHub repository.
A shorter description that npm shows in full (npm cuts descriptions at 255 characters), and keywords for the abandoned-cart, UTM and recommendation features.
The npm package no longer includes the plugin's compiled unit tests.
v0.19.3
New
Documentation
The README now shows the plugin logo, hosted on huloglobal.com so it displays on npm and GitHub alike, linking to the product page. No code changes.
v0.19.2
New
Security
Admin reads are scoped per channel. Every admin endpoint (REST /ees/visitors/*, /ees/goals* reads, /ees/journey/*, /ees/search-analytics/*, /ees/abandoned-carts list / summary / export / detail / recovery-link / status, and the huloVisitor* Admin API queries) used to take the channel from the query string, or read every channel when none was given. An administrator whose roles cover only channel B could therefore read channel A's visitors, IPs, journeys and abandoned carts (e-mail, name, phone) and mint recovery links for them. Now a user with the permission on the default channel (or SuperAdmin) still sees every channel as before; anyone else is limited to the channels their roles grant it on, gets their active channel when they name none, and gets 403 / FORBIDDEN for any other channel.
x-forwarded-for is read from the right. With trustedIpHeaders: ['x-forwarded-for'] the visitor IP (stored IP, rate-limit key) was the left-most entry, which is whatever the client sent. It is now the right-most entry, the hop the host's proxy appended.
Edge geo headers need a trusted edge.CF-IPCountry, X-Akamai-Edgescape, X-Country-Code and cf-region-code were believed from any client, so a visitor could choose its stored country. They are now used only when the immediate peer is a proxy Vendure trusts (apiOptions.trustProxy) or trustedIpHeaders is configured; otherwise the GeoLite2 lookup runs.
Fixed
The public recover-cart, recover-cart/resume, recover-cart/converted and opt-out endpoints keyed their rate limit on req.ip while ingest used trustedIpHeaders; on a host that relies on trustedIpHeaders every visitor behind the proxy shared one budget (30 restores a minute for the whole shop). They now use the same client IP as ingest.
README: the email on abandoned-cart rows is unverified beacon input — hosts must not send reminders to it as-is.
v0.19.1
New
Changed
Every install now gets a 14-day evaluation with all features on and no card (granted by the HULO licence server). The licence banner's buttons read Subscribe: during the evaluation the first charge falls on the day it ends, so there is no second free trial.
v0.19.0
Retention pass: a weekly report, a setup checklist, a dashboard widget and a licence banner that says what the plugin has done. No schema changes to the plugin's own tables; one shared hulo_plugin_prefs table (created on first boot by the licence SDK) holds the report settings.
Added
Weekly report. Every Monday at 08:00 server-local time the worker emails the previous week's unique visitors, sessions, page views, abandoned carts detected, carts recovered and their value, and conversion goals completed — each against the week before — plus next steps from the setup checklist and the licence notice when a trial or key is ending. Weekly report card on the admin page (enabled toggle, recipient with the resolved default as placeholder, last/next send, Send me a test, Preview); GET|POST /ees/digest/settings, POST /ees/digest/send-test, GET /ees/digest/preview. Sent through the host's SMTP_* environment via nodemailer, now an optional peer dependency. Default recipient: the licence holder, else the trial lead.
Setup checklist at the top of the admin page (GET /ees/setup): tracking events arriving in the last 7 days, public base URL, storefront URL for recovery links, a conversion goal, Slack alerts or recovery links. Hidden once complete or dismissed; shown again if a ticked item regresses. The undone items are the report's "next steps".
Dashboard widget (Dashboard → Add widget → Visitor Analytics): unique visitors, page views and carts recovered for the last 7 days, the licence notice, and a link to the page (GET /ees/widget).
Admin navigation:Marketing → Visitor Analytics (shared UI module VisitorsNavModule, included in uiExtensions).
Licence banner: lifecycle notice (trial ending, key expiring, evaluation ended) as an amber strip; the premium feature list and a "So far: …" line of real 30-day figures on the trial and free banners; Email me before it ends on the trial banner (POST /ees/eval/remind-me, which was missing); "Renews automatically — current key valid until …" on subscriptions.
Value metrics:Recovered revenue and Carts recovered / abandoned tiles on the KPI row from GET /ees/abandoned-carts/summary.
Free-tier cap:GET /ees/licence/status reports capReached (today's 100-event budget spent) and the page shows an amber notice; the Live now tile shows an unlock chip on the free tier instead of a silent "reconnecting".
Usage counters (visitorsTracked, sessions, pageViews, cartsAbandoned, cartsRecovered, recoveredValuePence, goalsCompleted, last 30 days, numbers only) now travel with both the evaluation ping and the daily heartbeat, so licensed installs keep reporting after purchase.
Any 402 / licence-coded error on the page renders "<what you tried> needs a licence — start the free trial or activate a key at the top of this page".
Changed
@huloglobal/vendure-licence-sdk^0.15.1.
Fixed
The daily heartbeat reported jti: unlicensed forever once a key was activated from the admin page or installed by the buy-from-admin claim, so the licence server dropped those installs' usage figures. It now reads the key currently in force on every ping.
v0.18.5
Fixed
MySQL/MariaDB regression in 0.18.4. The HAVING rewrite made trending, topQueries and zeroResultQueries fail on MySQL/MariaDB ("Unknown column 'meta' in 'HAVING'": MySQL resolves only the output alias there, Postgres only the expression). The filters now sit in WHERE as the expression, which both accept. 0.18.4 is deprecated on npm.
The corpus test now also runs every statement through a server-side PREPARE on MySQL/MariaDB (HULO_MYSQL_URL), so a fix for one dialect can no longer break the other unnoticed.
v0.18.4
Optimisation and Postgres pass — no new features, no new tables, no new indexes (nothing to migrate).
Fixed
Postgres. Every camelCase column on the entity tables (visitor_event, conversion_goal, abandoned_cart, product_co_view) and on the Vendure tables the plugin reads (customer, order, order_channels_channel, product, product_variant, product_translation, product_variant_translation) is quoted; NOW() - INTERVAL … became DATE_SUB(…); aliases are no longer used in HAVING; the personal-recommendations seed query no longer combines DISTINCT with an ORDER BY on an unselected column; the CAST(… AS UNSIGNED) on product ids / result counts is guarded by a digits check (Postgres raises where MySQL returns 0); the co-view upsert quotes its ON CONFLICT target; SUM(boolean) in the session summary became MAX(CASE …); boolean columns are compared with TRUE/FALSE; the abandoned-cart controller's queries go through the dialect adapter; and the boot-time abandoned_cart ALTERs quote the column name (an install without the migration got a lowercase duplicate) behind an information-schema check (MySQL 8 has no ADD COLUMN IF NOT EXISTS). A corpus test (tests/pg-corpus.test.ts, skipped unless HULO_PG_URL is set) runs all 98 statements against PostgreSQL 17 with TypeORM-quoted stand-ins for the entity and Vendure tables.
POST /ees/track and customerId. The customer is resolved from the Vendure session (activeUserId → customer.userId, cached 10 min); the body value is ignored, so an anonymous beacon can no longer file events under an arbitrary customer id. A storefront that never sent the session (the bundled tracker does not) sees no change: those events were already unlinked.
CORS.OPTIONS /ees/track answers 204 with the same headers as the POST (a JSON fetch from another origin sends a preflight). A disallowed origin gets no Access-Control-Allow-Origin header at all — the previous null is itself a valid origin value.
Changed
Co-view aggregation. Pairs are accumulated in memory per (A, B, channel) and written as multi-row upserts in chunks of 500 (one statement per ordered pair before: a 20-product session cost 380 round trips). The end of the last aggregated window is persisted, so overlapping runs — aggregate-now after the 6-hourly sweep — count nothing twice; aggregate-now?force=1 rebuilds regardless.
Live feed. One query in flight per stream (a slow tick used to queue behind itself every 5 s) and a : keepalive comment every 15 s.
CSV exports. Visitors and abandoned carts stream in id-ordered chunks of 5 000 with back-pressure instead of materialising up to 200 000 / 50 000 rows first. Rows are in id (chronological) order.
Housekeeping. Monthly, on the worker: abandoned_cart rows in status expired / converted / dismissed older than 180 days and product_co_view pairs not refreshed in 90 days are deleted in batches of 5 000.
v0.18.3
Changed
normaliseUrl and boundedMeta moved to src/ingest-utils.ts (decorator-free, unit-tested). No behaviour change.
v0.18.2
Reliability and security pass — no new features. Two indexes on visitor_event (createdAt, (channelId, createdAt)) are declared (run your migrations).
Security
Permissions. Self-update requires SuperAdmin; licence, purchase, portal and goal changes require UpdateSettings (everything was reachable with ReadCustomer).
The rate limiter keys on the same resolved address as everything else; proxy headers are only honoured when listed in trustedIpHeaders.
CSV exports quote cells that would run as spreadsheet formulas; the journey endpoint returns only the fields the drawer shows.
The IP hash salt falls back to signingSecret before the public constant.
Fixed
Storefront identity across origins.hulo.js now keeps a first-party visitor id (localStorage) and a 30-minute session id and sends them with every batch; on a storefront hosted on a different origin than the API the cookies never travelled, so uniques equalled page views.
URLs.hulo.js sends location.href; events are now stored as path + query, so funnels, conversion goals and source reports match again.
The GraphQL visitor summary aggregates bounce rate and duration in SQL instead of loading every session row; SUM(boolean) replaced with SUM(CASE …) everywhere (Postgres).
A cookie containing a bare % no longer turns every beacon into a 500; UTM fields are capped to their column widths (a long utm_source used to drop the whole batch); oversized meta (large cart snapshots) is shrunk item-wise instead of cut mid-JSON, so abandoned carts are still detected.
Public trending is capped at 7 days and memoised for a minute; goal stats count completions correctly (COUNT(v.id)); goal ids and query clamps are validated.
Abandoned-cart scanner: landing/last URL and referrer are the real first and last (the previous expression always returned an empty string), a scan cannot overlap the previous one, the Slack post times out after 8 s, and the opt-out GET shows a confirm button while the POST performs it (mail clients prefetch GETs).
Admin UI: the update banner is no longer shown twice, the copy button copies a real @, the restart poll is cancelled on destroy.
Changed
retention defaults to { days: 400 } (false keeps everything) and the sweeper runs on the worker only.
Events are inserted with insert() (no reload round trip).
v0.18.1
_Same content as 0.18.0, whose publish was left staged on the npm registry and never promoted; 0.18.1 is the first installable release of this line._
v0.18.0
Added
Recovery links can resume an order.issueRecoveryLink(cartId, { resumeOrderCode }) (and POST /ees/abandoned-carts/:id/recovery-link with the same body) binds the link to the visitor's open Vendure order. GET /ees/recover-cart now returns orderCode, orderState and resumable, and the new public POST /ees/recover-cart/resume?t=… adds resumeOrderCode — set only while that order is still AddingItems / ArrangingPayment. Storefronts keep re-adding items as the universal fallback.
Attribution. New abandoned_cart columns recoveryStep (link_issued → link_opened → resumed → converted, monotonic), convertedAt, convertedOrderId, convertedOrderCode and resumeOrderCode. The storefront reports a recovered checkout with the token-bound public POST /ees/recover-cart/converted { t, orderCode }; the scanner's own checkout_completed match sets convertedAt too. GET /ees/abandoned-carts/summary gains an attribution block (link issued / opened / resumed / converted counts, value recovered via link, opt-outs) and the list endpoint returns the new columns.
Email opt-out. New abandoned_cart_opt_out table. GET|POST /ees/abandoned-carts/opt-out?e=<token> (public; POST is the RFC 8058 one-click form) records an opt-out for the address in the HMAC token. Service API: isOptedOut(email) (fails closed), optOut, optIn, listOptOuts, buildOptOutLink(email) and buildListUnsubscribeHeaders(email) for the List-Unsubscribe / List-Unsubscribe-Post headers. Admin: GET /ees/abandoned-carts/opt-outs, POST /ees/abandoned-carts/opt-outs/remove { email }; the detail endpoint reports optedOut. New option abandonment.optOutSecret (defaults to recoveryLinkSecret, then signingSecret).
Storefront helper.hulo.resumeCart(token) and hulo.recoveryConverted(orderCode) — the helper remembers the token from restoreCart / resumeCart in sessionStorage, so the thank-you page needs one call.
Pure helpers exported for hosts: isResumableOrderState, advanceRecoveryStep, normaliseEmail, hashEmail, buildOptOutToken, verifyOptOutToken, buildOptOutUrl, buildListUnsubscribeHeaders.
Changed
The public recovery endpoints are rate-limited per client IP (recover-cart and resume 30/min, converted and opt-out 10/min) and answer with Cache-Control: no-store.
The new columns and the opt-out table are created at boot with ADD COLUMN IF NOT EXISTS / CREATE TABLE IF NOT EXISTS (MariaDB and PostgreSQL), so installs that do not run TypeORM migrations for plugins need no manual step. Installs that do can generate a migration as usual — the entity declares the same columns.
v0.17.2
Added
Per-channel recovery links.abandonment.storefrontBaseUrls (channel code → storefront origin) makes a cart abandoned on a second storefront link back to that storefront; unlisted channels use storefrontBaseUrl as before.
Fixed
README: the storefront restore route must show the basket the way the storefront does (drawer or page) rather than assume a /cart route, and must treat an ErrorResult from addItemToOrder as a failed line. The reference storefront implementation now does both.
v0.17.1
Changed
Branding. The bundled hulo-global-logo.svg is now the HG wordmark on the HULO black rounded square (the same mark as the huloglobal.com header), with explicit -light and -dark variants alongside the auto-switching default.
v0.17.0
Added
Licence & billing card in the admin. Always visible: the current state (free tier, free trial with first-charge date, monthly/annual subscription, lifetime, or master licence) with the actions that apply — start the 14-day free trial or subscribe, buy lifetime, Manage billing (Stripe customer portal: update card, cancel, switch plan) and Upgrade to lifetime (the old subscription stops billing at the end of its paid period). Requires licence SDK ^0.14.0.
v0.16.1
Changed
The 14-day free trial is now card-backed. Unlicensed installs run in the free tier; start the trial from the admin banner (monthly or annual → Start 14-day free trial) — Stripe collects a card, nothing is charged until day 15, cancel any time before then, one trial per customer — and the licence installs itself within a minute. The automatic no-card evaluation window is retired (licence SDK ^0.13.0).
v0.16.0
Added
Buy licence from the admin. The evaluation / free-tier banner now has a plan picker and a Buy licence button: checkout opens in a new tab and, once payment completes, the licence installs itself — no email round-trip, no .env edit, no restart. Renewed subscription keys are picked up automatically too. New admin endpoints licence/purchase-link and licence/claim-status.
Changed
Requires @huloglobal/vendure-licence-sdk ^0.12.0.
The 7-day card trial at checkout has been retired: every install already gets the 14-day no-card evaluation, and paid plans now bill from day one.
v0.15.3
Changed
README. Licensing paragraph now describes the 14-day fully-featured evaluation (the plugin already behaved this way); pricing unchanged at £9.95/month or £199 lifetime.
v0.15.2
Changed
Licence SDK ^0.11.0. Master licences (one key that activates every HULO plugin) and hardware-bound keys are now accepted by the runtime licence check.
Branding. Refreshed HULO Global logo (inline HG monogram) in the admin UI.
v0.15.1
Fixed
Premium background jobs now respect the tier. The abandoned-cart sweep (with its Slack notifications) and the recommendations co-view aggregation kept running after the evaluation ended; both now check premium access on every tick — and re-enable instantly when a licence is activated, no restart needed. Admin endpoints were already gated.
v0.15.0
Added
PostgreSQL support. All of the plugin's SQL now runs on Postgres as well as MySQL/MariaDB — the licence SDK's new dialect adapter translates queries transparently at runtime, so no configuration is needed: the plugin follows whatever database your Vendure dbConnectionOptions use. Verified against PostgreSQL 17. MySQL/MariaDB installs are unaffected (byte-identical passthrough).
v0.14.1
Changed
The update banner's "What's new" link now opens the plugin's changelog page on huloglobal.com, so you can read exactly what a release contains before updating.
v0.14.0
Added
One-click in-app updates. The update banner now has an "Update now" button: the plugin installs the new version via your project's own package manager (yarn/npm/pnpm auto-detected), verifies it landed, and gracefully restarts under your process supervisor (pm2/systemd). Admin-only; the target version is verified against the npm registry; a failed install never restarts anything. Disable with HULO_SELF_UPDATE=off; force restart without a detected supervisor with HULO_SELF_UPDATE=force. Note: a separate worker process picks the update up on its next restart, and the admin UI itself refreshes after your next admin build.
v0.13.1
Added
Update notifications in the admin UI. When a newer version is on npm, a dismissible banner shows current → latest with a copy-ready install command and a link to what's new. (Update data comes from the existing daily registry check — no new network calls.)
v0.13.0
Added
In-admin licence activation. A banner on the admin page shows the evaluation countdown (or free-tier state) with a paste-your-key box: the key is verified with the exact boot-time checks and activates instantly — no .env edit, no redeploy. Persisted in the shared hulo_licence_store table and restored on boot; env/init keys always take precedence. New licence/status, licence/activate and licence/deactivate admin endpoints.
v0.12.0
Added
14-day full-featured evaluation. Unlicensed installs now get the complete feature set for 14 days instead of the restricted free tier. Premium analytics features now also run during the evaluation window. The clock is anchored server-side (a hashed instance id — no personal data), so reinstalling does not restart it, and it fails open: if the licence server is unreachable the plugin keeps running fully. After the window the plugin drops to the free tier; all configuration is kept and reactivates instantly with a key.
v0.11.1
Fixed
anonymizeIp produced a malformed address (e.g. fe80::1::) for already-abbreviated IPv6 inputs. Abbreviated addresses are now left unchanged; full-form IPv6 still truncates to the first three hextets.
Added
Unit test suites: URL glob matcher, bot detection + IP anonymisation, proxy-header extraction.
v0.8.4
Added
GET /ees/abandoned-carts now includes each cart's parsed items array plus a short server-rendered itemsPreview string ("Windows 10 Pro, Office 2021 Pro +2 more"), sorted by quantity descending. Admin can see WHAT was abandoned without clicking through to the detail endpoint.
GET /ees/abandoned-carts/:id fills in missing name (and productId when it can) on every item by looking up product_variant_translation / product_translation. Only fills where the storefront snapshot didn't already capture a name — a stored name at cart time is more accurate than a live catalog lookup (products can be renamed after abandonment).
Changed
List endpoint drops the raw itemsJson string from its response — clients that need the JSON blob can hit the detail endpoint. Response payload stays lean.
v0.8.3
Added
Recommendation endpoints (trending, also-viewed, personal) now enrich every row with productName and productSlug via a single bulk lookup against product_translation. English translation preferred for multi-locale stores; single-locale installs land on their only translation. Soft-deleted products are excluded.
New exported type: RecommendedProduct.
Changed
Response row shape is now { productId, productName, productSlug, score, views } — the addition is backwards-compatible for consumers that only read productId, but callers that render the row can now show the name without a second round-trip. Admin UI updated in the parallel ee.software commit to render "Windows Server 2022 Datacenter #42" instead of just "#42".
v0.8.2
Documentation
README rewritten to cover every 0.8.x feature: the drop-in /ees/hulo.js storefront helper, cart-abandonment configuration and lifecycle, recommendation endpoints, search analytics, journey drawer buffs. Includes a walkthrough of the storefront-side /cart/restore route customers implement to consume recovery links.
Endpoints table split into Public (browser-safe, CORS-permissive) vs Admin, with every 0.8.0-introduced endpoint marked inline.
No runtime changes — bumped to ship the new README with the npm tarball.
v0.8.1
Added
/ees/hulo.js — the plugin now serves a drop-in typed storefront helper at this path. One <script src> tag and every event API (hulo.cartSnapshot, hulo.productView, hulo.search, hulo.checkoutCompleted, hulo.restoreCart) is available on window.hulo. Handles batching, sendBeacon on unload, and installs auto rage-click + dead-click detectors. Served with a 10-minute browser TTL + 24-hour stale-while-revalidate and permissive CORS so it works cross-origin from any storefront.
v0.8.0
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)
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.
v0.7.0
Added
Boot-time compatibility check via the new SDK helper warnIfIncompatibleVendure(). Logs a non-fatal warning when the runtime @vendure/core version is outside the tested range. Silent when inside; fail-open on unparseable versions.
Changed
Peer dep on @vendure/core tightened to >=3.5.0 <4.0.0 — Vendure 3.5, 3.6 and 3.7 are all covered. Anything under 3.5 has never been tested; anything from 4.0 upwards is deferred until the changelog is reviewed.
Uses @huloglobal/vendure-licence-sdk@^0.6.0.
v0.6.0
Added
Vendure Admin API GraphQL extensions. Operator endpoints are now first-class GraphQL queries alongside the existing REST admin endpoints: huloVisitorSummary, huloVisitorSources, huloVisitorTopPages, huloVisitorFunnel, huloVisitorJourney.
Storefront path (POST /ees/track) stays REST — it's anonymous, high-frequency, and can ingest millions of events a day; the resolver stack would add pointless overhead per event.
v0.5.0
Added
Tier-gating on every premium feature via the SDK's isLicensed() helper. Unlicensed installs get:
a hard 100 events / UTC day cap on POST /ees/track (returns {skipped: 'free-tier-cap'} after that);
live SSE feed 402;
conversion-goal creation 402;
CSV export 402.
Anti-tamper heartbeat via the SDK.
Changed
Relicensed the GitHub source to AGPL-3.0. Published npm builds remain under the commercial licence documented at <https://huloglobal.com/legal/terms/>.
npm builds now include Sigstore provenance attestations.
v0.4.3
Fixed
Dropped the conflicting display: block on mobile tables that broke the row / cell alignment.
v0.4.2
Changed
44px minimum tap targets on every interactive element in the admin UI.
v0.4.1
Changed
Comprehensive README refresh — documents the full v0.4 feature set with the storefront snippet, every privacy + security option, and the conversion-goals API.
v0.4.0
Added
Signed visitor + session cookies via the licence-sdk signValue / verifySignedValue helpers — tampered cookies are rejected.
Secure cookie flag is set automatically when serving over HTTPS.
Rate limiter (240 requests / 60s default) on POST /ees/track.
corsAllowedOrigins option restricts CORS reflection to the configured list (legacy wildcard preserved when empty).
UpdateChecker integration — /ees/visitors/status endpoint returns version + update info; admin banner appears on new releases.
v0.3.0
Added
Conversion goals — new ConversionGoal entity with a URL-glob matcher (* within segment, ** across segments). Pageviews matching a goal are tagged with goalId at ingest. CRUD endpoints (GET /ees/goals, POST /ees/goals, PUT /ees/goals/:id, DELETE /ees/goals/:id) and GET /ees/goals/stats for completion totals per period.
Bot detection — UA-classified isBot boolean on every event. Default keeps bot events for visibility; new dropBotEvents option skips ingest entirely.
anonymizeIp (default true) — IPv4 last octet / IPv6 last 80 bits dropped before storage; ipHash still uses the raw IP
requireConsent (default false) — gate ingest behind a body consent:true or cookie ees_consent=1
CSV export — GET /ees/visitors/export.csv?days=N (max 90).
v0.2.0
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.
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).