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

package/dist/resource_clients/build.d.ts

@@ -1,6 +1,7 @@
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
 import type { Build } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
 import { LogClient } from './log.js';
 export type { Build, BuildMeta, BuildOptions, BuildStats, BuildUsage } from '../models.js';
 /**
@@ -36,6 +37,8 @@ export declare class BuildClient extends ResourceClient {
      *
      * @param options - Get options
      * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the build 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 Build object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/actor-build-get
      *
@@ -55,6 +58,8 @@ export declare class BuildClient extends ResourceClient {
      *
      * Stops the build process immediately. The build will have an `ABORTED` status.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated Build object with `ABORTED` status
      * @see https://docs.apify.com/api/v2/actor-build-abort-post
      *
@@ -63,22 +68,26 @@ export declare class BuildClient extends ResourceClient {
      * await client.build('build-id').abort();
      * ```
      */
-    abort(): Promise<Build>;
+    abort(options?: TimeoutOptions): Promise<Build>;
     /**
      * Deletes the Actor build.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/actor-build-delete
      * @since Added in 2.8.1
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Retrieves the OpenAPI definition for the Actor build.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The OpenAPI definition object.
      * @see https://docs.apify.com/api/v2/actor-build-openapi-json-get
      * @since Added in 2.11.2
      */
-    getOpenApiDefinition(): Promise<OpenApiDefinition>;
+    getOpenApiDefinition(options?: TimeoutOptions): Promise<OpenApiDefinition>;
     /**
      * Waits for the Actor build to finish and returns the finished Build object.
      *
@@ -94,7 +103,8 @@ export declare class BuildClient extends ResourceClient {
      *
      * @param options - Wait options
      * @param options.waitSecs - Maximum time to wait for the build to finish, in seconds. If omitted, waits indefinitely.
-     * @returns The Build object (finished or still building if timeout was reached)
+     * @param options.timeoutSecs - Timeout for each polling API request. Default is `'noTimeout'`.
+     * @returns The Build object (finished or still building if the timeout was reached)
      *
      * @example
      * ```javascript
@@ -113,6 +123,8 @@ export declare class BuildClient extends ResourceClient {
     /**
      * Returns a client for accessing the log of this Actor build.
      *
+     * A 404 from this client throws an `ApifyApiError`, since the build itself may be what is missing.
+     *
      * @returns A client for accessing the build's log
      * @see https://docs.apify.com/api/v2/actor-build-log-get
      *
@@ -129,13 +141,13 @@ export declare class BuildClient extends ResourceClient {
 /**
  * Options for getting a Build.
  */
-export interface BuildClientGetOptions {
+export interface BuildClientGetOptions extends TimeoutOptions {
     waitForFinish?: number;
 }
 /**
  * Options for waiting for a Build to finish.
  */
-export interface BuildClientWaitForFinishOptions {
+export interface BuildClientWaitForFinishOptions extends TimeoutOptions {
     /**
      * Maximum time to wait for the build to finish, in seconds.
      * If the limit is reached, the returned promise is resolved to a build object that will have

package/dist/resource_clients/build.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
 import { ResourceClient } from '../base/resource_client.js';
-import { cast, parseArgument, parseDateFields, pluckData } from '../utils.js';
+import * as schemas from '../schemas.js';
+import { timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
+import { parseArgument, parseResponse } from '../utils.js';
 import { LogClient } from './log.js';
-const getOptionsSchema = z.strictObject({ waitForFinish: z.number().optional() });
-const waitForFinishOptionsSchema = z.strictObject({ waitSecs: z.number().optional() });
+const getOptionsSchema = z.strictObject({ waitForFinish: z.number().optional(), ...timeoutOptionsShape });
+const waitForFinishOptionsSchema = z.strictObject({ waitSecs: z.number().optional(), ...timeoutOptionsShape });
 /**
  * Client for managing a specific Actor build.
  *
@@ -42,6 +44,8 @@ export class BuildClient extends ResourceClient {
      *
      * @param options - Get options
      * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the build 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 Build object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/actor-build-get
      *
@@ -56,14 +60,16 @@ export class BuildClient extends ResourceClient {
      * ```
      */
     async get(options = {}) {
-        const parsed = parseArgument(options, getOptionsSchema, 'BuildClientGetOptions');
-        return this._get(parsed);
+        const { timeoutSecs, signal, ...params } = parseArgument(options, getOptionsSchema, 'BuildClientGetOptions');
+        return this.getResource(schemas.Build(), params, this.timeoutForWaitForFinish(timeoutSecs, 'short', params.waitForFinish), signal);
     }
     /**
      * Aborts the Actor build.
      *
      * Stops the build process immediately. The build will have an `ABORTED` status.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated Build object with `ABORTED` status
      * @see https://docs.apify.com/api/v2/actor-build-abort-post
      *
@@ -72,35 +78,46 @@ export class BuildClient extends ResourceClient {
      * await client.build('build-id').abort();
      * ```
      */
-    async abort() {
+    async abort(options = {}) {
+        const { timeoutSecs = 'short', signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
         const response = await this.httpClient.call({
-            url: this._url('abort'),
+            url: this.buildUrl('abort'),
             method: 'POST',
-            params: this._params(),
+            params: this.buildParams(),
+            timeoutSecs,
+            signal,
         });
-        return cast(parseDateFields(pluckData(response.data)));
+        return parseResponse(response, schemas.Build());
     }
     /**
      * Deletes the Actor build.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/actor-build-delete
      * @since Added in 2.8.1
      */
-    async delete() {
-        return this._delete();
+    async delete(options = {}) {
+        const { timeoutSecs = 'short', signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
+        return this.deleteResource(timeoutSecs, signal);
     }
     /**
      * Retrieves the OpenAPI definition for the Actor build.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @returns The OpenAPI definition object.
      * @see https://docs.apify.com/api/v2/actor-build-openapi-json-get
      * @since Added in 2.11.2
      */
-    async getOpenApiDefinition() {
+    async getOpenApiDefinition(options = {}) {
+        const { timeoutSecs = 'medium', signal } = parseArgument(options, timeoutOptionsSchema, 'TimeoutOptions');
         const response = await this.httpClient.call({
-            url: this._url('openapi.json'),
+            url: this.buildUrl('openapi.json'),
             method: 'GET',
-            params: this._params(),
+            params: this.buildParams(),
+            timeoutSecs,
+            signal,
         });
         return response.data;
     }
@@ -119,7 +136,8 @@ export class BuildClient extends ResourceClient {
      *
      * @param options - Wait options
      * @param options.waitSecs - Maximum time to wait for the build to finish, in seconds. If omitted, waits indefinitely.
-     * @returns The Build object (finished or still building if timeout was reached)
+     * @param options.timeoutSecs - Timeout for each polling API request. Default is `'noTimeout'`.
+     * @returns The Build object (finished or still building if the timeout was reached)
      *
      * @example
      * ```javascript
@@ -136,11 +154,13 @@ export class BuildClient extends ResourceClient {
      */
     async waitForFinish(options = {}) {
         const parsed = parseArgument(options, waitForFinishOptionsSchema, 'BuildClientWaitForFinishOptions');
-        return this._waitForFinish(parsed);
+        return this.waitForJobFinish(schemas.Build(), parsed);
     }
     /**
      * Returns a client for accessing the log of this Actor build.
      *
+     * A 404 from this client throws an `ApifyApiError`, since the build itself may be what is missing.
+     *
      * @returns A client for accessing the build's log
      * @see https://docs.apify.com/api/v2/actor-build-log-get
      *
@@ -153,7 +173,7 @@ export class BuildClient extends ResourceClient {
      * @since Added in 2.9.0
      */
     log() {
-        return new LogClient(this._subResourceOptions({
+        return new LogClient(this.subResourceOptions({
             resourcePath: 'log',
         }));
     }

package/dist/resource_clients/build_collection.d.ts

@@ -1,6 +1,7 @@
 import type { ApiClientOptionsWithOptionalResourcePath } from '../base/api_client.js';
 import { ResourceCollectionClient } from '../base/resource_collection_client.js';
 import type { BuildCollectionClientListItem } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
 import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../utils.js';
 export type { BuildCollectionClientListItem } from '../models.js';
 /**
@@ -46,12 +47,13 @@ export declare class BuildCollectionClient extends ResourceCollectionClient {
      * ```
      *
      * @param options - Pagination and sorting options.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns A paginated iterator of Actor builds.
      * @see https://docs.apify.com/api/v2/actor-builds-get
      */
     list(options?: BuildCollectionClientListOptions): PaginatedIterator<BuildCollectionClientListItem>;
 }
-export interface BuildCollectionClientListOptions extends PaginationOptions {
+export interface BuildCollectionClientListOptions extends PaginationOptions, TimeoutOptions {
     desc?: boolean;
 }
 export type BuildCollectionClientListResult = PaginatedList<BuildCollectionClientListItem>;

package/dist/resource_clients/build_collection.js

@@ -1,9 +1,12 @@
 import { z } from 'zod';
 import { ResourceCollectionClient } from '../base/resource_collection_client.js';
+import * as schemas from '../schemas.js';
+import { timeoutOptionsShape } from '../timeouts.js';
 import { paginationOptionsShape, parseArgument } from '../utils.js';
 const listOptionsSchema = z.strictObject({
     ...paginationOptionsShape,
     desc: z.boolean().optional(),
+    ...timeoutOptionsShape,
 });
 /**
  * Client for managing the collection of Actor builds.
@@ -53,11 +56,12 @@ export class BuildCollectionClient extends ResourceCollectionClient {
      * ```
      *
      * @param options - Pagination and sorting options.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns A paginated iterator of Actor builds.
      * @see https://docs.apify.com/api/v2/actor-builds-get
      */
     list(options = {}) {
         const parsed = parseArgument(options, listOptionsSchema, 'BuildCollectionClientListOptions');
-        return this._listPaginated(parsed);
+        return this.listResourcesPaginated(schemas.ListOfBuilds(), parsed, 'medium');
     }
 }

package/dist/resource_clients/dataset.d.ts

@@ -2,7 +2,20 @@ 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 { Dataset, DatasetStatistics } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
 import type { PaginatedIterator, PaginationOptions } from '../utils.js';
+/**
+ * Supported formats for downloading dataset items.
+ */
+export declare enum DownloadItemsFormat {
+    JSON = "json",
+    JSONL = "jsonl",
+    XML = "xml",
+    HTML = "html",
+    CSV = "csv",
+    XLSX = "xlsx",
+    RSS = "rss"
+}
 export type { Dataset, DatasetStatistics, DatasetStats, FieldStatistics } from '../models.js';
 /**
  * Client for managing a specific Dataset.
@@ -34,6 +47,7 @@ export type { Dataset, DatasetStatistics, DatasetStats, FieldStatistics } from '
  * @see https://docs.apify.com/platform/storage/dataset
  */
 export declare class DatasetClient<Data extends Record<string | number, any> = Record<string | number, unknown>> extends ResourceClient {
+    #private;
     /**
      * @hidden
      */
@@ -41,24 +55,30 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
     /**
      * Gets the dataset object from the Apify API.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The Dataset object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/dataset-get
      */
-    get(): Promise<Dataset | undefined>;
+    get(options?: TimeoutOptions): Promise<Dataset | undefined>;
     /**
      * Updates the dataset with specified fields.
      *
      * @param newFields - Fields to update in the dataset
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated Dataset object
      * @see https://docs.apify.com/api/v2/dataset-put
      */
-    update(newFields: DatasetClientUpdateOptions): Promise<Dataset>;
+    update(newFields: DatasetClientUpdateOptions, options?: TimeoutOptions): Promise<Dataset>;
     /**
      * Deletes the dataset.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/dataset-delete
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Lists items in the dataset.
      *
@@ -79,6 +99,7 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * @param options.flatten - Array of field names to flatten. Nested objects are converted to dot notation (e.g., `obj.field`).
      * @param options.unwind - Field name or array of field names to unwind. Each array value creates a separate item.
      * @param options.view - Name of a predefined view to use for field selection.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'long'`.
      * @returns A paginated list with `items`, `total` count, `offset`, `count`, and `limit`
      * @see https://docs.apify.com/api/v2/dataset-items-get
      *
@@ -121,6 +142,7 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * @param options.xmlRow - Name of the XML element for each item. Default is `'item'`.
      * @param options.fields - Array of field names to include in the export.
      * @param options.omit - Array of field names to exclude from the export.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @returns Buffer containing the serialized data in the specified format
      * @see https://docs.apify.com/api/v2/dataset-items-get
      *
@@ -144,17 +166,20 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * });
      * ```
      */
-    downloadItems(format: DownloadItemsFormat, options?: DatasetClientDownloadItemsOptions): Promise<Buffer>;
+    downloadItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Buffer>;
     /**
      * Stores one or more items into the dataset.
      *
-     * Items can be objects, strings, or arrays thereof. Each item will be stored as a separate
-     * record in the dataset. Objects are automatically serialized to JSON. If you provide an array,
-     * all items will be stored in order. This method is idempotent - calling it multiple times
-     * with the same data will not create duplicates, but will append items each time.
+     * Each item will be stored as a separate record in the dataset. Objects are automatically
+     * serialized to JSON. If you provide an array, all items will be stored in order. This method
+     * is idempotent - calling it multiple times with the same data will not create duplicates, but
+     * will append items each time.
      *
-     * @param items - A single item (object or string) or an array of items to store.
-     *                Objects are automatically stringified to JSON. Strings are stored as-is.
+     * @param items - A single item, an array of items, or a string that is the JSON serialization of
+     *                either - the API only accepts an object or an array of objects, so a plain string
+     *                is not a valid item on its own.
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @see https://docs.apify.com/api/v2/dataset-items-post
      *
      * @example
@@ -172,23 +197,22 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      *   { url: 'https://test.com', title: 'Test' },
      *   { url: 'https://demo.com', title: 'Demo' }
      * ]);
-     *
-     * // Store string items
-     * await client.dataset('my-dataset').pushItems(['item1', 'item2', 'item3']);
      * ```
      */
-    pushItems(items: Data | Data[] | string | string[]): Promise<void>;
+    pushItems(items: Data | Data[] | string, options?: TimeoutOptions): Promise<void>;
     /**
      * Gets statistical information about the dataset.
      *
      * Returns statistics for each field in the dataset, including information about
      * data types, null counts, and value ranges.
      *
-     * @returns Dataset statistics, or `undefined` if not available
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
+     * @returns Dataset statistics
      * @see https://docs.apify.com/api/v2/dataset-statistics-get
      * @since Added in 2.11.2
      */
-    getStatistics(): Promise<DatasetStatistics | undefined>;
+    getStatistics(options?: TimeoutOptions): Promise<DatasetStatistics>;
     /**
      * Generates a public URL for accessing dataset items.
      *
@@ -199,8 +223,10 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * @param options - URL generation options (extends all options from {@link listItems})
      * @param options.expiresInSecs - Number of seconds until the signed URL expires. If omitted, the URL never expires.
      * @param options.fields - Array of field names to include in the response.
+     * @param options.format - Format of the items served by the URL. Defaults to `json`.
      * @param options.limit - Maximum number of items to return.
      * @param options.offset - Number of items to skip.
+     * @param options.timeoutSecs - Timeout for the API request that fetches the dataset. Default is `'long'`.
      * @returns A public URL string for accessing the dataset items
      *
      * @example
@@ -222,7 +248,6 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * @since Added in 2.13.0
      */
     createItemsPublicUrl(options?: DatasetClientCreateItemsUrlOptions): Promise<string>;
-    private _createPaginationList;
 }
 /**
  * Options for updating a dataset.
@@ -244,7 +269,7 @@ export interface DatasetClientUpdateOptions {
  * Provides various filtering, pagination, and transformation options to customize
  * the output format and content of retrieved items.
  */
-export interface DatasetClientListItemOptions extends PaginationOptions {
+export interface DatasetClientListItemOptions extends PaginationOptions, TimeoutOptions {
     clean?: boolean;
     desc?: boolean;
     /**
@@ -268,25 +293,18 @@ export interface DatasetClientListItemOptions extends PaginationOptions {
 /**
  * Options for creating a public URL to access dataset items.
  *
- * Extends {@link DatasetClientListItemOptions} with URL expiration control, minus `chunkSize` (it only
+ * Extends {@link DatasetClientListItemOptions} with output format and URL expiration control, minus `chunkSize` (it only
  * sizes a client-side iteration) and `signature` (this method produces one).
  * @since Added in 2.16.0
  */
 export interface DatasetClientCreateItemsUrlOptions extends Omit<DatasetClientListItemOptions, 'chunkSize' | 'signature'> {
+    /**
+     * Format of the items served by the URL. Defaults to `json`.
+     * @since Added in 2.26.0
+     */
+    format?: `${DownloadItemsFormat}`;
     expiresInSecs?: number;
 }
-/**
- * Supported formats for downloading dataset items.
- */
-export declare enum DownloadItemsFormat {
-    JSON = "json",
-    JSONL = "jsonl",
-    XML = "xml",
-    HTML = "html",
-    CSV = "csv",
-    XLSX = "xlsx",
-    RSS = "rss"
-}
 /**
  * Options for downloading dataset items in a specific format.
  *