@internetdata/internetdata 1.0.0

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

@@ -0,0 +1,538 @@
+export type ClientOptions = {
+    baseUrl: 'https://internetdata.io' | (string & {});
+};
+export type Error = {
+    /**
+     * A machine-readable result code. Deliberately not an enum: a code
+     * added later must stay parseable by a client generated today.
+     *
+     */
+    rc: string;
+};
+/**
+ * One database FAMILY, with your organization's licence beside it. A
+ * licence covers the family, while a download names a specific version,
+ * so the ids passed to `download` and `checksum` come from `versions`.
+ *
+ */
+export type Database = {
+    /**
+     * The family, e.g. `vpn_ip`. What a licence is held against.
+     */
+    base: string;
+    name: string;
+    /**
+     * One line on what the newest version contains.
+     */
+    summary: string;
+    /**
+     * `licensed` is a live grant, `expired` one whose term has ended, and
+     * `unlicensed` a database published but never bought.
+     *
+     */
+    standing: 'licensed' | 'expired' | 'unlicensed';
+    /**
+     * What your licence permits you to do with the data. Null when there
+     * is no licence.
+     *
+     */
+    redistribution: 'evaluation' | 'internal' | 'redistribute' | null;
+    starts: string | null;
+    /**
+     * Null when the licence has no end date, or when there is none.
+     */
+    expires: string | null;
+    /**
+     * Every published version of this family, oldest first. Old versions
+     * are frozen rather than migrated, so both stay downloadable.
+     *
+     */
+    versions: Array<DatabaseVersion>;
+};
+export type DatabaseVersion = {
+    /**
+     * The versioned id. Pass this to `download`, `checksum` and `metadata`.
+     */
+    id: string;
+    version: number;
+    summary: string;
+    /**
+     * The formats this version is BUILT in. Asking for another is a 400,
+     * not a gap - the `_provider` catalogs are keyed by provider id, so no
+     * MMDB exists for them.
+     *
+     */
+    formats: Array<'csvgz' | 'mmdb'>;
+};
+/**
+ * One download ATTEMPT, refusals included.
+ */
+export type Download = {
+    dataset_id: string;
+    format: string;
+    outcome: 'ok' | 'unauthorized' | 'denied' | 'expired' | 'unknown' | 'unavailable';
+    /**
+     * Object size at redirect time, NOT bytes delivered: the transfer is a
+     * presigned redirect straight to object storage, so we never observe
+     * how much of it was taken.
+     *
+     */
+    bytes: number | null;
+    http_status: number | null;
+    /**
+     * The key that made the request. Null when it could not be resolved.
+     */
+    apikey_id: string | null;
+    client_ip: string | null;
+    user_agent: string | null;
+    created: string;
+};
+export type DatabaseMetadataColumn = {
+    name: string;
+    type: string;
+    description?: string;
+};
+/**
+ * The build document written by the exporter, served through unchanged.
+ */
+export type DatabaseMetadata = {
+    id: string;
+    /**
+     * How often a new build is published.
+     */
+    update_freq?: string;
+    /**
+     * ISO-8601 date (YYYY-MM-DD) the published build was generated on.
+     */
+    updated: string;
+    /**
+     * Row count in the current build.
+     */
+    entries: number;
+    /**
+     * Columns, keyed by format.
+     */
+    schema: {
+        [key: string]: Array<DatabaseMetadataColumn>;
+    };
+    /**
+     * A few real rows, keyed by format.
+     */
+    sample?: {
+        [key: string]: Array<{
+            [key: string]: unknown;
+        }>;
+    };
+    /**
+     * Bytes per format.
+     */
+    size: {
+        [key: string]: number;
+    };
+};
+export type DbChecksumSuccessResponse = {
+    rc: 'SUCCESS';
+    data: DbChecksums;
+};
+export type DbChecksums = {
+    /**
+     * Hex-encoded MD5 digest.
+     */
+    md5: string;
+    /**
+     * Hex-encoded SHA-1 digest.
+     */
+    sha1: string;
+    /**
+     * Hex-encoded SHA-256 digest.
+     */
+    sha256: string;
+    /**
+     * Hex-encoded SHA-512 digest.
+     */
+    sha512: string;
+};
+export type DbMetadataSuccessResponse = {
+    rc: 'SUCCESS';
+    data: DbMetadata;
+};
+export type DbMetadata = {
+    /**
+     * ISO-8601 calendar date (YYYY-MM-DD) on which the currently published version was generated.
+     */
+    updated: string;
+    /**
+     * Number of data rows in the published dataset (excluding the CSV header).
+     */
+    entries: number;
+    /**
+     * Sizes in bytes of the published files, keyed by format.
+     */
+    size: {
+        /**
+         * Size of the gzipped CSV file in bytes.
+         */
+        csvgz: number;
+        /**
+         * Size of the MMDB file in bytes (omitted when the dataset has no MMDB output).
+         */
+        mmdb?: number;
+    };
+};
+export type DbInvalidApiKeyError = {
+    rc: 'INVALID_APIKEY';
+};
+export type DbInvalidFormatError = {
+    rc: 'INVALID_FORMAT';
+};
+export type DbInvalidIdError = {
+    rc: 'INVALID_ID';
+};
+export type DbUnauthorizedIdError = {
+    rc: 'UNAUTHORIZED_ID';
+};
+export type DbNotFoundError = {
+    rc: 'DB_NOT_FOUND';
+};
+/**
+ * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+ */
+export type DbId = string;
+/**
+ * Database file format.
+ */
+export type DbFormat = 'csvgz' | 'mmdb';
+export type ListDatabasesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v2/database/list';
+};
+export type ListDatabasesErrors = {
+    /**
+     * Missing or invalid bearer key, the key lacks the `db.download` scope, or
+     * it belongs to no organization.
+     * `rc`: `UNAUTHORIZED`.
+     *
+     */
+    401: Error;
+};
+export type ListDatabasesError = ListDatabasesErrors[keyof ListDatabasesErrors];
+export type ListDatabasesResponses = {
+    /**
+     * OK
+     */
+    200: {
+        databases: Array<Database>;
+    };
+};
+export type ListDatabasesResponse = ListDatabasesResponses[keyof ListDatabasesResponses];
+export type DownloadDatabaseV2Data = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+        /**
+         * Database file format.
+         */
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v2/database/download';
+};
+export type DownloadDatabaseV2Errors = {
+    /**
+     * The database is not built in the requested format.
+     */
+    400: Error;
+    /**
+     * Missing or invalid bearer key, the key lacks the `db.download` scope, or
+     * it belongs to no organization.
+     * `rc`: `UNAUTHORIZED`.
+     *
+     */
+    401: Error;
+    /**
+     * Your organization holds no licence for this database, or its term has
+     * ended.
+     * `rc`: `NOT_LICENSED`, `LICENSE_EXPIRED`.
+     *
+     */
+    403: Error;
+    /**
+     * No such database.
+     * `rc`: `UNKNOWN_DATASET`.
+     *
+     */
+    404: Error;
+    /**
+     * Licensed, but the current build has not been published yet.
+     * `rc`: `NOT_AVAILABLE`.
+     *
+     */
+    503: Error;
+};
+export type DownloadDatabaseV2Error = DownloadDatabaseV2Errors[keyof DownloadDatabaseV2Errors];
+export type DatabaseMetadataV2Data = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+    };
+    url: '/api/v2/database/metadata';
+};
+export type DatabaseMetadataV2Errors = {
+    /**
+     * Missing or invalid bearer key, the key lacks the `db.download` scope, or
+     * it belongs to no organization.
+     * `rc`: `UNAUTHORIZED`.
+     *
+     */
+    401: Error;
+    /**
+     * Your organization holds no licence for this database, or its term has
+     * ended.
+     * `rc`: `NOT_LICENSED`, `LICENSE_EXPIRED`.
+     *
+     */
+    403: Error;
+    /**
+     * No such database.
+     * `rc`: `UNKNOWN_DATASET`.
+     *
+     */
+    404: Error;
+    /**
+     * Licensed, but the current build has not been published yet.
+     * `rc`: `NOT_AVAILABLE`.
+     *
+     */
+    503: Error;
+};
+export type DatabaseMetadataV2Error = DatabaseMetadataV2Errors[keyof DatabaseMetadataV2Errors];
+export type DatabaseMetadataV2Responses = {
+    /**
+     * OK
+     */
+    200: DatabaseMetadata;
+};
+export type DatabaseMetadataV2Response = DatabaseMetadataV2Responses[keyof DatabaseMetadataV2Responses];
+export type DatabaseChecksumV2Data = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+        /**
+         * Database file format.
+         */
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v2/database/checksum';
+};
+export type DatabaseChecksumV2Errors = {
+    /**
+     * The database is not built in the requested format.
+     */
+    400: Error;
+    /**
+     * Missing or invalid bearer key, the key lacks the `db.download` scope, or
+     * it belongs to no organization.
+     * `rc`: `UNAUTHORIZED`.
+     *
+     */
+    401: Error;
+    /**
+     * Your organization holds no licence for this database, or its term has
+     * ended.
+     * `rc`: `NOT_LICENSED`, `LICENSE_EXPIRED`.
+     *
+     */
+    403: Error;
+    /**
+     * No such database.
+     * `rc`: `UNKNOWN_DATASET`.
+     *
+     */
+    404: Error;
+    /**
+     * Licensed, but the current build has not been published yet.
+     * `rc`: `NOT_AVAILABLE`.
+     *
+     */
+    503: Error;
+};
+export type DatabaseChecksumV2Error = DatabaseChecksumV2Errors[keyof DatabaseChecksumV2Errors];
+export type DatabaseChecksumV2Responses = {
+    /**
+     * OK
+     */
+    200: {
+        id: string;
+        format: 'csvgz' | 'mmdb';
+        checksums: DbChecksums;
+    };
+};
+export type DatabaseChecksumV2Response = DatabaseChecksumV2Responses[keyof DatabaseChecksumV2Responses];
+export type ListDownloadsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * How many attempts to return. Clamped to 200.
+         */
+        limit?: number;
+    };
+    url: '/api/v2/database/downloads';
+};
+export type ListDownloadsErrors = {
+    /**
+     * Missing or invalid bearer key, the key lacks the `db.download` scope, or
+     * it belongs to no organization.
+     * `rc`: `UNAUTHORIZED`.
+     *
+     */
+    401: Error;
+};
+export type ListDownloadsError = ListDownloadsErrors[keyof ListDownloadsErrors];
+export type ListDownloadsResponses = {
+    /**
+     * OK
+     */
+    200: {
+        downloads: Array<Download>;
+    };
+};
+export type ListDownloadsResponse = ListDownloadsResponses[keyof ListDownloadsResponses];
+export type DatabaseDownloadData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+        /**
+         * Database file format.
+         */
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v1/database/download';
+};
+export type DatabaseDownloadErrors = {
+    /**
+     * The request query parameters were malformed.
+     * Possible `rc` values: `INVALID_FORMAT`, `INVALID_ID`.
+     *
+     */
+    400: DbInvalidFormatError | DbInvalidIdError;
+    /**
+     * The `apikey` query parameter was missing or not recognized.
+     */
+    401: DbInvalidApiKeyError;
+    /**
+     * The `apikey` is valid but is not authorized for the requested database id.
+     */
+    403: DbUnauthorizedIdError;
+    /**
+     * The requested database file does not exist on the server.
+     */
+    404: DbNotFoundError;
+};
+export type DatabaseDownloadError = DatabaseDownloadErrors[keyof DatabaseDownloadErrors];
+export type DatabaseDownloadResponses = {
+    /**
+     * Database file.
+     */
+    200: Blob | File;
+};
+export type DatabaseDownloadResponse = DatabaseDownloadResponses[keyof DatabaseDownloadResponses];
+export type DatabaseChecksumData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+        /**
+         * Database file format.
+         */
+        format: 'csvgz' | 'mmdb';
+    };
+    url: '/api/v1/database/checksum';
+};
+export type DatabaseChecksumErrors = {
+    /**
+     * The request query parameters were malformed.
+     * Possible `rc` values: `INVALID_FORMAT`, `INVALID_ID`.
+     *
+     */
+    400: DbInvalidFormatError | DbInvalidIdError;
+    /**
+     * The `apikey` query parameter was missing or not recognized.
+     */
+    401: DbInvalidApiKeyError;
+    /**
+     * The `apikey` is valid but is not authorized for the requested database id.
+     */
+    403: DbUnauthorizedIdError;
+    /**
+     * The requested database file does not exist on the server.
+     */
+    404: DbNotFoundError;
+};
+export type DatabaseChecksumError = DatabaseChecksumErrors[keyof DatabaseChecksumErrors];
+export type DatabaseChecksumResponses = {
+    /**
+     * Checksums for the requested database.
+     */
+    200: DbChecksumSuccessResponse;
+};
+export type DatabaseChecksumResponse = DatabaseChecksumResponses[keyof DatabaseChecksumResponses];
+export type DatabaseMetadataData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
+         */
+        id: string;
+    };
+    url: '/api/v1/database/metadata';
+};
+export type DatabaseMetadataErrors = {
+    /**
+     * The request query parameters were malformed.
+     * Possible `rc` values: `INVALID_FORMAT`, `INVALID_ID`.
+     *
+     */
+    400: DbInvalidFormatError | DbInvalidIdError;
+    /**
+     * The `apikey` query parameter was missing or not recognized.
+     */
+    401: DbInvalidApiKeyError;
+    /**
+     * The `apikey` is valid but is not authorized for the requested database id.
+     */
+    403: DbUnauthorizedIdError;
+    /**
+     * The requested database file does not exist on the server.
+     */
+    404: DbNotFoundError;
+};
+export type DatabaseMetadataError = DatabaseMetadataErrors[keyof DatabaseMetadataErrors];
+export type DatabaseMetadataResponses = {
+    /**
+     * Metadata for the requested database.
+     */
+    200: DbMetadataSuccessResponse;
+};
+export type DatabaseMetadataResponse = DatabaseMetadataResponses[keyof DatabaseMetadataResponses];

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,6 @@
+export { InternetData, DatabaseApi, DEFAULT_BASE_URL } from './client.js';
+export type { DownloadDestination, DownloadsOptions, Options } from './client.js';
+export { InternetDataError } from './errors.js';
+export type { ErrorKind } from './errors.js';
+export { DATASET_FORMATS, REDISTRIBUTION_RIGHTS, STANDINGS } from './types.js';
+export type { Database, DatabaseMetadata, DatabaseMetadataColumn, DatabaseVersion, DatasetFormat, DbChecksums, Download, Redistribution, Standing, } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { InternetData, DatabaseApi, DEFAULT_BASE_URL } from './client.js';
+export { InternetDataError } from './errors.js';
+export { DATASET_FORMATS, REDISTRIBUTION_RIGHTS, STANDINGS } from './types.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,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+import type { Database, DatabaseMetadata, DatabaseMetadataColumn, DatabaseVersion, DbChecksums, Download } from './generated/types.gen.js';
+export type { Database, DatabaseMetadata, DatabaseMetadataColumn, DatabaseVersion, DbChecksums, Download, };
+/** A file format one version of a database is built in. */
+export type DatasetFormat = DatabaseVersion['formats'][number];
+/** Where your organization's licence for a database family stands today. */
+export type Standing = Database['standing'];
+/** What a licence permits you to do with the data. Absent when there is no licence. */
+export type Redistribution = NonNullable<Database['redistribution']>;
+export declare const DATASET_FORMATS: readonly DatasetFormat[];
+export declare const STANDINGS: readonly Standing[];
+export declare const REDISTRIBUTION_RIGHTS: readonly Redistribution[];

package/dist/types.js

@@ -0,0 +1,10 @@
+// The runtime halves of the three closed vocabularies above, for a caller that
+// wants to validate or enumerate rather than switch. Each is TYPED by the
+// generated union, so a value the spec does not define will not compile; that a
+// value is MISSING is what the shared conformance corpus pins.
+export const DATASET_FORMATS = ['csvgz', 'mmdb'];
+export const STANDINGS = ['licensed', 'expired', 'unlicensed'];
+export const REDISTRIBUTION_RIGHTS = [
+    'evaluation', 'internal', 'redistribute',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiBA,+EAA+E;AAC/E,0EAA0E;AAC1E,gFAAgF;AAChF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,SAAS,GAAwB,CAAC,UAAU,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAA8B;IAC5D,YAAY,EAAE,UAAU,EAAE,cAAc;CAC3C,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@internetdata/internetdata",
+  "version": "1.0.0",
+  "description": "Official Node.js client library for the InternetData API. Download, verify and inspect licensed IP database files.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://internetdata.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/internetdata/sdk-nodejs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/internetdata/sdk-nodejs/issues"
+  },
+  "keywords": [
+    "ip-database",
+    "ip-intelligence",
+    "ip-data",
+    "mmdb",
+    "maxmind-db",
+    "asn",
+    "bogon",
+    "vpn",
+    "proxy",
+    "hosting",
+    "dataset",
+    "download"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "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"
+  }
+}