@noirtrack/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoirTrack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @noirtrack/sdk
+
+One NoirTrack SDK for the browser, React Native, and your server. You set your keys once with `createClient`, then call methods. The client routes each call: analytics use the public key, trusted operations (firewall, server goals, amount-based revenue) use the secret key.
+
+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)
+
+## Install
+
+```bash
+npm i @noirtrack/sdk
+```
+
+Two keys, both on your site's Install page. The public key (`pk_live_...`) is safe in browser and app code. The secret key (`sk_live_...`) is server-side only.
+
+## Browser
+
+```ts
+import { createClient } from '@noirtrack/sdk/web';
+
+const noir = createClient({ publicKey: process.env.NEXT_PUBLIC_NOIRTRACK_KEY!, autoPageviews: true });
+
+noir.event('signup', { plan: 'pro' });
+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)`.
+
+## React Native
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { createClient } from '@noirtrack/sdk/react-native';
+
+const noir = await createClient({ publicKey: process.env.EXPO_PUBLIC_NOIRTRACK_KEY!, storage: AsyncStorage });
+noir.view('Home');
+noir.event('signup', { plan: 'pro' });
+```
+
+Same methods as the browser. `createClient` is async because storage is async. Screen views are manual.
+
+## Server
+
+```ts
+import { createClient } from '@noirtrack/sdk';
+
+const noir = createClient({
+    publicKey: process.env.NOIRTRACK_PUBLIC_KEY!,
+    secretKey: process.env.NOIRTRACK_SECRET_KEY!,
+});
+
+await noir.event('signup', { plan: 'pro' }, { visitorId });
+await noir.goal('subscription_activated', { visitorId });
+await noir.revenue({ amount: 49.0, currency: 'USD', visitorId }); // explicit amount (secret)
+await noir.revenue({ checkoutId: 'cs_test_123' }); // capture by id (server verifies)
+await noir.identify({ visitorId, name: 'Jane', attributes: { plan: 'pro' } });
+await noir.shield({ email, honeypot: body._noir_hp, ip, ua });
+```
+
+`visitorId` is the `noir_vid` cookie the tracker sets. Read it on your server. Every method fails open.
+
+### Block traffic
+
+```ts
+const verdict = await noir.decide({ ip, ua, path });
+if (verdict?.action === 'block') {
+    /* deny */
+}
+```
+
+Or use an adapter and pass the client:
+
+```ts
+// Next.js: middleware.ts
+import { guard } from '@noirtrack/sdk/next';
+export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+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.
+
+## Options
+
+| Option                                    | Default                | Where    | Description                                             |
+| ----------------------------------------- | ---------------------- | -------- | ------------------------------------------------------- |
+| `publicKey`                               | required               | all      | Public key (`pk_live_...`).                             |
+| `secretKey`                               | required               | server   | Secret key (`sk_live_...`). Not accepted in browser/RN. |
+| `endpoint`                                | hosted                 | all      | Base URL. Self-hosted only.                             |
+| `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.                      |
+| `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.                                         |
+
+Full reference: the [Server SDK page](https://noirtrack.com/docs/server-sdk) in the NoirTrack docs.
+
+## License
+
+MIT

package/dist/core/client-ip.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve the real end-user IP from a request's headers, for the firewall + geo. Prefers
+ * Cloudflare's authoritative `CF-Connecting-IP` (it overwrites any client-supplied value), then
+ * `True-Client-IP` (CF Enterprise / Akamai), then the left-most `X-Forwarded-For` entry, then a
+ * transport fallback (e.g. socket.remoteAddress). Header names are matched case-insensitively by
+ * the caller's getter.
+ *
+ * Pass a getter that reads one header by (lowercase) name; it differs per runtime (Node's
+ * `req.headers[name]` vs the Fetch `Headers.get(name)`), so the seam stays tiny and shared.
+ */
+export declare function clientIp(get: (name: string) => string | null | undefined, fallback?: string | null): string;

package/dist/core/client-ip.js

@@ -0,0 +1,14 @@
+/**
+ * Resolve the real end-user IP from a request's headers, for the firewall + geo. Prefers
+ * Cloudflare's authoritative `CF-Connecting-IP` (it overwrites any client-supplied value), then
+ * `True-Client-IP` (CF Enterprise / Akamai), then the left-most `X-Forwarded-For` entry, then a
+ * transport fallback (e.g. socket.remoteAddress). Header names are matched case-insensitively by
+ * the caller's getter.
+ *
+ * Pass a getter that reads one header by (lowercase) name; it differs per runtime (Node's
+ * `req.headers[name]` vs the Fetch `Headers.get(name)`), so the seam stays tiny and shared.
+ */
+export function clientIp(get, fallback) {
+    const first = (value) => (value ?? '').split(',')[0]?.trim() ?? '';
+    return first(get('cf-connecting-ip')) || first(get('true-client-ip')) || first(get('x-forwarded-for')) || (fallback ?? '').trim() || '';
+}

package/dist/core/endpoint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Endpoint resolution and the blocked-page helper, shared by every entry (server, web, RN).
+ */
+/**
+ * Default NoirTrack API base. Resolution order: the `endpoint` option, then the
+ * `NOIRTRACK_ENDPOINT` env var (server only), then this constant. Self-hosted / white-label
+ * installs set the env var or pass `endpoint`; users on the hosted service set nothing.
+ */
+export declare const DEFAULT_ENDPOINT = "https://noirtrack.com";
+/** Resolve the base URL: explicit option, else NOIRTRACK_ENDPOINT env, else DEFAULT_ENDPOINT. */
+export declare function resolveEndpoint(explicit?: string): string;
+/**
+ * True when the current request path is the blocked page itself. Adapters use this to skip
+ * 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").
+ */
+export declare function isBlockedPagePath(path: string, page: string | null | undefined): boolean;

package/dist/core/endpoint.js

@@ -0,0 +1,32 @@
+/**
+ * Endpoint resolution and the blocked-page helper, shared by every entry (server, web, RN).
+ */
+/**
+ * Default NoirTrack API base. Resolution order: the `endpoint` option, then the
+ * `NOIRTRACK_ENDPOINT` env var (server only), then this constant. Self-hosted / white-label
+ * installs set the env var or pass `endpoint`; users on the hosted service set nothing.
+ */
+export const DEFAULT_ENDPOINT = 'https://noirtrack.com';
+/** Resolve the base URL: explicit option, else NOIRTRACK_ENDPOINT env, else DEFAULT_ENDPOINT. */
+export function resolveEndpoint(explicit) {
+    const g = globalThis;
+    const fromEnv = g.process?.env?.NOIRTRACK_ENDPOINT;
+    return (explicit ?? fromEnv ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
+}
+/**
+ * True when the current request path is the blocked page itself. Adapters use this to skip
+ * 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").
+ */
+export function isBlockedPagePath(path, page) {
+    if (!page)
+        return false;
+    const trim = (p) => p.replace(/\/+$/, '') || '/';
+    try {
+        const target = new URL(page, 'http://noirtrack.invalid').pathname;
+        return trim(path) === trim(target);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/http.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tiny fetch helpers with a timeout, used by every client. All callers fail open: a timeout or
+ * network error resolves to the safe default instead of throwing.
+ */
+/** POST JSON and return the parsed body, or null on non-2xx / timeout / error. */
+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>;
+/** Bearer header for the secret-key endpoints. */
+export declare function bearer(secretKey: string): Record<string, string>;

package/dist/core/http.js

@@ -0,0 +1,43 @@
+/**
+ * Tiny fetch helpers with a timeout, used by every client. All callers fail open: a timeout or
+ * network error resolves to the safe default instead of throwing.
+ */
+/** POST JSON and return the parsed body, or null on non-2xx / timeout / error. */
+export async function postJson(url, body, headers, timeoutMs) {
+    const res = await rawPost(url, body, headers, timeoutMs);
+    if (!res || !res.ok)
+        return null;
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/** POST JSON and return whether the server accepted it (2xx). */
+export async function postOk(url, body, headers, timeoutMs) {
+    const res = await rawPost(url, body, headers, timeoutMs);
+    return res?.ok ?? false;
+}
+async function rawPost(url, body, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Bearer header for the secret-key endpoints. */
+export function bearer(secretKey) {
+    return { Authorization: `Bearer ${secretKey}` };
+}

package/dist/core/ids.d.ts

@@ -0,0 +1,2 @@
+/** Visitor/session id generation, shared by the browser and React Native clients. */
+export declare function uuid(): string;

package/dist/core/ids.js

@@ -0,0 +1,10 @@
+/** Visitor/session id generation, shared by the browser and React Native clients. */
+export function uuid() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
+        const r = (Math.random() * 16) | 0;
+        return (ch === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}

package/dist/core/ingest.d.ts

@@ -0,0 +1,78 @@
+import type { Props, RevenueInput, ShieldInput, ShieldResult, Verdict } from './types.js';
+/** Request context for an event payload. The platform builds it (from `location`, or defaults). */
+export interface IngestContext {
+    host: string | null;
+    /** Path plus query string. */
+    path: string;
+    referrer: string | null;
+    screen: string | null;
+    utm: {
+        source: string | null;
+        medium: string | null;
+        campaign: string | null;
+    };
+}
+/** What each platform plugs into the shared ingest core. */
+export interface IngestPlatform {
+    publicKey: string;
+    endpoint: string;
+    timeoutMs: number;
+    /** Queue events and flush in batches (browser, RN). When false, deliver immediately (server). */
+    batch: boolean;
+    flushIntervalMs: number;
+    maxQueueSize: number;
+    visitorId(): string | null;
+    sessionId(): string | null;
+    /** Drop visitor + session ids so the next event starts a fresh identity. */
+    resetIds(): void;
+    context(pathOverride?: string): IngestContext;
+    /** True when tracking should be silently skipped (bot, localhost, iframe, disabled). */
+    disabled(): boolean;
+    /** Deliver one JSON payload to `url` (sendBeacon in the browser, fetch elsewhere). */
+    deliver(url: string, body: object): void;
+    /** Optional: wire periodic + final flush (browser: interval + pagehide). */
+    scheduleFlush?(flush: () => void): void;
+}
+export interface Ingest {
+    /** Record a pageview. Pass a path to override the current one (SPAs). */
+    view(path?: string): void;
+    /** Record a custom event. */
+    event(name: string, props?: Props): void;
+    /**
+     * Attach customer info to the current visitor. Pass one object — `userId`, `name`, `email`, and any
+     * custom fields — matching the snippet's `noir('identify', {…})`. The legacy `(userId, traits)` form
+     * still works.
+     */
+    identify(user: string | (Props & {
+        userId?: string;
+        name?: string;
+        email?: string;
+    }), traits?: Props): void;
+    /** Capture revenue by checkout id (the public, no-amount path). */
+    revenue(input: Extract<RevenueInput, {
+        checkoutId: string;
+    }>): void;
+    /** Forget the current visitor (e.g. on logout); the next event starts fresh. */
+    reset(): void;
+    /** Send everything queued right now. */
+    flush(): void;
+    /**
+     * Presence heartbeat: mark the current visitor as live right now. The realtime count is a
+     * 5-minute window, so a browser client pings on a timer (while visible) to stay in it. This
+     * hits a presence-only endpoint — no event row, no event-quota cost.
+     */
+    ping(): void;
+    /** Cross-domain link helpers. */
+    links: {
+        params(): {
+            noir_vid: string;
+            noir_sid: string;
+        };
+        decorate(url: string): string;
+    };
+    /** Spam/bot check for a form, with the public key. */
+    shield(input: ShieldInput): Promise<ShieldResult>;
+    /** Soft firewall check for the current request; returns the verdict (or null on error). */
+    check(path?: string): Promise<Verdict | null>;
+}
+export declare function createIngest(platform: IngestPlatform): Ingest;

package/dist/core/ingest.js

@@ -0,0 +1,117 @@
+/**
+ * The public-key ingest API: analytics that is safe to run anywhere (browser, React Native, or
+ * server). Shared by every entry. The platform seam supplies what differs per environment:
+ * request context, visitor/session storage, and how a payload is delivered.
+ */
+import { postJson } from './http.js';
+export function createIngest(platform) {
+    const { endpoint, publicKey, timeoutMs } = platform;
+    const eventUrl = `${endpoint}/api/v1/event`;
+    const queue = [];
+    let timer = null;
+    function payload(event, pathOverride, meta) {
+        const ctx = platform.context(pathOverride);
+        const base = {
+            site_key: publicKey,
+            host: ctx.host,
+            path: ctx.path,
+            referrer: ctx.referrer,
+            screen: ctx.screen,
+            visitor_id: platform.visitorId(),
+            session_id: platform.sessionId(),
+            utm: ctx.utm,
+            event,
+        };
+        if (meta)
+            base.meta = meta;
+        return base;
+    }
+    function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        const batch = queue.splice(0);
+        for (const body of batch)
+            platform.deliver(eventUrl, body);
+    }
+    function enqueue(body) {
+        if (platform.disabled())
+            return;
+        if (!platform.batch) {
+            platform.deliver(eventUrl, body);
+            return;
+        }
+        queue.push(body);
+        if (queue.length >= platform.maxQueueSize) {
+            flush();
+        }
+        else if (!timer) {
+            timer = setTimeout(flush, platform.flushIntervalMs);
+        }
+    }
+    if (platform.batch)
+        platform.scheduleFlush?.(flush);
+    function view(path) {
+        enqueue(payload('pageview', path));
+    }
+    function event(name, props) {
+        enqueue(payload(name, undefined, props));
+    }
+    function identify(user, traits = {}) {
+        // One object — { userId, name, email, …custom } — matches the snippet. Legacy (userId, traits)
+        // is normalised to the same shape so both forms send an identical `userId` field.
+        const meta = typeof user === 'string' ? { ...traits, userId: user } : { ...user };
+        enqueue(payload('$identify', undefined, meta));
+    }
+    function revenue(input) {
+        if (platform.disabled())
+            return;
+        const provider = input.provider ?? 'stripe';
+        platform.deliver(`${endpoint}/api/v1/payment/capture`, {
+            site_key: publicKey,
+            provider,
+            external_id: input.checkoutId,
+            visitor_id: input.visitorId ?? platform.visitorId(),
+        });
+    }
+    function reset() {
+        platform.resetIds();
+    }
+    function ping() {
+        if (platform.disabled())
+            return;
+        // Presence-only: deliver immediately (never queued), so "visitors now" updates without a flush.
+        platform.deliver(`${endpoint}/api/v1/ping`, { site_key: publicKey, visitor_id: platform.visitorId() });
+    }
+    const links = {
+        params() {
+            return { noir_vid: platform.visitorId() ?? '', noir_sid: platform.sessionId() ?? '' };
+        },
+        decorate(url) {
+            const { noir_vid, noir_sid } = links.params();
+            if (!noir_vid && !noir_sid)
+                return url;
+            try {
+                const u = new URL(url);
+                if (noir_vid)
+                    u.searchParams.set('noir_vid', noir_vid);
+                if (noir_sid)
+                    u.searchParams.set('noir_sid', noir_sid);
+                return u.toString();
+            }
+            catch {
+                return url;
+            }
+        },
+    };
+    function shield(input) {
+        return postJson(`${endpoint}/api/v1/form-shield`, { site_key: publicKey, ...input }, {}, Math.max(timeoutMs, 1500)).then((data) => (data ? { ok: data.ok !== false, reason: data.reason ?? null } : { ok: true, reason: null }));
+    }
+    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 { view, event, identify, revenue, reset, flush, ping, links, shield, check };
+}

package/dist/core/secret.d.ts

@@ -0,0 +1,26 @@
+import type { DecideInput, GoalInput, IdentifyInput, ShieldInput, ShieldResult, Verdict } from './types.js';
+export interface SecretConfig {
+    secretKey: string;
+    endpoint: string;
+    timeoutMs: number;
+    /** Cap how long a per-IP verdict is cached, ms. Default 60000. */
+    cacheTtlMs?: number;
+}
+export interface SecretApi {
+    decide(input: DecideInput): Promise<Verdict | null>;
+    goal(name: string, options?: Omit<GoalInput, 'name'>): Promise<boolean>;
+    /** Record revenue/lifecycle with an explicit amount or status (secret-key path of `revenue`). */
+    payment(input: {
+        amount?: number;
+        currency?: string;
+        visitorId?: string;
+        event?: string;
+        status?: 'paid' | 'refunded' | 'cancelled' | 'subscription_ended';
+        refund?: boolean;
+    }): Promise<boolean>;
+    identify(input: IdentifyInput & {
+        visitorId: string;
+    }): Promise<boolean>;
+    shield(input: ShieldInput): Promise<ShieldResult>;
+}
+export declare function createSecretApi(config: SecretConfig): SecretApi;

package/dist/core/secret.js

@@ -0,0 +1,60 @@
+/**
+ * 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';
+export function createSecretApi(config) {
+    const { secretKey, endpoint } = config;
+    const timeoutMs = config.timeoutMs;
+    const cacheTtlMs = config.cacheTtlMs ?? 60_000;
+    const head = bearer(secretKey);
+    // Per-IP+UA verdict cache so most requests make no network call.
+    const cache = new Map();
+    async function decide(input) {
+        // Recording analytics means every hit must reach the server, so skip the verdict cache and
+        // send the full pageview context (host/referrer/visitor) alongside the decision inputs.
+        if (input.record) {
+            return postJson(`${endpoint}/api/v1/decide`, { ip: input.ip, ua: input.ua, path: input.path, host: input.host, referrer: input.referrer, visitor_id: input.visitorId, record: true }, head, timeoutMs);
+        }
+        const key = `${input.ip ?? ''}|${input.ua ?? ''}`;
+        const now = Date.now();
+        const hit = cache.get(key);
+        if (hit && hit.expires > now)
+            return hit.verdict;
+        const verdict = await postJson(`${endpoint}/api/v1/decide`, { ip: input.ip, ua: input.ua, path: input.path }, head, timeoutMs);
+        if (verdict)
+            cache.set(key, { verdict, expires: now + Math.min(cacheTtlMs, (verdict.ttl ?? 60) * 1000) });
+        return verdict;
+    }
+    function goal(name, options = {}) {
+        return postOk(`${endpoint}/api/v1/goals`, { name, visitor_id: options.visitorId, path: options.path, metadata: options.metadata }, head, timeoutMs);
+    }
+    function payment(input) {
+        return postOk(`${endpoint}/api/v1/payment`, {
+            amount: input.amount,
+            currency: input.currency,
+            visitor_id: input.visitorId,
+            event: input.event,
+            status: input.status,
+            refund: input.refund, // legacy; the server normalises it to status:refunded
+        }, head, timeoutMs);
+    }
+    function identify(input) {
+        // Fold the convenience fields into attributes so userId/email land as the same `userId`/`email`
+        // keys the snippet and browser SDK send — one consistent profile shape across every surface.
+        const attributes = { ...input.attributes };
+        if (input.userId !== undefined)
+            attributes.userId = input.userId;
+        if (input.email !== undefined)
+            attributes.email = input.email;
+        return postOk(`${endpoint}/api/v1/identify`, { visitor_id: input.visitorId, name: input.name, attributes }, head, timeoutMs);
+    }
+    async function shield(input) {
+        // Form Shield wants a bit longer than a firewall decision; never below 1500ms.
+        const data = await postJson(`${endpoint}/api/v1/form-shield`, input, head, Math.max(timeoutMs, 1500));
+        if (!data)
+            return { ok: true, reason: null }; // fail open
+        return { ok: data.ok !== false, reason: data.reason ?? null };
+    }
+    return { decide, goal, payment, identify, shield };
+}