vpndetection 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+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,158 @@
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Node.js Client Library
+
+[![npm](https://img.shields.io/npm/v/vpndetection.svg)](https://www.npmjs.com/package/vpndetection)
+[![license](https://img.shields.io/npm/l/vpndetection.svg)](LICENSE)
+
+The official Node.js client library for the [VPNDetection](https://vpndetection.io) API.
+
+The library helps you query VPNDetection's APIs for anonymity detection including VPNs, residential proxies, Tor nodes, hosting servers, CDNs, relays and more.
+
+## Getting Started
+
+```bash
+npm install vpndetection
+```
+
+Requires Node.js 22 or newer. TypeScript types are included.
+
+## Usage
+
+**No API key needed to start.** The free tier answers `ip` and `is_vpn`, and allows 1000 requests per day per source address.
+
+```js
+import { VPNDetection } from 'vpndetection';
+
+const client = new VPNDetection();
+
+const result = await client.lookup('45.83.91.1');
+console.log(result.isVpn);   // true
+```
+
+### With an API key
+
+An API key raises your quota, and raises your features on a paid plan. Create one in the [console](https://app.vpndetection.io), then pass it in:
+
+```js
+const client = new VPNDetection({ apiKey: process.env.VPNDETECTION_API_KEY });
+
+const result = await client.lookup('45.83.91.1');
+console.log(result.isVpn);          // true
+console.log(result.vpn?.provider);  // 'mullvad'
+console.log(result.isHosting);      // true
+console.log(result.hosting?.provider);
+```
+
+### Batch lookup
+
+You can do batch lookups with a list, which parallelizes requests for you efficiently:
+
+```js
+const results = await client.lookupBatch(['45.83.91.1', '8.8.8.8', '1.1.1.1']);
+
+for (const [ip, result] of results) {
+    if (result instanceof Error) {
+        console.error(`${ip}: ${result.message}`);
+        continue;
+    }
+    console.log(`${ip}: ${result.isVpn}`);
+}
+```
+
+Results are keyed by address, so duplicates in your list collapse into a single request and one address failing never loses the rest.
+
+Concurrency and other variables are configurable per-call:
+
+```js
+const results = await client.lookupBatch(manyIps, { concurrency: 32, retries: 4 });
+```
+
+### Caching
+
+Answers are cached by default, so repeat lookups of the same address are free:
+
+```js
+const client = new VPNDetection();
+
+const result = await client.lookup('45.83.91.1');
+console.log(result.isVpn);   // true, API request
+
+const result2 = await client.lookup('45.83.91.1');
+console.log(result2.isVpn);  // true, no API request, result was cached
+```
+
+You can change the default cache variables (max size, TTL, etc) on initialization, or even disable it:
+
+```js
+const client = new VPNDetection({ cache: { max: 50_000, ttlMs: 6 * 60 * 60 * 1000 } });
+const clientNoCache = new VPNDetection({ cache: false });
+```
+
+### Private and reserved addresses
+
+Private, loopback, link-local, documentation and multicast addresses (and their IPv6 equivalents, including the 6to4 and Teredo ranges) can never be VPN or proxy infrastructure. The library answers them locally, so they cost no request and no quota:
+
+```js
+const result = await client.lookup('192.168.1.1');
+result.isBogon;   // true, this answer was computed rather than served
+result.isVpn;     // false
+```
+
+The check is available on the client, which is handy when your inputs are addresses anyway:
+
+```js
+client.isBogon('10.0.0.1');    // true
+client.isBogon('8.8.8.8');     // false
+```
+
+It is also importable on its own, if you want it without a client:
+
+```js
+import { isBogon } from 'vpndetection';
+
+isBogon('10.0.0.1');    // true
+```
+
+### Errors
+
+Failures throw a `VPNDetectionError` carrying a `kind` and a `retryable` flag:
+
+```js
+import { VPNDetectionError } from 'vpndetection';
+
+try {
+    await client.lookup('1.1.1.1');
+} catch (err) {
+    if (err instanceof VPNDetectionError) {
+        console.error(err.kind, err.retryable);
+    }
+}
+```
+
+`kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`.
+
+Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.
+
+### Database downloads
+
+If your key carries the `db.download` scope, the licensed datasets are available through `client.database`:
+
+```js
+const datasets = await client.database.list();
+const url = await client.database.downloadUrl('vpn_ip_extended_v1', 'mmdb');
+```
+
+`downloadUrl` returns a time-limited link rather than the bytes, so you choose how to transfer a file that can run to gigabytes.
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/bogon.d.ts

@@ -0,0 +1,19 @@
+import type { Result } from './types.js';
+/**
+ * Whether an address is a bogon: private, loopback, link-local, documentation,
+ * multicast or otherwise not routable on the public internet, including the
+ * IPv6 equivalents and the 6to4 and Teredo ranges that wrap them.
+ *
+ * These can never be VPN or proxy infrastructure, so the client answers them
+ * itself and they never cost a request.
+ */
+export declare function isBogon(ip: string): boolean;
+/**
+ * The answer a bogon gets, in the full shape the API serves at its widest plan:
+ * every flag present and false, every detail object present and empty.
+ *
+ * `isBogon` is set so a caller can always tell a locally computed answer from a
+ * served one. Note this is deliberately the WIDEST shape regardless of your
+ * plan, so do not infer which fields your plan includes from a bogon answer.
+ */
+export declare function bogonResult(ip: string): Result;

package/dist/bogon.js

@@ -0,0 +1,130 @@
+import { BOGON_V4, BOGON_V6 } from './bogons.gen.js';
+/**
+ * Whether an address is a bogon: private, loopback, link-local, documentation,
+ * multicast or otherwise not routable on the public internet, including the
+ * IPv6 equivalents and the 6to4 and Teredo ranges that wrap them.
+ *
+ * These can never be VPN or proxy infrastructure, so the client answers them
+ * itself and they never cost a request.
+ */
+export function isBogon(ip) {
+    if (ip.includes(':')) {
+        const a = v6ToInt(ip);
+        return a === null ? false : v6().some((r) => (a & r.mask) === r.net);
+    }
+    const a = v4ToInt(ip);
+    return a === null ? false : v4().some((r) => (a & r.mask) >>> 0 === r.net);
+}
+/**
+ * The answer a bogon gets, in the full shape the API serves at its widest plan:
+ * every flag present and false, every detail object present and empty.
+ *
+ * `isBogon` is set so a caller can always tell a locally computed answer from a
+ * served one. Note this is deliberately the WIDEST shape regardless of your
+ * plan, so do not infer which fields your plan includes from a bogon answer.
+ */
+export function bogonResult(ip) {
+    return {
+        ip: ip,
+        isBogon: true,
+        isVpn: false,
+        isHosting: false,
+        isRelay: false,
+        isTor: false,
+        isCdn: false,
+        isResproxy: false,
+        isDcproxy: false,
+        isMobproxy: false,
+        vpn: {},
+        hosting: {},
+        relay: {},
+        tor: {},
+        cdn: {},
+        resproxy: {},
+        dcproxy: {},
+        mobproxy: {},
+        raw: {},
+    };
+}
+// Parsed once on first use rather than at import: a consumer that never looks
+// up an address should not pay for the table, and module-scope work is what
+// makes a library expensive to import.
+let v4Cache = null;
+let v6Cache = null;
+function v4() {
+    if (!v4Cache) {
+        v4Cache = BOGON_V4.map((c) => {
+            const [net, bits] = c.split('/');
+            const mask = bits === '0' ? 0 : (~0 << (32 - Number(bits))) >>> 0;
+            return { net: (v4ToInt(net) & mask) >>> 0, mask: mask };
+        });
+    }
+    return v4Cache;
+}
+function v6() {
+    if (!v6Cache) {
+        v6Cache = BOGON_V6.map((c) => {
+            const [net, bits] = c.split('/');
+            const mask = bits === '0' ? 0n : (~0n << BigInt(128 - Number(bits))) & MAX128;
+            return { net: v6ToInt(net) & mask, mask: mask };
+        });
+    }
+    return v6Cache;
+}
+const MAX128 = (1n << 128n) - 1n;
+function v4ToInt(ip) {
+    const p = ip.split('.');
+    if (p.length !== 4) {
+        return null;
+    }
+    let n = 0;
+    for (const part of p) {
+        const b = Number(part);
+        if (!Number.isInteger(b) || b < 0 || b > 255 || part === '') {
+            return null;
+        }
+        n = ((n << 8) | b) >>> 0;
+    }
+    return n;
+}
+// Handles the `::` run and a trailing IPv4 literal (::ffff:1.2.3.4), which
+// several of the canonical ranges use.
+function v6ToInt(ip) {
+    let a = ip;
+    const v4Tail = a.match(/(\d+\.\d+\.\d+\.\d+)$/);
+    if (v4Tail) {
+        const n = v4ToInt(v4Tail[1]);
+        if (n === null) {
+            return null;
+        }
+        const hi = (n >>> 16).toString(16).padStart(4, '0');
+        const lo = (n & 0xffff).toString(16).padStart(4, '0');
+        a = `${a.slice(0, v4Tail.index)}${hi}:${lo}`;
+    }
+    const dbl = a.indexOf('::');
+    let groups;
+    if (dbl === -1) {
+        groups = a.split(':');
+        if (groups.length !== 8) {
+            return null;
+        }
+    }
+    else {
+        const head = a.slice(0, dbl).split(':').filter((g) => g !== '');
+        const tail = a.slice(dbl + 2).split(':').filter((g) => g !== '');
+        const fill = 8 - head.length - tail.length;
+        if (fill < 0) {
+            return null;
+        }
+        groups = [...head, ...Array(fill).fill('0'), ...tail];
+    }
+    let n = 0n;
+    for (const g of groups) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(g)) {
+            return null;
+        }
+        n = (n << 16n) | BigInt(parseInt(g, 16));
+    }
+    return n;
+}
+//# sourceMappingURL=bogon.js.map

package/dist/bogon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bogon.js","sourceRoot":"","sources":["../src/bogon.ts"],"names":[],"mappings":"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"}

package/dist/bogons.gen.d.ts

@@ -0,0 +1,2 @@
+export declare const BOGON_V4: readonly string[];
+export declare const BOGON_V6: readonly string[];

package/dist/bogons.gen.js

@@ -0,0 +1,62 @@
+// Generated by sdk/common. Do not edit.
+// The canonical list lives in the monorepo and is checked against both
+// upstream definitions on every regeneration.
+export const BOGON_V4 = [
+    '0.0.0.0/8',
+    '10.0.0.0/8',
+    '100.64.0.0/10',
+    '127.0.0.0/8',
+    '169.254.0.0/16',
+    '172.16.0.0/12',
+    '192.0.0.0/24',
+    '192.0.2.0/24',
+    '192.168.0.0/16',
+    '198.18.0.0/15',
+    '198.51.100.0/24',
+    '203.0.113.0/24',
+    '224.0.0.0/4',
+    '240.0.0.0/4',
+    '255.255.255.255/32',
+];
+export const BOGON_V6 = [
+    '::/128',
+    '::1/128',
+    '::ffff:0:0/96',
+    '::/96',
+    '100::/64',
+    '2001:10::/28',
+    '2001:db8::/32',
+    'fc00::/7',
+    'fe80::/10',
+    'fec0::/10',
+    'ff00::/8',
+    '2002::/24',
+    '2002:a00::/24',
+    '2002:7f00::/24',
+    '2002:a9fe::/32',
+    '2002:ac10::/28',
+    '2002:c000::/40',
+    '2002:c000:200::/40',
+    '2002:c0a8::/32',
+    '2002:c612::/31',
+    '2002:c633:6400::/40',
+    '2002:cb00:7100::/40',
+    '2002:e000::/20',
+    '2002:f000::/20',
+    '2002:ffff:ffff::/48',
+    '2001::/40',
+    '2001:0:a00::/40',
+    '2001:0:7f00::/40',
+    '2001:0:a9fe::/48',
+    '2001:0:ac10::/44',
+    '2001:0:c000::/56',
+    '2001:0:c000:200::/56',
+    '2001:0:c0a8::/48',
+    '2001:0:c612::/47',
+    '2001:0:c633:6400::/56',
+    '2001:0:cb00:7100::/56',
+    '2001:0:e000::/36',
+    '2001:0:f000::/36',
+    '2001:0:ffff:ffff::/64',
+];
+//# sourceMappingURL=bogons.gen.js.map

package/dist/bogons.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bogons.gen.js","sourceRoot":"","sources":["../src/bogons.gen.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,uEAAuE;AACvE,8CAA8C;AAE9C,MAAM,CAAC,MAAM,QAAQ,GAAsB;IACvC,WAAW;IACX,YAAY;IACZ,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,oBAAoB;CACvB,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAsB;IACvC,QAAQ;IACR,SAAS;IACT,eAAe;IACf,OAAO;IACP,UAAU;IACV,cAAc;IACd,eAAe;IACf,UAAU;IACV,WAAW;IACX,WAAW;IACX,UAAU;IACV,WAAW;IACX,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,oBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,gBAAgB;IAChB,qBAAqB;IACrB,WAAW;IACX,iBAAiB;IACjB,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAClB,sBAAsB;IACtB,kBAAkB;IAClB,kBAAkB;IAClB,uBAAuB;IACvB,uBAAuB;IACvB,kBAAkB;IAClB,kBAAkB;IAClB,uBAAuB;CAC1B,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+import type { Client } from './generated/client/index.js';
+import type { DatasetMetadata, Download, LicensedDataset } from './generated/types.gen.js';
+import { VPNDetectionError } from './errors.js';
+import { type Result } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.vpndetection.io";
+export interface CacheOptions {
+    /** Maximum number of addresses held. Default 10000. */
+    max?: number;
+    /** How long an answer stays fresh, in milliseconds. Default 1 hour. */
+    ttlMs?: number;
+}
+export interface Options {
+    /**
+     * Your API key. Omit it entirely to use the free tier, which answers
+     * `ip` and `is_vpn` and allows 1000 requests per day per source address.
+     */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Pass `false` to disable caching. */
+    cache?: CacheOptions | false;
+    /** Concurrent in-flight requests during a batch. Default 8. */
+    concurrency?: number;
+    /** Retry attempts for a transient failure. Default 2. */
+    retries?: number;
+    /** Override the HTTP implementation, mostly for tests. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Per-call overrides for a single lookup. Anything omitted falls back to the client's setting. */
+export interface LookupOptions {
+    /** Retry attempts for a transient failure. */
+    retries?: number;
+}
+/** Per-call overrides for one batch. Anything omitted falls back to the client's setting. */
+export interface BatchOptions extends LookupOptions {
+    /** Concurrent in-flight requests for THIS batch only. */
+    concurrency?: number;
+}
+/**
+ * A client for the VPNDetection API.
+ *
+ * The cache is per instance, so an answer is never shared between two clients
+ * holding different API keys and therefore entitled to different fields.
+ */
+export declare class VPNDetection {
+    private readonly client;
+    private readonly cache;
+    private readonly limit;
+    private readonly retries;
+    /** The licensed dataset downloads, for keys that carry the `db.download` scope. */
+    readonly database: DatabaseApi;
+    constructor(options?: Options);
+    /**
+     * Whether an address is private, loopback, link-local, documentation,
+     * multicast or otherwise not routable, including the IPv6 equivalents and
+     * the 6to4 and Teredo ranges.
+     *
+     * These are the addresses `lookup` answers locally. Exposed here so the
+     * check is reachable from the client you already hold; the same function is
+     * also importable on its own.
+     */
+    isBogon(ip: string): boolean;
+    /**
+     * Classify one address.
+     *
+     * A bogon is answered locally and never reaches the network. Everything
+     * else is served, then cached for this instance.
+     */
+    lookup(ip: string, options?: LookupOptions): Promise<Result>;
+    /**
+     * Classify many addresses concurrently.
+     *
+     * Keyed by address rather than positional, so duplicates in the input
+     * collapse to a single request and the caller never has to line two lists
+     * up. An address that fails carries its error as its value, so one bad
+     * entry cannot lose the rest of the answers.
+     */
+    lookupBatch(ips: Iterable<string>, options?: BatchOptions): Promise<Map<string, Result | VPNDetectionError>>;
+}
+/** The licensed dataset downloads. Access is granted by contract, not self-serve. */
+export declare class DatabaseApi {
+    private readonly client;
+    private readonly retries;
+    constructor(client: Client, retries: number);
+    list(): Promise<LicensedDataset[]>;
+    metadata(id: string): Promise<DatasetMetadata>;
+    checksum(id: string, format: 'csvgz' | 'mmdb'): Promise<string>;
+    downloads(): Promise<Download[]>;
+    /**
+     * The time-limited URL for one dataset file.
+     *
+     * The API answers `302` to object storage. The URL is returned rather than
+     * the bytes so the caller decides how to transfer a file that routinely
+     * runs to gigabytes; the link authorizes the START of a transfer, so one
+     * already running is not interrupted when it lapses.
+     */
+    downloadUrl(id: string, format: 'csvgz' | 'mmdb'): Promise<string>;
+}