apify-client 3.0.0-beta.6 → 3.0.0-beta.60

package/dist/resource_clients/request_queue.d.ts

@@ -1,8 +1,18 @@
 import type { STORAGE_GENERAL_ACCESS } from '@apify/consts';
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
-import type { RequestQueue, RequestQueueClientAddRequestResult, RequestQueueClientBatchDeleteRequestsResult, RequestQueueClientBatchRequestsOperationResult, RequestQueueClientListAndLockHeadResult, RequestQueueClientListHeadResult, RequestQueueClientListRequestsResult, RequestQueueClientProlongRequestLockResult, RequestQueueClientRequestSchema, RequestQueueClientRequestToAdd, RequestQueueClientRequestToUpdate, RequestQueueClientUnlockRequestsResult } from '../models.js';
-export type { AllowedHttpMethods, RequestQueue, RequestQueueClientAddRequestResult, RequestQueueClientBatchDeleteRequestsResult, RequestQueueClientBatchRequestsOperationResult, RequestQueueClientListAndLockHeadResult, RequestQueueClientListHeadResult, RequestQueueClientListItem, RequestQueueClientListRequestsResult, RequestQueueClientLockedListItem, RequestQueueClientProlongRequestLockResult, RequestQueueClientRequestSchema, RequestQueueClientRequestToAdd, RequestQueueClientRequestToUpdate, RequestQueueClientUnlockRequestsResult, RequestQueueStats, } from '../models.js';
+import type { BatchAddResult, BatchDeleteResult, ListOfRequests, LockedRequestQueueHead, RequestResource, RequestLockInfo, RequestQueueResource, RequestQueueClientRequestToAdd, RequestQueueClientRequestToUpdate, RequestQueueHead, RequestRegistration, UnlockRequestsResult } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
+/**
+ * A request to add, serialized once up front: `byteLength` decides which batch it goes into, `json` is what the body of
+ * that batch is assembled from, and `request` is what the result bookkeeping needs.
+ */
+interface SerializedRequestToAdd {
+    request: RequestQueueClientRequestToAdd;
+    json: string;
+    byteLength: number;
+}
+export type { HttpMethod, BatchAddResult, BatchDeleteResult, RequestQueueHeadItem, ListOfRequests, LockedRequestQueueHeadItem, LockedRequestQueueHead, RequestResource, RequestLockInfo, RequestQueueResource, RequestQueueClientRequestToAdd, RequestQueueClientRequestToUpdate, RequestQueueHead, RequestQueueStats, RequestRegistration, UnlockRequestsResult, } from '../models.js';
 /**
  * Client for managing a specific Request queue.
  *
@@ -34,8 +44,7 @@ export type { AllowedHttpMethods, RequestQueue, RequestQueueClientAddRequestResu
  * @see https://docs.apify.com/platform/storage/request-queue
  */
 export declare class RequestQueueClient extends ResourceClient {
-    private clientKey?;
-    private timeoutMillis?;
+    #private;
     /**
      * @hidden
      */
@@ -43,24 +52,30 @@ export declare class RequestQueueClient extends ResourceClient {
     /**
      * 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
      */
-    get(): Promise<RequestQueue | undefined>;
+    get(options?: TimeoutOptions): Promise<RequestQueueResource | undefined>;
     /**
      * 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
      */
-    update(newFields: RequestQueueClientUpdateOptions): Promise<RequestQueue>;
+    update(newFields: RequestQueueClientUpdateOptions, options?: TimeoutOptions): Promise<RequestQueueResource>;
     /**
      * 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
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Lists requests from the beginning of the queue (head).
      *
@@ -68,10 +83,12 @@ export declare 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
      */
-    listHead(options?: RequestQueueClientListHeadOptions): Promise<RequestQueueClientListHeadResult>;
+    listHead(options?: RequestQueueClientListHeadOptions): Promise<RequestQueueHead>;
     /**
      * Gets and locks the next requests from the queue head for processing.
      *
@@ -84,6 +101,7 @@ export declare 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
      *
@@ -105,7 +123,7 @@ export declare class RequestQueueClient extends ResourceClient {
      * ```
      * @since Added in 2.4.1
      */
-    listAndLockHead(options: RequestQueueClientListAndLockHeadOptions): Promise<RequestQueueClientListAndLockHeadResult>;
+    listAndLockHead(options: RequestQueueClientListAndLockHeadOptions): Promise<LockedRequestQueueHead>;
     /**
      * Adds a single request to the queue.
      *
@@ -122,6 +140,7 @@ export declare 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
      *
@@ -144,14 +163,14 @@ export declare class RequestQueueClient extends ResourceClient {
      * );
      * ```
      */
-    addRequest(request: RequestQueueClientRequestToAdd, options?: RequestQueueClientAddRequestOptions): Promise<RequestQueueClientAddRequestResult>;
+    addRequest(request: RequestQueueClientRequestToAdd, options?: RequestQueueClientAddRequestOptions): Promise<RequestRegistration>;
     /**
      * Writes requests to Request queue in batch.
      *
      * @private
      */
-    protected _batchAddRequests(requests: RequestQueueClientRequestToAdd[], options?: RequestQueueClientAddRequestOptions): Promise<RequestQueueClientBatchRequestsOperationResult>;
-    protected _batchAddRequestsWithRetries(requests: RequestQueueClientRequestToAdd[], options?: RequestQueueClientBatchAddRequestWithRetriesOptions): Promise<RequestQueueClientBatchRequestsOperationResult>;
+    protected addRequestBatch(requests: SerializedRequestToAdd[], options?: RequestQueueClientAddRequestOptions): Promise<BatchAddResult>;
+    protected addRequestBatchWithRetries(requests: SerializedRequestToAdd[], options?: RequestQueueClientBatchAddRequestWithRetriesOptions): Promise<BatchAddResult>;
     /**
      * Adds multiple requests to the queue in a single operation.
      *
@@ -167,6 +186,7 @@ export declare 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
      *
@@ -190,41 +210,49 @@ export declare class RequestQueueClient extends ResourceClient {
      * ```
      * @since Added in 2.1.0
      */
-    batchAddRequests(requests: RequestQueueClientRequestToAdd[], options?: RequestQueueClientBatchAddRequestWithRetriesOptions): Promise<RequestQueueClientBatchRequestsOperationResult>;
+    batchAddRequests(requests: RequestQueueClientRequestToAdd[], options?: RequestQueueClientBatchAddRequestWithRetriesOptions): Promise<BatchAddResult>;
     /**
      * Deletes multiple requests from the queue in a single operation.
      *
      * 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
      */
-    batchDeleteRequests(requests: RequestQueueClientRequestToDelete[]): Promise<RequestQueueClientBatchDeleteRequestsResult>;
+    batchDeleteRequests(requests: RequestQueueClientRequestToDelete[], options?: TimeoutOptions): Promise<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
      */
-    getRequest(id: string): Promise<RequestQueueClientGetRequestResult | undefined>;
+    getRequest(id: string, options?: TimeoutOptions): Promise<RequestQueueClientGetRequestResult | undefined>;
     /**
      * Updates a request in the queue.
      *
      * @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
      */
-    updateRequest(request: RequestQueueClientRequestToUpdate, options?: RequestQueueClientAddRequestOptions): Promise<RequestQueueClientAddRequestResult>;
+    updateRequest(request: RequestQueueClientRequestToUpdate, options?: RequestQueueClientAddRequestOptions): Promise<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'`.
      */
-    deleteRequest(id: string): Promise<void>;
+    deleteRequest(id: string, options?: TimeoutOptions): Promise<void>;
     /**
      * Prolongs the lock on a request to prevent it from being returned to other clients.
      *
@@ -236,6 +264,7 @@ export declare 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
      *
@@ -250,7 +279,7 @@ export declare class RequestQueueClient extends ResourceClient {
      * ```
      * @since Added in 2.4.1
      */
-    prolongRequestLock(id: string, options: RequestQueueClientProlongRequestLockOptions): Promise<RequestQueueClientProlongRequestLockResult>;
+    prolongRequestLock(id: string, options: RequestQueueClientProlongRequestLockOptions): Promise<RequestLockInfo>;
     /**
      * Releases the lock on a request, allowing other clients to process it.
      *
@@ -259,6 +288,8 @@ export declare 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
      */
@@ -270,22 +301,27 @@ export declare class RequestQueueClient extends ResourceClient {
      * queue contents.
      *
      * @param options - Pagination options
+     * @param options.chunkSize - Maximum number of requests fetched per API call when iterating across pages. `limit`
+     *   then caps the total across all pages.
+     * @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?: RequestQueueClientListRequestsOptions): Promise<RequestQueueClientListRequestsResult> & AsyncIterable<RequestQueueClientRequestSchema>;
+    listRequests(options?: RequestQueueClientListRequestsOptions): Promise<ListOfRequests> & AsyncIterable<RequestResource>;
     /**
      * Unlocks all requests locked by this client.
      *
      * 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
      */
-    unlockRequests(): Promise<RequestQueueClientUnlockRequestsResult>;
+    unlockRequests(options?: TimeoutOptions): Promise<UnlockRequestsResult>;
     /**
      * Returns an async iterable for paginating through all requests in the queue.
      *
@@ -293,6 +329,7 @@ export declare 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
      *
@@ -304,7 +341,7 @@ export declare class RequestQueueClient extends ResourceClient {
      * ```
      * @since Added in 2.5.1
      */
-    paginateRequests(options?: RequestQueueClientPaginateRequestsOptions): RequestQueueRequestsAsyncIterable<RequestQueueClientListRequestsResult>;
+    paginateRequests(options?: RequestQueueClientPaginateRequestsOptions): RequestQueueRequestsAsyncIterable<ListOfRequests>;
 }
 /**
  * User-specific options for RequestQueueClient.
@@ -312,6 +349,8 @@ export declare class RequestQueueClient extends ResourceClient {
 export interface RequestQueueUserOptions {
     clientKey?: string;
     /**
+     * Cap, in seconds, on the default timeout tier of every request this client sends. An explicit per-call
+     * `timeoutSecs` is not capped.
      * @since Added in 2.2.0
      */
     timeoutSecs?: number;
@@ -333,7 +372,7 @@ export interface RequestQueueClientUpdateOptions {
 /**
  * Options for listing requests from the queue head.
  */
-export interface RequestQueueClientListHeadOptions {
+export interface RequestQueueClientListHeadOptions extends TimeoutOptions {
     limit?: number;
 }
 /**
@@ -344,13 +383,14 @@ export type RequestQueueListRequestsFilter = 'locked' | 'pending';
  * Options for listing all requests in the queue.
  * @since Added in 2.5.1
  */
-export interface RequestQueueClientListRequestsOptions {
+export interface RequestQueueClientListRequestsOptions extends TimeoutOptions {
     limit?: number;
     /**
-     * Using id of request that does not exist in request queue leads to unpredictable results.
-     * @deprecated Use `cursor` for pagination instead.
+     * Maximum number of requests returned in one API response. When the call is iterated with `for await`, the iterator
+     * fetches requests in chunks of this size and yields them one by one, until `limit` is reached or the RQ is
+     * exhausted. Awaiting the call returns only the first chunk.
      */
-    exclusiveStartId?: string;
+    chunkSize?: number;
     /**
      * @since Added in 2.23.2
      */
@@ -364,11 +404,9 @@ export interface RequestQueueClientListRequestsOptions {
  * Options for paginating through requests in the queue.
  * @since Added in 2.5.1
  */
-export interface RequestQueueClientPaginateRequestsOptions {
+export interface RequestQueueClientPaginateRequestsOptions extends TimeoutOptions {
     limit?: number;
     maxPageLimit?: number;
-    /** @deprecated Use `cursor` for pagination instead. */
-    exclusiveStartId?: string;
     /**
      * @since Added in 2.23.2
      */
@@ -382,30 +420,30 @@ export interface RequestQueueClientPaginateRequestsOptions {
  * Options for listing and locking requests from the queue head.
  * @since Added in 2.4.1
  */
-export interface RequestQueueClientListAndLockHeadOptions {
+export interface RequestQueueClientListAndLockHeadOptions extends TimeoutOptions {
     lockSecs: number;
     limit?: number;
 }
-export interface RequestQueueClientAddRequestOptions {
+export interface RequestQueueClientAddRequestOptions extends TimeoutOptions {
     forefront?: boolean;
 }
 /**
  * @since Added in 2.4.1
  */
-export interface RequestQueueClientProlongRequestLockOptions {
+export interface RequestQueueClientProlongRequestLockOptions extends TimeoutOptions {
     forefront?: boolean;
     lockSecs: number;
 }
 /**
  * @since Added in 2.4.1
  */
-export interface RequestQueueClientDeleteRequestLockOptions {
+export interface RequestQueueClientDeleteRequestLockOptions extends TimeoutOptions {
     forefront?: boolean;
 }
 /**
  * @since Added in 2.3.0
  */
-export interface RequestQueueClientBatchAddRequestWithRetriesOptions {
+export interface RequestQueueClientBatchAddRequestWithRetriesOptions extends TimeoutOptions {
     forefront?: boolean;
     maxUnprocessedRequestsRetries?: number;
     maxParallel?: number;
@@ -417,14 +455,14 @@ export interface RequestQueueClientBatchAddRequestWithRetriesOptions {
 /**
  * @since Added in 2.3.0
  */
-export type RequestQueueClientRequestToDelete = Pick<RequestQueueClientRequestSchema, 'id'> | Pick<RequestQueueClientRequestSchema, 'uniqueKey'>;
+export type RequestQueueClientRequestToDelete = Pick<RequestResource, 'id'> | Pick<RequestResource, 'uniqueKey'>;
 /**
  * Result of getting a single request from the queue.
  *
  * `GET /v2/request-queues/{queueId}/requests/{requestId}` answers with the whole request rather than
  * a queue-head projection.
  */
-export type RequestQueueClientGetRequestResult = RequestQueueClientRequestSchema;
+export type RequestQueueClientGetRequestResult = RequestResource;
 /**
  * @since Added in 2.5.1
  */