@noirtrack/sdk 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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

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.js

@@ -133,6 +133,7 @@ function noopClient(cookieless) {
     return {
         view: noop,
         event: noop,
+        outbound: noop,
         identify: noop,
         revenue: noop,
         reset: noop,
@@ -150,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) {
@@ -181,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'),
@@ -213,7 +221,7 @@ export function createClient(options) {
             }
         },
         context,
-        disabled: () => blocked,
+        disabled: () => blocked || !allowed,
         deliver(url, body) {
             const json = JSON.stringify(body);
             if (navigator.sendBeacon) {
@@ -235,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.
@@ -269,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 = () => {
@@ -277,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.1",
+    "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": {