vpndetection 1.0.0

package/dist/generated/types.gen.d.ts

@@ -0,0 +1,466 @@
+export type ClientOptions = {
+    baseUrl: 'https://api.vpndetection.io' | 'https://api-staging.vpndetection.io' | (string & {});
+};
+/**
+ * The union of every plan's answer. Only `ip` and `is_vpn` are guaranteed;
+ * each remaining field is present when your plan includes it, and absent
+ * otherwise. A client that must work across plans should treat an absent
+ * flag as unknown rather than as `false`.
+ *
+ */
+export type LookupResponse = {
+    /**
+     * The address that was looked up, normalized.
+     */
+    ip: string;
+    /**
+     * Whether the address is VPN infrastructure. Keys off presence in the
+     * VPN dataset, so an unattributed range with no provider is still
+     * `true`.
+     *
+     */
+    is_vpn: boolean;
+    /**
+     * Whether the address belongs to a hosting or cloud provider. Starter and above.
+     */
+    is_hosting?: boolean;
+    /**
+     * Whether the address is a privacy relay egress. Starter and above.
+     */
+    is_relay?: boolean;
+    /**
+     * Whether the address is a Tor node. Starter and above.
+     */
+    is_tor?: boolean;
+    /**
+     * Whether the address belongs to a CDN. Starter and above.
+     */
+    is_cdn?: boolean;
+    /**
+     * Whether the address was seen in a residential proxy pool. Max only.
+     */
+    is_resproxy?: boolean;
+    /**
+     * Whether the address was seen in a datacenter proxy pool. Max only.
+     */
+    is_dcproxy?: boolean;
+    /**
+     * Whether the address was seen in a mobile proxy pool. Max only.
+     */
+    is_mobproxy?: boolean;
+    /**
+     * Detail for `is_vpn`. Empty when `is_vpn` is false. Starter and above.
+     *
+     */
+    vpn?: VpnDetail;
+    /**
+     * Detail for `is_hosting`. Empty when false. Scale and above.
+     */
+    hosting?: ClassDetail;
+    /**
+     * Detail for `is_relay`. Empty when false. Scale and above.
+     */
+    relay?: ClassDetail;
+    /**
+     * Detail for `is_tor`. Empty when false. Scale and above. The tor
+     * dataset carries no provider, so `provider` is always an empty string.
+     *
+     */
+    tor?: ClassDetail;
+    /**
+     * Detail for `is_cdn`. Empty when false. Scale and above.
+     */
+    cdn?: ClassDetail;
+    /**
+     * Detail for `is_resproxy`. Empty when false. Max only.
+     */
+    resproxy?: ProxyDetail;
+    /**
+     * Detail for `is_dcproxy`. Empty when false. Max only.
+     */
+    dcproxy?: ProxyDetail;
+    /**
+     * Detail for `is_mobproxy`. Empty when false. Max only.
+     */
+    mobproxy?: ProxyDetail;
+};
+/**
+ * What is known about the VPN attribution. Every key is present when the
+ * object is populated, empty values included; the object is `{}` when
+ * `is_vpn` is false. `confidence` and `method` are max only, so on a lower
+ * plan they are absent from a populated object rather than empty.
+ *
+ */
+export type VpnDetail = {
+    /**
+     * The VPN provider, or an empty string for an unattributed range.
+     */
+    provider?: string;
+    /**
+     * The most recent date this address was observed as VPN infrastructure.
+     */
+    last_seen?: string;
+    /**
+     * How strongly the attribution is supported. Max only.
+     */
+    confidence?: string;
+    /**
+     * How the address was attributed to the provider. Max only.
+     */
+    method?: string;
+};
+/**
+ * The shared detail shape for the hosting, relay, tor and cdn datasets.
+ * Every key is present when the object is populated; the object is `{}`
+ * when its flag is false.
+ *
+ */
+export type ClassDetail = {
+    /**
+     * The provider, or an empty string where the dataset has none.
+     */
+    provider?: string;
+    /**
+     * How strongly the classification is supported.
+     */
+    confidence?: string;
+    /**
+     * The most recent date this address was observed in this dataset.
+     */
+    last_seen?: string;
+};
+/**
+ * The shared detail shape for the residential, datacenter and mobile proxy
+ * families, measured over a rolling 90 day window. Every key is present
+ * when the object is populated; the object is `{}` when its flag is false.
+ *
+ */
+export type ProxyDetail = {
+    /**
+     * The proxy network, or an empty string where unattributed.
+     */
+    provider?: string;
+    /**
+     * The earliest date within the window this address was seen in the pool.
+     */
+    first_seen?: string;
+    /**
+     * The most recent date within the window this address was seen in the pool.
+     */
+    last_seen?: string;
+    /**
+     * How many times the address was observed in the pool during the window.
+     */
+    hits?: number;
+    /**
+     * The share of days in the window on which the address was seen, as a
+     * percentage. A high value means a stable pool member rather than a
+     * one-off sighting.
+     *
+     */
+    hits_days_pct?: number;
+    /**
+     * How many distinct proxy networks this address was seen in.
+     */
+    providers_num?: number;
+};
+/**
+ * Every non-2xx response carries this shape.
+ */
+export type LookupError = {
+    /**
+     * A human-readable explanation of the failure.
+     */
+    error: string;
+};
+export type Error = {
+    rc: string;
+};
+export type DatasetFormatSize = {
+    format: 'csvgz' | 'mmdb';
+    /**
+     * Size of the published file, or null when it has not been published yet
+     */
+    bytes: number | null;
+};
+export type LicensedDataset = {
+    id: string;
+    name: string;
+    summary?: string;
+    /**
+     * Licensed but no longer published. Talk to us.
+     */
+    retired?: boolean;
+    /**
+     * What your license permits you to do with the data
+     */
+    redistribution: 'evaluation' | 'internal' | 'redistribute';
+    starts?: string;
+    expires?: string | null;
+    /**
+     * False when the license has lapsed; downloads are refused
+     */
+    in_term: boolean;
+    formats: Array<DatasetFormatSize>;
+};
+export type Download = {
+    dataset_id: string;
+    format: string;
+    outcome: 'ok' | 'unauthorized' | 'denied' | 'expired' | 'unknown' | 'unavailable';
+    bytes?: number | null;
+    created: string;
+};
+export type DatasetMetadataColumn = {
+    name: string;
+    type: string;
+    description?: string;
+};
+export type DatasetMetadata = {
+    id: string;
+    /**
+     * How often a new build is published
+     */
+    update_freq?: string;
+    updated: string;
+    /**
+     * Row count in the current build
+     */
+    entries: number;
+    /**
+     * Columns, keyed by format
+     */
+    schema: {
+        [key: string]: Array<DatasetMetadataColumn>;
+    };
+    /**
+     * A few real rows, keyed by format
+     */
+    sample?: {
+        [key: string]: Array<{
+            [key: string]: unknown;
+        }>;
+    };
+    /**
+     * Bytes per format
+     */
+    size?: {
+        [key: string]: number;
+    };
+};
+export type LookupIpData = {
+    body?: never;
+    path: {
+        /**
+         * The IPv4 or IPv6 address to classify.
+         */
+        ip: string;
+    };
+    query?: never;
+    url: '/{ip}';
+};
+export type LookupIpErrors = {
+    /**
+     * The path segment is not a valid IP address.
+     */
+    400: LookupError;
+    /**
+     * The presented API key is unknown, revoked, or expired.
+     */
+    401: LookupError;
+    /**
+     * The key restricts which source addresses may use it, and this
+     * request did not come from one of them.
+     *
+     */
+    403: LookupError;
+    /**
+     * Either a transient rate limit or a spent allowance. `Retry-After` is
+     * present for the former and absent for the latter, and is the only
+     * way to tell them apart.
+     *
+     */
+    429: LookupError;
+    /**
+     * The VPN dataset could not be consulted.
+     */
+    500: LookupError;
+};
+export type LookupIpError = LookupIpErrors[keyof LookupIpErrors];
+export type LookupIpResponses = {
+    /**
+     * The classification. Present fields are those your plan includes; see
+     * the tier table in the API description.
+     *
+     */
+    200: LookupResponse;
+};
+export type LookupIpResponse = LookupIpResponses[keyof LookupIpResponses];
+export type ListDatabasesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v1/database/list';
+};
+export type ListDatabasesErrors = {
+    /**
+     * Missing or invalid key, or the key lacks the db.download scope
+     */
+    401: Error;
+};
+export type ListDatabasesError = ListDatabasesErrors[keyof ListDatabasesErrors];
+export type ListDatabasesResponses = {
+    /**
+     * OK
+     */
+    200: {
+        datasets: Array<LicensedDataset>;
+    };
+};
+export type ListDatabasesResponse = ListDatabasesResponses[keyof ListDatabasesResponses];
+export type DownloadDatabaseData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Dataset id, e.g. vpn_ip_extended_v1
+         */
+        id: string;
+        /**
+         * Not every dataset is built in every format. The `_provider`
+         * catalogues are keyed by provider id rather than by IP range, so no
+         * MMDB exists for them.
+         *
+         */
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v1/database/download';
+};
+export type DownloadDatabaseErrors = {
+    /**
+     * The dataset is not built in the requested format
+     */
+    400: Error;
+    /**
+     * Missing or invalid key, or the key lacks the db.download scope
+     */
+    401: Error;
+    /**
+     * Your organization holds no license for this dataset, or its term has ended
+     */
+    403: Error;
+    /**
+     * No such dataset
+     */
+    404: Error;
+    /**
+     * Licensed, but today's copy has not been published yet
+     */
+    503: Error;
+};
+export type DownloadDatabaseError = DownloadDatabaseErrors[keyof DownloadDatabaseErrors];
+export type DatabaseMetadataData = {
+    body?: never;
+    path?: never;
+    query: {
+        id: string;
+    };
+    url: '/api/v1/database/metadata';
+};
+export type DatabaseMetadataErrors = {
+    /**
+     * Missing or invalid key, or the key lacks the db.download scope
+     */
+    401: Error;
+    /**
+     * Your organization holds no license for this dataset, or its term has ended
+     */
+    403: Error;
+    /**
+     * No such dataset
+     */
+    404: Error;
+    /**
+     * Licensed, but today's copy has not been published yet
+     */
+    503: Error;
+};
+export type DatabaseMetadataError = DatabaseMetadataErrors[keyof DatabaseMetadataErrors];
+export type DatabaseMetadataResponses = {
+    /**
+     * OK
+     */
+    200: DatasetMetadata;
+};
+export type DatabaseMetadataResponse = DatabaseMetadataResponses[keyof DatabaseMetadataResponses];
+export type DatabaseChecksumData = {
+    body?: never;
+    path?: never;
+    query: {
+        id: string;
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v1/database/checksum';
+};
+export type DatabaseChecksumErrors = {
+    /**
+     * The dataset is not built in the requested format
+     */
+    400: Error;
+    /**
+     * Missing or invalid key, or the key lacks the db.download scope
+     */
+    401: Error;
+    /**
+     * Your organization holds no license for this dataset, or its term has ended
+     */
+    403: Error;
+    /**
+     * No such dataset
+     */
+    404: Error;
+    /**
+     * Licensed, but today's copy has not been published yet
+     */
+    503: Error;
+};
+export type DatabaseChecksumError = DatabaseChecksumErrors[keyof DatabaseChecksumErrors];
+export type DatabaseChecksumResponses = {
+    /**
+     * OK
+     */
+    200: {
+        id: string;
+        format: string;
+        checksums: {
+            md5?: string;
+            sha1?: string;
+            sha256?: string;
+            sha512?: string;
+        };
+    };
+};
+export type DatabaseChecksumResponse = DatabaseChecksumResponses[keyof DatabaseChecksumResponses];
+export type ListDownloadsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        limit?: number;
+    };
+    url: '/api/v1/database/downloads';
+};
+export type ListDownloadsErrors = {
+    /**
+     * Missing or invalid key, or the key lacks the db.download scope
+     */
+    401: Error;
+};
+export type ListDownloadsError = ListDownloadsErrors[keyof ListDownloadsErrors];
+export type ListDownloadsResponses = {
+    /**
+     * OK
+     */
+    200: {
+        downloads: Array<Download>;
+    };
+};
+export type ListDownloadsResponse = ListDownloadsResponses[keyof ListDownloadsResponses];

package/dist/generated/types.gen.js

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};
+//# sourceMappingURL=types.gen.js.map

package/dist/generated/types.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.gen.js","sourceRoot":"","sources":["../../src/generated/types.gen.ts"],"names":[],"mappings":"AAAA,qDAAqD"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { VPNDetection, DatabaseApi, DEFAULT_BASE_URL } from './client.js';
+export type { Options, CacheOptions, LookupOptions, BatchOptions } from './client.js';
+export { isBogon } from './bogon.js';
+export { VPNDetectionError } from './errors.js';
+export type { ErrorKind } from './errors.js';
+export type { Result, VpnDetail, ClassDetail, ProxyDetail, LookupResponse, } from './types.js';
+export type { LicensedDataset, DatasetMetadata, DatasetMetadataColumn, DatasetFormatSize, Download, } from './generated/types.gen.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { VPNDetection, DatabaseApi, DEFAULT_BASE_URL } from './client.js';
+export { isBogon } from './bogon.js';
+export { VPNDetectionError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { ClassDetail, LookupResponse, ProxyDetail, VpnDetail } from './generated/types.gen.js';
+export type { ClassDetail, ProxyDetail, VpnDetail, LookupResponse };
+/**
+ * What a lookup answers.
+ *
+ * An **optional** member is one your plan does not include. It never means "we
+ * could not check", so `undefined` and `false` are genuinely different answers:
+ * `undefined` is "not in your plan", `false` is "checked, and no". Use
+ * `?? false` when you only care whether the address is flagged.
+ *
+ * A detail object that is present but empty (`{}`) means the flag above it is
+ * false. A populated one always carries every one of its keys.
+ */
+export interface Result {
+    /** The address that was looked up, normalized. */
+    ip: string;
+    /** Whether the address is VPN infrastructure. Every plan includes this. */
+    isVpn: boolean;
+    /** Set when this answer was computed locally rather than served. */
+    isBogon: boolean;
+    isHosting?: boolean;
+    isRelay?: boolean;
+    isTor?: boolean;
+    isCdn?: boolean;
+    isResproxy?: boolean;
+    isDcproxy?: boolean;
+    isMobproxy?: boolean;
+    vpn?: VpnDetail;
+    hosting?: ClassDetail;
+    relay?: ClassDetail;
+    tor?: ClassDetail;
+    cdn?: ClassDetail;
+    resproxy?: ProxyDetail;
+    dcproxy?: ProxyDetail;
+    mobproxy?: ProxyDetail;
+    /** The response exactly as it came off the wire, with its original names. */
+    raw: LookupResponse;
+}
+export declare function toResult(body: LookupResponse): Result;

package/dist/types.js

@@ -0,0 +1,39 @@
+// The one place the wire's snake_case becomes idiomatic camelCase. Every
+// assignment is conditional on the key being PRESENT rather than truthy, so a
+// plan that includes a field and answers `false` keeps it, and a plan that does
+// not include it stays undefined.
+export function toResult(body) {
+    const r = {
+        ip: body.ip,
+        isVpn: body.is_vpn,
+        isBogon: false,
+        raw: body,
+    };
+    copyFlag(body, r, 'is_hosting', 'isHosting');
+    copyFlag(body, r, 'is_relay', 'isRelay');
+    copyFlag(body, r, 'is_tor', 'isTor');
+    copyFlag(body, r, 'is_cdn', 'isCdn');
+    copyFlag(body, r, 'is_resproxy', 'isResproxy');
+    copyFlag(body, r, 'is_dcproxy', 'isDcproxy');
+    copyFlag(body, r, 'is_mobproxy', 'isMobproxy');
+    copyDetail(body, r, 'vpn', 'vpn');
+    copyDetail(body, r, 'hosting', 'hosting');
+    copyDetail(body, r, 'relay', 'relay');
+    copyDetail(body, r, 'tor', 'tor');
+    copyDetail(body, r, 'cdn', 'cdn');
+    copyDetail(body, r, 'resproxy', 'resproxy');
+    copyDetail(body, r, 'dcproxy', 'dcproxy');
+    copyDetail(body, r, 'mobproxy', 'mobproxy');
+    return r;
+}
+function copyFlag(body, out, from, to) {
+    if (from in body && body[from] !== undefined) {
+        out[to] = body[from];
+    }
+}
+function copyDetail(body, out, from, to) {
+    if (from in body && body[from] !== undefined) {
+        out[to] = body[from];
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8CA,yEAAyE;AACzE,8EAA8E;AAC9E,gFAAgF;AAChF,kCAAkC;AAClC,MAAM,UAAU,QAAQ,CAAC,IAAoB;IACzC,MAAM,CAAC,GAAW;QACd,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,OAAO,EAAE,KAAK;QACd,GAAG,EAAE,IAAI;KACZ,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAClC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAC1C,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAClC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAClC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC5C,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAC1C,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC5C,OAAO,CAAC,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CACb,IAAoB,EAAE,GAAW,EACjC,IAA0B,EAAE,EACmB;IAE/C,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAY,CAAC;IACpC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CACf,IAAoB,EAAE,GAAW,EACjC,IAA0B,EAC1B,EAAqF;IAErF,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAU,CAAC;IAClC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "vpndetection",
+  "version": "1.0.0",
+  "description": "Official Node.js client library for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN IPs.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://vpndetection.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vpndetection-io/sdk-nodejs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vpndetection-io/sdk-nodejs/issues"
+  },
+  "keywords": [
+    "vpn",
+    "vpn-detection",
+    "proxy-detection",
+    "tor",
+    "ip-intelligence",
+    "ip-geolocation",
+    "fraud-prevention",
+    "residential-proxy",
+    "mobile-proxy",
+    "datacenter-proxy",
+    "hosting",
+    "cdn",
+    "relay"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "lru-cache": "^11.0.2",
+    "p-limit": "^6.2.0",
+    "p-retry": "^8.0.0"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && openapi-ts && tsc",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "generate": "openapi-ts"
+  }
+}