@affiliateo/web 4.7.0 → 4.9.0

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);
@@ -125,8 +125,8 @@ export class EventQueue {
             id,
             endpoint,
             // 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:
+            // 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
@@ -137,7 +137,7 @@ export class EventQueue {
             //
             //   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
+            //     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() },
@@ -153,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();
@@ -170,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',
@@ -186,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);
             }
@@ -216,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) {
@@ -255,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>;

package/dist/turnstile.js

@@ -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
@@ -17,20 +17,20 @@
  * those through; commission-on-sale (web_affiliate) tracking never depends
  * on the token at all.
  */
-// Public sitekey (safe to expose) — the same one public/t.js ships. The
+// Public sitekey (safe to expose) - the same one public/t.js ships. The
 // matching secret lives in TURNSTILE_SECRET on the server.
 const TURNSTILE_SITEKEY = '0x4AAAAAADR5UW2x6axFd13p';
 const TURNSTILE_SCRIPT_SRC = 'https://challenges.cloudflare.com/turnstile/v0/api.js?onload=__affiliateoTSLoaded&render=explicit';
 // Hard deadline for the whole mint (script load + challenge). t.js relies on
 // Turnstile's own timeout-callback, but a script tag that never loads never
-// fires ANY callback — this timer makes sure the first pageview can't be
+// fires ANY callback - this timer makes sure the first pageview can't be
 // held hostage by a blocked challenges.cloudflare.com.
 const MINT_TIMEOUT_MS = 3000;
 let token = null;
 let minting = null;
 /**
  * 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 function mintTurnstileToken() {
@@ -60,7 +60,7 @@ export function mintTurnstileToken() {
                 document.body.appendChild(holder);
                 window.turnstile.render(holder, {
                     sitekey: TURNSTILE_SITEKEY,
-                    // Invisible widget — never shows UI. Real browsers pass the
+                    // Invisible widget - never shows UI. Real browsers pass the
                     // challenge in 50-200ms with zero user interaction.
                     size: 'invisible',
                     callback: (tok) => {

package/dist/types.d.ts

@@ -1,9 +1,9 @@
 export interface AffiliateoConfig {
-    /** Your Affiliateo app ID — shown in the dashboard when you create a
+    /** Your Affiliateo app ID - shown in the dashboard when you create a
      *  Web App Affiliate app. One of `appId` / `campaignId` is required;
      *  `appId` wins when both are set. */
     appId?: string;
-    /** @deprecated Affiliateo campaigns are now called apps — use `appId`.
+    /** @deprecated Affiliateo campaigns are now called apps - use `appId`.
      *  Kept working so existing integrations don't break. */
     campaignId?: string;
     /** Base URL for the API. Defaults to https://affiliateo.com */
@@ -55,7 +55,7 @@ export interface AffiliateoConfig {
      *  true, the SDK logs every action it takes (init, pageview fired,
      *  goal tracked, blocked by bot detection, blocked by localhost, queue
      *  flush attempted, etc.). Only the merchant or anyone manually opening
-     *  DevTools sees these — normal visitors never look at the console.
+     *  DevTools sees these - normal visitors never look at the console.
      *
      *  Turn on temporarily when investigating "why aren't my events
      *  showing up?". Leave off in production.
@@ -80,6 +80,17 @@ export interface AffiliateoConfig {
     /** Pageview auto-capture behavior. Pass `false` to disable entirely
      *  (you'll call `trackPageview()` yourself). Pass an object to fine-tune.
      *  Defaults to `true` (auto-capture everything). */
+    /** Live Chat (4.9.0). Once the business switches Live Chat on for this
+     *  app in its Affiliateo dashboard, a chat bubble shows on the site.
+     *  `true` (the default) shows it; `'hidden'` loads the chat without a
+     *  bubble, for a site that calls `openChat()` from its own button; `false`
+     *  never loads it. */
+    chat?: boolean | 'hidden';
+    /** Your own look for the chat bubble (4.15.0), over the Live Chat settings
+     *  in your dashboard: anything left out keeps the dashboard's choice.
+     *  sendColor colors the send button and the person's own messages;
+     *  placeholder is the message box text, in your own words and language. */
+    chatLook?: ChatLook;
     autoCapturePageviews?: boolean | {
         /** Fire the initial pageview on mount. Defaults to true. Set false
          *  for cookie-consent flows where you want to defer until the user
@@ -121,7 +132,14 @@ export interface AffiliateoContextValue {
      *  both events resolve to the same user_id and the funnel reports a
      *  single converted person.
      *
-     *  Idempotent: safe to call on every page load. user_id only —
+     *  Since 4.8.0 a different user signing in on this browser switches it
+     *  to them (it used to be refused). The SDK stores the id and re-sends it
+     *  once per visit; calling it again in the same visit sends nothing. Does
+     *  nothing while opted out, and skips ids that mean "nobody" ("null",
+     *  "undefined", "guest", "0", RevenueCat's $RCAnonymousID:...) that the
+     *  server would refuse.
+     *
+     *  Idempotent: safe to call on every page load. user_id only -
      *  the SDK does not accept or transmit email or any other PII.
      *
      *  Example:
@@ -142,22 +160,25 @@ export interface AffiliateoContextValue {
      *      useEffect(() => { if (open) trackPageview('/pricing-modal') }, [open])
      *    } */
     trackPageview: (path?: string) => Promise<void>;
-    /** Wipe the visitor identity. Mints a fresh visitor_id and clears the
-     *  affiliate ref + campaign_id from localStorage so the next pageview
-     *  is treated as a brand-new anonymous visitor.
-     *
-     *  Use case: call on user logout so a different person sitting down at
-     *  the same browser doesn't get their actions merged into the previous
-     *  user's funnel. Without this, shared family computers / kiosks /
-     *  hot-desks silently pollute attribution.
+    /** The user signed out (4.8.0). Call it on sign-out: this 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, and
+     *  their Live Chat: the next person to open it starts a new thread. The
+     *  visitor id, the affiliate ref and tracking carry on unchanged.
      *
      *  Example:
-     *    const { reset } = useAffiliateRef()
+     *    const { logout } = useAffiliateRef()
      *    async function handleLogout() {
      *      await supabase.auth.signOut()
-     *      await reset()
+     *      await logout()
      *      router.push('/')
      *    } */
+    logout: () => Promise<void>;
+    /** The same as logout() since 4.8.0. It used to mint a fresh visitor id
+     *  and clear the affiliate ref, which split one person into two visitors
+     *  and lost their affiliate. Kept as an alias so existing integrations
+     *  get the sign-out they meant. */
     reset: () => Promise<void>;
     /** Stop tracking this visitor. Sets a persistent opt-out flag in
      *  localStorage and silences all subsequent track / identify / pageview
@@ -196,7 +217,20 @@ export interface AffiliateoContextValue {
      *    }
      *
      *  Returns a Promise that resolves when the flush attempt completes
-     *  (success OR failure — failed events stay in the queue for the next
+     *  (success OR failure - failed events stay in the queue for the next
      *  flush). Safe to await without timeout concerns. */
     flush: () => Promise<void>;
 }
+/** The chat bubble's look, set in code (4.15.0). Colors are hex ("#7C3AED"). */
+export interface ChatLook {
+    color?: string;
+    iconColor?: string;
+    /** The chat's send button and the person's own messages (iMessage blue unless the dashboard says otherwise). */
+    sendColor?: string;
+    /** The message box text, in your own words and language (up to 60 characters): pass your app's own translation. */
+    placeholder?: string;
+    style?: 'solid' | 'glass';
+    corner?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** In pixels, 40 to 80. */
+    size?: number;
+}

package/dist/user-id.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which user ids may name a signed-in person (4.8.0).
+ *
+ * Every device that signs in with the same user id becomes ONE customer of
+ * the app on Affiliateo's side, so an id that really means "nobody" ("null",
+ * "undefined", "guest", "0") would merge every stranger whose site sent it
+ * into one person. The server refuses these with a 400; this is the same
+ * list, checked here so a wrong call is skipped (and says so with
+ * debug={true}) instead of costing a request.
+ *
+ * KEEP IN SYNC with src/lib/customers/user-id.ts in the Affiliateo web repo,
+ * and with public/t.js, which the vanilla snippet loads.
+ */
+export declare const MAX_USER_ID_LENGTH = 128;
+/** The trimmed id when it can name a person, otherwise null. A number (a
+ *  database row id passed straight through) is read as its digits, the way
+ *  the server reads it. */
+export declare function usableUserId(value: unknown): string | null;

package/dist/user-id.js

@@ -0,0 +1,40 @@
+/**
+ * Which user ids may name a signed-in person (4.8.0).
+ *
+ * Every device that signs in with the same user id becomes ONE customer of
+ * the app on Affiliateo's side, so an id that really means "nobody" ("null",
+ * "undefined", "guest", "0") would merge every stranger whose site sent it
+ * into one person. The server refuses these with a 400; this is the same
+ * list, checked here so a wrong call is skipped (and says so with
+ * debug={true}) instead of costing a request.
+ *
+ * KEEP IN SYNC with src/lib/customers/user-id.ts in the Affiliateo web repo,
+ * and with public/t.js, which the vanilla snippet loads.
+ */
+export const MAX_USER_ID_LENGTH = 128;
+const NOT_A_USER = new Set([
+    'null', '(null)', '<null>', 'nil', 'none', 'no', 'undefined', 'unidentified',
+    'unknown', 'anonymous', 'anon', 'guest', 'nan', 'false', 'true',
+    '0', '-1', '[]', '{}', '[object object]',
+]);
+/** The trimmed id when it can name a person, otherwise null. A number (a
+ *  database row id passed straight through) is read as its digits, the way
+ *  the server reads it. */
+export function usableUserId(value) {
+    let raw;
+    if (typeof value === 'string')
+        raw = value;
+    else if (typeof value === 'number' && Number.isFinite(value))
+        raw = String(value);
+    else
+        return null;
+    const id = raw.trim();
+    if (id.length < 1 || id.length > MAX_USER_ID_LENGTH)
+        return null;
+    if (NOT_A_USER.has(id.toLowerCase()))
+        return null;
+    // RevenueCat's own anonymous id names an install, not a user.
+    if (id.startsWith('$RCAnonymousID:'))
+        return null;
+    return id;
+}

package/package.json

@@ -1,44 +1,46 @@
-{
-  "name": "@affiliateo/web",
-  "version": "4.7.0",
-  "description": "Affiliateo web SDK \u2014 affiliate attribution and tracking for web apps",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "prepack": "npm run build"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/react": "^19.0.0",
-    "typescript": "^5.0.0"
-  },
-  "keywords": [
-    "affiliateo",
-    "affiliate",
-    "attribution",
-    "stripe",
-    "web",
-    "session",
-    "tracking"
-  ],
-  "license": "MIT",
-  "files": [
-    "dist"
-  ]
-}
+{
+  "name": "@affiliateo/web",
+  "version": "4.9.0",
+  "description": "Affiliateo web SDK: affiliate attribution and tracking for web apps",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "affiliateo",
+    "affiliate",
+    "attribution",
+    "stripe",
+    "web",
+    "session",
+    "tracking"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist"
+  ]
+}