apify-client 3.0.0-beta.9 → 3.0.0-beta.90

package/dist/models.js

@@ -1,6 +1,8 @@
 /**
  * Public models adapted from the generated OpenAPI types in `./generated/api`.
  *
+ * Each model takes the name of the spec schema it is declared on, as the Python client does.
+ *
  * The generated file is never re-exported directly. Every type here is declared on top of a generated
  * schema so the compiler reports drift, and the spec is adopted as-is wherever it is trustworthy. What
  * remains is deliberately small, and each deviation falls into exactly one of five kinds, one block per
@@ -66,10 +68,10 @@ export var ScheduleActions;
 /**
  * Platform features a plan can enable.
  *
- * This enum is not the element type of `UserPlan.enabledPlatformFeatures`, which the spec types
- * as a plain `string[]`: the platform has features this list never gained -- `PROXY_RESIDENTIAL`,
- * `ACTORS_PUBLIC_ALL` and `ACTORS_PUBLIC_DEVELOPER` all appear as keys of `EffectivePlatformFeatures`
- * -- so using it there promised a completeness that was not real. It stays published for comparisons.
+ * This enum is not the element type of `UserPlan.enabledPlatformFeatures`, which the spec types as a plain
+ * `string[]`: the platform has features this list never gained -- `PROXY_RESIDENTIAL`, `ACTORS_PUBLIC_ALL`
+ * and `ACTORS_PUBLIC_DEVELOPER` all appear as keys of `EffectivePlatformFeatures` -- so using it there
+ * promised a completeness that was not real. It stays published for comparisons.
  *
  * Declared here rather than in `./resource_clients/user` so the user types can live alongside it. It is
  * re-exported from there, so the public name and import path are unchanged.

package/dist/resource_clients/actor.d.ts

@@ -2,7 +2,10 @@ import { ACTOR_JOB_STATUSES, ACTOR_PERMISSION_LEVEL, META_ORIGINS } from '@apify
 import { Log } from '@apify/log';
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
-import type { Actor, ActorRun } from '../models.js';
+import type { ActorResource, Run } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
+import type { Dictionary } from '../utils.js';
+import { ActorServerClient } from './actor_server.js';
 import { ActorVersionClient } from './actor_version.js';
 import { ActorVersionCollectionClient } from './actor_version_collection.js';
 import type { Build, BuildClientGetOptions } from './build.js';
@@ -13,7 +16,7 @@ import { RunCollectionClient } from './run_collection.js';
 import type { WebhookUpdateData } from './webhook.js';
 import { WebhookCollectionClient } from './webhook_collection.js';
 import type { ValueOf } from 'type-fest';
-export type { Actor, ActorChargeEvent, ActorChargeEvents, ActorDefaultRunOptions, ActorDefinition, ActorExampleRunInput, ActorRun, ActorRunListItem, ActorRunMeta, ActorRunMetamorph, ActorRunOptions, ActorRunPricingInfo, ActorRunStats, ActorRunStorageIds, ActorRunUsage, ActorStandby, ActorStats, ActorTaggedBuild, ActorTaggedBuilds, FlatPricePerMonthActorPricingInfo, FreeActorPricingInfo, PricePerDatasetItemActorPricingInfo, PricePerEventActorPricingInfo, TieredPricingPerDatasetItem, TieredPricingPerDatasetItemEntry, TieredPricingPerEvent, TieredPricingPerEventEntry, } from '../models.js';
+export type { ActorResource, ActorChargeEvent, ActorChargeEvents, ActorDefinition, ActorRunPricingInfo, ActorRunStorageIds, ActorStandby, ActorStats, DefaultRunOptions, ExampleRunInput, FlatPricePerMonthActorPricingInfo, FreeActorPricingInfo, RunMetamorphEvent, PayPerEventActorPricingInfo, PricePerDatasetItemActorPricingInfo, Run, RunMeta, RunOptions, RunListItem, RunStats, RunUsage, TaggedBuildInfo, TaggedBuilds, TieredPricingPerDatasetItem, TieredPricingPerDatasetItemEntry, TieredPricingPerEvent, TieredPricingPerEventEntry, } from '../models.js';
 /**
  * Client for managing a specific Actor.
  *
@@ -35,6 +38,7 @@ export type { Actor, ActorChargeEvent, ActorChargeEvents, ActorDefaultRunOptions
  * @see https://docs.apify.com/platform/actors
  */
 export declare class ActorClient extends ResourceClient {
+    #private;
     /**
      * @hidden
      */
@@ -42,24 +46,30 @@ export declare class ActorClient extends ResourceClient {
     /**
      * Gets the Actor object from the Apify API.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The Actor object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/act-get
      */
-    get(): Promise<Actor | undefined>;
+    get(options?: TimeoutOptions): Promise<ActorResource | undefined>;
     /**
      * Updates the Actor with specified fields.
      *
      * @param newFields - Fields to update in the Actor
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The updated Actor object
      * @see https://docs.apify.com/api/v2/act-put
      */
-    update(newFields: ActorUpdateOptions): Promise<Actor>;
+    update(newFields: ActorUpdateOptions, options?: TimeoutOptions): Promise<ActorResource>;
     /**
      * Deletes the Actor.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/act-delete
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Starts the Actor and immediately returns the Run object.
      *
@@ -67,17 +77,20 @@ export declare class ActorClient extends ResourceClient {
      * asynchronously and this method returns immediately without waiting for completion.
      * Use the {@link call} method if you want to wait for the Actor to finish.
      *
-     * @param input - Input for the Actor. Can be any JSON-serializable value (object, array, string, number).
-     *                If `contentType` is specified in options, input should be a string or Buffer.
+     * @param input - Input for the Actor: an object or array serialized to JSON, or raw bytes sent as they are.
+     *                Omit it to run the Actor without input.
      * @param options - Run configuration options
      * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`). If not provided, uses the default build.
      * @param options.memory - Memory in megabytes allocated for the run. If not provided, uses the Actor's default memory setting.
-     * @param options.timeout - Timeout for the run in seconds. Zero means no timeout. If not provided, uses the Actor's default timeout.
+     * @param options.runTimeoutSecs - Timeout for the run in seconds. Zero means no timeout. If not provided, uses the Actor's default timeout.
      * @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.webhooks - Webhooks to trigger when the Actor run reaches a specific state (e.g., `SUCCEEDED`, `FAILED`).
      * @param options.maxItems - Maximum number of dataset items that will be charged (only for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (only for pay-per-event Actors).
-     * @param options.contentType - Content type of the input. If specified, input must be a string or Buffer.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`, extended to cover `waitForFinish`
+     * when the API is asked to hold the response.
      * @returns The Actor run object with status, usage, and storage IDs
      * @see https://docs.apify.com/api/v2/act-runs-post
      *
@@ -90,11 +103,11 @@ export declare class ActorClient extends ResourceClient {
      * // Start Actor with specific build and memory
      * const run = await client.actor('my-actor').start(
      *   { url: 'https://example.com' },
-     *   { build: '0.1.2', memory: 512, timeout: 300 }
+     *   { build: '0.1.2', memory: 512, runTimeoutSecs: 300 }
      * );
      * ```
      */
-    start(input?: unknown, options?: ActorStartOptions): Promise<ActorRun>;
+    start(input?: ActorInput, options?: ActorStartOptions): Promise<Run>;
     /**
      * Starts the Actor and waits for it to finish before returning the Run object.
      *
@@ -102,14 +115,18 @@ export declare class ActorClient extends ResourceClient {
      * by polling the run status. It optionally streams logs to the console or a custom Log instance.
      * By default, it waits indefinitely unless the `waitSecs` option is provided.
      *
-     * @param input - Input for the Actor. Can be any JSON-serializable value (object, array, string, number).
-     *                If `contentType` is specified in options, input should be a string or Buffer.
+     * @param input - Input for the Actor: an object or array serialized to JSON, or raw bytes sent as they are.
+     *                Omit it to run the Actor without input.
      * @param options - Run configuration options (extends all options from {@link start})
      * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If omitted, waits indefinitely.
      * @param options.log - Log instance for streaming run logs. Use `'default'` for console output, `null` to disable logging, or provide a custom Log instance.
      * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`).
      * @param options.memory - Memory in megabytes allocated for the run.
-     * @param options.timeout - Maximum run duration in seconds.
+     * @param options.runTimeoutSecs - Maximum run duration in seconds.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds. The time spent
+     * retrying doesn't count toward `waitSecs`.
+     * @param options.timeoutSecs - Timeout for each API request, the start and every poll alike. Default is `'noTimeout'`.
      * @returns The finished Actor run object with final status (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`)
      * @see https://docs.apify.com/api/v2/act-runs-post
      *
@@ -132,7 +149,7 @@ export declare class ActorClient extends ResourceClient {
      * const run = await client.actor('my-actor').call({ url: 'https://example.com' }, { log });
      * ```
      */
-    call(input?: unknown, options?: ActorCallOptions): Promise<ActorRun>;
+    call(input?: ActorInput, options?: ActorCallOptions): Promise<Run>;
     /**
      * Validates the provided input for the Actor against its input schema.
      *
@@ -141,13 +158,12 @@ export declare class ActorClient extends ResourceClient {
      * invalid, the API responds with an error that is thrown as an `ApifyApiError` describing the
      * validation problem.
      *
-     * @param input - Input to validate against the Actor's input schema. Can be any JSON-serializable
-     *                value (object, array, string, number). If `contentType` is specified in options,
-     *                input should be a string or Buffer.
+     * @param input - Input to validate against the Actor's input schema: an object or array serialized to JSON, or
+     *                raw bytes sent as they are.
      * @param options - Validation options
      * @param options.build - Tag or number of the build whose input schema the input is validated against
      *                         (e.g., `'latest'` or `'1.2.345'`). If not provided, uses the 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 `'short'`.
      * @returns `true` if the input is valid. Invalid input causes the underlying API call to throw an `ApifyApiError`.
      * @see https://docs.apify.com/api/v2/act-validate-input-post
      *
@@ -164,7 +180,7 @@ export declare class ActorClient extends ResourceClient {
      * ```
      * @since Added in 2.24.0
      */
-    validateInput(input?: unknown, options?: ActorValidateInputOptions): Promise<boolean>;
+    validateInput(input?: ActorInput, options?: ActorValidateInputOptions): Promise<boolean>;
     /**
      * Builds the Actor.
      *
@@ -177,6 +193,8 @@ export declare class ActorClient extends ResourceClient {
      * @param options.tag - Tag to be applied to the build (e.g., `'latest'`, `'beta'`). Existing tag with the same name will be replaced.
      * @param options.useCache - If `false`, Docker build cache will be ignored. Default is `true`.
      * @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 `'medium'`, extended to cover `waitForFinish`
+     * when the API is asked to hold the response.
      * @returns The Build object with status and build details
      * @see https://docs.apify.com/api/v2/act-builds-post
      *
@@ -204,6 +222,8 @@ export declare class ActorClient extends ResourceClient {
      *
      * @param options - Options for getting the default build
      * @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 A client for the default build
      * @see https://docs.apify.com/api/v2/act-build-default-get
      *
@@ -275,22 +295,59 @@ export declare class ActorClient extends ResourceClient {
      * @see https://docs.apify.com/api/v2/act-webhooks-get
      */
     webhooks(): WebhookCollectionClient;
+    /**
+     * Returns a client for the server interface of this Actor.
+     *
+     * A Server Actor runs a web server, its server interface, that is called over HTTP without starting a run for
+     * each call. Server Actors were formerly called Actor Standby, and {@link standby} is a deprecated alias of this
+     * method. Every call returns the same client, so the server URL it fetches is reused.
+     *
+     * @returns The client for the server interface of this Actor
+     * @see https://docs.apify.com/platform/actors/running/standby
+     *
+     * @example
+     * ```javascript
+     * const response = await client.actor('username/actor-name').server().request('/search', {
+     *     params: { q: 'apify' },
+     * });
+     * ```
+     */
+    server(): ActorServerClient;
+    /**
+     * Returns a client for the server interface of this Actor in Standby mode.
+     *
+     * Named after Actor Standby, the former name of Server Actors.
+     *
+     * @deprecated Use {@link server} instead. Will be removed in v4.
+     * @returns The client for the server interface of this Actor
+     * @see https://docs.apify.com/platform/actors/running/standby
+     */
+    standby(): ActorServerClient;
 }
 /**
  * Fields that can be updated when modifying an Actor.
  */
-export type ActorUpdateOptions = Partial<Pick<Actor, 'name' | 'description' | 'isPublic' | 'isDeprecated' | 'seoTitle' | 'seoDescription' | 'title' | 'restartOnError' | 'versions' | 'categories' | 'defaultRunOptions' | 'actorStandby' | 'actorPermissionLevel' | 'taggedBuilds'>>;
-export interface ActorStartOptions {
+export type ActorUpdateOptions = Partial<Pick<ActorResource, 'name' | 'description' | 'isPublic' | 'isDeprecated' | 'seoTitle' | 'seoDescription' | 'title' | 'versions' | 'categories' | 'defaultRunOptions' | 'actorStandby' | 'actorPermissionLevel' | 'taggedBuilds' | 'pricingInfos' | 'exampleRunInput'>>;
+/**
+ * Input for an Actor run, as taken by {@link ActorClient.start}, {@link ActorClient.call},
+ * {@link ActorClient.validateInput} and {@link RunClient.metamorph}.
+ *
+ * A plain object or an array of plain objects, serialized into the request body, or raw bytes
+ * (a `Uint8Array` such as a `Buffer`, or an `ArrayBuffer`) sent as they are, typically with a
+ * `contentType`. An input typed as an `interface` or a class needs a spread (`{ ...input }`), or for
+ * an interface a `type` alias, to compile.
+ */
+export type ActorInput = Dictionary | readonly Dictionary[] | Uint8Array | ArrayBuffer;
+export interface ActorStartOptions extends TimeoutOptions {
     /**
      * Tag or number of the Actor build to run (e.g. `beta` or `1.2.345`).
      * If not provided, the run uses build tag or number from the default Actor run configuration (typically `latest`).
      */
     build?: string;
     /**
-     * Content type for the `input`. If not specified,
-     * `input` is expected to be an object that will be stringified to JSON and content type set to
-     * `application/json; charset=utf-8`. If `options.contentType` is specified, then `input` must be a
-     * `String` or `Buffer`.
+     * 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;
     /**
@@ -300,9 +357,9 @@ export interface ActorStartOptions {
     memory?: number;
     /**
      * Timeout for the Actor run in seconds. Zero value means there is no timeout.
-     * If not provided, the run uses timeout of the default Actor run configuration.
+     * If not provided, the run uses the timeout of the default Actor run configuration.
      */
-    timeout?: number;
+    runTimeoutSecs?: number;
     /**
      * Maximum time to wait for the Actor run to finish, in seconds.
      * If the limit is reached, the returned promise is resolved to a run object that will have
@@ -345,6 +402,20 @@ export interface ActorStartOptions {
      * @since Added in 2.17.0
      */
     forcePermissionLevel?: ACTOR_PERMISSION_LEVEL;
+    /**
+     * Retry the start while the account lacks the resources for the run, that is while the API rejects it with an
+     * `ApifyApiError` of type `actor-memory-limit-exceeded` or `concurrent-runs-limit-exceeded`. Both clear as
+     * other runs or builds finish. The start is retried every 10 seconds, and any other error is thrown right away.
+     *
+     * `true` retries until the run starts. A number stops retrying after that many seconds and throws the last
+     * error. Omitted or `false`, the first rejection is thrown.
+     *
+     * A run that requests more memory than the whole memory limit of the account is rejected with
+     * `actor-memory-limit-exceeded` as well and never starts, so `true` retries it forever.
+     *
+     * A `Readable` input can't be sent twice, so its start is never retried and the first rejection is thrown.
+     */
+    waitForResources?: boolean | number;
 }
 /**
  * Options for calling an Actor and waiting for it to finish.
@@ -369,24 +440,23 @@ export interface ActorCallOptions extends Omit<ActorStartOptions, 'waitForFinish
  * Options for validating an Actor input.
  * @since Added in 2.24.0
  */
-export interface ActorValidateInputOptions {
+export interface ActorValidateInputOptions extends TimeoutOptions {
     /**
      * Tag or number of the Actor build whose input schema the input is validated against
      * (e.g. `beta` or `1.2.345`). If not provided, the default build is used.
      */
     build?: string;
     /**
-     * Content type for the `input`. If not specified,
-     * `input` is expected to be an object that will be stringified to JSON and content type set to
-     * `application/json; charset=utf-8`. If `options.contentType` is specified, then `input` must be a
-     * `String` or `Buffer`.
+     * Content type of the request body carrying the input to validate. Without it, the 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;
 }
 /**
  * Options for building an Actor.
  */
-export interface ActorBuildOptions {
+export interface ActorBuildOptions extends TimeoutOptions {
     betaPackages?: boolean;
     tag?: string;
     useCache?: boolean;