@azzas/azzas-tracker-web 1.0.80 → 1.0.82

package/README.md

@@ -1,130 +1,130 @@
-# azzas-tracker-web
-
-Pacote interno para **Data Tracking** das lojas WEB, centralizando a captura e envio de eventos para diferentes plataformas de mídia (Meta, Dito, DataLayer, etc).  
-
-O objetivo é fornecer uma **camada única e consistente de tracking**, garantindo que todos os eventos sejam tratados, formatados e enviados de forma confiável.  
-
-E, principalmente, centralizar a complexidade e a “inteligência” de tracking **fora dos repositórios das lojas**.
-
----
-
-## Fluxo do Tracking
-
-O pacote segue o seguinte fluxo de eventos:
-
-1. **User Action**  
-   Ações do usuário na loja (ex: adicionar ao carrinho, iniciar checkout, finalizar compra).  
-
-2. **Tracks**  
-   Ponto central que recebe o contexto do evento vindo da ação do usuário e encaminha para o *Formatter*.  
-
-3. **Formatter**  
-   Acessa a constante `EVENTS` e, baseado no contexto do evento, puxa os parâmetros obrigatórios e entrega a biblioteca de parâmetros (`/params`).  
-
-4. **Params Library**  
-   Contém **getters** e **resolvers** que garantem que os dados sejam legítimos e que todos os parâmetros sejam corretamente tratados.  
-
-5. **Adapters**  
-   Módulos responsáveis por enviar os dados formatados para cada destino (Meta, Datalayer, Dito, etc).  
-
-![FLUXOGRAMA](/public/fluxograma-lib-params.png)
-
-## Instalação
-
-
-```bash
-npm install /path/azzas-tracker-web
-```
-
-
-## Exemplos
-
-Listagem dos `EVENTS` e função orquestradora `trackWebEvent`:
-```javascript
-  const EVENTS = {
-    ADD_PERSONAL_INFO: {
-      name: 'add_personal_info',
-      destinations: ['DataLayer'],
-      requiredParams: ['brand', 'pre_filled', 'currency', 'value', 'subtotal'],
-    }, 
-    VIEW_CART: {
-      name: 'add_personal_info',
-      destinations: ['DataLayer', 'Meta', 'Dito'],
-      requiredParams: ['....'],
-    }
-  }
-
-  export async function trackWebEvent(event: EventName, context: EventContext = {}) {
-    try {
-      const parameters = await getParameters(context, event);
-      return await dispatchTrackEvent(event, parameters);
-    } catch (err) {
-      return console.error(`[DT] Error tracking event ${event}:`, err);
-    }
-  }
-```
-
-Uso básico da função no consumidor:
-
-
-```javascript
-  import { trackWebEvent } from 'azzas-tracker-web';
-
-  // DATA TRACKING | add_personal_info at submit (pre-filled always false)
-  // @see notion document for more details:
-  const form: Element = document.querySelector('xxxxxx');
-  if (form) {
-    form.addEventListener('submit', () => {
-      trackWebEvent('ADD_PERSONAL_INFO', { preFilled: false, orderForm: vtexjs.checkout.orderForm });
-    });
-  }
-```
-
-***OBS***: atente-se ao adicionar eventos novos e contribua na documentação do NOTION ou apenas DOCUMENTE em algum lugar! Seu futuro EU será grato 👍
-
-## Teste Local para Ambientes CDN/DENO
-
-Para testar alterações na biblioteca localmente, simulando a forma como ela é carregada por uma CDN (<script src="...">), use o script npm run dev:deno.
-
-Este comando realiza o build mais recente da biblioteca, empacota-o e inicia um servidor HTTP local usando o Deno para servir o arquivo
-
-1. Aqui nesse repositório, rode o script que inicia o servidor local:
-
-```bash
-  npm run dev:deno
-```
-
-O servidor será iniciado e começará a servir o seu arquivo de build no seguinte endereço: http://localhost:4507/.
-
-2. No Projeto Consumidor (DENO/FRONT):
-
-Altere o link do <script> no seu projeto para apontar para o servidor local.
-
-Você deve usar: <script src="http://localhost:4507/dist/mod.global.js"></script>
-
-
-## Boas Práticas
-- Sempre garantir que os `requiredParams` de cada evento estejam preenchidos antes de enviar.
-
-- Procure sempre manter o envio das ações de usuário o mais ***genérico*** possível. Toda a inteligência e complexidade do tratamento dos dados deve ficar centralizada na lib, e não nos repositórios das lojas.
-
-- Usar nomes de eventos semânticos e consistentes (ex: VIEW_CART, ADD_PAYMENT_INFO).
-
-- Manter os contextos enxutos, enviando apenas dados realmente necessários.
-
-- Cada novo evento deve ser registrado em `EVENTS` com seus destinos e parâmetros obrigatórios. Essa constante talvez venha a ser dinâmica dependendo da MARCA utilizada
-
-
-## Contribuição
-
-- Adicionar novos eventos em `EVENTS`.
-
-- Criar adapter correspondente caso seja necessário integrar com nova plataforma. Nesse caso deve-se avaliar qual será o serviço feito, o que será consumido, para onde será enviado.
-
-- Garantir que todos os parâmetros obrigatórios estejam mapeados nos getters/resolvers.
-
-- Executar build (npm run build) antes de testar no checkout/loja.
-
-## Authors
-
-- Lucas Soares
+# azzas-tracker-web
+
+Pacote interno para **Data Tracking** das lojas WEB, centralizando a captura e envio de eventos para diferentes plataformas de mídia (Meta, Dito, DataLayer, etc).  
+
+O objetivo é fornecer uma **camada única e consistente de tracking**, garantindo que todos os eventos sejam tratados, formatados e enviados de forma confiável.  
+
+E, principalmente, centralizar a complexidade e a “inteligência” de tracking **fora dos repositórios das lojas**.
+
+---
+
+## Fluxo do Tracking
+
+O pacote segue o seguinte fluxo de eventos:
+
+1. **User Action**  
+   Ações do usuário na loja (ex: adicionar ao carrinho, iniciar checkout, finalizar compra).  
+
+2. **Tracks**  
+   Ponto central que recebe o contexto do evento vindo da ação do usuário e encaminha para o *Formatter*.  
+
+3. **Formatter**  
+   Acessa a constante `EVENTS` e, baseado no contexto do evento, puxa os parâmetros obrigatórios e entrega a biblioteca de parâmetros (`/params`).  
+
+4. **Params Library**  
+   Contém **getters** e **resolvers** que garantem que os dados sejam legítimos e que todos os parâmetros sejam corretamente tratados.  
+
+5. **Adapters**  
+   Módulos responsáveis por enviar os dados formatados para cada destino (Meta, Datalayer, Dito, etc).  
+
+![FLUXOGRAMA](/public/fluxograma-lib-params.png)
+
+## Instalação
+
+
+```bash
+npm install /path/azzas-tracker-web
+```
+
+
+## Exemplos
+
+Listagem dos `EVENTS` e função orquestradora `trackWebEvent`:
+```javascript
+  const EVENTS = {
+    ADD_PERSONAL_INFO: {
+      name: 'add_personal_info',
+      destinations: ['DataLayer'],
+      requiredParams: ['brand', 'pre_filled', 'currency', 'value', 'subtotal'],
+    }, 
+    VIEW_CART: {
+      name: 'add_personal_info',
+      destinations: ['DataLayer', 'Meta', 'Dito'],
+      requiredParams: ['....'],
+    }
+  }
+
+  export async function trackWebEvent(event: EventName, context: EventContext = {}) {
+    try {
+      const parameters = await getParameters(context, event);
+      return await dispatchTrackEvent(event, parameters);
+    } catch (err) {
+      return console.error(`[DT] Error tracking event ${event}:`, err);
+    }
+  }
+```
+
+Uso básico da função no consumidor:
+
+
+```javascript
+  import { trackWebEvent } from 'azzas-tracker-web';
+
+  // DATA TRACKING | add_personal_info at submit (pre-filled always false)
+  // @see notion document for more details:
+  const form: Element = document.querySelector('xxxxxx');
+  if (form) {
+    form.addEventListener('submit', () => {
+      trackWebEvent('ADD_PERSONAL_INFO', { preFilled: false, orderForm: vtexjs.checkout.orderForm });
+    });
+  }
+```
+
+***OBS***: atente-se ao adicionar eventos novos e contribua na documentação do NOTION ou apenas DOCUMENTE em algum lugar! Seu futuro EU será grato 👍
+
+## Teste Local para Ambientes CDN/DENO
+
+Para testar alterações na biblioteca localmente, simulando a forma como ela é carregada por uma CDN (<script src="...">), use o script npm run dev:deno.
+
+Este comando realiza o build mais recente da biblioteca, empacota-o e inicia um servidor HTTP local usando o Deno para servir o arquivo
+
+1. Aqui nesse repositório, rode o script que inicia o servidor local:
+
+```bash
+  npm run dev:deno
+```
+
+O servidor será iniciado e começará a servir o seu arquivo de build no seguinte endereço: http://localhost:4507/.
+
+2. No Projeto Consumidor (DENO/FRONT):
+
+Altere o link do <script> no seu projeto para apontar para o servidor local.
+
+Você deve usar: <script src="http://localhost:4507/dist/mod.global.js"></script>
+
+
+## Boas Práticas
+- Sempre garantir que os `requiredParams` de cada evento estejam preenchidos antes de enviar.
+
+- Procure sempre manter o envio das ações de usuário o mais ***genérico*** possível. Toda a inteligência e complexidade do tratamento dos dados deve ficar centralizada na lib, e não nos repositórios das lojas.
+
+- Usar nomes de eventos semânticos e consistentes (ex: VIEW_CART, ADD_PAYMENT_INFO).
+
+- Manter os contextos enxutos, enviando apenas dados realmente necessários.
+
+- Cada novo evento deve ser registrado em `EVENTS` com seus destinos e parâmetros obrigatórios. Essa constante talvez venha a ser dinâmica dependendo da MARCA utilizada
+
+
+## Contribuição
+
+- Adicionar novos eventos em `EVENTS`.
+
+- Criar adapter correspondente caso seja necessário integrar com nova plataforma. Nesse caso deve-se avaliar qual será o serviço feito, o que será consumido, para onde será enviado.
+
+- Garantir que todos os parâmetros obrigatórios estejam mapeados nos getters/resolvers.
+
+- Executar build (npm run build) antes de testar no checkout/loja.
+
+## Authors
+
+- Lucas Soares

package/dist/mod.cjs

@@ -630,10 +630,174 @@ async function itemsFromOrderForm(context) {
   );
 }
 
+// src/params/utils/itemListAttribution.ts
+var LAST_SELECTED_ITEM_KEY = "last_selected_item";
+var STORAGE_VIEWED = "last_viewed_item";
+var CART_LIST_HISTORY_KEY = "cart_list_history";
+var DAY_IN_MS = 24 * 60 * 60 * 1e3;
+function getStorage() {
+  try {
+    if (typeof window === "undefined" || !window.localStorage) return null;
+    return window.localStorage;
+  } catch (e) {
+    return null;
+  }
+}
+function parseJSON(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch (e) {
+    return null;
+  }
+}
+function isFreshTimestamp(timestamp) {
+  const elapsed = Date.now() - timestamp;
+  return elapsed >= 0 && elapsed < DAY_IN_MS;
+}
+function isStoredItemMemory(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.item_id === "string" && typeof candidate.item_list_name === "string" && typeof candidate.timestamp === "number";
+}
+function normalizeStoredItemMemory(value) {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value;
+  const itemId = candidate.item_id;
+  const itemListName = candidate.item_list_name;
+  const timestamp = candidate.timestamp;
+  if (typeof itemId !== "string" || typeof itemListName !== "string" || typeof timestamp !== "number") {
+    return null;
+  }
+  return {
+    item_id: itemId,
+    item_list_name: itemListName,
+    timestamp
+  };
+}
+function resolveIdFromUnknownItem(item) {
+  var _a, _b, _c, _d, _e;
+  const id = (_e = (_d = (_c = (_b = (_a = item == null ? void 0 : item.productID) != null ? _a : item == null ? void 0 : item.productId) != null ? _b : item == null ? void 0 : item.item_group_id) != null ? _c : item == null ? void 0 : item.item_id) != null ? _d : item == null ? void 0 : item.id) != null ? _e : null;
+  return id == null ? null : String(id);
+}
+function resolveItemId(item) {
+  return resolveIdFromUnknownItem(item);
+}
+function readStoredItem(key) {
+  const storage = getStorage();
+  if (!storage) return null;
+  try {
+    const parsed = parseJSON(storage.getItem(key));
+    const normalized = normalizeStoredItemMemory(parsed);
+    return normalized && isStoredItemMemory(normalized) ? normalized : null;
+  } catch (e) {
+    return null;
+  }
+}
+function writeStoredItem(key, value) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch (e) {
+  }
+}
+function readCartHistory() {
+  const storage = getStorage();
+  if (!storage) return [];
+  try {
+    const parsed = parseJSON(storage.getItem(CART_LIST_HISTORY_KEY));
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((entry) => !!entry && typeof entry === "object" && typeof entry.item_id === "string" && typeof entry.item_list_name === "string");
+  } catch (e) {
+    return [];
+  }
+}
+function writeCartHistory(history) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(CART_LIST_HISTORY_KEY, JSON.stringify(history));
+  } catch (e) {
+  }
+}
+function saveSelectedItem(productId, listName) {
+  if (productId == null || !listName) return;
+  const payload = {
+    item_id: String(productId),
+    item_list_name: String(listName),
+    timestamp: Date.now()
+  };
+  writeStoredItem(LAST_SELECTED_ITEM_KEY, payload);
+}
+function saveViewedItem(productId, listName) {
+  if (productId == null) return;
+  const payload = {
+    item_id: String(productId),
+    item_list_name: String(listName != null ? listName : "PDP"),
+    timestamp: Date.now()
+  };
+  writeStoredItem(STORAGE_VIEWED, payload);
+}
+function resolveItemListName(params) {
+  const { event, item, itemListName } = params;
+  const currentListName = itemListName != null ? itemListName : null;
+  const isResolvableEvent = event === "VIEW_ITEM" || event === "ADD_TO_CART";
+  if (!isResolvableEvent) return currentListName;
+  const currentItemId = resolveIdFromUnknownItem(item);
+  if (event === "VIEW_ITEM") {
+    if (!currentItemId) return "PDP";
+    const selectedItem = readStoredItem(LAST_SELECTED_ITEM_KEY);
+    if (!selectedItem) return "PDP";
+    if (selectedItem.item_id === currentItemId && isFreshTimestamp(selectedItem.timestamp)) {
+      return selectedItem.item_list_name;
+    }
+    return "PDP";
+  }
+  if (currentListName !== "PDP" && currentListName !== null) return currentListName;
+  if (!currentItemId) return currentListName;
+  const viewedItem = readStoredItem(STORAGE_VIEWED);
+  if (viewedItem && viewedItem.item_id === currentItemId && isFreshTimestamp(viewedItem.timestamp)) {
+    return viewedItem.item_list_name;
+  }
+  return currentListName === "PDP" ? "PDP" : null;
+}
+function appendCartHistory(productId, listName) {
+  if (productId == null) return;
+  const history = readCartHistory();
+  history.push({
+    item_id: String(productId),
+    item_list_name: listName ? String(listName) : "PDP"
+  });
+  writeCartHistory(history);
+}
+function pickSelectedItemFromResolvedItems(items, source) {
+  var _a;
+  if (!Array.isArray(items) || items.length === 0) return null;
+  if (typeof (source == null ? void 0 : source.index) === "number") {
+    const indexed = (_a = items.find((item) => (item == null ? void 0 : item.index) === source.index)) != null ? _a : items[source.index];
+    if (indexed && typeof indexed === "object") return indexed;
+  }
+  return items[0];
+}
+function persistSelectItemOriginFromResolvedItems(items, source) {
+  var _a, _b, _c;
+  const selectedItem = pickSelectedItemFromResolvedItems(items, source);
+  if (!selectedItem) return;
+  const productId = resolveIdFromUnknownItem(selectedItem);
+  const listName = (_c = (_b = (_a = selectedItem == null ? void 0 : selectedItem.item_list_name) != null ? _a : source == null ? void 0 : source.itemListName) != null ? _b : source == null ? void 0 : source.item_list_name) != null ? _c : null;
+  saveSelectedItem(productId, listName);
+}
+
 // src/params/resolvers/items/fromItem.ts
 async function itemsFromItem(context, event) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
   const { item, orderForm, itemListName } = context;
+  const resolvedListName = resolveItemListName({ event, item, itemListName });
+  const resolvedItemId = resolveItemId(item);
+  if (event === "ADD_TO_CART") {
+    appendCartHistory(resolvedItemId, resolvedListName);
+  }
   return [
     {
       index: typeof (item == null ? void 0 : item.index) === "number" ? item.index : null,
@@ -651,7 +815,7 @@ async function itemsFromItem(context, event) {
       item_variant: ((item == null ? void 0 : item.skuName) || (item == null ? void 0 : item.item_variant) || (item == null ? void 0 : item.name) || (item == null ? void 0 : item.itemOffered.name)).split(/[-/]/)[0].trim() || null,
       item_variant2: (item == null ? void 0 : item.size) || ((_n = item == null ? void 0 : item.itemAttributes) == null ? void 0 : _n.size) || ((_p = (_o = (item == null ? void 0 : item.skuName) || (item == null ? void 0 : item.name) || (item == null ? void 0 : item.itemOffered.name)) == null ? void 0 : _o.split(/[-/]/).pop()) == null ? void 0 : _p.trim()) || null,
       discount: getDiscount(item),
-      item_list_name: itemListName || null,
+      item_list_name: resolvedListName,
       item_url: (item == null ? void 0 : item.item_url) || null,
       // add_to_cart dito
       image_url: resizeVtexImage(item == null ? void 0 : item.image) || resizeVtexImage(item == null ? void 0 : item.imageUrl) || null
@@ -681,9 +845,14 @@ async function itemsFromList(context) {
 }
 
 // src/params/resolvers/items/fromPdp.ts
-async function itemsFromPDP(context) {
+async function itemsFromPDP(context, event) {
   var _a, _b, _c, _d;
   const { item, value, brand } = context;
+  const resolvedListName = resolveItemListName({ event, item, itemListName: null });
+  const resolvedItemId = resolveItemId(item);
+  if (event === "VIEW_ITEM") {
+    saveViewedItem(resolvedItemId, resolvedListName);
+  }
   return [
     {
       price: value || 0,
@@ -700,7 +869,8 @@ async function itemsFromPDP(context) {
       item_sku: (item == null ? void 0 : item.sku) || (item == null ? void 0 : item.productId) || null,
       item_url: (item == null ? void 0 : item.url) || (item == null ? void 0 : item.item_url) || (item == null ? void 0 : item.link) || null,
       image_url: resizeVtexImage(item == null ? void 0 : item.image) || resizeVtexImage(item == null ? void 0 : item.imageUrl) || null,
-      seller_id: (item == null ? void 0 : item.seller) || null
+      seller_id: (item == null ? void 0 : item.seller) || null,
+      item_list_name: resolvedListName
     }
   ];
 }
@@ -743,11 +913,15 @@ function getItems(context, eventName) {
     case "REMOVE_FROM_CART":
       return itemsFromItem(context, eventName);
     case "SELECT_ITEM":
+      return itemsFromList(context).then((items) => {
+        persistSelectItemOriginFromResolvedItems(items, context);
+        return items;
+      });
     case "VIEW_ITEM_LIST":
       return itemsFromList(context);
     case "VIEW_ITEM":
     case "CUSTOM_VIEW_ITEM":
-      return itemsFromPDP(context);
+      return itemsFromPDP(context, eventName);
     case "VIEW_PROMOTION":
     case "SELECT_PROMOTION":
       return itemsFromBanner(context);