@internetdata/internetdata 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,126 @@
+# [<img src="https://s3.internetdata.io/internetdata-public/brand/mark.svg" alt="InternetData" width="24"/>](https://internetdata.io/) InternetData Node.js Client Library
+
+[![npm](https://img.shields.io/npm/v/@internetdata/internetdata.svg)](https://www.npmjs.com/package/@internetdata/internetdata)
+[![license](https://img.shields.io/npm/l/@internetdata/internetdata.svg)](LICENSE)
+
+The official Node.js client library for the [InternetData](https://internetdata.io) API.
+
+InternetData publishes IP databases: VPN and proxy address space, hosting and CDN ranges, provider catalogs, bogons and more, as gzipped CSV and as MMDB. This library lists the databases your organization is licensed for, tells you what is inside one before you fetch it, downloads it, and verifies the bytes you got.
+
+## Getting Started
+
+```bash
+npm install @internetdata/internetdata
+```
+
+Requires Node.js 22 or newer. TypeScript types are included.
+
+## Usage
+
+Every call needs an API key carrying the `db.download` scope. Databases are licensed by contract rather than bought self-serve, so a key arrives with the licence; see the [API documentation](https://docs.internetdata.io/api) or write to [dev@internetdata.io](mailto:dev@internetdata.io).
+
+```js
+import { InternetData } from '@internetdata/internetdata';
+
+const client = new InternetData({ apiKey: process.env.INTERNETDATA_API_KEY });
+
+for (const db of await client.database.list()) {
+    console.log(db.base, db.standing, db.versions.map((v) => v.id).join(', '));
+}
+```
+
+`list()` returns one entry per database FAMILY, because a licence is held against the family while a download names a specific version. `standing` is `licensed` if the family is yours today, `expired` if the term has ended, and `unlicensed` if it is published but has never been bought. `versions` carries the ids you pass everywhere else, oldest first, and the formats each one is actually built in.
+
+**This listing is not the same for every key.** A database commissioned for a single customer is absent from the catalog for every other organization, rather than being listed as unlicensed. So the listing is only ever an answer about the key that asked, this library never caches one, and you should not carry an answer from one key over to another or treat it as the published catalog.
+
+### What is inside a database
+
+```js
+const meta = await client.database.metadata('vpn_ip_v1');
+
+console.log(meta.updated);        // '2026-09-04', the day this build was generated
+console.log(meta.entries);        // rows in the build
+console.log(meta.size.csvgz);     // bytes you are about to move
+console.log(meta.schema.csvgz);   // [{ name, type, description }, ...]
+console.log(meta.sample?.mmdb);   // a few real rows
+```
+
+Poll `updated` and `entries` to decide whether today's build is worth fetching; both are free of the transfer. `size` is also the honest way to budget a download before starting one.
+
+### Downloading
+
+`download` streams a file to a path and returns the number of bytes written. Nothing larger than a chunk is ever held in memory, whatever the database weighs:
+
+```js
+const written = await client.database.download('vpn_ip_v1', 'mmdb', './vpn_ip_v1.mmdb');
+console.log(`${written} bytes`);
+```
+
+The bytes go to a neighbouring `.part` file and the name only appears once the transfer completes, so an interruption cannot leave a truncated file that reads as a whole database. You can pass a writable stream instead of a path, in which case it stays yours to close and gets no such treatment.
+
+Or take the link and run the transfer yourself. The API answers a redirect to time-limited object storage, and that URL authorizes itself, so it can be handed to something holding no API key:
+
+```js
+const url = await client.database.downloadUrl('vpn_ip_v1', 'mmdb');
+```
+
+Or, for a small database, take the bytes directly:
+
+```js
+const bytes = await client.database.downloadBytes('bogon_ip_v1', 'csvgz');
+```
+
+`downloadBytes` holds the whole file in memory and the catalog spans seven orders of magnitude, from a few hundred bytes to over 5 GiB, so use `download` for anything you have not checked with `metadata` first.
+
+### Verifying what you got
+
+```js
+const sums = await client.database.checksums('vpn_ip_v1', 'mmdb');
+console.log(sums.sha256);   // also md5, sha1, sha512
+```
+
+### Download history
+
+Your organization's recent attempts, newest first, refusals included, because a denial is what answers "it stopped working" and its absence answers nothing:
+
+```js
+for (const d of await client.database.downloads({ limit: 20 })) {
+    console.log(d.created, d.dataset_id, d.format, d.outcome, d.http_status);
+}
+```
+
+### Errors
+
+Failures throw an `InternetDataError` carrying a `kind` and a `retryable` flag:
+
+```js
+import { InternetDataError } from '@internetdata/internetdata';
+
+try {
+    await client.database.download('vpn_ip_v1', 'mmdb', './vpn_ip_v1.mmdb');
+} catch (err) {
+    if (err instanceof InternetDataError) {
+        console.error(err.kind, err.status, err.retryable);
+    }
+}
+```
+
+`kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`. The message is the API's own result code, such as `NOT_LICENSED` or `LICENSE_EXPIRED`, which is usually the specific thing you want to read.
+
+Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a burst, so retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries the first for you and never the second.
+
+A failure part way through a transfer is rethrown as it arrived rather than wrapped: a reset socket and a full disk are different problems, and only one of them is ours.
+
+## Other Libraries
+
+There are official InternetData 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/internetdata for more.
+
+## About InternetData
+
+IP intelligence databases: VPN, proxy, hosting, CDN and relay address space, provider catalogs and network metadata, published as CSV and MMDB.
+
+[<img src="https://s3.internetdata.io/internetdata-public/brand/mark.svg" alt="InternetData" width="96"/>](https://internetdata.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,123 @@
+import type { Writable } from 'node:stream';
+import type { Client } from './generated/client/index.js';
+import type { Database, DatabaseMetadata, DatasetFormat, DbChecksums, Download } from './types.js';
+/**
+ * Where `download` puts the bytes: a path to write, or a stream you opened
+ * yourself and will close yourself.
+ */
+export type DownloadDestination = string | Writable;
+export declare const DEFAULT_BASE_URL = "https://internetdata.io";
+export interface DownloadsOptions {
+    /** How many attempts to return, newest first. The API clamps this to 200. */
+    limit?: number;
+}
+export interface Options {
+    /**
+     * Your API key, carrying the `db.download` scope. Omit it to send no
+     * `Authorization` header at all, which is what a dataset offered without a
+     * licence would be read with.
+     */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Retry attempts for a transient failure. Default 2. */
+    retries?: number;
+    /** Override the HTTP implementation, mostly for tests. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * A client for the InternetData API.
+ *
+ * Everything the API answers is scoped to the organization the key belongs to,
+ * including which databases are listed at all, so one client speaks for exactly
+ * one organization and nothing it learns may be reused for another key.
+ *
+ * The key is optional, and an absent one sends no `Authorization` header rather
+ * than an empty one. Every endpoint published today is licensed, so a keyless
+ * client is answered `401` for now; it exists because what the API serves
+ * without a licence is a product decision, not the client's to refuse.
+ */
+export declare class InternetData {
+    /** The database catalog, downloads and their history. */
+    readonly database: DatabaseApi;
+    constructor(options?: Options);
+}
+/** The licensed database downloads. Access is granted by contract, not self-serve. */
+export declare class DatabaseApi {
+    private readonly client;
+    private readonly retries;
+    private readonly fetchImpl;
+    constructor(client: Client, retries: number, fetchImpl: typeof globalThis.fetch);
+    /**
+     * The published catalog as your organization may see it, one entry per
+     * database FAMILY, with `standing` saying where your licence stands.
+     *
+     * **This listing is not the same for everyone, and it is not cached.** A
+     * database commissioned for a single customer is absent for every other
+     * organization rather than listed as unlicensed, so the answer is only ever
+     * the one this key's organization is entitled to see. Ask again rather than
+     * holding on to it, and never carry one key's answer over to another.
+     */
+    list(): Promise<Database[]>;
+    /**
+     * What is inside one database: its columns per format, sample rows, the row
+     * count, the byte size of each file, and the day it was last built.
+     *
+     * The cheap way to decide whether today's build is worth fetching, and the
+     * only way to know what a transfer will cost before starting it.
+     */
+    metadata(id: string): Promise<DatabaseMetadata>;
+    /**
+     * The digests for one database file.
+     *
+     * Returns the whole set rather than one algorithm: which digests a database
+     * publishes is the API's choice, not ours.
+     */
+    checksums(id: string, format: DatasetFormat): Promise<DbChecksums>;
+    /**
+     * Your organization's recent download attempts, newest first.
+     *
+     * Refusals are listed too: a denial is what answers "it stopped working",
+     * and its absence answers nothing.
+     */
+    downloads(options?: DownloadsOptions): Promise<Download[]>;
+    /**
+     * The time-limited URL for one database 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 runs to
+     * gigabytes; it carries its own authorization, so it can be handed to
+     * something that holds no API key. The link authorizes the START of a
+     * transfer, so one already running is not interrupted when it lapses.
+     */
+    downloadUrl(id: string, format: DatasetFormat): Promise<string>;
+    /**
+     * Download one database file, streaming it to `destination`.
+     *
+     * `destination` is either a path or a writable stream you opened yourself.
+     * A path is written through a neighboring `.part` file and renamed on
+     * completion, so a transfer that dies half way leaves no truncated file
+     * that reads as a whole database; a stream you pass is written as-is and
+     * stays yours to close. Nothing is ever held in memory beyond a single
+     * chunk, whatever the file weighs.
+     *
+     * Returns the number of bytes written.
+     *
+     * A failure DURING the transfer surfaces as the underlying error rather
+     * than an `InternetDataError`: a reset socket and a full disk are different
+     * problems and only one of them is ours.
+     */
+    download(id: string, format: DatasetFormat, destination: DownloadDestination): Promise<number>;
+    /**
+     * Download one database file and hand back its bytes.
+     *
+     * **This holds the entire file in memory**, and the catalog spans seven
+     * orders of magnitude: the smallest published build is a few hundred bytes,
+     * which is nothing, while the largest is over 5 GiB, which will cost you
+     * that much resident memory in one allocation and can fail outright. Reach
+     * for this at the small end, where the bytes are going straight into a
+     * parser; use `download` for anything you have not measured, and `metadata`
+     * to measure it before you do.
+     */
+    downloadBytes(id: string, format: DatasetFormat): Promise<Uint8Array>;
+    private fetchDatabaseFile;
+}

package/dist/client.js

@@ -0,0 +1,253 @@
+import pRetry from 'p-retry';
+import { createClient, createConfig } from './generated/client/index.js';
+import { databaseChecksumV2, databaseMetadataV2, downloadDatabaseV2 as downloadRedirect, listDatabases, listDownloads, } from './generated/sdk.gen.js';
+import { errorFromResponse, InternetDataError, messageFromBody } from './errors.js';
+export const DEFAULT_BASE_URL = 'https://internetdata.io';
+/**
+ * A client for the InternetData API.
+ *
+ * Everything the API answers is scoped to the organization the key belongs to,
+ * including which databases are listed at all, so one client speaks for exactly
+ * one organization and nothing it learns may be reused for another key.
+ *
+ * The key is optional, and an absent one sends no `Authorization` header rather
+ * than an empty one. Every endpoint published today is licensed, so a keyless
+ * client is answered `401` for now; it exists because what the API serves
+ * without a licence is a product decision, not the client's to refuse.
+ */
+export class InternetData {
+    /** The database catalog, downloads and their history. */
+    database;
+    constructor(options = {}) {
+        // Resolved once, because the download path calls object storage
+        // directly rather than through the generated client and has to reach
+        // the same implementation a test substituted.
+        const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const client = createClient(createConfig({
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            ...(options.apiKey === undefined ? {} : { auth: () => options.apiKey }),
+            fetch: fetchImpl,
+        }));
+        this.database = new DatabaseApi(client, options.retries ?? 2, fetchImpl);
+    }
+}
+/** The licensed database downloads. Access is granted by contract, not self-serve. */
+export class DatabaseApi {
+    client;
+    retries;
+    fetchImpl;
+    constructor(client, retries, fetchImpl) {
+        this.client = client;
+        this.retries = retries;
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * The published catalog as your organization may see it, one entry per
+     * database FAMILY, with `standing` saying where your licence stands.
+     *
+     * **This listing is not the same for everyone, and it is not cached.** A
+     * database commissioned for a single customer is absent for every other
+     * organization rather than listed as unlicensed, so the answer is only ever
+     * the one this key's organization is entitled to see. Ask again rather than
+     * holding on to it, and never carry one key's answer over to another.
+     */
+    async list() {
+        return withRetry(this.retries, async () => {
+            const res = await listDatabases({ client: this.client });
+            return unwrap(res).databases;
+        });
+    }
+    /**
+     * What is inside one database: its columns per format, sample rows, the row
+     * count, the byte size of each file, and the day it was last built.
+     *
+     * The cheap way to decide whether today's build is worth fetching, and the
+     * only way to know what a transfer will cost before starting it.
+     */
+    async metadata(id) {
+        return withRetry(this.retries, async () => {
+            const res = await databaseMetadataV2({ client: this.client, query: { id: id } });
+            return unwrap(res);
+        });
+    }
+    /**
+     * The digests for one database file.
+     *
+     * Returns the whole set rather than one algorithm: which digests a database
+     * publishes is the API's choice, not ours.
+     */
+    async checksums(id, format) {
+        return withRetry(this.retries, async () => {
+            const res = await databaseChecksumV2({
+                client: this.client, query: { id: id, format: format },
+            });
+            return unwrap(res).checksums;
+        });
+    }
+    /**
+     * Your organization's recent download attempts, newest first.
+     *
+     * Refusals are listed too: a denial is what answers "it stopped working",
+     * and its absence answers nothing.
+     */
+    async downloads(options = {}) {
+        return withRetry(this.retries, async () => {
+            const res = await listDownloads({
+                client: this.client,
+                ...(options.limit === undefined ? {} : { query: { limit: options.limit } }),
+            });
+            return unwrap(res).downloads;
+        });
+    }
+    /**
+     * The time-limited URL for one database 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 runs to
+     * gigabytes; it carries its own authorization, so it can be handed to
+     * something that holds no API key. The link authorizes the START of a
+     * transfer, so one already running is not interrupted when it lapses.
+     */
+    async downloadUrl(id, format) {
+        return withRetry(this.retries, async () => {
+            const res = await downloadRedirect({
+                client: this.client,
+                query: { id: id, format: format },
+                redirect: 'manual',
+            });
+            if (res.response === undefined) {
+                throw new InternetDataError('network', 'no response from the API');
+            }
+            const location = res.response.headers.get('location');
+            if (res.response.status === 302 && location !== null) {
+                return location;
+            }
+            unwrap(res);
+            throw new InternetDataError('server_error', 'expected a redirect to object storage', res.response.status);
+        });
+    }
+    /**
+     * Download one database file, streaming it to `destination`.
+     *
+     * `destination` is either a path or a writable stream you opened yourself.
+     * A path is written through a neighboring `.part` file and renamed on
+     * completion, so a transfer that dies half way leaves no truncated file
+     * that reads as a whole database; a stream you pass is written as-is and
+     * stays yours to close. Nothing is ever held in memory beyond a single
+     * chunk, whatever the file weighs.
+     *
+     * Returns the number of bytes written.
+     *
+     * A failure DURING the transfer surfaces as the underlying error rather
+     * than an `InternetDataError`: a reset socket and a full disk are different
+     * problems and only one of them is ours.
+     */
+    async download(id, format, destination) {
+        const res = await this.fetchDatabaseFile(id, format);
+        if (res.body === null) {
+            throw new InternetDataError('server_error', 'object storage answered with no body', res.status);
+        }
+        const { Readable } = await import('node:stream');
+        const { pipeline } = await import('node:stream/promises');
+        // `node:stream/web` and the DOM lib declare the same runtime object as
+        // two unrelated types, so `fromWeb` needs it restated.
+        const source = Readable.fromWeb(res.body);
+        let bytes = 0;
+        async function* counted() {
+            for await (const chunk of source) {
+                bytes += chunk.length;
+                yield chunk;
+            }
+        }
+        if (typeof destination !== 'string') {
+            await pipeline(counted(), destination);
+            return bytes;
+        }
+        const { createWriteStream } = await import('node:fs');
+        const { rename, unlink } = await import('node:fs/promises');
+        const partial = `${destination}.part`;
+        try {
+            await pipeline(counted(), createWriteStream(partial));
+        }
+        catch (err) {
+            await unlink(partial).catch(() => { });
+            throw err;
+        }
+        await rename(partial, destination);
+        return bytes;
+    }
+    /**
+     * Download one database file and hand back its bytes.
+     *
+     * **This holds the entire file in memory**, and the catalog spans seven
+     * orders of magnitude: the smallest published build is a few hundred bytes,
+     * which is nothing, while the largest is over 5 GiB, which will cost you
+     * that much resident memory in one allocation and can fail outright. Reach
+     * for this at the small end, where the bytes are going straight into a
+     * parser; use `download` for anything you have not measured, and `metadata`
+     * to measure it before you do.
+     */
+    async downloadBytes(id, format) {
+        const res = await this.fetchDatabaseFile(id, format);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    // Follows the 302 as a SECOND, unauthenticated request: the presigned URL
+    // carries its own authorization, so forwarding the API key would hand a
+    // credential to a host that has no business holding it.
+    async fetchDatabaseFile(id, format) {
+        const url = await this.downloadUrl(id, format);
+        return withRetry(this.retries, async () => {
+            const res = await this.fetchImpl(url);
+            if (!res.ok) {
+                // Left unread: the status is what separates a lapsed link from
+                // a refused one, and the body is not bounded by anything.
+                void res.body?.cancel();
+                throw errorFromResponse(res.status, res.headers, `object storage refused the download link with status ${res.status}`);
+            }
+            return res;
+        });
+    }
+}
+function unwrap(res) {
+    if (res.response === undefined) {
+        throw new InternetDataError('network', 'no response from the API');
+    }
+    if (!res.response.ok) {
+        throw errorFromResponse(res.response.status, res.response.headers, messageFromBody(res.error ?? res.data));
+    }
+    return res.data;
+}
+// p-retry owns the backoff schedule; the extra sleep here is what honors a
+// server-supplied Retry-After, which p-retry has no way to know about. A 429
+// carrying that header is the only 429 worth retrying, which is why the wait
+// and the retry decision both key off the same field.
+async function withRetry(retries, fn) {
+    try {
+        return await pRetry(fn, {
+            retries: retries,
+            shouldRetry: ({ error }) => !(error instanceof InternetDataError) || error.retryable,
+            onFailedAttempt: async ({ error }) => {
+                const seconds = error instanceof InternetDataError
+                    ? error.retryAfterSeconds
+                    : undefined;
+                if (seconds !== undefined && seconds > 0) {
+                    await new Promise((r) => setTimeout(r, seconds * 1000));
+                }
+            },
+        });
+    }
+    catch (err) {
+        throw asError(err);
+    }
+}
+function asError(err) {
+    if (err instanceof InternetDataError) {
+        return err;
+    }
+    const cause = err?.cause;
+    if (cause instanceof InternetDataError) {
+        return cause;
+    }
+    return new InternetDataError('network', err instanceof Error ? err.message : String(err));
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Why a request failed.
+ *
+ * `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are NOT the
+ * same thing. A rate limit is the API protecting itself and carries
+ * `Retry-After`; retrying works. A spent quota carries no such header and
+ * retrying will not help until the window rolls over or the limit is raised.
+ * The header is the only thing that distinguishes them.
+ */
+export type ErrorKind = 'bad_request' | 'unauthorized' | 'forbidden' | 'rate_limited' | 'quota_exceeded' | 'server_error' | 'network';
+export declare class InternetDataError extends Error {
+    readonly kind: ErrorKind;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+    constructor(kind: ErrorKind, message: string, status?: number, retryAfterSeconds?: number);
+    /** Whether retrying this exact request could succeed. */
+    get retryable(): boolean;
+}
+export declare function errorFromResponse(status: number, headers: {
+    get(name: string): string | null;
+}, message?: string): InternetDataError;
+/**
+ * The `rc` an error envelope carries.
+ *
+ * Deliberately not an enum, in the spec or here: a code added later must stay
+ * readable to a client generated today, and the string IS the message a caller
+ * wants to see.
+ */
+export declare function messageFromBody(body: unknown): string | undefined;

package/dist/errors.js

@@ -0,0 +1,74 @@
+export class InternetDataError extends Error {
+    kind;
+    status;
+    retryAfterSeconds;
+    constructor(kind, message, status, retryAfterSeconds) {
+        super(message);
+        this.name = 'InternetDataError';
+        this.kind = kind;
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+    /** Whether retrying this exact request could succeed. */
+    get retryable() {
+        return this.kind === 'rate_limited' || this.kind === 'server_error' || this.kind === 'network';
+    }
+}
+export function errorFromResponse(status, headers, message) {
+    const text = message ?? `request failed with status ${status}`;
+    const retryAfter = parseRetryAfter(headers.get('retry-after'));
+    if (status === 429) {
+        // Present means transient, absent means an allowance is spent. Nothing
+        // else in the response separates the two.
+        return retryAfter === undefined
+            ? new InternetDataError('quota_exceeded', text, status)
+            : new InternetDataError('rate_limited', text, status, retryAfter);
+    }
+    if (status === 400) {
+        return new InternetDataError('bad_request', text, status);
+    }
+    if (status === 401) {
+        return new InternetDataError('unauthorized', text, status);
+    }
+    if (status === 403) {
+        return new InternetDataError('forbidden', text, status);
+    }
+    // Any other 4xx is a CLIENT error. Falling through to the server_error
+    // default would make it retryable, so a misspelled dataset id (404
+    // UNKNOWN_DATASET) would be retried twice before failing. Only 5xx and
+    // transport failures are worth a retry.
+    if (status < 500) {
+        return new InternetDataError('bad_request', text, status);
+    }
+    return new InternetDataError('server_error', text, status);
+}
+/**
+ * The `rc` an error envelope carries.
+ *
+ * Deliberately not an enum, in the spec or here: a code added later must stay
+ * readable to a client generated today, and the string IS the message a caller
+ * wants to see.
+ */
+export function messageFromBody(body) {
+    if (typeof body !== 'object' || body === null) {
+        return undefined;
+    }
+    const rc = body['rc'];
+    return typeof rc === 'string' ? rc : undefined;
+}
+function parseRetryAfter(value) {
+    if (value === null || value.trim() === '') {
+        return undefined;
+    }
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds;
+    }
+    // The header also permits an HTTP date.
+    const when = Date.parse(value);
+    if (Number.isNaN(when)) {
+        return undefined;
+    }
+    return Math.max(0, Math.ceil((when - Date.now()) / 1000));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

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

@@ -0,0 +1,2 @@
+import type { Client, Config } from './types.gen.js';
+export declare const createClient: (config?: Config) => Client;