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

package/dist/actor.js

@@ -1,18 +1,21 @@
 import { createPrivateKey } from 'node:crypto';
-import { Configuration as CoreConfiguration, Dataset, purgeDefaultStorages, RequestQueue, StorageManager, } from '@crawlee/core';
+import { Dataset, purgeDefaultStorages, RequestQueue, serviceLocator } from '@crawlee/core';
 import { sleep, snakeCaseToCamelCase } from '@crawlee/utils';
 import { ApifyClient } from 'apify-client';
 import ow from 'ow';
-import { ACTOR_ENV_VARS, APIFY_ENV_VARS, INTEGER_ENV_VARS, } from '@apify/consts';
+import { ACTOR_ENV_VARS, ACTOR_EVENT_NAMES, APIFY_ENV_VARS, INTEGER_ENV_VARS, } from '@apify/consts';
 import { decryptInputSecrets } from '@apify/input_secrets';
 import log from '@apify/log';
 import { addTimeoutToPromise } from '@apify/timeout';
-import { ChargingManager } from './charging.js';
+import { ApifyStorageClient, pushDataChargingContext, USES_PUSH_DATA_INTERCEPTION, } from './apify_storage_client.js';
+import { ChargingManager, pushDataAndCharge } from './charging.js';
 import { Configuration } from './configuration.js';
+import { getDefaultsFromInputSchema, noActorInputSchemaDefinedMarker, readInputSchema } from './input-schemas.js';
 import { KeyValueStore } from './key_value_store.js';
 import { PlatformEventManager } from './platform_event_manager.js';
 import { ProxyConfiguration } from './proxy_configuration.js';
-import { checkCrawleeVersion, getSystemInfo, printOutdatedSdkWarning, } from './utils.js';
+import { openStorage } from './storage.js';
+import { checkCrawleeVersion, getSystemInfo, printOutdatedSdkWarning } from './utils.js';
 /**
  * Exit codes for the Actor process.
  * The error codes must be in the range 1-128, to avoid collision with signal exits
@@ -31,7 +34,6 @@ export const EXIT_CODES = {
  */
 export class Actor {
     /** @internal */
-    // eslint-disable-next-line no-use-before-define -- self-reference
     static _instance;
     /**
      * Configuration of this SDK instance (provided to its constructor). See {@link Configuration} for details.
@@ -61,13 +63,43 @@ export class Actor {
      * Set if the Actor is currently rebooting.
      */
     isRebooting = false;
+    /**
+     * Set if the Actor is currently exiting. Prevents double-exit from graceful shutdown handlers.
+     */
+    isExiting = false;
+    /**
+     * References to graceful shutdown handlers so they can be removed during cleanup.
+     */
+    gracefulShutdownHandlers = {};
     chargingManager;
+    /**
+     * Tracks which aliased storages have been purged during this session,
+     * so we only purge them once (on first open) when running locally.
+     * @internal
+     */
+    purgedStorageAliases = new Set();
     constructor(options = {}) {
-        // use default configuration object if nothing overridden (it fallbacks to env vars)
-        this.config =
-            Object.keys(options).length === 0
-                ? Configuration.getGlobalConfig()
-                : new Configuration(options);
+        const { configuration, ...configOptions } = options;
+        if (configuration) {
+            // BYO Configuration takes precedence; field-level overrides are
+            // ignored to keep the contract unambiguous. It must be the SDK's
+            // Configuration subclass, not a bare crawlee one — env-var
+            // resolution is driven by the subclass's `static fields`
+            // (`apifyConfigFields`) at construction, so a crawlee instance
+            // would silently expose none of the `APIFY_*`/`ACTOR_*` values.
+            if (!(configuration instanceof Configuration)) {
+                throw new Error('Actor `configuration` must be an Apify SDK Configuration (imported from `apify`), ' +
+                    'not a crawlee Configuration, otherwise APIFY_*/ACTOR_* environment variables are not resolved.');
+            }
+            this.config = configuration;
+        }
+        else if (Object.keys(configOptions).length === 0) {
+            // use default configuration object if nothing overridden (it fallbacks to env vars)
+            this.config = Configuration.getGlobalConfig();
+        }
+        else {
+            this.config = new Configuration(configOptions);
+        }
         this.apifyClient = this.newClient();
         this.eventManager = new PlatformEventManager(this.config);
         this.chargingManager = new ChargingManager(this.config, this.apifyClient);
@@ -173,26 +205,48 @@ export class Actor {
         checkCrawleeVersion();
         log.info('System info', getSystemInfo());
         printOutdatedSdkWarning();
-        // reset global config instance to respect APIFY_ prefixed env vars
-        CoreConfiguration.globalConfig = Configuration.getGlobalConfig();
+        // Register this Actor's config as the global one so crawlee storages and
+        // the event manager resolve the same instance (`availableMemoryRatio` /
+        // `disableBrowserSandbox` at-home defaults now live in `Configuration`).
+        serviceLocator.setConfiguration(this.config);
         if (this.isAtHome()) {
-            this.config.set('availableMemoryRatio', 1);
-            this.config.set('disableBrowserSandbox', true); // for browser launcher, adds `--no-sandbox` to args
-            this.config.useStorageClient(this.apifyClient);
-            this.config.useEventManager(this.eventManager);
+            serviceLocator.setStorageClient(new ApifyStorageClient(this.apifyClient, this.config, () => this.chargingManager));
+            serviceLocator.setEventManager(this.eventManager);
         }
         else if (options.storage) {
-            this.config.useStorageClient(options.storage);
+            serviceLocator.setStorageClient(options.storage);
         }
         // Init the event manager the config uses
-        await this.config.getEventManager().init();
+        await serviceLocator.getEventManager().init();
         log.debug(`Events initialized`);
+        // Register handlers for aborting and migrating events for automatic graceful shutdown.
+        // - aborting: calls Actor.exit() to terminate the run gracefully
+        // - migrating: calls Actor.reboot() to speed up migration (the run continues on a new worker)
+        // Using setTimeout to avoid deadlock with waitForAllListenersToComplete() in exit()/reboot()
+        if (options.gracefulShutdown !== false) {
+            const delay = options.gracefulShutdownDelayMillis ?? 0;
+            this.gracefulShutdownHandlers.aborting = () => {
+                setTimeout(() => {
+                    this.exit().catch((err) => {
+                        log.exception(err, 'Failed to exit gracefully');
+                    });
+                }, delay);
+            };
+            this.on(ACTOR_EVENT_NAMES.ABORTING, this.gracefulShutdownHandlers.aborting);
+            this.gracefulShutdownHandlers.migrating = () => {
+                setTimeout(() => {
+                    this.reboot().catch((err) => {
+                        log.exception(err, 'Failed to reboot on migration');
+                    });
+                }, delay);
+            };
+            this.on(ACTOR_EVENT_NAMES.MIGRATING, this.gracefulShutdownHandlers.migrating);
+        }
         await purgeDefaultStorages({
             config: this.config,
             onlyPurgeOnce: true,
         });
         log.debug(`Default storages purged`);
-        Configuration.storage.enterWith(this.config);
         await this.chargingManager.init();
         log.debug(`ChargingManager initialized`, this.chargingManager.getPricingInfo());
     }
@@ -200,6 +254,12 @@ export class Actor {
      * @ignore
      */
     async exit(messageOrOptions, options = {}) {
+        // Prevent double-exit from graceful shutdown handlers
+        if (this.isExiting) {
+            log.debug('Actor.exit() called while already exiting, skipping');
+            return;
+        }
+        this.isExiting = true;
         options =
             typeof messageOrOptions === 'string'
                 ? { ...options, statusMessage: messageOrOptions }
@@ -207,8 +267,16 @@ export class Actor {
         options.exit ??= true;
         options.exitCode ??= EXIT_CODES.SUCCESS;
         options.timeoutSecs ??= 30;
-        const client = this.config.getStorageClient();
-        const events = this.config.getEventManager();
+        this._ensureActorInit('exit');
+        const client = serviceLocator.getStorageClient();
+        const events = serviceLocator.getEventManager();
+        // Remove graceful shutdown handlers to prevent them from interfering with exit
+        if (this.gracefulShutdownHandlers.aborting) {
+            this.off(ACTOR_EVENT_NAMES.ABORTING, this.gracefulShutdownHandlers.aborting);
+        }
+        if (this.gracefulShutdownHandlers.migrating) {
+            this.off(ACTOR_EVENT_NAMES.MIGRATING, this.gracefulShutdownHandlers.migrating);
+        }
         // Close the event manager and emit the final PERSIST_STATE event
         await events.close();
         log.debug(`Events closed`);
@@ -216,6 +284,13 @@ export class Actor {
         events.emit("exit" /* EventType.EXIT */, options);
         // Wait for all event listeners to be processed
         log.debug(`Waiting for all event listeners to complete their execution (with ${options.timeoutSecs} seconds timeout)`);
+        if (options.exit) {
+            // `addTimeoutToPromise` is a cooperative timeout. This ensures that the process exits
+            // after the timeout, even if the event listeners don't trigger the timeout.
+            setTimeout(() => {
+                process.exit(options.exitCode);
+            }, options.timeoutSecs * 1000);
+        }
         await addTimeoutToPromise(async () => {
             await events.waitForAllListenersToComplete();
             if (client.teardown) {
@@ -229,16 +304,21 @@ export class Actor {
                 finished = true;
             }
             if (options.statusMessage != null) {
-                await this.setStatusMessage(options.statusMessage, {
+                const statusMessagePromise = this.setStatusMessage(options.statusMessage, {
                     isStatusMessageTerminal: true,
                     level: options.exitCode > 0 ? 'ERROR' : 'INFO',
                 });
+                // Waiting 1ms is enough for the network request to be sent. We don't need to wait for the response.
+                await Promise.race([statusMessagePromise, sleep(1)]);
             }
         }, options.timeoutSecs * 1000, `Waiting for all event listeners to complete their execution timed out after ${options.timeoutSecs} seconds`).catch(() => {
             if (options.exit) {
                 process.exit(options.exitCode);
             }
         });
+        // Reset the flag so the instance can be reused (e.g., in tests or when exit is false).
+        // When process.exit() actually terminates the process, this line is never reached - which is fine.
+        this.isExiting = false;
         if (!options.exit) {
             return;
         }
@@ -254,13 +334,13 @@ export class Actor {
      * @ignore
      */
     on(event, listener) {
-        this.config.getEventManager().on(event, listener);
+        serviceLocator.getEventManager().on(event, listener);
     }
     /**
      * @ignore
      */
     off(event, listener) {
-        this.config.getEventManager().off(event, listener);
+        serviceLocator.getEventManager().off(event, listener);
     }
     /**
      * Runs an Actor on the Apify platform using the current user account (determined by the `APIFY_TOKEN` environment variable).
@@ -287,9 +367,10 @@ export class Actor {
      * @ignore
      */
     async call(actorId, input, options = {}) {
+        const timeout = options.timeout === 'inherit' ? this.getRemainingTime() : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
-        return client.actor(actorId).call(input, rest);
+        return client.actor(actorId).call(input, { ...rest, timeout });
     }
     /**
      * Runs an Actor on the Apify platform using the current user account (determined by the `APIFY_TOKEN` environment variable),
@@ -316,9 +397,10 @@ export class Actor {
      * @ignore
      */
     async start(actorId, input, options = {}) {
+        const timeout = options.timeout === 'inherit' ? this.getRemainingTime() : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
-        return client.actor(actorId).start(input, rest);
+        return client.actor(actorId).start(input, { ...rest, timeout });
     }
     /**
      * Aborts given Actor run on the Apify platform using the current user account (determined by the `APIFY_TOKEN` environment variable).
@@ -372,9 +454,10 @@ export class Actor {
      * @ignore
      */
     async callTask(taskId, input, options = {}) {
+        const timeout = options.timeout === 'inherit' ? this.getRemainingTime() : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
-        return client.task(taskId).call(input, rest);
+        return client.task(taskId).call(input, { ...rest, timeout });
     }
     /**
      * Transforms this Actor run to an Actor run of a given Actor. The system stops the current container and starts
@@ -395,11 +478,9 @@ export class Actor {
             log.warning('Actor.metamorph() is only supported when running on the Apify platform.');
             return;
         }
-        const { customAfterSleepMillis = this.config.get('metamorphAfterSleepMillis'), ...metamorphOpts } = options;
-        const runId = this.config.get('actorRunId');
-        await this.apifyClient
-            .run(runId)
-            .metamorph(targetActorId, input, metamorphOpts);
+        const { customAfterSleepMillis = this.config.metamorphAfterSleepMillis, ...metamorphOpts } = options;
+        const runId = this.config.actorRunId;
+        await this.apifyClient.run(runId).metamorph(targetActorId, input, metamorphOpts);
         // Wait some time for container to be stopped.
         await sleep(customAfterSleepMillis);
     }
@@ -411,6 +492,7 @@ export class Actor {
      * @ignore
      */
     async reboot(options = {}) {
+        this._ensureActorInit('reboot');
         if (!this.isAtHome()) {
             log.warning('Actor.reboot() is only supported when running on the Apify platform.');
             return;
@@ -423,20 +505,20 @@ export class Actor {
         // Waiting for all the listeners to finish, as `.reboot()` kills the container.
         await Promise.all([
             // `persistState` for individual RequestLists, RequestQueue... instances to be persisted
-            ...this.config
+            ...serviceLocator
                 .getEventManager()
                 .listeners("persistState" /* EventType.PERSIST_STATE */)
-                .map(async (x) => x()),
+                .map(async (x) => x({})),
             // `migrating` to pause Apify crawlers
-            ...this.config
+            ...serviceLocator
                 .getEventManager()
                 .listeners("migrating" /* EventType.MIGRATING */)
-                .map(async (x) => x()),
+                .map(async (x) => x({})),
         ]);
-        const runId = this.config.get('actorRunId');
+        const runId = this.config.actorRunId;
         await this.apifyClient.run(runId).reboot();
         // Wait some time for container to be stopped.
-        const { customAfterSleepMillis = this.config.get('metamorphAfterSleepMillis'), } = options;
+        const { customAfterSleepMillis = this.config.metamorphAfterSleepMillis } = options;
         await sleep(customAfterSleepMillis);
     }
     /**
@@ -457,25 +539,27 @@ export class Actor {
             requestUrl: ow.string,
             payloadTemplate: ow.optional.string,
             idempotencyKey: ow.optional.string,
+            headersTemplate: ow.optional.string,
+            description: ow.optional.string,
+            ignoreSslErrors: ow.optional.boolean,
+            doNotRetry: ow.optional.boolean,
+            shouldInterpolateStrings: ow.optional.boolean,
+            isApifyIntegration: ow.optional.boolean,
         }));
-        const { eventTypes, requestUrl, payloadTemplate, idempotencyKey } = options;
         if (!this.isAtHome()) {
             log.warning('Actor.addWebhook() is only supported when running on the Apify platform. The webhook will not be invoked.');
             return undefined;
         }
-        const runId = this.config.get('actorRunId');
+        const runId = this.config.actorRunId;
         if (!runId) {
             throw new Error(`Environment variable ${ACTOR_ENV_VARS.RUN_ID} is not set!`);
         }
         return this.apifyClient.webhooks().create({
+            ...options,
             isAdHoc: true,
-            eventTypes,
             condition: {
                 actorRunId: runId,
             },
-            requestUrl,
-            payloadTemplate,
-            idempotencyKey,
         });
     }
     /**
@@ -489,6 +573,7 @@ export class Actor {
         const { isStatusMessageTerminal, level } = options || {};
         ow(statusMessage, ow.string);
         ow(isStatusMessageTerminal, ow.optional.boolean);
+        this._ensureActorInit('setStatusMessage');
         const loggedStatusMessage = `[Status message]: ${statusMessage}`;
         switch (level) {
             case 'DEBUG':
@@ -504,13 +589,13 @@ export class Actor {
                 log.info(loggedStatusMessage);
                 break;
         }
-        const client = this.config.getStorageClient();
+        const client = serviceLocator.getStorageClient();
         // just to be sure, this should be fast
         await addTimeoutToPromise(async () => client.setStatusMessage(statusMessage, {
             isStatusMessageTerminal,
             level,
         }), 1000, 'Setting status message timed out after 1s').catch((e) => log.warning(e.message));
-        const runId = this.config.get('actorRunId');
+        const runId = this.config.actorRunId;
         if (runId) {
             // just to be sure, this should be fast
             const run = await addTimeoutToPromise(async () => this.apifyClient.run(runId).get(), 1000, 'Getting the current run timed out after 1s').catch((e) => log.warning(e.message));
@@ -545,28 +630,22 @@ export class Actor {
      * @param eventName If provided, the method will attempt to charge for the event for each pushed item.
      * @ignore
      */
-    // eslint-disable-next-line consistent-return -- The `return` is inconsistent by design here (`ChargeResult` with `eventName` parameter)
     async pushData(item, eventName) {
         this._ensureActorInit('pushData');
-        const dataset = await this.openDataset();
-        const maxChargedCount = eventName !== undefined
-            ? this.chargingManager.calculateMaxEventChargeCountWithinLimit(eventName)
-            : Infinity;
-        const toCharge = Array.isArray(item) ? item.length : 1;
-        if (toCharge > maxChargedCount) {
-            // Push as many items as we can charge for
-            const items = Array.isArray(item) ? item : [item];
-            await dataset.pushData(items.slice(0, maxChargedCount));
-        }
-        else {
-            await dataset.pushData(item);
+        if (eventName?.startsWith('apify-')) {
+            throw new Error(`Cannot charge for synthetic event '${eventName}' manually`);
         }
-        if (eventName) {
-            return await this.chargingManager.charge({
-                eventName,
-                count: Math.min(toCharge, maxChargedCount),
-            });
+        const dataset = await this.openDataset();
+        // Two code paths for charging:
+        // 1. Intercepted client: PatchedDatasetClient intercepts pushItems() calls, handling charging
+        //    internally. This is needed because Crawlee's Dataset may call pushItems() directly,
+        //    bypassing Actor.pushData(). We propagate eventName via AsyncLocalStorage context.
+        // 2. Direct charging: When using a non-patched client (e.g., forceCloud option or custom client),
+        //    we handle charging here before delegating to the dataset.
+        if (this.usesPushDataInterception(dataset)) {
+            return await this.pushDataViaInterceptedClient(dataset, item, eventName);
         }
+        return await this.pushDataWithExplicitCharging(dataset, item, eventName);
     }
     /**
      * Opens a dataset and returns a promise resolving to an instance of the {@link Dataset} class.
@@ -578,13 +657,14 @@ export class Actor {
      * 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
      */
     async openDataset(datasetIdOrName, options = {}) {
-        ow(datasetIdOrName, ow.optional.string);
         ow(options, ow.object.exactShape({
             forceCloud: ow.optional.boolean,
         }));
@@ -691,17 +771,20 @@ export class Actor {
      */
     async getInput() {
         this._ensureActorInit('getInput');
-        const inputSecretsPrivateKeyFile = this.config.get('inputSecretsPrivateKeyFile');
-        const inputSecretsPrivateKeyPassphrase = this.config.get('inputSecretsPrivateKeyPassphrase');
-        const input = await this.getValue(this.config.get('inputKey'));
-        if (ow.isValid(input, ow.object.nonEmpty) &&
+        const { inputSecretsPrivateKeyFile, inputSecretsPrivateKeyPassphrase } = this.config;
+        const rawInput = await this.getValue(this.config.inputKey);
+        let input = rawInput;
+        if (ow.isValid(rawInput, ow.object.nonEmpty) &&
             inputSecretsPrivateKeyFile &&
             inputSecretsPrivateKeyPassphrase) {
             const privateKey = createPrivateKey({
                 key: Buffer.from(inputSecretsPrivateKeyFile, 'base64'),
                 passphrase: inputSecretsPrivateKeyPassphrase,
             });
-            return decryptInputSecrets({ input, privateKey });
+            input = decryptInputSecrets({ input: rawInput, privateKey });
+        }
+        if (ow.isValid(input, ow.object.nonEmpty) && !Buffer.isBuffer(input)) {
+            input = await this.inferDefaultsFromInputSchema(input);
         }
         return input;
     }
@@ -728,11 +811,11 @@ export class Actor {
      * @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
      */
     async openKeyValueStore(storeIdOrName, options = {}) {
-        ow(storeIdOrName, ow.optional.string);
         ow(options, ow.object.exactShape({
             forceCloud: ow.optional.boolean,
         }));
@@ -753,19 +836,18 @@ export class Actor {
      * @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
      */
     async openRequestQueue(queueIdOrName, options = {}) {
-        ow(queueIdOrName, ow.optional.string);
         ow(options, ow.object.exactShape({
             forceCloud: ow.optional.boolean,
         }));
         this._ensureActorInit('openRequestQueue');
         const queue = await this._openStorage(RequestQueue, queueIdOrName, options);
         // eslint-disable-next-line dot-notation
-        queue['initialCount'] =
-            (await queue.client.get())?.totalRequestCount ?? 0;
+        queue['initialCount'] = (await queue.client.getMetadata())?.totalRequestCount ?? 0;
         return queue;
     }
     /**
@@ -802,19 +884,23 @@ export class Actor {
      * ```
      * { 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
      */
     async createProxyConfiguration(proxyConfigurationOptions = {}) {
         // Compatibility fix for Input UI where proxy: None returns { useApifyProxy: false }
         // Without this, it would cause proxy to use the zero config / auto mode.
-        const { useApifyProxy, ...options } = proxyConfigurationOptions;
+        const { useApifyProxy, checkAccess, ...options } = proxyConfigurationOptions;
         const dontUseApifyProxy = useApifyProxy === false;
         const dontUseCustomProxies = !proxyConfigurationOptions.proxyUrls;
         if (dontUseApifyProxy && dontUseCustomProxies) {
             return undefined;
         }
         const proxyConfiguration = new ProxyConfiguration(options, this.config);
-        if (await proxyConfiguration.initialize()) {
+        if (await proxyConfiguration.initialize({ checkAccess })) {
             return proxyConfiguration;
         }
         return undefined;
@@ -825,6 +911,14 @@ export class Actor {
      * 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
      */
@@ -860,7 +954,7 @@ export class Actor {
      * 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
      */
@@ -895,15 +989,13 @@ export class Actor {
      * @ignore
      */
     newClient(options = {}) {
-        const { storageDir, ...storageClientOptions } = this.config.get('storageClientOptions');
+        const { storageDir, ...storageClientOptions } = (this.config.storageClientOptions ?? {});
         const { apifyVersion, crawleeVersion } = getSystemInfo();
         return new ApifyClient({
-            baseUrl: this.config.get('apiBaseUrl'),
-            token: this.config.get('token'),
-            userAgentSuffix: [
-                `SDK/${apifyVersion}`,
-                `Crawlee/${crawleeVersion}`,
-            ],
+            baseUrl: this.config.apiBaseUrl,
+            publicBaseUrl: this.config.apiPublicBaseUrl,
+            token: this.config.token,
+            userAgentSuffix: [`SDK/${apifyVersion}`, `Crawlee/${crawleeVersion}`],
             ...storageClientOptions,
             ...options, // allow overriding the instance configuration
         });
@@ -925,6 +1017,7 @@ export class Actor {
      * @param options An optional object parameter where a custom `keyValueStoreName` and `config` can be passed in.
      */
     async useState(name, defaultValue = {}, options) {
+        this._ensureActorInit('useState');
         const kvStore = await KeyValueStore.open(options?.keyValueStoreName, {
             config: options?.config || Configuration.getGlobalConfig(),
         });
@@ -1016,6 +1109,11 @@ export class Actor {
      * 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';
      *
@@ -1242,8 +1340,10 @@ export class Actor {
      * 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 async openDataset(datasetIdOrName, options = {}) {
@@ -1361,6 +1461,7 @@ export class Actor {
      * @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 async openKeyValueStore(storeIdOrName, options = {}) {
@@ -1380,6 +1481,7 @@ export class Actor {
      * @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 async openRequestQueue(queueIdOrName, options = {}) {
@@ -1419,6 +1521,9 @@ export class Actor {
      * ```
      * { 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 async createProxyConfiguration(proxyConfigurationOptions = {}) {
         return Actor.getDefaultInstance().createProxyConfiguration(proxyConfigurationOptions);
@@ -1429,6 +1534,14 @@ export class Actor {
      * 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 async charge(options) {
@@ -1444,7 +1557,7 @@ export class Actor {
      * 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() {
@@ -1479,9 +1592,52 @@ export class Actor {
         this._instance ??= new Actor();
         return this._instance;
     }
-    async _openStorage(storageClass, id, options = {}) {
-        const client = options.forceCloud ? this.apifyClient : undefined;
-        return StorageManager.openStorage(storageClass, id, client, this.config);
+    usesPushDataInterception(dataset) {
+        return Boolean(dataset.client[USES_PUSH_DATA_INTERCEPTION]);
+    }
+    async pushDataViaInterceptedClient(dataset, item, eventName) {
+        // PatchedDatasetClient will handle charging and item limiting.
+        // We only need to propagate `eventName` and (optionally) return aggregated charge info.
+        const context = {
+            eventName,
+        };
+        await pushDataChargingContext.run(context, async () => {
+            await dataset.pushData(item);
+        });
+        return (context.chargeResult ?? {
+            eventChargeLimitReached: false,
+            chargedCount: 0,
+            chargeableWithinLimit: {},
+        });
+    }
+    async pushDataWithExplicitCharging(dataset, items, explicitEventName) {
+        // `Actor.pushData()` historically worked even without calling `Actor.init()`.
+        // In that case, charging isn't configured, so just push the data through.
+        if (!this.initialized && explicitEventName === undefined) {
+            await dataset.pushData(items);
+            return {
+                eventChargeLimitReached: false,
+                chargedCount: 0,
+                chargeableWithinLimit: {},
+            };
+        }
+        const isDefaultDataset = dataset.id === this.config.defaultDatasetId;
+        return pushDataAndCharge({
+            chargingManager: this.chargingManager,
+            items,
+            eventName: explicitEventName,
+            isDefaultDataset,
+            pushFn: async (limitedItems) => dataset.pushData(limitedItems),
+        });
+    }
+    async _openStorage(storageClass, identifier, options = {}) {
+        return openStorage(storageClass, identifier, {
+            config: this.config,
+            client: options.forceCloud
+                ? new ApifyStorageClient(this.apifyClient, this.config, () => this.chargingManager)
+                : undefined,
+            purgedStorageAliases: this.purgedStorageAliases,
+        });
     }
     _ensureActorInit(methodCalled) {
         // If we already warned the user once, don't do it again to prevent spam
@@ -1497,5 +1653,36 @@ export class Actor {
             'Did you forget to call Actor.init()?',
         ].join('\n'));
     }
+    /**
+     * 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.
+     */
+    getRemainingTime() {
+        const env = this.getEnv();
+        if (this.isAtHome() && env.timeoutAt !== null) {
+            return env.timeoutAt.getTime() - Date.now();
+        }
+        log.warning('Using `inherit` argument is only possible when the Actor is running on the Apify platform and when the ' +
+            'timeout for the Actor run is set.');
+        return undefined;
+    }
+    async inferDefaultsFromInputSchema(input) {
+        // TODO: https://github.com/apify/apify-shared-js/issues/547
+        // On platform, this is already handled
+        if (this.isAtHome()) {
+            return input;
+        }
+        // On local, we can get the input schema from the local config
+        const inputSchema = readInputSchema();
+        // Don't emit warning if there is no input schema defined
+        if (inputSchema === noActorInputSchemaDefinedMarker) {
+            return input;
+        }
+        if (!inputSchema) {
+            log.warning('Failed to find the input schema for the local run of this Actor. Your input will be missing fields that have default values set if they are missing from the input you are using.');
+            return input;
+        }
+        const defaults = getDefaultsFromInputSchema(inputSchema);
+        return { ...defaults, ...input };
+    }
 }
-//# sourceMappingURL=actor.js.map