@formo/analytics 1.32.0 → 1.33.0

package/dist/esm/src/FormoAnalytics.js

@@ -66,6 +66,7 @@ import { detectInjectedProviderInfo, isValidProvider } from "./provider";
 import { FormoAnalyticsSession, SESSION_WALLET_DETECTED_KEY, SESSION_WALLET_IDENTIFIED_KEY, } from "./session";
 import { SignatureStatus, TransactionStatus, WRAPPED_REQUEST_SYMBOL, WRAPPED_REQUEST_REF_SYMBOL, } from "./types";
 import { validateAddress, validateAndChecksumAddress } from "./utils/address";
+import { getTimezone } from "./utils/timezone";
 import { isLocalhost } from "./validators";
 import { parseChainId } from "./utils/chain";
 import { WagmiEventHandler } from "./wagmi";
@@ -391,6 +392,14 @@ var FormoAnalytics = /** @class */ (function () {
                             logger.warn("Connect: Invalid address provided (\"".concat(address, "\"). Please provide a valid EVM or Solana address."));
                             return [2 /*return*/];
                         }
+                        // connect() persists wallet/chain state (active-wallet cookie,
+                        // currentAddress/currentChainId) before trackEvent's consent check —
+                        // gate the whole method so a suppressed visitor or excluded environment
+                        // (opt-out / timezone / host / path) leaves no session state.
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("connect() skipped: tracking is suppressed for this visitor or environment");
+                            return [2 /*return*/];
+                        }
                         this.setChainState(chainId, { address: validAddress });
                         return [4 /*yield*/, this.trackEvent(EventType.CONNECT, {
                                 chainId: chainId,
@@ -578,10 +587,11 @@ var FormoAnalytics = /** @class */ (function () {
                     case 0:
                         _d.trys.push([0, 12, , 13]);
                         // identify() writes the user-id cookie and marks wallet
-                        // identification before trackEvent's consent check — gate the
-                        // whole method so an opted-out user gets no identity persistence.
-                        if (this.hasOptedOutTracking()) {
-                            logger.info("identify() skipped: user has opted out of tracking");
+                        // identification before trackEvent's consent check — gate the whole
+                        // method so a suppressed visitor or excluded environment (opt-out /
+                        // timezone / host / path) gets no identity persistence.
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("identify() skipped: tracking is suppressed for this visitor or environment");
                             return [2 /*return*/];
                         }
                         if (!!params) return [3 /*break*/, 10];
@@ -709,9 +719,10 @@ var FormoAnalytics = /** @class */ (function () {
                 switch (_c.label) {
                     case 0:
                         // detect() marks wallet detection (a cookie write) before
-                        // trackEvent's consent check — gate it on opt-out.
-                        if (this.hasOptedOutTracking()) {
-                            logger.info("detect() skipped: user has opted out of tracking");
+                        // trackEvent's consent check — gate it for a suppressed visitor or
+                        // excluded environment (opt-out / timezone / host / path).
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("detect() skipped: tracking is suppressed for this visitor or environment");
                             return [2 /*return*/];
                         }
                         if (this.session.isWalletDetected(rdns))
@@ -1075,9 +1086,16 @@ var FormoAnalytics = /** @class */ (function () {
                     case 26:
                         nextChainId = _a.sent();
                         wasDisconnected = !this._evmAddress;
-                        // CRITICAL: Always update state regardless of whether connect tracking is enabled
-                        // This ensures disconnect events will have valid address/chainId values
-                        this.setChainState('evm', { address: address, chainId: nextChainId });
+                        // Update state regardless of whether connect *event* tracking is enabled,
+                        // so disconnect events keep valid address/chainId values. (excludeChains is
+                        // NOT suppression — it still updates state so currentChainId can gate
+                        // events.)
+                        if (this.isTrackingSuppressed()) {
+                            this.clearStaleEvmWalletOnSwitchWhileSuppressed(address);
+                        }
+                        else {
+                            this.setChainState('evm', { address: address, chainId: nextChainId });
+                        }
                         providerInfo = this.getProviderInfo(provider);
                         effectiveChainId = nextChainId || 0;
                         if (this.isAutocaptureEnabled("connect")) {
@@ -1250,13 +1268,19 @@ var FormoAnalytics = /** @class */ (function () {
                                 this._provider = provider;
                             }
                             isActiveProvider = this._provider === provider;
-                            // CRITICAL: Always update state from active provider regardless of tracking config
-                            // This ensures disconnect events will have valid address/chainId values
+                            // Update state from active provider so disconnect events keep valid
+                            // address/chainId values — except while suppressed, where we must not
+                            // LEARN identity (only drop a stale EVM wallet on a switch).
                             if (isActiveProvider) {
-                                this.setChainState('evm', {
-                                    chainId: chainId,
-                                    address: validateAndChecksumAddress(address) || undefined,
-                                });
+                                if (this.isTrackingSuppressed()) {
+                                    this.clearStaleEvmWalletOnSwitchWhileSuppressed(address);
+                                }
+                                else {
+                                    this.setChainState('evm', {
+                                        chainId: chainId,
+                                        address: validateAndChecksumAddress(address) || undefined,
+                                    });
+                                }
                             }
                             // Conditionally emit connect event based on tracking configuration
                             if (isActiveProvider && this._evmAddress) {
@@ -1625,6 +1649,108 @@ var FormoAnalytics = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Visitor-level tracking suppression.
+     *
+     * Returns true when the SDK must not persist any identity/session/chain
+     * state or send any events for this visitor — i.e. an explicit opt-out or a
+     * jurisdiction/timezone exclusion. Public entry points that write state
+     * before reaching the `shouldTrack()` event gate (identify/connect/detect)
+     * check this first so suppressed visitors leave no cookies or session state.
+     * @returns {boolean} True if all tracking and persistence must be suppressed
+     */
+    FormoAnalytics.prototype.isTrackingSuppressed = function () {
+        return this.hasOptedOutTracking() || this.isCurrentEnvironmentExcluded();
+    };
+    /**
+     * Whether the current environment is excluded from tracking — the visitor's
+     * timezone, the current hostname, or the current pathname matches a
+     * configured exclusion.
+     *
+     * Timezone is visitor/session-level (stable for the session); host/path are
+     * current-page-level and transient — if a SPA navigates to an allowed path,
+     * tracking resumes for future actions. Used as the "do not write identity or
+     * send events" gate at every entry point that would persist state before the
+     * `shouldTrack()` event gate.
+     * @returns {boolean} True if the current environment is excluded
+     */
+    FormoAnalytics.prototype.isCurrentEnvironmentExcluded = function () {
+        return (this.isTimezoneExcluded() ||
+            this.isHostExcluded() ||
+            this.isPathExcluded());
+    };
+    /**
+     * Whether the current hostname matches a configured `tracking.excludeHosts`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current hostname is excluded
+     */
+    FormoAnalytics.prototype.isHostExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        if (typeof window === "undefined") {
+            return false;
+        }
+        var _a = tracking.excludeHosts, excludeHosts = _a === void 0 ? [] : _a;
+        return excludeHosts.includes(window.location.hostname);
+    };
+    /**
+     * Whether the current pathname matches a configured `tracking.excludePaths`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current pathname is excluded
+     */
+    FormoAnalytics.prototype.isPathExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        if (typeof window === "undefined") {
+            return false;
+        }
+        var _a = tracking.excludePaths, excludePaths = _a === void 0 ? [] : _a;
+        return excludePaths.includes(window.location.pathname);
+    };
+    /**
+     * Whether the current call is in a visitor-level suppression state — opt-out
+     * or excluded timezone — for which any persisted identity cookie should be
+     * actively purged (not merely skipped). Host/path exclusions are
+     * deliberately excluded here: they are transient current-page states, so a
+     * cookie legitimately written on an allowed page must survive a visit to an
+     * excluded route.
+     * @returns {boolean} True if persisted identity must be purged
+     */
+    FormoAnalytics.prototype.isPersistedIdentityPurgeRequired = function () {
+        return this.hasOptedOutTracking() || this.isTimezoneExcluded();
+    };
+    /**
+     * Whether the visitor's browser-resolved timezone matches a configured
+     * `tracking.excludeTimezones` entry (case-insensitive). Client-side and
+     * best-effort — see TrackingOptions.excludeTimezones.
+     * @returns {boolean} True if the current timezone is excluded
+     */
+    FormoAnalytics.prototype.isTimezoneExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        var _a = tracking.excludeTimezones, excludeTimezones = _a === void 0 ? [] : _a;
+        if (excludeTimezones.length === 0) {
+            return false;
+        }
+        var timezone = getTimezone();
+        if (!timezone) {
+            return false;
+        }
+        var lowerTimezone = timezone.toLowerCase();
+        return excludeTimezones.some(function (tz) { return typeof tz === "string" && tz.toLowerCase() === lowerTimezone; });
+    };
     /**
      * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
@@ -1642,20 +1768,11 @@ var FormoAnalytics = /** @class */ (function () {
         if (this.options.tracking !== null &&
             typeof this.options.tracking === "object" &&
             !Array.isArray(this.options.tracking)) {
-            var _a = this.options.tracking, _b = _a.excludeHosts, excludeHosts = _b === void 0 ? [] : _b, _c = _a.excludePaths, excludePaths = _c === void 0 ? [] : _c, _d = _a.excludeChains, excludeChains = _d === void 0 ? [] : _d;
-            // Check hostname exclusions - use exact matching
-            if (excludeHosts.length > 0 && typeof window !== "undefined") {
-                var hostname = window.location.hostname;
-                if (excludeHosts.includes(hostname)) {
-                    return false;
-                }
-            }
-            // Check path exclusions - use exact matching
-            if (excludePaths.length > 0 && typeof window !== "undefined") {
-                var pathname = window.location.pathname;
-                if (excludePaths.includes(pathname)) {
-                    return false;
-                }
+            var _a = this.options.tracking.excludeChains, excludeChains = _a === void 0 ? [] : _a;
+            // Environment exclusions (timezone / host / path) — no identify / connect
+            // / track events while excluded. Host/path are exact-match.
+            if (this.isCurrentEnvironmentExcluded()) {
+                return false;
             }
             // Check chainId exclusions
             if (excludeChains.length > 0 &&
@@ -2046,10 +2163,31 @@ var FormoAnalytics = /** @class */ (function () {
      * value in the normal way; existing connections are never clobbered.
      */
     FormoAnalytics.prototype.backfillActiveWallet = function (address, chainId) {
+        // Never learn identity while suppressed (opt-out / timezone / excluded host
+        // or path). A signature/transaction observed on an excluded route must not
+        // populate currentAddress for later allowed-page events. backfill only ever
+        // *adds* an address (it no-ops when one is already known), so there is no
+        // stale state to clear here.
+        if (this.isTrackingSuppressed())
+            return;
         if (this._evmAddress)
             return;
         this.setChainState('evm', { address: address, chainId: chainId });
     };
+    /**
+     * Apply an EVM autocapture connect/switch while tracking is suppressed
+     * (opt-out / timezone / excluded host or path): never LEARN the wallet, but
+     * if it is a switch away from an already-learned EVM wallet, drop the stale
+     * one (which also clears the active-wallet cookie) so it can't attach to a
+     * later allowed-page event.
+     */
+    FormoAnalytics.prototype.clearStaleEvmWalletOnSwitchWhileSuppressed = function (address) {
+        var evmAddress = this._chainState.evm.address;
+        var incoming = validateAndChecksumAddress(address);
+        if (evmAddress && incoming && incoming !== evmAddress) {
+            this.clearChainState('evm');
+        }
+    };
     /**
      * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
      */
@@ -2256,6 +2394,39 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.syncWalletState = function (params) {
         var chainId = params.chainId, address = params.address;
+        if (this.isTrackingSuppressed()) {
+            // While suppressed (opt-out / timezone / excluded host or path) we must
+            // never LEARN a new wallet — but we must still CLEAR stale identity.
+            // Otherwise a disconnect or wallet switch observed on a suppressed route
+            // would leave the previously-learned address in memory and in the
+            // active-wallet cookie, attaching it to later allowed-page events.
+            if (!address) {
+                // Disconnect: drop the affected namespace(s).
+                if (chainId !== undefined && chainId !== null) {
+                    this.clearChainState(chainId);
+                }
+                else {
+                    this.clearChainState("evm");
+                    this.clearChainState("solana");
+                }
+                return;
+            }
+            // Address present: a switch away from the wallet already learned in this
+            // namespace invalidates it. Drop the stale one without learning the new
+            // address; a fresh connect (nothing learned yet) or a re-confirmation of
+            // the same address is a no-op.
+            if (chainId === null || chainId === undefined)
+                return;
+            var namespace = this.getNamespace(chainId);
+            var namespaceAddress = this._chainState[namespace].address;
+            var validIncoming = validateAddress(address, chainId);
+            if (namespaceAddress &&
+                validIncoming &&
+                validIncoming !== namespaceAddress) {
+                this.clearChainState(chainId);
+            }
+            return;
+        }
         if (!address) {
             if (chainId !== undefined && chainId !== null) {
                 this.clearChainState(chainId);
@@ -2313,18 +2484,28 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.persistActiveWallet = function () {
         try {
-            // Never write an identity cookie for an opted-out user; ensure any
-            // prior snapshot is removed instead.
-            if (this.hasOptedOutTracking()) {
+            // Visitor-level suppression (opt-out or excluded timezone): purge any
+            // prior snapshot — these are stable for the session, so deletion is safe.
+            if (this.isPersistedIdentityPurgeRequired()) {
                 cookie().remove(ACTIVE_WALLET_KEY);
                 return;
             }
             if (this.currentAddress) {
+                // Current-page exclusion (host/path): do not write a new snapshot while
+                // on an excluded route, but leave any existing cookie intact. A cookie
+                // written on an allowed page must survive a transient visit to an
+                // excluded one (passive navigation does not call this method).
+                if (this.isHostExcluded() || this.isPathExcluded()) {
+                    return;
+                }
                 var value = JSON.stringify(__assign({ address: this.currentAddress }, (this.currentChainId !== undefined && { chainId: this.currentChainId })));
                 var domain = getIdentityCookieDomain(this.crossSubdomainCookies);
                 cookie().set(ACTIVE_WALLET_KEY, value, __assign(__assign({ path: "/", expires: new Date(Date.now() + ACTIVE_WALLET_TTL_MS).toUTCString() }, getIdentityCookieSecurity()), (domain ? { domain: domain } : {})));
             }
             else {
+                // No active wallet → clear the snapshot. This runs even on an excluded
+                // route, so a disconnect/switch observed while suppressed actively
+                // removes stale identity instead of leaving it for later allowed events.
                 cookie().remove(ACTIVE_WALLET_KEY);
             }
         }
@@ -2338,12 +2519,18 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.loadActiveWallet = function () {
         try {
-            // Never restore wallet identity into memory for an opted-out user
-            // (mirrors persistActiveWallet's guard); drop any stale snapshot.
-            if (this.hasOptedOutTracking()) {
+            // Visitor-level suppression (opt-out or excluded timezone): never restore
+            // identity into memory; drop the stale snapshot.
+            if (this.isPersistedIdentityPurgeRequired()) {
                 cookie().remove(ACTIVE_WALLET_KEY);
                 return;
             }
+            // Current-page exclusion (host/path): don't restore into memory while on
+            // an excluded route, but keep the cookie so a later allowed-page load can
+            // restore it.
+            if (this.isHostExcluded() || this.isPathExcluded()) {
+                return;
+            }
             var raw = cookie().get(ACTIVE_WALLET_KEY);
             if (!raw)
                 return;

package/dist/esm/src/event/EventFactory.js

@@ -55,7 +55,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 import { COUNTRY_LIST, LOCAL_ANONYMOUS_ID_KEY, SESSION_TRAFFIC_SOURCE_KEY, } from "../constants";
-import { toSnakeCase } from "../utils";
+import { toSnakeCase, getTimezone } from "../utils";
 import { validateAddress } from "../utils/address";
 import { getCurrentTimeFormatted } from "../utils/timestamp";
 import { isUndefined } from "../validators";
@@ -270,13 +270,7 @@ var EventFactory = /** @class */ (function () {
         return validateAddress(address, chainId) || null;
     };
     EventFactory.prototype.getTimezone = function () {
-        try {
-            return Intl.DateTimeFormat().resolvedOptions().timeZone;
-        }
-        catch (error) {
-            logger.error("Error resolving timezone:", error);
-            return "";
-        }
+        return getTimezone();
     };
     EventFactory.prototype.getLocation = function () {
         try {

package/dist/esm/src/types/base.d.ts

@@ -72,6 +72,20 @@ export interface TrackingOptions {
     excludeHosts?: string[];
     excludePaths?: string[];
     excludeChains?: ChainID[];
+    /**
+     * IANA timezone names to opt out of tracking entirely. When the visitor's
+     * resolved timezone (via `Intl.DateTimeFormat().resolvedOptions().timeZone`)
+     * matches one of these, no events are enqueued or sent — including `identify`
+     * and `connect`. Matched case-insensitively against the full timezone string.
+     *
+     * Note: this is client-side, timezone-derived geolocation. It is best-effort
+     * and can be bypassed (a VPN does not change the browser timezone, and users
+     * can change their OS timezone). For authoritative jurisdiction blocking, use
+     * server-side IP geolocation at your ingest endpoint instead.
+     *
+     * @example ["Europe/London", "America/New_York"]
+     */
+    excludeTimezones?: string[];
     /**
      * Additional query parameter names to strip from forwarded and stored URLs,
      * on top of a built-in always-on denylist (currently `privy_oauth_code`,

package/dist/esm/src/utils/index.d.ts

@@ -3,4 +3,5 @@ export * from "./base";
 export * from "./converter";
 export * from "./generate";
 export * from "./hash";
+export * from "./timezone";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/src/utils/index.js

@@ -3,4 +3,5 @@ export * from "./base";
 export * from "./converter";
 export * from "./generate";
 export * from "./hash";
+export * from "./timezone";
 //# sourceMappingURL=index.js.map

package/dist/esm/src/utils/timezone.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve the current IANA timezone (e.g. "Europe/London") via the Intl API.
+ * Returns "" when the timezone cannot be resolved (e.g. Intl unavailable).
+ */
+declare const getTimezone: () => string;
+export { getTimezone };
+//# sourceMappingURL=timezone.d.ts.map

package/dist/esm/src/utils/timezone.js

@@ -0,0 +1,16 @@
+import { logger } from "../logger";
+/**
+ * Resolve the current IANA timezone (e.g. "Europe/London") via the Intl API.
+ * Returns "" when the timezone cannot be resolved (e.g. Intl unavailable).
+ */
+var getTimezone = function () {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "";
+    }
+    catch (error) {
+        logger.error("Error resolving timezone:", error);
+        return "";
+    }
+};
+export { getTimezone };
+//# sourceMappingURL=timezone.js.map