@luigisbox/luma 0.3.0 → 0.4.0

package/README.md

@@ -10,9 +10,9 @@ This package is what an integration is built with. Each integration lives in
 its own repository and depends on `@luigisbox/luma`
 ([Integration repository](#integration-repository)).
 
-> **Pre-release.** Until 1.0, a minor version (0.4.0) may change the
+> **Pre-release.** Until 1.0, a minor version (0.5.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.3.1) only fixes. Depend on `^0.3.0` to take fixes without breaking
+> (0.4.1) only fixes. Depend on `^0.4.0` to take fixes without breaking
 > changes.
 
 ## Core principles
@@ -405,8 +405,8 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 | Event | What `.read()` returns |
 |---|---|
 | `pageView` | the page's reference, or `null` for a page without one. On `lumaPages()`, one pageview per page, sent at once. On any other trigger, one per page that waits for its reference from that trigger (`.timeout(ms)`, default 1000 ms) and is sent without one after that. One `pageView` line per file |
-| `click` | a product click: a reference, or `{ reference }` |
-| `addToCart` | `{ reference, count?, price? }`, or a list of them |
+| `click` | a product click: a reference, or `{ reference, attributedToList? }` |
+| `addToCart` | `{ reference, count?, price?, attributedToList? }`, or a list of them |
 | `purchase` | `{ id?, currency?, items: [{ reference, title, count, total_price, was_discounted? }] }`; sent once per `id`, so a reloaded thank-you page does not count twice |
 | `search`, `autocomplete`, `recommender(name)` | a list from the site's own service: `{ query?, items, filters? }`. Not sent on a page where Luma runs that service itself (the API records Luma's own results) |
 
@@ -428,12 +428,26 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 
 | Reader | Reads |
 |---|---|
-| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id` |
-| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount` |
+| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id`. Clicks and add-to-carts are in a list (`attributedToList: true`) |
+| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount`. `select_item` is a pick from a list (`attributedToList: true`); `add_to_cart` is not |
 
 Each reader belongs to one event: `collect.purchase…read(fromGa4.addToCart)`
 is a type error, and throws when the file runs.
 
+**Clicks and add-to-carts in a list.** Luigi's Box credits a click or an
+add-to-cart to the last search, suggestions, recommendation or listing the
+shopper saw the product in only when the event says it happened in a list:
+`attributedToList: true` from `.read()`, sent as `attributed_to_list: true`.
+A click without it (a bare reference) counts for the product, never for a
+list, so a click on a product page's own link is not credited to a search the
+shopper made earlier. Luma's own tiles always say it (`fromLuma.click`,
+`fromLuma.addToCart`, autocomplete picks included), and so does GA4's
+`select_item` (`fromGa4.click`). A click on the site's own list, read with a
+function of yours, says it when the element is one of that list's results:
+return `{ reference, attributedToList: true }` (below). The list itself must
+be known too: Luma's own results are; the site's own are when the setup
+collects them (`collect.search`, `.autocomplete`, `.recommender(name)`).
+
 **References** follow `<type>/<field>:<value>`
 ([docs](https://docs.luigisbox.ai/analytics/references/)).
 `ref.product(value)` uses the field set by `ref.product.by(field)` (default
@@ -473,8 +487,8 @@ collect.search.on(mutationOf('#results')).once().read(({ element }) => ({
   query: { string: new URLSearchParams(location.search).get('q') ?? '' },
   items: [...element.querySelectorAll('[data-sku]')].map((tile, n) => ({ title: tile.textContent ?? '', type: 'product', reference: ref.product(tile.getAttribute('data-sku')!), position: n + 1 })),
 }));
-// clicks on those results
-collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!));
+// clicks on those results: in that list
+collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ({ reference: ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!), attributedToList: true }));
 // the site's suggestions, from its own API
 collect.autocomplete.on(xhrMatching(({ url }) => url.includes('/suggest'))).read(({ response }) => ({ items: /* … */ [] }));
 // the product page's product, from GA4's view_item

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Luma: Luigi's Box frontend integrations (autocomplete, search, category listings, recommenders) on the Luigi's Box AI API. Pre-release.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/analytics/chain.ts

@@ -26,6 +26,14 @@ export interface AddToCart {
   reference: string;
   count?: number;
   price?: number;
+  /** Added in a list (a tile's cart button): the platform credits it to that list. */
+  attributedToList?: boolean;
+}
+/** One click: what `collect.click` sends (a bare reference: not in a list). */
+export interface Click {
+  reference: string;
+  /** Picked in a list (a search, suggestions, a recommender, a listing): the platform credits it to that list. */
+  attributedToList?: boolean;
 }
 /** A purchase: what `collect.purchase` sends, once per `id`. */
 export interface Purchase {
@@ -42,7 +50,7 @@ export interface List {
 /** What `.read()` returns, per event (null or undefined: nothing sent). */
 export interface Reads {
   pageView: string | null | undefined;
-  click: string | { reference: string };
+  click: string | Click;
   addToCart: AddToCart | AddToCart[];
   purchase: Purchase;
   search: List;

package/src/analytics/collect.ts

@@ -3,9 +3,13 @@
 // - pageView: `pv` per page (./pageview.ts);
 // - search, autocomplete, recommender(name): a `list` event of the site's own
 //   service (`{ query?, items, filters? }`; ours the API records itself);
-// - click: an `interaction` click (a reference, or `{ reference }`);
-// - addToCart: `interaction` add_to_cart per item (`{ reference, count?, price? }` or a list);
+// - click: an `interaction` click (a reference, or `{ reference, attributedToList? }`);
+// - addToCart: `interaction` add_to_cart per item (`{ reference, count?, price?, attributedToList? }` or a list);
 // - purchase: a `transaction` (`{ id?, currency?, items }`), once per id.
+// `attributedToList`: the product was picked in a list (a search, suggestions,
+// a recommender, a listing): sent as `attributed_to_list: true`, the only
+// interactions the platform credits to the last list in the session that
+// held the product. Without it the interaction counts for the product alone.
 
 import { emit } from './outbox';
 import { state } from './setup';
@@ -26,24 +30,27 @@ export const autocomplete = /* @__PURE__ */ surface<'autocomplete'>('autocomplet
 /** The site's own recommender `name` (silent where ours of that name runs): a `list` event. */
 export const recommender = (name: string) => surface<'recommender'>(`recommender:${name}`, list('Recommendation'));
 
-/** A product click: the reference (or `{ reference }`). */
+/** `attributed_to_list: true` where the product was picked in a list (only then: absent is false). */
+const inList = (x: { attributedToList?: boolean } | undefined) => (x?.attributedToList === true ? { attributed_to_list: true } : {});
+
+/** A product click: the reference (or `{ reference, attributedToList? }`). */
 export const click = /* @__PURE__ */ surface<'click'>('click', (p) => {
-  const reference = typeof p === 'string' ? p : p?.reference;
-  if (isRef(reference)) emit({ type: 'interaction', interaction_type: 'click', listing_ab_test: false, reference });
+  const o = typeof p === 'string' ? { reference: p } : p;
+  if (isRef(o?.reference)) emit({ type: 'interaction', interaction_type: 'click', listing_ab_test: false, reference: o.reference, ...inList(o) });
 });
 
 const currency = () => state.g?.currency;
 /** When the last add-to-cart on our tiles was: the site's own push its cart then makes is the same one. */
 let ourCart = 0;
 const OUR_CART_MS = 10_000;
-/** Add-to-cart: `{ reference, count?, price? }` or a list of them. */
+/** Add-to-cart: `{ reference, count?, price?, attributedToList? }` or a list of them. */
 export const addToCart = /* @__PURE__ */ surface<'addToCart'>('addToCart', (p) => {
   const all: (AddToCart & { [OURS]?: true })[] = Array.isArray(p) ? p : [p];
   if (all.some((x) => x?.[OURS])) ourCart = Date.now();
   else if (Date.now() - ourCart < OUR_CART_MS) return void (ourCart = 0);
   for (const x of all) {
     if (!isRef(x?.reference)) continue;
-    emit({ type: 'interaction', interaction_type: 'add_to_cart', listing_ab_test: false, reference: x.reference, ...(x.count ? { count: x.count } : {}), ...(x.price != null && x.price >= 0 ? { price: x.price } : {}), ...(currency() ? { currency: currency() } : {}) });
+    emit({ type: 'interaction', interaction_type: 'add_to_cart', listing_ab_test: false, reference: x.reference, ...(x.count ? { count: x.count } : {}), ...(x.price != null && x.price >= 0 ? { price: x.price } : {}), ...(currency() ? { currency: currency() } : {}), ...inList(x) });
   }
 });
 

package/src/analytics/from-ga4.ts

@@ -56,8 +56,11 @@ export const purchase = /* @__PURE__ */ reader('purchase', (ctx: Ctx) => {
   });
   return items.length ? { id: e.transaction_id, currency: e.currency, items } : null;
 });
-/** select_item: the product clicked. */
-export const click = /* @__PURE__ */ reader('click', first);
+/** select_item (GA4: an item picked from a list): the product clicked, in its list. */
+export const click = /* @__PURE__ */ reader('click', (ctx: Ctx) => {
+  const reference = first(ctx);
+  return reference ? { reference, attributedToList: true } : null;
+});
 /** view_item: the page's product. */
 export const pageView = /* @__PURE__ */ reader('pageView', first);
 /** view_item_list of their search: its items, the query from search_term. */

package/src/analytics/from-luma.ts

@@ -6,7 +6,9 @@
 //   collect.addToCart.on(lumaCarts()).read(fromLuma.addToCart);
 //
 // Our tiles' references are their results' `@id`s (every result has one),
-// whatever ref.product.by() says for the site's own data.
+// whatever ref.product.by() says for the site's own data. Every tile of ours
+// is in a list (a search, suggestions, a recommender, a listing): its clicks
+// and add-to-carts are attributed to it.
 
 import type { TileEvent } from '../core/tiles';
 import { reader } from './chain';
@@ -15,7 +17,7 @@ import type { Page } from './page';
 
 /** A page: no reference of its own. */
 export const pageView = /* @__PURE__ */ reader('pageView', (_: Page) => null);
-/** A click on one of our tiles: the product clicked. */
-export const click = /* @__PURE__ */ reader('click', (t: TileEvent) => t.reference);
+/** A click on one of our tiles: the product clicked, in its list. */
+export const click = /* @__PURE__ */ reader('click', (t: TileEvent) => ({ reference: t.reference, attributedToList: true }));
 /** `[data-lbx-cart]` on one of our tiles: the product, its quantity and price (the site's own push its cart then makes is the same one). */
-export const addToCart = /* @__PURE__ */ reader('addToCart', (t: TileEvent) => ({ reference: t.reference, count: t.count ?? 1, ...(t.price != null ? { price: t.price } : {}), [OURS]: true as const }));
+export const addToCart = /* @__PURE__ */ reader('addToCart', (t: TileEvent) => ({ reference: t.reference, count: t.count ?? 1, ...(t.price != null ? { price: t.price } : {}), attributedToList: true, [OURS]: true as const }));

package/src/analytics/index.ts

@@ -19,6 +19,6 @@ export { user } from './user';
 export { ref } from './ref';
 export { dl, domClick, lumaCarts, lumaClicks, lumaPages, manual, mutationOf, urlChange, xhrMatching } from './triggers';
 export type { DlContext, DomClickContext, ManualContext, MutationContext, UrlChangeContext, XhrContext } from './triggers';
-export type { AddToCart, List, Purchase, Read, Trigger } from './chain';
+export type { AddToCart, Click, List, Purchase, Read, Trigger } from './chain';
 export type { Page } from './page';
 export type { TileEvent } from '../core/tiles';

package/src/core/early-rules.ts

@@ -35,9 +35,22 @@ export interface EarlyRoute {
 const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // reserveSelector: set by loadConfig (default: the first anchor).
 
-/** Only what the snippet can express: a path regex and a query param (no custom readQuery/active). */
-export const searchRule = (c: SearchConfigType, hostCss: string): EarlyRoute | null =>
-  c.urlMatch && c.queryParam && !c.readQuery && !c.active ? { id: 'search', path: c.urlMatch, need: [c.queryParam], css: holdCss(hostCss, c.reserveSelector!) } : null;
+/** Capture groups in a regex source (its alternation with the empty string always matches). */
+const groups = (re: string) => new RegExp(`${re}|`).exec('')!.length - 1;
+
+/**
+ * Only what the snippet can express (no custom readQuery/active): a path
+ * regex and a query param, or a path regex whose capture group 1 is the query
+ * (/search/<q>/). The snippet cannot check that capture (the bundle decodes
+ * and trims it), so it also holds a blank one (/search/+/); the bundle
+ * rejects that URL and drops the unclaimed hold at boot, as for plpRule's `active`.
+ */
+export const searchRule = (c: SearchConfigType, hostCss: string): EarlyRoute | null => {
+  if (!c.urlMatch || c.readQuery || c.active) return null;
+  const css = holdCss(hostCss, c.reserveSelector!);
+  if (c.queryParam) return { id: 'search', path: c.urlMatch, need: [c.queryParam], css };
+  return groups(c.urlMatch) ? { id: 'search', path: c.urlMatch, css } : null;
+};
 
 /**
  * Param names the category route can express (values are checked by the bundle).