@formo/analytics 1.35.2 → 1.36.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/src/FormoAnalytics.d.ts +79 -363
- package/dist/cjs/src/FormoAnalytics.js +368 -2234
- package/dist/cjs/src/event/EventManager.d.ts +3 -1
- package/dist/cjs/src/event/EventManager.js +5 -1
- package/dist/cjs/src/event/type.d.ts +1 -0
- package/dist/cjs/src/evm/EvmEventTracker.d.ts +175 -0
- package/dist/cjs/src/evm/EvmEventTracker.js +1030 -0
- package/dist/cjs/src/evm/EvmProviderRegistry.d.ts +132 -0
- package/dist/cjs/src/evm/EvmProviderRegistry.js +348 -0
- package/dist/cjs/src/evm/EvmRequestTracker.d.ts +120 -0
- package/dist/cjs/src/evm/EvmRequestTracker.js +756 -0
- package/dist/cjs/src/queue/EventQueue.d.ts +28 -0
- package/dist/cjs/src/queue/EventQueue.js +97 -19
- package/dist/cjs/src/queue/type.d.ts +1 -0
- package/dist/cjs/src/tracking/TrackingPolicy.d.ts +146 -0
- package/dist/cjs/src/tracking/TrackingPolicy.js +200 -0
- package/dist/cjs/src/validators/address.d.ts +1 -1
- package/dist/cjs/src/version.d.ts +1 -1
- package/dist/cjs/src/version.js +1 -1
- package/dist/cjs/src/wallet/WalletStateStore.d.ts +223 -0
- package/dist/cjs/src/wallet/WalletStateStore.js +515 -0
- package/dist/esm/src/FormoAnalytics.d.ts +79 -363
- package/dist/esm/src/FormoAnalytics.js +369 -2235
- package/dist/esm/src/event/EventManager.d.ts +3 -1
- package/dist/esm/src/event/EventManager.js +5 -1
- package/dist/esm/src/event/type.d.ts +1 -0
- package/dist/esm/src/evm/EvmEventTracker.d.ts +175 -0
- package/dist/esm/src/evm/EvmEventTracker.js +1027 -0
- package/dist/esm/src/evm/EvmProviderRegistry.d.ts +132 -0
- package/dist/esm/src/evm/EvmProviderRegistry.js +345 -0
- package/dist/esm/src/evm/EvmRequestTracker.d.ts +120 -0
- package/dist/esm/src/evm/EvmRequestTracker.js +753 -0
- package/dist/esm/src/queue/EventQueue.d.ts +28 -0
- package/dist/esm/src/queue/EventQueue.js +97 -19
- package/dist/esm/src/queue/type.d.ts +1 -0
- package/dist/esm/src/tracking/TrackingPolicy.d.ts +146 -0
- package/dist/esm/src/tracking/TrackingPolicy.js +197 -0
- package/dist/esm/src/version.d.ts +1 -1
- package/dist/esm/src/version.js +1 -1
- package/dist/esm/src/wallet/WalletStateStore.d.ts +223 -0
- package/dist/esm/src/wallet/WalletStateStore.js +512 -0
- package/dist/index.umd.min.js +1 -1
- package/package.json +5 -4
|
@@ -28,6 +28,8 @@ export declare class EventQueue implements IEventQueue {
|
|
|
28
28
|
private pendingFlush;
|
|
29
29
|
private payloadHashes;
|
|
30
30
|
private canSend?;
|
|
31
|
+
private closed;
|
|
32
|
+
private disposePageLeave;
|
|
31
33
|
constructor(writeKey: string, options: Options);
|
|
32
34
|
private generateMessageId;
|
|
33
35
|
/**
|
|
@@ -35,6 +37,26 @@ export declare class EventQueue implements IEventQueue {
|
|
|
35
37
|
* withdrawal / SDK teardown so nothing buffered can be sent later.
|
|
36
38
|
*/
|
|
37
39
|
clear(): void;
|
|
40
|
+
/**
|
|
41
|
+
* Terminal shutdown. Unlike clear(), which only empties the buffer and can
|
|
42
|
+
* be followed by more events (consent is re-granted, say), close() makes
|
|
43
|
+
* this queue permanently inert: every later enqueue() is a no-op and the
|
|
44
|
+
* page-leave listeners are removed. flush() needs no guard of its own,
|
|
45
|
+
* because a closed queue starts empty and can never be filled again.
|
|
46
|
+
*
|
|
47
|
+
* This is the guarantee a torn-down SDK instance needs. Emission decisions
|
|
48
|
+
* and the emission itself are separated by an await in many call paths
|
|
49
|
+
* (event creation is async), so guarding the *caller* cannot work: the
|
|
50
|
+
* instance may be destroyed while the continuation is in flight. Enforcing
|
|
51
|
+
* it here means no holder of a stale reference can ever send.
|
|
52
|
+
*
|
|
53
|
+
* What close() deliberately does NOT stop is a flush already in flight.
|
|
54
|
+
* Those events were accepted while the instance was alive, so they are
|
|
55
|
+
* real data; abandoning them would turn every unmount into silent loss.
|
|
56
|
+
*/
|
|
57
|
+
close(): void;
|
|
58
|
+
/** True once close() has run. Exposed for teardown assertions. */
|
|
59
|
+
get isClosed(): boolean;
|
|
38
60
|
enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
|
|
39
61
|
flush(callback?: (...args: any) => void, drainAll?: boolean): Promise<void | IFormoEventFlushPayload[]>;
|
|
40
62
|
/**
|
|
@@ -58,6 +80,12 @@ export declare class EventQueue implements IEventQueue {
|
|
|
58
80
|
private sendBatches;
|
|
59
81
|
private isErrorRetryable;
|
|
60
82
|
private isDuplicate;
|
|
83
|
+
/**
|
|
84
|
+
* Installs the page-leave listeners and returns a disposer that removes
|
|
85
|
+
* every one of them. Without the disposer each SDK instance leaked five
|
|
86
|
+
* listeners (three on the global, two on the document) that kept the
|
|
87
|
+
* instance and its queue alive for the life of the page.
|
|
88
|
+
*/
|
|
61
89
|
private onPageLeave;
|
|
62
90
|
}
|
|
63
91
|
export {};
|
|
@@ -83,11 +83,23 @@ var EventQueue = /** @class */ (function () {
|
|
|
83
83
|
this.queue = [];
|
|
84
84
|
this.queueByteSize = 0; // running total of queued items' byteSize
|
|
85
85
|
this.payloadHashes = new Set();
|
|
86
|
+
// Terminal shutdown flag. Once set, enqueue() and flush() are no-ops for
|
|
87
|
+
// the rest of this instance's life. See close().
|
|
88
|
+
this.closed = false;
|
|
89
|
+
// Undoes the page-leave listeners installed in the constructor.
|
|
90
|
+
this.disposePageLeave = null;
|
|
91
|
+
/**
|
|
92
|
+
* Installs the page-leave listeners and returns a disposer that removes
|
|
93
|
+
* every one of them. Without the disposer each SDK instance leaked five
|
|
94
|
+
* listeners (three on the global, two on the document) that kept the
|
|
95
|
+
* instance and its queue alive for the life of the page.
|
|
96
|
+
*/
|
|
86
97
|
this.onPageLeave = function (callback) {
|
|
87
98
|
// To ensure the callback is only called once even if more than one events
|
|
88
99
|
// are fired at once.
|
|
89
100
|
var pageLeft = false;
|
|
90
101
|
var isAccessible = false;
|
|
102
|
+
var resetTimer = null;
|
|
91
103
|
function handleOnLeave() {
|
|
92
104
|
if (pageLeft) {
|
|
93
105
|
return;
|
|
@@ -97,33 +109,27 @@ var EventQueue = /** @class */ (function () {
|
|
|
97
109
|
// Reset pageLeft on the next tick
|
|
98
110
|
// to ensure callback executes for other listeners
|
|
99
111
|
// when closing an inactive browser tab.
|
|
100
|
-
setTimeout(function () {
|
|
112
|
+
resetTimer = setTimeout(function () {
|
|
113
|
+
resetTimer = null;
|
|
101
114
|
pageLeft = false;
|
|
102
115
|
}, 0);
|
|
103
116
|
}
|
|
104
|
-
|
|
105
|
-
// Includes user actions like clicking a link, entering a new URL,
|
|
106
|
-
// refreshing the page, or closing the browser tab
|
|
107
|
-
// Note that 'pagehide' is not supported in IE.
|
|
108
|
-
// So, this is a fallback.
|
|
109
|
-
globalThis.addEventListener("beforeunload", function () {
|
|
117
|
+
var onBeforeUnload = function () {
|
|
110
118
|
isAccessible = false;
|
|
111
119
|
handleOnLeave();
|
|
112
|
-
}
|
|
113
|
-
|
|
120
|
+
};
|
|
121
|
+
var onBlur = function () {
|
|
114
122
|
isAccessible = true;
|
|
115
123
|
handleOnLeave();
|
|
116
|
-
}
|
|
117
|
-
|
|
124
|
+
};
|
|
125
|
+
var onFocus = function () {
|
|
118
126
|
pageLeft = false;
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
document.addEventListener("pagehide", function () {
|
|
127
|
+
};
|
|
128
|
+
var onPageHide = function () {
|
|
122
129
|
isAccessible = document.visibilityState !== "hidden";
|
|
123
130
|
handleOnLeave();
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
document.addEventListener("visibilitychange", function () {
|
|
131
|
+
};
|
|
132
|
+
var onVisibilityChange = function () {
|
|
127
133
|
isAccessible = document.visibilityState !== "hidden";
|
|
128
134
|
if (document.visibilityState === "hidden") {
|
|
129
135
|
handleOnLeave();
|
|
@@ -131,7 +137,36 @@ var EventQueue = /** @class */ (function () {
|
|
|
131
137
|
else {
|
|
132
138
|
pageLeft = false;
|
|
133
139
|
}
|
|
134
|
-
}
|
|
140
|
+
};
|
|
141
|
+
// Captured at install time, not read again at removal time. Teardown can
|
|
142
|
+
// run after the host has swapped or removed these globals (a test harness
|
|
143
|
+
// replacing jsdom between specs, for one), and removing a listener from a
|
|
144
|
+
// different object than it was added to silently leaves it attached.
|
|
145
|
+
var globalTarget = globalThis;
|
|
146
|
+
var documentTarget = document;
|
|
147
|
+
// Catches the unloading of the page (e.g., closing the tab or navigating away).
|
|
148
|
+
// Includes user actions like clicking a link, entering a new URL,
|
|
149
|
+
// refreshing the page, or closing the browser tab
|
|
150
|
+
// Note that 'pagehide' is not supported in IE.
|
|
151
|
+
// So, this is a fallback.
|
|
152
|
+
globalTarget.addEventListener("beforeunload", onBeforeUnload);
|
|
153
|
+
globalTarget.addEventListener("blur", onBlur);
|
|
154
|
+
globalTarget.addEventListener("focus", onFocus);
|
|
155
|
+
// Catches the page being hidden, including scenarios like closing the tab.
|
|
156
|
+
documentTarget.addEventListener("pagehide", onPageHide);
|
|
157
|
+
// Catches visibility changes, such as switching tabs or minimizing the browser.
|
|
158
|
+
documentTarget.addEventListener("visibilitychange", onVisibilityChange);
|
|
159
|
+
return function () {
|
|
160
|
+
if (resetTimer) {
|
|
161
|
+
clearTimeout(resetTimer);
|
|
162
|
+
resetTimer = null;
|
|
163
|
+
}
|
|
164
|
+
globalTarget.removeEventListener("beforeunload", onBeforeUnload);
|
|
165
|
+
globalTarget.removeEventListener("blur", onBlur);
|
|
166
|
+
globalTarget.removeEventListener("focus", onFocus);
|
|
167
|
+
documentTarget.removeEventListener("pagehide", onPageHide);
|
|
168
|
+
documentTarget.removeEventListener("visibilitychange", onVisibilityChange);
|
|
169
|
+
};
|
|
135
170
|
};
|
|
136
171
|
options = options || {};
|
|
137
172
|
this.queue = [];
|
|
@@ -151,7 +186,7 @@ var EventQueue = /** @class */ (function () {
|
|
|
151
186
|
this.errorHandler = options.errorHandler;
|
|
152
187
|
this.pendingFlush = null;
|
|
153
188
|
this.timer = null;
|
|
154
|
-
this.onPageLeave(function (isAccessible) { return __awaiter(_this, void 0, void 0, function () {
|
|
189
|
+
this.disposePageLeave = this.onPageLeave(function (isAccessible) { return __awaiter(_this, void 0, void 0, function () {
|
|
155
190
|
return __generator(this, function (_a) {
|
|
156
191
|
switch (_a.label) {
|
|
157
192
|
case 0:
|
|
@@ -189,6 +224,39 @@ var EventQueue = /** @class */ (function () {
|
|
|
189
224
|
this.queueByteSize = 0;
|
|
190
225
|
this.payloadHashes.clear();
|
|
191
226
|
};
|
|
227
|
+
/**
|
|
228
|
+
* Terminal shutdown. Unlike clear(), which only empties the buffer and can
|
|
229
|
+
* be followed by more events (consent is re-granted, say), close() makes
|
|
230
|
+
* this queue permanently inert: every later enqueue() is a no-op and the
|
|
231
|
+
* page-leave listeners are removed. flush() needs no guard of its own,
|
|
232
|
+
* because a closed queue starts empty and can never be filled again.
|
|
233
|
+
*
|
|
234
|
+
* This is the guarantee a torn-down SDK instance needs. Emission decisions
|
|
235
|
+
* and the emission itself are separated by an await in many call paths
|
|
236
|
+
* (event creation is async), so guarding the *caller* cannot work: the
|
|
237
|
+
* instance may be destroyed while the continuation is in flight. Enforcing
|
|
238
|
+
* it here means no holder of a stale reference can ever send.
|
|
239
|
+
*
|
|
240
|
+
* What close() deliberately does NOT stop is a flush already in flight.
|
|
241
|
+
* Those events were accepted while the instance was alive, so they are
|
|
242
|
+
* real data; abandoning them would turn every unmount into silent loss.
|
|
243
|
+
*/
|
|
244
|
+
EventQueue.prototype.close = function () {
|
|
245
|
+
this.closed = true;
|
|
246
|
+
this.clear();
|
|
247
|
+
if (this.disposePageLeave) {
|
|
248
|
+
safeCall(this.disposePageLeave);
|
|
249
|
+
this.disposePageLeave = null;
|
|
250
|
+
}
|
|
251
|
+
};
|
|
252
|
+
Object.defineProperty(EventQueue.prototype, "isClosed", {
|
|
253
|
+
/** True once close() has run. Exposed for teardown assertions. */
|
|
254
|
+
get: function () {
|
|
255
|
+
return this.closed;
|
|
256
|
+
},
|
|
257
|
+
enumerable: false,
|
|
258
|
+
configurable: true
|
|
259
|
+
});
|
|
192
260
|
EventQueue.prototype.enqueue = function (event, callback) {
|
|
193
261
|
return __awaiter(this, void 0, void 0, function () {
|
|
194
262
|
var message_id, queueItem, hasReachedFlushAt, hasReachedQueueSize;
|
|
@@ -196,6 +264,10 @@ var EventQueue = /** @class */ (function () {
|
|
|
196
264
|
switch (_a.label) {
|
|
197
265
|
case 0:
|
|
198
266
|
callback = callback || noop;
|
|
267
|
+
// A torn-down instance must never buffer, however late the caller
|
|
268
|
+
// arrives. See close().
|
|
269
|
+
if (this.closed)
|
|
270
|
+
return [2 /*return*/];
|
|
199
271
|
// Refuse to buffer anything once consent is withdrawn.
|
|
200
272
|
if (this.canSend && !this.canSend()) {
|
|
201
273
|
this.clear();
|
|
@@ -204,6 +276,12 @@ var EventQueue = /** @class */ (function () {
|
|
|
204
276
|
return [4 /*yield*/, this.generateMessageId(event)];
|
|
205
277
|
case 1:
|
|
206
278
|
message_id = _a.sent();
|
|
279
|
+
// Re-check after the await. A caller that entered before close() is
|
|
280
|
+
// suspended here, and on a queue that has not flushed yet its event
|
|
281
|
+
// would push and flush immediately - the exact shape of the bug close()
|
|
282
|
+
// exists to stop.
|
|
283
|
+
if (this.closed)
|
|
284
|
+
return [2 /*return*/];
|
|
207
285
|
// check if the message already exists
|
|
208
286
|
if (this.isDuplicate(message_id)) {
|
|
209
287
|
logger.warn("Event already enqueued, try again after ".concat(millisecondsToSecond(this.flushIntervalMs), " seconds."));
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { ChainID, Options } from "../types";
|
|
2
|
+
/** Wallet event kinds that `autocapture` can switch on or off individually. */
|
|
3
|
+
export type AutocaptureEventType = "connect" | "disconnect" | "signature" | "transaction" | "chain";
|
|
4
|
+
/**
|
|
5
|
+
* What the policy knows about the event being considered.
|
|
6
|
+
*
|
|
7
|
+
* An object rather than a bare chain id on purpose. The `excludeChains` fix
|
|
8
|
+
* had to thread an explicit chain through every gate because the policy had
|
|
9
|
+
* no identity of its own, and each further per-event input would widen those
|
|
10
|
+
* signatures again. New inputs extend this type instead.
|
|
11
|
+
*/
|
|
12
|
+
export interface TrackingContext {
|
|
13
|
+
/**
|
|
14
|
+
* The event's own chain, when it has one. It wins over the SDK's central
|
|
15
|
+
* chain, because the two differ whenever the event did not come from the
|
|
16
|
+
* active provider: a second wallet signing through its own transport, or a
|
|
17
|
+
* wagmi mutation naming an explicit chain.
|
|
18
|
+
*/
|
|
19
|
+
chainId?: ChainID;
|
|
20
|
+
}
|
|
21
|
+
/** What the policy needs from the SDK it advises. */
|
|
22
|
+
export interface TrackingPolicyDeps {
|
|
23
|
+
/**
|
|
24
|
+
* The CURRENT options.
|
|
25
|
+
*
|
|
26
|
+
* A getter, not a captured object: `FormoAnalytics.options` is public and
|
|
27
|
+
* mutable, so a consumer can replace it after init
|
|
28
|
+
* (`formo.options = { ...formo.options, tracking: false }`). The gates used
|
|
29
|
+
* to read `this.options` on every call, so that took effect immediately,
|
|
30
|
+
* and holding the constructor's object here would silently freeze
|
|
31
|
+
* configuration at init time.
|
|
32
|
+
*/
|
|
33
|
+
options(): Options;
|
|
34
|
+
/** Consent state. Separate from options because the visitor can change it. */
|
|
35
|
+
hasOptedOut(): boolean;
|
|
36
|
+
/** The SDK's central chain, used when an event carries none of its own. */
|
|
37
|
+
currentChainId(): ChainID | undefined;
|
|
38
|
+
}
|
|
39
|
+
export interface ITrackingPolicy {
|
|
40
|
+
shouldTrack(context?: TrackingContext): boolean;
|
|
41
|
+
isTrackingSuppressed(): boolean;
|
|
42
|
+
isChainExcluded(context?: TrackingContext): boolean;
|
|
43
|
+
isPageExcluded(): boolean;
|
|
44
|
+
isPersistedIdentityPurgeRequired(): boolean;
|
|
45
|
+
isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Every "may we track this?" decision, in one place.
|
|
49
|
+
*
|
|
50
|
+
* Split out of `FormoAnalytics` so the rules can be read and tested without
|
|
51
|
+
* an SDK instance, and so option parsing happens once rather than being
|
|
52
|
+
* re-derived at each gate.
|
|
53
|
+
*/
|
|
54
|
+
export declare class TrackingPolicy implements ITrackingPolicy {
|
|
55
|
+
private readonly deps;
|
|
56
|
+
constructor(deps: TrackingPolicyDeps);
|
|
57
|
+
/**
|
|
58
|
+
* `tracking` as an options object, or null when it is absent, a boolean, or
|
|
59
|
+
* anything else. Every exclusion rule lives on the object form, so a null
|
|
60
|
+
* here means "no exclusions configured", not "excluded".
|
|
61
|
+
*/
|
|
62
|
+
private trackingOptions;
|
|
63
|
+
/**
|
|
64
|
+
* Visitor-level tracking suppression.
|
|
65
|
+
*
|
|
66
|
+
* True when the SDK must not persist any identity/session/chain state or
|
|
67
|
+
* send any events for this visitor: an explicit opt-out, or a
|
|
68
|
+
* jurisdiction/timezone/host/path exclusion. Public entry points that write
|
|
69
|
+
* state before reaching `shouldTrack()` (identify / connect / detect) check
|
|
70
|
+
* this first, so a suppressed visitor leaves no cookies or session state.
|
|
71
|
+
*/
|
|
72
|
+
isTrackingSuppressed(): boolean;
|
|
73
|
+
/**
|
|
74
|
+
* Whether the environment is excluded: the visitor's timezone, the current
|
|
75
|
+
* hostname, or the current pathname.
|
|
76
|
+
*
|
|
77
|
+
* Timezone is visitor-level and stable for the session. Host and path are
|
|
78
|
+
* current-page-level and transient, so a SPA navigating back to an allowed
|
|
79
|
+
* path resumes tracking for later actions.
|
|
80
|
+
*/
|
|
81
|
+
private isEnvironmentExcluded;
|
|
82
|
+
/** Exact match against `tracking.excludeHosts`. */
|
|
83
|
+
private isHostExcluded;
|
|
84
|
+
/** Exact match against `tracking.excludePaths`. */
|
|
85
|
+
private isPathExcluded;
|
|
86
|
+
/**
|
|
87
|
+
* Case-insensitive match of the browser-resolved timezone against
|
|
88
|
+
* `tracking.excludeTimezones`. Client-side and best-effort; see the option's
|
|
89
|
+
* own documentation.
|
|
90
|
+
*/
|
|
91
|
+
private isTimezoneExcluded;
|
|
92
|
+
/**
|
|
93
|
+
* Whether the CURRENT PAGE is excluded, as opposed to the visitor.
|
|
94
|
+
*
|
|
95
|
+
* Host and path exclusions are transient: identity written on an allowed
|
|
96
|
+
* page must survive a visit to an excluded route, so callers that persist
|
|
97
|
+
* or restore identity skip the work here rather than purging.
|
|
98
|
+
*/
|
|
99
|
+
isPageExcluded(): boolean;
|
|
100
|
+
/**
|
|
101
|
+
* Whether a persisted identity cookie should be actively purged, not merely
|
|
102
|
+
* left unwritten.
|
|
103
|
+
*
|
|
104
|
+
* Host and path exclusions are deliberately absent: they are transient
|
|
105
|
+
* current-page states, so a cookie legitimately written on an allowed page
|
|
106
|
+
* must survive a visit to an excluded route.
|
|
107
|
+
*/
|
|
108
|
+
isPersistedIdentityPurgeRequired(): boolean;
|
|
109
|
+
/**
|
|
110
|
+
* Whether the chain in play is in `tracking.excludeChains`.
|
|
111
|
+
*
|
|
112
|
+
* Separate from `shouldTrack()` so `identify()` can ask *before* mutating
|
|
113
|
+
* identity state. `trackEvent()` drops an excluded event silently, but
|
|
114
|
+
* `identify()` marks the wallet as identified first, so without this an
|
|
115
|
+
* identify on an excluded chain is dedup-marked and then discarded, and the
|
|
116
|
+
* wallet never re-emits for the rest of the session even after switching to
|
|
117
|
+
* an allowed chain. On the Privy path that loses a whole cluster at once.
|
|
118
|
+
*/
|
|
119
|
+
isChainExcluded(context?: TrackingContext): boolean;
|
|
120
|
+
/**
|
|
121
|
+
* The shared chain rule, so `shouldTrack()` and `isChainExcluded()` cannot
|
|
122
|
+
* drift apart. Callers have already established that `excludeChains` is
|
|
123
|
+
* non-empty.
|
|
124
|
+
*
|
|
125
|
+
* Fails CLOSED on an unknown chain. `resolveChainIdForProvider` reports 0
|
|
126
|
+
* when it has never heard a chain from the signing wallet, and 0 is in no
|
|
127
|
+
* exclusion list, so treating it as "not excluded" would let through exactly
|
|
128
|
+
* the events an operator excluded: the wallet on the excluded chain is often
|
|
129
|
+
* the one we know least about. An explicit exclusion is a directive, so an
|
|
130
|
+
* unresolvable chain is refused.
|
|
131
|
+
*
|
|
132
|
+
* Keyed on 0 and deliberately NOT on `undefined`. 0 is the explicit "we
|
|
133
|
+
* asked and could not tell" marker. `undefined` means no chain state yet,
|
|
134
|
+
* which is a legitimate transient (the Privy path reconciles a Solana wallet
|
|
135
|
+
* through exactly that state), and refusing it would drop real events.
|
|
136
|
+
* `backfillActiveWallet()` never persists 0, so an unresolvable chain cannot
|
|
137
|
+
* leak into the central value and reach the unscoped events (page / track /
|
|
138
|
+
* identify) that fall back to it.
|
|
139
|
+
*/
|
|
140
|
+
private isChainRefused;
|
|
141
|
+
/** Whether an event may be tracked at all, given consent and configuration. */
|
|
142
|
+
shouldTrack(context?: TrackingContext): boolean;
|
|
143
|
+
/** Whether a wallet event kind is enabled for autocapture. Defaults to on. */
|
|
144
|
+
isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
|
|
145
|
+
}
|
|
146
|
+
//# sourceMappingURL=TrackingPolicy.d.ts.map
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import { getTimezone } from "../utils/timezone";
|
|
2
|
+
import { isLocalhost } from "../validators";
|
|
3
|
+
/**
|
|
4
|
+
* Every "may we track this?" decision, in one place.
|
|
5
|
+
*
|
|
6
|
+
* Split out of `FormoAnalytics` so the rules can be read and tested without
|
|
7
|
+
* an SDK instance, and so option parsing happens once rather than being
|
|
8
|
+
* re-derived at each gate.
|
|
9
|
+
*/
|
|
10
|
+
var TrackingPolicy = /** @class */ (function () {
|
|
11
|
+
function TrackingPolicy(deps) {
|
|
12
|
+
this.deps = deps;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* `tracking` as an options object, or null when it is absent, a boolean, or
|
|
16
|
+
* anything else. Every exclusion rule lives on the object form, so a null
|
|
17
|
+
* here means "no exclusions configured", not "excluded".
|
|
18
|
+
*/
|
|
19
|
+
TrackingPolicy.prototype.trackingOptions = function () {
|
|
20
|
+
var tracking = this.deps.options().tracking;
|
|
21
|
+
if (tracking === null ||
|
|
22
|
+
typeof tracking !== "object" ||
|
|
23
|
+
Array.isArray(tracking)) {
|
|
24
|
+
return null;
|
|
25
|
+
}
|
|
26
|
+
return tracking;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Visitor-level tracking suppression.
|
|
30
|
+
*
|
|
31
|
+
* True when the SDK must not persist any identity/session/chain state or
|
|
32
|
+
* send any events for this visitor: an explicit opt-out, or a
|
|
33
|
+
* jurisdiction/timezone/host/path exclusion. Public entry points that write
|
|
34
|
+
* state before reaching `shouldTrack()` (identify / connect / detect) check
|
|
35
|
+
* this first, so a suppressed visitor leaves no cookies or session state.
|
|
36
|
+
*/
|
|
37
|
+
TrackingPolicy.prototype.isTrackingSuppressed = function () {
|
|
38
|
+
return this.deps.hasOptedOut() || this.isEnvironmentExcluded();
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Whether the environment is excluded: the visitor's timezone, the current
|
|
42
|
+
* hostname, or the current pathname.
|
|
43
|
+
*
|
|
44
|
+
* Timezone is visitor-level and stable for the session. Host and path are
|
|
45
|
+
* current-page-level and transient, so a SPA navigating back to an allowed
|
|
46
|
+
* path resumes tracking for later actions.
|
|
47
|
+
*/
|
|
48
|
+
TrackingPolicy.prototype.isEnvironmentExcluded = function () {
|
|
49
|
+
return (this.isTimezoneExcluded() ||
|
|
50
|
+
this.isHostExcluded() ||
|
|
51
|
+
this.isPathExcluded());
|
|
52
|
+
};
|
|
53
|
+
/** Exact match against `tracking.excludeHosts`. */
|
|
54
|
+
TrackingPolicy.prototype.isHostExcluded = function () {
|
|
55
|
+
var tracking = this.trackingOptions();
|
|
56
|
+
if (!tracking)
|
|
57
|
+
return false;
|
|
58
|
+
if (typeof window === "undefined")
|
|
59
|
+
return false;
|
|
60
|
+
var _a = tracking.excludeHosts, excludeHosts = _a === void 0 ? [] : _a;
|
|
61
|
+
return excludeHosts.includes(window.location.hostname);
|
|
62
|
+
};
|
|
63
|
+
/** Exact match against `tracking.excludePaths`. */
|
|
64
|
+
TrackingPolicy.prototype.isPathExcluded = function () {
|
|
65
|
+
var tracking = this.trackingOptions();
|
|
66
|
+
if (!tracking)
|
|
67
|
+
return false;
|
|
68
|
+
if (typeof window === "undefined")
|
|
69
|
+
return false;
|
|
70
|
+
var _a = tracking.excludePaths, excludePaths = _a === void 0 ? [] : _a;
|
|
71
|
+
return excludePaths.includes(window.location.pathname);
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* Case-insensitive match of the browser-resolved timezone against
|
|
75
|
+
* `tracking.excludeTimezones`. Client-side and best-effort; see the option's
|
|
76
|
+
* own documentation.
|
|
77
|
+
*/
|
|
78
|
+
TrackingPolicy.prototype.isTimezoneExcluded = function () {
|
|
79
|
+
var tracking = this.trackingOptions();
|
|
80
|
+
if (!tracking)
|
|
81
|
+
return false;
|
|
82
|
+
var _a = tracking.excludeTimezones, excludeTimezones = _a === void 0 ? [] : _a;
|
|
83
|
+
if (excludeTimezones.length === 0)
|
|
84
|
+
return false;
|
|
85
|
+
var timezone = getTimezone();
|
|
86
|
+
if (!timezone)
|
|
87
|
+
return false;
|
|
88
|
+
var lowerTimezone = timezone.toLowerCase();
|
|
89
|
+
return excludeTimezones.some(function (tz) { return typeof tz === "string" && tz.toLowerCase() === lowerTimezone; });
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* Whether the CURRENT PAGE is excluded, as opposed to the visitor.
|
|
93
|
+
*
|
|
94
|
+
* Host and path exclusions are transient: identity written on an allowed
|
|
95
|
+
* page must survive a visit to an excluded route, so callers that persist
|
|
96
|
+
* or restore identity skip the work here rather than purging.
|
|
97
|
+
*/
|
|
98
|
+
TrackingPolicy.prototype.isPageExcluded = function () {
|
|
99
|
+
return this.isHostExcluded() || this.isPathExcluded();
|
|
100
|
+
};
|
|
101
|
+
/**
|
|
102
|
+
* Whether a persisted identity cookie should be actively purged, not merely
|
|
103
|
+
* left unwritten.
|
|
104
|
+
*
|
|
105
|
+
* Host and path exclusions are deliberately absent: they are transient
|
|
106
|
+
* current-page states, so a cookie legitimately written on an allowed page
|
|
107
|
+
* must survive a visit to an excluded route.
|
|
108
|
+
*/
|
|
109
|
+
TrackingPolicy.prototype.isPersistedIdentityPurgeRequired = function () {
|
|
110
|
+
return this.deps.hasOptedOut() || this.isTimezoneExcluded();
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* Whether the chain in play is in `tracking.excludeChains`.
|
|
114
|
+
*
|
|
115
|
+
* Separate from `shouldTrack()` so `identify()` can ask *before* mutating
|
|
116
|
+
* identity state. `trackEvent()` drops an excluded event silently, but
|
|
117
|
+
* `identify()` marks the wallet as identified first, so without this an
|
|
118
|
+
* identify on an excluded chain is dedup-marked and then discarded, and the
|
|
119
|
+
* wallet never re-emits for the rest of the session even after switching to
|
|
120
|
+
* an allowed chain. On the Privy path that loses a whole cluster at once.
|
|
121
|
+
*/
|
|
122
|
+
TrackingPolicy.prototype.isChainExcluded = function (context) {
|
|
123
|
+
var tracking = this.trackingOptions();
|
|
124
|
+
if (!tracking)
|
|
125
|
+
return false;
|
|
126
|
+
var _a = tracking.excludeChains, excludeChains = _a === void 0 ? [] : _a;
|
|
127
|
+
if (excludeChains.length === 0)
|
|
128
|
+
return false;
|
|
129
|
+
return this.isChainRefused(excludeChains, context);
|
|
130
|
+
};
|
|
131
|
+
/**
|
|
132
|
+
* The shared chain rule, so `shouldTrack()` and `isChainExcluded()` cannot
|
|
133
|
+
* drift apart. Callers have already established that `excludeChains` is
|
|
134
|
+
* non-empty.
|
|
135
|
+
*
|
|
136
|
+
* Fails CLOSED on an unknown chain. `resolveChainIdForProvider` reports 0
|
|
137
|
+
* when it has never heard a chain from the signing wallet, and 0 is in no
|
|
138
|
+
* exclusion list, so treating it as "not excluded" would let through exactly
|
|
139
|
+
* the events an operator excluded: the wallet on the excluded chain is often
|
|
140
|
+
* the one we know least about. An explicit exclusion is a directive, so an
|
|
141
|
+
* unresolvable chain is refused.
|
|
142
|
+
*
|
|
143
|
+
* Keyed on 0 and deliberately NOT on `undefined`. 0 is the explicit "we
|
|
144
|
+
* asked and could not tell" marker. `undefined` means no chain state yet,
|
|
145
|
+
* which is a legitimate transient (the Privy path reconciles a Solana wallet
|
|
146
|
+
* through exactly that state), and refusing it would drop real events.
|
|
147
|
+
* `backfillActiveWallet()` never persists 0, so an unresolvable chain cannot
|
|
148
|
+
* leak into the central value and reach the unscoped events (page / track /
|
|
149
|
+
* identify) that fall back to it.
|
|
150
|
+
*/
|
|
151
|
+
TrackingPolicy.prototype.isChainRefused = function (excludeChains, context) {
|
|
152
|
+
var _a;
|
|
153
|
+
var chainToCheck = (_a = context === null || context === void 0 ? void 0 : context.chainId) !== null && _a !== void 0 ? _a : this.deps.currentChainId();
|
|
154
|
+
if (chainToCheck === 0)
|
|
155
|
+
return true;
|
|
156
|
+
if (chainToCheck === undefined)
|
|
157
|
+
return false;
|
|
158
|
+
return excludeChains.includes(chainToCheck);
|
|
159
|
+
};
|
|
160
|
+
/** Whether an event may be tracked at all, given consent and configuration. */
|
|
161
|
+
TrackingPolicy.prototype.shouldTrack = function (context) {
|
|
162
|
+
if (this.deps.hasOptedOut())
|
|
163
|
+
return false;
|
|
164
|
+
// An explicit boolean is the whole answer; no exclusions apply to it.
|
|
165
|
+
var tracking = this.deps.options().tracking;
|
|
166
|
+
if (typeof tracking === "boolean")
|
|
167
|
+
return tracking;
|
|
168
|
+
var configured = this.trackingOptions();
|
|
169
|
+
if (configured) {
|
|
170
|
+
if (this.isEnvironmentExcluded())
|
|
171
|
+
return false;
|
|
172
|
+
var _a = configured.excludeChains, excludeChains = _a === void 0 ? [] : _a;
|
|
173
|
+
if (excludeChains.length > 0 && this.isChainRefused(excludeChains, context)) {
|
|
174
|
+
return false;
|
|
175
|
+
}
|
|
176
|
+
return true;
|
|
177
|
+
}
|
|
178
|
+
// Nothing configured: track everywhere except localhost.
|
|
179
|
+
return !isLocalhost();
|
|
180
|
+
};
|
|
181
|
+
/** Whether a wallet event kind is enabled for autocapture. Defaults to on. */
|
|
182
|
+
TrackingPolicy.prototype.isAutocaptureEnabled = function (eventType) {
|
|
183
|
+
var autocapture = this.deps.options().autocapture;
|
|
184
|
+
if (autocapture === undefined)
|
|
185
|
+
return true;
|
|
186
|
+
if (typeof autocapture === "boolean")
|
|
187
|
+
return autocapture;
|
|
188
|
+
if (autocapture !== null && typeof autocapture === "object") {
|
|
189
|
+
// Only an explicit false disables a kind.
|
|
190
|
+
return autocapture[eventType] !== false;
|
|
191
|
+
}
|
|
192
|
+
return true;
|
|
193
|
+
};
|
|
194
|
+
return TrackingPolicy;
|
|
195
|
+
}());
|
|
196
|
+
export { TrackingPolicy };
|
|
197
|
+
//# sourceMappingURL=TrackingPolicy.js.map
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const version = "1.
|
|
1
|
+
export declare const version = "1.36.0";
|
|
2
2
|
//# sourceMappingURL=version.d.ts.map
|
package/dist/esm/src/version.js
CHANGED