@autobusal/providers 1.23.0 → 1.26.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.26.0
+
+### Added
+
+- `FoundData.arrival_offset` — whole days between boarding and arriving, for
+  the overnight marker on result cards. Optional: external-provider offers do
+  not report one, and a missing value must read as same-day rather than
+  invent a day.
+
+## 1.25.0
+
+### Added
+
+- `LabelSettings.whatsapp.alert_template_name` / `alert_template_language` —
+  the separate approved template the route+date broadcast composer sends
+  through. Optional: a brand can confirm purchases over WhatsApp without ever
+  broadcasting, and Meta approves a template for a stated purpose, so service
+  alerts cannot reuse the confirmation one.
+
+## 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.26.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"

package/types/routes.ts

@@ -146,6 +146,19 @@ export interface FoundData extends Omit<RouteData, 'locations' | 'id'> {
   // another timezone, and "leaves in 20 minutes" must not be wrong.
   departs_in?: number | null
 
+  /**
+   * Edited: Ferjolt Ozuni - Date: 2026-08-05
+   * Whole days between boarding and arriving - 0 for a trip that arrives the
+   * same day, 1 for one arriving the next morning. Counted server-side from
+   * the timetable's own midnight markers, never guessed from the two clock
+   * times: a coach leaving 23:00 and arriving 07:00 is indistinguishable
+   * from one running backwards unless the timetable says which.
+   *
+   * Optional because external-provider offers do not report one; the card
+   * must read a missing value as same-day rather than invent a day.
+   */
+  arrival_offset?: number
+
   // The operator's subscription priority, as obtapi already sends it.
   // Used only as a tiebreak in the "recommended" ordering - see
   // routes-order's Found/refine.ts. Absent on external-provider offers.

package/types/settings.ts

@@ -217,6 +217,16 @@ export interface LabelSettings {
     access_token?: string
     template_name?: string
     template_language?: string
+
+    /**
+     * Edited: Ferjolt Ozuni - Date: 2026-08-05
+     * The separate approved template used by the route+date broadcast
+     * composer. Optional: a brand can confirm purchases without ever
+     * broadcasting, and Meta approves a template for a stated purpose, so
+     * service alerts cannot reuse the confirmation one.
+     */
+    alert_template_name?: string
+    alert_template_language?: string
     display_phone?: string
   }