@bot403/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Stoyanov
+
+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,46 @@
+# @bot403/node
+
+Bot403 is an invisible bot shield for HTML forms: one script tag makes the browser solve a small proof of work, and your server checks it with one call.
+
+This package is that one call, typed and with no dependencies. It runs wherever `fetch` exists: Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel and Next.js route handlers.
+
+```sh
+npm install @bot403/node
+```
+
+```ts
+import { Bot403 } from "@bot403/node";
+
+const bot403 = new Bot403({ secretKey: process.env.BOT403_SECRET_KEY! });
+
+// In your form handler:
+const result = await bot403.verifyForm(await request.formData());
+if (!result.ok) {
+  // result.reason: expired, replay, invalid, wrong_site, honeypot, quota or automation
+  return new Response("Spam check failed", { status: 400 });
+}
+```
+
+The same check with curl:
+
+```sh
+curl -X POST https://bot403.app/api/v1/verify \
+  -H "Authorization: Bearer sk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{"solution":"<the _bot403 field from the form>"}'
+```
+
+## API
+
+- `new Bot403({ secretKey, baseUrl?, fetch?, timeoutMs? })`: the secret key is the site's `sk_live_…` key. Keep it on the server.
+- `verify(token)`: checks one token. Resolves with a `VerifyResult`: `ok`, and a `reason` when it failed. A failed token is an answer, not an error.
+- `verifyForm(form)`: takes `FormData`, `URLSearchParams` or a parsed body object and sends every field, so a honeypot field set on the site is checked too.
+- `stats()`: the site's statistics for its window, with quota usage.
+- `tokenFrom(form)`: reads the token (`_bot403`, or `altcha` from the Altcha web component).
+- `Bot403Error`: thrown only when the request itself fails: a wrong secret key (401), too many verify calls (429), or a network failure (`status` 0).
+
+A `quota` reason comes with HTTP 402 and only in a capped month; the package returns it as a normal result, and you decide what the form does.
+
+In the browser, use [`@bot403/browser`](https://www.npmjs.com/package/@bot403/browser) or [`@bot403/react`](https://www.npmjs.com/package/@bot403/react), or just the script tag.
+
+Docs: https://bot403.app/docs/javascript · every failure reason: https://bot403.app/docs/verify

package/dist/cjs/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Bot403 on the server: verify the token a protected form sends, and read
+ * your site's statistics. Works wherever `fetch` exists: Node.js 18+, Bun,
+ * Deno, Cloudflare Workers, Vercel and Next.js route handlers.
+ *
+ * @example
+ * import { Bot403 } from "@bot403/node";
+ * const bot403 = new Bot403({ secretKey: process.env.BOT403_SECRET_KEY! });
+ * const result = await bot403.verifyForm(await request.formData());
+ * if (!result.ok) return new Response("Spam check failed", { status: 400 });
+ *
+ * @packageDocumentation
+ */
+/** The hidden form field the browser script fills with the token. */
+export declare const FIELD = "_bot403";
+/** Where the API lives unless you pass `baseUrl`. */
+export declare const DEFAULT_BASE_URL = "https://bot403.app";
+/** Why a token failed. `quota` comes with HTTP 402; the rest with 200. */
+export type FailureReason = "expired" | "replay" | "invalid" | "wrong_site" | "quota" | "honeypot" | "automation";
+/** Automation signals, present when they are on for the site. */
+export interface Automation {
+    /** `clean` means nothing was found, which is not a claim that a person is there. */
+    verdict: "clean" | "suspect" | "automated";
+    score: number;
+    reasons: string[];
+    /** `log` only reports; `enforce` also fails the token with reason `automation`. */
+    mode: "log" | "enforce";
+}
+/** The answer of `POST /api/v1/verify`. */
+export interface VerifyResult {
+    ok: boolean;
+    /** The site's public key. */
+    site: string;
+    /** Set when `ok` is false. */
+    reason?: FailureReason;
+    solved_at?: string;
+    /** The hostname the challenge was requested from. */
+    origin?: string;
+    difficulty?: string;
+    automation?: Automation;
+}
+/** The answer of `GET /api/v1/stats`. */
+export interface Stats {
+    site: string;
+    window_days: number;
+    totals: {
+        challenges: number;
+        solved: number;
+        verify_ok: number;
+        verify_fail: number;
+        rate_limited: number;
+        fail: Record<FailureReason, number>;
+        automated: number;
+        suspect: number;
+    };
+    days: {
+        day: string;
+        challenges: number;
+        verify_ok: number;
+        verify_fail: number;
+    }[];
+    series: number[];
+    origins: {
+        origin: string;
+        count: number;
+    }[];
+    recent: {
+        at: string;
+        kind: string;
+        reason?: string;
+        origin: string;
+        difficulty: string;
+        ip_prefix: string;
+        automation?: string;
+        automation_reasons?: string[];
+    }[];
+    quota: {
+        plan: string;
+        used: number;
+        limit: number;
+        /** Where verify starts answering 402; -1 when there is no cap this month. */
+        cap: number;
+        capped: boolean;
+        over_last_month: boolean;
+        resets_at: string;
+    };
+    automation_signals: {
+        reason: string;
+        count: number;
+    }[];
+}
+export interface Bot403Options {
+    /** The site's secret key, `sk_live_…`. Keep it on the server. */
+    secretKey: string;
+    /** Defaults to https://bot403.app. */
+    baseUrl?: string;
+    /** Your own fetch, for tests or older runtimes. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Abort a request after this many milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+}
+/**
+ * A request the API refused as a whole: a wrong secret key (401), too many
+ * verify calls (429), a body over 64 KB (413), or a network failure
+ * (`status` 0). A token that fails is not an error: it is a
+ * {@link VerifyResult} with `ok: false`.
+ */
+export declare class Bot403Error extends Error {
+    /** HTTP status, or 0 when the request did not complete. */
+    readonly status: number;
+    /** `unauthorized`, `rate_limited`, `too_large`, `invalid`, `network` or `http_<status>`. */
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/** Anything a form body can arrive as. */
+export type FormBody = FormData | URLSearchParams | Record<string, unknown>;
+/**
+ * Reads the token from a submitted form: the `_bot403` field, or `altcha`
+ * when the Altcha web component was used.
+ */
+export declare function tokenFrom(body: FormBody): string | undefined;
+export declare class Bot403 {
+    #private;
+    constructor(options: Bot403Options);
+    /**
+     * Checks one token. Resolves with `ok: true`, or `ok: false` and a reason;
+     * rejects with {@link Bot403Error} only when the request itself fails.
+     */
+    verify(token: string | null | undefined): Promise<VerifyResult>;
+    /**
+     * Checks the token inside a submitted form. The whole form is sent, so a
+     * honeypot field set on the site is checked too.
+     */
+    verifyForm(form: FormBody): Promise<VerifyResult>;
+    /** The site's statistics for its window, including quota usage. */
+    stats(): Promise<Stats>;
+}

package/dist/cjs/index.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Bot403 on the server: verify the token a protected form sends, and read
+ * your site's statistics. Works wherever `fetch` exists: Node.js 18+, Bun,
+ * Deno, Cloudflare Workers, Vercel and Next.js route handlers.
+ *
+ * @example
+ * import { Bot403 } from "@bot403/node";
+ * const bot403 = new Bot403({ secretKey: process.env.BOT403_SECRET_KEY! });
+ * const result = await bot403.verifyForm(await request.formData());
+ * if (!result.ok) return new Response("Spam check failed", { status: 400 });
+ *
+ * @packageDocumentation
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Bot403_instances, _Bot403_secretKey, _Bot403_baseUrl, _Bot403_fetch, _Bot403_timeoutMs, _Bot403_verifyBody, _Bot403_request;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bot403 = exports.Bot403Error = exports.DEFAULT_BASE_URL = exports.FIELD = void 0;
+exports.tokenFrom = tokenFrom;
+/** The hidden form field the browser script fills with the token. */
+exports.FIELD = "_bot403";
+/** Where the API lives unless you pass `baseUrl`. */
+exports.DEFAULT_BASE_URL = "https://bot403.app";
+/**
+ * A request the API refused as a whole: a wrong secret key (401), too many
+ * verify calls (429), a body over 64 KB (413), or a network failure
+ * (`status` 0). A token that fails is not an error: it is a
+ * {@link VerifyResult} with `ok: false`.
+ */
+class Bot403Error extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.name = "Bot403Error";
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.Bot403Error = Bot403Error;
+/**
+ * Reads the token from a submitted form: the `_bot403` field, or `altcha`
+ * when the Altcha web component was used.
+ */
+function tokenFrom(body) {
+    const get = (k) => body instanceof URLSearchParams || (typeof FormData !== "undefined" && body instanceof FormData)
+        ? body.get(k)
+        : body[k];
+    for (const k of [exports.FIELD, "altcha"]) {
+        const v = get(k);
+        if (typeof v === "string" && v !== "")
+            return v;
+    }
+    return undefined;
+}
+class Bot403 {
+    constructor(options) {
+        _Bot403_instances.add(this);
+        _Bot403_secretKey.set(this, void 0);
+        _Bot403_baseUrl.set(this, void 0);
+        _Bot403_fetch.set(this, void 0);
+        _Bot403_timeoutMs.set(this, void 0);
+        if (!options || !options.secretKey)
+            throw new TypeError("@bot403/node: secretKey is required");
+        if (options.secretKey.startsWith("pk_"))
+            throw new TypeError("@bot403/node: that is the public key; pass the secret key (sk_live_…)");
+        __classPrivateFieldSet(this, _Bot403_secretKey, options.secretKey, "f");
+        __classPrivateFieldSet(this, _Bot403_baseUrl, (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, ""), "f");
+        const f = options.fetch ?? (typeof fetch === "function" ? fetch : undefined);
+        if (!f)
+            throw new TypeError("@bot403/node: no fetch in this runtime; pass options.fetch");
+        __classPrivateFieldSet(this, _Bot403_fetch, f, "f");
+        __classPrivateFieldSet(this, _Bot403_timeoutMs, options.timeoutMs ?? 10000, "f");
+    }
+    /**
+     * Checks one token. Resolves with `ok: true`, or `ok: false` and a reason;
+     * rejects with {@link Bot403Error} only when the request itself fails.
+     */
+    verify(token) {
+        return __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_verifyBody).call(this, JSON.stringify({ solution: token ?? "" }), "application/json");
+    }
+    /**
+     * Checks the token inside a submitted form. The whole form is sent, so a
+     * honeypot field set on the site is checked too.
+     */
+    verifyForm(form) {
+        const params = new URLSearchParams();
+        const add = (k, v) => {
+            if (typeof v === "string")
+                params.append(k, v);
+        };
+        if (form instanceof URLSearchParams || (typeof FormData !== "undefined" && form instanceof FormData)) {
+            form.forEach((v, k) => add(k, v));
+        }
+        else {
+            for (const [k, v] of Object.entries(form))
+                add(k, Array.isArray(v) ? v[0] : v);
+        }
+        return __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_verifyBody).call(this, params.toString(), "application/x-www-form-urlencoded");
+    }
+    /** The site's statistics for its window, including quota usage. */
+    async stats() {
+        const res = await __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_request).call(this, "GET", "/api/v1/stats");
+        if (res.status !== 200)
+            throw await errorFrom(res);
+        return (await res.json());
+    }
+}
+exports.Bot403 = Bot403;
+_Bot403_secretKey = new WeakMap(), _Bot403_baseUrl = new WeakMap(), _Bot403_fetch = new WeakMap(), _Bot403_timeoutMs = new WeakMap(), _Bot403_instances = new WeakSet(), _Bot403_verifyBody = async function _Bot403_verifyBody(body, contentType) {
+    const res = await __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_request).call(this, "POST", "/api/v1/verify", body, contentType);
+    // 402 is a normal answer: the monthly quota is used up in a capped month.
+    if (res.status === 200 || res.status === 402)
+        return (await res.json());
+    throw await errorFrom(res);
+}, _Bot403_request = async function _Bot403_request(method, path, body, contentType) {
+    const ctrl = typeof AbortController === "function" ? new AbortController() : undefined;
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), __classPrivateFieldGet(this, _Bot403_timeoutMs, "f")) : undefined;
+    const headers = { Authorization: `Bearer ${__classPrivateFieldGet(this, _Bot403_secretKey, "f")}`, Accept: "application/json" };
+    if (contentType)
+        headers["Content-Type"] = contentType;
+    try {
+        return await __classPrivateFieldGet(this, _Bot403_fetch, "f").call(this, __classPrivateFieldGet(this, _Bot403_baseUrl, "f") + path, { method, headers, body, signal: ctrl?.signal });
+    }
+    catch (err) {
+        throw new Bot403Error(`@bot403/node: ${method} ${path} failed: ${err?.message ?? err}`, 0, "network");
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+};
+async function errorFrom(res) {
+    let code = `http_${res.status}`;
+    let message = `@bot403/node: HTTP ${res.status}`;
+    try {
+        const j = (await res.json());
+        code = j.reason || j.error || code;
+        if (j.message)
+            message = `@bot403/node: ${j.message}`;
+    }
+    catch {
+        // not JSON; keep the status
+    }
+    return new Bot403Error(message, res.status, code);
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/esm/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Bot403 on the server: verify the token a protected form sends, and read
+ * your site's statistics. Works wherever `fetch` exists: Node.js 18+, Bun,
+ * Deno, Cloudflare Workers, Vercel and Next.js route handlers.
+ *
+ * @example
+ * import { Bot403 } from "@bot403/node";
+ * const bot403 = new Bot403({ secretKey: process.env.BOT403_SECRET_KEY! });
+ * const result = await bot403.verifyForm(await request.formData());
+ * if (!result.ok) return new Response("Spam check failed", { status: 400 });
+ *
+ * @packageDocumentation
+ */
+/** The hidden form field the browser script fills with the token. */
+export declare const FIELD = "_bot403";
+/** Where the API lives unless you pass `baseUrl`. */
+export declare const DEFAULT_BASE_URL = "https://bot403.app";
+/** Why a token failed. `quota` comes with HTTP 402; the rest with 200. */
+export type FailureReason = "expired" | "replay" | "invalid" | "wrong_site" | "quota" | "honeypot" | "automation";
+/** Automation signals, present when they are on for the site. */
+export interface Automation {
+    /** `clean` means nothing was found, which is not a claim that a person is there. */
+    verdict: "clean" | "suspect" | "automated";
+    score: number;
+    reasons: string[];
+    /** `log` only reports; `enforce` also fails the token with reason `automation`. */
+    mode: "log" | "enforce";
+}
+/** The answer of `POST /api/v1/verify`. */
+export interface VerifyResult {
+    ok: boolean;
+    /** The site's public key. */
+    site: string;
+    /** Set when `ok` is false. */
+    reason?: FailureReason;
+    solved_at?: string;
+    /** The hostname the challenge was requested from. */
+    origin?: string;
+    difficulty?: string;
+    automation?: Automation;
+}
+/** The answer of `GET /api/v1/stats`. */
+export interface Stats {
+    site: string;
+    window_days: number;
+    totals: {
+        challenges: number;
+        solved: number;
+        verify_ok: number;
+        verify_fail: number;
+        rate_limited: number;
+        fail: Record<FailureReason, number>;
+        automated: number;
+        suspect: number;
+    };
+    days: {
+        day: string;
+        challenges: number;
+        verify_ok: number;
+        verify_fail: number;
+    }[];
+    series: number[];
+    origins: {
+        origin: string;
+        count: number;
+    }[];
+    recent: {
+        at: string;
+        kind: string;
+        reason?: string;
+        origin: string;
+        difficulty: string;
+        ip_prefix: string;
+        automation?: string;
+        automation_reasons?: string[];
+    }[];
+    quota: {
+        plan: string;
+        used: number;
+        limit: number;
+        /** Where verify starts answering 402; -1 when there is no cap this month. */
+        cap: number;
+        capped: boolean;
+        over_last_month: boolean;
+        resets_at: string;
+    };
+    automation_signals: {
+        reason: string;
+        count: number;
+    }[];
+}
+export interface Bot403Options {
+    /** The site's secret key, `sk_live_…`. Keep it on the server. */
+    secretKey: string;
+    /** Defaults to https://bot403.app. */
+    baseUrl?: string;
+    /** Your own fetch, for tests or older runtimes. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Abort a request after this many milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+}
+/**
+ * A request the API refused as a whole: a wrong secret key (401), too many
+ * verify calls (429), a body over 64 KB (413), or a network failure
+ * (`status` 0). A token that fails is not an error: it is a
+ * {@link VerifyResult} with `ok: false`.
+ */
+export declare class Bot403Error extends Error {
+    /** HTTP status, or 0 when the request did not complete. */
+    readonly status: number;
+    /** `unauthorized`, `rate_limited`, `too_large`, `invalid`, `network` or `http_<status>`. */
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/** Anything a form body can arrive as. */
+export type FormBody = FormData | URLSearchParams | Record<string, unknown>;
+/**
+ * Reads the token from a submitted form: the `_bot403` field, or `altcha`
+ * when the Altcha web component was used.
+ */
+export declare function tokenFrom(body: FormBody): string | undefined;
+export declare class Bot403 {
+    #private;
+    constructor(options: Bot403Options);
+    /**
+     * Checks one token. Resolves with `ok: true`, or `ok: false` and a reason;
+     * rejects with {@link Bot403Error} only when the request itself fails.
+     */
+    verify(token: string | null | undefined): Promise<VerifyResult>;
+    /**
+     * Checks the token inside a submitted form. The whole form is sent, so a
+     * honeypot field set on the site is checked too.
+     */
+    verifyForm(form: FormBody): Promise<VerifyResult>;
+    /** The site's statistics for its window, including quota usage. */
+    stats(): Promise<Stats>;
+}

package/dist/esm/index.js

@@ -0,0 +1,148 @@
+/**
+ * Bot403 on the server: verify the token a protected form sends, and read
+ * your site's statistics. Works wherever `fetch` exists: Node.js 18+, Bun,
+ * Deno, Cloudflare Workers, Vercel and Next.js route handlers.
+ *
+ * @example
+ * import { Bot403 } from "@bot403/node";
+ * const bot403 = new Bot403({ secretKey: process.env.BOT403_SECRET_KEY! });
+ * const result = await bot403.verifyForm(await request.formData());
+ * if (!result.ok) return new Response("Spam check failed", { status: 400 });
+ *
+ * @packageDocumentation
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Bot403_instances, _Bot403_secretKey, _Bot403_baseUrl, _Bot403_fetch, _Bot403_timeoutMs, _Bot403_verifyBody, _Bot403_request;
+/** The hidden form field the browser script fills with the token. */
+export const FIELD = "_bot403";
+/** Where the API lives unless you pass `baseUrl`. */
+export const DEFAULT_BASE_URL = "https://bot403.app";
+/**
+ * A request the API refused as a whole: a wrong secret key (401), too many
+ * verify calls (429), a body over 64 KB (413), or a network failure
+ * (`status` 0). A token that fails is not an error: it is a
+ * {@link VerifyResult} with `ok: false`.
+ */
+export class Bot403Error extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.name = "Bot403Error";
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Reads the token from a submitted form: the `_bot403` field, or `altcha`
+ * when the Altcha web component was used.
+ */
+export function tokenFrom(body) {
+    const get = (k) => body instanceof URLSearchParams || (typeof FormData !== "undefined" && body instanceof FormData)
+        ? body.get(k)
+        : body[k];
+    for (const k of [FIELD, "altcha"]) {
+        const v = get(k);
+        if (typeof v === "string" && v !== "")
+            return v;
+    }
+    return undefined;
+}
+export class Bot403 {
+    constructor(options) {
+        _Bot403_instances.add(this);
+        _Bot403_secretKey.set(this, void 0);
+        _Bot403_baseUrl.set(this, void 0);
+        _Bot403_fetch.set(this, void 0);
+        _Bot403_timeoutMs.set(this, void 0);
+        if (!options || !options.secretKey)
+            throw new TypeError("@bot403/node: secretKey is required");
+        if (options.secretKey.startsWith("pk_"))
+            throw new TypeError("@bot403/node: that is the public key; pass the secret key (sk_live_…)");
+        __classPrivateFieldSet(this, _Bot403_secretKey, options.secretKey, "f");
+        __classPrivateFieldSet(this, _Bot403_baseUrl, (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""), "f");
+        const f = options.fetch ?? (typeof fetch === "function" ? fetch : undefined);
+        if (!f)
+            throw new TypeError("@bot403/node: no fetch in this runtime; pass options.fetch");
+        __classPrivateFieldSet(this, _Bot403_fetch, f, "f");
+        __classPrivateFieldSet(this, _Bot403_timeoutMs, options.timeoutMs ?? 10000, "f");
+    }
+    /**
+     * Checks one token. Resolves with `ok: true`, or `ok: false` and a reason;
+     * rejects with {@link Bot403Error} only when the request itself fails.
+     */
+    verify(token) {
+        return __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_verifyBody).call(this, JSON.stringify({ solution: token ?? "" }), "application/json");
+    }
+    /**
+     * Checks the token inside a submitted form. The whole form is sent, so a
+     * honeypot field set on the site is checked too.
+     */
+    verifyForm(form) {
+        const params = new URLSearchParams();
+        const add = (k, v) => {
+            if (typeof v === "string")
+                params.append(k, v);
+        };
+        if (form instanceof URLSearchParams || (typeof FormData !== "undefined" && form instanceof FormData)) {
+            form.forEach((v, k) => add(k, v));
+        }
+        else {
+            for (const [k, v] of Object.entries(form))
+                add(k, Array.isArray(v) ? v[0] : v);
+        }
+        return __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_verifyBody).call(this, params.toString(), "application/x-www-form-urlencoded");
+    }
+    /** The site's statistics for its window, including quota usage. */
+    async stats() {
+        const res = await __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_request).call(this, "GET", "/api/v1/stats");
+        if (res.status !== 200)
+            throw await errorFrom(res);
+        return (await res.json());
+    }
+}
+_Bot403_secretKey = new WeakMap(), _Bot403_baseUrl = new WeakMap(), _Bot403_fetch = new WeakMap(), _Bot403_timeoutMs = new WeakMap(), _Bot403_instances = new WeakSet(), _Bot403_verifyBody = async function _Bot403_verifyBody(body, contentType) {
+    const res = await __classPrivateFieldGet(this, _Bot403_instances, "m", _Bot403_request).call(this, "POST", "/api/v1/verify", body, contentType);
+    // 402 is a normal answer: the monthly quota is used up in a capped month.
+    if (res.status === 200 || res.status === 402)
+        return (await res.json());
+    throw await errorFrom(res);
+}, _Bot403_request = async function _Bot403_request(method, path, body, contentType) {
+    const ctrl = typeof AbortController === "function" ? new AbortController() : undefined;
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), __classPrivateFieldGet(this, _Bot403_timeoutMs, "f")) : undefined;
+    const headers = { Authorization: `Bearer ${__classPrivateFieldGet(this, _Bot403_secretKey, "f")}`, Accept: "application/json" };
+    if (contentType)
+        headers["Content-Type"] = contentType;
+    try {
+        return await __classPrivateFieldGet(this, _Bot403_fetch, "f").call(this, __classPrivateFieldGet(this, _Bot403_baseUrl, "f") + path, { method, headers, body, signal: ctrl?.signal });
+    }
+    catch (err) {
+        throw new Bot403Error(`@bot403/node: ${method} ${path} failed: ${err?.message ?? err}`, 0, "network");
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+};
+async function errorFrom(res) {
+    let code = `http_${res.status}`;
+    let message = `@bot403/node: HTTP ${res.status}`;
+    try {
+        const j = (await res.json());
+        code = j.reason || j.error || code;
+        if (j.message)
+            message = `@bot403/node: ${j.message}`;
+    }
+    catch {
+        // not JSON; keep the status
+    }
+    return new Bot403Error(message, res.status, code);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@bot403/node",
+  "version": "0.1.0",
+  "description": "Bot403 for Node.js and other server runtimes: verify form tokens and read statistics. Typed, no dependencies. Works in Node.js 18+, Bun, Deno, Cloudflare Workers and Next.js.",
+  "keywords": [
+    "bot403",
+    "captcha",
+    "spam",
+    "bot-protection",
+    "proof-of-work",
+    "altcha",
+    "forms",
+    "server",
+    "nodejs",
+    "bun",
+    "deno",
+    "cloudflare-workers"
+  ],
+  "homepage": "https://bot403.app/docs/javascript",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zaharystoyanovlabs/bot403.git",
+    "directory": "sdk/js/packages/node"
+  },
+  "bugs": {
+    "email": "hello@bot403.app"
+  },
+  "license": "MIT",
+  "author": "Zahary Stoyanov",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ../../scripts/cjs-package.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}