@affiliateo/web 4.6.1 → 4.8.0

package/dist/provider.js

@@ -5,6 +5,7 @@ import { EventQueue } from './queue';
 import { isLikelyBot } from './bot-detect';
 import { isDevHost } from './dev-host';
 import { mintTurnstileToken, consumeTurnstileToken } from './turnstile';
+import { usableUserId } from './user-id';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
@@ -12,11 +13,16 @@ const LS_REF = 'affiliateo_ref';
 // write the same key, and renaming it would orphan existing visitors'
 // attribution mid-session.
 const LS_APP_ID = 'affiliateo_campaign_id';
-// Persistent opt-out flag (affiliateo_opt_out) —
+// Persistent opt-out flag (affiliateo_opt_out) -
 // when set to "true" the SDK silently noops every outbound call. Survives
 // page reloads. removed by optIn(). Checked at init time so a previously
 // opted-out visitor never re-fires auto-pageviews after a refresh.
 const LS_OPT_OUT = 'affiliateo_opt_out';
+// Who is signed in (4.8.0), and the visit it was last sent in, so the SDK
+// re-sends it once per visit instead of on every page load. Same keys as
+// public/t.js, so a site that runs both keeps one record.
+const LS_USER_ID = 'affiliateo_user_id';
+const LS_USER_SENT = 'affiliateo_user_sent';
 // Client-owned session id. The BROWSER owns the session,
 // not the server. One id is reused for every event within a sliding
 // 10-minute activity window, then a fresh one is minted. Because the id is
@@ -126,6 +132,7 @@ const AffiliateoContext = createContext({
     identify: asyncNoop,
     trackPageview: asyncNoop,
     reset: asyncNoop,
+    logout: asyncNoop,
     optOut: syncNoop,
     optIn: syncNoop,
     flush: asyncNoop,
@@ -158,7 +165,7 @@ export function getAttribution() {
         data.affiliateo_visitor_id = vid;
     if (ref)
         data.affiliateo_ref = ref;
-    // Key renamed from affiliateo_campaign_id in 4.5.0 — the Affiliateo
+    // Key renamed from affiliateo_campaign_id in 4.5.0 - the Affiliateo
     // webhook accepts both, so checkouts created by older SDKs keep working.
     if (cid)
         data.affiliateo_app_id = cid;
@@ -180,7 +187,7 @@ let providerMountCount = 0;
  * touching it there throws a ReferenceError rather than reading undefined.
  *
  * UNKNOWN COUNTS AS NOT-PRODUCTION, deliberately. The only caller is the
- * double-mount warning, and a double mount double-fires every pageview — which
+ * double-mount warning, and a double mount double-fires every pageview - which
  * corrupts the merchant's own numbers and the affiliate attribution built on
  * them. One stray console line on an unbundled production page is a smaller
  * cost than silently letting that run.
@@ -215,6 +222,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         identify: asyncNoop,
         trackPageview: asyncNoop,
         reset: asyncNoop,
+        logout: asyncNoop,
         optOut: syncNoop,
         optIn: syncNoop,
         flush: asyncNoop,
@@ -222,7 +230,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
     // Debug logger. Closes over the `debug` prop so flipping it on/off at
     // runtime (e.g. by changing a feature flag) takes effect on the next
     // render without remounting. eslint-disable for the intentional
-    // console.log — that's the whole point of this helper.
+    // console.log - that's the whole point of this helper.
     const log = useCallback((msg, data) => {
         if (!debug)
             return;
@@ -248,7 +256,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
     // forcing the methods (track / identify / trackPageview) to depend
     // on it for useCallback equality. Initialized inside the route
     // effect since EventQueue's constructor touches localStorage and
-    // window — both unavailable during SSR. Methods called before init
+    // window - both unavailable during SSR. Methods called before init
     // (during the first render, before useEffect runs) silently noop;
     // this is fine because methods are only ever called from event
     // handlers, which fire after mount.
@@ -280,49 +288,106 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 visitor_id: vid,
                 session_id: getSessionId(),
                 event_name: name,
+                // Page context, same three fields the pageview sender carries.
+                // A goal event used to go out without them, and the server's
+                // `path || hostname || '[Web]'` fallback then overwrote the
+                // visitor's real current_page with the literal string '[Web]' -
+                // which both broke the tracking-page popover and made the visitor
+                // invisible to any funnel step matching on a page path. The server
+                // no longer clobbers on missing values, but sending the real path
+                // is what actually keeps current_page correct as a visitor fires
+                // goals while navigating a single-page app.
+                url: window.location.href,
+                path: window.location.pathname,
+                hostname: window.location.hostname,
             };
             if (metadata && typeof metadata === 'object')
                 payload.metadata = metadata;
             // Enqueue. EventQueue handles persist, retry, and flush. If the
             // queue hasn't initialized yet (called during first render before
-            // useEffect runs), this noops — that's a vanishingly rare race
+            // useEffect runs), this noops - that's a vanishingly rare race
             // since track() is virtually always called from a click handler.
             queueRef.current?.enqueue(`${apiBase}/api/v1/web/event`, payload);
             log('track', { event: name, metadata });
         }
         catch { /* swallow */ }
     }, [apiBase, log]);
-    // identify(userId). user_id only — the SDK does NOT accept, collect,
-    // or transmit email or any other PII. Cross-device stitching uses the
-    // merchant's own user_id; we never touch identifying personal data.
+    // identify(userId): say who is signed in (4.8.0). The server keeps one
+    // customer per person per app: a sign-in makes this browser that person's
+    // (folded in with their phone and other browsers), and a DIFFERENT user
+    // signing in here switches the browser to them. user_id only - the SDK
+    // does NOT accept, collect, or transmit email or any other PII.
+    //
+    // The id is stored and re-sent once per visit (the 10-minute session
+    // above), on mount, so the server stays in step without a request on
+    // every page load. Ids that mean "nobody" are skipped (user-id.ts), and
+    // nothing is sent while opted out. A 400 is not retried (queue.ts).
     const identify = useCallback(async (userId) => {
         try {
             if (typeof window === 'undefined')
                 return;
-            if (isOptedOut())
-                return;
-            if (!userId || typeof userId !== 'string')
+            if (isOptedOut()) {
+                log('identify skipped: opted out');
                 return;
-            const uid = userId.trim();
-            // Cap at 128 chars (matches the server). Covers every common
-            // foreign user-id shape: uuid, ulid, mongo objectId, auth0 sub,
-            // firebase uid, supabase uuid.
-            if (!uid || uid.length > 128)
+            }
+            const uid = usableUserId(userId);
+            if (!uid) {
+                log('identify skipped: not a user id (empty, over 128 characters, or a placeholder like "null", "guest" or "0")', { user_id: userId });
                 return;
+            }
+            lsSet(LS_USER_ID, uid);
             const cid = appIdRef.current;
             const vid = visitorIdRef.current;
-            if (!cid || !vid)
+            const queue = queueRef.current;
+            // Not tracking yet: the stored id goes out with the next mount.
+            if (!cid || !vid || !queue)
                 return;
-            const payload = {
+            const mark = `${vid} ${getSessionId()} ${uid}`;
+            if (lsGet(LS_USER_SENT) === mark) {
+                log('identify: already sent this visit', { user_id: uid });
+                return;
+            }
+            lsSet(LS_USER_SENT, mark);
+            // A sign-out still waiting in the queue is replaced by this sign-in;
+            // delivered after it, it would sign the new person out again.
+            const logoutEndpoint = `${apiBase}/api/v1/web/logout`;
+            queue.drop((e) => e.endpoint === logoutEndpoint && e.payload.visitor_id === vid);
+            queue.enqueue(`${apiBase}/api/v1/web/identify`, {
                 campaign_id: cid,
                 visitor_id: vid,
                 user_id: uid,
-            };
-            queueRef.current?.enqueue(`${apiBase}/api/v1/web/identify`, payload);
+            });
             log('identify', { user_id: uid });
         }
         catch { /* swallow */ }
     }, [apiBase, log]);
+    // logout(): the person signed out (4.8.0). POST /api/v1/web/logout: the
+    // browser starts over as a new anonymous customer of the app, so whoever
+    // signs in next (or nobody) is not counted as the person who just left,
+    // and everything already recorded stays with them. Forgets the stored
+    // user id. The visitor id, the affiliate ref, the session and tracking
+    // itself all carry on unchanged.
+    const logout = useCallback(async () => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            log('logout');
+            lsRemove(LS_USER_ID);
+            lsRemove(LS_USER_SENT);
+            if (isOptedOut())
+                return;
+            const cid = appIdRef.current;
+            const vid = visitorIdRef.current;
+            const queue = queueRef.current;
+            if (!cid || !vid || !queue)
+                return;
+            queue.enqueue(`${apiBase}/api/v1/web/logout`, { campaign_id: cid, visitor_id: vid });
+            // Sign-out usually comes right before a redirect, so send it now.
+            // Still queued if this fails: the next page load delivers it.
+            await queue.flush();
+        }
+        catch { /* swallow */ }
+    }, [apiBase, log]);
     // Manual pageview via trackPageview(path?). Same payload
     // shape the auto-fired pageview uses (see sendPageview inside the route
     // effect below) so server-side routing / dedup / IP+UA enrichment behave
@@ -363,7 +428,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 utm_source: params.get('utm_source') || '',
                 utm_medium: params.get('utm_medium') || '',
                 utm_campaign: params.get('utm_campaign') || '',
-                // Ad-network click ids — set automatically on the landing URL by
+                // Ad-network click ids - set automatically on the landing URL by
                 // every Meta/TikTok/Google ad click. Label the sale's source and
                 // feed server-side conversion matching.
                 fbclid: params.get('fbclid') || '',
@@ -386,7 +451,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
     // batches and auto-flushes every 5s; this is the escape hatch for the
     // "I'm about to redirect, don't lose my events" case.
     //
-    // Resolves when the underlying queue.flush() completes — success OR
+    // Resolves when the underlying queue.flush() completes - success OR
     // failure. Events that fail to deliver stay in the queue and get
     // retried on the next normal flush cycle. Safe to await; never throws.
     const flush = useCallback(async () => {
@@ -396,49 +461,23 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         }
         catch { /* swallow */ }
     }, [log]);
-    // reset(): wipe visitor identity. Mints a fresh UUID and clears the
-    // affiliate ref so the next pageview is a brand-new anonymous visitor.
-    // The campaign_id stays (it's a property of the site, not the visitor).
-    //
-    // reset() semantics for non-cookieless mode: new
-    // visitor, no event fired, caller handles "tell the server about it"
-    // by triggering whatever pageview / navigation comes next.
-    //
-    // Returns a Promise so callers can `await reset()` before navigating
-    // (the localStorage writes are sync but the Promise lets the API stay
-    // an async signature, future-proofing for
-    // server-minted IDs in cookieless mode).
-    const reset = useCallback(async () => {
-        try {
-            if (typeof window === 'undefined')
-                return;
-            // Drain any pending events for the OLD visitor before swapping IDs,
-            // otherwise they'd land server-side stamped to the OLD visitor_id
-            // (correct) but persisted-in-localStorage as if to-be-retried under
-            // the new identity — confusing on retry inspection. Best effort.
-            void queueRef.current?.flush();
-            queueRef.current?.clear();
-            const newVid = uuid();
-            lsSet(LS_VISITOR_ID, newVid);
-            lsRemove(LS_REF);
-            lsRemove(LS_SESSION);
-            visitorIdRef.current = newVid;
-            setState((prev) => ({ ...prev, visitorId: newVid, refCode: null }));
-        }
-        catch { /* swallow */ }
-    }, []);
+    // reset(): the same as logout() since 4.8.0. It used to mint a fresh
+    // visitor id and clear the affiliate ref and session, which split one
+    // person's history into two visitors and lost their affiliate. Kept so
+    // existing integrations keep compiling and now get the sign-out they meant.
+    const reset = logout;
     // optOut(): persistent "don't track me" flag. After this call every
     // track / identify / trackPageview noops until optIn() is called. The
     // flag survives reloads via localStorage, so a visitor who opts out
     // stays opted out across browser sessions on the same device.
     //
-    // We don't actively send a "stop tracking me" signal to the server —
+    // We don't actively send a "stop tracking me" signal to the server -
     // the server only knows about visitors who ping it, so an opted-out
     // visitor simply stops appearing. The visitor row left behind in
     // Postgres ages out via normal retention.
     const optOut = useCallback(() => {
         lsSet(LS_OPT_OUT, 'true');
-        // Drop pending events too. The visitor explicitly said no — sending
+        // Drop pending events too. The visitor explicitly said no - sending
         // queued events from before the opt-out would still violate consent
         // even if those events were captured prior to the user's decision.
         queueRef.current?.clear();
@@ -452,13 +491,26 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         lsRemove(LS_OPT_OUT);
     }, []);
     const sentRef = useRef(false);
+    // Boot configuration, read once when the queue and the listeners are
+    // constructed. A ref kept current on every render rather than four more
+    // dependencies: listing them would tear the whole pipeline down and
+    // rebuild it whenever a host re-renders with a new inline object, and
+    // shutdown() drops the in-memory queue, so honoring the rule that way
+    // would cost real events. A host that needs different settings should
+    // remount the provider. (Hosts run React 18, so this is the latest-ref
+    // pattern rather than useEffectEvent.)
+    const bootRef = useRef({ flushInterval, maxQueueSize, allowFileProtocol, autoCfg });
+    useEffect(() => {
+        bootRef.current = { flushInterval, maxQueueSize, allowFileProtocol, autoCfg };
+    });
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
-        // Neither appId nor the legacy campaignId alias was passed — nothing to
+        const { flushInterval, maxQueueSize, allowFileProtocol, autoCfg } = bootRef.current;
+        // Neither appId nor the legacy campaignId alias was passed - nothing to
         // attribute events to, so stay dormant instead of firing junk.
         if (!appIdRef.current) {
-            console.error('[Affiliateo] Missing appId — pass your app ID to <AffiliateoProvider appId="...">.');
+            console.error('[Affiliateo] Missing appId - pass your app ID to <AffiliateoProvider appId="...">.');
             return;
         }
         // Mount-count warning. Fires only when more than one Provider has
@@ -471,7 +523,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         // Client-side bot detection. If the current browser context looks
         // like Selenium / Puppeteer / curl / a known automation tool, skip
         // ALL tracking before we even mint a queue. The server-side UA
-        // regex + Turnstile catch anything that sneaks past this check —
+        // regex + Turnstile catch anything that sneaks past this check -
         // this just saves the bot a round-trip and saves us a request.
         //
         // The hook still returns the four control methods (reset / optOut /
@@ -487,6 +539,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 identify: asyncNoop,
                 trackPageview: asyncNoop,
                 reset: asyncNoop,
+                logout: asyncNoop,
                 optOut: syncNoop,
                 optIn: syncNoop,
                 flush: asyncNoop,
@@ -511,6 +564,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 identify: asyncNoop,
                 trackPageview: asyncNoop,
                 reset: asyncNoop,
+                logout: asyncNoop,
                 optOut: syncNoop,
                 optIn: syncNoop,
                 flush: asyncNoop,
@@ -529,6 +583,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 identify: asyncNoop,
                 trackPageview: asyncNoop,
                 reset: asyncNoop,
+                logout: asyncNoop,
                 optOut: syncNoop,
                 optIn: syncNoop,
                 flush: asyncNoop,
@@ -563,6 +618,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                     identify: asyncNoop,
                     trackPageview: asyncNoop,
                     reset: asyncNoop,
+                    logout: asyncNoop,
                     optOut: syncNoop,
                     optIn: syncNoop,
                     flush: asyncNoop,
@@ -571,8 +627,8 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             }
         }
         // Initialize the event queue. Done inside useEffect (not in a useRef
-        // initializer) so the EventQueue constructor — which touches
-        // localStorage on hydration — only ever runs client-side. The queue
+        // initializer) so the EventQueue constructor - which touches
+        // localStorage on hydration - only ever runs client-side. The queue
         // takes over delivery for track / identify / trackPageview AND the
         // auto-fired pageview below; only session_end stays on sendBeacon
         // because tab-close urgency beats queue-retry reliability.
@@ -601,9 +657,9 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             setState({
                 refCode: null,
                 visitorId: optedOutVid,
-                track, identify, trackPageview, reset, optOut, optIn, flush,
+                track, identify, trackPageview, reset, logout, optOut, optIn, flush,
             });
-            // Don't leave a queue running for an opted-out visitor — the timer
+            // Don't leave a queue running for an opted-out visitor - the timer
             // would just keep waking up to flush nothing.
             queue.shutdown();
             queueRef.current = null;
@@ -661,9 +717,13 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         setState({
             refCode: ref,
             visitorId: vid,
-            track, identify, trackPageview, reset, optOut, optIn, flush,
+            track, identify, trackPageview, reset, logout, optOut, optIn, flush,
         });
         log('init', { app: appIdRef.current, visitor: vid, ref: ref || null });
+        // This visit's re-send of the signed-in user (see identify).
+        const storedUser = usableUserId(lsGet(LS_USER_ID));
+        if (storedUser)
+            void identify(storedUser);
         // lastSendTime drives the visibility-refire heuristic below (refire a
         // pageview when a tab returns after the session window). Duplicate
         // suppression itself is the persisted same-URL throttle inside
@@ -696,7 +756,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             ended = false;
             // Attach the (single-use) Turnstile token to the session-opening
             // pageview. consumeTurnstileToken() returns null after the first
-            // consume, so SPA navigations go out bare — the server trusts them
+            // consume, so SPA navigations go out bare - the server trusts them
             // because the visitor row was created behind the verified token.
             const tsToken = consumeTurnstileToken();
             queue.enqueue(endpoint, {
@@ -727,7 +787,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         // directly. The queue's fetch-with-keepalive is great for normal
         // events because it returns a status code we can retry on, but it
         // can't guarantee the request lands when the tab is in the act of
-        // closing — fetch may be aborted mid-flight. sendBeacon was
+        // closing - fetch may be aborted mid-flight. sendBeacon was
         // designed exactly for this case and CANNOT be cancelled by the
         // unload handler. We also try to drain the queue's pending events
         // here, which uses sendBeacon under the hood for the same reason.
@@ -760,7 +820,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             }
         }
         // Server-side session window. Matches STALE_VISITOR_MS in the
-        // tracking Durable Object — after this much idle time the server
+        // tracking Durable Object - after this much idle time the server
         // treats the visitor as a new session, rotates session_id, and
         // expects a fresh pageview to anchor the new visit in
         // campaign_events. Without that anchor, funnel steps starting on
@@ -777,7 +837,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 // If the SDK's last pageview was longer ago than the server's
                 // 10-min session window, the server has already rolled the
                 // visitor over to a new session_id. Refire pageview so the new
-                // session has a proper anchor — otherwise the next scroll /
+                // session has a proper anchor - otherwise the next scroll /
                 // click / custom event arrives orphaned and the funnel overlay
                 // sees the visitor enter "mid-funnel" (e.g. on a scroll step)
                 // without ever passing through the page-step that should
@@ -800,7 +860,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             //
             // sentRef is set HERE (not before the mint) so a StrictMode
             // double-mount can't mark the pageview as sent and then tear down the
-            // queue before the deferred send ever ran — the surviving mount's
+            // queue before the deferred send ever ran - the surviving mount's
             // callback sees sentRef still false and fires.
             if (cancelled)
                 return;
@@ -959,20 +1019,14 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
                 document.removeEventListener('keydown', onKeydownForLinkDecoration, true);
             }
             // Stop the queue's flush timer. The queue tries one final flush
-            // before going quiet — anything still queued lives in localStorage
+            // before going quiet - anything still queued lives in localStorage
             // and will be picked up by the next page load's queue init.
             queue.shutdown();
             queueRef.current = null;
             providerMountCount = Math.max(0, providerMountCount - 1);
         };
-        // flushInterval, maxQueueSize, allowFileProtocol and the autoCfg.* fields
-        // are BOOT configuration, read once when the queue and listeners are
-        // constructed. Listing them would tear the whole pipeline down and rebuild
-        // it whenever a host app re-renders with a new inline object, and
-        // shutdown() drops the in-memory queue — so honoring the rule here would
-        // cost real events. A host that needs different settings should remount
-        // the provider.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [apiBase, allowedHostnames, allowLocalhost, allowIframe, log, track, identify, trackPageview, reset, optOut, optIn, flush]);
+        // The boot configuration comes off bootRef above, so this list is what
+        // legitimately rebuilds the pipeline.
+    }, [apiBase, allowedHostnames, allowLocalhost, allowIframe, log, track, identify, trackPageview, reset, logout, optOut, optIn, flush]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/queue.d.ts

@@ -85,16 +85,20 @@ export declare class EventQueue {
      *  flush at a time. */
     flush(): Promise<void>;
     /** Best-effort sync flush triggered on page unload. Uses sendBeacon
-     *  for each event so it survives the tab closing. No retry — this is
+     *  for each event so it survives the tab closing. No retry - this is
      *  the last chance.
      *
      *  Called from the provider's pagehide / visibilitychange=hidden
      *  handlers so any events still queued at unload get one last shot.
      *  After this call, the in-memory queue is cleared (events that
-     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  sendBeacon couldn't queue are lost - that's the cost of the
      *  guaranteed-fast unload path). */
     flushOnUnload(): void;
-    /** Wipe the queue. Called by reset() and optOut(). Removes the
+    /** Remove the queued events `predicate` picks (4.8.0). A sign-in uses it
+     *  to drop a sign-out still waiting to be delivered: the sign-in replaces
+     *  it, and a sign-out retried after it would undo it. */
+    drop(predicate: (event: QueuedEvent) => boolean): void;
+    /** Wipe the queue. Called by optOut(). Removes the
      *  localStorage entry entirely so a reload doesn't re-hydrate the
      *  wiped events. */
     clear(): void;

package/dist/queue.js

@@ -88,7 +88,7 @@ export class EventQueue {
         this.maxQueueSize = Math.max(10, Math.min(1000, opts.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE));
         // Hydrate from localStorage so events from a prior page load survive
         // a refresh / navigation. Guards against corrupt JSON or wrong-shape
-        // entries by resetting to empty if anything looks off — better to
+        // entries by resetting to empty if anything looks off - better to
         // lose a few stuck events than crash the host app on init.
         try {
             const raw = lsGet(STORAGE_KEY);
@@ -120,10 +120,27 @@ export class EventQueue {
     enqueue(endpoint, payload) {
         if (this.shuttingDown)
             return;
+        const id = uuid();
         this.queue.push({
-            id: uuid(),
+            id,
             endpoint,
-            payload,
+            // Delivery metadata is baked into the PERSISTED payload rather than
+            // added at flush time, so every retry - and every recovery after a
+            // page reload - sends a byte-identical body:
+            //
+            //   event_id  makes the server insert idempotent. Without it, a 5xx
+            //     raised after the row was already written, or a network timeout
+            //     on a request the server actually processed, lands the same
+            //     event twice: flush() only removes an entry on res.ok, so
+            //     anything else bumps retries and sends it again (MAX_RETRIES=3).
+            //     The server dedups on this via a unique index.
+            //
+            //   client_ts is when the event HAPPENED. The server used to stamp
+            //     arrival time, but the 5s flush cadence, the size-threshold
+            //     burst flush, and retries all reorder delivery freely - so
+            //     arrival order is not user order. Stamping at enqueue is the
+            //     only point that still knows the real sequence.
+            payload: { ...payload, event_id: id, client_ts: Date.now() },
             retries: 0,
         });
         // FIFO drop when over cap. Network outage edge case: if we're way
@@ -136,7 +153,7 @@ export class EventQueue {
         this.persist();
         // Burst protection: when many events fire in quick succession
         // (auto-pageview + immediate track + identify on app boot), don't
-        // wait for the 5s timer — flush right away. The isFlushing guard
+        // wait for the 5s timer - flush right away. The isFlushing guard
         // inside flush() makes overlapping calls safe.
         if (this.queue.length >= SIZE_FLUSH_THRESHOLD) {
             void this.flush();
@@ -153,13 +170,21 @@ export class EventQueue {
         if (this.isFlushing || this.queue.length === 0)
             return;
         this.isFlushing = true;
-        // Snapshot the queue so we iterate a stable list — new enqueue()
+        // Snapshot the queue so we iterate a stable list - new enqueue()
         // calls during the flush land in the live queue and get picked up
         // by the next flush rather than this one (avoids infinite loops
         // and reasoning headaches).
         const batch = this.queue.slice();
         for (const event of batch) {
+            // Dropped or cleared since the batch was taken (optOut(), or a
+            // sign-in replacing a sign-out still waiting here): not sent.
+            if (!this.queue.some((e) => e.id === event.id))
+                continue;
             let ok = false;
+            // A 400 says the request itself is wrong (a placeholder user id, a
+            // malformed body), so sending it again cannot succeed: dropped
+            // rather than retried (4.8.0).
+            let rejected = false;
             try {
                 const res = await fetch(event.endpoint, {
                     method: 'POST',
@@ -169,16 +194,16 @@ export class EventQueue {
                     // with the queue so even if this fetch errors, we'll retry.
                     keepalive: true,
                 });
-                // 2xx = success. Anything else (4xx, 5xx) counts as a failure
-                // and bumps retries. A 4xx is usually a permanent error
-                // (bad payload, dead campaign) so retrying 3 times then
-                // dropping is the right move — keeps the queue clean.
+                // 2xx = success. A 400 is dropped at once (above). Anything else
+                // (other 4xx, 5xx) counts as a failure and bumps retries; after
+                // 3 it is dropped, which keeps the queue clean.
                 ok = res.ok;
+                rejected = res.status === 400;
             }
             catch {
                 ok = false;
             }
-            if (ok) {
+            if (ok || rejected) {
                 // Remove from live queue (not the snapshot) by id
                 this.queue = this.queue.filter((e) => e.id !== event.id);
             }
@@ -199,19 +224,19 @@ export class EventQueue {
         this.isFlushing = false;
     }
     /** Best-effort sync flush triggered on page unload. Uses sendBeacon
-     *  for each event so it survives the tab closing. No retry — this is
+     *  for each event so it survives the tab closing. No retry - this is
      *  the last chance.
      *
      *  Called from the provider's pagehide / visibilitychange=hidden
      *  handlers so any events still queued at unload get one last shot.
      *  After this call, the in-memory queue is cleared (events that
-     *  sendBeacon couldn't queue are lost — that's the cost of the
+     *  sendBeacon couldn't queue are lost - that's the cost of the
      *  guaranteed-fast unload path). */
     flushOnUnload() {
         if (this.queue.length === 0)
             return;
         if (typeof navigator === 'undefined' || !navigator.sendBeacon) {
-            // No sendBeacon (very old browser) — try a sync fetch with
+            // No sendBeacon (very old browser) - try a sync fetch with
             // keepalive as a fallback. Won't actually finish, but it's our
             // last shot.
             for (const event of this.queue) {
@@ -238,7 +263,16 @@ export class EventQueue {
         this.queue = [];
         this.persist();
     }
-    /** Wipe the queue. Called by reset() and optOut(). Removes the
+    /** Remove the queued events `predicate` picks (4.8.0). A sign-in uses it
+     *  to drop a sign-out still waiting to be delivered: the sign-in replaces
+     *  it, and a sign-out retried after it would undo it. */
+    drop(predicate) {
+        const before = this.queue.length;
+        this.queue = this.queue.filter((e) => !predicate(e));
+        if (this.queue.length !== before)
+            this.persist();
+    }
+    /** Wipe the queue. Called by optOut(). Removes the
      *  localStorage entry entirely so a reload doesn't re-hydrate the
      *  wiped events. */
     clear() {

package/dist/turnstile.d.ts

@@ -2,13 +2,13 @@
  * Cloudflare Turnstile token minting. Mirrors the hosted t.js tracker:
  * mint ONE invisible token at SDK init and attach it to the first pageview.
  * The server verifies the token before creating the visitor row (and before
- * counting a pay-per-click web_traffic click — the billable path REQUIRES a
+ * counting a pay-per-click web_traffic click - the billable path REQUIRES a
  * genuine pass when TURNSTILE_SECRET is configured). Subsequent events from
  * the same visitor_id are trusted because the row was created behind a
  * verified token, so the cost is one mint + one verify per session.
  *
  * Tokens are single-use at Cloudflare's siteverify, so consumeToken()
- * hands the token out exactly once — re-sending a used token would get the
+ * hands the token out exactly once - re-sending a used token would get the
  * event rejected server-side, not warn-allowed.
  *
  * Failure modes: if the Turnstile script is blocked (ad blockers, strict
@@ -28,7 +28,7 @@ declare global {
 }
 /**
  * Load the Turnstile script (once) and run the invisible challenge. Resolves
- * when a token is available OR the mint failed/timed out — never rejects, so
+ * when a token is available OR the mint failed/timed out - never rejects, so
  * callers can unconditionally `.then(sendPageview)`.
  */
 export declare function mintTurnstileToken(): Promise<void>;