@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/dist/cli.js

@@ -1,268 +1,3 @@
 #!/usr/bin/env node
-import { parseArgs } from 'node:util';
-import { createRequire } from 'node:module';
-import { TestRailClient } from './client.js';
-// ── Version ───────────────────────────────────────────────────────────────────
-const require = createRequire(import.meta.url);
-const VERSION = require('../package.json').version;
-// ── Arg Parsing ───────────────────────────────────────────────────────────────
-const { values, positionals } = parseArgs({
-    args: process.argv.slice(2),
-    options: {
-        'base-url': { type: 'string' },
-        email: { type: 'string' },
-        'api-key': { type: 'string' },
-        format: { type: 'string', default: 'json' },
-        quiet: { type: 'boolean', default: false },
-        help: { type: 'boolean', default: false },
-        version: { type: 'boolean', default: false },
-        'project-id': { type: 'string' },
-        'suite-id': { type: 'string' },
-        'run-id': { type: 'string' },
-        'case-id': { type: 'string' },
-        limit: { type: 'string' },
-        offset: { type: 'string' },
-    },
-    allowPositionals: true,
-    strict: false,
-});
-// ── Output Helpers ────────────────────────────────────────────────────────────
-const quiet = values.quiet === true;
-const format = values.format ?? 'json';
-function out(data) {
-    if (quiet)
-        return;
-    if (format === 'table') {
-        process.stdout.write(`${renderTable(data)}\n`);
-    }
-    else {
-        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
-    }
-}
-function err(message) {
-    if (!quiet)
-        process.stderr.write(`Error: ${message}\n`);
-}
-function valueToString(v) {
-    if (v === null || v === undefined)
-        return '';
-    if (typeof v === 'object')
-        return JSON.stringify(v);
-    if (typeof v === 'string')
-        return v;
-    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint')
-        return String(v);
-    if (typeof v === 'symbol')
-        return v.toString();
-    return '[Function]';
-}
-function renderTable(data) {
-    const rows = Array.isArray(data) ? data : [data];
-    if (rows.length === 0)
-        return '(empty)';
-    const first = rows[0];
-    if (typeof first !== 'object' || first === null) {
-        return rows.map(String).join('\n');
-    }
-    const keys = Object.keys(first);
-    const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => valueToString(r[k]).length)));
-    const line = widths.map((w) => '-'.repeat(w)).join('-+-');
-    const header = keys.map((k, i) => k.padEnd(widths[i] ?? k.length)).join(' | ');
-    const body = rows.map((r) => keys.map((k, i) => valueToString(r[k]).padEnd(widths[i] ?? k.length)).join(' | '));
-    return [header, line, ...body].join('\n');
-}
-// ── Help ──────────────────────────────────────────────────────────────────────
-const HELP = `
-testrail <resource> <action> [id] [options]
-
-Resources & actions:
-  project  get <id> | list [--limit N] [--offset N]
-  suite    get <id> | list --project-id <id>
-  case     get <id> | list --project-id <id> [--suite-id <id>]
-  run      get <id> | list --project-id <id> [--limit N] [--offset N]
-  result   list --run-id <id> [--limit N] [--offset N]
-  milestone  get <id> | list --project-id <id> [--limit N] [--offset N]
-  user     get <id> | list [--limit N] [--offset N]
-
-Auth (env var or flag):
-  TESTRAIL_BASE_URL / --base-url <url>
-  TESTRAIL_EMAIL    / --email <email>
-  TESTRAIL_API_KEY  / --api-key <key>
-
-Options:
-  --format json|table   Output format (default: json)
-  --quiet               Suppress output; use exit code 0/1
-  --help                Show this help
-  --version             Print version
-`.trim();
-// ── Entry Point ───────────────────────────────────────────────────────────────
-if (values.version === true) {
-    process.stdout.write(`testrail-cli v${VERSION}\n`);
-    process.exit(0);
-}
-if (values.help === true || positionals.length === 0) {
-    process.stdout.write(`${HELP}\n`);
-    process.exit(0);
-}
-const [resource, action, idArg] = positionals;
-if (resource === undefined || resource === '' || action === undefined || action === '') {
-    process.stderr.write('Usage: testrail <resource> <action> [id] [options]\nRun with --help for details.\n');
-    process.exit(1);
-}
-// ── Auth Resolution ───────────────────────────────────────────────────────────
-const baseUrl = values['base-url'] ?? process.env['TESTRAIL_BASE_URL'];
-const email = values['email'] ?? process.env['TESTRAIL_EMAIL'];
-const apiKey = values['api-key'] ?? process.env['TESTRAIL_API_KEY'];
-if (baseUrl === undefined ||
-    baseUrl === '' ||
-    email === undefined ||
-    email === '' ||
-    apiKey === undefined ||
-    apiKey === '') {
-    err('Missing auth. Set TESTRAIL_BASE_URL, TESTRAIL_EMAIL, TESTRAIL_API_KEY or use --base-url, --email, --api-key flags.');
-    process.exit(1);
-}
-const config = { baseUrl, email, apiKey };
-const client = new TestRailClient(config);
-// ── Numeric Helpers ───────────────────────────────────────────────────────────
-function parseId(raw, name) {
-    const n = Number(raw);
-    if (raw === undefined || raw === '' || !Number.isInteger(n) || n <= 0) {
-        err(`${name} must be a positive integer (got: ${raw ?? '(none)'})`);
-        process.exit(1);
-    }
-    return n;
-}
-function optInt(raw) {
-    if (raw === undefined)
-        return undefined;
-    const n = Number(raw);
-    return Number.isInteger(n) && n >= 0 ? n : undefined;
-}
-const suiteId = optInt(values['suite-id']);
-const limit = optInt(values.limit);
-const offset = optInt(values.offset);
-// ── Command Dispatch ──────────────────────────────────────────────────────────
-async function run(res, act) {
-    switch (res) {
-        case 'project': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'project id');
-                out(await client.getProject(id));
-            }
-            else if (act === 'list') {
-                out(await client.getProjects(limit, offset));
-            }
-            else {
-                err(`Unknown action '${act}' for project. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'suite': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'suite id');
-                out(await client.getSuite(id));
-            }
-            else if (act === 'list') {
-                const pid = parseId(values['project-id'], '--project-id');
-                out(await client.getSuites(pid));
-            }
-            else {
-                err(`Unknown action '${act}' for suite. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'case': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'case id');
-                out(await client.getCase(id));
-            }
-            else if (act === 'list') {
-                const pid = parseId(values['project-id'], '--project-id');
-                out(await client.getCases(pid, suiteId !== undefined ? { suiteId } : undefined));
-            }
-            else {
-                err(`Unknown action '${act}' for case. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'run': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'run id');
-                out(await client.getRun(id));
-            }
-            else if (act === 'list') {
-                const pid = parseId(values['project-id'], '--project-id');
-                out(await client.getRuns(pid, {
-                    ...(limit !== undefined && { limit }),
-                    ...(offset !== undefined && { offset }),
-                }));
-            }
-            else {
-                err(`Unknown action '${act}' for run. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'result': {
-            if (act === 'list') {
-                const rid = parseId(values['run-id'], '--run-id');
-                const resultOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
-                out(await client.getResultsForRun(rid, resultOpts));
-            }
-            else {
-                err(`Unknown action '${act}' for result. Use: list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'milestone': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'milestone id');
-                out(await client.getMilestone(id));
-            }
-            else if (act === 'list') {
-                const pid = parseId(values['project-id'], '--project-id');
-                const msOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
-                out(await client.getMilestones(pid, msOpts));
-            }
-            else {
-                err(`Unknown action '${act}' for milestone. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        case 'user': {
-            if (act === 'get') {
-                const id = parseId(idArg, 'user id');
-                out(await client.getUser(id));
-            }
-            else if (act === 'list') {
-                out(await client.getUsers(limit, offset));
-            }
-            else {
-                err(`Unknown action '${act}' for user. Use: get, list`);
-                process.exit(1);
-            }
-            break;
-        }
-        default: {
-            err(`Unknown resource '${res}'. Use: project, suite, case, run, result, milestone, user`);
-            process.exit(1);
-        }
-    }
-}
-run(resource, action)
-    .then(() => {
-    client.destroy();
-    process.exit(0);
-})
-    .catch((e) => {
-    err(e instanceof Error ? e.message : String(e));
-    client.destroy();
-    process.exit(1);
-});
+import './cli/index.js';
 //# sourceMappingURL=cli.js.map

package/dist/client-core.d.ts

@@ -1,4 +1,5 @@
 import type { TestRailConfig } from './types.js';
+import { type ZodType } from 'zod';
 /**
  * HTTP pipeline, caching, rate limiting, retry logic, and lifecycle management.
  * Extended by {@link TestRailClient} which adds all API endpoint methods.
@@ -16,6 +17,8 @@ export declare class TestRailClientCore {
     private cacheCleanupTimer;
     private readonly rateLimiter;
     private isDestroyed;
+    private readonly dnsValidationPromise;
+    private dnsValidationError;
     constructor(config: TestRailConfig);
     private validateConfig;
     private getRetryDelay;
@@ -32,24 +35,24 @@ export declare class TestRailClientCore {
      * Validates that an ID is a positive integer.
      * @throws {TestRailValidationError} When ID is invalid
      */
-    protected validateId(id: number, name: string): void;
+    validateId(id: number, name: string): void;
     /**
      * Validates that a string entry ID is non-empty.
      * @throws {TestRailValidationError} When entryId is not a non-empty string
      */
-    protected validateEntryId(entryId: string): void;
+    validateEntryId(entryId: string): void;
     /**
      * Validates optional pagination parameters.
      * @throws {TestRailValidationError} When limit is not a positive integer or offset is not a non-negative integer
      */
-    protected validatePaginationParams(limit?: number, offset?: number): void;
+    validatePaginationParams(limit?: number, offset?: number): void;
     /**
      * Builds a TestRail endpoint URL with optional query parameters.
      * Appends params using `&key=value` (TestRail URL quirk — uses `&`, not `?`).
      * Keys and values are automatically percent-encoded via `encodeURIComponent`.
      * Do NOT pre-encode values before passing them; doing so will cause double-encoding.
      */
-    protected buildEndpoint(base: string, params?: Record<string, string | number | undefined>): string;
+    buildEndpoint(base: string, params?: Record<string, string | number | undefined>): string;
     private getCachedData;
     private setCachedData;
     /**
@@ -77,7 +80,7 @@ export declare class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected request<T>(method: string, endpoint: string, data?: unknown, retryCount?: number, skipCache?: boolean): Promise<T>;
+    request<T>(method: string, endpoint: string, data?: unknown, retryCount?: number, skipCache?: boolean): Promise<T>;
     /**
      * Makes a multipart/form-data POST request to the TestRail API.
      * Used exclusively for file attachment uploads. Applies rate limiting
@@ -89,7 +92,7 @@ export declare class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected requestMultipart<T>(endpoint: string, file: globalThis.Blob | Uint8Array | globalThis.File, filename: string): Promise<T>;
+    requestMultipart<T>(endpoint: string, file: globalThis.Blob | Uint8Array | globalThis.File, filename: string): Promise<T>;
     /**
      * Makes a GET request to the TestRail API and returns the raw binary response.
      * Used for downloading attachment contents.
@@ -98,6 +101,12 @@ export declare class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected requestBinary(endpoint: string, retryCount?: number): Promise<ArrayBuffer>;
+    requestBinary(endpoint: string, retryCount?: number): Promise<ArrayBuffer>;
+    private awaitDnsValidation;
+    /**
+     * Validates `data` against `schema` and returns it typed as `T`.
+     * @throws {TestRailValidationError} When data does not conform to schema
+     */
+    parse<T>(schema: ZodType, data: unknown): T;
 }
 //# sourceMappingURL=client-core.d.ts.map

package/dist/client-core.js

@@ -1,15 +1,17 @@
 import { base64Encode, sleep } from './utils.js';
-import { TestRailApiError, TestRailValidationError } from './errors.js';
+import { TestRailApiError, TestRailValidationError, handleZodError } from './errors.js';
 import pkg from '../package.json' with { type: 'json' };
+import { isIP } from 'node:net';
+import { ZodError } from 'zod';
 const USER_AGENT = `${pkg.description}/${pkg.version}`;
-import { BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRIES, DEFAULT_CACHE_TTL_MS, DEFAULT_CACHE_CLEANUP_INTERVAL_MS, DEFAULT_MAX_CACHE_SIZE, DEFAULT_RATE_LIMIT_MAX_REQUESTS, DEFAULT_RATE_LIMIT_WINDOW_MS, } from './constants.js';
+import { BASE_RETRY_DELAY_MS, MAX_RETRY_DELAY_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRIES, DEFAULT_CACHE_TTL_MS, DEFAULT_CACHE_CLEANUP_INTERVAL_MS, DEFAULT_MAX_CACHE_SIZE, DEFAULT_RATE_LIMIT_MAX_REQUESTS, DEFAULT_RATE_LIMIT_WINDOW_MS, DEFAULT_DNS_VALIDATION_MAX_WAIT_MS, } from './constants.js';
 // Reject loopback, link-local, and private-range hosts to prevent SSRF.
 // All requests carry a full Authorization header, making the client a credentialed
 // probe for internal services when baseUrl is attacker-controlled.
-// NOTE: This check is purely syntactic (regex on the hostname string). It does NOT
-// resolve DNS, so a public-looking hostname that resolves to a private IP, or a
-// DNS-rebinding attack, can still bypass this protection. For full SSRF prevention
-// use a network-level egress filter or a proxy that validates resolved addresses.
+// Protection combines syntactic checks (regex on hostname string) with DNS resolution:
+// validatePublicHost() resolves the hostname and checks resulting IPs. A DNS validation
+// promise is awaited briefly before each request. This blocks obvious private-host
+// resolutions but does not fully eliminate rebinding after initial validation.
 const PRIVATE_HOST_PATTERNS = [
     /^localhost\.?$/i, // matches "localhost" with or without trailing dot
     /^127\./,
@@ -22,15 +24,74 @@ const PRIVATE_HOST_PATTERNS = [
     /^f[cd][0-9a-f]{2}:/i, // IPv6 unique-local (fc00::/7 covers fc** and fd**)
     /^0\./,
 ];
-function validatePublicHost(hostname) {
-    // Strip enclosing brackets from IPv6 literals (e.g. "[::1]" → "::1")
+function isPrivateOrLoopbackIPv4(ip) {
+    const octetParts = ip.split('.');
+    if (octetParts.length !== 4 || octetParts.some((part) => !/^\d+$/.test(part))) {
+        return false;
+    }
+    const octets = octetParts.map((part) => Number.parseInt(part, 10));
+    if (octets.some((part) => Number.isNaN(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [o0, o1] = octets;
+    return (o0 === 0 ||
+        o0 === 10 ||
+        o0 === 127 ||
+        (o0 === 169 && o1 === 254) ||
+        (o0 === 172 && o1 >= 16 && o1 <= 31) ||
+        (o0 === 192 && o1 === 168));
+}
+function isPrivateOrLoopbackIP(ip, family) {
+    const [normalized] = ip.toLowerCase().split('%');
+    // Handle IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1).
+    const mappedIPv4 = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    const mappedAddress = mappedIPv4?.[1];
+    if (mappedAddress !== undefined) {
+        return isPrivateOrLoopbackIPv4(mappedAddress);
+    }
+    const ipFamily = family ?? isIP(normalized);
+    if (ipFamily === 4) {
+        return isPrivateOrLoopbackIPv4(normalized);
+    }
+    if (ipFamily === 6) {
+        if (normalized === '::' || normalized === '::1') {
+            return true;
+        }
+        const [firstHextet] = normalized.split(':');
+        return (firstHextet.startsWith('fc') ||
+            firstHextet.startsWith('fd') ||
+            firstHextet.startsWith('fe8') ||
+            firstHextet.startsWith('fe9') ||
+            firstHextet.startsWith('fea') ||
+            firstHextet.startsWith('feb'));
+    }
+    return false;
+}
+async function validatePublicHost(hostname) {
     const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
-    for (const pattern of PRIVATE_HOST_PATTERNS) {
-        if (pattern.test(bare)) {
-            throw new TestRailValidationError(`baseUrl resolves to a private/loopback host ("${hostname}"). ` +
-                'Set allowPrivateHosts: true to allow on-premise deployments.');
+    const isPrivatePattern = PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(bare));
+    if (isPrivatePattern) {
+        throw new TestRailValidationError(`baseUrl resolves to a private/loopback host ("${hostname}"). ` +
+            'Set allowPrivateHosts: true to allow on-premise deployments.');
+    }
+    try {
+        const dns = await import('node:dns/promises');
+        const lookups = await dns.lookup(bare, { all: true }).catch(() => []);
+        for (const lookup of lookups) {
+            if (lookup.address !== '' && isPrivateOrLoopbackIP(lookup.address, lookup.family)) {
+                throw new TestRailValidationError(`baseUrl resolves to a private/loopback host ("${hostname}" -> "${lookup.address}"). ` +
+                    'Set allowPrivateHosts: true to allow on-premise deployments.');
+            }
         }
     }
+    catch (err) {
+        if (err instanceof TestRailValidationError)
+            throw err;
+        // DNS/import failures are ignored to avoid blocking valid public hosts
+        // when DNS is temporarily unavailable in constrained runtimes.
+        // eslint-disable-next-line no-console
+        console.warn(`Warning: DNS host validation skipped due to lookup error: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    }
 }
 const activeClients = new Set();
 let processHandlersRegistered = false;
@@ -76,6 +137,8 @@ export class TestRailClientCore {
     cacheCleanupTimer;
     rateLimiter;
     isDestroyed = false;
+    dnsValidationPromise;
+    dnsValidationError;
     constructor(config) {
         this.validateConfig(config);
         this.baseUrl = config.baseUrl.replace(/\/$/, '');
@@ -98,6 +161,21 @@ export class TestRailClientCore {
             windowMs: config.rateLimiter?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS,
             requests: [],
         };
+        // Start async DNS host validation in the background and await it in request().
+        // If DNS resolves to a private IP, mark this client so all requests fail.
+        // The synchronous regex check in validateConfig already blocks obvious private addresses.
+        if (config.allowPrivateHosts !== true) {
+            // URL already validated by validateConfig — this parse cannot throw.
+            const url = new URL(config.baseUrl);
+            this.dnsValidationPromise = validatePublicHost(url.hostname).catch((err) => {
+                if (err instanceof TestRailValidationError) {
+                    this.dnsValidationError = err;
+                }
+            });
+        }
+        else {
+            this.dnsValidationPromise = undefined;
+        }
         // Register this instance for automatic cleanup
         activeClients.add(this);
         registerProcessHandlers();
@@ -128,10 +206,16 @@ export class TestRailClientCore {
                 throw new TestRailValidationError('baseUrl must use HTTPS. HTTP sends credentials in cleartext. ' +
                     'Set allowInsecure: true only in isolated development environments.');
             }
-            // Block SSRF targets (loopback, link-local, private ranges) unless
-            // the caller explicitly opts in for on-premise/private-network deployments.
+            // Syntactic SSRF protection: reject obvious private hostnames synchronously.
+            // The async DNS check in validatePublicHost adds defence-in-depth for rebinding.
             if (config.allowPrivateHosts !== true) {
-                validatePublicHost(url.hostname);
+                const bare = url.hostname.startsWith('[') && url.hostname.endsWith(']')
+                    ? url.hostname.slice(1, -1)
+                    : url.hostname;
+                if (PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(bare))) {
+                    throw new TestRailValidationError(`baseUrl resolves to a private/loopback host ("${url.hostname}"). ` +
+                        'Set allowPrivateHosts: true to allow on-premise deployments.');
+                }
             }
         }
         catch (err) {
@@ -228,7 +312,10 @@ export class TestRailClientCore {
                 }
             }
             const waitTime = oldestRequest + this.rateLimiter.windowMs - now;
-            throw new TestRailApiError(`Rate limit exceeded. Please wait ${Math.ceil(waitTime / 1000)} seconds before making another request.`);
+            throw new TestRailApiError(429, 'Too Many Requests', {
+                message: `Rate limit exceeded. Please wait ${Math.ceil(waitTime / 1000)} seconds before making another request.`,
+                waitTimeMs: waitTime,
+            });
         }
         this.rateLimiter.requests.push(now);
     }
@@ -385,6 +472,7 @@ export class TestRailClientCore {
         if (this.isDestroyed) {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
+        await this.awaitDnsValidation();
         // Check cache for GET requests
         if (method === 'GET' && !skipCache) {
             const cacheKey = `${method}:${endpoint}`;
@@ -428,7 +516,7 @@ export class TestRailClientCore {
                 // or secret values. Keep it in the structured `response` field for
                 // programmatic inspection but do not embed it in the message string,
                 // which callers commonly pass to loggers.
-                throw new TestRailApiError(`TestRail API error: ${response.status} ${response.statusText}`, response.status, response.statusText, errorText);
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
             // Invalidate cache after mutating requests to avoid stale GET results.
             // Done before the empty-body check so empty responses (e.g. delete endpoints)
@@ -450,7 +538,7 @@ export class TestRailClientCore {
                 return result;
             }
             catch {
-                throw new TestRailApiError('Invalid JSON response from TestRail API');
+                throw new TestRailApiError(0, 'Invalid JSON response from TestRail API');
             }
         }
         catch (error) {
@@ -461,14 +549,14 @@ export class TestRailClientCore {
             const isAbortError = error.name === 'AbortError';
             // Don't retry timeout errors to avoid excessive wait times
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
             // Retry on network errors up to the maximum number of retries
             if (retryCount < this.maxRetries) {
                 await sleep(this.getRetryDelay(retryCount));
                 return this.request(method, endpoint, data, retryCount + 1, skipCache);
             }
-            throw new TestRailApiError(`Network error: ${error.message}`, undefined, undefined, error.message);
+            throw new TestRailApiError(0, `Network error: ${error.message}`, error.message);
         }
     }
     /**
@@ -486,6 +574,7 @@ export class TestRailClientCore {
         if (this.isDestroyed) {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
+        await this.awaitDnsValidation();
         this.checkRateLimit();
         const url = `${this.baseUrl}/index.php?/api/v2/${endpoint}`;
         const formData = new globalThis.FormData();
@@ -514,7 +603,7 @@ export class TestRailClientCore {
             clearTimeout(timeoutId);
             if (!response.ok) {
                 const errorText = await response.text().catch(() => 'Unknown error');
-                throw new TestRailApiError(`TestRail API error: ${response.status} ${response.statusText}`, response.status, response.statusText, errorText);
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
             // Invalidate cache after upload
             this.clearCache();
@@ -526,7 +615,7 @@ export class TestRailClientCore {
                 return JSON.parse(responseText);
             }
             catch {
-                throw new TestRailApiError('Invalid JSON response from TestRail API');
+                throw new TestRailApiError(0, 'Invalid JSON response from TestRail API');
             }
         }
         catch (error) {
@@ -536,9 +625,9 @@ export class TestRailClientCore {
             }
             const isAbortError = error.name === 'AbortError';
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
-            throw new TestRailApiError(`Network error: ${error.message}`, undefined, undefined, error.message);
+            throw new TestRailApiError(0, `Network error: ${error.message}`, error.message);
         }
     }
     /**
@@ -553,6 +642,7 @@ export class TestRailClientCore {
         if (this.isDestroyed) {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
+        await this.awaitDnsValidation();
         this.checkRateLimit();
         const url = `${this.baseUrl}/index.php?/api/v2/${endpoint}`;
         const controller = new AbortController();
@@ -577,7 +667,7 @@ export class TestRailClientCore {
                     await sleep(delay);
                     return this.requestBinary(endpoint, retryCount + 1);
                 }
-                throw new TestRailApiError(`TestRail API error: ${response.status} ${response.statusText}`, response.status, response.statusText, errorText);
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
             return response.arrayBuffer();
         }
@@ -588,13 +678,49 @@ export class TestRailClientCore {
             }
             const isAbortError = error.name === 'AbortError';
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
             if (retryCount < this.maxRetries) {
                 await sleep(this.getRetryDelay(retryCount));
                 return this.requestBinary(endpoint, retryCount + 1);
             }
-            throw new TestRailApiError(`Network error: ${error.message}`, undefined, undefined, error.message);
+            throw new TestRailApiError(0, `Network error: ${error.message}`, error.message);
+        }
+    }
+    async awaitDnsValidation() {
+        if (this.dnsValidationPromise !== undefined) {
+            let timeoutId;
+            try {
+                await Promise.race([
+                    this.dnsValidationPromise,
+                    new Promise((resolve) => {
+                        timeoutId = setTimeout(resolve, DEFAULT_DNS_VALIDATION_MAX_WAIT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+            }
+        }
+        if (this.dnsValidationError !== undefined) {
+            throw this.dnsValidationError;
+        }
+    }
+    /**
+     * Validates `data` against `schema` and returns it typed as `T`.
+     * @throws {TestRailValidationError} When data does not conform to schema
+     */
+    parse(schema, data) {
+        try {
+            return schema.parse(data);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                throw handleZodError(err);
+            }
+            throw err;
         }
     }
 }