apify-client 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/resource_clients/request_queue.js

@@ -1,23 +1,26 @@
 import { z } from 'zod';
 import { MAX_PAYLOAD_SIZE_BYTES, REQUEST_QUEUE_MAX_REQUESTS_PER_BATCH_OPERATION } from '@apify/consts';
 import log from '@apify/log';
-import { MEDIUM_TIMEOUT_MILLIS, ResourceClient, SMALL_TIMEOUT_MILLIS } from '../base/resource_client.js';
-import { anyObjectSchema, cast, catchNotFoundOrThrow, isNonArrayObject, mutuallyExclusive, parseArgument, parseDateFields, pluckData, RequestQueuePaginationIterator, sliceArrayByByteLength, } from '../utils.js';
+import { ResourceClient } from '../base/resource_client.js';
+import { ResponseValidationError } from '../response_validation_error.js';
+import * as schemas from '../schemas.js';
+import { optionalSignalSchema, optionalTimeoutSchema, timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
+import { anyObjectSchema, catchNotFoundOrThrow, isNonArrayObject, parseArgument, parseResponse, RequestQueuePaginationIterator, sleep, splitIntoJsonArrayBatches, utf8ByteLength, } from '../utils.js';
 const DEFAULT_PARALLEL_BATCH_ADD_REQUESTS = 5;
 const DEFAULT_UNPROCESSED_RETRIES_BATCH_ADD_REQUESTS = 3;
 const DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS = 500;
 const DEFAULT_REQUEST_QUEUE_REQUEST_PAGE_LIMIT = 1000;
 const SAFETY_BUFFER_PERCENT = 0.01 / 100; // 0.01%
-const listHeadOptionsSchema = z.strictObject({ limit: z.number().min(0).optional() });
+const listHeadOptionsSchema = z.strictObject({ limit: z.number().min(0).optional(), ...timeoutOptionsShape });
 const listAndLockHeadOptionsSchema = z.strictObject({
     lockSecs: z.number(),
     limit: z.number().min(0).optional(),
+    ...timeoutOptionsShape,
 });
 // Predicates, not `z.looseObject` arms: these run over a whole batch, and an object arm would copy
 // every key of every request. `id` is assigned by the API, so a new request must not carry one.
 const newRequestSchema = z.custom((value) => isNonArrayObject(value) && value.id === undefined, 'Expected a request object without an `id`');
-const forefrontOptionsSchema = z.strictObject({ forefront: z.boolean().optional() });
-const batchAddRequestsSchema = z.array(newRequestSchema).min(1).max(REQUEST_QUEUE_MAX_REQUESTS_PER_BATCH_OPERATION);
+const forefrontOptionsSchema = z.strictObject({ forefront: z.boolean().optional(), ...timeoutOptionsShape });
 const batchAddRequestsWithRetriesSchema = z.array(newRequestSchema).min(1);
 const optionalBooleanSchema = z.boolean().optional();
 const optionalNumberSchema = z.number().optional();
@@ -31,25 +34,22 @@ const existingRequestSchema = z.custom((value) => isNonArrayObject(value) && typ
 const prolongRequestLockOptionsSchema = z.strictObject({
     lockSecs: z.number(),
     forefront: z.boolean().optional(),
+    ...timeoutOptionsShape,
 });
 const requestFilterSchema = z.array(z.enum(['locked', 'pending'])).min(1);
-const listRequestsOptionsSchema = z
-    .strictObject({
+const listRequestsOptionsSchema = z.strictObject({
     limit: z.number().min(0).optional(),
-    exclusiveStartId: z.string().optional(),
     cursor: z.string().optional(),
     filter: requestFilterSchema.optional(),
-})
-    .refine(...mutuallyExclusive('exclusiveStartId', 'cursor'));
-const paginateRequestsOptionsSchema = z
-    .strictObject({
+    ...timeoutOptionsShape,
+});
+const paginateRequestsOptionsSchema = z.strictObject({
     limit: z.number().min(0).optional(),
     maxPageLimit: z.number().default(DEFAULT_REQUEST_QUEUE_REQUEST_PAGE_LIMIT),
-    exclusiveStartId: z.string().optional(),
     cursor: z.string().optional(),
     filter: requestFilterSchema.optional(),
-})
-    .refine(...mutuallyExclusive('exclusiveStartId', 'cursor'));
+    ...timeoutOptionsShape,
+});
 /**
  * Client for managing a specific Request queue.
  *
@@ -81,8 +81,8 @@ const paginateRequestsOptionsSchema = z
  * @see https://docs.apify.com/platform/storage/request-queue
  */
 export class RequestQueueClient extends ResourceClient {
-    clientKey;
-    timeoutMillis;
+    #clientKey;
+    #timeoutSecs;
     /**
      * @hidden
      */
@@ -91,36 +91,57 @@ export class RequestQueueClient extends ResourceClient {
             resourcePath: 'request-queues',
             ...options,
         });
-        this.clientKey = userOptions.clientKey;
-        this.timeoutMillis = userOptions.timeoutSecs ? userOptions.timeoutSecs * 1e3 : undefined;
+        this.#clientKey = userOptions.clientKey;
+        this.#timeoutSecs = userOptions.timeoutSecs;
+    }
+    /**
+     * Picks the timeout of a request: an explicit per-call `timeoutSecs` as is, otherwise the method's default
+     * tier, capped at the queue-wide `timeoutSecs` when one was given.
+     */
+    #resolveTimeout(timeoutSecs, defaultTier) {
+        if (timeoutSecs !== undefined)
+            return timeoutSecs;
+        if (this.#timeoutSecs === undefined)
+            return defaultTier;
+        const tierSecs = this.httpClient.timeoutMillis[defaultTier] / 1000;
+        return tierSecs <= this.#timeoutSecs ? defaultTier : this.#timeoutSecs;
     }
     /**
      * Gets the Request queue object from the Apify API.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The RequestQueue object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/request-queue-get
      */
-    async get() {
-        return this._get({}, SMALL_TIMEOUT_MILLIS);
+    async get(options = {}) {
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        return this.getResource(schemas.RequestQueue(), {}, this.#resolveTimeout(timeoutSecs, 'short'), signal);
     }
     /**
      * Updates the Request queue with specified fields.
      *
      * @param newFields - Fields to update in the Request queue
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated RequestQueue object
      * @see https://docs.apify.com/api/v2/request-queue-put
      */
-    async update(newFields) {
+    async update(newFields, options = {}) {
         parseArgument(newFields, anyObjectSchema);
-        return this._update(newFields, SMALL_TIMEOUT_MILLIS);
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        return this.updateResource(schemas.RequestQueue(), newFields, this.#resolveTimeout(timeoutSecs, 'short'), signal);
     }
     /**
      * Deletes the Request queue.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/request-queue-delete
      */
-    async delete() {
-        return this._delete(SMALL_TIMEOUT_MILLIS);
+    async delete(options = {}) {
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        return this.deleteResource(this.#resolveTimeout(timeoutSecs, 'short'), signal);
     }
     /**
      * Lists requests from the beginning of the queue (head).
@@ -129,21 +150,24 @@ export class RequestQueueClient extends ResourceClient {
      * inspecting what requests are waiting to be processed.
      *
      * @param options - Options for listing (e.g., limit)
+     * @param options.limit - Maximum number of requests to return.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns List of requests from the queue head
      * @see https://docs.apify.com/api/v2/request-queue-head-get
      */
     async listHead(options = {}) {
         const parsed = parseArgument(options, listHeadOptionsSchema, 'RequestQueueClientListHeadOptions');
         const response = await this.httpClient.call({
-            url: this._url('head'),
+            url: this.buildUrl('head'),
             method: 'GET',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'short'),
+            signal: parsed.signal,
+            params: this.buildParams({
                 limit: parsed.limit,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.RequestQueueHead());
     }
     /**
      * Gets and locks the next requests from the queue head for processing.
@@ -157,6 +181,7 @@ export class RequestQueueClient extends ResourceClient {
      * @param options - Lock configuration
      * @param options.lockSecs - **Required.** Duration in seconds to lock the requests. After this time, the locks expire and requests can be retrieved by other clients.
      * @param options.limit - Maximum number of requests to return. Default is 25.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns Object containing `items` (locked requests), `queueModifiedAt`, `hadMultipleClients`, and lock information
      * @see https://docs.apify.com/api/v2/request-queue-head-lock-post
      *
@@ -181,16 +206,17 @@ export class RequestQueueClient extends ResourceClient {
     async listAndLockHead(options) {
         const parsed = parseArgument(options, listAndLockHeadOptionsSchema, 'RequestQueueClientListAndLockHeadOptions');
         const response = await this.httpClient.call({
-            url: this._url('head/lock'),
+            url: this.buildUrl('head/lock'),
             method: 'POST',
-            timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'medium'),
+            signal: parsed.signal,
+            params: this.buildParams({
                 limit: parsed.limit,
                 lockSecs: parsed.lockSecs,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.LockedRequestQueueHead());
     }
     /**
      * Adds a single request to the queue.
@@ -208,6 +234,7 @@ export class RequestQueueClient extends ResourceClient {
      * @param request.payload - HTTP payload for POST/PUT requests (string).
      * @param options - Additional options
      * @param options.forefront - If `true`, adds the request to the beginning of the queue. Default is `false` (adds to the end).
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns Object with `requestId`, `wasAlreadyPresent`, and `wasAlreadyHandled` flags
      * @see https://docs.apify.com/api/v2/request-queue-requests-post
      *
@@ -234,39 +261,43 @@ export class RequestQueueClient extends ResourceClient {
         parseArgument(request, newRequestSchema);
         const parsed = parseArgument(options, forefrontOptionsSchema, 'RequestQueueClientAddRequestOptions');
         const response = await this.httpClient.call({
-            url: this._url('requests'),
+            url: this.buildUrl('requests'),
             method: 'POST',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'short'),
+            signal: parsed.signal,
             data: request,
-            params: this._params({
+            params: this.buildParams({
                 forefront: parsed.forefront,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.RequestRegistration());
     }
     /**
      * Writes requests to Request queue in batch.
      *
      * @private
      */
-    async _batchAddRequests(requests, options = {}) {
-        parseArgument(requests, batchAddRequestsSchema);
+    async addRequestBatch(requests, options = {}) {
         const parsed = parseArgument(options, forefrontOptionsSchema, 'RequestQueueClientAddRequestOptions');
-        const { data } = await this.httpClient.call({
-            url: this._url('requests/batch'),
+        const response = await this.httpClient.call({
+            url: this.buildUrl('requests/batch'),
             method: 'POST',
-            timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            data: requests,
-            params: this._params({
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'medium'),
+            signal: parsed.signal,
+            // The body is assembled from the requests as `batchAddRequests` serialized them; the explicit content type
+            // makes the request interceptor send the string as it is instead of serializing the requests again.
+            headers: { 'content-type': 'application/json' },
+            data: `[${requests.map(({ json }) => json).join(',')}]`,
+            params: this.buildParams({
                 forefront: parsed.forefront,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(data)));
+        return parseResponse(response, schemas.BatchAddResult());
     }
-    async _batchAddRequestsWithRetries(requests, options = {}) {
-        const { forefront, maxUnprocessedRequestsRetries = DEFAULT_UNPROCESSED_RETRIES_BATCH_ADD_REQUESTS, minDelayBetweenUnprocessedRequestsRetriesMillis = DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS, } = options;
+    async addRequestBatchWithRetries(requests, options = {}) {
+        const { forefront, timeoutSecs, signal, maxUnprocessedRequestsRetries = DEFAULT_UNPROCESSED_RETRIES_BATCH_ADD_REQUESTS, minDelayBetweenUnprocessedRequestsRetriesMillis = DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS, } = options;
         // Keep track of the requests that remain to be processed (in parameter format)
         let remainingRequests = requests;
         // Keep track of the requests that have been processed (in api format)
@@ -276,8 +307,10 @@ export class RequestQueueClient extends ResourceClient {
         let unprocessedRequests = [];
         for (let i = 0; i < 1 + maxUnprocessedRequestsRetries; i++) {
             try {
-                const response = await this._batchAddRequests(remainingRequests, {
+                const response = await this.addRequestBatch(remainingRequests, {
                     forefront,
+                    timeoutSecs,
+                    signal,
                 });
                 processedRequests.push(...response.processedRequests);
                 unprocessedRequests = response.unprocessedRequests;
@@ -289,30 +322,34 @@ export class RequestQueueClient extends ResourceClient {
                 // Get unique keys of all requests processed so far
                 const processedRequestsUniqueKeys = processedRequests.map(({ uniqueKey }) => uniqueKey);
                 // Requests remaining to be processed are the all that remain
-                remainingRequests = requests.filter(({ uniqueKey }) => !processedRequestsUniqueKeys.includes(uniqueKey));
+                remainingRequests = requests.filter(({ request }) => !processedRequestsUniqueKeys.includes(request.uniqueKey));
                 // Stop if all requests have been processed
                 if (remainingRequests.length === 0) {
                     break;
                 }
             }
             catch (err) {
+                // An abort rejects the whole call, since the caller asked to stop and not for a partial result.
+                signal?.throwIfAborted();
+                // A response the specification does not describe is reported, as everywhere else: the server may well
+                // have added the batch, so calling it unprocessed would hide the mismatch behind a wrong answer.
+                if (err instanceof ResponseValidationError)
+                    throw err;
                 log.exception(err, 'Request batch insert failed');
                 // When something fails and http client does not retry, the remaining requests are treated as unprocessed.
                 // This ensures that this method does not throw and keeps the signature.
                 const processedRequestsUniqueKeys = processedRequests.map(({ uniqueKey }) => uniqueKey);
                 unprocessedRequests = requests
-                    .filter(({ uniqueKey }) => !processedRequestsUniqueKeys.includes(uniqueKey))
-                    .map(({ method, uniqueKey, url }) => ({ method, uniqueKey, url }));
+                    .filter(({ request }) => !processedRequestsUniqueKeys.includes(request.uniqueKey))
+                    .map(({ request: { method, uniqueKey, url } }) => ({ method, uniqueKey, url }));
                 break;
             }
             // Exponential backoff
             const delayMillis = Math.floor((1 + Math.random()) * 2 ** i * minDelayBetweenUnprocessedRequestsRetriesMillis);
-            await new Promise((resolve) => {
-                setTimeout(resolve, delayMillis);
-            });
+            await sleep(delayMillis, signal);
+            signal?.throwIfAborted();
         }
-        const result = { processedRequests, unprocessedRequests };
-        return cast(parseDateFields(result));
+        return { processedRequests, unprocessedRequests };
     }
     /**
      * Adds multiple requests to the queue in a single operation.
@@ -329,6 +366,7 @@ export class RequestQueueClient extends ResourceClient {
      * @param options.maxUnprocessedRequestsRetries - Maximum number of retry attempts for rate-limited requests. Default is 3.
      * @param options.maxParallel - Maximum number of parallel batch API calls. Default is 5.
      * @param options.minDelayBetweenUnprocessedRequestsRetriesMillis - Minimum delay before retrying rate-limited requests. Default is 500ms.
+     * @param options.timeoutSecs - Timeout for each batch API request. Default is `'medium'`.
      * @returns Object with `processedRequests` (successfully added) and `unprocessedRequests` (failed after all retries)
      * @see https://docs.apify.com/api/v2/request-queue-requests-batch-post
      *
@@ -353,30 +391,46 @@ export class RequestQueueClient extends ResourceClient {
      * @since Added in 2.1.0
      */
     async batchAddRequests(requests, options = {}) {
-        const { forefront, maxUnprocessedRequestsRetries = DEFAULT_UNPROCESSED_RETRIES_BATCH_ADD_REQUESTS, maxParallel = DEFAULT_PARALLEL_BATCH_ADD_REQUESTS, minDelayBetweenUnprocessedRequestsRetriesMillis = DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS, } = options;
+        const { forefront, timeoutSecs, signal, maxUnprocessedRequestsRetries = DEFAULT_UNPROCESSED_RETRIES_BATCH_ADD_REQUESTS, maxParallel = DEFAULT_PARALLEL_BATCH_ADD_REQUESTS, minDelayBetweenUnprocessedRequestsRetriesMillis = DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS, } = options;
         parseArgument(requests, batchAddRequestsWithRetriesSchema);
         parseArgument(forefront, optionalBooleanSchema);
+        parseArgument(timeoutSecs, optionalTimeoutSchema);
+        parseArgument(signal, optionalSignalSchema);
         parseArgument(maxUnprocessedRequestsRetries, optionalNumberSchema);
         parseArgument(maxParallel, optionalNumberSchema);
         parseArgument(minDelayBetweenUnprocessedRequestsRetriesMillis, optionalNumberSchema);
         const executingRequests = new Set();
         const individualResults = [];
         const payloadSizeLimitBytes = MAX_PAYLOAD_SIZE_BYTES - Math.ceil(MAX_PAYLOAD_SIZE_BYTES * SAFETY_BUFFER_PERCENT);
+        // Serialize every request once: the byte lengths decide the batch boundaries, and the same strings are joined
+        // into the batch bodies, so nothing is stringified a second time when it is sent.
+        const serializedRequests = requests.map((request, index) => {
+            const json = JSON.stringify(request);
+            const byteLength = utf8ByteLength(json);
+            // Two more bytes for the brackets, which even a batch of one request carries.
+            if (byteLength + 2 > payloadSizeLimitBytes) {
+                throw new Error(`RequestQueueClient.batchAddRequests: The size of the request with index: ${index} ` +
+                    `exceeds the maximum allowed size (${payloadSizeLimitBytes} bytes).`);
+            }
+            return { request, json, byteLength };
+        });
+        const batches = splitIntoJsonArrayBatches(serializedRequests, {
+            maxCount: REQUEST_QUEUE_MAX_REQUESTS_PER_BATCH_OPERATION,
+            maxByteLength: payloadSizeLimitBytes,
+        });
         // Keep a pool of up to `maxParallel` requests running at once
-        let i = 0;
-        while (i < requests.length) {
-            const slicedRequests = requests.slice(i, i + REQUEST_QUEUE_MAX_REQUESTS_PER_BATCH_OPERATION);
-            const requestsInBatch = sliceArrayByByteLength(slicedRequests, payloadSizeLimitBytes, i);
-            const requestPromise = this._batchAddRequestsWithRetries(requestsInBatch, options);
+        for (const batch of batches) {
+            const requestPromise = this.addRequestBatchWithRetries(batch, options);
             executingRequests.add(requestPromise);
+            // A rejection reaches the caller through the awaits below; this bookkeeping chain only has to avoid
+            // turning it into an unhandled one of its own.
             void requestPromise.then((batchAddResult) => {
                 executingRequests.delete(requestPromise);
                 individualResults.push(batchAddResult);
-            });
+            }, () => undefined);
             if (executingRequests.size >= maxParallel) {
                 await Promise.race(executingRequests);
             }
-            i += requestsInBatch.length;
         }
         // Get results from remaining operations
         await Promise.all(executingRequests);
@@ -397,41 +451,49 @@ export class RequestQueueClient extends ResourceClient {
      * Requests can be identified by either their ID or unique key.
      *
      * @param requests - Array of requests to delete (by id or uniqueKey)
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns Result containing processed and unprocessed requests
      * @see https://docs.apify.com/api/v2/request-queue-requests-batch-delete
      * @since Added in 2.3.0
      */
-    async batchDeleteRequests(requests) {
+    async batchDeleteRequests(requests, options = {}) {
         parseArgument(requests, batchDeleteRequestsSchema);
-        const { data } = await this.httpClient.call({
-            url: this._url('requests/batch'),
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        const response = await this.httpClient.call({
+            url: this.buildUrl('requests/batch'),
             method: 'DELETE',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
+            timeoutSecs: this.#resolveTimeout(timeoutSecs, 'short'),
+            signal,
             data: requests,
-            params: this._params({
-                clientKey: this.clientKey,
+            params: this.buildParams({
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(data)));
+        return parseResponse(response, schemas.BatchDeleteResult());
     }
     /**
      * Gets a specific request from the queue by its ID.
      *
      * @param id - Request ID
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The request object, or `undefined` if not found
      * @see https://docs.apify.com/api/v2/request-queue-request-get
      */
-    async getRequest(id) {
+    async getRequest(id, options = {}) {
         parseArgument(id, requestIdSchema);
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
         const requestOpts = {
-            url: this._url(['requests', id]),
+            url: this.buildUrl(['requests', id]),
             method: 'GET',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params(),
+            timeoutSecs: this.#resolveTimeout(timeoutSecs, 'short'),
+            signal,
+            params: this.buildParams(),
         };
         try {
             const response = await this.httpClient.call(requestOpts);
-            return cast(parseDateFields(pluckData(response.data)));
+            return parseResponse(response, schemas.Request());
         }
         catch (err) {
             catchNotFoundOrThrow(err);
@@ -443,6 +505,8 @@ export class RequestQueueClient extends ResourceClient {
      *
      * @param request - The updated request object (must include id)
      * @param options - Update options such as whether to move to front
+     * @param options.forefront - If `true`, moves the request to the beginning of the queue. Default is `false`.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns Information about the updated request
      * @see https://docs.apify.com/api/v2/request-queue-request-put
      */
@@ -450,30 +514,35 @@ export class RequestQueueClient extends ResourceClient {
         parseArgument(request, existingRequestSchema);
         const parsed = parseArgument(options, forefrontOptionsSchema, 'RequestQueueClientAddRequestOptions');
         const response = await this.httpClient.call({
-            url: this._url(['requests', request.id]),
+            url: this.buildUrl(['requests', request.id]),
             method: 'PUT',
-            timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'medium'),
+            signal: parsed.signal,
             data: request,
-            params: this._params({
+            params: this.buildParams({
                 forefront: parsed.forefront,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.RequestRegistration());
     }
     /**
      * Deletes a specific request from the queue.
      *
      * @param id - Request ID
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      */
-    async deleteRequest(id) {
+    async deleteRequest(id, options = {}) {
         parseArgument(id, requestIdSchema);
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
         await this.httpClient.call({
-            url: this._url(['requests', id]),
+            url: this.buildUrl(['requests', id]),
             method: 'DELETE',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
-                clientKey: this.clientKey,
+            timeoutSecs: this.#resolveTimeout(timeoutSecs, 'short'),
+            signal,
+            params: this.buildParams({
+                clientKey: this.#clientKey,
             }),
         });
     }
@@ -488,6 +557,7 @@ export class RequestQueueClient extends ResourceClient {
      * @param options - Lock extension options
      * @param options.lockSecs - **Required.** New lock duration in seconds from now.
      * @param options.forefront - If `true`, moves the request to the beginning of the queue when the lock expires. Default is `false`.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns Object with new `lockExpiresAt` timestamp
      * @see https://docs.apify.com/api/v2/request-queue-request-lock-put
      *
@@ -506,16 +576,17 @@ export class RequestQueueClient extends ResourceClient {
         parseArgument(id, requestIdSchema);
         const parsed = parseArgument(options, prolongRequestLockOptionsSchema, 'RequestQueueClientProlongRequestLockOptions');
         const response = await this.httpClient.call({
-            url: this._url(['requests', id, 'lock']),
+            url: this.buildUrl(['requests', id, 'lock']),
             method: 'PUT',
-            timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'medium'),
+            signal: parsed.signal,
+            params: this.buildParams({
                 forefront: parsed.forefront,
                 lockSecs: parsed.lockSecs,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.RequestLockInfo());
     }
     /**
      * Releases the lock on a request, allowing other clients to process it.
@@ -525,6 +596,8 @@ export class RequestQueueClient extends ResourceClient {
      *
      * @param id - Request ID
      * @param options - Options such as whether to move to front
+     * @param options.forefront - If `true`, moves the request to the beginning of the queue. Default is `false`.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/request-queue-request-lock-delete
      * @since Added in 2.4.1
      */
@@ -532,12 +605,13 @@ export class RequestQueueClient extends ResourceClient {
         parseArgument(id, requestIdSchema);
         const parsed = parseArgument(options, forefrontOptionsSchema, 'RequestQueueClientDeleteRequestLockOptions');
         await this.httpClient.call({
-            url: this._url(['requests', id, 'lock']),
+            url: this.buildUrl(['requests', id, 'lock']),
             method: 'DELETE',
-            timeout: Math.min(SMALL_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
+            timeoutSecs: this.#resolveTimeout(parsed.timeoutSecs, 'short'),
+            signal: parsed.signal,
+            params: this.buildParams({
                 forefront: parsed.forefront,
-                clientKey: this.clientKey,
+                clientKey: this.#clientKey,
             }),
         });
     }
@@ -548,24 +622,29 @@ export class RequestQueueClient extends ResourceClient {
      * queue contents.
      *
      * @param options - Pagination options
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns List of requests with pagination information
      * @see https://docs.apify.com/api/v2/request-queue-requests-get
      * @since Added in 2.5.1
      */
     listRequests(options = {}) {
-        const parsed = parseArgument(options, listRequestsOptionsSchema, 'RequestQueueClientListRequestsOptions');
+        // `timeoutSecs` and `signal` apply to every page request; they are not API parameters, so they must not reach
+        // the query string.
+        const { timeoutSecs, signal, ...parsed } = parseArgument(options, listRequestsOptionsSchema, 'RequestQueueClientListRequestsOptions');
+        const pageTimeout = this.#resolveTimeout(timeoutSecs, 'medium');
         const getPaginatedList = async (rqListOptions = {}) => {
             const response = await this.httpClient.call({
-                url: this._url('requests'),
+                url: this.buildUrl('requests'),
                 method: 'GET',
-                timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-                params: this._params({
+                timeoutSecs: pageTimeout,
+                signal,
+                params: this.buildParams({
                     ...rqListOptions,
                     filter: rqListOptions.filter ? rqListOptions.filter.join(',') : undefined,
-                    clientKey: this.clientKey,
+                    clientKey: this.#clientKey,
                 }),
             });
-            return cast(parseDateFields(pluckData(response.data)));
+            return parseResponse(response, schemas.ListOfRequests());
         };
         const paginatedListPromise = getPaginatedList(parsed);
         async function* asyncGenerator() {
@@ -581,8 +660,6 @@ export class RequestQueueClient extends ResourceClient {
                 const newOptions = {
                     ...parsed,
                     limit: remainingItems,
-                    // remove original exclusiveStartId, if there was any, and use cursor-based pagination
-                    exclusiveStartId: undefined,
                     cursor: currentPage.nextCursor,
                 };
                 currentPage = await getPaginatedList(newOptions);
@@ -602,20 +679,24 @@ export class RequestQueueClient extends ResourceClient {
      * This is useful for releasing all locks at once, for example when shutting down
      * a crawler gracefully.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @returns Number of requests that were unlocked
      * @see https://docs.apify.com/api/v2/request-queue-requests-unlock-post
      * @since Added in 2.12.5
      */
-    async unlockRequests() {
+    async unlockRequests(options = {}) {
+        const { timeoutSecs, signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
         const response = await this.httpClient.call({
-            url: this._url('requests/unlock'),
+            url: this.buildUrl('requests/unlock'),
             method: 'POST',
-            timeout: Math.min(MEDIUM_TIMEOUT_MILLIS, this.timeoutMillis ?? Infinity),
-            params: this._params({
-                clientKey: this.clientKey,
+            timeoutSecs: this.#resolveTimeout(timeoutSecs, 'long'),
+            signal,
+            params: this.buildParams({
+                clientKey: this.#clientKey,
             }),
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.UnlockRequestsResult());
     }
     /**
      * Returns an async iterable for paginating through all requests in the queue.
@@ -624,6 +705,7 @@ export class RequestQueueClient extends ResourceClient {
      * automatically handling pagination behind the scenes.
      *
      * @param options - Pagination options
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns An async iterable of request pages
      * @see https://docs.apify.com/api/v2/request-queue-requests-get
      *
@@ -636,11 +718,10 @@ export class RequestQueueClient extends ResourceClient {
      * @since Added in 2.5.1
      */
     paginateRequests(options = {}) {
-        const { limit, exclusiveStartId, cursor, filter, maxPageLimit } = parseArgument(options, paginateRequestsOptionsSchema, 'RequestQueueClientPaginateRequestsOptions');
+        const { limit, cursor, filter, maxPageLimit, timeoutSecs, signal } = parseArgument(options, paginateRequestsOptionsSchema, 'RequestQueueClientPaginateRequestsOptions');
         return new RequestQueuePaginationIterator({
-            getPage: async (pageOptions) => this.listRequests({ ...pageOptions, filter }),
+            getPage: async (pageOptions) => this.listRequests({ ...pageOptions, filter, timeoutSecs, signal }),
             limit,
-            exclusiveStartId,
             cursor,
             maxPageLimit,
         });