@noirtrack/sdk 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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.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 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
+
+- `Verdict.style` (`'redirect' | 'overlay' | null`): the block style returned by the server. The web client applies it automatically, so the snippet and SDK no longer hardcode the style.
+
+## 0.1.0
+
+- Initial release. Framework-agnostic core with browser, React Native, Next.js, Express, and fetch/edge adapters. Analytics, firewall decisions, goals, revenue, identify, and Form Shield, all from one client.

package/README.md

@@ -4,7 +4,7 @@ One NoirTrack SDK for the browser, React Native, and your server. You set your k
 
 Works in any runtime with a global `fetch`: Node 18+, Next.js, Cloudflare Workers, Deno, Bun, the browser, and React Native. ESM only.
 
-**Docs:** [noirtrack.com/docs](https://noirtrack.com/docs) — [NPM SDK guide](https://noirtrack.com/docs/npm-sdk) · [Server SDK reference](https://noirtrack.com/docs/server-sdk)
+**Docs:** [noirtrack.com/docs](https://noirtrack.com/docs) · [NPM SDK guide](https://noirtrack.com/docs/npm-sdk) · [Server SDK reference](https://noirtrack.com/docs/server-sdk)
 
 ## Install
 
@@ -26,7 +26,7 @@ noir.identify('user_123', { email });
 noir.revenue({ checkoutId: 'cs_test_123' });
 ```
 
-Pageviews and SPA route changes are automatic. Events are batched and sent with `sendBeacon`. Set `cookieless: true` for a no-cookie mode. Safe to import in SSR (no-op 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
 
@@ -81,7 +81,9 @@ export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
 
 `@noirtrack/sdk/express` (`guard(noir, { onBlock })`) and `@noirtrack/sdk/fetch` (`createGuard(noir, { onBlock })`) work the same way. You can also pass `{ publicKey, secretKey, onBlock }` instead of a client.
 
-The guards resolve the visitor IP from `CF-Connecting-IP`, `True-Client-IP`, then the left-most `X-Forwarded-For`. Run them **behind a trusted proxy/CDN that sets those headers** — if requests can reach your app directly, a client can spoof `X-Forwarded-For` to forge its IP. Keep your secret key server-side only; it is never needed in the browser or app bundle.
+**Monitor or Block is set in the dashboard.** Adding a guard turns the firewall on, but whether it blocks or just monitors is your Firewall Mode, not the code. New sites start in **Monitor** (detect and log, don't block anyone) until you switch to **Block** in Firewall settings. `onBlock` only changes how a block is delivered once you are in Block mode.
+
+The guards resolve the visitor IP from `CF-Connecting-IP`, `True-Client-IP`, then the left-most `X-Forwarded-For`. Run them **behind a trusted proxy/CDN that sets those headers**. If requests can reach your app directly, a client can spoof `X-Forwarded-For` to forge its IP. Keep your secret key server-side only; it is never needed in the browser or app bundle.
 
 ## Options
 
@@ -93,6 +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 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.js

@@ -111,7 +111,15 @@ export function createIngest(platform) {
     function check(path) {
         // /api/v1/check responds with { block, reason, blocked_page } — not the { action } shape that
         // /decide uses — so normalise it into a Verdict before returning.
-        return postJson(`${endpoint}/api/v1/check`, payload('pageview', path), {}, timeoutMs).then((r) => r ? { action: r.block ? 'block' : 'allow', reason: r.reason ?? null, blocked_page: r.blocked_page ?? null, ttl: 0 } : null);
+        return postJson(`${endpoint}/api/v1/check`, payload('pageview', path), {}, timeoutMs).then((r) => r
+            ? {
+                action: r.block ? 'block' : 'allow',
+                reason: r.reason ?? null,
+                blocked_page: r.blocked_page ?? null,
+                style: r.style ?? null,
+                ttl: 0,
+            }
+            : null);
     }
     return { view, event, identify, revenue, reset, flush, ping, links, shield, check };
 }

package/dist/core/types.d.ts

@@ -9,6 +9,8 @@ export interface Verdict {
     action: 'allow' | 'block' | 'challenge';
     reason: string | null;
     blocked_page: string | null;
+    /** How to present a block (set in Firewall settings): redirect to a page or show an overlay. */
+    style?: 'redirect' | 'overlay' | null;
     ttl: number;
 }
 /** Input to a hard firewall decision (server, secret key). */
@@ -52,7 +54,11 @@ export type RevenueInput = {
     provider?: 'stripe' | 'polar' | 'lemonsqueezy';
     visitorId?: string;
 } | {
-    /** Required for `paid`/`refunded`; omit for `cancelled`/`subscription_ended` (no money moves). */
+    /**
+     * Required for `paid`/`refunded`; omit for `cancelled`/`subscription_ended` (no money moves).
+     * The server rejects a `paid`/`refunded` call with no amount (422) and the SDK fails open
+     * silently — the revenue is dropped, not thrown — so always pass it for those two statuses.
+     */
     amount?: number;
     currency?: string;
     visitorId?: string;

package/dist/index.js

@@ -31,6 +31,9 @@ export function createClient(options) {
         // cancellation — goes through the secret-key payment endpoint.
         if (!('checkoutId' in input))
             return secret.payment(input);
+        // Capture is authenticated by the PUBLIC key (`site.key` middleware). A guard-only client built
+        // without `publicKey` sends `site_key: undefined`, so the server rejects it and this fails open
+        // silently — set `publicKey` on the client if you capture revenue by checkout id.
         const provider = input.provider ?? 'stripe';
         return postOk(`${endpoint}/api/v1/payment/capture`, { site_key: options.publicKey, provider, external_id: input.checkoutId, visitor_id: input.visitorId }, {}, timeoutMs);
     }

package/dist/web.d.ts

@@ -11,9 +11,10 @@ export interface WebClientOptions {
     cookieless?: boolean;
     /** Track on localhost too (off by default, like the hosted script). */
     allowLocalhost?: boolean;
-    /** Soft, client-side firewall on the first view. Off by default. */
-    block?: 'redirect' | 'overlay';
-    /** Where to send blocked visitors when `block` is `redirect`. */
+    /** 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;
     /** Self-hosted base URL. Defaults to the hosted service. */
     endpoint?: 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);
@@ -230,7 +245,10 @@ export function createClient(options) {
                 if (verdict?.action !== 'block')
                     return;
                 const page = verdict.blocked_page ?? options.blockedPage;
-                if (options.block === 'redirect' && page)
+                // Style comes from Firewall settings (redirect or overlay); fall back to redirect when
+                // a page exists, else overlay.
+                const style = verdict.style ?? (page ? 'redirect' : 'overlay');
+                if (style === 'redirect' && page)
                     location.replace(page);
                 else
                     overlay();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@noirtrack/sdk",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "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": {
@@ -41,9 +41,10 @@
             "import": "./dist/form-shield.js"
         }
     },
-    "files": ["dist"],
+    "files": ["dist", "README.md", "CHANGELOG.md"],
     "scripts": {
         "build": "tsc",
+        "prepublishOnly": "tsc",
         "test:live": "node ../docs/live-test.mjs"
     },
     "keywords": ["noirtrack", "firewall", "bot-detection", "waf", "revenue", "goals", "middleware", "nextjs", "express", "edge"],