@noirtrack/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

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

package/README.md

@@ -87,6 +87,10 @@ On Cloudflare Workers, read the key from the `env` argument inside `fetch` (`cre
 
 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                                             |

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

@@ -1,5 +1,6 @@
 import { clientIp } from './core/client-ip.js';
 import { blockMode, isBlockedPagePath } from './core/endpoint.js';
+import { indexNowKeyFile } from './core/indexnow.js';
 import { resolveGuard } from './index.js';
 /**
  *   import { guard } from '@noirtrack/sdk/express';
@@ -13,6 +14,12 @@ import { resolveGuard } from './index.js';
 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;

package/dist/fetch.d.ts

@@ -14,7 +14,7 @@ import { type GuardTarget } from './index.js';
  *   };
  *
  * 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.
+ * 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,6 +1,7 @@
 /** @noirtrack/sdk/fetch — guard for standard Request/Response runtimes (Hono, Cloudflare Workers, Deno). */
 import { clientIp } from './core/client-ip.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
@@ -19,7 +20,7 @@ const STATIC_FILE = /\.(?:css|js|mjs|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|
  *   };
  *
  * 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.
+ * 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).
  */
@@ -27,6 +28,9 @@ 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));

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

@@ -2,6 +2,7 @@
 import { NextResponse } from 'next/server';
 import { clientIp } from './core/client-ip.js';
 import { blockMode, isBlockedPagePath } from './core/endpoint.js';
+import { indexNowKeyFile } from './core/indexnow.js';
 import { resolveGuard } from './index.js';
 /**
  *   // middleware.ts
@@ -17,6 +18,10 @@ import { resolveGuard } from './index.js';
 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;

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

@@ -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'),
             },
         };
     }

package/package.json

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