apify-client 3.0.0-beta.9 → 3.0.0-rc.0

package/dist/http_clients/base.js

@@ -0,0 +1,563 @@
+import { z } from 'zod';
+import { APIFY_ENV_VARS } from '@apify/consts';
+import log from '@apify/log';
+import { concatStreamToBuffer } from '@apify/utilities';
+import { ApifyApiError } from '../apify_api_error.js';
+import { maybeParseBody } from '../body_parser.js';
+import { resolveCompressor } from '../http_compressors/resolve.js';
+import { InvalidResponseBodyError } from '../invalid_response_body_error.js';
+import { Statistics } from '../statistics.js';
+import { DEFAULT_TIMEOUT_LONG_SECS, DEFAULT_TIMEOUT_MAX_SECS, DEFAULT_TIMEOUT_MEDIUM_SECS, DEFAULT_TIMEOUT_SHORT_SECS, } from '../timeouts.js';
+import { runtime } from '#runtime';
+import { asArray, getEnv, isBuffer, isCompressibleContentType, isStream, MIN_COMPRESS_BYTES, parseArgument, sleep, toBytes, version, } from '../utils.js';
+export const DEFAULT_MAX_RETRIES = 8;
+export const DEFAULT_MIN_DELAY_BETWEEN_RETRIES_MILLIS = 500;
+const RATE_LIMIT_EXCEEDED_STATUS_CODE = 429;
+const CONTENT_TYPE_JSON = 'application/json';
+const CONTENT_TYPE_FORM_URLENCODED = 'application/x-www-form-urlencoded';
+/**
+ * Bounds of the numeric {@link HttpClientOptions}. `ApifyClientOptions` checks the same bounds and adds the defaults.
+ * @internal
+ */
+export const httpClientOptionsShape = {
+    maxRetries: z.number().int().nonnegative(),
+    minDelayBetweenRetriesMillis: z.number().nonnegative(),
+    timeoutShortSecs: z.number().positive(),
+    timeoutMediumSecs: z.number().positive(),
+    timeoutLongSecs: z.number().positive(),
+    timeoutMaxSecs: z.number().positive(),
+};
+const httpClientOptionsSchema = z.looseObject(httpClientOptionsShape).partial();
+/** Objects whose payload does not live in their own enumerable keys, so JSON serialization loses it. */
+const UNSERIALIZABLE_OBJECT_TAGS = new Set(['Blob', 'File', 'FormData', 'ReadableStream']);
+/**
+ * Base class for the HTTP clients used by {@link ApifyClient}.
+ *
+ * It holds the shared request pipeline: {@link call} merges the default headers in, serializes and compresses the
+ * body, encodes the query parameters, retries transient failures with exponential backoff, grows the timeout with
+ * every attempt, decodes the response body by content type, records statistics and converts error statuses to
+ * {@link ApifyApiError}. A concrete client only has to implement {@link sendRequest}, the transport that moves one
+ * prepared request over the wire, and can override the classification and lifecycle hooks {@link isTimeoutError},
+ * {@link isRetryableTransportError} and {@link close}.
+ *
+ * Overriding {@link call} itself is also supported and bypasses the transport hooks entirely. Such a client has
+ * to send the default headers from `defaultHeaders` with every request, otherwise the `Authorization` header never
+ * reaches the API. The protected helpers `prepareRequest()`, `buildUrl()` and `computeTimeoutMillis()` stay
+ * available to it.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, HttpClient } from 'apify-client';
+ *
+ * class FetchHttpClient extends HttpClient {
+ *     async sendRequest({ method, url, headers, body, timeoutMillis, signal }) {
+ *         const signals = signal ? [signal] : [];
+ *         if (timeoutMillis !== undefined) signals.push(AbortSignal.timeout(timeoutMillis));
+ *         const response = await fetch(url, { method, headers, body, signal: AbortSignal.any(signals) });
+ *         return {
+ *             status: response.status,
+ *             headers: Object.fromEntries(response.headers),
+ *             body: Buffer.from(await response.arrayBuffer()),
+ *         };
+ *     }
+ *
+ *     isRetryableTransportError(error) {
+ *         // Without this the client gives up on the first connection failure.
+ *         return this.isTimeoutError(error) || error instanceof TypeError;
+ *     }
+ * }
+ *
+ * const client = ApifyClient.withCustomHttpClient({ token: 'my-token', httpClient: new FetchHttpClient() });
+ * ```
+ */
+export class HttpClient {
+    /** Statistics of the API calls made through this client. */
+    stats;
+    /** Logger for the retry warnings. */
+    logger;
+    /** How many times a failed request is retried at most. */
+    maxRetries;
+    /** Lower bound for the delay before the first retry in milliseconds. It doubles with every further retry. */
+    minDelayBetweenRetriesMillis;
+    /** Duration of each timeout tier, in milliseconds. */
+    timeoutMillis;
+    /** Upper bound for the timeout of a single attempt, in milliseconds. */
+    timeoutMaxMillis;
+    /** Compressor the request pipeline runs the bodies worth compressing through. */
+    httpCompressor;
+    /**
+     * Headers sent with every request: the `Authorization` header built from the token, the `User-Agent` where the
+     * runtime lets a client set one, the `X-Apify-Workflow-Key` when a workflow key is configured, and whatever
+     * {@link HttpClientOptions.headers} added.
+     */
+    defaultHeaders;
+    /**
+     * @param options - Configuration of the pipeline. The retry and timeout options are validated the same way the
+     * `ApifyClient` constructor validates them.
+     * @throws {ArgumentValidationError} When a retry or timeout option is out of bounds.
+     */
+    constructor(options = {}) {
+        parseArgument(options, httpClientOptionsSchema, 'HttpClientOptions');
+        this.stats = options.stats ?? new Statistics();
+        this.logger = options.logger ?? log.child({ prefix: 'ApifyClient' });
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.minDelayBetweenRetriesMillis =
+            options.minDelayBetweenRetriesMillis ?? DEFAULT_MIN_DELAY_BETWEEN_RETRIES_MILLIS;
+        this.timeoutMillis = {
+            short: (options.timeoutShortSecs ?? DEFAULT_TIMEOUT_SHORT_SECS) * 1000,
+            medium: (options.timeoutMediumSecs ?? DEFAULT_TIMEOUT_MEDIUM_SECS) * 1000,
+            long: (options.timeoutLongSecs ?? DEFAULT_TIMEOUT_LONG_SECS) * 1000,
+        };
+        this.timeoutMaxMillis = (options.timeoutMaxSecs ?? DEFAULT_TIMEOUT_MAX_SECS) * 1000;
+        this.httpCompressor = resolveCompressor(options.compression ?? 'brotli');
+        const defaults = {};
+        const workflowKey = options.workflowKey || getEnv(APIFY_ENV_VARS.WORKFLOW_KEY);
+        if (workflowKey)
+            defaults['X-Apify-Workflow-Key'] = workflowKey;
+        // Browsers do not let a page set the header, so it only goes out where the runtime describes its platform.
+        if (runtime.platform) {
+            const isAtHome = !!getEnv(APIFY_ENV_VARS.IS_AT_HOME);
+            let userAgent = `ApifyClient/${version} (${runtime.platform}); isAtHome/${isAtHome}`;
+            if (options.userAgentSuffix)
+                userAgent += `; ${asArray(options.userAgentSuffix).join('; ')}`;
+            defaults['User-Agent'] = userAgent;
+        }
+        if (options.token)
+            defaults.Authorization = `Bearer ${options.token}`;
+        this.defaultHeaders = mergeHeaders(defaults, options.headers);
+    }
+    /**
+     * Sets the `Authorization` header from the token, unless an authorization header is already configured.
+     *
+     * @param token - The Apify API token to send as the `Bearer` token.
+     */
+    setDefaultAuthorization(token) {
+        if (getHeader(this.defaultHeaders, 'authorization') === undefined) {
+            this.defaultHeaders.Authorization = `Bearer ${token}`;
+        }
+    }
+    /**
+     * Whether an error thrown by the transport is a timeout.
+     *
+     * Recognizes errors named `TimeoutError`, which is what `AbortSignal.timeout()` produces. Transports extend it
+     * with the timeout errors their HTTP library throws. The classification is independent of retryability: a
+     * timeout the retry loop should retry has to be covered by {@link isRetryableTransportError} too.
+     */
+    isTimeoutError(error) {
+        return error instanceof Error && error.name === 'TimeoutError';
+    }
+    /**
+     * Whether an error thrown by the transport is worth retrying.
+     *
+     * The default classifies nothing as retryable, so a transport that does not override it gives up on the first
+     * connection failure. Every transport should map its own transient errors here: connection resets, refused
+     * connections, timeouts and the like. Error responses are not the transport's concern, the pipeline decides on
+     * them from the status code.
+     */
+    isRetryableTransportError(_error) {
+        return false;
+    }
+    /**
+     * Releases resources owned by the transport, such as a connection pool. The default does nothing.
+     */
+    async close() {
+        // Nothing to release without a transport of its own.
+    }
+    /**
+     * Sends one prepared request through the underlying HTTP library.
+     *
+     * The inherited {@link call} needs it, so every transport has to implement it. Let the library's errors
+     * propagate unwrapped: {@link call} classifies them through {@link isRetryableTransportError} and
+     * {@link isTimeoutError}. Return error responses as they are too, the pipeline turns them into
+     * {@link ApifyApiError} and decides whether to retry.
+     *
+     * @param request - The request to send, with the headers merged, the body serialized and the query encoded.
+     * @returns The response, with the body unread when `request.stream` is set and as raw bytes otherwise.
+     */
+    async sendRequest(request) {
+        throw new Error(`Implement sendRequest() to send ${request.method} ${request.url}, or override call() entirely.`);
+    }
+    /**
+     * Makes an API request with automatic retries and exponential backoff.
+     *
+     * Network errors the transport classifies as retryable, rate limits (HTTP 429) and server errors (HTTP 5xx)
+     * are retried up to {@link maxRetries} times. Any other error status is thrown as {@link ApifyApiError} right
+     * away. A request whose body is a `Readable` is never retried, since part of the stream has already been
+     * consumed by the time the failure shows. Aborting `config.signal` ends the attempt in flight, skips the
+     * remaining retries and rejects the call with the signal's `reason`.
+     *
+     * @template T - Type of the parsed response body.
+     * @param config - The request to make.
+     * @returns The successful response.
+     * @throws {ApifyApiError} When the API responds with an error status the retries could not fix.
+     */
+    async call(config) {
+        config.signal?.throwIfAborted();
+        this.stats.calls++;
+        const { headers, body } = await this.prepareRequest(config);
+        const url = this.buildUrl(config.url, config.params);
+        return this.#retryWithExpBackoff(async (stopRetrying, attempt) => this.#makeRequest({ config, url, headers, body, attempt, stopRetrying }), config.signal);
+    }
+    /**
+     * Prepares the headers and the body of a request.
+     *
+     * Merges the client's default headers with the per-request ones, header names compared case-insensitively and
+     * the per-request values winning. Serializes an object body to JSON, setting `Content-Type: application/json`
+     * unless the caller supplied a content type. Runs the body through {@link httpCompressor} unless a
+     * `Content-Encoding` header is already set, the body is too small, or its content type says the payload is
+     * already compressed. A caller-supplied `Content-Encoding` is forwarded as it is, which is how a pre-encoded
+     * body is uploaded, and `Content-Encoding: identity` opts a single request out of compression.
+     */
+    async prepareRequest(config) {
+        let headers = mergeHeaders(this.defaultHeaders, config.headers);
+        let body = serializeBody(config.data, headers, config.stringifyFunctions);
+        const bytes = compressibleBytes(body, headers);
+        if (bytes) {
+            body = await this.httpCompressor.compress(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+            // Compressing changes the body length, so a `Content-Length` the caller set describes the wrong body
+            // and would leave the server waiting for bytes that never arrive.
+            headers = mergeHeaders(headers, { 'Content-Encoding': this.httpCompressor.contentEncoding });
+            deleteHeader(headers, 'content-length');
+        }
+        return { headers, body };
+    }
+    /**
+     * Appends the query parameters to the URL. `undefined` values are dropped, booleans are sent as `1` and `0`,
+     * `Date` values as ISO 8601 strings and arrays comma-separated.
+     */
+    buildUrl(url, params) {
+        const pairs = [];
+        for (const [key, value] of Object.entries(params ?? {})) {
+            if (value === undefined)
+                continue;
+            if (value instanceof Date)
+                pairs.push([key, value.toISOString()]);
+            else if (typeof value === 'boolean')
+                pairs.push([key, String(Number(value))]);
+            else
+                pairs.push([key, String(value)]);
+        }
+        if (pairs.length === 0)
+            return url;
+        const query = new URLSearchParams(pairs).toString();
+        return `${url}${url.includes('?') ? '&' : '?'}${query}`;
+    }
+    /**
+     * Resolves `timeoutSecs` to the number of milliseconds the given attempt gets. A tier name resolves to its
+     * configured duration, a number is taken as seconds, and `'noTimeout'` becomes `undefined`. The result doubles
+     * with each attempt and is capped at `timeoutMaxMillis`. A requested value above the cap is capped too, which
+     * warns once, since it does not take effect in full.
+     *
+     * @param attempt - Current attempt number, starting at 1.
+     * @param timeoutSecs - The request's timeout. Defaults to the `medium` tier.
+     */
+    computeTimeoutMillis(attempt, timeoutSecs = 'medium') {
+        if (timeoutSecs === 'noTimeout')
+            return undefined;
+        const requestedMillis = typeof timeoutSecs === 'number' ? timeoutSecs * 1000 : this.timeoutMillis[timeoutSecs];
+        if (requestedMillis > this.timeoutMaxMillis) {
+            // `warningOnce` keys by message, so each requested value warns once.
+            this.logger.warningOnce(`The requested timeout of ${requestedMillis / 1000}s exceeds timeoutMaxSecs ` +
+                `(${this.timeoutMaxMillis / 1000}s) and is capped at it. ` +
+                'Raise timeoutMaxSecs on the client to allow longer request timeouts.');
+        }
+        return Math.min(requestedMillis * 2 ** (attempt - 1), this.timeoutMaxMillis);
+    }
+    /**
+     * Retries `fn` with randomized exponential backoff until it resolves, `stopRetrying()` was called before it
+     * threw, the retries are exhausted, or `signal` aborts. The last attempt's error propagates as it is, and an
+     * abort throws the signal's `reason`, whether it lands during an attempt or during the wait before the next.
+     */
+    async #retryWithExpBackoff(fn, signal) {
+        let retry = true;
+        const stopRetrying = () => {
+            retry = false;
+        };
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            signal?.throwIfAborted();
+            try {
+                return await fn(stopRetrying, attempt);
+            }
+            catch (err) {
+                // A transport that does not honor the signal may still answer the aborted attempt with an error
+                // status, and the caller expects the reason for that too.
+                signal?.throwIfAborted();
+                if (!retry)
+                    throw err;
+                this.#onRequestRetry(err, attempt);
+            }
+            // The delay doubles with every attempt and is spread over a random factor between 1 and 2, so that
+            // callers that failed together do not come back at the API in lockstep on every retry.
+            const delayMillis = this.minDelayBetweenRetriesMillis * 2 ** (attempt - 1) * (1 + Math.random());
+            await sleep(delayMillis, signal);
+        }
+        signal?.throwIfAborted();
+        return fn(stopRetrying, this.maxRetries + 1);
+    }
+    /**
+     * Executes one attempt: sends the request, decodes the body and turns an error status into {@link ApifyApiError}.
+     * Throws for anything that is not a success, and flags the failure as final through `stopRetrying()` when a
+     * retry could not fix it.
+     */
+    async #makeRequest(options) {
+        const { config, url, headers, body, attempt, stopRetrying } = options;
+        this.stats.requests++;
+        const requestIsStream = isStream(config.data);
+        let response;
+        try {
+            response = await this.sendRequest({
+                method: config.method,
+                url,
+                headers,
+                body,
+                timeoutMillis: this.computeTimeoutMillis(attempt, config.timeoutSecs),
+                stream: config.responseType === 'stream',
+                signal: config.signal,
+            });
+        }
+        catch (err) {
+            // Every HTTP library reports an abort with an error of its own, so the caller gets the reason instead.
+            config.signal?.throwIfAborted();
+            this.#handleRequestError(err, config, stopRetrying);
+            throw err;
+        }
+        // A failed streaming request carries the API error body in the stream, so read it and let
+        // `ApifyApiError` parse it like any other error body. A body that cannot be read leaves the error
+        // without a message, which beats losing the status code to a stream error.
+        if (response.status >= 300 && isStream(response.body)) {
+            response.body = await concatStreamToBuffer(response.body).catch(() => undefined);
+        }
+        let data;
+        try {
+            data = this.#parseResponseBody(response, config);
+        }
+        catch (err) {
+            // A body that does not parse is usually a connection dropped mid-response, which a retry fixes.
+            if (requestIsStream) {
+                this.#informAboutStreamNoRetry();
+                stopRetrying();
+            }
+            throw err;
+        }
+        const apifyResponse = {
+            status: response.status,
+            headers: response.headers,
+            data: data,
+            config,
+        };
+        if (response.status < 300)
+            return apifyResponse;
+        if (response.status === RATE_LIMIT_EXCEEDED_STATUS_CODE) {
+            this.stats.addRateLimitError(attempt);
+        }
+        const apiError = ApifyApiError.fromResponse(apifyResponse, attempt);
+        if (!this.#isStatusCodeRetryable(response.status)) {
+            stopRetrying();
+        }
+        else if (requestIsStream) {
+            this.#informAboutStreamNoRetry();
+            stopRetrying();
+        }
+        throw apiError;
+    }
+    /**
+     * Decodes the response body according to the request's `responseType`. An empty body decodes to `undefined`.
+     *
+     * @throws {InvalidResponseBodyError} When the body does not parse as its content type claims.
+     */
+    #parseResponseBody(response, config) {
+        const { body } = response;
+        if (config.responseType === 'stream' || config.responseType === 'buffer')
+            return body;
+        if (body === undefined || isStream(body))
+            return body;
+        if (body.byteLength === 0)
+            return undefined;
+        try {
+            return maybeParseBody(body, headerValue(response.headers['content-type']) ?? '');
+        }
+        catch (err) {
+            throw new InvalidResponseBodyError(response, err);
+        }
+    }
+    /**
+     * Decides whether a transport error ends the call. Timeouts the request opted out of retrying and errors the
+     * transport does not classify as retryable are final, and so is any error on a request with a stream body.
+     */
+    #handleRequestError(err, config, stopRetrying) {
+        if (config.doNotRetryTimeouts && this.isTimeoutError(err)) {
+            stopRetrying();
+            return;
+        }
+        if (!this.isRetryableTransportError(err)) {
+            stopRetrying();
+            return;
+        }
+        if (isStream(config.data)) {
+            this.#informAboutStreamNoRetry();
+            stopRetrying();
+        }
+    }
+    /**
+     * Rate limits (429) and server errors (500+) are retried. Anything else in 300-499 is a redirect the client
+     * cannot follow or invalid input, which repeating the request cannot fix.
+     */
+    #isStatusCodeRetryable(statusCode) {
+        return statusCode === RATE_LIMIT_EXCEEDED_STATUS_CODE || statusCode >= 500;
+    }
+    #informAboutStreamNoRetry() {
+        this.logger.warningOnce('Request body was a stream - retrying will not work, as part of it was already consumed.');
+        this.logger.warningOnce('If you want Apify client to handle retries for you, collect the stream into a buffer before sending it.');
+    }
+    #onRequestRetry(error, attempt) {
+        if (attempt === Math.round(this.maxRetries / 2)) {
+            this.logger.warning(`API request failed ${attempt} times. Max attempts: ${this.maxRetries + 1}.\nCause:${error.stack}`);
+        }
+    }
+}
+/**
+ * Looks a header up by name, compared case-insensitively.
+ */
+function getHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === wanted);
+    return key === undefined ? undefined : headers[key];
+}
+/**
+ * Merges two header records, header names compared case-insensitively. A header from `override` replaces a
+ * same-named header in `base` whatever the casing of either, and keeps the casing it was passed with.
+ */
+function mergeHeaders(base, override) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override ?? {})) {
+        for (const existing of Object.keys(merged)) {
+            if (existing.toLowerCase() === key.toLowerCase())
+                delete merged[existing];
+        }
+        merged[key] = value;
+    }
+    return merged;
+}
+/**
+ * Removes a header by name, compared case-insensitively.
+ */
+function deleteHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted)
+            delete headers[key];
+    }
+}
+/**
+ * Views a serialized body as the bytes to compress, or `undefined` when compressing it would not pay off: the
+ * caller already labeled the body with a `Content-Encoding`, its content type carries its own compression, it is
+ * a stream or smaller than {@link MIN_COMPRESS_BYTES}, or the runtime has no compression to offer.
+ */
+function compressibleBytes(body, headers) {
+    if (body === undefined || !runtime.isNode)
+        return undefined;
+    if (getHeader(headers, 'content-encoding') !== undefined)
+        return undefined;
+    if (!isCompressibleContentType(getHeader(headers, 'content-type')))
+        return undefined;
+    const bytes = toBytes(body);
+    return bytes && bytes.byteLength >= MIN_COMPRESS_BYTES ? bytes : undefined;
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function mediaType(contentType) {
+    return contentType?.split(';', 1)[0].trim().toLowerCase();
+}
+function isJsonContentType(contentType) {
+    return mediaType(contentType) === CONTENT_TYPE_JSON;
+}
+/**
+ * Serializes a request body and sets the `Content-Type` header a JSON body needs. Binary bodies become a `Buffer`
+ * in Node.js, sharing the memory of the value passed in, so the compressor can handle them.
+ */
+function serializeBody(data, headers, stringifyFunctions) {
+    if (data === undefined || data === null)
+        return undefined;
+    if (isStream(data))
+        return data;
+    if (isBuffer(data)) {
+        // The axios Node.js adapter refuses a body that is neither a `Buffer`, an `ArrayBuffer` nor a string.
+        if (!runtime.isNode || Buffer.isBuffer(data))
+            return data;
+        return ArrayBuffer.isView(data)
+            ? Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+            : Buffer.from(data);
+    }
+    // A string body is already serialized and goes out as it is. Parsing a JSON one to check that it is valid
+    // would cost about as much as serializing it did, for a body assembled from thousands of requests.
+    if (typeof data === 'string')
+        return data;
+    if (typeof data === 'object') {
+        if (data instanceof URLSearchParams) {
+            if (getHeader(headers, 'content-type') === undefined) {
+                headers['Content-Type'] = `${CONTENT_TYPE_FORM_URLENCODED};charset=utf-8`;
+            }
+            return data.toString();
+        }
+        // Refusing these is louder than the empty body the JSON fallback below would send.
+        const tag = objectTag(data);
+        if (UNSERIALIZABLE_OBJECT_TAGS.has(tag)) {
+            throw new TypeError(`Unsupported request body type: ${tag}`);
+        }
+        if (getHeader(headers, 'content-type') === undefined)
+            headers['Content-Type'] = CONTENT_TYPE_JSON;
+        const contentType = getHeader(headers, 'content-type');
+        if (mediaType(contentType) === CONTENT_TYPE_FORM_URLENCODED)
+            return toFormUrlEncoded(data);
+        const withFunctions = stringifyFunctions && isJsonContentType(contentType);
+        return JSON.stringify(data, withFunctions ? stringifyFunctionReplacer : undefined);
+    }
+    throw new TypeError(`Unsupported request body type: ${typeof data}`);
+}
+function objectTag(value) {
+    return Object.prototype.toString.call(value).slice('[object '.length, -1);
+}
+function stringifyFunctionReplacer(_key, value) {
+    return typeof value === 'function' ? value.toString() : value;
+}
+/**
+ * Form-encodes an object the way HTML forms and axios do: nested objects as `key[sub]`, arrays of plain values as
+ * repeated `key[]`, arrays holding objects or arrays as indexed `key[0]`, binary values base64-encoded, dates in
+ * ISO 8601, and `null` and `undefined` fields left out.
+ */
+function toFormUrlEncoded(data) {
+    const params = new URLSearchParams();
+    const append = (key, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (value instanceof Date)
+            params.append(key, value.toISOString());
+        else if (isBuffer(value))
+            params.append(key, binaryToBase64(value));
+        else if (Array.isArray(value)) {
+            // An item spanning several fields needs its own index, otherwise the items merge into one on the
+            // receiving side: `list[]=` twice reads back as a single object with an array-valued field.
+            const indexed = value.some(spansSeveralFields);
+            value.forEach((item, index) => append(indexed ? `${key}[${index}]` : `${key}[]`, item));
+        }
+        else if (typeof value === 'object') {
+            Object.entries(value).forEach(([sub, item]) => append(`${key}[${sub}]`, item));
+        }
+        else
+            params.append(key, String(value));
+    };
+    Object.entries(data).forEach(([key, value]) => append(key, value));
+    return params.toString();
+}
+function spansSeveralFields(value) {
+    if (Array.isArray(value))
+        return true;
+    return typeof value === 'object' && value !== null && !(value instanceof Date) && !isBuffer(value);
+}
+function binaryToBase64(value) {
+    const buffer = ArrayBuffer.isView(value)
+        ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+        : Buffer.from(value);
+    return buffer.toString('base64');
+}

package/dist/http_clients/index.d.ts

@@ -0,0 +1,4 @@
+export type { AxiosHttpClientOptions, RequestInterceptorFunction } from './axios.js';
+export { AxiosHttpClient } from './axios.js';
+export type { ApifyRequestConfig, ApifyResponse, ApifyResponseType, HttpClientOptions, HttpMethod, HttpRequest, HttpRequestBody, HttpResponse, HttpResponseBody, HttpResponseHeaders, } from './base.js';
+export { HttpClient } from './base.js';

package/dist/http_clients/index.js

@@ -0,0 +1,2 @@
+export { AxiosHttpClient } from './axios.js';
+export { HttpClient } from './base.js';

package/dist/http_compressors/base.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Strategy for compressing HTTP request bodies.
+ *
+ * Implement this interface to create a custom compressor. Set `contentEncoding` to the value that should be sent in
+ * the `Content-Encoding` header and implement `compress()`. The client calls it only for bodies that are large
+ * enough to benefit from compression, whose content type does not already carry its own compression, and which the
+ * caller did not send with a `Content-Encoding` of their own.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient } from 'apify-client';
+ *
+ * const identityCompressor = {
+ *     contentEncoding: 'identity',
+ *
+ *     async compress(data) {
+ *         return data;
+ *     },
+ * };
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: identityCompressor });
+ * ```
+ */
+export interface HttpCompressor {
+    /** Value sent in the `Content-Encoding` header, for example `gzip` or `br`. */
+    readonly contentEncoding: string;
+    /**
+     * Compresses a request body.
+     *
+     * @param data - The raw bytes to compress.
+     * @returns The compressed bytes.
+     */
+    compress(data: Buffer): Promise<Buffer>;
+}
+/**
+ * Schema accepting anything shaped like an {@link HttpCompressor}.
+ * @internal
+ */
+export declare const httpCompressorSchema: z.ZodCustom<HttpCompressor, HttpCompressor>;

package/dist/http_compressors/base.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/**
+ * Schema accepting anything shaped like an {@link HttpCompressor}.
+ * @internal
+ */
+export const httpCompressorSchema = z.custom((value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.contentEncoding === 'string' &&
+    typeof value.compress === 'function', { error: 'Invalid input: expected an HttpCompressor' });

package/dist/http_compressors/brotli.d.ts

@@ -0,0 +1,33 @@
+import type { HttpCompressor } from './base.js';
+/**
+ * Compresses request bodies using brotli.
+ *
+ * Built on the `node:zlib` module, so it works wherever the client runs on Node.js.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, BrotliHttpCompressor } from 'apify-client';
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: new BrotliHttpCompressor({ quality: 11 }) });
+ * ```
+ */
+export declare class BrotliHttpCompressor implements HttpCompressor {
+    #private;
+    readonly contentEncoding = "br";
+    /**
+     * @param options - Compressor options.
+     * @throws {ArgumentValidationError} If `quality` is out of the valid range.
+     */
+    constructor(options?: BrotliHttpCompressorOptions);
+    compress(data: Buffer): Promise<Buffer>;
+}
+/**
+ * Options for {@link BrotliHttpCompressor}.
+ */
+export interface BrotliHttpCompressorOptions {
+    /**
+     * Compression level, from `0` (the fastest) to `11` (the best compression).
+     * @default 6
+     */
+    quality?: number;
+}