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:T2aa7,# 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.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:T1407,# 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.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:Tdec,# Vendure GoedGepickt plugin Plugin for integrating Vendure with GoedGepickt. ## Getting started Vendure's responsibilities vs GoedGepickt's responsibilities: - Vendure is your catalog. If you want a new product, add it in Vendure - GoedGepickt manages all things stock related. StockLevel, size and weight are all managed in GoedGepickt. 1. Add this to your plugin in `vendure-config.ts`: ```ts import { GoedgepicktPlugin } from '@pinelab/vendure-plugin-goedgepickt'; plugins: [ GoedgepicktPlugin.init({ vendureHost: 'https://your-vendure-server.io/', setWebhook: true // Automatically set webhooks in Goedgepickt or not // You can optionally set orders 'on_hold' in Goedgepickt if you'd like determineOrderStatus: (ctx, order) => { if (order.state === 'PaymentAuthorized') { return 'on_hold' as const; } else { return 'open' as const; // This is the default } } }), ... ] ``` 2. Run a [database migration](https://www.vendure.io/docs/developer-guide/migrations/) to add the new fields and entities to your database. 3. Start the server and go to `Settings` > `Channels`, open the channel you want to configure and select the **GoedGepickt** tab. Make sure you have the `SetGoedGepicktConfig` permission. 4. Here you can configure your `apiKey` and `webshopUuid` per channel. When you save the credentials, the plugin will make sure the configured vendureHost is set as webhook for order and stock updates. **The plugin will never delete webhooks**, so if you ever change your url, you should manually delete the old webhook via GoedGepickt. 1. The plugin registers two scheduled tasks. Make sure you have `DefaultSchedulerPlugin` configured in your Vendure config: - **Stock sync** runs every night at 2:00 UTC and pulls stock levels from GoedGepickt into Vendure. - **Product push** runs every Monday at 6:00 UTC and pushes all Vendure products to GoedGepickt. 2. Orders can be manually (re-)pushed to GoedGepickt via the **Push to Goedgepickt** action in the order detail page's action bar dropdown. ### Pickup points / drop off points This plugin uses custom fields on an order as pickup location address. You can set a pickup points on an order with this mutation, the plugin will then send the address to Goedgepickt: ```graphql mutation { setOrderCustomFields( input: { customFields: { pickupLocationNumber: "1234" pickupLocationCarrier: "1" pickupLocationName: "Local shop" pickupLocationStreet: "Shopstreet" pickupLocationHouseNumber: "13" pickupLocationZipcode: "8888HG" pickupLocationCity: "Leeuwarden" pickupLocationCountry: "nl" } } ) { ... on Order { id code } ... on NoActiveOrderError { errorCode message } } } ``` ### Stock locations This plugin **only works with a single stock location** in Vendure. It will not work correctly when you have multiple stock locations configured. GoedGepickt should manage stock for all your locations, and Vendure should only have a single stock location that reflects the total stock managed by GoedGepickt. ## Monitoring and Alerting You should monitor your server logs for the message `Failed to process job sync-order` with severity WARNING. This means an order was not pushed to GoedGepickt. Depending on your job queue implementation this will be retried. In Google Cloud, we create an alert for the following log query: ``` severity>=WARNING "Failed to process job sync-order" ``` 96:T1373,# 3.1.0 (2026-07-29) - Split the single nightly full sync scheduled task into two separate tasks: - `goedgepickt-sync-stock` runs every night at 2:00 AM to pull stock levels from GoedGepickt - `goedgepickt-push-products` runs every Monday at 6:00 AM to push all Vendure products to GoedGepickt - Split `doFullSync()` into `pullAllStocklevels()` and `pushAllProductsToGoedgepickt()` in `GoedgepicktService` # 3.0.1 (2026-07-24) - Include dashboard extensions in dist. # 3.0.0 (2026-07-24) - Replaced manual full sync with an automated nightly scheduled task. The plugin now registers a `ScheduledTask` that runs every night at 2:00 UTC (4:00 CEST) and syncs all enabled channels. - Pull stock levels from GoedGepickt via a button on the product detail page. - **Breaking:** Removed `endpointSecret` from `GoedgepicktPluginConfig`. The `/goedgepickt/fullsync/:secret` endpoint has been removed. - **Breaking:** Removed the `runGoedgepicktFullSync` GraphQL mutation. - **Breaking:** Removed the `GoedGepickt full sync` action bar item from the product list page in the dashboard. Use the scheduled task UI to trigger a full sync. - **Breaking:** The `DefaultSchedulerPlugin` must now be present in your Vendure config for the full sync to run automatically. # 2.4.1 (2026-07-24) - Fix negative freeStock from Goedgepickt by clamping stockOnHand to 0, preventing `error.stockonhand-cannot-be-negative` errors # 2.4.0 (2026-07-21) - Migrated to React Dashboard # 2.3.2 (2026-07-02) - Fix image placeholder detection so Vendure images are sent when Goedgepickt's placeholder is `.jpg` and so new products get the Vendure image # 2.3.1 (2026-06-30) - Send house numbers as strings to Goedgepickt API to prevent "Billing house number moet een tekst zijn" errors - Reduced push order job retries from 10 to 3 # 2.3.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 2.2.1 (2026-04-23) - Added support for incoming compound product stock update webhook # 2.2.0 (2026-02-05) - Upgraded to Vendure 3.5.3 # 2.1.6 (2025-11-25) - Fix `object null is not iterable at GoedgepicktService.splitHouseNumberAndAddition` for empty house number string # 2.1.4 (2025-11-13) - Documentation update # 2.1.3 (2025-11-06) - Updated official documentation URL # 2.1.2 (2025-10-17) - Allow empty UUID and ApiKey in Goedgepickt config on Channel. # 2.1.1 (2025-06-24) - Improved error logging when incoming webhooks fail - Don't try to transition to Delivered when the order is in PaymentAuthorized state # 2.1.0 (2025-06-04) - Upgrade to Vendure to 3.3.2 # 2.0.8 (2025-05-22) - Try/catch around event handling, to prevent node process crash on error # 2.0.7 (2025-04-24) - Fix for numeric SKU's # 2.0.6 (2025-04-24) - Set correct `main` and `types` paths in package.json, now that we don't export files from outside the root anymore. # 2.0.5 (2025-04-17) - Process incoming stock and order webhooks via the job queue, to prevent webhook disabling in GoedGepickt # 2.0.4 (2025-04-15) - Process stock updates via the job queue, so that it is retried when GoedGepickt returns a `Too Many Attempts` error - Don't use GoedGepickt as fulfilment handler anymore, instead directly move to `Shipped` or `Delivered` on incoming status change. - Update image when the image on GoedGepickt is a placeholder # 2.0.3 (2025-04-03) - Check for undefined or null, to prevent stock updates with 0 being ignored # 2.0.2 (2025-03-20) - Prevent empty update SQL statement - Update stock in batches of 500 # 2.0.1 (2025-03-20) - Setting allocated to 0 on incoming stock updates and full sync # 2.0.0 (2025-03-20) - Removed validating of webhook signature. Fetching stock and order status directly from GoedGepickt on incoming webhook instead. - Moved GG config to Channel Custom Fields, instead of custom UI component. - Breaking: DB migration needed - Breaking: You need to save GoedGepickt credentials on a channel now: Settings > Channel > GoedGepickt custom fields # 1.4.1 (2025-03-18) - Only sync product image on creation, not on update, after complaints from GoedGepickt about too many updates. # 1.4.0 (2024-12-19) - Update Vendure to 3.1.1 # 1.3.2 (2024-11-05) - `orderPlacedAt` field should not be mandatory to push to Picqer # 1.3.0 (2024-10-18) - Allow setting custom order state in GoedGepickt # 1.2.1 (2024-08-04) - Update compatibility range (#480) # 1.2.0 (2024-06-21) - Updated Vendure to 2.2.6 # 1.1.5 (2024-04-30) - Push jobs to queue with promise.all(), so that the fullsync webhook finishes faster, and all jobs are in queue. # 1.1.4 (2024-04-30) - Query by SKU fix for MySQL. `sku = :sku` instead of `productVariant.sku = :sku` # 1.1.3 (2024-04-30) - Log rate limit exceeded as info statements and retry. # 1.1.2 (2024-04-30) - Fix related to stock not updating when a variant with the same SKU has been deleted before. # 1.1.1 (2024-01-16) - Correctly transition to Delivered from Shipped # 1.1.0 (2023-10-24) - Updated vendure to 2.1.1 97:T1cae,# Vendure Store Credit Plugin A plugin for channel-aware store credit wallets with ledger tracking. Customers can use wallet balance as a payment method at checkout. ![Store Credit Wallets](https://plugins.pinelab.studio/plugin-images/store-credit-wallets.png) ## Installation ```bash npm i @pinelab/vendure-plugin-store-credit ``` ```ts // vendure-config.ts import { StoreCreditPlugin } from '@pinelab/vendure-plugin-store-credit'; plugins: [StoreCreditPlugin], ``` Run a migration to add the Wallet entities to the database, then create a Payment Method in the admin using the `store-credit` handler. You also need to rebuild the admin dashboard to see the new Store Credit Wallets on the customer detail page. ## Admin API These functions are available in the admin API. ### Create wallet Each customer can have multiple wallets. This mutation creates a new wallet for the customer. Starting balance is always 0. ```graphql mutation CreateWallet($input: CreateWalletInput!) { createWallet(input: $input) { id name balance currencyCode adjustments { id amount } } } # Variables: { "input": { "customerId": "1", "name": "Gift card" } } ``` ### Set balance (add or subtract) ```graphql mutation AdjustBalance($input: AdjustBalanceForWalletInput!) { adjustBalanceForWallet(input: $input) { id balance } } # Variables: { "input": { "walletId": "1", "amount": 1500 } } # Amount in minor units (1500 = €15.00). Use negative for deductions. ``` ### Refund payment to store credit An admin can choose to refund any payment to store credit wiht the custom `refundPaymentToStoreCredit` mutation: ```graphql mutation RefundToStoreCredit($paymentId: ID!, $walletId: ID!) { refundPaymentToStoreCredit(paymentId: $paymentId, walletId: $walletId) { id balance } } ``` To refund a payment that was made with store credit, you can use the built-in `refundOrder` mutation supplied by Vendure. In this case it will refund the store credit to the same wallet that was used to make the payment. ## Storefront usage Customers can pay for orders using their store credit balance. ```graphql mutation { addPaymentToOrder( input: { method: "store-credit", metadata: { walletId: "1" } } ) { ... on Order { id code } } } ``` Optionally, a customer can choose to partially pay for an order by specifying the amount to pay with store credit. ```graphql mutation { addPaymentToOrder( input: { method: "store-credit" metadata: { walletId: "1", amount: 100000 } } ) { ... on Order { id code } } } ``` Logged-in customers can fetch their wallets via `activeCustomer`: ```graphql query MyWallets { activeCustomer { id wallets { items { id name balance currencyCode adjustments { amount } } totalItems } } } ``` Or query a single wallet by ID: ```graphql query Wallet($id: ID!) { wallet(id: $id) { id name balance currencyCode adjustments { id amount createdAt } } } ``` ## Gift cards You can configure the plugin to automatically create gift card wallets when certain products are ordered. Use the `createGiftCardWallet` hook in the plugin options: ```ts StoreCreditPlugin.init({ createGiftCardWallet: async (ctx, injector, order, orderLine) => { // Return { price, cardCode } to create a gift card wallet for this item // Returning false skips this item }, }); ``` The hook is called **once for each quantity per order line item**. For example, if an order has 1 order line with a giftcard, and the quantity is 3, the hook is invoked 3 times, allowing you to return a different `cardCode` for each individual gift card. The generated gift card codes are saved to the order line's `giftCardCodes` custom field, so you can reference them later (e.g. for email delivery or customer notifications). ### Paying with a gift card code Customers can pay for an order by providing the gift card code at checkout. The full wallet balance will be applied to the order (up to the outstanding amount). ```graphql mutation { addPaymentToOrder( input: { method: "store-credit", metadata: { giftCardCode: "ABC123" } } ) { ... on Order { id code } } } ``` To only pay a specific amount with the gift card, include the `amount` in the metadata: ```graphql mutation { addPaymentToOrder( input: { method: "store-credit" metadata: { giftCardCode: "ABC123", amount: 100000 } } ) { ... on Order { id code } } } ``` ## Gift card code security Gift card wallets are identified by their `code`. Treat this code like cash: anyone who knows the code can spend the wallet. It is the responsibility of the consuming project (via the `createGiftCardWallet` strategy) to make sure the returned `cardCode` is sufficiently unguessable — use a cryptographically secure random generator (e.g. `crypto.randomUUID()` or `generatePublicId()` from `@vendure/core`) and never derive the code from predictable data like order id or sequence numbers. The `walletByCode` query has a few safeguards to reduce enumeration risk: - on the admin API it requires the `UpdateOrder` permission; - on the shop API it requires the caller to have an active order on the session; - it returns `null` for unknown codes (instead of throwing) so the API does not leak whether a given code exists; - lookups are channel-scoped. # Helper scripts You can create wallets with a specified balance for all (or given) customers with the following script that is included: ```ts import { bootstrap } from '@vendure/core'; import { createWalletsForCustomers } from '@pinelab/vendure-plugin-store-credit'; import dotenv from 'dotenv'; dotenv.config({ path: process.env.ENV_FILE }); // Import vendure config after dotenv.config() so env variables are available in config import('./vendure-config') .then(async ({ config }) => { const app = await bootstrap(config); const wallets = await createWalletsForCustomers( app, // Details for all wallets { name: 'Special promotion wallet', balance: 123456, balanceDescription: 'Special promotion credits', }, // Administrator email address to use for record-keeping 'admin@example.com', // A list of customer email addresses to create wallets for. If omitted, all customers get a wallet. undefined ); console.log(`Created ${wallets.length} wallets`); await app.close(); }) .catch((err) => { console.error(err); }); ``` # FAQ ## Can I create a wallet with an initial starting balance? To create a wallet with an initial starting balance, you can create a wallet for a customer on the customer detail page in the admin dashboard. Wallets always start with a balance of 0, but you can adjust the balance to anything you want after creation. Wallets always start with 0, so that you can recalculate the current balance by 'rerunning' all the adjustments. ## Can I delete a customer's wallet? Currently you can not delete a wallet, because of accountability: you need to be able to see the history of adjustments on the wallet. Future version will allow you to archive a wallet. 98:Tbca,# 2.1.0 (2026-08-06) - Allow creating gift cards via the Dashboard. # 2.0.2 (2026-08-04) - Auto-created gift cards are no longer linked to the purchasing customer, so they can be used by any customer with the gift card code. - Made `WalletAdjustment.mutatedBy` optional, allowing gift-card payments to be recorded without an active user (e.g. anonymous/guest customers). - **BREAKING**: A database migration is required. Drop the `NOT NULL` constraint on `wallet_adjustment.mutatedById` so that adjustments can be created without an associated user. # 2.0.1 (2026-08-04) - Added documentation for paying with a gift card code, with and without a specified amount. # 2.0.0 (2026-07-21) - **BREAKING**: The `createGiftCardWallet` hook is now called once per order line quantity instead of once per order line. This allows returning different gift card configurations for each individual item when the quantity of an order line is > 1. - Added `giftCardCodes` custom field to `OrderLine` to store generated gift card codes. - Renamed `GiftCardWalletCreatedEvent` to `GiftCardsCreatedEvent`. The old class name is kept as a deprecated alias. - A database migration is required due to the new custom field. # 1.7.0 (2026-07-21) - Migrated to React Dashboard # 1.6.0 (2026-08-05) - Upgraded to Vendure 3.6.3 # 1.5.0 (2026-04-15) - Added support for `Wallet` based Gift Cards - Security: `walletByCode` is now channel-scoped, returns `null` for unknown codes, requires `UpdateOrder` on the admin API and an active order on the shop API (to prevent enumeration attacks) - Security: wallet debits are now performed atomically to prevent race conditions / double-spend - BREAKING: `WalletService.create` now throws when neither `customerId` nor `code` is provided. The admin `CreateWalletInput` has a new optional `code` field; pass a code explicitly when creating a wallet without a customer - BREAKING: the admin `giftCardWallets` query now requires the `ReadCustomer` permission - The removed unique index on `wallet.name` allows duplicate wallet names across customers # 1.4.1 (2026-02-20) - Include raw .tsx components for React Extension distribution # 1.4.0 (2026-02-13) - Add pagination support for querying adjustments on wallets. - BREAKING: `wallet.adjustments` is now paginated, that means you need to query `adjustments { items { ...fields } }` instead of `adjustments { ...fields }`; # 1.3.0 (2026-02-12) - Added metadata field on a wallet for custom data # 1.2.0 (2026-02-12) - Added dashboard components for managing wallets and balance on the customer detail page. - BREAKING: DB migration required, balance is now defined as `Money` to prevent rounding errors. # 1.1.0 (2026-02-03) - Accept amount as input to the store credit payment handler, to partially pay for an order with store credit - Export helper functions to populate wallets for customers - BREAKING: DB migration required: Customers can not have multiple wallets with the same name # 1.0.0 (2026-02-03) - Initial release 99: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). 9a:T395a,# 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.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). a1:T3110,# 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.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