@noirtrack/sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.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,18 +70,20 @@ 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.
 
@@ -95,10 +97,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/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,14 +1,13 @@
 import { clientIp } from './core/client-ip.js';
-import { isBlockedPagePath } from './core/endpoint.js';
+import { blockMode, isBlockedPagePath } from './core/endpoint.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) {
@@ -38,7 +37,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.
  *
  * Fails open: a NoirTrack error/timeout returns null (let the request through).
  */

package/dist/fetch.js

@@ -1,17 +1,25 @@
 /** @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 { 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.
  *
  * Fails open: a NoirTrack error/timeout returns null (let the request through).
  */
@@ -19,6 +27,8 @@ export function createGuard(target, blockOptions) {
     const { client, block } = resolveGuard(target, blockOptions);
     return async function guard(request) {
         const url = new URL(request.url);
+        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 +47,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/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,18 +1,17 @@
 /** @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 { 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) {
@@ -35,8 +34,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/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
@@ -250,7 +250,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.5.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": {