@noirtrack/sdk 0.1.0

package/dist/web.js

@@ -0,0 +1,271 @@
+/**
+ * @noirtrack/sdk/web — browser analytics for frameworks (React, Vue, Svelte, and friends).
+ *
+ *   import { createClient } from '@noirtrack/sdk/web';
+ *   const noir = createClient({ publicKey: 'pk_live_...', autoPageviews: true });
+ *   noir.event('signup', { plan: 'pro' });
+ *
+ * Uses the public key only (browser code can't hold a secret). Safe to import in SSR: when there
+ * is no `window`, every method is a no-op and `init`-time tracking is skipped.
+ */
+import { resolveEndpoint } from './core/endpoint.js';
+import { uuid } from './core/ids.js';
+import { createIngest } from './core/ingest.js';
+const hasWindow = typeof window !== 'undefined' && typeof document !== 'undefined';
+function getCookie(name) {
+    const m = document.cookie.match('(^|;)\\s*' + name + '\\s*=\\s*([^;]+)');
+    return m ? (m.pop() ?? null) : null;
+}
+function setCookie(name, value, days) {
+    const d = new Date();
+    d.setTime(d.getTime() + days * 86_400_000);
+    document.cookie = `${name}=${value};expires=${d.toUTCString()};path=/;SameSite=Lax`;
+}
+function isBot() {
+    try {
+        if (navigator.webdriver)
+            return true;
+        const ua = (navigator.userAgent || '').toLowerCase();
+        if (!ua || ua.length < 5)
+            return true;
+        return /headless|phantom|selenium|puppeteer|playwright|webdriver|bot|crawl|spider|curl|wget|python|axios|postman/.test(ua);
+    }
+    catch {
+        return false;
+    }
+}
+function scrollPercent() {
+    try {
+        const h = document.documentElement;
+        const max = h.scrollHeight - h.clientHeight;
+        return max > 0 ? Math.min(100, Math.round(((h.scrollTop || window.pageYOffset || 0) / max) * 100)) : 100;
+    }
+    catch {
+        return 0;
+    }
+}
+/** `data-noir-goal-plan="pro"` → `{ plan: "pro" }` (kebab-case suffix → snake_case key). */
+function metaFromAttrs(el, prefix) {
+    let meta;
+    for (const attr of Array.from(el.attributes)) {
+        if (attr.name.startsWith(prefix) && attr.name.length > prefix.length) {
+            (meta ??= {})[attr.name.slice(prefix.length).replace(/-/g, '_')] = attr.value;
+        }
+    }
+    return meta;
+}
+/**
+ * Declarative goals, matching the hosted snippet so markup is portable between snippet and SDK:
+ *   <button data-noir-goal="cta" data-noir-goal-loc="hero">   — fires on click (event delegation)
+ *   <section data-noir-scroll="viewed_pricing">                — fires once when scrolled into view
+ * Click uses delegation so dynamically-rendered elements work; scroll targets are (re-)scanned via a
+ * MutationObserver because a framework mounts them after createClient() runs.
+ */
+function initDeclarativeGoals(fire) {
+    document.addEventListener('click', (e) => {
+        const el = e.target?.closest?.('[data-noir-goal]');
+        const name = el?.getAttribute('data-noir-goal');
+        if (el && name)
+            fire(name, metaFromAttrs(el, 'data-noir-goal-'));
+    }, true);
+    if (!('IntersectionObserver' in window))
+        return;
+    const observed = new WeakSet();
+    const observeScroll = (el) => {
+        if (observed.has(el))
+            return;
+        observed.add(el);
+        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;
+        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) {
+                    obs.disconnect(); // once per element per page
+                    const meta = { scroll_percentage: scrollPercent(), threshold };
+                    if (delay > 0)
+                        setTimeout(() => fire(name, meta), delay);
+                    else
+                        fire(name, meta);
+                    return;
+                }
+            }
+        }, { threshold });
+        obs.observe(el);
+    };
+    const scan = () => document.querySelectorAll('[data-noir-scroll]').forEach(observeScroll);
+    scan();
+    if (window.MutationObserver) {
+        let queued = false;
+        new MutationObserver(() => {
+            if (queued)
+                return;
+            queued = true;
+            setTimeout(() => {
+                queued = false;
+                scan();
+            }, 200);
+        }).observe(document.documentElement, { childList: true, subtree: true });
+    }
+}
+/** A no-op client for SSR (no window) so imports and calls are always safe. */
+function noopClient(cookieless) {
+    const noop = () => { };
+    return {
+        view: noop,
+        event: noop,
+        identify: noop,
+        revenue: noop,
+        reset: noop,
+        flush: noop,
+        ping: noop,
+        links: { params: () => ({ noir_vid: '', noir_sid: '' }), decorate: (url) => url },
+        shield: async () => ({ ok: true, reason: null }),
+        check: async () => null,
+        cookieless,
+    };
+}
+export function createClient(options) {
+    const cookieless = options.cookieless ?? false;
+    if (!hasWindow)
+        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;
+    // Visitor + session ids. With cookies: persistent vid (365d) + short sid (30m). Cookieless:
+    // sessionStorage only, so nothing is written to the device.
+    function id(kind) {
+        const cookieName = kind === 'vid' ? 'noir_vid' : 'noir_sid';
+        if (cookieless) {
+            try {
+                let v = sessionStorage.getItem(cookieName);
+                if (!v) {
+                    v = uuid();
+                    sessionStorage.setItem(cookieName, v);
+                }
+                return v;
+            }
+            catch {
+                return null;
+            }
+        }
+        let v = getCookie(cookieName);
+        if (!v) {
+            v = uuid();
+            setCookie(cookieName, v, kind === 'vid' ? 365 : 1 / 48);
+        }
+        return v;
+    }
+    function context(pathOverride) {
+        const params = new URLSearchParams(location.search);
+        return {
+            host: location.hostname,
+            path: pathOverride ?? location.pathname + location.search,
+            referrer: document.referrer || null,
+            screen: window.screen ? `${screen.width}x${screen.height}` : null,
+            utm: {
+                source: params.get('utm_source'),
+                medium: params.get('utm_medium'),
+                campaign: params.get('utm_campaign'),
+            },
+        };
+    }
+    const platform = {
+        publicKey: options.publicKey,
+        endpoint,
+        timeoutMs: options.timeoutMs ?? 800,
+        batch: true,
+        flushIntervalMs: options.flushIntervalMs ?? 5000,
+        maxQueueSize: options.maxQueueSize ?? 10,
+        visitorId: () => id('vid'),
+        sessionId: () => id('sid'),
+        resetIds() {
+            if (cookieless) {
+                try {
+                    sessionStorage.removeItem('noir_vid');
+                    sessionStorage.removeItem('noir_sid');
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            else {
+                setCookie('noir_vid', '', -1);
+                setCookie('noir_sid', '', -1);
+            }
+        },
+        context,
+        disabled: () => blocked,
+        deliver(url, body) {
+            const json = JSON.stringify(body);
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(url, new Blob([json], { type: 'application/json' }));
+            }
+            else {
+                void fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: json, keepalive: true }).catch(() => { });
+            }
+        },
+        scheduleFlush(flush) {
+            setInterval(flush, options.flushIntervalMs ?? 5000);
+            const final = () => {
+                if (document.visibilityState === 'hidden')
+                    flush();
+            };
+            document.addEventListener('visibilitychange', final);
+            window.addEventListener('pagehide', flush);
+        },
+    };
+    const ingest = createIngest(platform);
+    const client = { ...ingest, cookieless };
+    if (!blocked) {
+        // 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.
+        const wantsBlock = !!options.block;
+        if (wantsBlock) {
+            void ingest.check().then((verdict) => {
+                if (verdict?.action !== 'block')
+                    return;
+                const page = verdict.blocked_page ?? options.blockedPage;
+                if (options.block === 'redirect' && page)
+                    location.replace(page);
+                else
+                    overlay();
+            });
+        }
+        if (options.autoPageviews ?? true) {
+            if (!wantsBlock)
+                ingest.view(); // when blocking, check() already recorded the first view
+            const onRoute = () => ingest.view();
+            const push = history.pushState;
+            history.pushState = function (...args) {
+                push.apply(this, args);
+                onRoute();
+            };
+            window.addEventListener('popstate', onRoute);
+        }
+        // Declarative goals (data-noir-goal / data-noir-scroll) — parity with the hosted snippet.
+        if (options.autoGoals ?? true) {
+            initDeclarativeGoals((name, meta) => ingest.event(name, meta));
+        }
+        // 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 = () => {
+            if (document.visibilityState === 'visible')
+                ingest.ping();
+        };
+        document.addEventListener('visibilitychange', heartbeat);
+        setInterval(heartbeat, 45_000);
+    }
+    return client;
+}
+function overlay() {
+    const el = document.createElement('div');
+    el.setAttribute('style', 'position:fixed;inset:0;z-index:2147483647;background:#0a0a0a;color:#fff;' +
+        'display:flex;align-items:center;justify-content:center;font:600 16px system-ui;padding:2rem;text-align:center');
+    el.textContent = 'Access blocked';
+    document.documentElement.appendChild(el);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+    "name": "@noirtrack/sdk",
+    "version": "0.1.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": {
+        "url": "https://noirtrack.com/docs"
+    },
+    "author": "NoirTrack",
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./web": {
+            "types": "./dist/web.d.ts",
+            "import": "./dist/web.js"
+        },
+        "./react-native": {
+            "types": "./dist/react-native.d.ts",
+            "import": "./dist/react-native.js"
+        },
+        "./next": {
+            "types": "./dist/next.d.ts",
+            "import": "./dist/next.js"
+        },
+        "./express": {
+            "types": "./dist/express.d.ts",
+            "import": "./dist/express.js"
+        },
+        "./fetch": {
+            "types": "./dist/fetch.d.ts",
+            "import": "./dist/fetch.js"
+        },
+        "./form-shield": {
+            "types": "./dist/form-shield.d.ts",
+            "import": "./dist/form-shield.js"
+        }
+    },
+    "files": ["dist"],
+    "scripts": {
+        "build": "tsc",
+        "test:live": "node ../docs/live-test.mjs"
+    },
+    "keywords": ["noirtrack", "firewall", "bot-detection", "waf", "revenue", "goals", "middleware", "nextjs", "express", "edge"],
+    "license": "MIT",
+    "engines": {
+        "node": ">=18"
+    },
+    "peerDependencies": {
+        "express": ">=4",
+        "next": ">=13"
+    },
+    "peerDependenciesMeta": {
+        "express": { "optional": true },
+        "next": { "optional": true }
+    },
+    "devDependencies": {
+        "@types/express": "^4.17.21",
+        "express": "^4.19.0",
+        "next": "^14.0.0",
+        "typescript": "^5.4.0"
+    }
+}