apify-client 3.0.0-beta.5 → 3.0.0-beta.50

package/dist/resource_clients/request_queue_collection.js

@@ -2,12 +2,14 @@ import { z } from 'zod';
 import { STORAGE_OWNERSHIP_FILTER } from '@apify/consts';
 import { ResourceCollectionClient } from '../base/resource_collection_client.js';
 import * as schemas from '../schemas.js';
+import { timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
 import { paginationOptionsShape, parseArgument } from '../utils.js';
 const listOptionsSchema = z.strictObject({
     unnamed: z.boolean().optional(),
     ...paginationOptionsShape,
     desc: z.boolean().optional(),
     ownership: z.enum(STORAGE_OWNERSHIP_FILTER).optional(),
+    ...timeoutOptionsShape,
 });
 const nameSchema = z.string().optional();
 /**
@@ -57,22 +59,26 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient {
      * ```
      *
      * @param options - Pagination options.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns A paginated iterator of Request queues.
      * @see https://docs.apify.com/api/v2/request-queues-get
      */
     list(options = {}) {
         const parsed = parseArgument(options, listOptionsSchema, 'RequestQueueCollectionListOptions');
-        return this._listPaginated(schemas.ListOfRequestQueues(), parsed);
+        return this.listResourcesPaginated(schemas.ListOfRequestQueues(), parsed, 'medium');
     }
     /**
      * Gets or creates a Request queue with the specified name.
      *
      * @param name - Name of the Request queue. If not provided, a default queue is used.
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The Request queue object.
      * @see https://docs.apify.com/api/v2/request-queues-post
      */
-    async getOrCreate(name) {
+    async getOrCreate(name, options = {}) {
         parseArgument(name, nameSchema);
-        return this._getOrCreate(schemas.RequestQueue(), name);
+        const { timeoutSecs = 'short', signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        return this.getOrCreateResource(schemas.RequestQueue(), name, undefined, timeoutSecs, signal);
     }
 }

package/dist/resource_clients/run.d.ts

@@ -2,8 +2,10 @@ import type { RUN_GENERAL_ACCESS } from '@apify/consts';
 import { Log } from '@apify/log';
 import type { ApiClientOptionsWithOptionalResourcePath } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
-import type { ApifyResponse } from '../http_client.js';
-import type { ActorRun } from './actor.js';
+import type { ApifyResponse } from '../http_clients/index.js';
+import type { TimeoutOptions } from '../timeouts.js';
+import type { PaginationOptions } from '../utils.js';
+import type { ActorInput, ActorRun } from './actor.js';
 import { DatasetClient } from './dataset.js';
 import { KeyValueStoreClient } from './key_value_store.js';
 import { LogClient, StreamedLog } from './log.js';
@@ -41,6 +43,8 @@ export declare class RunClient extends ResourceClient {
      *
      * @param options - Get options
      * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the run to finish on the API side before returning. Default is 0 (returns immediately).
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`, extended to cover `waitForFinish`
+     * when the API is asked to hold the response.
      * @returns The ActorRun object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/actor-run-get
      *
@@ -60,6 +64,7 @@ export declare class RunClient extends ResourceClient {
      *
      * @param options - Abort options
      * @param options.gracefully - If `true`, the Actor run will abort gracefully - it can send status messages and perform cleanup. Default is `false` (immediate abort).
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The updated ActorRun object with `ABORTING` or `ABORTED` status
      * @see https://docs.apify.com/api/v2/actor-run-abort-post
      *
@@ -76,10 +81,12 @@ export declare class RunClient extends ResourceClient {
     /**
      * Deletes the Actor run.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/actor-run-delete
      * @since Added in 2.8.1
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Transforms the Actor run into a run of another Actor (metamorph).
      *
@@ -88,10 +95,11 @@ export declare class RunClient extends ResourceClient {
      * This is useful for chaining Actor executions or implementing complex workflows.
      *
      * @param targetActorId - ID or username/name of the target Actor
-     * @param input - Input for the target Actor. Can be any JSON-serializable value.
+     * @param input - Input for the target Actor: an object or array serialized to JSON, or raw bytes sent as they
+     *                are. Omit it to metamorph without input.
      * @param options - Metamorph options
      * @param options.build - Tag or number of the target Actor's build to run. Default is the target Actor's default build.
-     * @param options.contentType - Content type of the input. If specified, input must be a string or Buffer.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The metamorphed ActorRun object (same ID, but now running the target Actor)
      * @see https://docs.apify.com/api/v2/actor-run-metamorph-post
      *
@@ -105,7 +113,7 @@ export declare class RunClient extends ResourceClient {
      * console.log(`Run ${metamorphedRun.id} is now running ${metamorphedRun.actId}`);
      * ```
      */
-    metamorph(targetActorId: string, input: unknown, options?: RunMetamorphOptions): Promise<ActorRun>;
+    metamorph(targetActorId: string, input?: ActorInput, options?: RunMetamorphOptions): Promise<ActorRun>;
     /**
      * Reboots the Actor run.
      *
@@ -113,6 +121,8 @@ export declare class RunClient extends ResourceClient {
      * This can be useful to recover from certain errors or to force the Actor to restart
      * with a fresh environment.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The updated ActorRun object
      * @see https://docs.apify.com/api/v2/actor-run-reboot-post
      *
@@ -122,7 +132,7 @@ export declare class RunClient extends ResourceClient {
      * ```
      * @since Added in 2.8.0
      */
-    reboot(): Promise<ActorRun>;
+    reboot(options?: TimeoutOptions): Promise<ActorRun>;
     /**
      * Updates the Actor run with specified fields.
      *
@@ -130,6 +140,8 @@ export declare class RunClient extends ResourceClient {
      * @param newFields.statusMessage - Custom status message to display (e.g., "Processing page 10/100")
      * @param newFields.isStatusMessageTerminal - If `true`, the status message is final and won't be overwritten. Default is `false`.
      * @param newFields.generalAccess - General resource access level ('FOLLOW_USER_SETTING', 'ANYONE_WITH_ID_CAN_READ' or 'RESTRICTED')
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated ActorRun object
      *
      * @example
@@ -141,7 +153,7 @@ export declare class RunClient extends ResourceClient {
      * ```
      * @since Added in 2.6.0
      */
-    update(newFields: RunUpdateOptions): Promise<ActorRun>;
+    update(newFields: RunUpdateOptions, options?: TimeoutOptions): Promise<ActorRun>;
     /**
      * Resurrects a finished Actor run, starting it again with the same settings.
      *
@@ -151,10 +163,11 @@ export declare class RunClient extends ResourceClient {
      * @param options - Resurrection options (override original run settings)
      * @param options.build - Tag or number of the build to use. If not provided, uses the original run's build.
      * @param options.memory - Memory in megabytes. If not provided, uses the original run's memory.
-     * @param options.timeout - Timeout in seconds. If not provided, uses the original run's timeout.
+     * @param options.runTimeoutSecs - Timeout for the resurrected run in seconds. If not provided, uses the original run's timeout.
      * @param options.maxItems - Maximum number of dataset items (pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (pay-per-event Actors).
      * @param options.restartOnError - Whether to restart on error.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The new (resurrected) ActorRun object
      * @see https://docs.apify.com/api/v2/post-resurrect-run
      *
@@ -173,6 +186,7 @@ export declare class RunClient extends ResourceClient {
      * @param options.eventName - **Required.** Name of the event to charge for.
      * @param options.count - Number of times to charge the event. Default is 1.
      * @param options.idempotencyKey - Optional key to ensure the charge is not duplicated. If not provided, one is auto-generated.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns Empty response object.
      * @see https://docs.apify.com/api/v2/post-charge-run
      * @since Added in 2.11.0
@@ -191,7 +205,8 @@ export declare class RunClient extends ResourceClient {
      *
      * @param options - Wait options
      * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If the limit is reached, the returned promise resolves to a run object that will have status `READY` or `RUNNING`. If omitted, waits indefinitely.
-     * @returns The ActorRun object (finished or still running if timeout was reached)
+     * @param options.timeoutSecs - Timeout for each polling API request. Default is `'noTimeout'`.
+     * @returns The ActorRun object (finished or still running if the timeout was reached)
      *
      * @example
      * ```javascript
@@ -210,6 +225,8 @@ export declare class RunClient extends ResourceClient {
     /**
      * Returns a client for the default dataset of this Actor run.
      *
+     * A 404 from this client throws an `ApifyApiError`, since the run itself may be what is missing.
+     *
      * @returns A client for accessing the run's default dataset
      * @see https://docs.apify.com/api/v2/actor-run-get
      *
@@ -223,6 +240,9 @@ export declare class RunClient extends ResourceClient {
     /**
      * Returns a client for the default key-value store of this Actor run.
      *
+     * `get()` and `delete()` throw an `ApifyApiError` on a 404, since the run itself may be what is missing. Record
+     * lookups such as `getRecord()` read a 404 as a missing record.
+     *
      * @returns A client for accessing the run's default key-value store
      * @see https://docs.apify.com/api/v2/actor-run-get
      *
@@ -236,6 +256,9 @@ export declare class RunClient extends ResourceClient {
     /**
      * Returns a client for the default Request queue of this Actor run.
      *
+     * `get()` and `delete()` throw an `ApifyApiError` on a 404, since the run itself may be what is missing.
+     * `getRequest()` reads a 404 as a missing request.
+     *
      * @returns A client for accessing the run's default Request queue
      * @see https://docs.apify.com/api/v2/actor-run-get
      *
@@ -249,6 +272,8 @@ export declare class RunClient extends ResourceClient {
     /**
      * Returns a client for accessing the log of this Actor run.
      *
+     * A 404 from this client throws an `ApifyApiError`, since the run itself may be what is missing.
+     *
      * @returns A client for accessing the run's log
      * @see https://docs.apify.com/api/v2/actor-run-get
      *
@@ -262,34 +287,79 @@ export declare class RunClient extends ResourceClient {
     log(): LogClient;
     /**
      * Get StreamedLog for convenient streaming of the run log and their redirection.
+     *
+     * @param options - Streaming options
+     * @param options.toLog - Log instance to redirect the run log to. Use `'default'` for a preconfigured one, or `null` to disable the redirection.
+     * @param options.fromStart - If `true`, the log is streamed from its beginning. Default is `true`.
+     * @param options.timeoutSecs - Timeout for the API requests that fetch the run and its Actor. Default is `'long'`.
      * @since Added in 2.20.0
      */
     getStreamedLog(options?: GetStreamedLogOptions): Promise<StreamedLog | undefined>;
+    /**
+     * Iterates over the items of the run's default dataset while the run is still producing them.
+     *
+     * While the run has not finished, each poll yields the rows below the dataset's `itemCount` and then waits up to
+     * `pollIntervalSecs` for the run to finish, so the last rows are read as soon as it does. Each page is requested
+     * with a `limit` that ends at `itemCount`, so it covers exactly the rows it asks for, whatever the filters or
+     * `unwind` do to the items. `itemCount` lags a few seconds behind
+     * the pushed items, so once the run reaches a terminal status, the rows past it are read a page at a time until
+     * none are left, and the iterator returns. On a `lastRun()` client, the iterator sticks to the run that its first
+     * request resolves to.
+     *
+     * @param options - Iteration options
+     * @param options.offset - Number of rows to skip from the beginning. Default is 0.
+     * @param options.limit - Maximum number of dataset rows to scan. Fewer items are yielded when filters drop some,
+     * more when `unwind` splits a row into several. Default is no limit.
+     * @param options.clean - If `true`, returns only non-empty items and skips hidden fields. Default is `false`.
+     * @param options.fields - Array of field names to include in the results. Omits all other fields.
+     * @param options.omit - Array of field names to exclude from the results.
+     * @param options.unwind - Array of field names to unwind. Each array value creates a separate item.
+     * @param options.skipEmpty - If `true`, skips empty items. Default is `false`.
+     * @param options.skipHidden - If `true`, skips hidden fields (fields starting with `#`). Default is `false`.
+     * @param options.chunkSize - Maximum number of dataset rows requested per API call. Default is 1000.
+     * @param options.pollIntervalSecs - How long to wait for the run to finish between polls, in seconds. Default is 5.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'long'`.
+     * @returns An async iterable of the dataset items
+     * @see https://docs.apify.com/api/v2/dataset-items-get
+     *
+     * @example
+     * ```javascript
+     * for await (const item of client.run('run-id').iterateDatasetItems()) {
+     *     console.log(item);
+     * }
+     * ```
+     */
+    iterateDatasetItems<Data extends Record<string | number, any> = Record<string | number, unknown>>(options?: RunIterateDatasetItemsOptions): AsyncGenerator<Data, void, undefined>;
 }
 /**
  * Options for getting a streamed log.
  * @since Added in 2.20.0
  */
-export interface GetStreamedLogOptions {
+export interface GetStreamedLogOptions extends TimeoutOptions {
     toLog?: Log | null | 'default';
     fromStart?: boolean;
 }
 /**
  * Options for getting a Run.
  */
-export interface RunGetOptions {
+export interface RunGetOptions extends TimeoutOptions {
     waitForFinish?: number;
 }
 /**
  * Options for aborting a Run.
  */
-export interface RunAbortOptions {
+export interface RunAbortOptions extends TimeoutOptions {
     gracefully?: boolean;
 }
 /**
  * Options for metamorphing a Run into another Actor.
  */
-export interface RunMetamorphOptions {
+export interface RunMetamorphOptions extends TimeoutOptions {
+    /**
+     * Content type of the request body, which becomes the content type of the run's `INPUT` record.
+     * Without it, an input is serialized to JSON and sent as `application/json`. Pairing an object
+     * with `application/x-www-form-urlencoded` form-encodes it instead.
+     */
     contentType?: string;
     build?: string;
 }
@@ -311,10 +381,11 @@ export interface RunUpdateOptions {
 /**
  * Options for resurrecting a finished Run.
  */
-export interface RunResurrectOptions {
+export interface RunResurrectOptions extends TimeoutOptions {
     build?: string;
     memory?: number;
-    timeout?: number;
+    /** Timeout for the resurrected run in seconds. If not provided, the run keeps its original timeout. */
+    runTimeoutSecs?: number;
     /**
      * @since Added in 2.12.1
      */
@@ -332,7 +403,7 @@ export interface RunResurrectOptions {
  * Options for charging events in a pay-per-event Actor run.
  * @since Added in 2.11.0
  */
-export interface RunChargeOptions {
+export interface RunChargeOptions extends TimeoutOptions {
     /** Name of the event to charge. Must be defined in the Actor's pricing info else the API will throw. */
     eventName: string;
     /** Defaults to 1 */
@@ -343,7 +414,7 @@ export interface RunChargeOptions {
 /**
  * Options for waiting for a Run to finish.
  */
-export interface RunWaitForFinishOptions {
+export interface RunWaitForFinishOptions extends TimeoutOptions {
     /**
      * Maximum time to wait for the run to finish, in seconds.
      * If the limit is reached, the returned promise is resolved to a run object that will have
@@ -351,3 +422,22 @@ export interface RunWaitForFinishOptions {
      */
     waitSecs?: number;
 }
+/**
+ * Options for iterating over the items of a run's default dataset while the run is still producing them.
+ */
+export interface RunIterateDatasetItemsOptions extends PaginationOptions, TimeoutOptions {
+    /** If `true`, returns only non-empty items and skips hidden fields. */
+    clean?: boolean;
+    /** Field names to include in the items. Omits all other fields. */
+    fields?: string[];
+    /** Field names to exclude from the items. */
+    omit?: string[];
+    /** If `true`, skips empty items. */
+    skipEmpty?: boolean;
+    /** If `true`, skips hidden fields (fields starting with `#`). */
+    skipHidden?: boolean;
+    /** Field names to unwind. Each array value creates a separate item. */
+    unwind?: string[];
+    /** How long to wait for the run to finish between polls, in seconds. Default is 5. */
+    pollIntervalSecs?: number;
+}