@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/http-request.d.ts

@@ -1,951 +0,0 @@
-/**
- * @fileoverview HTTP/HTTPS request utilities using Node.js built-in modules with retry logic, redirects, and download support.
- *
- * This module provides a fetch-like API built on top of Node.js native `http` and `https` modules.
- * It supports automatic retries with exponential backoff, redirect following, streaming downloads,
- * and provides a familiar fetch-style response interface.
- *
- * Key Features:
- * - Automatic retries with exponential backoff for failed requests.
- * - Redirect following with configurable max redirects.
- * - Streaming downloads with progress callbacks.
- * - Fetch-like response interface (`.json()`, `.text()`, `.arrayBuffer()`).
- * - Timeout support for all operations.
- * - Zero dependencies on external HTTP libraries.
- */
-import type { IncomingHttpHeaders, IncomingMessage } from 'node:http';
-import type { Readable } from 'node:stream';
-import type { Logger } from './logger';
-/** IncomingMessage received as a response to a client request (http.request callback). */
-export type IncomingResponse = IncomingMessage;
-/** IncomingMessage received as a request in a server handler (http.createServer callback). */
-export type IncomingRequest = IncomingMessage;
-/**
- * Information passed to the onRequest hook before each request attempt.
- */
-export interface HttpHookRequestInfo {
-    headers: Record<string, string>;
-    method: string;
-    timeout: number;
-    url: string;
-}
-/**
- * Information passed to the onResponse hook after each request attempt.
- */
-export interface HttpHookResponseInfo {
-    duration: number;
-    error?: Error | undefined;
-    headers?: IncomingHttpHeaders | undefined;
-    method: string;
-    status?: number | undefined;
-    statusText?: string | undefined;
-    url: string;
-}
-/**
- * Lifecycle hooks for observing HTTP request/response events.
- * Hooks fire per-attempt (retries produce multiple hook calls).
- */
-export interface HttpHooks {
-    onRequest?: ((info: HttpHookRequestInfo) => void) | undefined;
-    onResponse?: ((info: HttpHookResponseInfo) => void) | undefined;
-}
-/**
- * Configuration options for HTTP/HTTPS requests.
- */
-export interface HttpRequestOptions {
-    /**
-     * Request body to send.
-     * Can be a string, Buffer, or Readable stream.
-     *
-     * When a Readable stream is provided, it is piped directly to the request.
-     * If the stream has a `getHeaders()` method (duck-typed, e.g., the `form-data`
-     * npm package), its headers (Content-Type with boundary) are automatically
-     * merged into the request headers.
-     *
-     * **Note:** Streaming bodies are one-shot — they cannot be replayed. Using a
-     * Readable body with `retries > 0` throws an error. Buffer the body as a
-     * string/Buffer if retries are needed. Redirects are also disabled for
-     * streaming bodies since the stream is consumed on the first request.
-     *
-     * @example
-     * ```ts
-     * // Send JSON data
-     * await httpRequest('https://api.example.com/data', {
-     *   method: 'POST',
-     *   body: JSON.stringify({ name: 'Alice' }),
-     *   headers: { 'Content-Type': 'application/json' }
-     * })
-     *
-     * // Send binary data
-     * const buffer = Buffer.from([0x00, 0x01, 0x02])
-     * await httpRequest('https://api.example.com/upload', {
-     *   method: 'POST',
-     *   body: buffer
-     * })
-     *
-     * // Stream form-data (npm package, not native FormData)
-     * import FormData from 'form-data'
-     * const form = new FormData()
-     * form.append('file', createReadStream('data.json'))
-     * await httpRequest('https://api.example.com/upload', {
-     *   method: 'POST',
-     *   body: form  // auto-merges form.getHeaders()
-     * })
-     * ```
-     */
-    body?: Buffer | Readable | string | undefined;
-    /**
-     * Custom CA certificates for TLS connections.
-     * When provided, these certificates are combined with the default trust
-     * store via an HTTPS agent. Useful when SSL_CERT_FILE is set but
-     * NODE_EXTRA_CA_CERTS was not available at process startup.
-     *
-     * @example
-     * ```ts
-     * import { rootCertificates } from 'node:tls'
-     * import { readFileSync } from 'node:fs'
-     *
-     * const extraCerts = readFileSync('/path/to/cert.pem', 'utf-8')
-     * await httpRequest('https://api.example.com', {
-     *   ca: [...rootCertificates, extraCerts]
-     * })
-     * ```
-     */
-    ca?: string[] | undefined;
-    /**
-     * Whether to automatically follow HTTP redirects (3xx status codes).
-     *
-     * @default true
-     *
-     * @example
-     * ```ts
-     * // Follow redirects (default)
-     * await httpRequest('https://example.com/redirect')
-     *
-     * // Don't follow redirects
-     * const response = await httpRequest('https://example.com/redirect', {
-     *   followRedirects: false
-     * })
-     * console.log(response.status) // 301 or 302
-     * ```
-     */
-    followRedirects?: boolean | undefined;
-    /**
-     * Lifecycle hooks for observing request/response events.
-     * Hooks fire per-attempt — retries and redirects each trigger separate hook calls.
-     */
-    hooks?: HttpHooks | undefined;
-    /**
-     * HTTP headers to send with the request.
-     * A `User-Agent` header is automatically added if not provided.
-     *
-     * @example
-     * ```ts
-     * await httpRequest('https://api.example.com/data', {
-     *   headers: {
-     *     'Authorization': 'Bearer token123',
-     *     'Content-Type': 'application/json',
-     *     'Accept': 'application/json'
-     *   }
-     * })
-     * ```
-     */
-    headers?: Record<string, string> | undefined;
-    /**
-     * Maximum number of redirects to follow before throwing an error.
-     * Only relevant when `followRedirects` is `true`.
-     *
-     * @default 5
-     *
-     * @example
-     * ```ts
-     * // Allow up to 10 redirects
-     * await httpRequest('https://example.com/many-redirects', {
-     *   maxRedirects: 10
-     * })
-     * ```
-     */
-    maxRedirects?: number | undefined;
-    /**
-     * Maximum response body size in bytes. Responses exceeding this limit
-     * will be rejected with an error. Prevents memory exhaustion from
-     * unexpectedly large responses.
-     *
-     * @default undefined (no limit)
-     */
-    maxResponseSize?: number | undefined;
-    /**
-     * HTTP method to use for the request.
-     *
-     * @default 'GET'
-     *
-     * @example
-     * ```ts
-     * // GET request (default)
-     * await httpRequest('https://api.example.com/data')
-     *
-     * // POST request
-     * await httpRequest('https://api.example.com/data', {
-     *   method: 'POST',
-     *   body: JSON.stringify({ name: 'Alice' })
-     * })
-     *
-     * // DELETE request
-     * await httpRequest('https://api.example.com/data/123', {
-     *   method: 'DELETE'
-     * })
-     * ```
-     */
-    method?: string | undefined;
-    /**
-     * Callback invoked before each retry attempt.
-     * Allows customizing retry behavior per-attempt (e.g., skip 4xx, honor Retry-After).
-     *
-     * @param attempt - Current retry attempt number (1-based)
-     * @param error - The error that triggered the retry (HttpResponseError for HTTP errors)
-     * @param delay - The calculated delay in ms before next retry
-     * @returns `false` to stop retrying and rethrow,
-     *          a `number` to override the delay (ms),
-     *          or `undefined` to use the calculated delay
-     *
-     * @example
-     * ```ts
-     * await httpRequest('https://api.example.com/data', {
-     *   retries: 3,
-     *   throwOnError: true,
-     *   onRetry: (attempt, error, delay) => {
-     *     // Don't retry client errors (except 429)
-     *     if (error instanceof HttpResponseError) {
-     *       if (error.response.status === 429) {
-     *         const retryAfter = parseRetryAfterHeader(error.response.headers['retry-after'])
-     *         return retryAfter ?? undefined
-     *       }
-     *       if (error.response.status >= 400 && error.response.status < 500) {
-     *         return false
-     *       }
-     *     }
-     *   }
-     * })
-     * ```
-     */
-    onRetry?: ((attempt: number, error: unknown, delay: number) => boolean | number | undefined) | undefined;
-    /**
-     * Number of retry attempts for failed requests.
-     * Uses exponential backoff: delay = `retryDelay` * 2^attempt.
-     *
-     * @default 0
-     *
-     * @example
-     * ```ts
-     * // Retry up to 3 times with exponential backoff
-     * await httpRequest('https://api.example.com/data', {
-     *   retries: 3,
-     *   retryDelay: 1000 // 1s, then 2s, then 4s
-     * })
-     * ```
-     */
-    retries?: number | undefined;
-    /**
-     * Initial delay in milliseconds before first retry.
-     * Subsequent retries use exponential backoff.
-     *
-     * @default 1000
-     *
-     * @example
-     * ```ts
-     * // Start with 2 second delay, then 4s, 8s, etc.
-     * await httpRequest('https://api.example.com/data', {
-     *   retries: 3,
-     *   retryDelay: 2000
-     * })
-     * ```
-     */
-    retryDelay?: number | undefined;
-    /**
-     * When true, non-2xx HTTP responses throw an `HttpResponseError` instead
-     * of resolving with `response.ok === false`. This makes HTTP error
-     * responses eligible for retry via the `retries` option.
-     *
-     * @default false
-     *
-     * @example
-     * ```ts
-     * // Throw on 4xx/5xx responses (enabling retry for 5xx)
-     * await httpRequest('https://api.example.com/data', {
-     *   throwOnError: true,
-     *   retries: 3
-     * })
-     * ```
-     */
-    /**
-     * When true, resolve with an HttpResponse whose body is NOT buffered.
-     * The `rawResponse` property contains the unconsumed IncomingResponse
-     * stream for piping to files or other destinations.
-     *
-     * `body`, `text()`, `json()`, and `arrayBuffer()` return empty/zero
-     * values since the stream has not been read.
-     *
-     * Incompatible with `maxResponseSize` (size enforcement requires
-     * reading the body).
-     *
-     * @default false
-     */
-    stream?: boolean | undefined;
-    throwOnError?: boolean | undefined;
-    /**
-     * Request timeout in milliseconds.
-     * If the request takes longer than this, it will be aborted.
-     *
-     * @default 30000
-     *
-     * @example
-     * ```ts
-     * // 60 second timeout
-     * await httpRequest('https://api.example.com/slow-endpoint', {
-     *   timeout: 60000
-     * })
-     * ```
-     */
-    timeout?: number | undefined;
-}
-/**
- * HTTP response object with fetch-like interface.
- * Provides multiple ways to access the response body.
- */
-export interface HttpResponse {
-    /**
-     * Get response body as ArrayBuffer.
-     * Useful for binary data or when you need compatibility with browser APIs.
-     *
-     * @returns The response body as an ArrayBuffer
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com/image.png')
-     * const arrayBuffer = response.arrayBuffer()
-     * console.log(arrayBuffer.byteLength)
-     * ```
-     */
-    arrayBuffer(): ArrayBuffer;
-    /**
-     * Raw response body as Buffer.
-     * Direct access to the underlying Node.js Buffer.
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com/data')
-     * console.log(response.body.length) // Size in bytes
-     * console.log(response.body.toString('hex')) // View as hex
-     * ```
-     */
-    body: Buffer;
-    /**
-     * HTTP response headers.
-     * Keys are lowercase header names, values can be strings or string arrays.
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com')
-     * console.log(response.headers['content-type'])
-     * console.log(response.headers['set-cookie']) // May be string[]
-     * ```
-     */
-    headers: IncomingHttpHeaders;
-    /**
-     * Parse response body as JSON.
-     * Type parameter `T` allows specifying the expected JSON structure.
-     *
-     * @template T - Expected JSON type (defaults to `unknown`)
-     * @returns Parsed JSON data
-     * @throws {SyntaxError} When response body is not valid JSON
-     *
-     * @example
-     * ```ts
-     * interface User { name: string; id: number }
-     * const response = await httpRequest('https://api.example.com/user')
-     * const user = response.json<User>()
-     * console.log(user.name, user.id)
-     * ```
-     */
-    json<T = unknown>(): T;
-    /**
-     * Whether the request was successful (status code 200-299).
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com/data')
-     * if (response.ok) {
-     *   console.log('Success:', response.json())
-     * } else {
-     *   console.error('Failed:', response.status, response.statusText)
-     * }
-     * ```
-     */
-    ok: boolean;
-    /**
-     * HTTP status code (e.g., 200, 404, 500).
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com')
-     * console.log(response.status) // 200, 404, etc.
-     * ```
-     */
-    status: number;
-    /**
-     * HTTP status message (e.g., "OK", "Not Found", "Internal Server Error").
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com')
-     * console.log(response.statusText) // "OK"
-     * ```
-     */
-    statusText: string;
-    /**
-     * Get response body as UTF-8 text string.
-     *
-     * @returns The response body as a string
-     *
-     * @example
-     * ```ts
-     * const response = await httpRequest('https://example.com')
-     * const html = response.text()
-     * console.log(html.includes('<html>'))
-     * ```
-     */
-    text(): string;
-    /**
-     * The underlying Node.js IncomingResponse for advanced use cases
-     * (e.g., streaming, custom header inspection). Only available when
-     * the response was not consumed by the convenience methods.
-     */
-    rawResponse?: IncomingResponse | undefined;
-}
-/**
- * Error thrown when an HTTP response has a non-2xx status code
- * and `throwOnError` is enabled. Carries the full `HttpResponse`
- * so callers can inspect status, headers, and body.
- */
-export declare class HttpResponseError extends Error {
-    response: HttpResponse;
-    constructor(response: HttpResponse, message?: string | undefined);
-}
-/**
- * Configuration options for file downloads.
- */
-export interface HttpDownloadOptions {
-    /**
-     * Custom CA certificates for TLS connections.
-     * When provided, these certificates are used for the download request.
-     * See `HttpRequestOptions.ca` for details.
-     */
-    ca?: string[] | undefined;
-    /**
-     * Whether to automatically follow HTTP redirects (3xx status codes).
-     * This is essential for downloading from services that use CDN redirects,
-     * such as GitHub release assets which return HTTP 302 to their CDN.
-     *
-     * @default true
-     *
-     * @example
-     * ```ts
-     * // Follow redirects (default) - works with GitHub releases
-     * await httpDownload(
-     *   'https://github.com/org/repo/releases/download/v1.0.0/file.zip',
-     *   '/tmp/file.zip'
-     * )
-     *
-     * // Don't follow redirects
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   followRedirects: false
-     * })
-     * ```
-     */
-    followRedirects?: boolean | undefined;
-    /**
-     * HTTP headers to send with the download request.
-     * A `User-Agent` header is automatically added if not provided.
-     *
-     * @example
-     * ```ts
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   headers: {
-     *     'Authorization': 'Bearer token123'
-     *   }
-     * })
-     * ```
-     */
-    headers?: Record<string, string> | undefined;
-    /**
-     * Logger instance for automatic progress logging.
-     * When provided with `progressInterval`, will automatically log download progress.
-     * If both `onProgress` and `logger` are provided, `onProgress` takes precedence.
-     *
-     * @example
-     * ```ts
-     * import { getDefaultLogger } from '@socketsecurity/lib/logger'
-     *
-     * const logger = getDefaultLogger()
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   logger,
-     *   progressInterval: 10  // Log every 10%
-     * })
-     * // Output:
-     * //   Progress: 10% (5.2 MB / 52.0 MB)
-     * //   Progress: 20% (10.4 MB / 52.0 MB)
-     * //   ...
-     * ```
-     */
-    logger?: Logger | undefined;
-    /**
-     * Maximum number of redirects to follow before throwing an error.
-     * Only relevant when `followRedirects` is `true`.
-     *
-     * @default 5
-     *
-     * @example
-     * ```ts
-     * // Allow up to 10 redirects
-     * await httpDownload('https://example.com/many-redirects/file.zip', '/tmp/file.zip', {
-     *   maxRedirects: 10
-     * })
-     * ```
-     */
-    maxRedirects?: number | undefined;
-    /**
-     * Callback for tracking download progress.
-     * Called periodically as data is received.
-     * Takes precedence over `logger` if both are provided.
-     *
-     * @param downloaded - Number of bytes downloaded so far
-     * @param total - Total file size in bytes (from Content-Length header)
-     *
-     * @example
-     * ```ts
-     * await httpDownload('https://example.com/large-file.zip', '/tmp/file.zip', {
-     *   onProgress: (downloaded, total) => {
-     *     const percent = ((downloaded / total) * 100).toFixed(1)
-     *     console.log(`Progress: ${percent}%`)
-     *   }
-     * })
-     * ```
-     */
-    onProgress?: ((downloaded: number, total: number) => void) | undefined;
-    /**
-     * Progress reporting interval as a percentage (0-100).
-     * Only used when `logger` is provided.
-     * Progress will be logged each time the download advances by this percentage.
-     *
-     * @default 10
-     *
-     * @example
-     * ```ts
-     * // Log every 10%
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   logger: getDefaultLogger(),
-     *   progressInterval: 10
-     * })
-     *
-     * // Log every 25%
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   logger: getDefaultLogger(),
-     *   progressInterval: 25
-     * })
-     * ```
-     */
-    progressInterval?: number | undefined;
-    /**
-     * Number of retry attempts for failed downloads.
-     * Uses exponential backoff: delay = `retryDelay` * 2^attempt.
-     *
-     * @default 0
-     *
-     * @example
-     * ```ts
-     * // Retry up to 3 times for unreliable connections
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   retries: 3,
-     *   retryDelay: 2000
-     * })
-     * ```
-     */
-    retries?: number | undefined;
-    /**
-     * Initial delay in milliseconds before first retry.
-     * Subsequent retries use exponential backoff.
-     *
-     * @default 1000
-     */
-    retryDelay?: number | undefined;
-    /**
-     * Download timeout in milliseconds.
-     * If the download takes longer than this, it will be aborted.
-     *
-     * @default 120000
-     *
-     * @example
-     * ```ts
-     * // 5 minute timeout for large files
-     * await httpDownload('https://example.com/huge-file.zip', '/tmp/file.zip', {
-     *   timeout: 300000
-     * })
-     * ```
-     */
-    timeout?: number | undefined;
-    /**
-     * Expected SHA256 hash of the downloaded file.
-     * If provided, the download will fail if the computed hash doesn't match.
-     * The hash should be a lowercase hex string (64 characters).
-     *
-     * Use `fetchChecksums()` to fetch hashes from a checksums URL, then pass
-     * the specific hash here.
-     *
-     * @example
-     * ```ts
-     * // Verify download integrity with direct hash
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
-     * })
-     *
-     * // Verify using checksums from a URL
-     * const checksums = await fetchChecksums('https://example.com/checksums.txt')
-     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
-     *   sha256: checksums['file.zip']
-     * })
-     * ```
-     */
-    sha256?: string | undefined;
-}
-/**
- * Result of a successful file download.
- */
-export interface HttpDownloadResult {
-    /** HTTP response headers from the final response (after redirects). */
-    headers: IncomingHttpHeaders;
-    /** Whether the download succeeded (status 200-299). Always true on success (non-2xx throws). */
-    ok: true;
-    /** Absolute path where the file was saved. */
-    path: string;
-    /** Total size of downloaded file in bytes. */
-    size: number;
-    /** HTTP status code from the final response (after redirects). */
-    status: number;
-    /** HTTP status message from the final response (after redirects). */
-    statusText: string;
-}
-/**
- * Map of filenames to their SHA256 hashes.
- * Keys are filenames (not paths), values are lowercase hex-encoded SHA256 hashes.
- *
- * @example
- * ```ts
- * const checksums: Checksums = {
- *   'file.zip': 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
- *   'other.tar.gz': 'abc123...'
- * }
- * ```
- */
-export type Checksums = Record<string, string>;
-/**
- * Options for fetching checksums from a URL.
- */
-export interface FetchChecksumsOptions {
-    /**
-     * Custom CA certificates for TLS connections.
-     * See `HttpRequestOptions.ca` for details.
-     */
-    ca?: string[] | undefined;
-    /**
-     * HTTP headers to send with the request.
-     */
-    headers?: Record<string, string> | undefined;
-    /**
-     * Request timeout in milliseconds.
-     * @default 30000
-     */
-    timeout?: number | undefined;
-}
-/**
- * Build an enriched error message based on the error code.
- * Generic guidance (no product-specific branding).
- *
- * @example
- * ```typescript
- * try {
- *   await fetch('https://api.example.com')
- * } catch (e) {
- *   console.error(enrichErrorMessage('https://api.example.com', 'GET', e))
- * }
- * ```
- */
-export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
-/**
- * Fetch and parse a checksums file from a URL.
- *
- * This is useful for verifying downloads from GitHub releases which typically
- * publish a checksums.txt file alongside release assets.
- *
- * @param url - URL to the checksums file
- * @param options - Request options
- * @returns Map of filenames to lowercase SHA256 hashes
- * @throws {Error} When the checksums file cannot be fetched
- *
- * @example
- * ```ts
- * // Fetch checksums from GitHub release
- * const checksums = await fetchChecksums(
- *   'https://github.com/org/repo/releases/download/v1.0.0/checksums.txt'
- * )
- *
- * // Use with httpDownload
- * await httpDownload(
- *   'https://github.com/org/repo/releases/download/v1.0.0/tool_linux.tar.gz',
- *   '/tmp/tool.tar.gz',
- *   { sha256: checksums['tool_linux.tar.gz'] }
- * )
- * ```
- */
-export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
-/**
- * Download a file from a URL to a local path with redirect support, retry logic, and progress callbacks.
- * Uses streaming to avoid loading entire file in memory.
- *
- * The download is streamed directly to disk, making it memory-efficient even for
- * large files. Progress callbacks allow for real-time download status updates.
- *
- * Automatically follows HTTP redirects (3xx status codes) by default, making it suitable
- * for downloading from services like GitHub releases that redirect to CDN URLs.
- *
- * @param url - The URL to download from (must start with http:// or https://)
- * @param destPath - Absolute path where the file should be saved
- * @param options - Download configuration options
- * @returns Promise resolving to download result with path and size
- * @throws {Error} When all retries are exhausted, download fails, or file cannot be written
- *
- * @example
- * ```ts
- * // Simple download
- * const result = await httpDownload(
- *   'https://example.com/file.zip',
- *   '/tmp/file.zip'
- * )
- * console.log(`Downloaded ${result.size} bytes to ${result.path}`)
- *
- * // Download from GitHub releases (handles 302 redirect automatically)
- * await httpDownload(
- *   'https://github.com/org/repo/releases/download/v1.0.0/binary.tar.gz',
- *   '/tmp/binary.tar.gz'
- * )
- *
- * // With progress tracking
- * await httpDownload(
- *   'https://example.com/large-file.zip',
- *   '/tmp/file.zip',
- *   {
- *     onProgress: (downloaded, total) => {
- *       const percent = ((downloaded / total) * 100).toFixed(1)
- *       console.log(`Progress: ${percent}% (${downloaded}/${total} bytes)`)
- *     }
- *   }
- * )
- *
- * // With retries and custom timeout
- * await httpDownload(
- *   'https://example.com/file.zip',
- *   '/tmp/file.zip',
- *   {
- *     retries: 3,
- *     retryDelay: 2000,
- *     timeout: 300000, // 5 minutes
- *     headers: { 'Authorization': 'Bearer token123' }
- *   }
- * )
- * ```
- */
-export declare function httpDownload(url: string, destPath: string, options?: HttpDownloadOptions | undefined): Promise<HttpDownloadResult>;
-/**
- * Perform an HTTP request and parse JSON response.
- * Convenience wrapper around `httpRequest` for JSON API calls.
- * Automatically sets appropriate headers for JSON requests:
- * - `Accept: application/json` (always)
- * - `Content-Type: application/json` (when body is present)
- * User-provided headers override these defaults.
- *
- * @template T - Expected JSON response type (defaults to `unknown`)
- * @param url - The URL to request (must start with http:// or https://)
- * @param options - Request configuration options
- * @returns Promise resolving to parsed JSON data
- * @throws {Error} When request fails, response is not ok (status < 200 or >= 300), or JSON parsing fails
- *
- * @example
- * ```ts
- * // Simple JSON GET (automatically sets Accept: application/json)
- * const data = await httpJson('https://api.example.com/data')
- * console.log(data)
- *
- * // With type safety
- * interface User { id: number; name: string; email: string }
- * const user = await httpJson<User>('https://api.example.com/user/123')
- * console.log(user.name, user.email)
- *
- * // POST with JSON body (automatically sets Content-Type: application/json)
- * const result = await httpJson('https://api.example.com/users', {
- *   method: 'POST',
- *   body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
- * })
- *
- * // With custom headers and retries
- * const data = await httpJson('https://api.example.com/data', {
- *   headers: {
- *     'Authorization': 'Bearer token123'
- *   },
- *   retries: 3,
- *   retryDelay: 1000
- * })
- * ```
- */
-export declare function httpJson<T = unknown>(url: string, options?: HttpRequestOptions | undefined): Promise<T>;
-/**
- * Make an HTTP/HTTPS request with retry logic and redirect support.
- * Provides a fetch-like API using Node.js native http/https modules.
- *
- * This is the main entry point for making HTTP requests. It handles retries,
- * redirects, timeouts, and provides a fetch-compatible response interface.
- *
- * @param url - The URL to request (must start with http:// or https://)
- * @param options - Request configuration options
- * @returns Promise resolving to response object with `.json()`, `.text()`, etc.
- * @throws {Error} When all retries are exhausted, timeout occurs, or non-retryable error happens
- *
- * @example
- * ```ts
- * // Simple GET request
- * const response = await httpRequest('https://api.example.com/data')
- * const data = response.json()
- *
- * // POST with JSON body
- * const response = await httpRequest('https://api.example.com/users', {
- *   method: 'POST',
- *   headers: { 'Content-Type': 'application/json' },
- *   body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
- * })
- *
- * // With retries and timeout
- * const response = await httpRequest('https://api.example.com/data', {
- *   retries: 3,
- *   retryDelay: 1000,
- *   timeout: 60000
- * })
- *
- * // Don't follow redirects
- * const response = await httpRequest('https://example.com/redirect', {
- *   followRedirects: false
- * })
- * console.log(response.status) // 301, 302, etc.
- * ```
- */
-export declare function httpRequest(url: string, options?: HttpRequestOptions | undefined): Promise<HttpResponse>;
-/**
- * Perform an HTTP request and return text response.
- * Convenience wrapper around `httpRequest` for fetching text content.
- * Automatically sets appropriate headers for text requests:
- * - `Accept: text/plain` (always)
- * - `Content-Type: text/plain` (when body is present)
- * User-provided headers override these defaults.
- *
- * @param url - The URL to request (must start with http:// or https://)
- * @param options - Request configuration options
- * @returns Promise resolving to response body as UTF-8 string
- * @throws {Error} When request fails or response is not ok (status < 200 or >= 300)
- *
- * @example
- * ```ts
- * // Fetch HTML (automatically sets Accept: text/plain)
- * const html = await httpText('https://example.com')
- * console.log(html.includes('<!DOCTYPE html>'))
- *
- * // Fetch plain text
- * const text = await httpText('https://example.com/file.txt')
- * console.log(text)
- *
- * // POST with text body (automatically sets Content-Type: text/plain)
- * const result = await httpText('https://example.com/api', {
- *   method: 'POST',
- *   body: 'raw text data'
- * })
- *
- * // With custom headers (override defaults)
- * const text = await httpText('https://example.com/data.txt', {
- *   headers: {
- *     'Authorization': 'Bearer token123',
- *     'Accept': 'text/html'  // Override default Accept header
- *   }
- * })
- *
- * // With timeout
- * const text = await httpText('https://example.com/large-file.txt', {
- *   timeout: 60000 // 1 minute
- * })
- * ```
- */
-export declare function httpText(url: string, options?: HttpRequestOptions | undefined): Promise<string>;
-export declare function parseChecksums(text: string): Checksums;
-/**
- * Parse a `Retry-After` HTTP header value into milliseconds.
- *
- * Supports both formats defined in RFC 7231 §7.1.3:
- * - **delay-seconds**: integer number of seconds (e.g., `"120"`)
- * - **HTTP-date**: an absolute date/time (e.g., `"Fri, 31 Dec 2027 23:59:59 GMT"`)
- *
- * When the header is an array (multiple values), the first element is used.
- *
- * @param value - The raw Retry-After header value(s)
- * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
- *
- * @example
- * ```ts
- * import { setTimeout as delay } from 'node:timers/promises'
- * const ms = parseRetryAfterHeader(response.headers['retry-after'])
- * if (ms !== undefined) {
- *   await delay(ms)
- * }
- * ```
- */
-export declare function parseRetryAfterHeader(value: string | string[] | undefined): number | undefined;
-/**
- * Read and buffer a client-side IncomingResponse into an HttpResponse.
- *
- * Useful when you have a raw response from code that bypasses
- * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
- * or responses from third-party HTTP libraries) and need to convert it
- * into the standard HttpResponse interface.
- *
- * @example
- * ```typescript
- * const raw = await makeRawRequest('https://example.com/api')
- * const response = await readIncomingResponse(raw)
- * console.log(response.status, response.body.toString('utf8'))
- * ```
- */
-export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
-/**
- * Redact sensitive HTTP headers for safe logging and telemetry.
- *
- * Replaces values of sensitive headers (Authorization, Cookie, etc.)
- * with `[REDACTED]`. Non-sensitive headers are passed through unchanged.
- * Array values are joined with `', '`.
- *
- * @param headers - HTTP headers to sanitize
- * @returns A new object with sensitive values redacted
- *
- * @example
- * ```ts
- * const safe = sanitizeHeaders({
- *   'authorization': 'Bearer secret',
- *   'content-type': 'application/json'
- * })
- * // { authorization: '[REDACTED]', 'content-type': 'application/json' }
- * ```
- */
-export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;