@indiebob/tracker 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -2,6 +2,13 @@
 
 // src/core/config.ts
 var DEFAULT_ENDPOINT = "https://www.indiebob.com/api/collect";
+var OPTIONS = "projectId endpoint debug respectDnt respectGpc autoDetect hashMode persistence";
+var AUTO_OPTIONS = "signupPaths loginPaths pricingPaths checkoutPaths successPaths onboardingPaths contactPaths dataAttributes formSubmit outboundClicks fileDownloads";
+function warnUnknown(obj, known, where) {
+  for (const k of Object.keys(obj)) {
+    if (!known.split(" ").includes(k)) console.warn(`[IndieBob] Unknown option ${where}"${k}" ignored`);
+  }
+}
 function resolveConfig(input) {
   var _a, _b, _c, _d, _e, _f;
   if (!input.projectId || !input.projectId.startsWith("proj_")) {
@@ -9,6 +16,11 @@ function resolveConfig(input) {
       `[IndieBob] Invalid projectId "${input.projectId}". Must start with "proj_".`
     );
   }
+  warnUnknown(input, OPTIONS, "");
+  if (typeof input.autoDetect === "object") warnUnknown(input.autoDetect, AUTO_OPTIONS, "autoDetect.");
+  if (input.persistence !== void 0 && input.persistence !== "local" && input.persistence !== "none") {
+    console.warn(`[IndieBob] persistence "${String(input.persistence)}" is not 'none' or 'local'; using 'none'`);
+  }
   return {
     projectId: input.projectId,
     endpoint: (_a = input.endpoint) != null ? _a : DEFAULT_ENDPOINT,
@@ -16,7 +28,8 @@ function resolveConfig(input) {
     respectDnt: (_c = input.respectDnt) != null ? _c : true,
     respectGpc: (_d = input.respectGpc) != null ? _d : true,
     autoDetect: (_e = input.autoDetect) != null ? _e : true,
-    hashMode: (_f = input.hashMode) != null ? _f : false
+    hashMode: (_f = input.hashMode) != null ? _f : false,
+    persistence: input.persistence === "local" ? "local" : "none"
   };
 }
 
@@ -279,7 +292,6 @@ async function sendBatch(payload, config, isUnloading = false) {
 var OFFLINE_KEY = "_ib_queue";
 var MAX_BATCH = 10;
 var FLUSH_INTERVAL_MS = 5e3;
-var MAX_OFFLINE = 50;
 var EventQueue = class {
   /**
    * @param beforeHide runs right before the hide flush, so an event that
@@ -287,7 +299,9 @@ var EventQueue = class {
    */
   constructor(config, beforeHide) {
     this.b = [];
-    this.i = false;
+    /** Failed events awaiting a retry, when nothing may be stored ('none'). */
+    this.j = [];
+    this.k = false;
     this.a = config;
     setInterval(() => {
       if (this.b.length > 0) void this.flush();
@@ -302,10 +316,10 @@ var EventQueue = class {
     });
     window.addEventListener("pagehide", hide);
     window.addEventListener("online", () => {
-      void this.m();
+      void this.o();
     });
     if (navigator.onLine) {
-      void this.m();
+      void this.o();
     }
   }
   push(event) {
@@ -315,32 +329,49 @@ var EventQueue = class {
     }
   }
   async flush(isUnloading = false) {
-    if (this.i && !isUnloading) return;
+    if (this.k && !isUnloading) return;
     if (this.b.length === 0) return;
-    this.i = true;
+    this.k = true;
     const batch = this.b.splice(0);
     const payload = { batch };
     const ok = await sendBatch(payload, this.a, isUnloading);
     if (!ok) {
-      try {
-        const trimmed = [...this.n(), ...batch].slice(-MAX_OFFLINE);
-        localStorage.setItem(OFFLINE_KEY, JSON.stringify(trimmed));
-      } catch (e) {
-      }
+      this.t([...this.p(), ...batch].slice(-50));
     }
-    this.i = false;
+    this.k = false;
   }
-  async m() {
-    const stored = this.n();
+  async o() {
+    const stored = this.p();
     if (stored.length === 0) return;
+    this.clearStored();
+    const payload = { batch: stored };
+    await sendBatch(payload, this.a);
+  }
+  /** Give events still waiting the ids they lacked (storage was just allowed). */
+  stamp(anonymousId, sessionId) {
+    for (const e of this.b) if (!e.anonymousId) Object.assign(e, { anonymousId, sessionId });
+  }
+  /** Drop the retry queue, wherever it is kept. */
+  clearStored() {
+    this.j = [];
     try {
       localStorage.removeItem(OFFLINE_KEY);
     } catch (e) {
     }
-    const payload = { batch: stored };
-    await sendBatch(payload, this.a);
   }
-  n() {
+  /** In localStorage only with persistence 'local'; in memory otherwise. */
+  t(events) {
+    if (this.a.persistence !== "local") {
+      this.j = events;
+      return;
+    }
+    try {
+      localStorage.setItem(OFFLINE_KEY, JSON.stringify(events));
+    } catch (e) {
+    }
+  }
+  p() {
+    if (this.a.persistence !== "local") return this.j;
     try {
       const raw = localStorage.getItem(OFFLINE_KEY);
       if (!raw) return [];
@@ -351,9 +382,40 @@ var EventQueue = class {
   }
 };
 
+// src/core/url.ts
+var KEEP = /^(utm_\w+|ref)$/;
+function cleanSearch(search) {
+  const out = new URLSearchParams();
+  new URLSearchParams(search).forEach((v, k) => {
+    if (KEEP.test(k)) out.append(k, v);
+  });
+  const s = out.toString();
+  return s ? "?" + s : "";
+}
+function cleanHash(hash) {
+  const route = hash.split("?")[0];
+  return route.includes("=") ? "" : route;
+}
+function cleanUrl(href, hashMode) {
+  try {
+    const u = new URL(href);
+    return u.origin + u.pathname + cleanSearch(u.search) + (hashMode ? cleanHash(u.hash) : "");
+  } catch (e) {
+    return "";
+  }
+}
+function cleanReferrer(ref) {
+  try {
+    const u = new URL(ref);
+    return u.origin + u.pathname;
+  } catch (e) {
+    return "";
+  }
+}
+
 // src/collectors/page.ts
 function pagePath(loc, hashMode) {
-  return loc.pathname + loc.search + (hashMode ? loc.hash : "");
+  return loc.pathname + cleanSearch(loc.search) + (hashMode ? cleanHash(loc.hash) : "");
 }
 function patchHistory(onNavigate, hashMode) {
   if (typeof window === "undefined") return () => {
@@ -379,9 +441,9 @@ function patchHistory(onNavigate, hashMode) {
 
 // src/collectors/context.ts
 var PAYMENT_HOST = /^https?:\/\/[^/]*(stripe\.com|paypal\.com|paddle\.com|lemonsqueezy\.com|gumroad\.com)(\/|$)/i;
-function buildContext(overrides, hashMode) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
-  const sdkVersion = "0.3.0" ;
+function buildContext(overrides, hashMode, local) {
+  var _a, _b, _c, _d, _e, _f, _g, _h;
+  const sdkVersion = "0.4.1" ;
   if (typeof window === "undefined") {
     return {
       page: { path: (_a = overrides == null ? void 0 : overrides.path) != null ? _a : "", url: "", title: (_b = overrides == null ? void 0 : overrides.title) != null ? _b : "", referrer: (_c = overrides == null ? void 0 : overrides.referrer) != null ? _c : "" },
@@ -396,18 +458,19 @@ function buildContext(overrides, hashMode) {
   return {
     page: {
       path: (_e = overrides == null ? void 0 : overrides.path) != null ? _e : pagePath(location, hashMode),
-      url: location.href,
+      url: cleanUrl(location.href, hashMode),
       title: (_f = overrides == null ? void 0 : overrides.title) != null ? _f : document.title,
       // First touch survives the round trip: a /thanks page reached from Stripe
-      // reports the referrer and UTM the visit STARTED with, not checkout.stripe.com
-      // — otherwise every sale files itself under the payment host.
-      referrer: liveReferrer === "" || PAYMENT_HOST.test(liveReferrer) ? (_g = getStoredReferrer()) != null ? _g : liveReferrer : liveReferrer
+      // reports the referrer the visit STARTED with (stored with 'local'), and
+      // never checkout.stripe.com — otherwise every sale files itself under the
+      // payment host. Without storage the server's visit already holds it.
+      referrer: cleanReferrer(liveReferrer === "" || PAYMENT_HOST.test(liveReferrer) ? local && getStoredReferrer() || "" : liveReferrer)
     },
     // Device class from the viewport width; still required by /api/collect
     device: { width, height: innerHeight, type: width <= 768 ? "mobile" : width <= 1024 ? "tablet" : "desktop" },
-    utm: (_h = parseUtm(location.search)) != null ? _h : getStoredFirstUtm(),
+    utm: (_g = parseUtm(location.search)) != null ? _g : local ? getStoredFirstUtm() : void 0,
     locale: navigator.language,
-    timezone: (_i = Intl.DateTimeFormat().resolvedOptions().timeZone) != null ? _i : "UTC",
+    timezone: (_h = Intl.DateTimeFormat().resolvedOptions().timeZone) != null ? _h : "UTC",
     sdkVersion
   };
 }
@@ -578,9 +641,9 @@ function trackEngagement() {
   window.addEventListener("scroll", sample);
   reset();
   return {
-    r: sample,
-    s: reset,
-    t(measure) {
+    u: sample,
+    w: reset,
+    x(measure) {
       if (measure) sample();
       tick();
       if (!shouldSendEngagement(ms, scroll, sent)) return null;
@@ -599,17 +662,17 @@ function unseen() {
 }
 var IndieBob = class _IndieBob {
   constructor(config) {
-    this.f = null;
-    this.k = null;
     this.g = null;
+    this.m = null;
+    this.h = null;
     /** Engagement meter for the current page (browser only). */
-    this.d = null;
+    this.e = null;
     /** Context of the page last counted — what an engagement event describes. */
-    this.l = null;
+    this.n = null;
     /** A first pageview waiting for the tab to become visible. */
-    this.h = false;
+    this.i = false;
     this.a = config;
-    this.b = new EventQueue(config, () => this.q(true));
+    this.b = new EventQueue(config, () => this.s(true));
     if (typeof window !== "undefined") {
       try {
         if (applyIgnore(window.location.search, localStorage)) {
@@ -617,17 +680,17 @@ var IndieBob = class _IndieBob {
         }
       } catch (e) {
       }
-      initAttribution(window.location.search, document.referrer);
-      this.d = trackEngagement();
+      if (this.c && isTrackingAllowed(config)) initAttribution(window.location.search, document.referrer);
+      this.e = trackEngagement();
       window.addEventListener("pageshow", (e) => {
-        if (e.persisted && this.e !== void 0) {
-          this.e = void 0;
-          this.page(this.o);
+        if (e.persisted && this.f !== void 0) {
+          this.f = void 0;
+          this.page(this.q);
         }
       });
       if (config.autoDetect !== false) {
         const opts = typeof config.autoDetect === "object" ? config.autoDetect : {};
-        this.k = initClickTracking(
+        this.m = initClickTracking(
           (event, properties) => this.track(event, properties),
           opts.dataAttributes !== false,
           opts.fileDownloads !== false,
@@ -662,14 +725,14 @@ var IndieBob = class _IndieBob {
   page(overrides) {
     var _a;
     if (!isTrackingAllowed(this.a)) return;
-    if (this.e === void 0 && unseen()) {
-      this.p = overrides;
-      if (!this.h) {
-        this.h = true;
+    if (this.f === void 0 && unseen()) {
+      this.r = overrides;
+      if (!this.i) {
+        this.i = true;
         const go = () => {
-          if (this.h && !unseen()) {
-            this.h = false;
-            this.page(this.p);
+          if (this.i && !unseen()) {
+            this.i = false;
+            this.page(this.r);
           }
         };
         document.addEventListener("visibilitychange", go);
@@ -677,34 +740,34 @@ var IndieBob = class _IndieBob {
       }
       return;
     }
-    const ctx = buildContext(overrides, this.a.hashMode);
-    if (ctx.page.path === this.e) return;
-    this.q(false);
-    this.e = ctx.page.path;
-    this.o = overrides;
-    this.l = ctx;
-    if (this.d) {
-      this.d.s();
-      setTimeout(this.d.r, 1e3);
+    const ctx = buildContext(overrides, this.a.hashMode, this.c);
+    if (ctx.page.path === this.f) return;
+    this.s(false);
+    this.f = ctx.page.path;
+    this.q = overrides;
+    this.n = ctx;
+    if (this.e) {
+      this.e.w();
+      setTimeout(this.e.u, 1e3);
     }
-    this.b.push(this.c("page", { context: ctx }));
+    this.b.push(this.d("page", { context: ctx }));
     if (this.a.autoDetect !== false) {
       const path = ctx.page.path;
       const opts = typeof this.a.autoDetect === "object" ? this.a.autoDetect : {};
       const intent = detectIntent(path, opts);
       if (intent) {
-        this.b.push(this.c("track", {
+        this.b.push(this.d("track", {
           event: intent,
           properties: { auto: true },
           context: ctx
         }));
         log(this.a, `auto-detected: ${intent} on ${path}`);
         if (opts.formSubmit !== false) {
-          (_a = this.g) == null ? void 0 : _a.call(this);
+          (_a = this.h) == null ? void 0 : _a.call(this);
           const submitEvent = intentToSubmitEvent(intent);
           if (submitEvent) {
-            this.g = observeFormSubmits(submitEvent, (eventName) => {
-              this.b.push(this.c("track", {
+            this.h = observeFormSubmits(submitEvent, (eventName) => {
+              this.b.push(this.d("track", {
                 event: eventName,
                 properties: { auto: true }
               }));
@@ -724,7 +787,7 @@ var IndieBob = class _IndieBob {
    */
   track(event, properties) {
     if (!isTrackingAllowed(this.a)) return;
-    this.b.push(this.c("track", { event, properties }));
+    this.b.push(this.d("track", { event, properties }));
   }
   /**
    * Associate the current anonymous visitor with a known user ID.
@@ -749,18 +812,19 @@ var IndieBob = class _IndieBob {
    */
   identify(userId, traits, options) {
     if (!isTrackingAllowed(this.a)) return;
-    this.j = userId;
-    this.b.push(this.c("identify", { traits, userId }));
-    if (this.a.autoDetect !== false) {
-      const first = typeof (options == null ? void 0 : options.isNew) === "boolean" ? options.isNew : isFirstIdentify();
+    this.l = userId;
+    this.b.push(this.d("identify", { traits, userId }));
+    const known = typeof (options == null ? void 0 : options.isNew) === "boolean";
+    if (this.a.autoDetect !== false && (known || this.c)) {
+      const first = known ? options.isNew : isFirstIdentify();
       const eventName = first ? "signup" : "login";
-      this.b.push(this.c("track", {
+      this.b.push(this.d("track", {
         event: eventName,
         // `auto` says where the verdict came from, so a funnel that looks
         // wrong later can be traced to a guess rather than to the server.
-        properties: { auto: typeof (options == null ? void 0 : options.isNew) !== "boolean" }
+        properties: { auto: !known }
       }));
-      markIdentified();
+      if (this.c) markIdentified();
       log(this.a, `${eventName} for ${userId}`);
     }
   }
@@ -773,7 +837,7 @@ var IndieBob = class _IndieBob {
   revenue(data) {
     var _a;
     if (!isTrackingAllowed(this.a)) return;
-    this.b.push(this.c("revenue", {
+    this.b.push(this.d("revenue", {
       revenue: {
         amount: data.amount,
         currency: (_a = data.currency) != null ? _a : "USD",
@@ -791,11 +855,11 @@ var IndieBob = class _IndieBob {
     void this.b.flush();
     optOut();
     clearIdentified();
-    this.j = void 0;
-    (_a = this.k) == null ? void 0 : _a.call(this);
-    (_b = this.g) == null ? void 0 : _b.call(this);
-    this.k = null;
-    this.g = null;
+    this.l = void 0;
+    (_a = this.m) == null ? void 0 : _a.call(this);
+    (_b = this.h) == null ? void 0 : _b.call(this);
+    this.m = null;
+    this.h = null;
     log(this.a, "opted out");
   }
   /** Re-enable tracking after optOut(). */
@@ -818,13 +882,42 @@ var IndieBob = class _IndieBob {
   async flush() {
     await this.b.flush();
   }
-  /** Get the current anonymous ID. */
+  /** The stored anonymous ID with `persistence: 'local'`; '' without storage. */
   getAnonymousId() {
-    return getAnonymousId();
+    return this.c ? getAnonymousId() : "";
   }
-  /** Get the current session ID. */
+  /** The stored session ID with `persistence: 'local'`; '' without storage. */
   getSessionId() {
-    return getSessionId();
+    return this.c ? getSessionId() : "";
+  }
+  /**
+   * Switch storage on or off — call it from your consent banner.
+   * `'local'` starts storing the visitor id and first-touch attribution from
+   * this page on; `'none'` removes everything the tracker stored.
+   *
+   * @example
+   * onConsent(() => bob.setPersistence('local'))
+   * onConsentWithdrawn(() => bob.setPersistence('none'))
+   */
+  setPersistence(mode) {
+    if (mode !== "local" && mode !== "none") return;
+    this.a.persistence = mode;
+    if (mode === "local") {
+      if (typeof window !== "undefined" && isTrackingAllowed(this.a)) {
+        initAttribution(location.search, document.referrer);
+        this.b.stamp(getAnonymousId(), getSessionId());
+      }
+    } else {
+      clearAnonymousId();
+      clearSession();
+      clearAttribution();
+      clearIdentified();
+      this.b.clearStored();
+    }
+    log(this.a, `persistence: ${mode}`);
+  }
+  get c() {
+    return this.a.persistence === "local";
   }
   /** Get the resolved configuration (read-only). */
   getConfig() {
@@ -840,12 +933,12 @@ var IndieBob = class _IndieBob {
    */
   enableAutoPage() {
     var _a;
-    (_a = this.f) == null ? void 0 : _a.call(this);
-    this.f = patchHistory(() => this.page(), this.a.hashMode);
+    (_a = this.g) == null ? void 0 : _a.call(this);
+    this.g = patchHistory(() => this.page(), this.a.hashMode);
     return () => {
       var _a2;
-      (_a2 = this.f) == null ? void 0 : _a2.call(this);
-      this.f = null;
+      (_a2 = this.g) == null ? void 0 : _a2.call(this);
+      this.g = null;
     };
   }
   /**
@@ -853,14 +946,14 @@ var IndieBob = class _IndieBob {
    * worth sending. `measure`: sample the scroll first (false on an SPA
    * change, when the DOM already shows the next page).
    */
-  q(measure) {
+  s(measure) {
     var _a;
-    const reading = this.l && ((_a = this.d) == null ? void 0 : _a.t(measure));
+    const reading = this.n && ((_a = this.e) == null ? void 0 : _a.x(measure));
     if (reading && isTrackingAllowed(this.a)) {
-      this.b.push(this.c("engagement", { context: this.l, engagement: reading }));
+      this.b.push(this.d("engagement", { context: this.n, engagement: reading }));
     }
   }
-  c(type, extras) {
+  d(type, extras) {
     var _a, _b;
     return {
       ...extras,
@@ -868,11 +961,11 @@ var IndieBob = class _IndieBob {
       id: generateId(),
       projectId: this.a.projectId,
       type,
-      anonymousId: getAnonymousId(),
-      userId: (_a = this.j) != null ? _a : extras.userId,
-      sessionId: getSessionId(),
+      // Without storage the server derives both from its daily hash
+      ...this.c ? { anonymousId: getAnonymousId(), sessionId: getSessionId() } : {},
+      userId: (_a = this.l) != null ? _a : extras.userId,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      context: (_b = extras.context) != null ? _b : buildContext(void 0, this.a.hashMode)
+      context: (_b = extras.context) != null ? _b : buildContext(void 0, this.a.hashMode, this.c)
     };
   }
 };

package/dist/index.d.mts

@@ -4,13 +4,13 @@
 interface TrackerConfig {
     /** Your SDK project ID from the IndieBob dashboard. Format: 'proj_...' */
     projectId: string;
-    /** Ingestion endpoint URL. Default: 'https://indiebob.com/api/collect' */
+    /** Ingestion endpoint URL. Default: 'https://www.indiebob.com/api/collect' */
     endpoint?: string;
     /** Log all events to the browser console. Default: false */
     debug?: boolean;
     /** Honor the browser Do Not Track header. Default: true */
     respectDnt?: boolean;
-    /** Honor Global Privacy Control signal (legally binding in CA/GDPR). Default: true */
+    /** Honor Global Privacy Control signal (legally binding under CCPA in California). Default: true */
     respectGpc?: boolean;
     /**
      * Auto-detect user intent from URL patterns and identify() calls.
@@ -51,7 +51,22 @@ interface TrackerConfig {
      * path. Default: false (a hash-only change is not a new page).
      */
     hashMode?: boolean;
+    /**
+     * What the tracker keeps in the visitor's browser.
+     *
+     * - `'none'` (default): nothing. No id, no stored UTM or referrer, no offline
+     *   queue. IndieBob counts the visitor on its server from a hash of a daily
+     *   salt, the site, the IP address and the user agent; the salt is deleted
+     *   after a day and the IP is never stored. No consent needed.
+     * - `'local'`: a random visitor id, first-touch UTM and referrer in
+     *   localStorage, so a visitor is recognised across days. Storing an id on
+     *   the visitor's device needs their consent in the EU (ePrivacy Art. 5(3)):
+     *   switch to it from your consent banner with `bob.setPersistence('local')`.
+     */
+    persistence?: Persistence;
 }
+/** Where the tracker may store anything: nowhere, or localStorage. */
+type Persistence = 'none' | 'local';
 /** Resolved config with all defaults applied. */
 interface ResolvedConfig {
     projectId: string;
@@ -73,6 +88,7 @@ interface ResolvedConfig {
         fileDownloads?: boolean;
     };
     hashMode: boolean;
+    persistence: Persistence;
 }
 /** The tracking event type. */
 type EventType = 'page' | 'track' | 'identify' | 'revenue' | 'engagement';
@@ -117,9 +133,11 @@ interface TrackerEvent {
     id: string;
     projectId: string;
     type: EventType;
-    anonymousId: string;
+    /** Absent with `persistence: 'none'`: the server derives the visitor from its daily hash. */
+    anonymousId?: string;
     userId?: string;
-    sessionId: string;
+    /** Absent with `persistence: 'none'`: the server groups visits on its own. */
+    sessionId?: string;
     timestamp: string;
     context: EventContext;
     event?: string;
@@ -253,10 +271,21 @@ declare class IndieBob {
     isIgnored(): boolean;
     /** Force-send all queued events immediately. Useful in tests. */
     flush(): Promise<void>;
-    /** Get the current anonymous ID. */
+    /** The stored anonymous ID with `persistence: 'local'`; '' without storage. */
     getAnonymousId(): string;
-    /** Get the current session ID. */
+    /** The stored session ID with `persistence: 'local'`; '' without storage. */
     getSessionId(): string;
+    /**
+     * Switch storage on or off — call it from your consent banner.
+     * `'local'` starts storing the visitor id and first-touch attribution from
+     * this page on; `'none'` removes everything the tracker stored.
+     *
+     * @example
+     * onConsent(() => bob.setPersistence('local'))
+     * onConsentWithdrawn(() => bob.setPersistence('none'))
+     */
+    setPersistence(mode: Persistence): void;
+    private get _local();
     /** Get the resolved configuration (read-only). */
     getConfig(): Readonly<ResolvedConfig>;
     /**
@@ -277,4 +306,4 @@ declare class IndieBob {
     private _buildEvent;
 }
 
-export { type DeviceType, type EventContext, type EventType, IndieBob, type PageOverrides, type RevenueData, type RevenueType, type TrackerConfig, type TrackerEvent, type UtmData };
+export { type DeviceType, type EventContext, type EventType, IndieBob, type PageOverrides, type Persistence, type RevenueData, type RevenueType, type TrackerConfig, type TrackerEvent, type UtmData };

package/dist/index.d.ts

@@ -4,13 +4,13 @@
 interface TrackerConfig {
     /** Your SDK project ID from the IndieBob dashboard. Format: 'proj_...' */
     projectId: string;
-    /** Ingestion endpoint URL. Default: 'https://indiebob.com/api/collect' */
+    /** Ingestion endpoint URL. Default: 'https://www.indiebob.com/api/collect' */
     endpoint?: string;
     /** Log all events to the browser console. Default: false */
     debug?: boolean;
     /** Honor the browser Do Not Track header. Default: true */
     respectDnt?: boolean;
-    /** Honor Global Privacy Control signal (legally binding in CA/GDPR). Default: true */
+    /** Honor Global Privacy Control signal (legally binding under CCPA in California). Default: true */
     respectGpc?: boolean;
     /**
      * Auto-detect user intent from URL patterns and identify() calls.
@@ -51,7 +51,22 @@ interface TrackerConfig {
      * path. Default: false (a hash-only change is not a new page).
      */
     hashMode?: boolean;
+    /**
+     * What the tracker keeps in the visitor's browser.
+     *
+     * - `'none'` (default): nothing. No id, no stored UTM or referrer, no offline
+     *   queue. IndieBob counts the visitor on its server from a hash of a daily
+     *   salt, the site, the IP address and the user agent; the salt is deleted
+     *   after a day and the IP is never stored. No consent needed.
+     * - `'local'`: a random visitor id, first-touch UTM and referrer in
+     *   localStorage, so a visitor is recognised across days. Storing an id on
+     *   the visitor's device needs their consent in the EU (ePrivacy Art. 5(3)):
+     *   switch to it from your consent banner with `bob.setPersistence('local')`.
+     */
+    persistence?: Persistence;
 }
+/** Where the tracker may store anything: nowhere, or localStorage. */
+type Persistence = 'none' | 'local';
 /** Resolved config with all defaults applied. */
 interface ResolvedConfig {
     projectId: string;
@@ -73,6 +88,7 @@ interface ResolvedConfig {
         fileDownloads?: boolean;
     };
     hashMode: boolean;
+    persistence: Persistence;
 }
 /** The tracking event type. */
 type EventType = 'page' | 'track' | 'identify' | 'revenue' | 'engagement';
@@ -117,9 +133,11 @@ interface TrackerEvent {
     id: string;
     projectId: string;
     type: EventType;
-    anonymousId: string;
+    /** Absent with `persistence: 'none'`: the server derives the visitor from its daily hash. */
+    anonymousId?: string;
     userId?: string;
-    sessionId: string;
+    /** Absent with `persistence: 'none'`: the server groups visits on its own. */
+    sessionId?: string;
     timestamp: string;
     context: EventContext;
     event?: string;
@@ -253,10 +271,21 @@ declare class IndieBob {
     isIgnored(): boolean;
     /** Force-send all queued events immediately. Useful in tests. */
     flush(): Promise<void>;
-    /** Get the current anonymous ID. */
+    /** The stored anonymous ID with `persistence: 'local'`; '' without storage. */
     getAnonymousId(): string;
-    /** Get the current session ID. */
+    /** The stored session ID with `persistence: 'local'`; '' without storage. */
     getSessionId(): string;
+    /**
+     * Switch storage on or off — call it from your consent banner.
+     * `'local'` starts storing the visitor id and first-touch attribution from
+     * this page on; `'none'` removes everything the tracker stored.
+     *
+     * @example
+     * onConsent(() => bob.setPersistence('local'))
+     * onConsentWithdrawn(() => bob.setPersistence('none'))
+     */
+    setPersistence(mode: Persistence): void;
+    private get _local();
     /** Get the resolved configuration (read-only). */
     getConfig(): Readonly<ResolvedConfig>;
     /**
@@ -277,4 +306,4 @@ declare class IndieBob {
     private _buildEvent;
 }
 
-export { type DeviceType, type EventContext, type EventType, IndieBob, type PageOverrides, type RevenueData, type RevenueType, type TrackerConfig, type TrackerEvent, type UtmData };
+export { type DeviceType, type EventContext, type EventType, IndieBob, type PageOverrides, type Persistence, type RevenueData, type RevenueType, type TrackerConfig, type TrackerEvent, type UtmData };