@your-scope/activity-tracking

Noyau agnostique de tracking d’activité avec connecteurs plug-and-play (GTM, GA4, Console…).
Architecture middleware par connecteur : map(event) → transform(mapped) → send(transformed).

✨ Features

• Core agnostique (aucun nom d’event spécifique à un outil)
• Connecteurs modulaires, chacun avec config, mapping, transform, send
• Renommage d’event par connecteur (ex. page_load → page_view pour GA4)
• SPA navigation observer, Web Vitals (LCP/CLS/INP), JS error tracking, scroll depth
• ESM + CJS + Types fournis

📦 Installation

npm i @your-scope/activity-tracking
# ou
yarn add @your-scope/activity-tracking

🚀 Quickstart (ESM)

import { createActivityTracking } from "@your-scope/activity-tracking";
import { gtmConnector, ga4Connector } from "@your-scope/activity-tracking";

const AT = createActivityTracking();

AT.registerConnector(gtmConnector());
AT.registerConnector(ga4Connector());

AT.init({
  detectAdblock: true,
  trackWebVitals: true,
  trackSpaPages: true,
  connectors: {
    gtm: { enabled: true },
    ga4: {
      enabled: true,
      eventMap: { page_load: "page_view" },
      flattenUserActivity: true
    }
  }
});

// AT.sendEvent("click_product", { product_id: "SKU123" });

CommonJS

const pkg = require("@your-scope/activity-tracking");
const AT = pkg.createActivityTracking();

AT.registerConnector(pkg.gtmConnector());
AT.registerConnector(pkg.ga4Connector());

AT.init({ connectors: { gtm: { enabled: true }, ga4: { enabled: true } } });

🧱 Concept

• Core : gère l’identité/visite, la collecte, et dispatch chaque event vers tous les connecteurs actifs.
• Connecteur : encapsule la logique d’un outil cible (mapping d’events, transformation, envoi).

event (agnostique)
   └─> connector.map(evt)
          └─> connector.transform(mapped)
                 └─> connector.send(transformed)

🧩 Créer un connecteur custom (template)

import type { ConnectorPack } from "@your-scope/activity-tracking";

export function myConnector(): ConnectorPack {
  return {
    name: "myConnector",
    defaults: {
      enabled: true,
      eventMap: { page_load: "page_load" }
    },
    factory({ config, globalConfig }) {
      return {
        map(evt) {
          const name = (config.eventMap?.[evt.event]) ?? evt.event;
          return { ...evt, event: name };
        },
        transform(mapped) {
          return mapped;
        },
        async send(payload) {
          await fetch("https://api.example.com/collect", {
            method: "POST",
            headers: { "content-type": "application/json" },
            body: JSON.stringify(payload)
          });
        }
      };
    }
  };
}

📦 Build / Dev

• npm run build → ESM + CJS + types (tsup)
• npm run dev → watch
• npm run check → tsc --noEmit

📤 Publish via GitHub Actions

Crée le secret NPM_TOKEN, puis :

npm version patch   # ou minor/major
git push --follow-tags