apify 4.0.0-beta.12 → 4.0.0-beta.14

package/README.md

@@ -5,81 +5,45 @@
 [![Chat on discord](https://img.shields.io/discord/801163717915574323?label=discord)](https://discord.gg/jyEM2PRvMU)
 [![Build Status](https://github.com/apify/apify-sdk-js/actions/workflows/test-and-release.yaml/badge.svg?branch=master)](https://github.com/apify/apify-sdk-js/actions/workflows/test-and-release.yaml)
 
-Apify SDK provides the tools required to run your own Apify Actors. The crawlers and scraping related tools, previously included in Apify SDK (v2), have been split into a brand-new module - [`crawlee`](https://npmjs.org/crawlee), while keeping the Apify specific parts in this module.
-
-> Would you like to work with us on Crawlee, Apify SDK or similar projects? We are hiring [Node.js engineers](https://apify.com/jobs#senior-node.js-engineer).
-
-## Upgrading from v2
-
-A lot of things have changed since version 2 of the Apify SDK, including the split of the crawlers to the new [`crawlee`](https://npmjs.org/crawlee) module. We've written a guide to help you easily migrate from v2 to v3. Visit the [Upgrading Guide](https://docs.apify.com/sdk/js/docs/upgrading/upgrading-to-v3) to find out what changes you need to make (especially the section related to this very [Apify SDK](https://docs.apify.com/sdk/js/docs/upgrading/upgrading-to-v3#apify-sdk)), and, if you encounter any issues, join our [Discord server](https://discord.gg/jyEM2PRvMU) for help!
-
 ## Quick Start
 
 This short tutorial will set you up to start using Apify SDK in a minute or two.
-If you want to learn more, proceed to the [Apify Platform](https://docs.apify.com/sdk/js/docs/guides/apify-platform)
+If you want to learn more, proceed to the [Apify Platform](https://docs.apify.com/sdk/js/docs/concepts/actor-lifecycle)
 guide that will take you step by step through running your Actor on Apify's platform.
 
 Apify SDK requires [Node.js](https://nodejs.org/en/) 16 or later. Add Apify SDK to any Node.js project by running:
 
 ```bash
-npm install apify crawlee playwright
+npm install apify
 ```
 
-> For this example, we'll also install the [`crawlee`](https://npmjs.org/crawlee) module, as it now provides the crawlers that were previously exported by Apify SDK. If you don't plan to use crawlers in your Actors, then you don't need to install it. Keep in mind that neither `playwright` nor `puppeteer` are bundled with `crawlee` in order to reduce install size and allow greater flexibility. That's why we manually install it with NPM. You can choose one, both, or neither.
-
-There are two ways to initialize your Actor: by using the `Actor.main()` function you're probably used to, or by calling `Actor.init()` and `Actor.exit()` manually. We prefer explicitly calling `init` and `exit`.
-
-### Using `Actor.init()` and `Actor.exit()`
+To initialize your Actor and to stop it use the `Actor.init()` and `Actor.exit()` functions. You also may use `Actor.main()` function for cases with multiple crawlers in one context.
 
 ```typescript
 import { Actor } from 'apify';
-import { PlaywrightCrawler } from 'crawlee';
 
 await Actor.init();
 
-const crawler = new PlaywrightCrawler({
-    async requestHandler({ request, page, enqueueLinks }) {
-        // Extract HTML title of the page.
-        const title = await page.title();
-        console.log(`Title of ${request.url}: ${title}`);
-
-        // Add URLs that point to the same hostname.
-        await enqueueLinks();
-    },
+const input = (await Actor.getInput()) ?? {};
+await Actor.setValue('OUTPUT', {
+    message: 'Hello from Apify SDK!',
+    input,
 });
 
-await crawler.run(['https://crawlee.dev/']);
-
 await Actor.exit();
 ```
 
-### Using `Actor.main()`
-
-```typescript
-import { Actor } from 'apify';
-import { PlaywrightCrawler } from 'crawlee';
-
-await Actor.main(async () => {
-    const crawler = new PlaywrightCrawler({
-        async requestHandler({ request, page, enqueueLinks }) {
-            // Extract HTML title of the page.
-            const title = await page.title();
-            console.log(`Title of ${request.url}: ${title}`);
-
-            // Add URLs that point to the same hostname.
-            await enqueueLinks();
-        },
-    });
-
-    await crawler.run(['https://crawlee.dev/']);
-});
-```
+> You can also install the [`crawlee`](https://npmjs.org/crawlee) module, as it now provides the crawlers that were previously exported by Apify SDK. If you don't plan to use crawlers in your Actors, then you don't need to install it. Keep in mind that neither `playwright` nor `puppeteer` are bundled with `crawlee` in order to reduce install size and allow greater flexibility. That's why we manually install it with NPM. You can choose one, both, or neither. For more information and example please check [`documentation.`](https://docs.apify.com/sdk/js/docs/concepts/actor-lifecycle#running-crawlee-code-as-an-actor)
 
 ## Support
 
 If you find any bug or issue with the Apify SDK, please [submit an issue on GitHub](https://github.com/apify/apify-sdk-js/issues).
 For questions, you can ask on [Stack Overflow](https://stackoverflow.com/questions/tagged/apify) or contact support@apify.com
 
+## Upgrading
+
+Visit the [Upgrading Guide](https://docs.apify.com/sdk/js/docs/upgrading/upgrading-to-v3) to find out what changes you might want to make, and, if you encounter any issues, join our [Discord server](https://discord.gg/jyEM2PRvMU) for help!
+
 ## Contributing
 
 Your code contributions are welcome, and you'll be praised to eternity!

package/dist/actor.d.ts

@@ -1,17 +1,46 @@
-import type { ConfigurationOptions, EventManager, EventTypeName, RecordOptions, UseStateOptions } from '@crawlee/core';
+import type { EventManager, EventTypeName, RecordOptions, UseStateOptions } from '@crawlee/core';
 import { Dataset, RequestQueue } from '@crawlee/core';
 import type { Awaitable, Dictionary, SetStatusMessageOptions, StorageClient } from '@crawlee/types';
-import type { ActorCallOptions, ApifyClientOptions, RunAbortOptions, TaskCallOptions, Webhook, WebhookEventType } from 'apify-client';
+import type { ActorCallOptions, ActorStartOptions, ApifyClientOptions, RunAbortOptions, TaskCallOptions, Webhook, WebhookEventType } from 'apify-client';
 import { ActorRun as ClientActorRun, ApifyClient } from 'apify-client';
+import { type ACTOR_PERMISSION_LEVEL } from '@apify/consts';
 import type { ChargeOptions, ChargeResult } from './charging.js';
 import { ChargingManager } from './charging.js';
+import type { ConfigurationOptions } from './configuration.js';
 import { Configuration } from './configuration.js';
 import { KeyValueStore } from './key_value_store.js';
 import type { ProxyConfigurationOptions } from './proxy_configuration.js';
 import { ProxyConfiguration } from './proxy_configuration.js';
+import type { OpenStorageOptions, StorageIdentifier, StorageIdentifierWithoutAlias } from './storage.js';
 export interface InitOptions {
     storage?: StorageClient;
+    /**
+     * Whether to automatically handle platform shutdown signals.
+     * When enabled, `Actor.exit()` is called on `aborting` events and `Actor.reboot()` on `migrating` events.
+     * @default true
+     */
+    gracefulShutdown?: boolean;
+    /**
+     * Delay in milliseconds before calling `Actor.exit()`/`Actor.reboot()` on `aborting`/`migrating` events.
+     * Since both methods already wait for all event handlers to complete, this delay is usually unnecessary.
+     * @default 0
+     */
+    gracefulShutdownDelayMillis?: number;
 }
+/**
+ * Options accepted by the {@link Actor} constructor. Either pass field-level
+ * overrides (`token`, `inputKey`, …) — which the Actor turns into a fresh
+ * {@link Configuration} — or pass a pre-built `configuration` instance. When
+ * both are present, `configuration` wins and the field-level overrides are
+ * ignored.
+ */
+export type ActorOptions = ConfigurationOptions & {
+    /**
+     * Pre-built {@link Configuration} instance the Actor should use. Takes
+     * precedence over any field-level overrides also passed in `options`.
+     */
+    configuration?: Configuration;
+};
 export interface ExitOptions {
     /** Exit with given status message */
     statusMessage?: string;
@@ -48,11 +77,19 @@ export interface ApifyEnv {
      * ID of the Actor build used in the run. (ACTOR_BUILD_ID)
      */
     actorBuildId: string | null;
+    /**
+     * [Permission level](https://docs.apify.com/platform/actors/development/permissions) the Actor is run under. (ACTOR_PERMISSION_LEVEL)
+     */
+    actorPermissionLevel: ACTOR_PERMISSION_LEVEL | null;
     /**
      * ID of the user who started the Actor - note that it might be
      * different than the owner of the Actor (APIFY_USER_ID)
      */
     userId: string | null;
+    /**
+     * If it is `1`, it means that the user who started the Actor is a paying user. (APIFY_USER_IS_PAYING)
+     */
+    userIsPaying: string | null;
     /**
      * Authentication token representing privileges given to the Actor run,
      * it can be passed to various Apify APIs (APIFY_TOKEN)
@@ -113,7 +150,7 @@ export interface ApifyEnv {
      * Defines the path to a local directory where KeyValueStore, Dataset, and RequestQueue
      * store their data. Typically, it is set to ./storage. If omitted, you should define the
      * APIFY_TOKEN environment variable instead. See more info on combination of this and
-     * APIFY_TOKEN [here](https://docs.apify.com/sdk/js/docs/guides/environment-variables#combinations-of-apify_local_storage_dir-and-apify_token)(CRAWLEE_STORAGE_DIR)
+     * APIFY_TOKEN [here](https://docs.apify.com/sdk/js/docs/concepts/environment-variables#combinations-of-apify_local_storage_dir-and-apify_token)(CRAWLEE_STORAGE_DIR)
      */
     localStorageDir: string | null;
     /**
@@ -142,23 +179,28 @@ export interface ApifyEnv {
     defaultRequestQueueId: string | null;
 }
 export type UserFunc<T = unknown> = () => Awaitable<T>;
-export interface CallOptions extends ActorCallOptions {
+export interface Token {
     /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
+     * User Apify API token that is used for API calls. By default, it is taken from the `APIFY_TOKEN` environment variable.
      */
     token?: string;
 }
-export interface CallTaskOptions extends TaskCallOptions {
+export interface Timeout {
     /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
+     * Timeout for the Actor run in seconds, or `'inherit'`.
+     *
+     * Using `inherit` will set timeout of the newly started Actor run to the time
+     * remaining until this Actor run times out so that the new run does not outlive this one.
      */
-    token?: string;
+    timeout?: number | 'inherit';
 }
-export interface AbortOptions extends RunAbortOptions {
-    /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
-     */
-    token?: string;
+export interface CallOptions extends Omit<ActorCallOptions, 'timeout'>, Token, Timeout {
+}
+export interface StartOptions extends Omit<ActorStartOptions, 'waitForFinish' | 'timeout'>, Token, Timeout {
+}
+export interface CallTaskOptions extends Omit<TaskCallOptions, 'timeout'>, Token, Timeout {
+}
+export interface AbortOptions extends RunAbortOptions, Token {
     /** Exit with given status message */
     statusMessage?: string;
 }
@@ -188,6 +230,35 @@ export interface WebhookOptions {
      * {@link Actor.getEnv} function.
      */
     idempotencyKey?: string;
+    /**
+     * Headers template is a JSON-like string that describes the HTTP headers to be sent with the webhook POST request.
+     * It uses JSON syntax, extended with a double curly braces syntax for injecting variables `{{variable}}`.
+     * Those variables are resolved at the time of the webhook's dispatch, and a list of available variables with their descriptions
+     * is available in the [Apify webhook documentation](https://docs.apify.com/webhooks).
+     * If `headersTemplate` is omitted, no extra headers are added
+     * ([view docs](https://docs.apify.com/platform/integrations/webhooks/actions#headers-template)).
+     */
+    headersTemplate?: string;
+    /**
+     * A description of the webhook.
+     */
+    description?: string;
+    /**
+     * If true, the webhook will ignore SSL errors when sending the request.
+     */
+    ignoreSslErrors?: boolean;
+    /**
+     * If true, the webhook will not retry on failure.
+     */
+    doNotRetry?: boolean;
+    /**
+     * If true, the webhook will interpolate strings in the payloadTemplate and headersTemplate.
+     */
+    shouldInterpolateStrings?: boolean;
+    /**
+     * If true, indicates the webhook is an Apify integration.
+     */
+    isApifyIntegration?: boolean;
 }
 export interface MetamorphOptions {
     /**
@@ -209,14 +280,6 @@ export interface RebootOptions {
     /** @internal */
     customAfterSleepMillis?: number;
 }
-export interface OpenStorageOptions {
-    /**
-     * If set to `true` then the cloud storage is used even if the `CRAWLEE_STORAGE_DIR`
-     * environment variable is set. This way it is possible to combine local and cloud storage.
-     * @default false
-     */
-    forceCloud?: boolean;
-}
 export { ClientActorRun as ActorRun };
 /**
  * Exit codes for the Actor process.
@@ -265,8 +328,22 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * Set if the Actor is currently rebooting.
      */
     private isRebooting;
+    /**
+     * Set if the Actor is currently exiting. Prevents double-exit from graceful shutdown handlers.
+     */
+    private isExiting;
+    /**
+     * References to graceful shutdown handlers so they can be removed during cleanup.
+     */
+    private gracefulShutdownHandlers;
     private chargingManager;
-    constructor(options?: ConfigurationOptions);
+    /**
+     * Tracks which aliased storages have been purged during this session,
+     * so we only purge them once (on first open) when running locally.
+     * @internal
+     */
+    purgedStorageAliases: Set<string>;
+    constructor(options?: ActorOptions);
     /**
      * Runs the main user function that performs the job of the Actor
      * and terminates the process when the user function finishes.
@@ -399,7 +476,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [options]
      * @ignore
      */
-    start(actorId: string, input?: unknown, options?: CallOptions): Promise<ClientActorRun>;
+    start(actorId: string, input?: unknown, options?: StartOptions): Promise<ClientActorRun>;
     /**
      * Aborts given Actor run on the Apify platform using the current user account (determined by the `APIFY_TOKEN` environment variable).
      *
@@ -487,31 +564,6 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @ignore
      */
     setStatusMessage(statusMessage: string, options?: SetStatusMessageOptions): Promise<ClientActorRun>;
-    /**
-     * Stores an object or an array of objects to the default {@link Dataset} of the current Actor run.
-     *
-     * This is just a convenient shortcut for {@link Dataset.pushData}.
-     * For example, calling the following code:
-     * ```js
-     * await Actor.pushData({ myValue: 123 });
-     * ```
-     *
-     * is equivalent to:
-     * ```js
-     * const dataset = await Actor.openDataset();
-     * await dataset.pushData({ myValue: 123 });
-     * ```
-     *
-     * For more information, see {@link Actor.openDataset} and {@link Dataset.pushData}
-     *
-     * **IMPORTANT**: Make sure to use the `await` keyword when calling `pushData()`,
-     * otherwise the Actor process might finish before the data are stored!
-     *
-     * @param item Object or array of objects containing data to be stored in the default dataset.
-     * The objects must be serializable to JSON and the JSON representation of each object must be smaller than 9MB.
-     * @ignore
-     */
-    pushData(item: Data | Data[]): Promise<void>;
     /**
      * Stores an object or an array of objects to the default {@link Dataset} of the current Actor run.
      *
@@ -537,7 +589,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param eventName If provided, the method will attempt to charge for the event for each pushed item.
      * @ignore
      */
-    pushData(item: Data | Data[], eventName: string): Promise<ChargeResult>;
+    pushData(item: Data | Data[], eventName?: string | undefined): Promise<ChargeResult>;
     /**
      * Opens a dataset and returns a promise resolving to an instance of the {@link Dataset} class.
      *
@@ -548,12 +600,14 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * For more details and code examples, see the {@link Dataset} class.
      *
      * @param [datasetIdOrName]
-     *   ID or name of the dataset to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
+     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
+     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
-    openDataset(datasetIdOrName?: string | null, options?: OpenStorageOptions): Promise<Dataset<Data>>;
+    openDataset(datasetIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<Dataset<Data>>;
     /**
      * Gets a value from the default {@link KeyValueStore} associated with the current Actor run.
      *
@@ -662,10 +716,11 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [storeIdOrName]
      *   ID or name of the key-value store to be opened. If `null` or `undefined`,
      *   the function returns the default key-value store associated with the Actor run.
+     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
-    openKeyValueStore(storeIdOrName?: string | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
+    openKeyValueStore(storeIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
     /**
      * Opens a request queue and returns a promise resolving to an instance
      * of the {@link RequestQueue} class.
@@ -680,10 +735,11 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [queueIdOrName]
      *   ID or name of the request queue to be opened. If `null` or `undefined`,
      *   the function returns the default request queue associated with the Actor run.
+     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
-    openRequestQueue(queueIdOrName?: string | null, options?: OpenStorageOptions): Promise<RequestQueue>;
+    openRequestQueue(queueIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<RequestQueue>;
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the {@link ProxyConfiguration} class that is already initialized.
@@ -718,6 +774,10 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * ```
      * { useApifyProxy: false }
      * ```
+     *
+     * As part of the init process, we verify the configuration by checking the proxy status endpoint.
+     * This can make the init slower, to opt-out of this, use `checkAccess: false` (defaults to `true`).
+     *
      * @ignore
      */
     createProxyConfiguration(proxyConfigurationOptions?: ProxyConfigurationOptions & {
@@ -729,6 +789,14 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * This method attempts to charge for the specified number of events, but may charge fewer
      * if doing so would exceed the total budget limit (`maxTotalChargeUsd`).
      *
+     * **Important:** When using the `count` parameter to charge for multiple events at once,
+     * be aware that the charge may be partially fulfilled — i.e. `chargedCount` can be less
+     * than the requested `count`. Always check the returned `chargedCount` to know how many
+     * events were actually charged, and only perform that much work. If your work is
+     * meaningfully divisible into individual units, prefer calling `charge()` once per unit
+     * rather than batching via `count` — this gives finer control over budget consumption
+     * and avoids situations where more work is requested than the budget allows.
+     *
      * @param options The name of the event to charge for and the number of events to be charged.
      * @ignore
      */
@@ -746,7 +814,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * Returns a new {@link ApifyEnv} object which contains information parsed from all the Apify environment variables.
      *
      * For the list of the Apify environment variables, see
-     * [Actor documentation](https://docs.apify.com/actor/run#environment-variables).
+     * [Actor documentation](https://docs.apify.com/platform/actors/development/programming-interface/environment-variables).
      * If some variables are not defined or are invalid, the corresponding value in the resulting object will be null.
      * @ignore
      */
@@ -857,6 +925,11 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * Calling `Actor.exit()` is required if you use the `Actor.init()` method, since it opens websocket connection
      * (see {@link Actor.events} for details), which needs to be terminated for the code to finish.
      *
+     * **Graceful shutdown:** When running on the Apify platform, the Actor may receive `aborting` or `migrating`
+     * events. By default, the SDK will automatically call `Actor.exit()` on `aborting` events and `Actor.reboot()`
+     * on `migrating` events (to speed up the migration and continue the run on a new worker). You can disable this
+     * behavior by setting `options.gracefulShutdown` to `false`.
+     *
      * ```js
      * import { gotScraping } from 'got-scraping';
      *
@@ -958,7 +1031,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      *  Otherwise the `options.contentType` parameter must be provided.
      * @param [options]
      */
-    static start(actorId: string, input?: Dictionary, options?: CallOptions): Promise<ClientActorRun>;
+    static start(actorId: string, input?: Dictionary, options?: StartOptions): Promise<ClientActorRun>;
     /**
      * Aborts given Actor run on the Apify platform using the current user account (determined by the `APIFY_TOKEN` environment variable).
      *
@@ -1076,11 +1149,13 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * For more details and code examples, see the {@link Dataset} class.
      *
      * @param [datasetIdOrName]
-     *   ID or name of the dataset to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
+     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
+     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
-    static openDataset<Data extends Dictionary = Dictionary>(datasetIdOrName?: string | null, options?: OpenStorageOptions): Promise<Dataset<Data>>;
+    static openDataset<Data extends Dictionary = Dictionary>(datasetIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<Dataset<Data>>;
     /**
      * Gets a value from the default {@link KeyValueStore} associated with the current Actor run.
      *
@@ -1185,9 +1260,10 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [storeIdOrName]
      *   ID or name of the key-value store to be opened. If `null` or `undefined`,
      *   the function returns the default key-value store associated with the Actor run.
+     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
-    static openKeyValueStore(storeIdOrName?: string | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
+    static openKeyValueStore(storeIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
     /**
      * Opens a request queue and returns a promise resolving to an instance
      * of the {@link RequestQueue} class.
@@ -1202,9 +1278,10 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [queueIdOrName]
      *   ID or name of the request queue to be opened. If `null` or `undefined`,
      *   the function returns the default request queue associated with the Actor run.
+     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
-    static openRequestQueue(queueIdOrName?: string | null, options?: OpenStorageOptions): Promise<RequestQueue>;
+    static openRequestQueue(queueIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<RequestQueue>;
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the {@link ProxyConfiguration} class that is already initialized.
@@ -1239,6 +1316,9 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * ```
      * { useApifyProxy: false }
      * ```
+     *
+     * As part of the init process, we verify the configuration by checking the proxy status endpoint.
+     * This can make the init slower, to opt-out of this, use `checkAccess: false` (defaults to `true`).
      */
     static createProxyConfiguration(proxyConfigurationOptions?: ProxyConfigurationOptions & {
         useApifyProxy?: boolean;
@@ -1249,6 +1329,14 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * This method attempts to charge for the specified number of events, but may charge fewer
      * if doing so would exceed the total budget limit (`maxTotalChargeUsd`).
      *
+     * **Important:** When using the `count` parameter to charge for multiple events at once,
+     * be aware that the charge may be partially fulfilled — i.e. `chargedCount` can be less
+     * than the requested `count`. Always check the returned `chargedCount` to know how many
+     * events were actually charged, and only perform that much work. If your work is
+     * meaningfully divisible into individual units, prefer calling `charge()` once per unit
+     * rather than batching via `count` — this gives finer control over budget consumption
+     * and avoids situations where more work is requested than the budget allows.
+     *
      * @param options The name of the event to charge for and the number of events to be charged.
      */
     static charge(options: ChargeOptions): Promise<ChargeResult>;
@@ -1260,7 +1348,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * Returns a new {@link ApifyEnv} object which contains information parsed from all the Apify environment variables.
      *
      * For the list of the Apify environment variables, see
-     * [Actor documentation](https://docs.apify.com/actor/run#environment-variables).
+     * [Actor documentation](https://docs.apify.com/platform/actors/development/programming-interface/environment-variables).
      * If some of the variables are not defined or are invalid, the corresponding value in the resulting object will be null.
      */
     static getEnv(): ApifyEnv;
@@ -1282,7 +1370,15 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
     static get config(): Configuration;
     /** @internal */
     static getDefaultInstance(): Actor;
+    private usesPushDataInterception;
+    private pushDataViaInterceptedClient;
+    private pushDataWithExplicitCharging;
     private _openStorage;
     private _ensureActorInit;
+    /**
+     * Get time remaining from the Actor run timeout. Returns `undefined` if not on an Apify platform or the current
+     * run was started without a timeout.
+     */
+    private getRemainingTime;
+    private inferDefaultsFromInputSchema;
 }
-//# sourceMappingURL=actor.d.ts.map