@autobusal/providers 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.24.0
+
+**New `Setup/commerce.ts` — the booking funnel, pushed to the dataLayer.**
+
+`analytics.ts` already loaded the container and announced page views; this is what makes those page views mean something. Until now the funnel was unmeasurable for a more basic reason than missing events — every step of the wizard shared one URL, so no tool could tell a search from a checkout.
+
+Uses **GA4's own event names** (`view_item_list`, `select_item`, `begin_checkout`, `add_to_cart`, `remove_from_cart`, `purchase`) so a container wires them by picking from a list rather than needing a custom mapping per brand.
+
+`purchase` is the hard one and the reason this is a module rather than a few inline pushes: a card payment leaves the site entirely and returns on a URL carrying nothing but an order hash, and most buyers are guests with no account to read the order back from. So `stash()` remembers the value at order time and `flush()` announces it on return — clearing as it fires, and checking the hash, so neither a refresh nor a stale entry from an abandoned attempt can report a sale.
+
+Each push clears `ecommerce` first; GTM's dataLayer is cumulative, and without that a later event inherits the previous one's items.
+
 ## 1.23.0
 
 - `CountryData.timezone` — the IANA zone, so the date picker can floor itself on the departure city's date rather than ours or the buyer's. Carried on `/api/cities/browse`, which the search form already loads.

package/Setup/commerce.ts

@@ -0,0 +1,138 @@
+/**
+ * The booking funnel, pushed to the dataLayer.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-05
+ *
+ * `analytics.ts` loads the container and announces page views; this is what
+ * makes those page views mean something. Until now the funnel was
+ * unmeasurable for a more basic reason than missing events - every step of
+ * the wizard shared one URL, so no tool could tell a search from a checkout.
+ * That is fixed; this is the other half.
+ *
+ * GA4'S OWN EVENT NAMES, deliberately. `view_item_list`, `select_item`,
+ * `begin_checkout`, `add_to_cart` and `purchase` are wired in GTM by
+ * choosing them from a list; anything invented here would need a custom
+ * mapping in every brand's container, and nothing in this codebase should
+ * know which tags a brand runs.
+ *
+ * PURCHASE IS THE HARD ONE, and the reason this file exists rather than a
+ * few inline pushes. A card payment leaves the site entirely and comes back
+ * on a URL carrying nothing but an order hash, and most buyers are guests
+ * with no account to look the order up with. So the value is stashed when
+ * the order is placed and flushed when the buyer returns - see stash() and
+ * flush() below.
+ */
+
+const push = (payload: Record<string, unknown>): void => {
+  window.dataLayer = window.dataLayer || [];
+
+  // Clear the previous event's ecommerce object first. GTM's dataLayer is
+  // cumulative, so without this a later event inherits whatever items the
+  // last one left behind - the classic double-counted purchase.
+  window.dataLayer.push({ ecommerce: null });
+  window.dataLayer.push(payload);
+};
+
+export interface CommerceItem {
+  item_id: string
+  item_name: string
+  item_brand?: string
+  price?: number
+  quantity?: number
+}
+
+/** Search results were shown. */
+export const viewItemList = (items: CommerceItem[], currency?: string): void => {
+  if (items.length === 0) {
+    return;
+  }
+
+  push({ event: 'view_item_list', ecommerce: { currency, items } });
+};
+
+/** One coach was chosen from the results. */
+export const selectItem = (item: CommerceItem, currency?: string): void => {
+  push({ event: 'select_item', ecommerce: { currency, items: [item] } });
+};
+
+/** The buyer reached the passenger-details and payment screen. */
+export const beginCheckout = (value: number, items: CommerceItem[], currency?: string): void => {
+  push({ event: 'begin_checkout', ecommerce: { currency, value, items } });
+};
+
+/**
+ * A paid add-on was ticked or unticked.
+ *
+ * The attach rate this measures is the single input the Flexible Ticket
+ * pricing decision is waiting on - it cannot be banded by window without
+ * knowing how often each window is actually bought.
+ */
+export const addon = (added: boolean, name: string, price: number, currency?: string): void => {
+  push({
+    event: added ? 'add_to_cart' : 'remove_from_cart',
+    ecommerce: {
+      currency,
+      value: price,
+      items: [{ item_id: name, item_name: name, price, quantity: 1 }]
+    }
+  });
+};
+
+const KEY = 'commerce.purchase';
+
+/**
+ * Remember what an order was worth, against its hash.
+ *
+ * sessionStorage rather than a variable: a card payment navigates away to
+ * the bank and back, so anything held in memory is gone by the time the
+ * buyer returns. Same origin either side, so the value survives.
+ */
+export const stash = (hash: string, value: number, items: CommerceItem[], currency?: string): void => {
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify({ hash, value, items, currency }));
+  } catch {
+    // storage disabled or full - measurement is never worth breaking a sale
+  }
+};
+
+/**
+ * Announce a completed purchase, once.
+ *
+ * CLEARED AS IT FIRES. The confirmation page is a plain URL a buyer can
+ * refresh, bookmark or reach twice from their history, and each of those
+ * would otherwise report another sale. The hash is checked too, so a stale
+ * entry from an abandoned attempt cannot be attributed to a later order.
+ */
+export const flush = (hash: string): void => {
+  let stored: { hash?: string, value?: number, items?: CommerceItem[], currency?: string } | null = null;
+
+  try {
+    const raw = sessionStorage.getItem(KEY);
+
+    stored = raw ? JSON.parse(raw) : null;
+  } catch {
+    stored = null;
+  }
+
+  if (!stored || stored.hash !== hash) {
+    return;
+  }
+
+  try {
+    sessionStorage.removeItem(KEY);
+  } catch {
+    // if it cannot be cleared, do not fire - a repeatable purchase event is
+    // worse than a missing one
+    return;
+  }
+
+  push({
+    event: 'purchase',
+    ecommerce: {
+      transaction_id: hash,
+      currency: stored.currency,
+      value: stored.value,
+      items: stored.items ?? []
+    }
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/providers",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"