@noirtrack/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,11 +2,25 @@
 
 All notable changes to `@noirtrack/sdk` are documented here. This project follows semantic versioning (while pre-1.0, a minor bump may include breaking changes).
 
+## 0.3.0
+
+### Added
+
+- **Outbound link tracking (web client).** Clicks on links that leave your site are recorded automatically as `$outbound` events with the destination, matching the hosted snippet. Powers the new Outbound links breakdown.
+- **Cookie consent gate (web client).** When you enable a consent banner in the dashboard (Settings → Cookie consent), a non-cookieless client holds all tracking behind it for visitors in the regions you choose, until they accept — no code change, the client reads the setting on load.
+- **Language.** The web client now sends the visitor's `navigator.language`, so the dashboard's Languages breakdown reflects real traffic.
+
+## 0.2.1
+
+### Fixed
+
+- **Scroll goals on tall sections.** `data-noir-scroll-threshold` is the fraction of the *element* visible at once, so a section taller than the viewport could never reach it and the goal never fired. The effective threshold is now capped to what's reachable for the element's height, so a tall section fires once it has essentially filled the screen. Short elements are unaffected. The same fix ships in the hosted snippet.
+
 ## 0.2.0
 
 ### Changed
 
-- **Breaking (web client):** `block` is now a boolean. Turn on the Traffic Filter with `createClient({ block: true })` instead of `block: 'redirect' | 'overlay'`. Whether it monitors or blocks, and how a block looks (redirect or overlay), are now set per site in Firewall settings, with no code change. If you passed `block: 'redirect'` or `block: 'overlay'`, change it to `block: true`.
+- **Breaking (web client):** `block` is now a boolean. Turn on the firewall with `createClient({ block: true })` instead of `block: 'redirect' | 'overlay'`. Whether it monitors or blocks, and how a block looks (redirect or overlay), are now set per site in Firewall settings, with no code change. If you passed `block: 'redirect'` or `block: 'overlay'`, change it to `block: true`.
 
 ### Added
 

package/README.md

@@ -26,7 +26,7 @@ noir.identify('user_123', { email });
 noir.revenue({ checkoutId: 'cs_test_123' });
 ```
 
-Pageviews and route changes are automatic. Events are batched and sent with `sendBeacon`. Set `cookieless: true` for a no-cookie mode, or `block: true` to turn on the Traffic Filter. Whether it monitors or blocks, and how a block looks (redirect or overlay), are set in your Firewall settings, with no code change. Safe to import in SSR (it does nothing without a window). Also: `view(path?)`, `reset()`, `flush()`, `links.decorate(url)`.
+Pageviews and route changes are automatic. Events are batched and sent with `sendBeacon`. Set `cookieless: true` for a no-cookie mode, or `block: true` to turn on the firewall. Whether it monitors or blocks, and how a block looks (redirect or overlay), are set in your Firewall settings, with no code change. Safe to import in SSR (it does nothing without a window). Also: `view(path?)`, `reset()`, `flush()`, `links.decorate(url)`.
 
 ## React Native
 
@@ -95,7 +95,7 @@ The guards resolve the visitor IP from `CF-Connecting-IP`, `True-Client-IP`, the
 | `timeoutMs`                               | `800`                  | all      | Abort a call after this, then fail open.                |
 | `autoPageviews`                           | `true`                 | web      | Capture initial + SPA pageviews.                        |
 | `cookieless`                              | `false`                | web      | No cookies; ids in sessionStorage.                      |
-| `block`                                   | `false`                | web      | Turn on the Traffic Filter (Monitor/Block set in dashboard). |
+| `block`                                   | `false`                | web      | Turn on the firewall (Monitor/Block set in dashboard). |
 | `flushIntervalMs` / `maxQueueSize`        | `5000` / `10`          | web, RN  | Batch flush tuning.                                     |
 | `storage`                                 | in-memory              | RN       | Async store (pass AsyncStorage).                        |
 | `onBlock` / `blockStatus` / `blockedPage` | `block` / `403` / none | adapters | Block handling.                                         |

package/dist/core/ingest.d.ts

@@ -6,6 +6,8 @@ export interface IngestContext {
     path: string;
     referrer: string | null;
     screen: string | null;
+    /** Visitor's primary language (navigator.language); normalised server-side. */
+    lang?: string | null;
     utm: {
         source: string | null;
         medium: string | null;
@@ -38,6 +40,8 @@ export interface Ingest {
     view(path?: string): void;
     /** Record a custom event. */
     event(name: string, props?: Props): void;
+    /** Record a click that leaves the site (an `$outbound` event; the destination rides `path`). */
+    outbound(url: string): void;
     /**
      * Attach customer info to the current visitor. Pass one object — `userId`, `name`, `email`, and any
      * custom fields — matching the snippet's `noir('identify', {…})`. The legacy `(userId, traits)` form

package/dist/core/ingest.js

@@ -17,6 +17,7 @@ export function createIngest(platform) {
             path: ctx.path,
             referrer: ctx.referrer,
             screen: ctx.screen,
+            lang: ctx.lang ?? null,
             visitor_id: platform.visitorId(),
             session_id: platform.sessionId(),
             utm: ctx.utm,
@@ -58,6 +59,10 @@ export function createIngest(platform) {
     function event(name, props) {
         enqueue(payload(name, undefined, props));
     }
+    // Outbound click → `$outbound` event with the destination in `path` (parity with the hosted snippet).
+    function outbound(url) {
+        enqueue(payload('$outbound', url));
+    }
     function identify(user, traits = {}) {
         // One object — { userId, name, email, …custom } — matches the snippet. Legacy (userId, traits)
         // is normalised to the same shape so both forms send an identical `userId` field.
@@ -121,5 +126,5 @@ export function createIngest(platform) {
             }
             : null);
     }
-    return { view, event, identify, revenue, reset, flush, ping, links, shield, check };
+    return { view, event, outbound, identify, revenue, reset, flush, ping, links, shield, check };
 }

package/dist/web.d.ts

@@ -11,8 +11,8 @@ export interface WebClientOptions {
     cookieless?: boolean;
     /** Track on localhost too (off by default, like the hosted script). */
     allowLocalhost?: boolean;
-    /** Turn on the Traffic Filter on the first view. Whether it monitors or blocks, and how a block
-     *  looks (redirect or overlay), are set per site in Firewall settings. Off by default. */
+    /** Turn on the firewall on the first view. Whether it monitors or blocks, and how a block looks
+     *  (redirect or overlay), are set per site in Firewall settings. Off by default. */
     block?: boolean;
     /** Optional redirect target if none is set in Firewall settings. */
     blockedPage?: string;

package/dist/web.js

@@ -70,6 +70,11 @@ function initDeclarativeGoals(fire) {
     }, true);
     if (!('IntersectionObserver' in window))
         return;
+    // Granular thresholds so the callback runs across the whole scroll range; the actual trigger is
+    // computed live per element (see below), so we can't rely on a single fixed threshold.
+    const STEPS = [];
+    for (let s = 0; s <= 1.0001; s += 0.05)
+        STEPS.push(Math.round(s * 100) / 100);
     const observed = new WeakSet();
     const observeScroll = (el) => {
         if (observed.has(el))
@@ -78,15 +83,25 @@ function initDeclarativeGoals(fire) {
         const name = el.getAttribute('data-noir-scroll');
         if (!name)
             return;
-        let threshold = parseFloat(el.getAttribute('data-noir-scroll-threshold') ?? '');
-        if (!(threshold > 0 && threshold <= 1))
-            threshold = 0.5;
+        let requested = parseFloat(el.getAttribute('data-noir-scroll-threshold') ?? '');
+        if (!(requested > 0 && requested <= 1))
+            requested = 0.5;
         const delay = parseInt(el.getAttribute('data-noir-scroll-delay') ?? '', 10) || 0;
         const obs = new IntersectionObserver((entries) => {
             for (const entry of entries) {
-                if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+                if (!entry.isIntersecting)
+                    continue;
+                // A section taller than the viewport can never expose `requested` of itself at once —
+                // the most ever visible is viewportHeight/elementHeight. Compare against that reachable
+                // max (×0.9) so a tall element still fires once it has essentially filled the screen,
+                // instead of never firing. Short elements keep their requested threshold. // why
+                const elHeight = entry.boundingClientRect.height;
+                const viewport = entry.rootBounds?.height || window.innerHeight || 0;
+                const reachable = elHeight > 0 && viewport > 0 ? (viewport / elHeight) * 0.9 : 1;
+                const effective = Math.min(requested, reachable);
+                if (entry.intersectionRatio >= effective) {
                     obs.disconnect(); // once per element per page
-                    const meta = { scroll_percentage: scrollPercent(), threshold };
+                    const meta = { scroll_percentage: scrollPercent(), threshold: requested };
                     if (delay > 0)
                         setTimeout(() => fire(name, meta), delay);
                     else
@@ -94,7 +109,7 @@ function initDeclarativeGoals(fire) {
                     return;
                 }
             }
-        }, { threshold });
+        }, { threshold: STEPS });
         obs.observe(el);
     };
     const scan = () => document.querySelectorAll('[data-noir-scroll]').forEach(observeScroll);
@@ -118,6 +133,7 @@ function noopClient(cookieless) {
     return {
         view: noop,
         event: noop,
+        outbound: noop,
         identify: noop,
         revenue: noop,
         reset: noop,
@@ -135,6 +151,12 @@ export function createClient(options) {
         return noopClient(cookieless);
     const endpoint = resolveEndpoint(options.endpoint);
     const blocked = isBot() || (!options.allowLocalhost && /^(localhost|127\.0\.0\.1|\[::1\])$/.test(location.hostname)) || window.top !== window.self;
+    // Consent gate (dashboard-driven, parity with the hosted snippet). When the site enables a banner
+    // in Settings → Cookie consent, a non-cookieless client holds ALL tracking until this visitor's
+    // region is cleared or they accept. Cookieless stores nothing on the device, so it skips the gate.
+    // `allowed` gates every send via platform.disabled() below; initConsent() flips it open.
+    const consentGate = !cookieless;
+    let allowed = !consentGate;
     // Visitor + session ids. With cookies: persistent vid (365d) + short sid (30m). Cookieless:
     // sessionStorage only, so nothing is written to the device.
     function id(kind) {
@@ -166,6 +188,7 @@ export function createClient(options) {
             path: pathOverride ?? location.pathname + location.search,
             referrer: document.referrer || null,
             screen: window.screen ? `${screen.width}x${screen.height}` : null,
+            lang: navigator.language || null,
             utm: {
                 source: params.get('utm_source'),
                 medium: params.get('utm_medium'),
@@ -198,7 +221,7 @@ export function createClient(options) {
             }
         },
         context,
-        disabled: () => blocked,
+        disabled: () => blocked || !allowed,
         deliver(url, body) {
             const json = JSON.stringify(body);
             if (navigator.sendBeacon) {
@@ -220,7 +243,10 @@ export function createClient(options) {
     };
     const ingest = createIngest(platform);
     const client = { ...ingest, cookieless };
-    if (!blocked) {
+    // Everything that tracks lives here so the consent gate can hold it until the visitor accepts.
+    // Opening `allowed` first is what lets the gated senders (view/event/ping/…) fire.
+    const startTracking = () => {
+        allowed = true;
         // Soft block on the first view: ask the server, then enforce. /api/v1/check already RECORDS
         // this pageview (stamped with the verdict), so when blocking is on we must NOT also call
         // ingest.view() for the first view, or it would be counted twice.
@@ -254,6 +280,23 @@ export function createClient(options) {
         if (options.autoGoals ?? true) {
             initDeclarativeGoals((name, meta) => ingest.event(name, meta));
         }
+        // Outbound link tracking — clicks that leave the site become `$outbound` events (parity with
+        // the hosted snippet). Same-site and non-http(s) links (mailto:, tel:) are skipped.
+        document.addEventListener('click', (e) => {
+            const a = e.target?.closest?.('a[href]');
+            if (!a)
+                return;
+            let url;
+            try {
+                url = new URL(a.href, location.href);
+            }
+            catch {
+                return;
+            }
+            if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.host === location.host)
+                return;
+            ingest.outbound(url.host + url.pathname);
+        }, true);
         // Presence heartbeat — keep this visitor in the realtime count while the tab is visible
         // (parity with the hosted snippet). Paused when hidden; re-sent the instant it regains focus.
         const heartbeat = () => {
@@ -262,9 +305,135 @@ export function createClient(options) {
         };
         document.addEventListener('visibilitychange', heartbeat);
         setInterval(heartbeat, 45_000);
+    };
+    if (!blocked) {
+        if (consentGate)
+            initConsent(endpoint, options.publicKey, startTracking);
+        else
+            startTracking();
     }
     return client;
 }
+const CONSENT_KEY = 'noir_consent';
+function readConsentDecision() {
+    try {
+        return JSON.parse(localStorage.getItem(CONSENT_KEY) || 'null');
+    }
+    catch {
+        return null;
+    }
+}
+function writeConsentDecision(decision, reaskDays) {
+    try {
+        localStorage.setItem(CONSENT_KEY, JSON.stringify({ d: decision, exp: Date.now() + reaskDays * 86_400_000 }));
+    }
+    catch {
+        /* storage may be unavailable */
+    }
+}
+/**
+ * Ask the server whether THIS visitor needs the banner, honouring a fresh stored decision first so a
+ * returning decider skips the round-trip. A "not required" result is cached briefly so an ungated site
+ * doesn't call on every load, while still picking up a newly-enabled banner within ~30 min. Fail-open,
+ * matching the SDK's philosophy: a consent-endpoint hiccup opens the gate rather than losing analytics.
+ */
+function initConsent(endpoint, publicKey, start) {
+    const rec = readConsentDecision();
+    if (rec && rec.exp && rec.exp > Date.now()) {
+        if (rec.d === 'a')
+            start(); // accepted & fresh → track; declined → stay silent
+        return;
+    }
+    void fetch(`${endpoint}/api/v1/consent`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ site_key: publicKey }),
+    })
+        .then((r) => r.json())
+        .then((res) => {
+        if (!res || !res.required) {
+            writeConsentDecision('a', 1 / 48); // ~30 min: re-check so an enabled banner reaches seen visitors
+            start();
+            return;
+        }
+        renderConsentBanner(res.banner ?? {}, start);
+    })
+        .catch(() => start());
+}
+// Brand indigo (NoirTrack --primary ≈ hsl(243 75% 59%)). Self-contained banner that adapts to the
+// visitor's site theme (prefers-color-scheme), so it reads well on any light or dark host page.
+const CONSENT_ACCENT = '#5048e5';
+const CONSENT_SHIELD = `<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="${CONSENT_ACCENT}" stroke-width="2" ` +
+    'stroke-linecap="round" stroke-linejoin="round"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10Z"/><path d="m9 12 2 2 4-4"/></svg>';
+function renderConsentBanner(cfg, onAccept) {
+    const pos = cfg.position || 'bottom';
+    const box = pos === 'bottom-left' || pos === 'bottom-right';
+    let dark = false;
+    try {
+        dark = !!(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches);
+    }
+    catch {
+        /* matchMedia may be unavailable */
+    }
+    const cardBg = dark ? '#0f172a' : '#ffffff';
+    const textCol = dark ? '#e2e8f0' : '#334155';
+    const ring = dark ? 'rgba(255,255,255,0.10)' : 'rgba(15,23,42,0.08)';
+    const declineBorder = dark ? 'rgba(255,255,255,0.16)' : '#cbd5e1';
+    const wrap = document.createElement('div');
+    const pin = box
+        ? 'bottom:16px;' + (pos === 'bottom-left' ? 'left:16px;' : 'right:16px;') + 'max-width:400px;'
+        : 'left:16px;right:16px;' + (pos === 'top' ? 'top:16px;' : 'bottom:16px;') + 'max-width:920px;margin:0 auto;';
+    wrap.setAttribute('style', 'position:fixed;z-index:2147483646;' +
+        pin +
+        'font:14px/1.55 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;display:flex;gap:14px;align-items:center;flex-wrap:wrap;' +
+        `background:${cardBg};color:${textCol};border:1px solid ${ring};border-radius:16px;padding:16px 18px;` +
+        `box-shadow:0 12px 42px -10px rgba(0,0,0,${dark ? '0.65' : '0.22'});`);
+    const icon = document.createElement('span');
+    icon.setAttribute('style', 'display:flex;align-items:center;justify-content:center;width:34px;height:34px;flex:none;border-radius:10px;background:rgba(80,72,229,0.14);');
+    icon.innerHTML = CONSENT_SHIELD; // hardcoded constant (no user data) — safe
+    const msg = document.createElement('div');
+    msg.setAttribute('style', 'flex:1 1 240px;min-width:0;');
+    msg.textContent = cfg.message || 'We use privacy-friendly analytics. No personal data is sold or shared.';
+    if (cfg.privacyUrl) {
+        const a = document.createElement('a');
+        a.href = cfg.privacyUrl;
+        a.target = '_blank';
+        a.rel = 'noopener';
+        a.textContent = 'Privacy';
+        a.setAttribute('style', `margin-left:6px;color:${CONSENT_ACCENT};font-weight:500;text-decoration:underline;`);
+        msg.appendChild(a);
+    }
+    const btns = document.createElement('div');
+    btns.setAttribute('style', 'display:flex;gap:8px;flex:0 0 auto;');
+    const decline = document.createElement('button');
+    decline.type = 'button';
+    decline.textContent = cfg.decline || 'Decline';
+    decline.setAttribute('style', `padding:9px 15px;border:1px solid ${declineBorder};background:transparent;color:${textCol};border-radius:10px;font:inherit;font-weight:500;cursor:pointer;`);
+    const accept = document.createElement('button');
+    accept.type = 'button';
+    accept.textContent = cfg.accept || 'Accept';
+    accept.setAttribute('style', `padding:9px 15px;border:0;background:${CONSENT_ACCENT};color:#fff;border-radius:10px;font:inherit;font-weight:600;cursor:pointer;box-shadow:0 1px 2px rgba(0,0,0,0.15);`);
+    const close = () => {
+        if (wrap.parentNode)
+            wrap.parentNode.removeChild(wrap);
+    };
+    const reask = cfg.reaskDays || 180;
+    accept.addEventListener('click', () => {
+        writeConsentDecision('a', reask);
+        close();
+        onAccept();
+    });
+    decline.addEventListener('click', () => {
+        writeConsentDecision('d', reask); // stay silent until the re-ask window lapses
+        close();
+    });
+    btns.appendChild(decline);
+    btns.appendChild(accept);
+    wrap.appendChild(icon);
+    wrap.appendChild(msg);
+    wrap.appendChild(btns);
+    (document.body || document.documentElement).appendChild(wrap);
+}
 function overlay() {
     const el = document.createElement('div');
     el.setAttribute('style', 'position:fixed;inset:0;z-index:2147483647;background:#0a0a0a;color:#fff;' +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@noirtrack/sdk",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "NoirTrack server SDK. Block bots and bad traffic before your app renders, and record goals, revenue, and identify from your backend with one secret key. Framework-agnostic core plus Next.js, Express, and fetch/edge adapters.",
     "homepage": "https://noirtrack.com/docs",
     "bugs": {