@huloglobal/vendure-plugin-visitor-analytics 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.18.0] — 2026-09-11
+
+### Added
+- **Recovery links can resume an order.** `issueRecoveryLink(cartId, { resumeOrderCode })` (and `POST /ees/abandoned-carts/:id/recovery-link` with the same body) binds the link to the visitor's open Vendure order. `GET /ees/recover-cart` now returns `orderCode`, `orderState` and `resumable`, and the new public `POST /ees/recover-cart/resume?t=…` adds `resumeOrderCode` — set only while that order is still `AddingItems` / `ArrangingPayment`. Storefronts keep re-adding `items` as the universal fallback.
+- **Attribution.** New `abandoned_cart` columns `recoveryStep` (`link_issued` → `link_opened` → `resumed` → `converted`, monotonic), `convertedAt`, `convertedOrderId`, `convertedOrderCode` and `resumeOrderCode`. The storefront reports a recovered checkout with the token-bound public `POST /ees/recover-cart/converted { t, orderCode }`; the scanner's own `checkout_completed` match sets `convertedAt` too. `GET /ees/abandoned-carts/summary` gains an `attribution` block (link issued / opened / resumed / converted counts, value recovered via link, opt-outs) and the list endpoint returns the new columns.
+- **Email opt-out.** New `abandoned_cart_opt_out` table. `GET|POST /ees/abandoned-carts/opt-out?e=<token>` (public; POST is the RFC 8058 one-click form) records an opt-out for the address in the HMAC token. Service API: `isOptedOut(email)` (fails closed), `optOut`, `optIn`, `listOptOuts`, `buildOptOutLink(email)` and `buildListUnsubscribeHeaders(email)` for the `List-Unsubscribe` / `List-Unsubscribe-Post` headers. Admin: `GET /ees/abandoned-carts/opt-outs`, `POST /ees/abandoned-carts/opt-outs/remove { email }`; the detail endpoint reports `optedOut`. New option `abandonment.optOutSecret` (defaults to `recoveryLinkSecret`, then `signingSecret`).
+- **Storefront helper.** `hulo.resumeCart(token)` and `hulo.recoveryConverted(orderCode)` — the helper remembers the token from `restoreCart` / `resumeCart` in `sessionStorage`, so the thank-you page needs one call.
+- Pure helpers exported for hosts: `isResumableOrderState`, `advanceRecoveryStep`, `normaliseEmail`, `hashEmail`, `buildOptOutToken`, `verifyOptOutToken`, `buildOptOutUrl`, `buildListUnsubscribeHeaders`.
+
+### Changed
+- The public recovery endpoints are rate-limited per client IP (`recover-cart` and `resume` 30/min, `converted` and `opt-out` 10/min) and answer with `Cache-Control: no-store`.
+- The new columns and the opt-out table are created at boot with `ADD COLUMN IF NOT EXISTS` / `CREATE TABLE IF NOT EXISTS` (MariaDB and PostgreSQL), so installs that do not run TypeORM migrations for plugins need no manual step. Installs that do can generate a migration as usual — the entity declares the same columns.
+
+## [0.17.2] — 2026-09-10
+
+### Added
+- **Per-channel recovery links.** `abandonment.storefrontBaseUrls` (channel code → storefront origin) makes a cart abandoned on a second storefront link back to that storefront; unlisted channels use `storefrontBaseUrl` as before.
+
+### Fixed
+- README: the storefront restore route must show the basket the way the storefront does (drawer or page) rather than assume a `/cart` route, and must treat an `ErrorResult` from `addItemToOrder` as a failed line. The reference storefront implementation now does both.
+
 ## [0.17.1] — 2026-09-02
 
 ### Changed

package/README.md

@@ -64,6 +64,9 @@ export const config: VendureConfig = {
                 recoveryLinkSecret: process.env.HULO_ABANDONMENT_SECRET,
                 recoveryLinkTtlHours: 72,
                 storefrontBaseUrl: 'https://shop.example.com',
+                // Opt-out link signing (0.18.0). Falls back to
+                // recoveryLinkSecret, then signingSecret.
+                optOutSecret: process.env.HULO_ABANDONMENT_OPTOUT_SECRET,
             },
         }),
     ],
@@ -101,6 +104,8 @@ server-side scanners look those event types up by name.
 | `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 |
+| `hulo.resumeCart(token)` | same route, when you can resume the visitor's open order | as above, plus `resumeOrderCode` while the bound order is still open (0.18.0) |
+| `hulo.recoveryConverted(orderCode)` | on the thank-you page | attributes the order to the recovery link the visitor arrived through (0.18.0) |
 
 Full payload shapes:
 
@@ -130,9 +135,26 @@ needs a route that:
 
 1. Reads `?t=` from the URL
 2. Calls `GET /ees/recover-cart?t=<token>` to fetch `{ items: [...] }`
+   (or `POST /ees/recover-cart/resume?t=<token>` — see below)
 3. Re-adds each `{ variantId, qty }` via your Vendure order API (usually
-   `addItemToOrder(productVariantId, quantity)`)
-4. Navigates to `/cart` when done
+   `addItemToOrder(productVariantId, quantity)`) — check the result is an
+   `Order`, not an `ErrorResult` (out of stock, purchase limit…)
+4. Shows the basket when done — open your cart drawer or navigate to your
+   cart page, whichever your storefront has (don't assume a `/cart` route)
+5. On the thank-you page, calls `hulo.recoveryConverted(order.code)` (or
+   `POST /ees/recover-cart/converted { t, orderCode }`) so the cart is
+   attributed to the link — the helper remembers `t` in `sessionStorage`
+   from step 2, so this is a no-op for visitors who did not arrive through
+   a recovery link
+
+**Resuming the visitor's order (0.18.0).** When the host mints the link
+with `issueRecoveryLink(id, { resumeOrderCode })`, both recovery endpoints
+return `orderCode`, `orderState` and `resumable`, and the `resume` endpoint
+adds `resumeOrderCode` — non-null only while that order is still in
+`AddingItems` / `ArrangingPayment`. The Shop API cannot adopt an order
+anonymously, so treat it as a hint: a signed-in owner already has it as
+their active order (skip the re-add), a guest gets the items re-added as
+usual. Either way the `items` array is always present as the fallback.
 
 Guard against silently overwriting a live cart — if the visitor
 already has items, show a "you already have items in your cart"
@@ -232,9 +254,58 @@ The token is time-bounded (`recoveryLinkTtlHours`, default 72) and
 non-reusable. The storefront exchanges it via
 `GET /ees/recover-cart?t=<token>` to get back the persisted item list.
 
+Multi-storefront installs: set `abandonment.storefrontBaseUrls` to a map of
+channel code → storefront origin (for example
+`{ licensedock: 'https://license-dock.com' }`) and each cart's link points
+at the storefront it was abandoned on; channels not listed fall back to
+`storefrontBaseUrl`.
+
 Set `abandonment.recoveryLinkSecret` in plugin options to enable this —
 without it, the endpoint returns `{ error: 'recovery-disabled-or-not-found' }`.
 
+**Attribution (0.18.0).**
+Every `abandoned_cart` row carries `recoveryStep` — `link_issued` →
+`link_opened` → `resumed` → `converted`, never moving backwards — plus
+`convertedAt`, `convertedOrderId`, `convertedOrderCode` and
+`resumeOrderCode`. Steps advance as the link is minted, exchanged
+(`recover-cart`), resumed (`recover-cart/resume`) and finally reported
+converted by the storefront (`POST /ees/recover-cart/converted
+{ t, orderCode }` — token-bound, the order must exist and be past
+`AddingItems`). The scanner's own `checkout_completed` match still marks
+rows `converted` and stamps `convertedAt`, but leaves `recoveryStep`
+alone — so "converted via link" is exactly `recoveryStep = 'converted'`.
+`GET /ees/abandoned-carts/summary` returns an `attribution` block:
+
+```json
+{ "linkIssued": 120, "linkOpened": 41, "resumed": 9, "convertedViaLink": 14,
+  "convertedViaLinkValueMinor": 184950, "convertedTotal": 37, "optOuts": 3 }
+```
+
+**Email opt-out (0.18.0).**
+Recovery emails must carry an unsubscribe link. Build it with
+`abandonedCartService.buildOptOutLink(email)` and add the headers from
+`abandonedCartService.buildListUnsubscribeHeaders(email)`
+(`List-Unsubscribe` + `List-Unsubscribe-Post: List-Unsubscribe=One-Click`)
+so Gmail / Outlook / Yahoo show their native "Unsubscribe" button. Both
+point at `GET|POST /ees/abandoned-carts/opt-out?e=<token>` on the Vendure
+server: GET renders a small confirmation page, POST is the RFC 8058
+one-click form. The token is `base64url(email).hmac(email)` signed with
+`abandonment.optOutSecret` (default: `recoveryLinkSecret`, then
+`signingSecret`) — nobody can unsubscribe someone else.
+
+Before every send call `await abandonedCartService.isOptedOut(email)`;
+it fails closed (a DB error counts as opted out). Opt-outs live in
+`abandoned_cart_opt_out` (keyed by the SHA-256 of the lower-cased
+address). Admin: `GET /ees/abandoned-carts/opt-outs`,
+`POST /ees/abandoned-carts/opt-outs/remove { email }` after an explicit
+customer request; `GET /ees/abandoned-carts/:id` reports `optedOut`.
+
+**Schema.** The 0.18.0 columns and the opt-out table are added at boot
+with `ADD COLUMN IF NOT EXISTS` / `CREATE TABLE IF NOT EXISTS` (MariaDB
+and PostgreSQL). Installs that run TypeORM migrations for plugins can
+generate one as usual — the `AbandonedCart` entity declares the same
+columns, so the generator finds nothing to add once the plugin has booted.
+
 **Slack notification.**
 `abandonment.slackWebhookUrl` + `abandonment.slackMinValueMinor`
 control an at-most-once Slack post per abandonment above the value
@@ -315,7 +386,10 @@ storefront origin):
 | --- | --- | --- |
 | `POST` | `/ees/track` | ingest a batch of visitor events |
 | `GET`  | `/ees/hulo.js` | typed storefront helper JS (since 0.8.1) |
-| `GET`  | `/ees/recover-cart?t=<token>` | resolve a recovery token → items |
+| `GET`  | `/ees/recover-cart?t=<token>` | resolve a recovery token → items (+ `orderCode`, `orderState`, `resumable` since 0.18.0); 30/min per IP |
+| `POST` | `/ees/recover-cart/resume?t=<token>` | as above plus `resumeOrderCode` while the bound order is open (0.18.0); 30/min per IP |
+| `POST` | `/ees/recover-cart/converted` | `{ t, orderCode }` — attribute a placed order to its recovery link (0.18.0); 10/min per IP |
+| `GET`/`POST` | `/ees/abandoned-carts/opt-out?e=<token>` | email opt-out; POST is RFC 8058 one-click (0.18.0); 10/min per IP |
 | `GET`  | `/ees/recommendations/also-viewed?productId=…` | co-view recs |
 | `GET`  | `/ees/recommendations/personal?visitorId=…` | personalised recs |
 | `GET`  | `/ees/recommendations/trending?hours=…` | most-viewed products |
@@ -344,7 +418,9 @@ Vendure admin session cookie):
 | `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/recovery-link` | mint signed URL (0.8.0, `UpdateCustomer`); body `{ resumeOrderCode? }` binds it to an order (0.18.0) |
+| `GET`  | `/ees/abandoned-carts/opt-outs` | opted-out addresses (0.18.0) |
+| `POST` | `/ees/abandoned-carts/opt-outs/remove` | `{ email }` — re-enable after an explicit request (0.18.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`) |

package/dist/abandoned-cart.controller.d.ts

@@ -1,3 +1,4 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
 import { RequestContext } from '@vendure/core';
 import { Request, Response } from 'express';
 import { AbandonedCartService } from './abandoned-cart.service';
@@ -9,15 +10,26 @@ import { AbandonedCartService } from './abandoned-cart.service';
  *   GET  /ees/abandoned-carts/summary        — totals + top-value + recovery rate
  *   GET  /ees/abandoned-carts/:id            — detail incl. parsed items
  *   POST /ees/abandoned-carts/:id/recovery-link  — mint/reissue signed URL
+ *                                               (body `{ resumeOrderCode? }` binds it to an order, 0.18.0)
  *   POST /ees/abandoned-carts/:id/status     — mark recovered/dismissed
  *   GET  /ees/abandoned-carts/export.csv     — CSV export
+ *   GET  /ees/abandoned-carts/opt-outs       — opted-out addresses (0.18.0)
+ *   POST /ees/abandoned-carts/opt-outs/remove — `{ email }` re-enable (0.18.0)
  *
- * Storefront-side (unauthenticated):
- *   GET  /ees/recover-cart?t=...             — resolve a token → items
+ * Storefront-side (unauthenticated, rate-limited per IP):
+ *   GET  /ees/recover-cart?t=...             — resolve a token → items (+ orderCode / resumable, 0.18.0)
+ *   POST /ees/recover-cart/resume?t=...      — same, plus `resumeOrderCode` while the bound order is open (0.18.0)
+ *   POST /ees/recover-cart/converted         — `{ t, orderCode }` attribution when the restored cart checks out (0.18.0)
+ *   GET|POST /ees/abandoned-carts/opt-out?e= — email opt-out (RFC 8058 one-click on POST) (0.18.0)
  */
-export declare class AbandonedCartController {
+export declare class AbandonedCartController implements OnApplicationBootstrap {
     private readonly service;
+    private limiter;
     constructor(service: AbandonedCartService);
+    onApplicationBootstrap(): void;
+    /** True (and 429 already written) when the caller is over budget.
+     *  `cost` = 60 / per-minute allowance, so cost 2 → 30/min, cost 6 → 10/min. */
+    private rateLimited;
     list(ctx: RequestContext, takeRaw?: string, skipRaw?: string, status?: string, minValueRaw?: string, email?: string): Promise<{
         items: any;
         total: number;
@@ -28,6 +40,15 @@ export declare class AbandonedCartController {
     private buildItemsPreview;
     summary(ctx: RequestContext, daysRaw?: string): Promise<{
         windowDays: number;
+        attribution: {
+            linkIssued: number;
+            linkOpened: number;
+            resumed: number;
+            convertedViaLink: number;
+            convertedViaLinkValueMinor: number;
+            convertedTotal: number;
+            optOuts: number;
+        };
         total: number;
         openCount: number;
         recoveredCount: number;
@@ -40,6 +61,32 @@ export declare class AbandonedCartController {
         avgValueMinor: number;
     }>;
     exportCsv(ctx: RequestContext, res: Response, daysRaw?: string): Promise<void>;
+    /**
+     * Email opt-out. Public, token-bound (`e=` is an HMAC of the address —
+     * see `buildOptOutToken`). GET renders a tiny confirmation page for
+     * humans clicking the footer link; POST is the RFC 8058 one-click form
+     * mail clients send when the user hits their native "Unsubscribe".
+     * Both are idempotent.
+     */
+    optOutGet(req: Request, res: Response, tokenRaw?: string): Promise<void>;
+    optOutPost(req: Request, res: Response, tokenRaw?: string, body?: any): Promise<void>;
+    private applyOptOut;
+    private optOutPage;
+    listOptOuts(ctx: RequestContext, takeRaw?: string, skipRaw?: string): Promise<{
+        items: any[];
+        total: number;
+        take: number;
+        skip: number;
+    }>;
+    removeOptOut(ctx: RequestContext, body: {
+        email?: string;
+    }): Promise<{
+        ok: boolean;
+        error?: undefined;
+    } | {
+        error: string;
+        ok?: undefined;
+    }>;
     detail(ctx: RequestContext, idRaw: string): Promise<any>;
     /**
      * Fill in missing `name` (and, when possible, `productId`) on each
@@ -50,7 +97,9 @@ export declare class AbandonedCartController {
      * cart was abandoned).
      */
     private enrichItemsWithNames;
-    issueRecoveryLink(ctx: RequestContext, idRaw: string): Promise<{
+    issueRecoveryLink(ctx: RequestContext, idRaw: string, body?: {
+        resumeOrderCode?: string | null;
+    }): Promise<{
         error: string;
         hint: string;
         ok?: undefined;
@@ -75,15 +124,22 @@ export declare class AbandonedCartController {
      * of cart items the storefront can restore. Rate-limited by the
      * plugin's usual ingest limiter (same origin as the tracker).
      */
-    recover(req: Request, token?: string): Promise<{
-        error: string;
-    } | {
-        id: number;
-        currency: string;
-        items: any[];
-        email: string | null;
-        ok: boolean;
-        error?: undefined;
-    }>;
+    recover(req: Request, res: Response, token?: string): Promise<void>;
+    /**
+     * Resume the exact order the link was bound to. Same payload as
+     * `recover-cart` plus `resumeOrderCode` — non-null only while that
+     * order is still `AddingItems` / `ArrangingPayment`. The storefront
+     * cannot adopt an order anonymously through the Shop API, so it
+     * should treat `resumeOrderCode` as a hint (e.g. sign-in prompt for
+     * the owner, or "your order S2BZ… is waiting") and fall back to
+     * re-adding `items` — which always works.
+     */
+    resume(req: Request, res: Response, tokenQ?: string, body?: any): Promise<void>;
+    /**
+     * Attribution — the restored cart checked out. Token-bound, so a
+     * stranger cannot mark carts converted; the order must exist and be
+     * past `AddingItems`. Idempotent.
+     */
+    converted(req: Request, res: Response, tokenQ?: string, body?: any): Promise<void>;
 }
 //# sourceMappingURL=abandoned-cart.controller.d.ts.map

package/dist/abandoned-cart.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abandoned-cart.controller.d.ts","sourceRoot":"","sources":["../src/abandoned-cart.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAO,cAAc,EAAqB,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,qBACa,uBAAuB;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAIpD,IAAI,CACC,GAAG,EAAE,cAAc,EACX,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACvB,KAAK,CAAC,EAAE,MAAM;;;;;;IA6DlC,uDAAuD;IACvD,OAAO,CAAC,iBAAiB;IAiBnB,OAAO,CAAQ,GAAG,EAAE,cAAc,EAAiB,OAAO,CAAC,EAAE,MAAM;;;;;;;;;;;;;IAuCnE,SAAS,CAAQ,GAAG,EAAE,cAAc,EAAS,GAAG,EAAE,QAAQ,EAAiB,OAAO,CAAC,EAAE,MAAM;IA+B3F,MAAM,CAAQ,GAAG,EAAE,cAAc,EAAe,KAAK,EAAE,MAAM;IAwBnE;;;;;;;OAOG;YACW,oBAAoB;IAyE5B,iBAAiB,CAAQ,GAAG,EAAE,cAAc,EAAe,KAAK,EAAE,MAAM;;;;;;;;;;;IASxE,SAAS,CACJ,GAAG,EAAE,cAAc,EACb,KAAK,EAAE,MAAM,EAClB,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;IAWrC;;;;OAIG;IAEG,OAAO,CAAQ,GAAG,EAAE,OAAO,EAAc,KAAK,CAAC,EAAE,MAAM;;;;;;;;;;CAOhE"}
+{"version":3,"file":"abandoned-cart.controller.d.ts","sourceRoot":"","sources":["../src/abandoned-cart.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuD,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7G,OAAO,EAAO,cAAc,EAAqB,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,uBAAwB,YAAW,sBAAsB;IAGtD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,OAAO,CAA4B;gBAEd,OAAO,EAAE,oBAAoB;IAE1D,sBAAsB,IAAI,IAAI;IAO9B;mFAC+E;IAC/E,OAAO,CAAC,WAAW;IAab,IAAI,CACC,GAAG,EAAE,cAAc,EACX,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACvB,KAAK,CAAC,EAAE,MAAM;;;;;;IA8DlC,uDAAuD;IACvD,OAAO,CAAC,iBAAiB;IAiBnB,OAAO,CAAQ,GAAG,EAAE,cAAc,EAAiB,OAAO,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;IAyCnE,SAAS,CAAQ,GAAG,EAAE,cAAc,EAAS,GAAG,EAAE,QAAQ,EAAiB,OAAO,CAAC,EAAE,MAAM;IA6BjG;;;;;;OAMG;IAEG,SAAS,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ,EAAc,QAAQ,CAAC,EAAE,MAAM;IASlF,UAAU,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ,EAAc,QAAQ,CAAC,EAAE,MAAM,EAAU,IAAI,CAAC,EAAE,GAAG;YAQ/F,WAAW;IASzB,OAAO,CAAC,UAAU;IAcZ,WAAW,CAAQ,GAAG,EAAE,cAAc,EAAiB,OAAO,CAAC,EAAE,MAAM,EAAiB,OAAO,CAAC,EAAE,MAAM;;;;;;IASxG,YAAY,CAAQ,GAAG,EAAE,cAAc,EAAU,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;IAOzE,MAAM,CAAQ,GAAG,EAAE,cAAc,EAAe,KAAK,EAAE,MAAM;IA0BnE;;;;;;;OAOG;YACW,oBAAoB;IAyE5B,iBAAiB,CACZ,GAAG,EAAE,cAAc,EACb,KAAK,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;;;;;;;;;IAahD,SAAS,CACJ,GAAG,EAAE,cAAc,EACb,KAAK,EAAE,MAAM,EAClB,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;IAWrC;;;;OAIG;IAEG,OAAO,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ,EAAc,KAAK,CAAC,EAAE,MAAM;IAUnF;;;;;;;;OAQG;IAEG,MAAM,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ,EAAc,MAAM,CAAC,EAAE,MAAM,EAAU,IAAI,CAAC,EAAE,GAAG;IAUvG;;;;OAIG;IAEG,SAAS,CAAQ,GAAG,EAAE,OAAO,EAAS,GAAG,EAAE,QAAQ,EAAc,MAAM,CAAC,EAAE,MAAM,EAAU,IAAI,CAAC,EAAE,GAAG;CAS7G"}

package/dist/abandoned-cart.controller.js

@@ -15,7 +15,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AbandonedCartController = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@vendure/core");
+const vendure_licence_sdk_1 = require("@huloglobal/vendure-licence-sdk");
 const abandoned_cart_service_1 = require("./abandoned-cart.service");
+const proxy_headers_1 = require("./proxy-headers");
+const recovery_tokens_1 = require("./recovery-tokens");
 /**
  * Admin API for the Abandoned Cart feature.
  *
@@ -24,15 +27,41 @@ const abandoned_cart_service_1 = require("./abandoned-cart.service");
  *   GET  /ees/abandoned-carts/summary        — totals + top-value + recovery rate
  *   GET  /ees/abandoned-carts/:id            — detail incl. parsed items
  *   POST /ees/abandoned-carts/:id/recovery-link  — mint/reissue signed URL
+ *                                               (body `{ resumeOrderCode? }` binds it to an order, 0.18.0)
  *   POST /ees/abandoned-carts/:id/status     — mark recovered/dismissed
  *   GET  /ees/abandoned-carts/export.csv     — CSV export
+ *   GET  /ees/abandoned-carts/opt-outs       — opted-out addresses (0.18.0)
+ *   POST /ees/abandoned-carts/opt-outs/remove — `{ email }` re-enable (0.18.0)
  *
- * Storefront-side (unauthenticated):
- *   GET  /ees/recover-cart?t=...             — resolve a token → items
+ * Storefront-side (unauthenticated, rate-limited per IP):
+ *   GET  /ees/recover-cart?t=...             — resolve a token → items (+ orderCode / resumable, 0.18.0)
+ *   POST /ees/recover-cart/resume?t=...      — same, plus `resumeOrderCode` while the bound order is open (0.18.0)
+ *   POST /ees/recover-cart/converted         — `{ t, orderCode }` attribution when the restored cart checks out (0.18.0)
+ *   GET|POST /ees/abandoned-carts/opt-out?e= — email opt-out (RFC 8058 one-click on POST) (0.18.0)
  */
 let AbandonedCartController = class AbandonedCartController {
     constructor(service) {
         this.service = service;
+        this.limiter = null;
+    }
+    onApplicationBootstrap() {
+        // One shared bucket map; the bucket name is part of the key so each
+        // endpoint gets its own allowance. Capacity is the most generous of
+        // the per-endpoint limits — `cost` scales the others down.
+        this.limiter = new vendure_licence_sdk_1.RateLimiter({ capacity: 60, windowMs: 60000 });
+    }
+    /** True (and 429 already written) when the caller is over budget.
+     *  `cost` = 60 / per-minute allowance, so cost 2 → 30/min, cost 6 → 10/min. */
+    rateLimited(req, res, bucket, cost) {
+        const ip = (0, proxy_headers_1.getRealIp)(req) || '';
+        if (!ip || !this.limiter)
+            return false;
+        if (!this.limiter.allow(`${bucket}|${ip}`, cost)) {
+            res.setHeader('Retry-After', '60');
+            res.status(429).json({ error: 'rate-limited' });
+            return true;
+        }
+        return false;
     }
     async list(ctx, takeRaw, skipRaw, status, minValueRaw, email) {
         var _a;
@@ -65,6 +94,7 @@ let AbandonedCartController = class AbandonedCartController {
             // so the payload growth stays proportional to the page size.
             `SELECT id, sessionId, visitorId, customerId, currency, totalMinor, itemCount,
                         itemsJson, email, status, abandonedAt, recoveredAt, notificationSent,
+                        resumeOrderCode, recoveryStep, convertedAt, convertedOrderId, convertedOrderCode,
                         utmSource, utmMedium, utmCampaign, countryCode, regionCode, city,
                         ip, ipHash, userAgent, browser, deviceType,
                         landingUrl, lastKnownUrl, lastKnownReferrer,
@@ -135,8 +165,10 @@ let AbandonedCartController = class AbandonedCartController {
         const s = (rows === null || rows === void 0 ? void 0 : rows[0]) || {};
         const total = Number(s.total || 0);
         const rec = Number(s.recoveredCount || 0) + Number(s.convertedCount || 0);
+        const attribution = await this.service.attributionSummary(since);
         return {
             windowDays: days,
+            attribution,
             total,
             openCount: Number(s.openCount || 0),
             recoveredCount: Number(s.recoveredCount || 0),
@@ -173,6 +205,60 @@ let AbandonedCartController = class AbandonedCartController {
         }
         res.end();
     }
+    /**
+     * Email opt-out. Public, token-bound (`e=` is an HMAC of the address —
+     * see `buildOptOutToken`). GET renders a tiny confirmation page for
+     * humans clicking the footer link; POST is the RFC 8058 one-click form
+     * mail clients send when the user hits their native "Unsubscribe".
+     * Both are idempotent.
+     */
+    async optOutGet(req, res, tokenRaw) {
+        if (this.rateLimited(req, res, 'opt-out', 6))
+            return;
+        const result = await this.applyOptOut(req, tokenRaw);
+        res.setHeader('cache-control', 'no-store');
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.status(result.ok ? 200 : 400).send(this.optOutPage(result.ok));
+    }
+    async optOutPost(req, res, tokenRaw, body) {
+        if (this.rateLimited(req, res, 'opt-out', 6))
+            return;
+        const token = tokenRaw || (body === null || body === void 0 ? void 0 : body.e) || (typeof body === 'string' ? '' : undefined);
+        const result = await this.applyOptOut(req, token);
+        res.setHeader('cache-control', 'no-store');
+        res.status(result.ok ? 200 : 400).json(result);
+    }
+    async applyOptOut(req, tokenRaw) {
+        const secret = this.service.getOptOutSecret();
+        if (!secret)
+            return { ok: false, error: 'opt-out-disabled' };
+        const email = (0, recovery_tokens_1.verifyOptOutToken)(tokenRaw, secret);
+        if (!email)
+            return { ok: false, error: 'invalid-token' };
+        await this.service.optOut(email, { source: 'link', ip: (0, proxy_headers_1.getRealIp)(req) });
+        return { ok: true };
+    }
+    optOutPage(ok) {
+        const title = ok ? 'You have been unsubscribed' : 'This link is not valid';
+        const body = ok
+            ? 'We will not send you any more reminders about items left in your basket. You can close this page.'
+            : 'The unsubscribe link is incomplete or has been altered. Please use the link exactly as it appears in the email.';
+        return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">`
+            + `<meta name="robots" content="noindex"><title>${title}</title>`
+            + `<style>body{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#f6f7f9;color:#1b1f24;margin:0;display:flex;min-height:100vh;align-items:center;justify-content:center}`
+            + `main{background:#fff;border:1px solid #e3e6ea;border-radius:12px;padding:32px 36px;max-width:440px;box-shadow:0 2px 12px rgba(0,0,0,.05)}h1{font-size:20px;margin:0 0 12px}p{margin:0;line-height:1.5;color:#4b5563}</style>`
+            + `</head><body><main><h1>${title}</h1><p>${body}</p></main></body></html>`;
+    }
+    async listOptOuts(ctx, takeRaw, skipRaw) {
+        const take = Math.min(Math.max(1, parseInt(takeRaw || '50', 10) || 50), 500);
+        const skip = Math.max(0, parseInt(skipRaw || '0', 10) || 0);
+        const { items, total } = await this.service.listOptOuts(take, skip);
+        return { items, total, take, skip };
+    }
+    async removeOptOut(ctx, body) {
+        const ok = await this.service.optIn(String((body === null || body === void 0 ? void 0 : body.email) || ''));
+        return ok ? { ok: true } : { error: 'not-found' };
+    }
     async detail(ctx, idRaw) {
         const id = parseInt(idRaw, 10);
         const conn = this.service.connection.rawConnection;
@@ -191,10 +277,12 @@ let AbandonedCartController = class AbandonedCartController {
         // before the product had a translation, or third-party
         // integrations that fire cart_snapshot without a name field.
         const enrichedItems = await this.enrichItemsWithNames(items);
+        const optedOut = r.email ? await this.service.isOptedOut(r.email) : false;
         return {
             ...r,
             items: enrichedItems,
             itemsPreview: this.buildItemsPreview(enrichedItems),
+            optedOut,
         };
     }
     /**
@@ -279,9 +367,12 @@ let AbandonedCartController = class AbandonedCartController {
             return it;
         });
     }
-    async issueRecoveryLink(ctx, idRaw) {
+    async issueRecoveryLink(ctx, idRaw, body) {
         const id = parseInt(idRaw, 10);
-        const url = await this.service.issueRecoveryLink(id);
+        const options = body && body.resumeOrderCode !== undefined
+            ? { resumeOrderCode: body.resumeOrderCode === null ? null : (0, recovery_tokens_1.sanitiseOrderCode)(body.resumeOrderCode) || null }
+            : {};
+        const url = await this.service.issueRecoveryLink(id, options);
         if (!url)
             return { error: 'recovery-disabled-or-not-found', hint: 'Set abandonment.recoveryLinkSecret in plugin options' };
         return { ok: true, url };
@@ -300,14 +391,64 @@ let AbandonedCartController = class AbandonedCartController {
      * of cart items the storefront can restore. Rate-limited by the
      * plugin's usual ingest limiter (same origin as the tracker).
      */
-    async recover(req, token) {
+    async recover(req, res, token) {
+        if (this.rateLimited(req, res, 'recover', 2))
+            return;
+        res.setHeader('cache-control', 'no-store');
         const t = String(token || '').trim();
-        if (!t)
-            return { error: 'missing-token' };
+        if (!t) {
+            res.status(400).json({ error: 'missing-token' });
+            return;
+        }
         const result = await this.service.findByRecoveryToken(t);
-        if (!result)
-            return { error: 'expired-or-invalid' };
-        return { ok: true, ...result };
+        if (!result) {
+            res.json({ error: 'expired-or-invalid' });
+            return;
+        }
+        res.json({ ok: true, ...result });
+    }
+    /**
+     * Resume the exact order the link was bound to. Same payload as
+     * `recover-cart` plus `resumeOrderCode` — non-null only while that
+     * order is still `AddingItems` / `ArrangingPayment`. The storefront
+     * cannot adopt an order anonymously through the Shop API, so it
+     * should treat `resumeOrderCode` as a hint (e.g. sign-in prompt for
+     * the owner, or "your order S2BZ… is waiting") and fall back to
+     * re-adding `items` — which always works.
+     */
+    async resume(req, res, tokenQ, body) {
+        if (this.rateLimited(req, res, 'recover', 2))
+            return;
+        res.setHeader('cache-control', 'no-store');
+        const t = String(tokenQ || (body === null || body === void 0 ? void 0 : body.t) || '').trim();
+        if (!t) {
+            res.status(400).json({ error: 'missing-token' });
+            return;
+        }
+        const result = await this.service.resumeByRecoveryToken(t);
+        if (!result) {
+            res.json({ error: 'expired-or-invalid' });
+            return;
+        }
+        res.json({ ok: true, ...result });
+    }
+    /**
+     * Attribution — the restored cart checked out. Token-bound, so a
+     * stranger cannot mark carts converted; the order must exist and be
+     * past `AddingItems`. Idempotent.
+     */
+    async converted(req, res, tokenQ, body) {
+        if (this.rateLimited(req, res, 'converted', 6))
+            return;
+        res.setHeader('cache-control', 'no-store');
+        const t = String(tokenQ || (body === null || body === void 0 ? void 0 : body.t) || '').trim();
+        const orderCode = (0, recovery_tokens_1.sanitiseOrderCode)(body === null || body === void 0 ? void 0 : body.orderCode);
+        if (!t || !orderCode) {
+            res.status(400).json({ error: 'missing-token-or-order-code' });
+            return;
+        }
+        const result = await this.service.markConvertedByToken(t, orderCode);
+        res.status(result.ok ? 200 : 400).json(result);
     }
 };
 exports.AbandonedCartController = AbandonedCartController;
@@ -343,6 +484,44 @@ __decorate([
     __metadata("design:paramtypes", [core_1.RequestContext, Object, String]),
     __metadata("design:returntype", Promise)
 ], AbandonedCartController.prototype, "exportCsv", null);
+__decorate([
+    (0, common_1.Get)('abandoned-carts/opt-out'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __param(2, (0, common_1.Query)('e')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, String]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "optOutGet", null);
+__decorate([
+    (0, common_1.Post)('abandoned-carts/opt-out'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __param(2, (0, common_1.Query)('e')),
+    __param(3, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "optOutPost", null);
+__decorate([
+    (0, common_1.Get)('abandoned-carts/opt-outs'),
+    (0, core_1.Allow)(core_1.Permission.ReadCustomer),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Query)('take')),
+    __param(2, (0, common_1.Query)('skip')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, String, String]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "listOptOuts", null);
+__decorate([
+    (0, common_1.Post)('abandoned-carts/opt-outs/remove'),
+    (0, core_1.Allow)(core_1.Permission.UpdateCustomer),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, Object]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "removeOptOut", null);
 __decorate([
     (0, common_1.Get)('abandoned-carts/:id'),
     (0, core_1.Allow)(core_1.Permission.ReadCustomer),
@@ -357,8 +536,9 @@ __decorate([
     (0, core_1.Allow)(core_1.Permission.UpdateCustomer),
     __param(0, (0, core_1.Ctx)()),
     __param(1, (0, common_1.Param)('id')),
+    __param(2, (0, common_1.Body)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [core_1.RequestContext, String]),
+    __metadata("design:paramtypes", [core_1.RequestContext, String, Object]),
     __metadata("design:returntype", Promise)
 ], AbandonedCartController.prototype, "issueRecoveryLink", null);
 __decorate([
@@ -374,11 +554,32 @@ __decorate([
 __decorate([
     (0, common_1.Get)('recover-cart'),
     __param(0, (0, common_1.Req)()),
-    __param(1, (0, common_1.Query)('t')),
+    __param(1, (0, common_1.Res)()),
+    __param(2, (0, common_1.Query)('t')),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:paramtypes", [Object, Object, String]),
     __metadata("design:returntype", Promise)
 ], AbandonedCartController.prototype, "recover", null);
+__decorate([
+    (0, common_1.Post)('recover-cart/resume'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __param(2, (0, common_1.Query)('t')),
+    __param(3, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "resume", null);
+__decorate([
+    (0, common_1.Post)('recover-cart/converted'),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __param(2, (0, common_1.Query)('t')),
+    __param(3, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], AbandonedCartController.prototype, "converted", null);
 exports.AbandonedCartController = AbandonedCartController = __decorate([
     (0, common_1.Controller)('ees'),
     __metadata("design:paramtypes", [abandoned_cart_service_1.AbandonedCartService])