@mfeflow/analytics 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @mfeflow/analytics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Analytics for micro-frontends behind one provider interface. The shell starts it once; remotes only send events. Ships a Google Tag Manager provider with Consent Mode v2, a typed event map each remote extends, a tracker that stamps `mfe_name` and `mfe_version`, and React bindings.
+
+## Install
+
+```sh
+pnpm add @mfeflow/analytics
+```
+
+`react` (19) is an optional peer dependency, needed only for `@mfeflow/analytics/react`. In a project made with mfeflow, `mfeflow add analytics-gtm` does all of this.
+
+## Usage
+
+```ts
+// shell, once
+import { initAnalytics } from '@mfeflow/analytics';
+import { createGtmProvider } from '@mfeflow/analytics/gtm';
+
+initAnalytics(createGtmProvider({ containerId: 'GTM-ABC123' }));
+```
+
+```ts
+// a remote
+import { createTracker } from '@mfeflow/analytics';
+
+declare module '@mfeflow/analytics' {
+  interface AnalyticsEvents {
+    add_to_cart: { sku: string };
+  }
+}
+
+export const tracker = createTracker('cart', { events: ['add_to_cart'] });
+tracker.track('add_to_cart', { sku: 'A1' });
+```
+
+The GTM provider pushes the four consent signals as `denied` to `dataLayer` before it requests `gtm.js`, and drops parameters that look like personal data.
+
+## Module Federation sharing
+
+Bucket: **singleton**. Share `@mfeflow/analytics` and `@mfeflow/analytics/react` (`@mfeflow/rsbuild` does). State also lives on `globalThis`, so a second copy still talks to the one provider. `@mfeflow/analytics/gtm` is imported by the shell only.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/consent.d.ts

@@ -0,0 +1,8 @@
+import { type ConsentUpdate } from './types.js';
+export declare const CONSENT_STORAGE_KEY = "mfeflow:consent";
+export declare const GRANT_ALL: ConsentUpdate;
+export declare const DENY_ALL: ConsentUpdate;
+/** Keeps only the known signals with a valid value; anything else in stored or passed-in data is dropped. */
+export declare function cleanConsent(input: unknown): ConsentUpdate;
+export declare function readStoredConsent(): ConsentUpdate;
+export declare function writeStoredConsent(consent: ConsentUpdate): void;

package/dist/consent.js

@@ -0,0 +1,38 @@
+import { CONSENT_KEYS } from "./types.js";
+const CONSENT_STORAGE_KEY = 'mfeflow:consent';
+const GRANT_ALL = {
+    ad_storage: 'granted',
+    analytics_storage: 'granted',
+    ad_user_data: 'granted',
+    ad_personalization: 'granted'
+};
+const DENY_ALL = {
+    ad_storage: 'denied',
+    analytics_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied'
+};
+const isValue = (value)=>'granted' === value || 'denied' === value;
+function cleanConsent(input) {
+    const out = {};
+    if ('object' != typeof input || null === input) return out;
+    for (const key of CONSENT_KEYS){
+        const value = Reflect.get(input, key);
+        if (isValue(value)) out[key] = value;
+    }
+    return out;
+}
+function readStoredConsent() {
+    try {
+        const raw = localStorage.getItem(CONSENT_STORAGE_KEY);
+        return null === raw ? {} : cleanConsent(JSON.parse(raw));
+    } catch  {
+        return {};
+    }
+}
+function writeStoredConsent(consent) {
+    try {
+        localStorage.setItem(CONSENT_STORAGE_KEY, JSON.stringify(consent));
+    } catch  {}
+}
+export { CONSENT_STORAGE_KEY, DENY_ALL, GRANT_ALL, cleanConsent, readStoredConsent, writeStoredConsent };

package/dist/core.d.ts

@@ -0,0 +1,22 @@
+import type { AnalyticsProvider, ConsentUpdate, EventParams } from './types.js';
+/**
+ * Starts analytics with a provider. Only the shell calls this. The first call wins; later calls
+ * (a second mount, StrictMode, a remote running on its own) do nothing and return false.
+ */
+export declare function initAnalytics(provider: AnalyticsProvider): boolean;
+export declare function isAnalyticsReady(): boolean;
+export declare function providerName(): string;
+export declare function track(event: string, params?: EventParams): void;
+export declare function page(path: string, params?: EventParams): void;
+/** Like `page`, but skips a path that was just sent: navigation and StrictMode can ask twice. */
+export declare function pageOnce(path: string, params?: EventParams): void;
+export declare function identify(userId: string, traits?: EventParams): void;
+/** The visitor's consent choice so far. A new object whenever it changes. */
+export declare function getConsent(): ConsentUpdate;
+/** Whether the visitor has made a choice, on this visit or an earlier one. */
+export declare function hasConsentChoice(): boolean;
+export declare function subscribeConsent(listener: () => void): () => void;
+/** Records the visitor's choice, remembers it for next time and tells the provider. */
+export declare function updateConsent(update: ConsentUpdate): void;
+/** Only for tests: forgets the provider, the queue and the stored choice. */
+export declare function resetAnalyticsForTests(): void;

package/dist/core.js

@@ -0,0 +1,96 @@
+import { CONSENT_STORAGE_KEY, cleanConsent, readStoredConsent, writeStoredConsent } from "./consent.js";
+import { noopProvider } from "./noop.js";
+const KEY = Symbol.for('mfeflow.analytics');
+const QUEUE_LIMIT = 100;
+function isState(value) {
+    return 'object' == typeof value && null !== value && 'queue' in value && 'listeners' in value;
+}
+function state() {
+    const existing = Reflect.get(globalThis, KEY);
+    if (isState(existing)) return existing;
+    const fresh = {
+        provider: void 0,
+        queue: [],
+        consent: readStoredConsent(),
+        listeners: new Set(),
+        lastPage: void 0
+    };
+    Reflect.set(globalThis, KEY, fresh);
+    return fresh;
+}
+function send(call) {
+    const s = state();
+    if (s.provider) call(s.provider);
+    else if (s.queue.length < QUEUE_LIMIT) s.queue.push(call);
+}
+function initAnalytics(provider) {
+    const s = state();
+    if (s.provider) return false;
+    s.provider = provider;
+    provider.init({
+        ...s.consent
+    });
+    const queued = s.queue.splice(0);
+    for (const call of queued)call(provider);
+    return true;
+}
+function isAnalyticsReady() {
+    return void 0 !== state().provider;
+}
+function providerName() {
+    return state().provider?.name ?? noopProvider.name;
+}
+function track(event, params = {}) {
+    send((p)=>{
+        p.track(event, params);
+    });
+}
+function page(path, params = {}) {
+    send((p)=>{
+        p.page(path, params);
+    });
+}
+function pageOnce(path, params = {}) {
+    const s = state();
+    if (s.lastPage === path) return;
+    s.lastPage = path;
+    page(path, params);
+}
+function identify(userId, traits = {}) {
+    send((p)=>{
+        p.identify(userId, traits);
+    });
+}
+function getConsent() {
+    return state().consent;
+}
+function hasConsentChoice() {
+    return Object.keys(state().consent).length > 0;
+}
+function subscribeConsent(listener) {
+    const { listeners } = state();
+    listeners.add(listener);
+    return ()=>{
+        listeners.delete(listener);
+    };
+}
+function updateConsent(update) {
+    const s = state();
+    const clean = cleanConsent(update);
+    s.consent = {
+        ...s.consent,
+        ...clean
+    };
+    writeStoredConsent(s.consent);
+    send((p)=>{
+        p.setConsent(clean);
+    });
+    for (const listener of s.listeners)listener();
+}
+function resetAnalyticsForTests() {
+    Reflect.deleteProperty(globalThis, KEY);
+    try {
+        localStorage.removeItem(CONSENT_STORAGE_KEY);
+    } catch  {}
+}
+export { getConsent, hasConsentChoice, identify, initAnalytics, isAnalyticsReady, page, pageOnce, providerName, resetAnalyticsForTests, subscribeConsent, track, updateConsent };

package/dist/gtm.d.ts

@@ -0,0 +1,29 @@
+import { type AnalyticsProvider, type ConsentUpdate } from './types.js';
+import { scrubPii } from './pii.js';
+export { scrubPii };
+export interface GtmOptions {
+    /** The container, e.g. `GTM-ABC123`. From the runtime config, never baked into the bundle. */
+    containerId: string;
+    /** Default `dataLayer`. */
+    dataLayerName?: string | undefined;
+    /** Default Google's `gtm.js`. Tests and server-side containers point it elsewhere. */
+    scriptUrl?: string | undefined;
+    /** Consent before the visitor chooses. Default: every signal `denied`. */
+    consentDefaults?: ConsentUpdate | undefined;
+    /** How long tags wait for a consent update, in milliseconds. Default 500. */
+    waitForUpdate?: number | undefined;
+    /** Send `user_id` on `identify`. Off by default; traits are never sent. */
+    sendUserId?: boolean | undefined;
+    /** Send parameters that look like personal data. Off by default: they are dropped. */
+    allowPii?: boolean | undefined;
+}
+export declare const GTM_SCRIPT_URL = "https://www.googletagmanager.com/gtm.js";
+export declare const GTM_SCRIPT_ATTRIBUTE = "data-mfeflow-gtm";
+/** The longest a `page_view` waits for the new route to set `document.title`, in milliseconds. */
+export declare const TITLE_WAIT_MS = 300;
+/**
+ * Google Tag Manager with Consent Mode v2. `init` pushes the consent defaults to the data layer
+ * before it adds the `gtm.js` script, so tags never run ahead of the visitor's choice. A second
+ * `init` for the same container (a second provider, StrictMode) finds the script tag and changes nothing.
+ */
+export declare function createGtmProvider(options: GtmOptions): AnalyticsProvider;

package/dist/gtm.js

@@ -0,0 +1,101 @@
+import { CONSENT_KEYS } from "./types.js";
+import { scrubPii } from "./pii.js";
+import { warnOnce } from "./validate.js";
+const CONTAINER_ID = /^GTM-[A-Z0-9]{4,12}$/;
+const GTM_SCRIPT_URL = 'https://www.googletagmanager.com/gtm.js';
+const GTM_SCRIPT_ATTRIBUTE = 'data-mfeflow-gtm';
+const TITLE_WAIT_MS = 300;
+function settledTitle(send) {
+    const before = document.title;
+    let observer;
+    let timer;
+    const finish = ()=>{
+        observer?.disconnect();
+        clearTimeout(timer);
+        send(document.title);
+    };
+    if ('function' == typeof MutationObserver) {
+        observer = new MutationObserver(()=>{
+            if (document.title !== before) finish();
+        });
+        observer.observe(document.head, {
+            childList: true,
+            subtree: true,
+            characterData: true
+        });
+    }
+    timer = setTimeout(finish, TITLE_WAIT_MS);
+}
+function layerOf(name) {
+    const existing = Reflect.get(globalThis, name);
+    if (Array.isArray(existing)) return existing;
+    const fresh = [];
+    Reflect.set(globalThis, name, fresh);
+    return fresh;
+}
+function createGtmProvider(options) {
+    const { containerId } = options;
+    if (!CONTAINER_ID.test(containerId)) throw new Error(`"${containerId}" is not a Tag Manager container id (expected GTM-XXXXXXX)`);
+    const layerName = options.dataLayerName ?? 'dataLayer';
+    const layer = ()=>layerOf(layerName);
+    function gtag() {
+        layer().push(arguments);
+    }
+    const defaults = {};
+    for (const key of CONSENT_KEYS)defaults[key] = options.consentDefaults?.[key] ?? 'denied';
+    defaults['wait_for_update'] = options.waitForUpdate ?? 500;
+    return {
+        name: 'gtm',
+        init (consent) {
+            const selector = `script[${GTM_SCRIPT_ATTRIBUTE}="${containerId}"]`;
+            if (document.querySelector(selector)) return;
+            gtag('consent', 'default', defaults);
+            if (Object.keys(consent).length > 0) gtag('consent', 'update', consent);
+            layer().push({
+                'gtm.start': Date.now(),
+                event: 'gtm.js'
+            });
+            const script = document.createElement("script");
+            script.async = true;
+            script.setAttribute(GTM_SCRIPT_ATTRIBUTE, containerId);
+            const url = new URL(options.scriptUrl ?? GTM_SCRIPT_URL, location.href);
+            url.searchParams.set('id', containerId);
+            if ('dataLayer' !== layerName) url.searchParams.set('l', layerName);
+            script.src = url.href;
+            document.head.append(script);
+        },
+        track (event, params) {
+            const { clean, dropped } = true === options.allowPii ? {
+                clean: params,
+                dropped: []
+            } : scrubPii(params);
+            if (dropped.length > 0) warnOnce(`"${event}": dropped ${dropped.join(', ')} because it looks like personal data`);
+            layer().push({
+                ...clean,
+                event
+            });
+        },
+        page (path, params) {
+            const pageLocation = location.origin + path;
+            settledTitle((title)=>{
+                layer().push({
+                    ...params,
+                    event: 'page_view',
+                    page_path: path,
+                    page_location: pageLocation,
+                    page_title: title
+                });
+            });
+        },
+        identify (userId) {
+            if (true === options.sendUserId) layer().push({
+                event: 'identify',
+                user_id: userId
+            });
+        },
+        setConsent (update) {
+            if (Object.keys(update).length > 0) gtag('consent', 'update', update);
+        }
+    };
+}
+export { GTM_SCRIPT_ATTRIBUTE, GTM_SCRIPT_URL, TITLE_WAIT_MS, createGtmProvider, scrubPii };

package/dist/history.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Calls `listener` with the new path whenever the page navigates without a reload: `pushState`,
+ * `replaceState`, back/forward and hash changes. The path carries the query string and a hash
+ * route, with personal data removed (see `currentPath`). Works with any router. The first call
+ * patches `history` once.
+ */
+export declare function onNavigate(listener: (path: string) => void): () => void;

package/dist/history.js

@@ -0,0 +1,32 @@
+import { currentPath } from "./url.js";
+const EVENT = 'mfeflow:navigate';
+const PATCHED = Symbol.for('mfeflow.history-patched');
+function patchHistory() {
+    if (true === Reflect.get(history, PATCHED)) return;
+    Reflect.set(history, PATCHED, true);
+    for (const method of [
+        'pushState',
+        'replaceState'
+    ]){
+        const original = history[method].bind(history);
+        history[method] = (...args)=>{
+            original(...args);
+            dispatchEvent(new Event(EVENT));
+        };
+    }
+}
+function onNavigate(listener) {
+    patchHistory();
+    const handle = ()=>{
+        listener(currentPath());
+    };
+    addEventListener(EVENT, handle);
+    addEventListener('popstate', handle);
+    addEventListener('hashchange', handle);
+    return ()=>{
+        removeEventListener(EVENT, handle);
+        removeEventListener('popstate', handle);
+        removeEventListener('hashchange', handle);
+    };
+}
+export { onNavigate };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Every event the platform knows, with its parameters. Empty here: each remote adds its own
+ * by declaration merging, so `tracker.track('add_to_cart', { sku })` is checked end to end.
+ *
+ *   declare module '@mfeflow/analytics' {
+ *     interface AnalyticsEvents {
+ *       add_to_cart: { sku: string };
+ *       cart_viewed: undefined;
+ *     }
+ *   }
+ */
+export interface AnalyticsEvents {
+}
+export { getConsent, hasConsentChoice, identify, initAnalytics, isAnalyticsReady, page, pageOnce, providerName, resetAnalyticsForTests, subscribeConsent, track, updateConsent, } from './core.js';
+export { CONSENT_STORAGE_KEY, DENY_ALL, GRANT_ALL, cleanConsent } from './consent.js';
+export { createRecordingProvider, noopProvider, type RecordedCall } from './noop.js';
+export { createTracker, type EventName, type ParamsArg, type Tracker, type TrackerOptions, } from './tracker.js';
+export { CONSENT_KEYS, type AnalyticsProvider, type ConsentKey, type ConsentUpdate, type ConsentValue, type EventParams, } from './types.js';
+export { resetWarningsForTests } from './validate.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { getConsent, hasConsentChoice, identify, initAnalytics, isAnalyticsReady, page, pageOnce, providerName, resetAnalyticsForTests, subscribeConsent, track, updateConsent } from "./core.js";
+export { CONSENT_STORAGE_KEY, DENY_ALL, GRANT_ALL, cleanConsent } from "./consent.js";
+export { createRecordingProvider, noopProvider } from "./noop.js";
+export { createTracker } from "./tracker.js";
+export { CONSENT_KEYS } from "./types.js";
+export { resetWarningsForTests } from "./validate.js";

package/dist/noop.d.ts

@@ -0,0 +1,25 @@
+import type { AnalyticsProvider, ConsentUpdate, EventParams } from './types.js';
+export declare const noopProvider: AnalyticsProvider;
+export type RecordedCall = {
+    type: 'init';
+    consent: ConsentUpdate;
+} | {
+    type: 'track';
+    event: string;
+    params: EventParams;
+} | {
+    type: 'page';
+    path: string;
+    params: EventParams;
+} | {
+    type: 'identify';
+    userId: string;
+    traits: EventParams;
+} | {
+    type: 'consent';
+    update: ConsentUpdate;
+};
+/** A provider for tests: it sends nothing and remembers every call in order. */
+export declare function createRecordingProvider(): AnalyticsProvider & {
+    calls: RecordedCall[];
+};

package/dist/noop.js

@@ -0,0 +1,49 @@
+const noopProvider = {
+    name: 'noop',
+    init () {},
+    track () {},
+    page () {},
+    identify () {},
+    setConsent () {}
+};
+function createRecordingProvider() {
+    const calls = [];
+    return {
+        name: 'recording',
+        calls,
+        init (consent) {
+            calls.push({
+                type: 'init',
+                consent
+            });
+        },
+        track (event, params) {
+            calls.push({
+                type: 'track',
+                event,
+                params
+            });
+        },
+        page (path, params) {
+            calls.push({
+                type: 'page',
+                path,
+                params
+            });
+        },
+        identify (userId, traits) {
+            calls.push({
+                type: 'identify',
+                userId,
+                traits
+            });
+        },
+        setConsent (update) {
+            calls.push({
+                type: 'consent',
+                update
+            });
+        }
+    };
+}
+export { createRecordingProvider, noopProvider };

package/dist/pii.d.ts

@@ -0,0 +1,6 @@
+import type { EventParams } from './types.js';
+/** Drops personal data from event parameters, and says what it dropped. */
+export declare function scrubPii(params: EventParams): {
+    clean: EventParams;
+    dropped: string[];
+};

package/dist/pii.js

@@ -0,0 +1,13 @@
+const PII_KEY = /^(e-?mail|phone|mobile|first_?name|last_?name|full_?name|name|address|ssn|dob|birth_?date|password|token)$/i;
+const EMAIL = /[^\s@]+@[^\s@]+\.[^\s@]+/;
+function scrubPii(params) {
+    const clean = {};
+    const dropped = [];
+    for (const [key, value] of Object.entries(params))if (PII_KEY.test(key) || 'string' == typeof value && EMAIL.test(value)) dropped.push(key);
+    else clean[key] = value;
+    return {
+        clean,
+        dropped
+    };
+}
+export { scrubPii };

package/dist/react.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import { type EventName, type ParamsArg, type Tracker, type TrackerOptions } from './tracker.js';
+import type { ConsentUpdate } from './types.js';
+export interface AnalyticsProviderProps {
+    children: ReactNode;
+    /** Send a `page_view` for the first page and for every navigation. Default true. */
+    pageViews?: boolean;
+}
+/**
+ * The shell wraps its app in this once. It sends `page_view` on route changes, once per path
+ * even when React runs effects twice, and lets `useTracker` tell a missing shell from a ready one.
+ */
+export declare function AnalyticsProvider({ children, pageViews }: AnalyticsProviderProps): import("react").JSX.Element;
+/** The tracker for a remote. The same tracker comes back on every render. */
+export declare function useTracker(mfeName: string, options?: TrackerOptions): Tracker;
+/** Sends an event once when the component mounts. Safe under StrictMode, which runs effects twice. */
+export declare function useTrackOnMount<E extends EventName>(tracker: Tracker, event: E, ...params: ParamsArg<E>): void;
+export interface ConsentApi {
+    consent: ConsentUpdate;
+    /** Whether the visitor has chosen yet. Show the banner while this is false. */
+    decided: boolean;
+    update: (update: ConsentUpdate) => void;
+    acceptAll: () => void;
+    rejectAll: () => void;
+}
+/** Headless consent state for your own banner. */
+export declare function useConsent(): ConsentApi;

package/dist/react.js

@@ -0,0 +1,63 @@
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { DENY_ALL, GRANT_ALL } from "./consent.js";
+import { getConsent, pageOnce, subscribeConsent, updateConsent } from "./core.js";
+import { onNavigate } from "./history.js";
+import { currentPath } from "./url.js";
+import { createTracker } from "./tracker.js";
+import { warnOnce } from "./validate.js";
+const Mounted = /*#__PURE__*/ createContext(false);
+function sendPageView(path) {
+    pageOnce(path, {
+        mfe_name: 'shell',
+        mfe_version: null
+    });
+}
+function AnalyticsProvider({ children, pageViews = true }) {
+    useEffect(()=>{
+        if (!pageViews) return;
+        sendPageView(currentPath());
+        return onNavigate(sendPageView);
+    }, [
+        pageViews
+    ]);
+    return /*#__PURE__*/ jsx(Mounted, {
+        value: true,
+        children: children
+    });
+}
+function useTracker(mfeName, options) {
+    const mounted = useContext(Mounted);
+    useEffect(()=>{
+        if (!mounted) warnOnce(`${mfeName}: no <AnalyticsProvider> above this component. Running outside the shell? Events wait for analytics to start and are dropped if it never does.`);
+    }, [
+        mounted,
+        mfeName
+    ]);
+    return useMemo(()=>createTracker(mfeName, options), [
+        mfeName
+    ]);
+}
+function useTrackOnMount(tracker, event, ...params) {
+    const sent = useRef(false);
+    useEffect(()=>{
+        if (sent.current) return;
+        sent.current = true;
+        tracker.track(event, ...params);
+    }, []);
+}
+function useConsent() {
+    const consent = useSyncExternalStore(subscribeConsent, getConsent, getConsent);
+    return {
+        consent,
+        decided: Object.keys(consent).length > 0,
+        update: updateConsent,
+        acceptAll: ()=>{
+            updateConsent(GRANT_ALL);
+        },
+        rejectAll: ()=>{
+            updateConsent(DENY_ALL);
+        }
+    };
+}
+export { AnalyticsProvider, useConsent, useTrackOnMount, useTracker };

package/dist/tracker.d.ts

@@ -0,0 +1,22 @@
+import type { AnalyticsEvents } from './index.js';
+export type EventName = Extract<keyof AnalyticsEvents, string>;
+/** Events that take no parameters are called as `track('name')`; the rest as `track('name', { … })`. */
+export type ParamsArg<E extends EventName> = AnalyticsEvents[E] extends undefined | void ? [params?: undefined] : [params: AnalyticsEvents[E]];
+export interface TrackerOptions {
+    /** Version of the remote, sent as `mfe_version`. */
+    mfeVersion?: string | undefined;
+    /** Every event this remote sends. In development, any other name logs a warning once. */
+    events?: readonly EventName[] | undefined;
+}
+export interface Tracker {
+    /** The micro-frontend this tracker belongs to. */
+    readonly mfe: string;
+    track<E extends EventName>(event: E, ...params: ParamsArg<E>): void;
+    page(path: string): void;
+}
+/**
+ * A tracker for one micro-frontend. Every event it sends carries `mfe_name` and `mfe_version`
+ * (`null` when unknown). They are flat and always both set: the data layer merges nested objects,
+ * and an object or a missing key would leave the previous remote's value on this remote's event.
+ */
+export declare function createTracker(mfeName: string, options?: TrackerOptions): Tracker;

package/dist/tracker.js

@@ -0,0 +1,26 @@
+import { page, track } from "./core.js";
+import { eventProblem, isDev, warnOnce } from "./validate.js";
+const isParams = (value)=>'object' == typeof value && null !== value;
+function createTracker(mfeName, options = {}) {
+    const known = options.events ? new Set(options.events) : void 0;
+    const stamp = (params)=>({
+            ...params,
+            mfe_name: mfeName,
+            mfe_version: options.mfeVersion ?? null
+        });
+    return {
+        mfe: mfeName,
+        track (event, ...rest) {
+            if (isDev()) {
+                const problem = eventProblem(mfeName, event, known);
+                if (problem) warnOnce(problem);
+            }
+            const params = rest[0];
+            track(event, stamp(isParams(params) ? params : void 0));
+        },
+        page (path) {
+            page(path, stamp());
+        }
+    };
+}
+export { createTracker };

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export type EventParams = Record<string, unknown>;
+/** The four Consent Mode v2 signals. */
+export type ConsentKey = 'ad_storage' | 'analytics_storage' | 'ad_user_data' | 'ad_personalization';
+export type ConsentValue = 'granted' | 'denied';
+export type ConsentUpdate = Partial<Record<ConsentKey, ConsentValue>>;
+export declare const CONSENT_KEYS: readonly ConsentKey[];
+export interface AnalyticsProvider {
+    readonly name: string;
+    /** Called once. `consent` is the choice the visitor made on an earlier visit, if any. */
+    init(consent: ConsentUpdate): void;
+    track(event: string, params: EventParams): void;
+    page(path: string, params: EventParams): void;
+    identify(userId: string, traits: EventParams): void;
+    setConsent(update: ConsentUpdate): void;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+const CONSENT_KEYS = [
+    'ad_storage',
+    'analytics_storage',
+    'ad_user_data',
+    'ad_personalization'
+];
+export { CONSENT_KEYS };

package/dist/url.d.ts

@@ -0,0 +1,7 @@
+/** A query string with personal data and secrets removed. Returns `''` or a string starting with `?`. */
+export declare function scrubQuery(query: string): string;
+/**
+ * Where the visitor is, as a path for `page_view`: the pathname, the query without personal data,
+ * and for hash routers (`/#/catalog?x=1`) the hash route the same way. Never anything else of the hash.
+ */
+export declare function currentPath(): string;

package/dist/url.js

@@ -0,0 +1,34 @@
+import { scrubPii } from "./pii.js";
+const KEEP = /^(utm_[a-z_]+|gclid|fbclid)$/i;
+const SECRET = /token|secret|passw(or)?d|auth|session|api_?key|^key$|^code$/i;
+function scrubQuery(query) {
+    const kept = new URLSearchParams();
+    for (const [key, value] of new URLSearchParams(query)){
+        const pii = scrubPii({
+            [key]: value
+        }).dropped.length > 0;
+        if (KEEP.test(key) ? !pii : !(pii || SECRET.test(key))) kept.append(key, value);
+    }
+    const text = kept.toString();
+    return '' === text ? '' : `?${text}`;
+}
+const split = (text)=>{
+    const at = text.indexOf('?');
+    return -1 === at ? [
+        text,
+        ''
+    ] : [
+        text.slice(0, at),
+        text.slice(at)
+    ];
+};
+function currentPath() {
+    const { pathname, search, hash } = location;
+    let path = pathname + scrubQuery(search);
+    if (hash.startsWith('#/')) {
+        const [route, query] = split(hash.slice(1));
+        path += `#${route}${scrubQuery(query)}`;
+    }
+    return path;
+}
+export { currentPath, scrubQuery };

package/dist/validate.d.ts

@@ -0,0 +1,7 @@
+/** Dev builds warn about mistakes; production builds stay quiet. Bundlers replace `process.env.NODE_ENV`. */
+export declare const isDev: () => boolean;
+export declare function warnOnce(message: string): void;
+/** What is wrong with an event, or undefined. `known` is the tracker's declared list, if it has one. */
+export declare function eventProblem(mfe: string, event: string, known: ReadonlySet<string> | undefined): string | undefined;
+/** Only for tests. */
+export declare function resetWarningsForTests(): void;

package/dist/validate.js

@@ -0,0 +1,18 @@
+const EVENT_NAME = /^[a-z][a-z0-9_]{0,39}$/i;
+const warned = new Set();
+const isDev = ()=>'production' !== process.env.NODE_ENV;
+function warnOnce(message) {
+    if (!isDev() || warned.has(message)) return;
+    warned.add(message);
+    console.warn(`[mfeflow/analytics] ${message}`);
+}
+function eventProblem(mfe, event, known) {
+    if (!EVENT_NAME.test(event)) return `${mfe}: "${event}" is not a valid event name (letters, digits and underscores, starting with a letter, at most 40 characters)`;
+    if (known && !known.has(event)) return `${mfe}: "${event}" is not one of the events this tracker declares (${[
+        ...known
+    ].join(', ') || 'none'}); add it to analytics.ts`;
+}
+function resetWarningsForTests() {
+    warned.clear();
+}
+export { eventProblem, isDev, resetWarningsForTests, warnOnce };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@mfeflow/analytics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Analytics for micro-frontends behind one provider interface: typed events, a tracker that stamps mfe_name, Consent Mode v2, and a Google Tag Manager provider.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "analytics",
+    "google-tag-manager",
+    "consent-mode"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/analytics"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./gtm": {
+      "types": "./dist/gtm.d.ts",
+      "import": "./dist/gtm.js",
+      "default": "./dist/gtm.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }