@buildinams/core 0.3.1 → 0.4.0

package/README.md

@@ -1,7 +1,30 @@
 # `@buildinams/core`
 
-# Install
+Framework-agnostic utilities used by `@buildinams/react`.
+
+| Import                               | Contents                                                   |
+| ------------------------------------ | ---------------------------------------------------------- |
+| `@buildinams/core`                   | Utility functions, type guards, shared types.              |
+| `@buildinams/core/analytics`         | Typed, consent-aware analytics events.                     |
+| `@buildinams/core/analytics/google`  | GTM dataLayer destination and GA4 mapping.                 |
+| `@buildinams/core/analytics/shopify` | Shopify Analytics destination, through Hydrogen.           |
+| `@buildinams/core/consent`           | Consent categories, `ConsentSource` and `ConsentTarget`.   |
+| `@buildinams/core/consent/cookiebot` | Consent from Cookiebot.                                    |
+| `@buildinams/core/consent/onetrust`  | Consent from OneTrust.                                     |
+| `@buildinams/core/consent/google`    | Google Consent Mode consent target.                        |
+| `@buildinams/core/consent/shopify`   | Consent from, and to, Shopify's Customer Privacy API.      |
+| `@buildinams/core/store`             | Observable stores and store groups.                        |
+| `@buildinams/core/tracking/dom`      | Tracking from markup: `createDomWatcher()` and plugins.    |
+| `@buildinams/core/tracking/cart`     | Adds and removes from cart changes: `createCartChanges()`. |
+| `@buildinams/core/schema`            | Parse/serialize schemas, incl. `hrefSchema`.               |
+| `@buildinams/core/navigation`        | Deprecated: use `@buildinams/core/schema`.                 |
 
 ```bash
 npm install @buildinams/core
 ```
+
+# Docs
+
+- [Analytics](./docs/analytics.md): one `track()` typed by the project's own events, mapped to every provider and gated by consent (`@buildinams/core/analytics`, `@buildinams/core/consent`)
+- [Tracking](./docs/tracking.md): page views, products, clicks and cart changes reported from markup and confirmed carts (`@buildinams/core/tracking/dom`, `@buildinams/core/tracking/cart`)
+- [Cookies](./docs/cookies.md): typesafe cookies across Next.js server and client (`@buildinams/core/cookies`)

package/dist/analytics/google/index.d.ts

@@ -0,0 +1,158 @@
+import { E as EventMap, j as EcommerceShapes, h as AnalyticsContext, k as ShapesOf, C as CartItemOf } from '../../define-events-CxZjoUlG.js';
+import { a as AnalyticsMapping, A as AnalyticsDestination, D as DestinationEvent } from '../../destination-5KJ5PeR3.js';
+import '../../index-Zef1nnTP.js';
+
+declare const ECOMMERCE_EVENTS: readonly ["view_item_list", "select_item", "view_item", "add_to_wishlist", "add_to_cart", "remove_from_cart", "view_cart", "begin_checkout", "add_shipping_info", "add_payment_info", "purchase", "refund", "view_promotion", "select_promotion"];
+declare const EVENTS: readonly ["search", "select_content", "share", "login", "sign_up", "generate_lead", "click", "video_start", "video_progress", "video_complete", "form_start", "form_submit", "scroll"];
+type Ga4Params = Record<string, unknown>;
+/** @see https://developers.google.com/analytics/devguides/collection/ga4/reference/events#add_to_cart_item */
+type Ga4Item = {
+    item_id?: string;
+    item_name?: string;
+    affiliation?: string;
+    coupon?: string;
+    discount?: number;
+    index?: number;
+    item_brand?: string;
+    item_category?: string;
+    item_category2?: string;
+    item_category3?: string;
+    item_category4?: string;
+    item_category5?: string;
+    item_list_id?: string;
+    item_list_name?: string;
+    item_variant?: string;
+    location_id?: string;
+    /** Unit price, after discount. */
+    price?: number;
+    quantity?: number;
+    promotion_id?: string;
+    promotion_name?: string;
+    creative_name?: string;
+    creative_slot?: string;
+} & Ga4Params;
+type Ga4List = {
+    item_list_id?: string;
+    item_list_name?: string;
+};
+type Ga4Promotion = {
+    promotion_id?: string;
+    promotion_name?: string;
+    creative_name?: string;
+    creative_slot?: string;
+};
+/** An ecommerce event's params, pushed under `ecommerce`. */
+type Ga4Ecommerce = {
+    /** ISO 4217, e.g. `"EUR"`. */
+    currency?: string;
+    value?: number;
+    items?: Ga4Item[];
+} & Ga4Params;
+/**
+ * What GTM accepts: GA4's events by name, in GA4's params, and `custom` for any other event name. Each is pushed with
+ * `event_id` and the context variables, e.g. `{ event: "login", event_id, user_id, method }`, and ecommerce events'
+ * params under `ecommerce`.
+ */
+type GtmEvents = {
+    [N in (typeof ECOMMERCE_EVENTS)[number]]: Ga4Ecommerce;
+} & {
+    [N in (typeof EVENTS)[number]]: Ga4Params;
+} & {
+    page_view: {
+        page_location: string;
+        page_path: string;
+        page_title: string;
+        page_referrer: string;
+        page_type?: string;
+    } & Ga4Params;
+    /** Pushed as `{ event, ...params }`. */
+    custom: {
+        event: string;
+        params: Ga4Params;
+    };
+};
+type Ga4MappingOptions<Shapes extends EcommerceShapes, CartItem, Context extends object> = {
+    /** For what `ecommerce()` reports: the project's item as a GA4 item, e.g. `({ product }) => ({ item_id: product.id })`. */
+    item?: (item: Shapes["item"]) => Ga4Item;
+    /** `itemViewed`'s currency, with its price as `value`, e.g. from the item or the context's market. */
+    currency?: (item: Shapes["item"], context: AnalyticsContext<Context>) => string | undefined;
+    list?: (list: Shapes["list"]) => Ga4List;
+    promotion?: (promotion: Shapes["promotion"]) => Ga4Promotion;
+} & ([CartItem] extends [never | Shapes["item"]] ? {
+    /**
+     * For what `createCartChanges()` reports: the project's cart line item as a GA4 item. Price and quantity come
+     * from the line. Defaults to `item`.
+     */
+    cartItem?: (item: CartItem) => Ga4Item;
+} : {
+    item?: undefined;
+    cartItem?: (item: CartItem) => Ga4Item;
+} | {
+    /**
+     * For what `createCartChanges()` reports: the project's cart line item as a GA4 item. Price and quantity
+     * come from the line. Required with `item`, as the cart item isn't one.
+     */
+    cartItem: (item: CartItem) => Ga4Item;
+});
+/**
+ * Maps what tracking reports to GA4's recommended events, e.g. `clicked` to `click`, `itemsViewed` to
+ * `view_item_list` and `addedToCart` to `add_to_cart`: `DomEvents` with their camelCase fields as snake_case params,
+ * `EcommerceEvents` with `item`, `list` and `promotion`, and `CartEvents` with `cartItem`. Events without what they
+ * need, e.g. ecommerce events without `item`, aren't mapped. Spread it to add or override events.
+ *
+ * @example
+ * ```ts
+ * map(gtmDestination(), {
+ *   ...mapEvery(events, toGa4CustomEvent),
+ *   ...ga4Mapping<Events>({
+ *     item: ({ product, variant }) => ({
+ *       item_id: product.id,
+ *       item_name: product.title,
+ *       item_variant: variant?.title,
+ *       price: Number((variant ?? product).price.amount),
+ *     }),
+ *     currency: ({ product }) => product.price.currencyCode,
+ *     list: ({ id, name }) => ({ item_list_id: id, item_list_name: name }),
+ *   }),
+ *   newsletterSignedUp: ({ source }) => ({ name: "generate_lead", payload: { lead_source: source } }),
+ * });
+ * ```
+ */
+declare const ga4Mapping: <Events extends EventMap, Context extends object = Record<never, never>>({ item: toItem, currency, list: toList, promotion: toPromotion, cartItem, }?: Ga4MappingOptions<ShapesOf<Events>, CartItemOf<Events>, Context>) => AnalyticsMapping<Events, GtmEvents, Context>;
+/**
+ * For `mapEvery()`, spread before the other entries: an event without one, e.g. a custom one, under its name and with
+ * its fields in snake_case, e.g. `newsletterSignedUp` as `newsletter_signed_up`. Unmapped ecommerce events aren't sent, as GA4's
+ * tags would read them with the `ecommerce` of an earlier event.
+ */
+declare const toGa4CustomEvent: (event: {
+    name: string;
+    payload: object;
+}) => DestinationEvent<GtmEvents> | null;
+type GtmDestinationOptions = {
+    /** Default `"dataLayer"`. */
+    dataLayerName?: string;
+};
+/**
+ * Pushes events to the GTM dataLayer, with the context as dataLayer variables (`user_data` only with marketing
+ * consent), and ecommerce events' params under `ecommerce`. Map it with `ga4Mapping<Events>()`, and give it
+ * `withConsent(…, "none")` for Google Consent Mode's advanced setup, where Consent Mode gates tags inside the container, or
+ * `["analytics"]` for its basic one. Consent Mode signals come from the consent platform's integration, e.g.
+ * Cookiebot's, or from `googleConsentMode()`. See `docs/analytics.md`.
+ *
+ * @example
+ * ```ts
+ * export const analytics = createAnalytics<Events>({
+ *   events,
+ *   consent: cookiebotConsent(),
+ *   destinations: [
+ *     withConsent(
+ *       map(gtmDestination(), { ...mapEvery(events, toGa4CustomEvent), ...ga4Mapping<Events>({ item: toGa4Item }) }),
+ *       "none",
+ *     ),
+ *   ],
+ * });
+ * ```
+ */
+declare const gtmDestination: ({ dataLayerName, }?: GtmDestinationOptions) => AnalyticsDestination<GtmEvents>;
+
+export { type Ga4Ecommerce, type Ga4Item, type Ga4List, type Ga4Promotion, type GtmDestinationOptions, type GtmEvents, ga4Mapping, gtmDestination, toGa4CustomEvent };

package/dist/analytics/google/index.js

@@ -0,0 +1,274 @@
+import { IS_DEVELOPMENT } from '../../chunk-GQVN2ECX.js';
+
+// src/analytics/google/gtm-destination.ts
+var ECOMMERCE_EVENTS = [
+  "view_item_list",
+  "select_item",
+  "view_item",
+  "add_to_wishlist",
+  "add_to_cart",
+  "remove_from_cart",
+  "view_cart",
+  "begin_checkout",
+  "add_shipping_info",
+  "add_payment_info",
+  "purchase",
+  "refund",
+  "view_promotion",
+  "select_promotion"
+];
+var EVENTS = [
+  "search",
+  "select_content",
+  "share",
+  "login",
+  "sign_up",
+  "generate_lead",
+  "click",
+  "video_start",
+  "video_progress",
+  "video_complete",
+  "form_start",
+  "form_submit",
+  "scroll"
+];
+var ECOMMERCE = new Set(ECOMMERCE_EVENTS);
+var toSnakeCase = (key) => key.replace(/([a-z\d])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toLowerCase();
+var toParams = (input, names = {}) => {
+  const params = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0) continue;
+    params[names[key] ?? toSnakeCase(key)] = value;
+  }
+  return params;
+};
+var USER_PARAM_NAMES = {
+  id: "user_id",
+  type: "user_type"
+};
+var CONTEXT_PARAM_NAMES = { locale: "language" };
+var PAGE_CONTEXT_KEYS = /* @__PURE__ */ new Set(["url", "title", "referrer"]);
+var toContextParams = (context, includeUserData) => {
+  const { user, ...fields } = context;
+  const rest = Object.entries(fields).filter(
+    ([key]) => !PAGE_CONTEXT_KEYS.has(key)
+  );
+  const { email, phone, ...userFields } = user ?? {};
+  const userParams = {};
+  for (const [key, value] of Object.entries(userFields)) {
+    userParams[USER_PARAM_NAMES[key] ?? `user_${toSnakeCase(key)}`] = value;
+  }
+  return {
+    user_id: void 0,
+    user_type: void 0,
+    ...userParams,
+    language: void 0,
+    market: void 0,
+    ...Object.fromEntries(
+      rest.map(([key, value]) => [
+        CONTEXT_PARAM_NAMES[key] ?? toSnakeCase(key),
+        value
+      ])
+    ),
+    user_data: includeUserData && (email || phone) ? toParams({ email, phone_number: phone }, {}) : void 0
+  };
+};
+var toPageView = (payload, context) => {
+  const { url = context.url, title = context.title, pageType } = payload;
+  return {
+    name: "page_view",
+    payload: {
+      page_location: url,
+      page_path: new URL(url, context.url).pathname,
+      page_title: title,
+      page_referrer: context.referrer,
+      // Only on page views, so GTM's data model keeps it for the page's other events.
+      page_type: pageType
+    }
+  };
+};
+var DOM_EVENTS = {
+  clicked: "click",
+  videoStarted: "video_start",
+  videoProgressed: "video_progress",
+  videoCompleted: "video_complete",
+  formStarted: "form_start",
+  formSubmitted: "form_submit",
+  scrolled: "scroll"
+};
+var CART_EVENTS = {
+  addedToCart: "add_to_cart",
+  removedFromCart: "remove_from_cart"
+};
+var TRACKER_ECOMMERCE = new Set(
+  Object.keys({
+    itemViewed: true,
+    itemSelected: true,
+    itemsViewed: true,
+    promotionViewed: true,
+    promotionSelected: true,
+    ...CART_EVENTS
+  })
+);
+var ga4Mapping = ({
+  item: toItem,
+  currency,
+  list: toList = () => ({}),
+  promotion: toPromotion = () => ({}),
+  cartItem
+} = {}) => {
+  const toCartItem = cartItem ?? toItem;
+  const entries = {
+    pageViewed: (payload, { context }) => toPageView(payload, context)
+  };
+  for (const [event, name] of Object.entries(DOM_EVENTS)) {
+    entries[event] = (payload) => ({
+      name,
+      payload: toParams(payload)
+    });
+  }
+  if (toItem) {
+    const toPlacedItem = ({
+      item,
+      list,
+      index,
+      promotion
+    }) => ({
+      ...toItem(item),
+      ...list ? toList(list) : {},
+      ...promotion ? toPromotion(promotion) : {},
+      ...index !== void 0 && { index }
+    });
+    Object.assign(entries, {
+      itemViewed: (placed, { context }) => {
+        const item = toPlacedItem(placed);
+        const itemCurrency = currency?.(placed.item, context);
+        return {
+          name: "view_item",
+          payload: toParams({
+            currency: itemCurrency,
+            value: itemCurrency && item.price !== void 0 ? item.price * (item.quantity ?? 1) : void 0,
+            items: [item]
+          })
+        };
+      },
+      itemSelected: ({ list, ...placed }) => ({
+        name: "select_item",
+        payload: {
+          ...list ? toList(list) : {},
+          items: [toPlacedItem(placed)]
+        }
+      }),
+      itemsViewed: ({ list, items }) => ({
+        name: "view_item_list",
+        payload: {
+          ...list ? toList(list) : {},
+          items: items.map(toPlacedItem)
+        }
+      }),
+      promotionViewed: ({
+        promotion,
+        items
+      }) => ({
+        name: "view_promotion",
+        payload: {
+          ...toPromotion(promotion),
+          ...items.length > 0 && { items: items.map((item) => toItem(item)) }
+        }
+      }),
+      promotionSelected: ({
+        promotion,
+        item
+      }) => ({
+        name: "select_promotion",
+        payload: {
+          ...toPromotion(promotion),
+          ...item ? { items: [toItem(item)] } : {}
+        }
+      })
+    });
+  }
+  if (toCartItem) {
+    for (const [event, name] of Object.entries(CART_EVENTS)) {
+      entries[event] = ({
+        currency: cartCurrency,
+        value,
+        items
+      }) => ({
+        name,
+        payload: {
+          currency: cartCurrency,
+          value,
+          items: items.map(({ item, quantity, price }) => ({
+            ...toCartItem(item),
+            price,
+            quantity
+          }))
+        }
+      });
+    }
+  }
+  return entries;
+};
+var warnedUnmapped = /* @__PURE__ */ new Set();
+var toGa4CustomEvent = (event) => {
+  const name = toSnakeCase(event.name);
+  if (ECOMMERCE.has(name) || TRACKER_ECOMMERCE.has(event.name)) {
+    if (IS_DEVELOPMENT && !warnedUnmapped.has(event.name)) {
+      warnedUnmapped.add(event.name);
+      console.warn(
+        `[analytics] gtm: "${event.name}" isn't mapped. Pass ga4Mapping()'s adapters or map it yourself.`
+      );
+    }
+    return null;
+  }
+  return {
+    name: "custom",
+    payload: { event: name, params: toParams(event.payload) }
+  };
+};
+var gtmDestination = ({
+  dataLayerName = "dataLayer"
+} = {}) => {
+  const dataLayer = () => {
+    const target = window;
+    return target[dataLayerName] ??= [];
+  };
+  const contextKeys = /* @__PURE__ */ new Set();
+  return {
+    name: "gtm",
+    setup: ({ subscribe }) => {
+      const push = (event, params, { id, context, consent }) => {
+        const contextParams = toContextParams(context, !!consent?.marketing);
+        for (const key of contextKeys) {
+          if (!(key in contextParams)) contextParams[key] = void 0;
+        }
+        Object.keys(contextParams).forEach((key) => contextKeys.add(key));
+        if ("ecommerce" in params) dataLayer().push({ ecommerce: null });
+        dataLayer().push({ event, event_id: id, ...contextParams, ...params });
+      };
+      for (const name of [
+        ...ECOMMERCE_EVENTS,
+        ...EVENTS,
+        "page_view"
+      ]) {
+        subscribe(
+          name,
+          (params, context) => push(
+            name,
+            ECOMMERCE.has(name) ? { ecommerce: params } : params,
+            context
+          )
+        );
+      }
+      subscribe(
+        "custom",
+        ({ event, params }, context) => push(event, params, context)
+      );
+    }
+  };
+};
+
+export { ga4Mapping, gtmDestination, toGa4CustomEvent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/analytics/google/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/analytics/google/gtm-destination.ts"],"names":[],"mappings":";;;AAuBA,IAAM,gBAAA,GAAmB;AAAA,EACxB,gBAAA;AAAA,EACA,aAAA;AAAA,EACA,WAAA;AAAA,EACA,iBAAA;AAAA,EACA,aAAA;AAAA,EACA,kBAAA;AAAA,EACA,WAAA;AAAA,EACA,gBAAA;AAAA,EACA,mBAAA;AAAA,EACA,kBAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACD,CAAA;AAEA,IAAM,MAAA,GAAS;AAAA,EACd,QAAA;AAAA,EACA,gBAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,eAAA;AAAA,EACA,OAAA;AAAA,EACA,aAAA;AAAA,EACA,gBAAA;AAAA,EACA,gBAAA;AAAA,EACA,YAAA;AAAA,EACA,aAAA;AAAA,EACA;AACD,CAAA;AAEA,IAAM,SAAA,GAAY,IAAI,GAAA,CAAY,gBAAgB,CAAA;AAsElD,IAAM,WAAA,GAAc,CAAC,GAAA,KACpB,GAAA,CACE,OAAA,CAAQ,mBAAA,EAAqB,OAAO,CAAA,CACpC,OAAA,CAAQ,uBAAA,EAAyB,OAAO,CAAA,CACxC,WAAA,EAAY;AAGf,IAAM,QAAA,GAAW,CAChB,KAAA,EACA,KAAA,GAAgC,EAAC,KACJ;AAC7B,EAAA,MAAM,SAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AACjD,IAAA,IAAI,UAAU,MAAA,EAAW;AACzB,IAAA,MAAA,CAAO,MAAM,GAAG,CAAA,IAAK,WAAA,CAAY,GAAG,CAAC,CAAA,GAAI,KAAA;AAAA,EAC1C;AACA,EAAA,OAAO,MAAA;AACR,CAAA;AAEA,IAAM,gBAAA,GAA2C;AAAA,EAChD,EAAA,EAAI,SAAA;AAAA,EACJ,IAAA,EAAM;AACP,CAAA;AAEA,IAAM,mBAAA,GAA8C,EAAE,MAAA,EAAQ,UAAA,EAAW;AAGzE,IAAM,oCAAoB,IAAI,GAAA,CAAI,CAAC,KAAA,EAAO,OAAA,EAAS,UAAU,CAAC,CAAA;AAMvD,IAAM,eAAA,GAAkB,CAC9B,OAAA,EACA,eAAA,KAC6B;AAC7B,EAAA,MAAM,EAAE,IAAA,EAAM,GAAG,MAAA,EAAO,GAAI,OAAA;AAC5B,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,CAAE,MAAA;AAAA,IACnC,CAAC,CAAC,GAAG,MAAM,CAAC,iBAAA,CAAkB,IAAI,GAAG;AAAA,GACtC;AACA,EAAA,MAAM,EAAE,KAAA,EAAO,KAAA,EAAO,GAAG,UAAA,EAAW,GAAI,QAAQ,EAAC;AACjD,EAAA,MAAM,aAAsC,EAAC;AAC7C,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,UAAU,CAAA,EAAG;AACtD,IAAA,UAAA,CAAW,gBAAA,CAAiB,GAAG,CAAA,IAAK,CAAA,KAAA,EAAQ,YAAY,GAAG,CAAC,EAAE,CAAA,GAAI,KAAA;AAAA,EACnE;AAEA,EAAA,OAAO;AAAA,IACN,OAAA,EAAS,MAAA;AAAA,IACT,SAAA,EAAW,MAAA;AAAA,IACX,GAAG,UAAA;AAAA,IACH,QAAA,EAAU,MAAA;AAAA,IACV,MAAA,EAAQ,MAAA;AAAA,IACR,GAAG,MAAA,CAAO,WAAA;AAAA,MACT,KAAK,GAAA,CAAI,CAAC,CAAC,GAAA,EAAK,KAAK,CAAA,KAAM;AAAA,QAC1B,mBAAA,CAAoB,GAAG,CAAA,IAAK,WAAA,CAAY,GAAG,CAAA;AAAA,QAC3C;AAAA,OACA;AAAA,KACF;AAAA,IACA,SAAA,EACC,eAAA,KAAoB,KAAA,IAAS,KAAA,CAAA,GAC1B,QAAA,CAAS,EAAE,KAAA,EAAO,YAAA,EAAc,KAAA,EAAM,EAAG,EAAE,CAAA,GAC3C;AAAA,GACL;AACD,CAAA;AAoCA,IAAM,UAAA,GAAa,CAClB,OAAA,EACA,OAAA,KACiC;AACjC,EAAA,MAAM,EAAE,MAAM,OAAA,CAAQ,GAAA,EAAK,QAAQ,OAAA,CAAQ,KAAA,EAAO,UAAS,GAAI,OAAA;AAC/D,EAAA,OAAO;AAAA,IACN,IAAA,EAAM,WAAA;AAAA,IACN,OAAA,EAAS;AAAA,MACR,aAAA,EAAe,GAAA;AAAA,MACf,WAAW,IAAI,GAAA,CAAI,GAAA,EAAK,OAAA,CAAQ,GAAG,CAAA,CAAE,QAAA;AAAA,MACrC,UAAA,EAAY,KAAA;AAAA,MACZ,eAAe,OAAA,CAAQ,QAAA;AAAA;AAAA,MAEvB,SAAA,EAAW;AAAA;AACZ,GACD;AACD,CAAA;AAEA,IAAM,UAAA,GAAa;AAAA,EAClB,OAAA,EAAS,OAAA;AAAA,EACT,YAAA,EAAc,aAAA;AAAA,EACd,eAAA,EAAiB,gBAAA;AAAA,EACjB,cAAA,EAAgB,gBAAA;AAAA,EAChB,WAAA,EAAa,YAAA;AAAA,EACb,aAAA,EAAe,aAAA;AAAA,EACf,QAAA,EAAU;AACX,CAAA;AAKA,IAAM,WAAA,GAAc;AAAA,EACnB,WAAA,EAAa,aAAA;AAAA,EACb,eAAA,EAAiB;AAClB,CAAA;AAGA,IAAM,oBAAoB,IAAI,GAAA;AAAA,EAC7B,OAAO,IAAA,CAAK;AAAA,IACX,UAAA,EAAY,IAAA;AAAA,IACZ,YAAA,EAAc,IAAA;AAAA,IACd,WAAA,EAAa,IAAA;AAAA,IACb,eAAA,EAAiB,IAAA;AAAA,IACjB,iBAAA,EAAmB,IAAA;AAAA,IACnB,GAAG;AAAA,GAIH;AACF,CAAA;AA+BO,IAAM,aAAa,CAGxB;AAAA,EACD,IAAA,EAAM,MAAA;AAAA,EACN,QAAA;AAAA,EACA,IAAA,EAAM,MAAA,GAAS,OAAO,EAAC,CAAA;AAAA,EACvB,SAAA,EAAW,WAAA,GAAc,OAAO,EAAC,CAAA;AAAA,EACjC;AACD,CAAA,GAII,EAAC,KAAoD;AAGxD,EAAA,MAAM,aAAc,QAAA,IAAY,MAAA;AAIhC,EAAA,MAAM,OAAA,GAAiC;AAAA,IACtC,UAAA,EAAY,CAAC,OAAA,EAAkC,EAAE,SAAQ,KACxD,UAAA,CAAW,SAAS,OAAO;AAAA,GAC7B;AACA,EAAA,KAAA,MAAW,CAAC,KAAA,EAAO,IAAI,KAAK,MAAA,CAAO,OAAA,CAAQ,UAAU,CAAA,EAAG;AACvD,IAAA,OAAA,CAAQ,KAAK,CAAA,GAAI,CAAC,OAAA,MAAqB;AAAA,MACtC,IAAA;AAAA,MACA,OAAA,EAAS,SAAS,OAAO;AAAA,KAC1B,CAAA;AAAA,EACD;AAEA,EAAA,IAAI,MAAA,EAAQ;AACX,IAAA,MAAM,eAAe,CAAC;AAAA,MACrB,IAAA;AAAA,MACA,IAAA;AAAA,MACA,KAAA;AAAA,MACA;AAAA,KACD,MAAqE;AAAA,MACpE,GAAG,OAAO,IAAI,CAAA;AAAA,MACd,GAAI,IAAA,GAAO,MAAA,CAAO,IAAI,IAAI,EAAC;AAAA,MAC3B,GAAI,SAAA,GAAY,WAAA,CAAY,SAAS,IAAI,EAAC;AAAA,MAC1C,GAAI,KAAA,KAAU,MAAA,IAAa,EAAE,KAAA;AAAM,KACpC,CAAA;AAEA,IAAA,MAAA,CAAO,OAAO,OAAA,EAAS;AAAA,MACtB,UAAA,EAAY,CACX,MAAA,EACA,EAAE,SAAQ,KACN;AACJ,QAAA,MAAM,IAAA,GAAO,aAAa,MAAM,CAAA;AAChC,QAAA,MAAM,YAAA,GAAe,QAAA,GAAW,MAAA,CAAO,IAAA,EAAM,OAAO,CAAA;AACpD,QAAA,OAAO;AAAA,UACN,IAAA,EAAM,WAAA;AAAA,UACN,SAAS,QAAA,CAAS;AAAA,YACjB,QAAA,EAAU,YAAA;AAAA,YACV,KAAA,EACC,gBAAgB,IAAA,CAAK,KAAA,KAAU,SAC5B,IAAA,CAAK,KAAA,IAAS,IAAA,CAAK,QAAA,IAAY,CAAA,CAAA,GAC/B,MAAA;AAAA,YACJ,KAAA,EAAO,CAAC,IAAI;AAAA,WACZ;AAAA,SACF;AAAA,MACD,CAAA;AAAA,MACA,cAAc,CAAC,EAAE,IAAA,EAAM,GAAG,QAAO,MAAkC;AAAA,QAClE,IAAA,EAAM,aAAA;AAAA,QACN,OAAA,EAAS;AAAA,UACR,GAAI,IAAA,GAAO,MAAA,CAAO,IAAI,IAAI,EAAC;AAAA,UAC3B,KAAA,EAAO,CAAC,YAAA,CAAa,MAAM,CAAC;AAAA;AAC7B,OACD,CAAA;AAAA,MACA,WAAA,EAAa,CAAC,EAAE,IAAA,EAAM,OAAM,MAAiC;AAAA,QAC5D,IAAA,EAAM,gBAAA;AAAA,QACN,OAAA,EAAS;AAAA,UACR,GAAI,IAAA,GAAO,MAAA,CAAO,IAAI,IAAI,EAAC;AAAA,UAC3B,KAAA,EAAO,KAAA,CAAM,GAAA,CAAI,YAAY;AAAA;AAC9B,OACD,CAAA;AAAA,MACA,iBAAiB,CAAC;AAAA,QACjB,SAAA;AAAA,QACA;AAAA,OACD,MAAqC;AAAA,QACpC,IAAA,EAAM,gBAAA;AAAA,QACN,OAAA,EAAS;AAAA,UACR,GAAG,YAAY,SAAS,CAAA;AAAA,UACxB,GAAI,KAAA,CAAM,MAAA,GAAS,CAAA,IAAK,EAAE,KAAA,EAAO,KAAA,CAAM,GAAA,CAAI,CAAC,IAAA,KAAS,MAAA,CAAO,IAAI,CAAC,CAAA;AAAE;AACpE,OACD,CAAA;AAAA,MACA,mBAAmB,CAAC;AAAA,QACnB,SAAA;AAAA,QACA;AAAA,OACD,MAAuC;AAAA,QACtC,IAAA,EAAM,kBAAA;AAAA,QACN,OAAA,EAAS;AAAA,UACR,GAAG,YAAY,SAAS,CAAA;AAAA,UACxB,GAAI,IAAA,GAAO,EAAE,KAAA,EAAO,CAAC,OAAO,IAAI,CAAC,CAAA,EAAE,GAAI;AAAC;AACzC,OACD;AAAA,KACyC,CAAA;AAAA,EAC3C;AAEA,EAAA,IAAI,UAAA,EAAY;AACf,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,IAAI,KAAK,MAAA,CAAO,OAAA,CAAQ,WAAW,CAAA,EAAG;AACxD,MAAA,OAAA,CAAQ,KAAK,IAAI,CAAC;AAAA,QACjB,QAAA,EAAU,YAAA;AAAA,QACV,KAAA;AAAA,QACA;AAAA,OACD,MAIO;AAAA,QACN,IAAA;AAAA,QACA,OAAA,EAAS;AAAA,UACR,QAAA,EAAU,YAAA;AAAA,UACV,KAAA;AAAA,UACA,KAAA,EAAO,MAAM,GAAA,CAAI,CAAC,EAAE,IAAA,EAAM,QAAA,EAAU,OAAM,MAAO;AAAA,YAChD,GAAG,WAAW,IAAI,CAAA;AAAA,YAClB,KAAA;AAAA,YACA;AAAA,WACD,CAAE;AAAA;AACH,OACD,CAAA;AAAA,IACD;AAAA,EACD;AAEA,EAAA,OAAO,OAAA;AACR;AAEA,IAAM,cAAA,uBAAqB,GAAA,EAAY;AAOhC,IAAM,gBAAA,GAAmB,CAAC,KAAA,KAGS;AACzC,EAAA,MAAM,IAAA,GAAO,WAAA,CAAY,KAAA,CAAM,IAAI,CAAA;AACnC,EAAA,IAAI,SAAA,CAAU,IAAI,IAAI,CAAA,IAAK,kBAAkB,GAAA,CAAI,KAAA,CAAM,IAAI,CAAA,EAAG;AAC7D,IAAA,IAAI,kBAAkB,CAAC,cAAA,CAAe,GAAA,CAAI,KAAA,CAAM,IAAI,CAAA,EAAG;AACtD,MAAA,cAAA,CAAe,GAAA,CAAI,MAAM,IAAI,CAAA;AAC7B,MAAA,OAAA,CAAQ,IAAA;AAAA,QACP,CAAA,kBAAA,EAAqB,MAAM,IAAI,CAAA,gEAAA;AAAA,OAChC;AAAA,IACD;AACA,IAAA,OAAO,IAAA;AAAA,EACR;AACA,EAAA,OAAO;AAAA,IACN,IAAA,EAAM,QAAA;AAAA,IACN,OAAA,EAAS,EAAE,KAAA,EAAO,IAAA,EAAM,QAAQ,QAAA,CAAS,KAAA,CAAM,OAAO,CAAA;AAAE,GACzD;AACD;AA4BO,IAAM,iBAAiB,CAAC;AAAA,EAC9B,aAAA,GAAgB;AACjB,CAAA,GAA2B,EAAC,KAAuC;AAClE,EAAA,MAAM,YAAY,MAAM;AACvB,IAAA,MAAM,MAAA,GAAS,MAAA;AACf,IAAA,OAAQ,MAAA,CAAO,aAAa,CAAA,KAAM,EAAC;AAAA,EACpC,CAAA;AAIA,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AAEpC,EAAA,OAAO;AAAA,IACN,IAAA,EAAM,KAAA;AAAA,IACN,KAAA,EAAO,CAAC,EAAE,SAAA,EAAU,KAAM;AACzB,MAAA,MAAM,IAAA,GAAO,CACZ,KAAA,EACA,MAAA,EACA,EAAE,EAAA,EAAI,OAAA,EAAS,SAAQ,KACnB;AACJ,QAAA,MAAM,gBAAgB,eAAA,CAAgB,OAAA,EAAS,CAAC,CAAC,SAAS,SAAS,CAAA;AACnE,QAAA,KAAA,MAAW,OAAO,WAAA,EAAa;AAC9B,UAAA,IAAI,EAAE,GAAA,IAAO,aAAA,CAAA,EAAgB,aAAA,CAAc,GAAG,CAAA,GAAI,MAAA;AAAA,QACnD;AACA,QAAA,MAAA,CAAO,IAAA,CAAK,aAAa,CAAA,CAAE,OAAA,CAAQ,CAAC,GAAA,KAAQ,WAAA,CAAY,GAAA,CAAI,GAAG,CAAC,CAAA;AAEhE,QAAA,IAAI,WAAA,IAAe,QAAQ,SAAA,EAAU,CAAE,KAAK,EAAE,SAAA,EAAW,MAAM,CAAA;AAC/D,QAAA,SAAA,EAAU,CAAE,IAAA,CAAK,EAAE,KAAA,EAAO,QAAA,EAAU,IAAI,GAAG,aAAA,EAAe,GAAG,MAAA,EAAQ,CAAA;AAAA,MACtE,CAAA;AAEA,MAAA,KAAA,MAAW,IAAA,IAAQ;AAAA,QAClB,GAAG,gBAAA;AAAA,QACH,GAAG,MAAA;AAAA,QACH;AAAA,OACD,EAAY;AACX,QAAA,SAAA;AAAA,UAAU,IAAA;AAAA,UAAM,CAAC,QAAQ,OAAA,KACxB,IAAA;AAAA,YACC,IAAA;AAAA,YACA,UAAU,GAAA,CAAI,IAAI,IAAI,EAAE,SAAA,EAAW,QAAO,GAAI,MAAA;AAAA,YAC9C;AAAA;AACD,SACD;AAAA,MACD;AACA,MAAA,SAAA;AAAA,QAAU,QAAA;AAAA,QAAU,CAAC,EAAE,KAAA,EAAO,MAAA,IAAU,OAAA,KACvC,IAAA,CAAK,KAAA,EAAO,MAAA,EAAQ,OAAO;AAAA,OAC5B;AAAA,IACD;AAAA,GACD;AACD","file":"index.js","sourcesContent":["import { IS_DEVELOPMENT } from \"../../config\";\nimport type {\n\tCartOccurrences,\n\tEcommerceOccurrences,\n\tEcommerceShapes,\n\tPlacedItem,\n} from \"../../tracking/occurrences\";\nimport type {\n\tAnalyticsDestination,\n\tAnalyticsMapping,\n\tDestinationEvent,\n\tDestinationEventContext,\n} from \"../destination\";\nimport type {\n\tAnalyticsContext,\n\tCartItemOf,\n\tDomEvents,\n\tEcommerceEvents,\n\tEventMap,\n\tShapesOf,\n} from \"../events\";\n\n// Pushed under `ecommerce`, as GA4's ecommerce tags read them there.\nconst ECOMMERCE_EVENTS = [\n\t\"view_item_list\",\n\t\"select_item\",\n\t\"view_item\",\n\t\"add_to_wishlist\",\n\t\"add_to_cart\",\n\t\"remove_from_cart\",\n\t\"view_cart\",\n\t\"begin_checkout\",\n\t\"add_shipping_info\",\n\t\"add_payment_info\",\n\t\"purchase\",\n\t\"refund\",\n\t\"view_promotion\",\n\t\"select_promotion\",\n] as const;\n\nconst EVENTS = [\n\t\"search\",\n\t\"select_content\",\n\t\"share\",\n\t\"login\",\n\t\"sign_up\",\n\t\"generate_lead\",\n\t\"click\",\n\t\"video_start\",\n\t\"video_progress\",\n\t\"video_complete\",\n\t\"form_start\",\n\t\"form_submit\",\n\t\"scroll\",\n] as const;\n\nconst ECOMMERCE = new Set<string>(ECOMMERCE_EVENTS);\n\ntype Ga4Params = Record<string, unknown>;\n\n/** @see https://developers.google.com/analytics/devguides/collection/ga4/reference/events#add_to_cart_item */\nexport type Ga4Item = {\n\titem_id?: string;\n\titem_name?: string;\n\taffiliation?: string;\n\tcoupon?: string;\n\tdiscount?: number;\n\tindex?: number;\n\titem_brand?: string;\n\titem_category?: string;\n\titem_category2?: string;\n\titem_category3?: string;\n\titem_category4?: string;\n\titem_category5?: string;\n\titem_list_id?: string;\n\titem_list_name?: string;\n\titem_variant?: string;\n\tlocation_id?: string;\n\t/** Unit price, after discount. */\n\tprice?: number;\n\tquantity?: number;\n\tpromotion_id?: string;\n\tpromotion_name?: string;\n\tcreative_name?: string;\n\tcreative_slot?: string;\n} & Ga4Params;\n\nexport type Ga4List = { item_list_id?: string; item_list_name?: string };\n\nexport type Ga4Promotion = {\n\tpromotion_id?: string;\n\tpromotion_name?: string;\n\tcreative_name?: string;\n\tcreative_slot?: string;\n};\n\n/** An ecommerce event's params, pushed under `ecommerce`. */\nexport type Ga4Ecommerce = {\n\t/** ISO 4217, e.g. `\"EUR\"`. */\n\tcurrency?: string;\n\tvalue?: number;\n\titems?: Ga4Item[];\n} & Ga4Params;\n\n/**\n * What GTM accepts: GA4's events by name, in GA4's params, and `custom` for any other event name. Each is pushed with\n * `event_id` and the context variables, e.g. `{ event: \"login\", event_id, user_id, method }`, and ecommerce events'\n * params under `ecommerce`.\n */\nexport type GtmEvents = {\n\t[N in (typeof ECOMMERCE_EVENTS)[number]]: Ga4Ecommerce;\n} & {\n\t[N in (typeof EVENTS)[number]]: Ga4Params;\n} & {\n\tpage_view: {\n\t\tpage_location: string;\n\t\tpage_path: string;\n\t\tpage_title: string;\n\t\tpage_referrer: string;\n\t\tpage_type?: string;\n\t} & Ga4Params;\n\t/** Pushed as `{ event, ...params }`. */\n\tcustom: { event: string; params: Ga4Params };\n};\n\n// Acronyms stay one word: `viewedFAQ` as `viewed_faq`.\nconst toSnakeCase = (key: string) =>\n\tkey\n\t\t.replace(/([a-z\\d])([A-Z])/g, \"$1_$2\")\n\t\t.replace(/([A-Z]+)([A-Z][a-z])/g, \"$1_$2\")\n\t\t.toLowerCase();\n\n// Without `undefined` fields, so GTM's data model keeps no stale keys.\nconst toParams = (\n\tinput: object,\n\tnames: Record<string, string> = {},\n): Record<string, unknown> => {\n\tconst params: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(input)) {\n\t\tif (value === undefined) continue;\n\t\tparams[names[key] ?? toSnakeCase(key)] = value;\n\t}\n\treturn params;\n};\n\nconst USER_PARAM_NAMES: Record<string, string> = {\n\tid: \"user_id\",\n\ttype: \"user_type\",\n};\n\nconst CONTEXT_PARAM_NAMES: Record<string, string> = { locale: \"language\" };\n\n// Mapped to `page_*` params on page views instead.\nconst PAGE_CONTEXT_KEYS = new Set([\"url\", \"title\", \"referrer\"]);\n\n/**\n * Context as dataLayer variables: built-in and the project's fields, in snake_case, with user fields prefixed `user_`.\n * Email and phone only go into `user_data`, which Google's enhanced conversions read and hash before sending.\n */\nexport const toContextParams = (\n\tcontext: AnalyticsContext,\n\tincludeUserData: boolean,\n): Record<string, unknown> => {\n\tconst { user, ...fields } = context;\n\tconst rest = Object.entries(fields).filter(\n\t\t([key]) => !PAGE_CONTEXT_KEYS.has(key),\n\t);\n\tconst { email, phone, ...userFields } = user ?? {};\n\tconst userParams: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(userFields)) {\n\t\tuserParams[USER_PARAM_NAMES[key] ?? `user_${toSnakeCase(key)}`] = value;\n\t}\n\n\treturn {\n\t\tuser_id: undefined,\n\t\tuser_type: undefined,\n\t\t...userParams,\n\t\tlanguage: undefined,\n\t\tmarket: undefined,\n\t\t...Object.fromEntries(\n\t\t\trest.map(([key, value]) => [\n\t\t\t\tCONTEXT_PARAM_NAMES[key] ?? toSnakeCase(key),\n\t\t\t\tvalue,\n\t\t\t]),\n\t\t),\n\t\tuser_data:\n\t\t\tincludeUserData && (email || phone)\n\t\t\t\t? toParams({ email, phone_number: phone }, {})\n\t\t\t\t: undefined,\n\t};\n};\n\ntype Ga4MappingOptions<\n\tShapes extends EcommerceShapes,\n\tCartItem,\n\tContext extends object,\n> = {\n\t/** For what `ecommerce()` reports: the project's item as a GA4 item, e.g. `({ product }) => ({ item_id: product.id })`. */\n\titem?: (item: Shapes[\"item\"]) => Ga4Item;\n\t/** `itemViewed`'s currency, with its price as `value`, e.g. from the item or the context's market. */\n\tcurrency?: (\n\t\titem: Shapes[\"item\"],\n\t\tcontext: AnalyticsContext<Context>,\n\t) => string | undefined;\n\tlist?: (list: Shapes[\"list\"]) => Ga4List;\n\tpromotion?: (promotion: Shapes[\"promotion\"]) => Ga4Promotion;\n} & ([CartItem] extends [never | Shapes[\"item\"]]\n\t? {\n\t\t\t/**\n\t\t\t * For what `createCartChanges()` reports: the project's cart line item as a GA4 item. Price and quantity come\n\t\t\t * from the line. Defaults to `item`.\n\t\t\t */\n\t\t\tcartItem?: (item: CartItem) => Ga4Item;\n\t\t}\n\t:\n\t\t\t| { item?: undefined; cartItem?: (item: CartItem) => Ga4Item }\n\t\t\t| {\n\t\t\t\t\t/**\n\t\t\t\t\t * For what `createCartChanges()` reports: the project's cart line item as a GA4 item. Price and quantity\n\t\t\t\t\t * come from the line. Required with `item`, as the cart item isn't one.\n\t\t\t\t\t */\n\t\t\t\t\tcartItem: (item: CartItem) => Ga4Item;\n\t\t\t  });\n\ntype DomEventName = keyof DomEvents & string;\n\nconst toPageView = (\n\tpayload: DomEvents[\"pageViewed\"],\n\tcontext: AnalyticsContext,\n): DestinationEvent<GtmEvents> => {\n\tconst { url = context.url, title = context.title, pageType } = payload;\n\treturn {\n\t\tname: \"page_view\",\n\t\tpayload: {\n\t\t\tpage_location: url,\n\t\t\tpage_path: new URL(url, context.url).pathname,\n\t\t\tpage_title: title,\n\t\t\tpage_referrer: context.referrer,\n\t\t\t// Only on page views, so GTM's data model keeps it for the page's other events.\n\t\t\tpage_type: pageType,\n\t\t},\n\t};\n};\n\nconst DOM_EVENTS = {\n\tclicked: \"click\",\n\tvideoStarted: \"video_start\",\n\tvideoProgressed: \"video_progress\",\n\tvideoCompleted: \"video_complete\",\n\tformStarted: \"form_start\",\n\tformSubmitted: \"form_submit\",\n\tscrolled: \"scroll\",\n} as const satisfies Record<\n\tExclude<DomEventName, \"pageViewed\">,\n\tkeyof GtmEvents\n>;\n\nconst CART_EVENTS = {\n\taddedToCart: \"add_to_cart\",\n\tremovedFromCart: \"remove_from_cart\",\n} as const satisfies Record<keyof CartOccurrences<object>, keyof GtmEvents>;\n\n// Mapped only with `ga4Mapping()`'s adapters.\nconst TRACKER_ECOMMERCE = new Set<string>(\n\tObject.keys({\n\t\titemViewed: true,\n\t\titemSelected: true,\n\t\titemsViewed: true,\n\t\tpromotionViewed: true,\n\t\tpromotionSelected: true,\n\t\t...CART_EVENTS,\n\t} satisfies Record<\n\t\tkeyof EcommerceOccurrences<EcommerceShapes> | keyof typeof CART_EVENTS,\n\t\tunknown\n\t>),\n);\n\ntype Entry = (\n\tpayload: never,\n\tevent: { context: AnalyticsContext<never> },\n) => DestinationEvent<GtmEvents> | null;\n\n/**\n * Maps what tracking reports to GA4's recommended events, e.g. `clicked` to `click`, `itemsViewed` to\n * `view_item_list` and `addedToCart` to `add_to_cart`: `DomEvents` with their camelCase fields as snake_case params,\n * `EcommerceEvents` with `item`, `list` and `promotion`, and `CartEvents` with `cartItem`. Events without what they\n * need, e.g. ecommerce events without `item`, aren't mapped. Spread it to add or override events.\n *\n * @example\n * ```ts\n * map(gtmDestination(), {\n *   ...mapEvery(events, toGa4CustomEvent),\n *   ...ga4Mapping<Events>({\n *     item: ({ product, variant }) => ({\n *       item_id: product.id,\n *       item_name: product.title,\n *       item_variant: variant?.title,\n *       price: Number((variant ?? product).price.amount),\n *     }),\n *     currency: ({ product }) => product.price.currencyCode,\n *     list: ({ id, name }) => ({ item_list_id: id, item_list_name: name }),\n *   }),\n *   newsletterSignedUp: ({ source }) => ({ name: \"generate_lead\", payload: { lead_source: source } }),\n * });\n * ```\n */\nexport const ga4Mapping = <\n\tEvents extends EventMap,\n\tContext extends object = Record<never, never>,\n>({\n\titem: toItem,\n\tcurrency,\n\tlist: toList = () => ({}),\n\tpromotion: toPromotion = () => ({}),\n\tcartItem,\n}: Ga4MappingOptions<\n\tShapesOf<Events>,\n\tCartItemOf<Events>,\n\tContext\n> = {}): AnalyticsMapping<Events, GtmEvents, Context> => {\n\ttype Shapes = ShapesOf<Events>;\n\ttype Ecommerce = EcommerceEvents<Shapes>;\n\tconst toCartItem = (cartItem ?? toItem) as\n\t\t| ((item: CartItemOf<Events>) => Ga4Item)\n\t\t| undefined;\n\n\tconst entries: Record<string, Entry> = {\n\t\tpageViewed: (payload: DomEvents[\"pageViewed\"], { context }) =>\n\t\t\ttoPageView(payload, context),\n\t};\n\tfor (const [event, name] of Object.entries(DOM_EVENTS)) {\n\t\tentries[event] = (payload: object) => ({\n\t\t\tname,\n\t\t\tpayload: toParams(payload),\n\t\t});\n\t}\n\n\tif (toItem) {\n\t\tconst toPlacedItem = ({\n\t\t\titem,\n\t\t\tlist,\n\t\t\tindex,\n\t\t\tpromotion,\n\t\t}: Omit<PlacedItem<Shapes>, \"list\"> & { list?: Shapes[\"list\"] }) => ({\n\t\t\t...toItem(item),\n\t\t\t...(list ? toList(list) : {}),\n\t\t\t...(promotion ? toPromotion(promotion) : {}),\n\t\t\t...(index !== undefined && { index }),\n\t\t});\n\n\t\tObject.assign(entries, {\n\t\t\titemViewed: (\n\t\t\t\tplaced: Ecommerce[\"itemViewed\"],\n\t\t\t\t{ context }: { context: AnalyticsContext<Context> },\n\t\t\t) => {\n\t\t\t\tconst item = toPlacedItem(placed);\n\t\t\t\tconst itemCurrency = currency?.(placed.item, context);\n\t\t\t\treturn {\n\t\t\t\t\tname: \"view_item\",\n\t\t\t\t\tpayload: toParams({\n\t\t\t\t\t\tcurrency: itemCurrency,\n\t\t\t\t\t\tvalue:\n\t\t\t\t\t\t\titemCurrency && item.price !== undefined\n\t\t\t\t\t\t\t\t? item.price * (item.quantity ?? 1)\n\t\t\t\t\t\t\t\t: undefined,\n\t\t\t\t\t\titems: [item],\n\t\t\t\t\t}),\n\t\t\t\t};\n\t\t\t},\n\t\t\titemSelected: ({ list, ...placed }: Ecommerce[\"itemSelected\"]) => ({\n\t\t\t\tname: \"select_item\",\n\t\t\t\tpayload: {\n\t\t\t\t\t...(list ? toList(list) : {}),\n\t\t\t\t\titems: [toPlacedItem(placed)],\n\t\t\t\t},\n\t\t\t}),\n\t\t\titemsViewed: ({ list, items }: Ecommerce[\"itemsViewed\"]) => ({\n\t\t\t\tname: \"view_item_list\",\n\t\t\t\tpayload: {\n\t\t\t\t\t...(list ? toList(list) : {}),\n\t\t\t\t\titems: items.map(toPlacedItem),\n\t\t\t\t},\n\t\t\t}),\n\t\t\tpromotionViewed: ({\n\t\t\t\tpromotion,\n\t\t\t\titems,\n\t\t\t}: Ecommerce[\"promotionViewed\"]) => ({\n\t\t\t\tname: \"view_promotion\",\n\t\t\t\tpayload: {\n\t\t\t\t\t...toPromotion(promotion),\n\t\t\t\t\t...(items.length > 0 && { items: items.map((item) => toItem(item)) }),\n\t\t\t\t},\n\t\t\t}),\n\t\t\tpromotionSelected: ({\n\t\t\t\tpromotion,\n\t\t\t\titem,\n\t\t\t}: Ecommerce[\"promotionSelected\"]) => ({\n\t\t\t\tname: \"select_promotion\",\n\t\t\t\tpayload: {\n\t\t\t\t\t...toPromotion(promotion),\n\t\t\t\t\t...(item ? { items: [toItem(item)] } : {}),\n\t\t\t\t},\n\t\t\t}),\n\t\t} satisfies Record<keyof Ecommerce, Entry>);\n\t}\n\n\tif (toCartItem) {\n\t\tfor (const [event, name] of Object.entries(CART_EVENTS)) {\n\t\t\tentries[event] = ({\n\t\t\t\tcurrency: cartCurrency,\n\t\t\t\tvalue,\n\t\t\t\titems,\n\t\t\t}: {\n\t\t\t\tcurrency: string;\n\t\t\t\tvalue: number;\n\t\t\t\titems: { item: CartItemOf<Events>; quantity: number; price: number }[];\n\t\t\t}) => ({\n\t\t\t\tname,\n\t\t\t\tpayload: {\n\t\t\t\t\tcurrency: cartCurrency,\n\t\t\t\t\tvalue,\n\t\t\t\t\titems: items.map(({ item, quantity, price }) => ({\n\t\t\t\t\t\t...toCartItem(item),\n\t\t\t\t\t\tprice,\n\t\t\t\t\t\tquantity,\n\t\t\t\t\t})),\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\t}\n\n\treturn entries as unknown as AnalyticsMapping<Events, GtmEvents, Context>;\n};\n\nconst warnedUnmapped = new Set<string>();\n\n/**\n * For `mapEvery()`, spread before the other entries: an event without one, e.g. a custom one, under its name and with\n * its fields in snake_case, e.g. `newsletterSignedUp` as `newsletter_signed_up`. Unmapped ecommerce events aren't sent, as GA4's\n * tags would read them with the `ecommerce` of an earlier event.\n */\nexport const toGa4CustomEvent = (event: {\n\tname: string;\n\tpayload: object;\n}): DestinationEvent<GtmEvents> | null => {\n\tconst name = toSnakeCase(event.name);\n\tif (ECOMMERCE.has(name) || TRACKER_ECOMMERCE.has(event.name)) {\n\t\tif (IS_DEVELOPMENT && !warnedUnmapped.has(event.name)) {\n\t\t\twarnedUnmapped.add(event.name);\n\t\t\tconsole.warn(\n\t\t\t\t`[analytics] gtm: \"${event.name}\" isn't mapped. Pass ga4Mapping()'s adapters or map it yourself.`,\n\t\t\t);\n\t\t}\n\t\treturn null;\n\t}\n\treturn {\n\t\tname: \"custom\",\n\t\tpayload: { event: name, params: toParams(event.payload) },\n\t};\n};\n\nexport type GtmDestinationOptions = {\n\t/** Default `\"dataLayer\"`. */\n\tdataLayerName?: string;\n};\n\n/**\n * Pushes events to the GTM dataLayer, with the context as dataLayer variables (`user_data` only with marketing\n * consent), and ecommerce events' params under `ecommerce`. Map it with `ga4Mapping<Events>()`, and give it\n * `withConsent(…, \"none\")` for Google Consent Mode's advanced setup, where Consent Mode gates tags inside the container, or\n * `[\"analytics\"]` for its basic one. Consent Mode signals come from the consent platform's integration, e.g.\n * Cookiebot's, or from `googleConsentMode()`. See `docs/analytics.md`.\n *\n * @example\n * ```ts\n * export const analytics = createAnalytics<Events>({\n *   events,\n *   consent: cookiebotConsent(),\n *   destinations: [\n *     withConsent(\n *       map(gtmDestination(), { ...mapEvery(events, toGa4CustomEvent), ...ga4Mapping<Events>({ item: toGa4Item }) }),\n *       \"none\",\n *     ),\n *   ],\n * });\n * ```\n */\nexport const gtmDestination = ({\n\tdataLayerName = \"dataLayer\",\n}: GtmDestinationOptions = {}): AnalyticsDestination<GtmEvents> => {\n\tconst dataLayer = () => {\n\t\tconst target = window as unknown as Record<string, unknown[] | undefined>;\n\t\treturn (target[dataLayerName] ??= []);\n\t};\n\n\t// GTM's data model keeps a value until it's overwritten, so a context key that disappears, like `user_id` after\n\t// logout, is pushed as `undefined`.\n\tconst contextKeys = new Set<string>();\n\n\treturn {\n\t\tname: \"gtm\",\n\t\tsetup: ({ subscribe }) => {\n\t\t\tconst push = (\n\t\t\t\tevent: string,\n\t\t\t\tparams: Ga4Params,\n\t\t\t\t{ id, context, consent }: DestinationEventContext,\n\t\t\t) => {\n\t\t\t\tconst contextParams = toContextParams(context, !!consent?.marketing);\n\t\t\t\tfor (const key of contextKeys) {\n\t\t\t\t\tif (!(key in contextParams)) contextParams[key] = undefined;\n\t\t\t\t}\n\t\t\t\tObject.keys(contextParams).forEach((key) => contextKeys.add(key));\n\t\t\t\t// Clears the previous ecommerce object, which GTM would otherwise merge into this one.\n\t\t\t\tif (\"ecommerce\" in params) dataLayer().push({ ecommerce: null });\n\t\t\t\tdataLayer().push({ event, event_id: id, ...contextParams, ...params });\n\t\t\t};\n\n\t\t\tfor (const name of [\n\t\t\t\t...ECOMMERCE_EVENTS,\n\t\t\t\t...EVENTS,\n\t\t\t\t\"page_view\",\n\t\t\t] as const) {\n\t\t\t\tsubscribe(name, (params, context) =>\n\t\t\t\t\tpush(\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tECOMMERCE.has(name) ? { ecommerce: params } : params,\n\t\t\t\t\t\tcontext,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t\tsubscribe(\"custom\", ({ event, params }, context) =>\n\t\t\t\tpush(event, params, context),\n\t\t\t);\n\t\t},\n\t};\n};\n"]}

package/dist/analytics/index.d.ts

@@ -0,0 +1,101 @@
+import { C as ConsentCategory, a as ConsentSource, b as ConsentTarget } from '../index-Zef1nnTP.js';
+import { E as EventMap, A as AnalyticsEventName, a as AnalyticsPayloadArgs, b as AnalyticsContextFields, c as AnalyticsEnvelope, d as EventCatalog } from '../define-events-CxZjoUlG.js';
+export { h as AnalyticsContext, i as AnalyticsUser, f as EventDefinition, g as EventsOf, S as Shape, e as defineEvents, s as shape } from '../define-events-CxZjoUlG.js';
+import { C as ConsentedDestination } from '../destination-5KJ5PeR3.js';
+export { A as AnalyticsDestination, a as AnalyticsMapping, b as ConsentRequirement, D as DestinationEvent, c as DestinationEventContext, d as DestinationSetupContext, M as MappingResult, m as map, e as mapEvery, w as withConsent } from '../destination-5KJ5PeR3.js';
+
+type AnalyticsOptions<Events extends EventMap, Context extends object> = {
+    /** Every event the project tracks, from `defineEvents()`. */
+    events: EventCatalog<Events>;
+    /** E.g. `cookiebotConsent()` from `@buildinams/core/consent`. Until answered, events are queued. */
+    consent: ConsentSource;
+    /** Told every answer, before destinations receive events under it, e.g. `googleConsentMode()`. */
+    consentTargets?: ConsentTarget[];
+    /** Destinations with the consent they require, from `withConsent()`. */
+    destinations?: ConsentedDestination<Events, Context>[];
+    /**
+     * What reports events to track under their own names, e.g. `createDomWatcher()` and `createCartChanges()`, with their
+     * `events` in the catalog. A source feeds one instance: a later `createAnalytics()` with it, e.g. after HMR, takes it
+     * over.
+     */
+    sources?: NoInfer<AnalyticsSource<Events>>[];
+    /** Initial `context` for every event, after `url`, `title` and `referrer`. Update it with `setContext()`. */
+    context?: AnalyticsContextFields<Context>;
+    /**
+     * `"deferred"` delivers events to destinations after the next paint, so tracking in an event handler doesn't delay
+     * its response (INP), or straight away while the page is hidden or unloading. `"immediate"` delivers them as they're
+     * tracked, e.g. in tests. Subscribers always receive them as they're tracked. Either way, a prerendered page delivers
+     * nothing until the visitor navigates to it.
+     */
+    delivery?: "deferred" | "immediate";
+};
+declare const types: unique symbol;
+/** Reports events of the project, e.g. `createDomWatcher()` or `createCartChanges()`. */
+type AnalyticsSource<Events extends EventMap = EventMap> = {
+    subscribe: (listener: (event: {
+        [N in AnalyticsEventName<Events>]: {
+            name: N;
+            payload: Events[N];
+        };
+    }[AnalyticsEventName<Events>]) => void) => () => void;
+};
+/** How a destination receives an event. */
+type AnalyticsRoute = {
+    /** The consent categories it waits for, or `"none"`. */
+    requires: readonly ConsentCategory[] | "none";
+};
+/** Per event of the catalog, its description and the destinations that receive it, by name. */
+type AnalyticsRoutes<Events extends EventMap> = {
+    [N in AnalyticsEventName<Events>]: {
+        description: string;
+        destinations: Record<string, AnalyticsRoute>;
+    };
+};
+type Analytics<Events extends EventMap, Context extends object = Record<never, never>> = {
+    /** Type only, so helpers taking the instance infer its events. */
+    readonly [types]?: {
+        events: Events;
+        context: Context;
+    };
+    track: <N extends AnalyticsEventName<Events>>(name: N, ...args: AnalyticsPayloadArgs<Events, N>) => void;
+    /**
+     * Merges into the context of events tracked from now on, e.g. `{ user }` after login. Pass `undefined` to clear
+     * a field.
+     */
+    setContext: (fields: AnalyticsContextFields<Context>) => void;
+    /** Every tracked event as it's tracked, before consent gating, e.g. to log it. Returns a function that unsubscribes. */
+    subscribe: (listener: (event: AnalyticsEnvelope<Events, Context>) => void) => () => void;
+    /**
+     * Which destinations receive each event, and how, e.g. to check in a test, or for an agent or analyst to read what
+     * the project tracks where. Also on the server.
+     */
+    routes: () => AnalyticsRoutes<Events>;
+};
+/**
+ * Creates the analytics bus: one `track()`, typed by the project's `Events` from `defineEvents()`, that forwards to
+ * every destination the visitor consented to, and tracks what its `sources` report. `Context` adds fields to the
+ * built-in context. Never throws: invalid input and failing destinations
+ * are logged instead. Calls on the server do nothing. See `docs/analytics.md`.
+ *
+ * @example
+ * ```ts
+ * const events = defineEvents({
+ *   ...domWatcher.events,
+ *   newsletterSignedUp: { description: "The newsletter form was submitted.", payload: shape<{ source: "footer" }>() },
+ * });
+ *
+ * type Events = EventsOf<typeof events>;
+ *
+ * export const analytics = createAnalytics<Events>({
+ *   events,
+ *   consent,
+ *   sources: [domWatcher],
+ *   destinations: [withConsent(map(gtmDestination(), ga4Mapping<Events>()), "none")],
+ * });
+ *
+ * analytics.track("newsletterSignedUp", { source: "footer" });
+ * ```
+ */
+declare const createAnalytics: <Events extends EventMap, Context extends object = Record<never, never>>({ events, consent: consentSource, consentTargets, destinations: allDestinations, sources, context: initialContext, delivery, }: AnalyticsOptions<Events, Context>) => Analytics<Events, Context>;
+
+export { type Analytics, AnalyticsContextFields, AnalyticsEnvelope, AnalyticsEventName, type AnalyticsRoute, type AnalyticsRoutes, type AnalyticsSource, ConsentedDestination, EventCatalog, EventMap, createAnalytics };