8f:Te07,# @huloglobal/vendure-plugin-fraud-prevention Full fraud-prevention suite for [Vendure](https://www.vendure.io/). Every placed order is risk-scored **server-side** the moment it lands — no storefront integration required — and what happens next is up to your per-channel policy: log it, hold it for manual review, or hold it *and* tell the customer it's being verified. **Plugin page & pricing:** https://huloglobal.com/vendure-plugins/fraud-prevention/ ## Signals Each fired signal adds weighted points (all weights overridable per channel): | Signal | Default points | |---|---| | Blocklisted email / domain | 60 / 45 | | Blocklisted IP / IP in CIDR range | 55 | | Disposable email domain | 50 | | Failed payments from IP (1h) | 45 | | IP order velocity (hour / day) | 40 / 30 | | High-risk country | 40 | | Email order velocity (24h) | 35 | | Email daily value ceiling | 30 | | Order value ceiling | 25 | | First order + high value | 18 | | Plus-addressed email (`x+7@gmail`) | 12 | Emails are canonicalised before velocity counting — `x+1@gmail.com`, `x+2@gmail.com` and `x.y@gmail.com` all count as one identity. Allowlisted identities bypass everything. ## Enforcement modes (per channel) - **Off** — nothing, not even logging. - **Monitor** — score + log every order; risky orders are flagged but never held. Start here and tune thresholds against the Activity tab. - **Enforce** — score ≥ review threshold opens a case in the Review queue and (with the host integration below) holds licence-key/goods fulfilment until a human approves; score ≥ block threshold additionally emails the customer that their order is under verification. Approve releases + notifies; reject cancels + notifies. ## Threat feeds Daily sync (03:00) into the blocklist: **FireHOL Level 1**, **Spamhaus DROP** (CIDR ranges are matched properly), **Tor exit nodes**, and the community **disposable-email-domains** list. Manual allow/block entries ride on top. ## Install ```bash npm i @huloglobal/vendure-plugin-fraud-prevention ``` ```ts import { FraudPreventionPlugin } from '@huloglobal/vendure-plugin-fraud-prevention'; plugins: [ FraudPreventionPlugin.init({ publicBaseUrl: 'https://shop.example.com', licenceKey: process.env.HULO_FRAUD_LICENCE, }), ], ``` Admin UI (multi-tab dashboard: Overview, Rules, Review queue, Lists, Simulate, Activity, Settings): ```ts // in your compileUiExtensions extensions array: FraudPreventionPlugin.uiExtensions, ``` ### Holding fulfilment on pending cases The plugin marks orders as held; your fulfilment path asks before shipping: ```ts import { FraudPreventionService } from '@huloglobal/vendure-plugin-fraud-prevention'; const held = new Set(await this.fraudService.pendingOrderIds()); if (held.has(orderId)) continue; // skip until a human approves ``` ### Storefront pre-check (optional) `POST /fraud-prevention/check` `{ email, orderValuePence, channelId }` → `{ allowed, riskLevel }` — rate-limited, minimal response shape by design. ## Licensing Without a licence key the plugin runs in the **free tier**: monitor mode, manual lists and simulate. Enforce mode, review-queue holds, threat-feed sync and email alerts require a licence from https://huloglobal.com/vendure-plugins/fraud-prevention/. ## Compatibility Vendure `>=3.5 <4`. MariaDB/MySQL. Tables are created/migrated automatically on boot; upgrading from the pre-plugin HULO implementation preserves all existing config, log and list data. ## License AGPL-3.0-or-later — commercial licences available from HULO Global. 90:T38ec,# Changelog All notable changes to `@huloglobal/vendure-plugin-fraud-prevention` 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.14.0] — 2026-08-23 ### 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. ## [0.13.0] — 2026-08-22 ### Changed - **"Off" no longer means "blind".** When protection is disabled the engine still evaluates every rule and records a shadow assessment (action 'shadow', never any holds). Risky shadow-scored orders warn in the server log, fan out to the ops channels (new 'shadow.risky' event), optionally email the admin, and the order-detail panel shows a "scored while protection was off" notice — so switching protection off never silently loses the risk picture. ## [0.12.0] — 2026-08-22 ### Added - **Fraud panel on the admin order page.** Every paid order's detail page now shows the risk score (/100), level, contributing signals and review-case status, colour-coded and adapted to the admin light/dark theme. Only rendered once the order has a settled payment. New GET order-assessment/:orderId admin endpoint. ## [0.11.0] — 2026-08-21 ### Added - **One-click threat-feed presets.** The Custom feeds section now offers seven curated, well-known public lists (IPsum L3+, blocklist.de, FireHOL L2/L3, Emerging Threats compromised, CINS Army, StopForumSpam toxic domains) as add-with-one-click presets — no more hunting URLs. All URLs verified live at publish time; already-added feeds are hidden from the preset row. ### Fixed - Premium buttons (enforce mode, feed sync, custom feeds) were still disabled during the full-featured evaluation — gating now keys off the tier, so trial installs can use everything the server allows. ## [0.10.0] — 2026-08-21 ### Added - **In-admin licence activation.** Paste your key into the plugin's admin page and it verifies (signature, plugin id, domain binding, expiry, revocation) and activates instantly — no .env edit, no redeploy. The key persists in the shared hulo_licence_store table and is re-applied on every boot; an explicitly configured env/init key always wins. POST licence/activate + licence/deactivate endpoints. ## [0.9.1] — 2026-08-21 ### Added - Evaluation pings now include anonymous usage aggregates (counts only, never personal data) so the opt-in reminder emails can say what the plugin actually did during the trial. ## [0.9.0] — 2026-08-21 ### Added - **14-day full-featured evaluation.** Unlicensed installs now get the complete feature set for 14 days instead of the restricted free tier. Enforce mode, review-queue holds, threat feeds and alerts 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. - Admin-UI evaluation banner with live countdown and an optional "email me before it ends" reminder opt-in (explicit consent — no email is sent anywhere otherwise). ## [0.8.0] — 2026-08-04 ### Added - **Upload image / asset library** button in the message editor — opens Vendure's asset picker (browse or upload) and inserts the image, stored in your asset library. Editor selection is saved/restored so toolbar and colour actions apply reliably after a dialog opens. ## [0.7.0] — 2026-08-04 ### Added - **Full editor toolbar** for the customer messages: text + highlight colour, font size, underline/strikethrough, headings/quotes, numbered lists, indent/outdent, image insert, custom button, divider, alignment, clear-formatting and undo/redo. ### Fixed - Editor text showed grey in dark mode (admin theme colouring bare block elements). Canvas content now forces dark ink on the white paper. ## [0.6.1] — 2026-08-04 ### Fixed - Dark mode: the customer-message editor canvas now reads as intentional white paper (framed, visible caret), and the message preview renders on white — it was showing on a dark surface, which misrepresented the email and clashed with its inline colours. ## [0.6.0] — 2026-08-04 ### Added - **Visual email editor** for the customer messages (held / approved / rejected): formatting toolbar, drag-and-drop variable chips, and a Visual / HTML toggle. Message bodies are now HTML-aware — the plain-text defaults still render as before, but you can build a fully styled HTML email and it passes through untouched. ## [0.5.0] — 2026-08-03 ### Added - **Custom threat feeds.** Add your own public blocklist URLs in the Lists tab — any line-based list (one entry per line, `#` comments ignored), typed as IP / CIDR range / email / email-domain. They sync nightly alongside the built-ins and are matched identically (CIDR included), with per-feed enable/disable, on-demand sync, and last sync count / error surfaced. Licensed feature. - Endpoints: `GET/POST /fraud-prevention/feeds/custom`, `POST /feeds/custom/:id` (edit / `{sync:true}`), `DELETE /feeds/custom/:id`. ### Security - Feed fetches reject non-http(s) schemes and internal/private targets (localhost, RFC-1918, link-local) as a basic SSRF guard, and cap the response at 30 MB. ## [0.4.3] — 2026-08-02 ### Fixed - Public `POST /fraud-prevention/check` returned Nest's default `201` for a POST; it's a read-only risk check, so it now returns `200`. ### Added - End-to-end test suite (`@vendure/testing`, real MariaDB dialect): admin auth gating, public-check shape + rate limiting, and the assessment engine (disposable email, order value, returning-customer trust credit, blocklist incl. CIDR ranges, allowlist bypass, unlicensed enforce downgrade). 11 e2e tests. ## [0.4.2] — 2026-08-02 ### Fixed - **Webhook integration row showed nothing, Telegram row was wrong.** A regex repair back in 0.3.3 over-matched and deleted the Telegram chat-ID field and the entire Webhook case, leaving the Telegram row bound to the webhook secret. Both integration rows are restored: Telegram (bot token + chat ID) and Webhook (URL + signing secret). ### Added - **Customer messages: multi-select + bulk reset.** Each of the three templates (held / approved / rejected) shows a default / customised badge; tick any combination and "Reset selected to default", or "Reset all to default" in one click. Per-template reset stays. ## [0.4.1] — 2026-08-02 ### Fixed - **Review queue froze the browser tab** ("page unresponsive") when toggling the per-case "email customer" / "blocklist" checkboxes. The checkboxes bound to method calls (`[ngModel]="caseNotify(id)"`) which Angular re-evaluated every change-detection pass. The per-case ticks are now seeded from the global defaults when cases load and bound to plain state. The Settings integrations list likewise iterates a stable array instead of one rebuilt each cycle. ## [0.4.0] — 2026-08-02 ### Added - **Silent resolution.** Approve and Reject each carry a per-case "email customer" tick — untick to resolve without telling the customer anything. Defaults follow the global settings. - **Silent identity blocklist on reject.** A per-case "blocklist" tick (and a global default) quietly adds the rejected email + canonical + IP to the blocklist, so a fraudster is turned away next time and never learns why — the classic don't-tip-them-off move. - **Global notification defaults**: email-on-approval, email-on-rejection and blocklist-on-reject are all channel-wide toggles in Settings; the per-case ticks pre-fill from them and override for the single case. ## [0.3.3] — 2026-08-02 ### Fixed - 0.3.2's `@` escape was corrupted by the release tooling (sed `&` back-reference) and still shipped a bare `@` — admin builds kept failing. Repaired and verified: no bare `@` remains in any template text node. ## [0.3.2] — 2026-08-02 ### Fixed - Admin UI failed to compile under Angular 17+ block syntax: the literal `@BotFather` in the Telegram help text is now the `@` entity. ### Changed - New logo: shield + amber pulse trace (live risk monitoring), also used in the admin hero. ## [0.3.1] — 2026-08-02 ### Changed - **Rules tab simplified.** New Protection level presets — Relaxed / Balanced (recommended) / Strict — set thresholds and velocity limits in one click; every numeric field now lives behind an Advanced settings toggle. Editing any value flips the level to Custom. - **Notifications redesigned** as an integrations list: one row per channel (Email, Slack, Discord, Teams, Telegram, Webhook) with a connected-status dot, expanding in place to its few fields — instead of seven URL inputs spread across the page. ## [0.3.0] — 2026-08-02 ### Added - **Ops notification fan-out**: Slack, **Discord**, **Microsoft Teams**, **Telegram** (bot token + chat id) and a **generic signed webhook** (JSON POST, HMAC-SHA256 in `X-Hulo-Signature`) — every held, approved, rejected and auto-released case pings all configured channels. Each transport fails independently. - **Customisable customer messages, per channel**: the three gating outcomes (held / approved / rejected) are now editable templates with `{{orderCode}}`, `{{firstName}}`, `{{supportEmail}}` and `{{reviewHours}}` variables, live preview and one-click reset. Bodies are plain text (blank lines = paragraphs) so tone is editable without HTML foot-guns. Defaults rewritten to be honest without being alarming — a held order is "a quick security check", never an accusation, and a rejection includes a human-appeal path. - **Hold-notice policy per channel**: tell the customer never / only at block level (default) / on every held order; plus a configurable `reviewHours` promise surfaced in the templates. - Auto-released cases now email the customer with the approved template and post an ops event. ## [0.2.0] — 2026-08-02 ### Added - **IP intelligence** (ip-api.com, cached 30 days in `fraud_ip_intel`, fails open): VPN/proxy and datacentre-IP signals — the `blockVpnProxy` toggle finally does something — plus **IP vs billing-country mismatch**. - **Email MX validation**: a domain that can't receive mail can't receive licence keys either. Authoritative NXDOMAIN/no-MX scores; DNS timeouts fail open. 24h in-memory cache. - **Identity fan-out**: ≥3 distinct customer emails ordering from one IP inside 24h — the classic card-testing pattern. - **Customer trust credit**: returning customers earn NEGATIVE points (−12 for 1–2 settled orders, −25 for 3+), counted by canonical email so plus-tag variants share one track record. Score floors at 0. High-value first orders still score as before. - **Gibberish-email heuristic** (digit-heavy or keyboard-mash local parts; deliberately low-weight) and **billing/shipping country mismatch** signal. - **Customer Lookup tab**: full dossier per email — orders, lifetime value, settled/cancelled split, failed payments, prior cases, assessment history, list status, one-click allow/block. - **Slack alerts**: optional webhook pinged on every held order. - **Auto-release timer** (per channel, default off): pending cases older than N hours auto-approve so held orders don't strand over a weekend. - **CSV export** of the activity log. ## [0.1.0] — 2026-08-02 First release as a standalone plugin — a full rebuild of the fraud tooling that previously lived inside the HULO host project, with the piece that implementation never had: **real enforcement**. ### Added - **Server-side order guard.** Every `OrderPlacedEvent` is assessed — the old `/check` endpoint required the storefront to call it, and nothing did. - **Signal-based scoring engine** with per-channel weights: velocity (IP/hour, IP/day, email/day, email daily value), order value, disposable emails, block/allow lists, high-risk countries, failed payments, plus-addressing detection (emails canonicalised before velocity counting), first-order-high-value. - **CIDR range matching.** Spamhaus DROP and FireHOL ship ranges; the old implementation stored them but never matched them. Prefix-filtered SQL + exact `ipInCidr` verification (unit-tested). - **Enforcement modes** per channel: off / monitor / enforce, with separate review and block thresholds and a plain-English status sentence. - **Review queue workflow.** Pending cases hold fulfilment (host hook: `pendingOrderIds()`); approve releases + emails the customer, reject cancels + emails. All decisions audited. - **Multi-tab admin dashboard** on the verified HULO admin design system (WCAG AA both themes): Overview (KPIs, daily chart, top IPs with one-click block), Rules, Review queue (count badge), Lists (manual + feeds), Simulate (full signal breakdown, dry-run), Activity (filterable audit log), Settings (notifications). - **Licensing** via the HULO licence SDK: free tier = monitor + manual lists + simulate; enforce, feed sync and alerts require a licence. Update banner + heartbeat as across the HULO suite. - **Retention**: audit log pruned nightly (default 180 days). ### Changed - Table names are inherited from the pre-plugin implementation (`fraud_config`, `fraud_log`, `fraud_blocked_orders`, `fraud_blocklist`, `fraud_whitelist`, `fraud_notification_config`) — upgrading preserves all live data; new columns are added automatically. ### Security - Admin REST surface now requires an authenticated admin session (`ReadCatalog` / `UpdateCatalog`) — previously these endpoints were mounted without any auth guard. The public `/check` endpoint is rate-limited and returns a minimal shape (no signal internals to probe). 91:Tdfa,# Vendure Google Asset Storage plugin Plugin for storing Vendure assets on Google Cloud Storage with support for pre-generated image presets. ## Getting started 1. Create a bucket which is publicly available in Google Cloud. 2. Add this to your `vendure-config.ts`: ```ts import { GoogleStoragePlugin, GoogleStorageStrategy, } from '@pinelab/vendure-plugin-google-storage-assets'; plugins: [ AssetServerPlugin.init({ storageStrategyFactory: () => new GoogleStorageStrategy(), route: 'assets', assetUploadDir: '/tmp/vendure/assets', }), GoogleStoragePlugin.init({ bucketName: 'your-bucket-name', presets: { // 500px wide webp thumbnail thumbnail: { extension: 'webp', generateFn: (sharp) => sharp .resize(500) .toFormat('webp', { quality: 80, smartSubsample: true }) .toBuffer(), }, // 1500px wide webp preview webpPreview: { extension: 'webp', generateFn: (sharp) => sharp.resize(1500).toFormat('webp').toBuffer(), }, }, }), ]; ``` 3. Run a database migration to add the `presets` custom field to the `Asset` entity. ## Image Presets Presets allow you to pre-generate different versions of uploaded images. These versions are stored directly in your Google Cloud Storage bucket. This means you can get direct URLs to these pre-generated images without having to go through the Vendure asset server. When an asset is uploaded, all configured presets are automatically generated. Each preset generates a new file in your bucket. ### Fetching Preset URLs You can fetch preset URLs through the Shop API using this query: ```graphql query { product(id: "1") { featuredAsset { id name presets { # these presets are defined in the plugin config above thumbnail webpPreview } } } } ``` :warning: Whenever you change the presets, or set presets for the first time,you need to re-generate the presets for all assets. This can be done by running the `generateGoogleStorageAssetPresets` mutation. ### Generating Presets for Existing Assets To generate presets for all existing assets, you can use the Admin API. You will need to have Asset Update permission to run this mutation. ```graphql # This will generate presets for assets that don't have any presets yet mutation { generateGoogleStorageAssetPresets } # Or, if you want to force re-generation of all presets mutation { generateGoogleStorageAssetPresets(force: true) } ``` ### Running locally Using this plugin on your local machine requires you to be logged in to Google Cloud, so that the plugin can upload assets to your bucket. 1. Run `gcloud auth application-default login` 2. Create a .env file with the following contents: ```env GCLOUD_PROJECT=your-project-id BUCKET=your-bucket ``` 3. Run `yarn start` and go to https://localhost:3050/admin to test asset uploads ### Google Cloud Storage Authentication Internally this plugin uses `new Storage();` to instantiate the Storage client, which uses ENV variables to authenticate: ``` // By default, the client will authenticate using the service account file // specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable and use // the project specified by the GCLOUD_PROJECT environment variable. See // https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application ``` For more information about Google Cloud authentication, see: https://cloud.google.com/compute/docs/tutorials/nodejs-guide 92:T507,# 2.3.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 2.2.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 2.1.2 (2025-11-13) - Documentation update # 2.1.1 (2025-11-06) - Updated official documentation URL # 2.1.0 (2025-07-15) - Allow generating presets only for assets that don't have presets yet # 2.0.0 (2025-07-11) - Added support for presets. The first time you set presets, or change preset settings, you will need to regenerate the presets for all existing assets with `generateGoogleStorageAssetPresets`. - Breaking: Config is now passed into `GoogleStorageAssetsPlugin.init({})`, instead of to the `GoogleStorageStrategy` constructor - Breaking: `Asset.thumbnail` is now deprecated, use `Asset.presets.` instead. `Asset.thumbnail` still resolves to old thumbnails, **but will not work for new assets** - Breaking: A database migration is needed, because a custom field is added to the `Asset` entity for saving the presets. # 1.4.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 1.3.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.2.2 (2024-10-31) - Use asset server for admin with Vendure V3 support # 1.2.1 (2024-08-04) - Update compatibility range (#480) # 1.2.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.1.0 (2023-10-24) - Updated vendure to 2.1.1 93:Tcf2,# @huloglobal/vendure-plugin-review-requests Automated post-purchase **review invitations** for [Vendure](https://www.vendure.io/), timed off your order dates. Sends a branded, Trustpilot-style email that links to your **free** Trustpilot review page — no paid Automatic Feedback Service required — and can show your live star rating pulled from the free Trustpilot API. **Plugin page & pricing:** https://huloglobal.com/vendure-plugins/review-requests/ ## What it does - **Timed off order dates.** An hourly worker finds orders that reached a trigger state (Delivered / Payment settled / Shipped) *N days ago* and invites the customer to review you. - **Free Trustpilot, done right.** The review button links to `https://www.trustpilot.com/evaluate/` (organic Service Reviews, free). Optionally add a free Trustpilot developer API key and the email shows your live **TrustScore + review count** as social proof. The link template is configurable, so you can point at Google reviews or anywhere else instead. - **Exclusions.** Never invite specific emails or whole domains (wholesale accounts, staff). One-click **unsubscribe** in every email auto-excludes. - **No spam.** Deduped per order, plus a per-customer **cooldown** (default 120 days) and a minimum order value. - **Editable email** with live preview + test-send, per channel. - **Multi-tab admin**: Overview (sent / eligible / opt-outs / failed, live rating), Settings, Email, Exclusions, Activity log. ## Install ```bash npm i @huloglobal/vendure-plugin-review-requests ``` ```ts import { ReviewRequestPlugin } from '@huloglobal/vendure-plugin-review-requests'; plugins: [ ReviewRequestPlugin.init({ publicBaseUrl: 'https://shop.example.com', // for unsubscribe links licenceKey: process.env.HULO_REVIEW_LICENCE, }), ], ``` Admin UI: ```ts ReviewRequestPlugin.uiExtensions, // in your compileUiExtensions extensions array ``` Then open **Review requests** in the admin, set your Trustpilot domain, timing and email, hit **Send test**, and switch the channel on. ## Getting your Trustpilot bits (all free) - **Review link** — nothing needed; it's just `evaluate/`. - **Live rating (optional)** — register a free app at for an **API key**, put it in Settings, and click *Check rating* (the plugin finds your business-unit id from the domain). ## Configuration (per channel) | Setting | Default | Notes | |---|---|---| | Trigger state | Delivered | Delivered / Payment settled / Shipped | | Delay (days) | 14 | days after the order date | | Min order value | 0 | skip low-value orders | | Cooldown (days) | 120 | don't re-ask the same customer | | Max per run | 200 | hourly throttle | | Review link template | Trustpilot evaluate URL | `{domain}` is substituted | ## Licensing Free tier: configure, preview and test-send. **Scheduled sending requires a licence** from https://huloglobal.com/vendure-plugins/review-requests/. ## Compatibility Vendure `>=3.5 <4`. MySQL / MariaDB. Tables are created on boot. Sends via your SMTP (`SMTP_SERVER` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASSWORD` / `SMTP_FROM`, or pass `smtp` to `init()`). ## License AGPL-3.0-or-later — commercial licences available from HULO Global. 94:T1f29,# Changelog All notable changes to `@huloglobal/vendure-plugin-review-requests` are documented here. Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project follows [semantic versioning](https://semver.org/spec/v2.0.0.html). ## [0.12.0] — 2026-08-23 ### 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. ## [0.11.1] — 2026-08-23 ### 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.) ## [0.11.0] — 2026-08-22 ### Added - **Review panel on the admin order page.** Shows whether this order's customer was invited to review (with history), and lets staff send the invitation manually — including a confirmed force-resend and a confirmed override for excluded customers. Opt-outs are always honoured server-side. Light/dark theme aware. New GET order-status/:orderId + POST send-order/:orderId endpoints. ## [0.10.0] — 2026-08-21 ### Added - **In-admin licence activation.** Paste your key into the plugin's admin page and it verifies (signature, plugin id, domain binding, expiry, revocation) and activates instantly — no .env edit, no redeploy. The key persists in the shared hulo_licence_store table and is re-applied on every boot; an explicitly configured env/init key always wins. POST licence/activate + licence/deactivate endpoints. ## [0.9.1] — 2026-08-21 ### Added - Evaluation pings now include anonymous usage aggregates (counts only, never personal data) so the opt-in reminder emails can say what the plugin actually did during the trial. ## [0.9.0] — 2026-08-21 ### Added - **14-day full-featured evaluation.** Unlicensed installs now get the complete feature set for 14 days instead of the restricted free tier. Scheduled sending now also runs 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. - Admin-UI evaluation banner with live countdown and an optional "email me before it ends" reminder opt-in (explicit consent — no email is sent anywhere otherwise). ## [0.8.0] — 2026-08-04 ### Added - **Upload image / asset library.** A new toolbar button opens Vendure's asset picker — browse the library or upload a new image — and inserts it into the email. Images are stored in your Vendure asset library like any other asset. The previous insert-by-URL button stays. Editor selection is now saved/restored so toolbar and colour actions apply reliably even after a dialog opens. ## [0.7.0] — 2026-08-04 ### Added - **Full editor toolbar**: text + highlight colour, font size, underline/ strikethrough, headings/subheadings/quotes, numbered lists, indent/ outdent, image insert (by URL, alt text), a custom button, horizontal divider, left/centre/right align, clear-formatting and undo/redo. ### Fixed - Editor text showed grey in dark mode: the admin theme was colouring bare block elements. Canvas content now forces its own dark ink on the white paper (inline colours in your HTML still win). ## [0.6.1] — 2026-08-04 ### Fixed - Dark mode: the visual editor canvas now reads as an intentional white "paper" (framed, with a visible caret + selection) instead of a bare white block, and the email preview renders on white to match how the email actually looks. ## [0.6.0] — 2026-08-04 ### Added - **Visual email editor.** The invitation email now has a WYSIWYG editor with a formatting toolbar (bold, italic, heading, lists, links, a one-click review button, alignment), **drag-and-drop variable chips** (drop {{firstName}}, {{productList}}, etc. anywhere), and a **Visual / HTML toggle** so you can drop into raw HTML whenever you want. Live preview + test-send unchanged. ## [0.5.0] — 2026-08-04 ### Added - **Product reviews.** A new "What to ask for" mode — Store review / Product reviews / Both. In product (or both) mode the email lists the actual products from the customer's order, each with its own "Review this" button linking to your storefront's product-review page (a configurable link template with {slug}, {name}, {orderCode}). Works alongside the Trustpilot/Google store review. New template variables {{reviewButton}} and {{productList}}. ## [0.4.0] — 2026-08-04 ### Added - **Google reviews live rating.** Pick Google in the platform selector, add a Google Maps API key (Places API) + your Place ID, and Connect — the email now shows your live Google star rating + review count, the same way Trustpilot does. Both platforms cache for 6h and fail open. ## [0.3.0] — 2026-08-04 ### Added - **Live customer search in Exclusions.** Type a name or email and pick a real customer to exclude — each result shows whether they're *already* excluded (and why: excluded / domain rule / unsubscribed), so it doubles as a quick "is this customer excluded?" check. - **Review-platform picker.** Choose Trustpilot / Google reviews / Reviews.io / Custom and the review link is built for you (Trustpilot keeps the live-rating auto-detect; the others use the link only). Any site with a review URL already worked via the template — this makes it one click. - Endpoints: `GET /review-requests/customers/search`, `GET /review-requests/exclusions/check`. ## [0.2.0] — 2026-08-04 ### Changed - **Simpler setup.** The Settings tab now opens with a one-click **Connect Trustpilot**: enter your domain (and an optional free API key) and the plugin auto-detects your business-unit id and pulls your live star rating — no manual lookups. Just a domain, a business name and "days after order" are on the main screen; everything else moved behind an Advanced toggle. ### Added - `POST /review-requests/trustpilot/detect` — resolve review link + business-unit id + live rating from a domain (+ key) in one call. ## [0.1.0] — 2026-08-04 First release. ### Added - **Order-date-timed review invitations.** Hourly worker invites customers whose order reached a trigger state (Delivered / PaymentSettled / Shipped) a configurable number of days ago. - **Free Trustpilot integration.** Review button links to the free `trustpilot.com/evaluate/` page (organic reviews, no paid AFS). Optional free Trustpilot API key reads the live TrustScore + review count to show as social proof in the email. Link template is configurable (Google, etc.). - **Customer exclusions** by email or domain, plus signed one-click **unsubscribe** that auto-excludes. - **Dedup + cooldown + minimum order value** so nobody is over-asked. - **Editable email template** per channel, with live preview and **test-send**. - **Multi-tab admin dashboard** (Overview / Settings / Email / Exclusions / Activity) on the HULO design system, with a send log and eligibility preview. - HULO licence SDK: free tier = configure + preview + test-send; scheduled sending is licensed. Admin REST requires an authenticated admin session. 95:T3f86,# @huloglobal/vendure-plugin-visitor-analytics Self-hosted full-funnel visitor analytics for Vendure storefronts. Pageviews, time-on-page, exit pages, configurable funnel, UTM attribution, conversion goals with URL-glob matching, bot detection, 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 7-day free trial then **£9.95/month**, or **£199 one-off lifetime** at [elite.charity/licence/buy/vendure-plugin-visitor-analytics](https://elite.charity/licence/buy/vendure-plugin-visitor-analytics). ## Install ```bash yarn add @huloglobal/vendure-plugin-visitor-analytics ``` ```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_VISITOR_ANALYTICS, // -- Privacy (defaults shown) -- honorDoNotTrack: true, anonymizeIp: true, requireConsent: false, dropBotEvents: false, // -- Security (recommended in production) -- signingSecret: process.env.HULO_VISITOR_SIGNING_SECRET, corsAllowedOrigins: [ 'https://shop.example.com', 'https://www.example.com', ], rateLimit: { capacity: 240, windowMs: 60_000 }, // -- 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 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 ``` 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 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) ``` ### Cart-restore route The recovery link the admin mints (see below) lands on `https://shop.example.com/cart/restore?t=`. Your storefront needs a route that: 1. Reads `?t=` from the URL 2. Calls `GET /ees/recover-cart?t=` 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 ### Lightweight ingest - `POST /ees/track` accepts a batch of up to 50 events at once. - Visitor + session cookies (`ees_vid`, `ees_sid`) issued + refreshed automatically. When `signingSecret` is set, cookies are HMAC-signed and tampered values are rejected — the visitor gets a fresh id. - `Secure` flag is set automatically when serving over HTTPS. ### Auto-enrichment Per event: - **User-agent** parsed via `ua-parser-js` → browser, version, OS, device. - **Geo** via MaxMind GeoLite2-City (no MaxMind account required — DB fetched at install via `geolite2-redist`). Skipped when the upstream proxy already provides a country (Cloudflare, Akamai, Fastly). - **UTM attribution** parsed server-side from every pageview URL: `utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`. Plus `referrerDomain` for grouping by source even when UTM is absent. - **Bot flag** — known crawler / monitoring / library UAs (Googlebot, Bingbot, UptimeRobot, Datadog, curl, Puppeteer, …) marked `isBot=true`. ### Configurable conversion goals A goal is a URL glob that, when matched, counts the visitor as having converted. Supports `*` (within segment) and `**` (across segments). ```bash curl -X POST https://shop.example.com/ees/goals -H 'content-type: application/json' \ -d '{"channelId":1,"name":"Checkout completed","urlPattern":"/checkout/thank-you/*","valueMinor":5000}' ``` Stats at `GET /ees/goals/stats?days=30&channelId=1`. ### Privacy controls - `honorDoNotTrack: true` (default) — `DNT: 1` and `Sec-GPC: 1` requests get a 200 with `{stored:0, skipped:'dnt'}`. - `anonymizeIp: true` (default) — IPv4 last octet dropped before storage; IPv6 reduced to the first 3 hextets. `ipHash` still uses the raw IP so unique-visitor counts stay accurate. - `requireConsent: false` (default) — flip on to require a `consent: true` 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: '/cart/restore?t=...' }`. The token is time-bounded (`recoveryLinkTtlHours`, default 72) and non-reusable. The storefront exchanges it via `GET /ees/recover-cart?t=` 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 and the 20 most recent URLs every 5 seconds. Auto-reconnects. ### Per-visitor journey Click any visitor for the full timeline: pages, custom events, time-on-page, country, browser, OS. ### CSV export `GET /ees/visitors/export.csv?days=N` (max 90 days) returns the raw events with full enrichment. ## HTTP endpoints **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=` | 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 User manual + screenshots: [huloglobal.com/vendure-plugins/visitor-analytics/docs/](https://huloglobal.com/vendure-plugins/visitor-analytics/docs/) ## Lost your licence key? Re-send every active key on file at [elite.charity/licence/forgot](https://elite.charity/licence/forgot). ## Licence Commercial. Buy at [elite.charity/licence/buy/vendure-plugin-visitor-analytics](https://elite.charity/licence/buy/vendure-plugin-visitor-analytics). 96:T416d,# 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.14.0] — 2026-08-23 ### 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. ## [0.13.1] — 2026-08-23 ### 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.) ## [0.13.0] — 2026-08-21 ### 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. ## [0.12.0] — 2026-08-21 ### 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. ## [0.11.1] — 2026-08-02 ### 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. ## [0.8.4] — 2026-07-04 ### 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. ## [0.8.3] — 2026-07-04 ### 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". ## [0.8.2] — 2026-07-04 ### 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. ## [0.8.1] — 2026-07-04 ### Added - `/ees/hulo.js` — the plugin now serves a drop-in typed storefront helper at this path. One ` ``` On `DOMContentLoaded` the helper calls `/geo-block/check`, and: - if the visitor is allowed → no-op - if `mode=block` → redirects to `/geo-block/blocked` (or the channel's `blockRedirectUrl` if set, or the tag's `data-redirect`) - if `mode=soft` → injects a sticky top banner with the operator's message Optional `data-*` attributes: `data-redirect="/somewhere-else"`, `data-timeout-ms="2500"`, `data-preview` (log verdict, no side effects). ### Server-side integration (full control) ```ts // On boot: cache the rules const cfg = await fetch('https://shop.example.com/geo-block/site-config', { headers: { 'vendure-token': CHANNEL_TOKEN }, }).then(r => r.json()); // Per request: get a decision (and audit it) const verdict = await fetch('https://shop.example.com/geo-block/check', { headers: { 'vendure-token': CHANNEL_TOKEN, 'cf-ipcountry': req.headers['cf-ipcountry'] ?? '', }, }).then(r => r.json()); if (!verdict.allowed) { if (verdict.redirectUrl) return res.redirect(302, verdict.redirectUrl); return res.render('blocked', { message: verdict.message, mode: verdict.mode }); } ``` ## Documentation User manual + screenshots: [huloglobal.com/vendure-plugins/geo-block/docs/](https://huloglobal.com/vendure-plugins/geo-block/docs/) ## Licence Commercial. Buy at [elite.charity/licence/buy/vendure-plugin-geo-block](https://elite.charity/licence/buy/vendure-plugin-geo-block). 9d:T391f,# Changelog All notable changes to `@huloglobal/vendure-plugin-geo-block` 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.10.0] — 2026-08-23 ### 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. ## [0.9.1] — 2026-08-23 ### 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.) ## [0.9.0] — 2026-08-21 ### 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. ## [0.8.0] — 2026-08-21 ### Added - **14-day full-featured evaluation.** Unlicensed installs now get the complete feature set for 14 days instead of the restricted free tier. Premium blocking 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. ## [0.7.4] — 2026-07-30 ### Fixed - **Buttons rendered unstyled in the admin.** The page borrowed Clarity button classes (`btn btn-secondary` etc.) from the admin shell, but the built admin CSS defines `.btn` only contextually and `.btn-secondary` not at all — "+ Add" and friends rendered as bare native buttons. Every control is now styled by the component itself (`.gbtn` system). - **Unreadable muted text.** Secondary text leaned on `--color-component-color-200/300`, which the admin never defines, so hardcoded slate fallbacks applied in both themes — unreadable on dark surfaces. Replaced by per-theme ink tokens. - **Invisible control boundaries.** The admin border tokens fail WCAG 1.4.11 in both themes (light `#bfc3cc` ≈ 1.7:1; dark border-200 is *darker than the surface*, 1.01:1). Inputs/buttons/switch now use a dedicated `--gb-ui-border` at ≥ 3:1 per theme. ### Added - **Accessibility, verified not assumed.** `scripts/contrast-check.py` simulates the shipped `color-mix()` tokens against the real admin theme values and checks every text/surface pair — 40/40 WCAG AA pass (≥ 4.5:1 text, ≥ 3:1 UI boundaries) in light and dark. - **Enforcement toggle switch** (`role="switch"`, keyboard + focus ring) replaces the ON/OFF pill + button pair. - **ARIA tabs** (`role="tablist"`/`tab`, `aria-selected`), labelled chip remove buttons, `aria-expanded` on collapsibles, `:focus-visible` rings on every control, `prefers-reduced-motion` support. - **Sticky save bar** — stays in view, shows "Unsaved changes" with an amber accent when dirty, and disables Save/Discard when clean. ## [0.7.3] — 2026-07-29 ### Fixed - **Dark mode.** All semantic surfaces (success/warning/danger/info tints) are derived from the live theme variables with `color-mix()` instead of hardcoded light-mode pastels, which produced light-text-on- cream unreadables in the dark theme (worst: selected preset cards). ### Changed - Active tab restyled to brand amber; IP allowlist tab shows a bypass-IP count badge; save bar highlights when there are unsaved changes. ## [0.7.2] — 2026-07-29 ### Changed - **Admin page redesign** on the unified HULO admin design system: brand hero with help drawer, plain-English status sentence describing exactly what the current rules do (with lockout warning), first-run panel, tabbed layout (Rules / Block page / IP allowlist / Simulate / Stats), KPI tiles and mini-bar country table on Stats. ## [0.7.0] — 2026-07-07 ### Added - **Bot / crawler allowlist.** New plugin option `botAllowlist`, defaulting to `'strict'` — matches every well-known SEO + social crawler (Googlebot, Bingbot, DuckDuckBot, Baidu, Yandex, AppleBot, Slurp, facebookexternalhit, Twitterbot, LinkedInBot, Slackbot, WhatsApp, Discord, Telegram, Pinterest, Reddit + more). Ships crawler-safe by default so restrictive geo rules don't silently drop search-engine crawls and de-index the site. Also accepts `'permissive'` (any UA self-identifying as bot / crawler / spider), `false` (no allowlist — use only when a WAF handles bots upstream), or a custom pattern array of strings + regexes. New audit decision `bot-allowlist`. - **Business-hours schedule.** New per-channel custom field `geoBlockSchedule` — a JSON object with `timezone`, `days`, `from`, `to`, and `outsideAction` (`block` / `soft` / `allow`). Recurring weekly window per channel; outside the window the configured action fires. Handles overnight windows and DST via `Intl.DateTimeFormat`. New audit decision `schedule`. IP + bot allowlists still bypass so ops and crawlers never see "closed for orders". - **Storefront drop-in helper JS** at `GET /geo-block/hulo-geo.js`. One `

Plugin Directory

Plugin Directory