@crelora/mark 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Mark is Crelora's lightweight attribution SDK for capturing user journeys, conversions, and consent across browsers and server-side runtimes. The npm package includes both browser and Node entry points so you can send consistent data from any surface.
 
-Use it to feed **OneLence** with first‑party behavioral and conversion data so you can build **analytics**, **insights**, **signals**, and **decisions** on top of a unified event stream.
+Use it to feed [**OneLence**](https://onelence.com) with first‑party behavioral and conversion data so you can build **analytics**, **insights**, **signals**, and **decisions** on top of a unified event stream.
 
 ### API keys and documentation
 
@@ -104,6 +104,7 @@ The Node factory accepts optional custom storage or transport adapters so you ca
 - `flush()` – flushes queued/persisted delivery items.
 - `reset()` – clears user/session/attribution state and rotates visitor identity for logout flows.
 - `getStats()` – returns runtime delivery stats `{ queued, sent, failed, dropped }`.
+- `setInternal(value)` / `getInternal()` – flags the current visitor as internal traffic (QA, staff, smoke tests). While set, every outgoing event is stamped with `is_internal: true` so the backend can exclude it from customer-facing reports by default. See [Flagging internal traffic](#flagging-internal-traffic).
 
 Reserved SDK fields (for example `event_name`, `user_id`, `consent_state`, and internal identity metadata) are sanitized from user payloads/traits and cannot override SDK-managed values.
 
@@ -223,6 +224,77 @@ Mark.identify('user_123', {
 - Autocapture (optional): set `autocapture: { pageview: true }` (and optionally `track_route_changes: true`) to emit on first load and SPA route changes. If consent is required and not yet granted, initial pageview is deferred and emitted once consent is granted.
 - All SDK config and event fields use snake_case (`site_id`, `site_host`, etc.) and map directly to stored payloads and database columns.
 
+## Extended autocapture (browser)
+
+All of the following are **opt-in** under `autocapture`. They respect the same consent, DNT/GPC, and sampling rules as `track()` (see `sample_rate`: conversions are exempt; these modes are **not** conversion events). They are registered when `Mark.init()` runs.
+
+| Flag | Event name(s) | Behavior |
+| --- | --- | --- |
+| `click` | `data-mark-event` value, or `click` | Listens for clicks. **Default:** only elements matching `[data-mark-event]`; set `click: { selector: '.my-tracked' }` to use a custom selector. Sends `element_id`, `element_classes`, truncated `text`, and `href` when applicable. |
+| `form_submit` | `form_submit` | Listens for `submit`; sends `form_id`, `form_name`, `action`. |
+| `outbound_link` | `outbound_link_click` | On click, if the link target is another origin, sends `href`. Uses `preferBeacon: true` so the event is more likely to fire before navigation. |
+| `scroll_depth` | `scroll_depth` | Fires at **25%, 50%, 75%, and 100%** of vertical scroll depth (once each per page load). Payload includes `percent`. |
+| `web_vitals` | `web_vital` | Lazy-loads the `web-vitals` dependency and reports **LCP, CLS, INP, and TTFB** with `metric`, `value`, optional `rating`, and `metric_id`. If the module fails to load, only `debug: true` logs a warning. |
+
+Example:
+
+```ts
+Mark.init({
+  key: 'pk_xxxxx',
+  require_consent: 'auto',
+  autocapture: {
+    pageview: true,
+    click: true,
+    // or: click: { selector: '[data-analytics]' },
+    form_submit: true,
+    outbound_link: true,
+    scroll_depth: true,
+    web_vitals: true,
+  },
+});
+```
+
+## Flagging internal traffic
+
+Use the `is_internal` marker to keep QA sessions, staff testing, or automated smoke tests out of customer-facing reports without dropping them on the client. The SDK supports it in two complementary ways:
+
+**1. Per-event field.** Any `track` / `conversion` call can carry `is_internal: true`:
+
+```ts
+Mark.track('checkout_started', { value: 1299, is_internal: true });
+```
+
+**2. Persistent visitor flag.** Set it once and every subsequent event is stamped automatically:
+
+```ts
+Mark.setInternal(true);  // stamps is_internal: true on all future events
+Mark.setInternal(false); // stops stamping
+Mark.getInternal();      // boolean
+```
+
+The persistent flag is stored in the SDK's browser storage so it survives reloads. It is cleared automatically by `Mark.reset()` and by `Mark.setConsent('denied')`.
+
+**Design note.** The SDK intentionally does *not* read a magic URL parameter or write to a well-known `localStorage` key on its own — that would let anyone opt themselves out of your analytics just by visiting a URL, and it would bake a specific policy into every integration. Instead, your app decides when to flip the flag. A common pattern is a URL query parameter for staff onboarding:
+
+```ts
+// After Mark.init(...)
+const params = new URLSearchParams(window.location.search);
+if (params.get('onelence_internal') === '1') Mark.setInternal(true);
+if (params.get('onelence_internal') === '0') Mark.setInternal(false);
+```
+
+Other reasonable triggers: an authenticated admin/staff role, an internal IP range detected server-side, a feature flag, or an explicit toggle in your own settings UI.
+
+**Server-side** the same API is available on `NodeMark`:
+
+```ts
+const mark = createNodeMark({ key: process.env.MARK_SECRET_KEY! });
+mark.setInternal(true);
+mark.track('backoffice_action'); // is_internal: true
+```
+
+`is_internal` is a first-class field on the backend: events are still ingested (so you can audit and debug integrations), but excluded from customer-facing reports by default.
+
 ## Support
 
 Need help? Reach out through your account team or file a ticket via the OneLence dashboard. Please include the SDK version, runtime (browser or Node), and any reproduction steps so we can assist quickly.

package/dist/browser.es.js

@@ -1,4 +1,4 @@
-const S = "https://ingest.onelence.com";
+const I = "https://ingest.onelence.com";
 class h extends Error {
   status;
   retryAfterMs;
@@ -6,7 +6,7 @@ class h extends Error {
     super(t), this.name = "TransportError", this.status = e.status, this.retryAfterMs = e.retryAfterMs;
   }
 }
-function I(c) {
+function S(c) {
   return !(typeof c != "number" || c < 400 || c >= 500 || c === 408 || c === 429);
 }
 function E(c) {
@@ -22,10 +22,10 @@ function E(c) {
     return s > 0 ? s : 0;
   }
 }
-const x = 5, q = 300, T = 15e3, k = 2880 * 60 * 1e3;
-class D {
+const x = 5, q = 300, T = 15e3, D = 2880 * 60 * 1e3;
+class C {
   constructor(t, e = {}) {
-    this.transport = t, this.maxAttempts = e.maxAttempts ?? x, this.baseBackoffMs = e.baseBackoffMs ?? q, this.maxBackoffMs = e.maxBackoffMs ?? T, this.maxItemAgeMs = e.maxItemAgeMs ?? k, this.debug = e.debug ?? !1, this.loadPersisted = e.loadPersisted, this.savePersisted = e.savePersisted, this.onError = e.onError;
+    this.transport = t, this.maxAttempts = e.maxAttempts ?? x, this.baseBackoffMs = e.baseBackoffMs ?? q, this.maxBackoffMs = e.maxBackoffMs ?? T, this.maxItemAgeMs = e.maxItemAgeMs ?? D, this.debug = e.debug ?? !1, this.loadPersisted = e.loadPersisted, this.savePersisted = e.savePersisted, this.onError = e.onError;
     const i = this.loadPersisted?.() ?? [];
     if (i.length > 0) {
       const s = Date.now();
@@ -118,7 +118,7 @@ class D {
           } catch (i) {
             this.failed += 1, this.onError?.(i, e.data);
             const s = i instanceof h ? i.status : void 0;
-            if (I(s)) {
+            if (S(s)) {
               this.queue.shift(), this.dropped += 1, this.persist(), this.debug && console.error("[Mark] Dropping event after non-retriable status", s, e.path);
               continue;
             }
@@ -147,7 +147,7 @@ class D {
     }
   }
 }
-const C = /* @__PURE__ */ new Set(["event_name", "user_id", "consent_state", "source", "is_conversion"]), U = /* @__PURE__ */ new Set([
+const U = /* @__PURE__ */ new Set(["event_name", "user_id", "consent_state", "source", "is_conversion"]), k = /* @__PURE__ */ new Set([
   "user_id",
   "visitor_id",
   "click_id",
@@ -159,10 +159,10 @@ const C = /* @__PURE__ */ new Set(["event_name", "user_id", "consent_state", "so
 class L {
   constructor(t, e) {
     this.deps = e, this.validateConfig(t), this.config = {
-      endpoint: t.endpoint ?? S,
+      endpoint: t.endpoint ?? I,
       ...t,
       include_page_context: t.include_page_context ?? !0
-    }, this.consentRequirement = t.require_consent ?? !1, this.siteId = t.site_id, this.siteHost = t.site_host, this.sessionTimeoutMs = t.session_timeout_ms ?? 1800 * 1e3, this.queue = new D(this.deps.transport, {
+    }, this.consentRequirement = t.require_consent ?? !1, this.siteId = t.site_id, this.siteHost = t.site_host, this.sessionTimeoutMs = t.session_timeout_ms ?? 1800 * 1e3, this.queue = new C(this.deps.transport, {
       debug: this.config.debug,
       loadPersisted: () => this.deps.storage.getOutbox?.() ?? [],
       savePersisted: (i) => this.deps.storage.setOutbox?.(i),
@@ -214,7 +214,7 @@ class L {
     };
     i && (a.is_conversion = !0);
     const l = r.site_id ?? this.siteId, f = r.site_host ?? this.siteHost;
-    l && (a.site_id = l), f && (a.site_host = f), this.config.include_page_context && typeof window < "u" && (this.applyPageContext(a), !f && a.site && (a.site_host = a.site));
+    l && (a.site_id = l), f && (a.site_host = f), this.config.include_page_context && typeof window < "u" && (this.applyPageContext(a), !f && a.site && (a.site_host = a.site)), this.applyInternalFlag(a, r.is_internal);
     const d = this.config.before_send ? this.config.before_send(a) : a;
     return d ? (this.ensureSession(), this.config.batching?.enabled && !i && !s?.preferBeacon ? (this.enqueueBatch(d), !0) : (this.queue.enqueue("/event", { ...d, __prefer_beacon: s?.preferBeacon === !0 }), !0)) : !0;
   }
@@ -234,7 +234,7 @@ class L {
       ...this.sanitizeIdentifyTraits(e),
       ...this.getIdentityFields()
     };
-    this.siteId && (i.site_id = this.siteId), this.siteHost && (i.site_host = this.siteHost);
+    this.siteId && (i.site_id = this.siteId), this.siteHost && (i.site_host = this.siteHost), this.applyInternalFlag(i);
     const s = this.config.before_send ? this.config.before_send(i) : i;
     s && this.queue.enqueue("/identify", s);
   }
@@ -253,14 +253,14 @@ class L {
   }
   setConsent(t) {
     const e = this.deps.storage.getConsentStatus();
-    this.deps.storage.setConsentStatus(t), t === "denied" ? (this.deps.storage.clearAttribution?.(), this.deps.storage.clearCookieVisitorId?.()) : t === "granted" && e === "denied" && this.config.rotate_visitor_on_consent_change && this.deps.storage.rotateVisitorId?.();
+    this.deps.storage.setConsentStatus(t), t === "denied" ? (this.deps.storage.clearAttribution?.(), this.deps.storage.clearCookieVisitorId?.(), this.deps.storage.setInternal?.(!1)) : t === "granted" && e === "denied" && this.config.rotate_visitor_on_consent_change && this.deps.storage.rotateVisitorId?.();
     const i = {
       visitor_id: this.deps.storage.getVisitorId(),
       consent_state: t,
       source: "sdk",
       message_id: this.createMessageId()
     };
-    this.siteId && (i.site_id = this.siteId), this.siteHost && (i.site_host = this.siteHost);
+    this.siteId && (i.site_id = this.siteId), this.siteHost && (i.site_host = this.siteHost), this.applyInternalFlag(i);
     const s = this.config.before_send ? this.config.before_send(i) : i;
     s && this.queue.enqueue("/consent", s);
   }
@@ -272,15 +272,51 @@ class L {
       query_params: void 0,
       session_id: void 0,
       session_started_at: void 0,
-      last_activity_at: void 0
+      last_activity_at: void 0,
+      is_internal: void 0
     }), this.deps.storage.rotateVisitorId?.();
   }
+  /**
+   * Marks or unmarks the current visitor as internal traffic. While set, every
+   * subsequent event (track/identify/conversion/consent) is stamped with
+   * `is_internal: true`, so the backend can exclude it from customer-facing
+   * reports by default.
+   *
+   * The flag is persisted via the storage adapter (browser: localStorage) so
+   * it survives reloads, and is cleared by `reset()` and by
+   * `setConsent('denied')`.
+   */
+  setInternal(t) {
+    this.deps.storage.setInternal?.(!!t);
+  }
+  /**
+   * Returns the currently persisted internal-traffic flag, if any.
+   */
+  getInternal() {
+    return !!this.deps.storage.getInternal?.();
+  }
   flush() {
     return this.flushBatch(), this.queue.flush();
   }
   getStats() {
     return this.queue.getStats();
   }
+  /**
+   * Stamps `is_internal: true` on the payload when either:
+   * - the persistent visitor flag is set (via setInternal), or
+   * - the caller passed `is_internal: true` on this specific event.
+   *
+   * Explicit `is_internal: false` on a single event wins over the visitor flag
+   * so individual calls can opt out.
+   */
+  applyInternalFlag(t, e) {
+    if (e === !1) {
+      delete t.is_internal;
+      return;
+    }
+    const i = this.deps.storage.getInternal?.() === !0;
+    e === !0 || i ? t.is_internal = !0 : delete t.is_internal;
+  }
   getIdentityFields(t) {
     const e = t?.visitor_id ?? this.deps.storage.getVisitorId(), i = t?.user_id ?? this.deps.storage.getUserId?.(), s = t?.click_id ?? this.deps.storage.getLastClickId(), r = t?.campaign_id ?? this.deps.storage.getCampaignId(), o = t?.session_id ?? this.deps.storage.getSessionId?.(), a = this.deps.storage.getQueryParams() ?? {}, l = t?.query ?? {}, f = { ...a, ...l }, d = {};
     return e && (d.visitor_id = e), i && (d.user_id = i), s && (d.click_id = s), r && (d.campaign_id = r), o && (d.session_id = o), Object.keys(f).length > 0 && (d.query = f), d;
@@ -296,13 +332,13 @@ class L {
   sanitizeTrackData(t) {
     const e = {};
     for (const [i, s] of Object.entries(t))
-      C.has(i) || (e[i] = s);
+      U.has(i) || (e[i] = s);
     return e;
   }
   sanitizeIdentifyTraits(t) {
     const e = {};
     for (const [i, s] of Object.entries(t))
-      U.has(i) || (e[i] = s);
+      k.has(i) || (e[i] = s);
     return e;
   }
   validateConfig(t) {
@@ -426,7 +462,7 @@ class P {
   endpoint;
   pending = /* @__PURE__ */ new Set();
   constructor(t) {
-    this.config = t, this.endpoint = t.endpoint ?? S;
+    this.config = t, this.endpoint = t.endpoint ?? I;
   }
   async send(t, e, i) {
     const s = this.sendInternal(t, e, i);
@@ -456,7 +492,7 @@ class P {
       throw this.config.debug && console.error("[Mark] Global fetch is not available in this runtime."), new h("[Mark] Global fetch is not available in this runtime.");
     const l = this.config.request_timeout_ms ?? 1e4, f = new AbortController();
     let d = !1;
-    const p = setTimeout(() => {
+    const g = setTimeout(() => {
       d = !0, f.abort();
     }, l);
     try {
@@ -468,16 +504,16 @@ class P {
         signal: f.signal
       });
       if (!u.ok) {
-        const g = await this.readErrorSnippet(u), y = E(u.headers.get("Retry-After"));
+        const p = await this.readErrorSnippet(u), w = E(u.headers.get("Retry-After"));
         throw this.config.debug && console.error("[Mark] Request rejected", {
           url: s,
           status: u.status,
           statusText: u.statusText,
-          body: g,
-          retryAfterMs: y
+          body: p,
+          retryAfterMs: w
         }), new h(
-          `[Mark] Request rejected with status ${u.status}: ${g}`,
-          { status: u.status, retryAfterMs: y }
+          `[Mark] Request rejected with status ${u.status}: ${p}`,
+          { status: u.status, retryAfterMs: w }
         );
       }
     } catch (u) {
@@ -485,10 +521,10 @@ class P {
         throw u;
       if (d)
         throw new h(`[Mark] Request timed out after ${l}ms`, { status: 408 });
-      const g = u instanceof Error ? u.message : String(u);
-      throw new h(`[Mark] Network error: ${g}`);
+      const p = u instanceof Error ? u.message : String(u);
+      throw new h(`[Mark] Network error: ${p}`);
     } finally {
-      clearTimeout(p);
+      clearTimeout(g);
     }
   }
   joinUrl(t, e) {
@@ -503,7 +539,7 @@ class P {
     }
   }
 }
-const R = "crelora_mark_data", B = "crelora_mark_outbox", w = "crelora_mark_vid";
+const R = "crelora_mark_data", B = "crelora_mark_outbox", y = "crelora_mark_vid";
 class F {
   data;
   storageKey;
@@ -546,6 +582,12 @@ class F {
   getLastActivityAt() {
     return this.data.last_activity_at;
   }
+  getInternal() {
+    return this.data.is_internal;
+  }
+  setInternal(t) {
+    t ? this.update({ is_internal: !0 }) : this.update({ is_internal: void 0 });
+  }
   update(t) {
     this.data = { ...this.data, ...t }, this.save();
   }
@@ -560,7 +602,7 @@ class F {
     });
   }
   clearCookieVisitorId() {
-    this.setCookie(w, "", -1);
+    this.setCookie(y, "", -1);
   }
   rotateVisitorId() {
     this.update({ visitor_id: this.generateUUID() });
@@ -592,7 +634,7 @@ class F {
         return JSON.parse(e);
     } catch {
     }
-    const t = this.getCookie(w);
+    const t = this.getCookie(y);
     return t ? { visitor_id: t } : {};
   }
   save() {
@@ -601,7 +643,7 @@ class F {
         localStorage.setItem(this.storageKey, JSON.stringify(this.data));
       } catch {
       }
-      this.data.visitor_id && this.isCookieEnabled() && (this.setCookie(w, this.data.visitor_id, 365), this.options.bridge?.url && this.bridgeReady && this.postBridgeMessage({
+      this.data.visitor_id && this.isCookieEnabled() && (this.setCookie(y, this.data.visitor_id, 365), this.options.bridge?.url && this.bridgeReady && this.postBridgeMessage({
         type: "MARK_SYNC_UPDATE",
         visitorId: this.data.visitor_id
       }));
@@ -756,14 +798,14 @@ function j(c, t) {
     const d = m(l);
     if (!d)
       continue;
-    const p = K[d] ?? d;
-    if (i.has(d) || i.has(p) || a && !a.has(d))
+    const g = K[d] ?? d;
+    if (i.has(d) || i.has(g) || a && !a.has(d))
       continue;
     const u = f.trim();
     if (u) {
-      if (!(p in e) && Object.keys(e).length >= s)
+      if (!(g in e) && Object.keys(e).length >= s)
         break;
-      e[p] = u.slice(0, r);
+      e[g] = u.slice(0, r);
     }
   }
   return e;
@@ -877,6 +919,30 @@ class n {
   static flush() {
     return n.client ? n.client.flush() : Promise.resolve();
   }
+  /**
+   * Flags (or un-flags) the current visitor as internal traffic. Persists
+   * across reloads via the SDK's browser storage. Cleared by `reset()` and by
+   * `setConsent('denied')`.
+   *
+   * The policy for deciding *when* to call this (URL query parameter, auth
+   * role, IP, feature flag, etc.) is intentionally left to the host app.
+   *
+   * @example
+   *   // URL-based opt-in: call once during app bootstrap, after Mark.init()
+   *   const params = new URLSearchParams(window.location.search);
+   *   if (params.get('onelence_internal') === '1') Mark.setInternal(true);
+   *   if (params.get('onelence_internal') === '0') Mark.setInternal(false);
+   */
+  static setInternal(t) {
+    if (!n.client) {
+      n.config?.debug && console.warn("[Mark] Not initialized. Call init() first.");
+      return;
+    }
+    n.client.setInternal(t);
+  }
+  static getInternal() {
+    return n.client?.getInternal() ?? !1;
+  }
   static reset() {
     n.client?.reset(), n.pendingAttribution = {}, n.lastPageviewHref = null;
   }