@noirtrack/sdk 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.6.0
+
+### Added
+
+- **IndexNow key file.** With Indexing on (Site → Settings → Indexing), the `next`, `express` and `fetch` guards answer `/{key}.txt` with your site's IndexNow key, so Bing, Yandex and other search engines accept the new pages NoirTrack sends them. Nothing to configure. `createClient()` also gains `indexNowKey()`.
+- **UTM content and term (web client).** `utm_content` and `utm_term` are sent with page views and events, so the dashboard's Campaigns menu breaks traffic down by them too.
+
+## 0.5.0
+
+### Changed
+
+- **The setup is just your key.** Protection is controlled in the dashboard (Firewall settings), so the code no longer needs options for it:
+  - **Breaking (web client):** the firewall now runs by default. `block` defaults to `true`, and whether it only monitors or blocks is set in Firewall settings as before. To skip it, pass `block: false`.
+  - **Server guards (`next`, `express`, `fetch`):** without `onBlock`, a blocked visitor is redirected to the Blocked page URL from Firewall settings when one is set, otherwise gets an HTTP 403. Before, the guard always returned 403 unless you passed `onBlock: 'redirect'`. Passing `onBlock` still overrides it.
+  - **Fetch guard (`fetch`):** images, styles, scripts, fonts and media now pass straight through. A Cloudflare Worker in front of a site runs for every file a page loads, and each one used to count as a page view and a firewall check.
+
 ## 0.4.0
 
 ### Added

package/README.md

@@ -19,14 +19,14 @@ Two keys, both on your site's Install page. The public key (`pk_live_...`) is sa
 ```ts
 import { createClient } from '@noirtrack/sdk/web';
 
-const noir = createClient({ publicKey: process.env.NEXT_PUBLIC_NOIRTRACK_KEY!, autoPageviews: true });
+const noir = createClient({ publicKey: process.env.NEXT_PUBLIC_NOIRTRACK_KEY! });
 
 noir.event('signup', { plan: 'pro' });
 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 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)`.
+Pageviews, route changes and the firewall are automatic. Whether the firewall only monitors or blocks, and how a block looks (redirect or overlay), are set in your Firewall settings, with no code change. Events are batched and sent with `sendBeacon`. See [Options](#options) for `cookieless` and the rest. Safe to import in SSR (it does nothing without a window). Also: `view(path?)`, `reset()`, `flush()`, `links.decorate(url)`.
 
 ## React Native
 
@@ -70,21 +70,27 @@ if (verdict?.action === 'block') {
 }
 ```
 
-Or use an adapter and pass the client:
+Or use an adapter. It only needs your secret key:
 
 ```ts
 // Next.js: middleware.ts
 import { guard } from '@noirtrack/sdk/next';
-export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+export const middleware = guard({ secretKey: process.env.NOIRTRACK_SECRET_KEY! });
 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.
+`@noirtrack/sdk/express` (`app.use(guard({ secretKey }))`) and `@noirtrack/sdk/fetch` (`createGuard({ secretKey })`) work the same way. You can also pass a client you already created: `guard(noir)`.
 
-**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.
+On Cloudflare Workers, read the key from the `env` argument inside `fetch` (`createGuard({ secretKey: env.NOIRTRACK_SECRET_KEY })`), since `process.env` is only there with Node.js compatibility on. The fetch guard lets images, CSS, JavaScript, fonts and videos through without a check. Step-by-step setup: [Cloudflare Workers](https://noirtrack.com/docs/cloudflare-workers).
+
+**Everything else is set in the dashboard.** Adding a guard turns the firewall on. Whether it blocks or just monitors is your Firewall Mode, and a blocked visitor is sent to the Blocked page URL from Firewall settings (or gets a 403 when none is set). New sites start in **Monitor** (detect and log, don't block anyone) until you switch to **Block**. To handle a block differently in code, pass `onBlock` (see [Options](#options)).
 
 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.
 
+### IndexNow key file
+
+With Indexing on (Site → Settings → Indexing), the `next`, `express` and `fetch` guards also answer `/{key}.txt` with your site's IndexNow key, so Bing, Yandex and other search engines accept the new pages NoirTrack sends them. There is nothing to configure.
+
 ## Options
 
 | Option                                    | Default                | Where    | Description                                             |
@@ -95,10 +101,10 @@ 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). |
+| `block`                                   | `true`                 | web      | Run the firewall (Monitor/Block set in dashboard). `false` skips it. |
 | `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.                                         |
+| `onBlock` / `blockStatus` / `blockedPage` | from dashboard / `403` / none | adapters | Block handling. Default: redirect to the dashboard's Blocked page URL, else 403. |
 
 Full reference: the [Server SDK page](https://noirtrack.com/docs/server-sdk) in the NoirTrack docs.
 

package/dist/core/endpoint.d.ts

@@ -14,4 +14,9 @@ export declare function resolveEndpoint(explicit?: string): string;
  * enforcement on the blocked page so a still-blocked visitor isn't redirected to it forever.
  * `page` may be a path ("/blocked") or an absolute URL ("https://site.com/blocked").
  */
+/**
+ * What a guard does with a block verdict when the code doesn't say: redirect to the Blocked page URL set in Firewall
+ * settings when there is one, otherwise return an HTTP error. So a block is set up in the dashboard, not in code.
+ */
+export declare function blockMode(onBlock: 'redirect' | 'rewrite' | 'block' | undefined, page: string | null | undefined): 'redirect' | 'rewrite' | 'block';
 export declare function isBlockedPagePath(path: string, page: string | null | undefined): boolean;

package/dist/core/endpoint.js

@@ -18,6 +18,13 @@ export function resolveEndpoint(explicit) {
  * enforcement on the blocked page so a still-blocked visitor isn't redirected to it forever.
  * `page` may be a path ("/blocked") or an absolute URL ("https://site.com/blocked").
  */
+/**
+ * What a guard does with a block verdict when the code doesn't say: redirect to the Blocked page URL set in Firewall
+ * settings when there is one, otherwise return an HTTP error. So a block is set up in the dashboard, not in code.
+ */
+export function blockMode(onBlock, page) {
+    return onBlock ?? (page ? 'redirect' : 'block');
+}
 export function isBlockedPagePath(path, page) {
     if (!page)
         return false;

package/dist/core/http.d.ts

@@ -6,5 +6,7 @@
 export declare function postJson<T>(url: string, body: unknown, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;
 /** POST JSON and return whether the server accepted it (2xx). */
 export declare function postOk(url: string, body: unknown, headers: Record<string, string>, timeoutMs: number): Promise<boolean>;
+/** GET JSON and return the parsed body, or null on non-2xx / timeout / error. */
+export declare function getJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;
 /** Bearer header for the secret-key endpoints. */
 export declare function bearer(secretKey: string): Record<string, string>;

package/dist/core/http.js

@@ -37,6 +37,21 @@ async function rawPost(url, body, headers, timeoutMs) {
         clearTimeout(timer);
     }
 }
+/** GET JSON and return the parsed body, or null on non-2xx / timeout / error. */
+export async function getJson(url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { headers, signal: controller.signal });
+        return res.ok ? (await res.json()) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Bearer header for the secret-key endpoints. */
 export function bearer(secretKey) {
     return { Authorization: `Bearer ${secretKey}` };

package/dist/core/indexnow.d.ts

@@ -0,0 +1,2 @@
+/** The body for a key-file request, or null when the path is not this site's key file. */
+export declare function indexNowKeyFile(pathname: string, lookup: () => Promise<string | null>): Promise<string | null>;

package/dist/core/indexnow.js

@@ -0,0 +1,14 @@
+/**
+ * The IndexNow key file. Search engines confirm a site sent them URLs by fetching https://{host}/{key}.txt, so the
+ * server guards answer that one path with the site's key from NoirTrack (Settings → Indexing). Nothing is served while
+ * Indexing is off, and any other .txt file passes through untouched.
+ */
+const KEY_FILE = /^\/([a-f0-9]{32})\.txt$/;
+/** The body for a key-file request, or null when the path is not this site's key file. */
+export async function indexNowKeyFile(pathname, lookup) {
+    const match = KEY_FILE.exec(pathname);
+    if (!match)
+        return null;
+    const key = await lookup();
+    return key !== null && key === match[1] ? key : null;
+}

package/dist/core/ingest.d.ts

@@ -12,6 +12,8 @@ export interface IngestContext {
         source: string | null;
         medium: string | null;
         campaign: string | null;
+        content: string | null;
+        term: string | null;
     };
 }
 /** What each platform plugs into the shared ingest core. */

package/dist/core/secret.d.ts

@@ -26,5 +26,7 @@ export interface SecretApi {
         visitorId: string;
     }): Promise<boolean>;
     shield(input: ShieldInput): Promise<ShieldResult>;
+    /** The site's IndexNow key, or null while Indexing is off. Cached for an hour. */
+    indexNowKey(): Promise<string | null>;
 }
 export declare function createSecretApi(config: SecretConfig): SecretApi;

package/dist/core/secret.js

@@ -2,7 +2,7 @@
  * The secret-key API: trusted server-to-server methods. Authenticated with the secret key
  * (Bearer). Every method fails open. Used by the server client and the firewall adapters.
  */
-import { bearer, postJson, postOk } from './http.js';
+import { bearer, getJson, postJson, postOk } from './http.js';
 export function createSecretApi(config) {
     const { secretKey, endpoint } = config;
     const timeoutMs = config.timeoutMs;
@@ -60,5 +60,16 @@ export function createSecretApi(config) {
             return { ok: true, reason: null }; // fail open
         return { ok: data.ok !== false, reason: data.reason ?? null };
     }
-    return { decide, goal, payment, identify, shield };
+    // Only asked for when a search engine fetches /{key}.txt, and the key almost never changes, so one answer an hour is
+    // plenty. A failed lookup is cached for a minute, so an outage can't turn every key-file request into a network call.
+    let keyCache = null;
+    async function indexNowKey() {
+        const now = Date.now();
+        if (keyCache && keyCache.expires > now)
+            return keyCache.key;
+        const data = await getJson(`${endpoint}/api/v1/indexnow-key`, head, Math.max(timeoutMs, 1500));
+        keyCache = { key: data?.key ?? null, expires: now + (data ? 3_600_000 : 60_000) };
+        return keyCache.key;
+    }
+    return { decide, goal, payment, identify, shield, indexNowKey };
 }

package/dist/core/types.d.ts

@@ -105,7 +105,10 @@ export interface ShieldResult {
 }
 /** Block-handling shared by the firewall adapters. */
 export interface BlockOptions {
-    /** What to do on a block verdict. Default 'block' (return an HTTP error). */
+    /**
+     * What to do on a block verdict. By default it follows Firewall settings: a redirect to the Blocked page URL when
+     * one is set there, otherwise 'block' (an HTTP error).
+     */
     onBlock?: 'redirect' | 'rewrite' | 'block';
     /** Page to redirect/rewrite to (falls back to the verdict's blocked_page). */
     blockedPage?: string;

package/dist/express.d.ts

@@ -3,13 +3,12 @@ import type { RequestHandler } from 'express';
 import type { BlockOptions } from './core/types.js';
 import { type GuardTarget } from './index.js';
 /**
- *   import { createClient } from '@noirtrack/sdk';
  *   import { guard } from '@noirtrack/sdk/express';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
- *   app.use(guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' }));
+ *   app.use(guard({ secretKey: process.env.NOIRTRACK_SECRET_KEY! }));
  *
- * Or pass options: `guard({ publicKey, secretKey, onBlock: 'block' })`.
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. You can also pass a client:
+ * `guard(noir, { onBlock: 'block' })`.
  * Fails open: a NoirTrack error/timeout calls next() and never breaks your app.
  */
 export declare function guard(target: GuardTarget, blockOptions?: BlockOptions): RequestHandler;

package/dist/express.js

@@ -1,19 +1,25 @@
 import { clientIp } from './core/client-ip.js';
-import { isBlockedPagePath } from './core/endpoint.js';
+import { blockMode, isBlockedPagePath } from './core/endpoint.js';
+import { indexNowKeyFile } from './core/indexnow.js';
 import { resolveGuard } from './index.js';
 /**
- *   import { createClient } from '@noirtrack/sdk';
  *   import { guard } from '@noirtrack/sdk/express';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
- *   app.use(guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' }));
+ *   app.use(guard({ secretKey: process.env.NOIRTRACK_SECRET_KEY! }));
  *
- * Or pass options: `guard({ publicKey, secretKey, onBlock: 'block' })`.
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. You can also pass a client:
+ * `guard(noir, { onBlock: 'block' })`.
  * Fails open: a NoirTrack error/timeout calls next() and never breaks your app.
  */
 export function guard(target, blockOptions) {
     const { client, block } = resolveGuard(target, blockOptions);
     return async function (request, response, next) {
+        // With Indexing on, search engines read the IndexNow key here (docs: Indexing).
+        const keyFile = await indexNowKeyFile(request.path, () => client.indexNowKey());
+        if (keyFile) {
+            response.type('text/plain').send(keyFile);
+            return;
+        }
         const ip = clientIp((name) => {
             const value = request.headers[name];
             return Array.isArray(value) ? value[0] : value;
@@ -38,7 +44,7 @@ export function guard(target, blockOptions) {
             return;
         }
         const page = verdict.blocked_page ?? block.blockedPage;
-        if ((block.onBlock ?? 'block') === 'redirect' && page) {
+        if (blockMode(block.onBlock, page) === 'redirect' && page) {
             // Don't redirect the blocked page to itself — that loops forever.
             if (isBlockedPagePath(path, page)) {
                 next();

package/dist/fetch.d.ts

@@ -4,12 +4,17 @@ import { type GuardTarget } from './index.js';
  * Returns a guard that, given a standard Request, resolves to a blocking Response, or null when
  * the request should continue.
  *
- *   import { createClient } from '@noirtrack/sdk';
  *   import { createGuard } from '@noirtrack/sdk/fetch';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: env.NOIRTRACK_SECRET });
- *   const guard = createGuard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
- *   export default { async fetch(req) { return (await guard(req)) ?? fetch(req); } };
+ *   export default {
+ *     async fetch(request, env) {
+ *       const guard = createGuard({ secretKey: env.NOIRTRACK_SECRET_KEY });
+ *       return (await guard(request)) ?? fetch(request);
+ *     },
+ *   };
+ *
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. Images, styles, scripts, fonts
+ * and media pass straight through without a check. With Indexing on, `/{key}.txt` answers with your IndexNow key.
  *
  * Fails open: a NoirTrack error/timeout returns null (let the request through).
  */

package/dist/fetch.js

@@ -1,17 +1,26 @@
 /** @noirtrack/sdk/fetch — guard for standard Request/Response runtimes (Hono, Cloudflare Workers, Deno). */
 import { clientIp } from './core/client-ip.js';
-import { isBlockedPagePath } from './core/endpoint.js';
+import { blockMode, isBlockedPagePath } from './core/endpoint.js';
+import { indexNowKeyFile } from './core/indexnow.js';
 import { resolveGuard } from './index.js';
+// A Worker in front of a site runs for every file a page loads. Checking those would record each image and stylesheet as
+// a page view and spend a firewall check on it, so they skip the guard, like the Next.js matcher skips Next's own files. // why
+const STATIC_FILE = /\.(?:css|js|mjs|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|eot|mp4|webm|mp3)$/i;
 /**
  * Returns a guard that, given a standard Request, resolves to a blocking Response, or null when
  * the request should continue.
  *
- *   import { createClient } from '@noirtrack/sdk';
  *   import { createGuard } from '@noirtrack/sdk/fetch';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: env.NOIRTRACK_SECRET });
- *   const guard = createGuard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
- *   export default { async fetch(req) { return (await guard(req)) ?? fetch(req); } };
+ *   export default {
+ *     async fetch(request, env) {
+ *       const guard = createGuard({ secretKey: env.NOIRTRACK_SECRET_KEY });
+ *       return (await guard(request)) ?? fetch(request);
+ *     },
+ *   };
+ *
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. Images, styles, scripts, fonts
+ * and media pass straight through without a check. With Indexing on, `/{key}.txt` answers with your IndexNow key.
  *
  * Fails open: a NoirTrack error/timeout returns null (let the request through).
  */
@@ -19,6 +28,11 @@ export function createGuard(target, blockOptions) {
     const { client, block } = resolveGuard(target, blockOptions);
     return async function guard(request) {
         const url = new URL(request.url);
+        const keyFile = await indexNowKeyFile(url.pathname, () => client.indexNowKey());
+        if (keyFile)
+            return new Response(keyFile, { headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
+        if (STATIC_FILE.test(url.pathname))
+            return null;
         const ip = clientIp((name) => request.headers.get(name));
         const ua = request.headers.get('user-agent') ?? '';
         const path = url.pathname;
@@ -37,7 +51,7 @@ export function createGuard(target, blockOptions) {
         if (verdict?.action !== 'block')
             return null;
         const page = verdict.blocked_page ?? block.blockedPage;
-        if ((block.onBlock ?? 'block') === 'redirect' && page) {
+        if (blockMode(block.onBlock, page) === 'redirect' && page) {
             // Already on the blocked page → let it through, don't loop.
             if (isBlockedPagePath(path, page))
                 return null;

package/dist/index.d.ts

@@ -40,6 +40,8 @@ export interface ServerClient {
     goal(name: string, options?: Omit<GoalInput, 'name'>): Promise<boolean>;
     /** Check a form submission for spam and bots. */
     shield(input: ShieldInput): Promise<ShieldResult>;
+    /** The site's IndexNow key, or null while Indexing is off. The guards use it to serve `/{key}.txt`. */
+    indexNowKey(): Promise<string | null>;
 }
 export declare function createClient(options: ServerClientOptions): ServerClient;
 /** What a firewall adapter accepts: an existing client, or options to build one. */

package/dist/index.js

@@ -45,6 +45,7 @@ export function createClient(options) {
         decide: secret.decide,
         goal: secret.goal,
         shield: secret.shield,
+        indexNowKey: secret.indexNowKey,
     };
 }
 /**

package/dist/next.d.ts

@@ -3,14 +3,13 @@ import { NextRequest, NextResponse } from 'next/server';
 import { type GuardTarget } from './index.js';
 /**
  *   // middleware.ts
- *   import { createClient } from '@noirtrack/sdk';
  *   import { guard } from '@noirtrack/sdk/next';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
- *   export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export const middleware = guard({ secretKey: process.env.NOIRTRACK_SECRET_KEY! });
  *   export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
  *
- * You can also pass options directly: `guard({ publicKey, secretKey, onBlock: 'redirect' })`.
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. You can also pass a client:
+ * `guard(noir, { onBlock: 'rewrite' })`.
  * Fails open: a NoirTrack error/timeout never blocks or breaks your site.
  */
 export declare function guard(target: GuardTarget, blockOptions?: import('./core/types.js').BlockOptions): (request: NextRequest) => Promise<NextResponse>;

package/dist/next.js

@@ -1,23 +1,27 @@
 /** @noirtrack/sdk/next — firewall middleware for Next.js (Edge runtime). */
 import { NextResponse } from 'next/server';
 import { clientIp } from './core/client-ip.js';
-import { isBlockedPagePath } from './core/endpoint.js';
+import { blockMode, isBlockedPagePath } from './core/endpoint.js';
+import { indexNowKeyFile } from './core/indexnow.js';
 import { resolveGuard } from './index.js';
 /**
  *   // middleware.ts
- *   import { createClient } from '@noirtrack/sdk';
  *   import { guard } from '@noirtrack/sdk/next';
  *
- *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
- *   export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export const middleware = guard({ secretKey: process.env.NOIRTRACK_SECRET_KEY! });
  *   export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
  *
- * You can also pass options directly: `guard({ publicKey, secretKey, onBlock: 'redirect' })`.
+ * Monitor or Block, and where a blocked visitor goes, come from Firewall settings. You can also pass a client:
+ * `guard(noir, { onBlock: 'rewrite' })`.
  * Fails open: a NoirTrack error/timeout never blocks or breaks your site.
  */
 export function guard(target, blockOptions) {
     const { client, block } = resolveGuard(target, blockOptions);
     return async function middleware(request) {
+        // With Indexing on, search engines read the IndexNow key here (docs: Indexing).
+        const keyFile = await indexNowKeyFile(request.nextUrl.pathname, () => client.indexNowKey());
+        if (keyFile)
+            return new NextResponse(keyFile, { headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
         const ip = clientIp((name) => request.headers.get(name));
         const ua = request.headers.get('user-agent') ?? '';
         const path = request.nextUrl.pathname;
@@ -35,8 +39,8 @@ export function guard(target, blockOptions) {
         });
         if (verdict?.action !== 'block')
             return NextResponse.next();
-        const mode = block.onBlock ?? 'block';
         const page = verdict.blocked_page ?? block.blockedPage;
+        const mode = blockMode(block.onBlock, page);
         // The blocked page must stay reachable, or a still-blocked visitor loops forever
         // when that page also runs this middleware.
         if ((mode === 'redirect' || mode === 'rewrite') && page) {

package/dist/react-native.js

@@ -42,7 +42,7 @@ export async function createClient(options) {
             path: pathOverride ?? '/',
             referrer: null,
             screen: null,
-            utm: { source: null, medium: null, campaign: null },
+            utm: { source: null, medium: null, campaign: null, content: null, term: null },
         };
     }
     const platform = {

package/dist/web.d.ts

@@ -11,8 +11,9 @@ export interface WebClientOptions {
     cookieless?: boolean;
     /** Track on localhost too (off by default, like the hosted script). */
     allowLocalhost?: boolean;
-    /** 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. */
+    /** Run the firewall on the first view. On by default: whether it only monitors or blocks, and how a block
+     *  looks (redirect or overlay), are set per site in Firewall settings, so nothing here needs changing. Set
+     *  false to skip the check entirely. */
     block?: boolean;
     /** Optional redirect target if none is set in Firewall settings. */
     blockedPage?: string;

package/dist/web.js

@@ -2,7 +2,7 @@
  * @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 });
+ *   const noir = createClient({ publicKey: 'pk_live_...' });
  *   noir.event('signup', { plan: 'pro' });
  *
  * Uses the public key only (browser code can't hold a secret). Safe to import in SSR: when there
@@ -193,6 +193,8 @@ export function createClient(options) {
                 source: params.get('utm_source'),
                 medium: params.get('utm_medium'),
                 campaign: params.get('utm_campaign'),
+                content: params.get('utm_content'),
+                term: params.get('utm_term'),
             },
         };
     }
@@ -250,7 +252,7 @@ export function createClient(options) {
         // 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;
+        const wantsBlock = options.block !== false;
         if (wantsBlock) {
             void ingest.check().then((verdict) => {
                 if (verdict?.action !== 'block')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@noirtrack/sdk",
-    "version": "0.4.0",
+    "version": "0.6.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": {