scrapely 1.2.3 → 1.2.5

package/dist/actor.js

@@ -0,0 +1,1441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Actor = exports.EXIT_CODES = exports.ACTOR_PERMISSION_LEVEL = void 0;
+require("./log-env.js");
+const node_events_1 = require("node:events");
+/** Actor permission level - matches Apify's ACTOR_PERMISSION_LEVEL enum */
+var ACTOR_PERMISSION_LEVEL;
+(function (ACTOR_PERMISSION_LEVEL) {
+    /** User has no special permissions */
+    ACTOR_PERMISSION_LEVEL["NONE"] = "NONE";
+    /** User can run the actor */
+    ACTOR_PERMISSION_LEVEL["RUN"] = "RUN";
+    /** User can modify the actor */
+    ACTOR_PERMISSION_LEVEL["WRITE"] = "WRITE";
+    /** User has full administrative access */
+    ACTOR_PERMISSION_LEVEL["ADMIN"] = "ADMIN";
+})(ACTOR_PERMISSION_LEVEL || (exports.ACTOR_PERMISSION_LEVEL = ACTOR_PERMISSION_LEVEL = {}));
+const core_1 = require("@crawlee/core");
+const configuration_js_1 = require("./configuration.js");
+const patch_storage_js_1 = require("./storage/patch-storage.js");
+const api_storage_client_js_1 = require("./storage/api-storage-client.js");
+const events_client_js_1 = require("./events/events-client.js");
+const scrapely_event_manager_js_1 = require("./events/scrapely-event-manager.js");
+const secrets_js_1 = require("./crypto/secrets.js");
+const charging_js_1 = require("./charging.js");
+const charging_client_js_1 = require("./charging_client.js");
+const proxy_configuration_js_1 = require("./proxy-configuration.js");
+const browser_configuration_js_1 = require("./browser-configuration.js");
+const utils_js_1 = require("./utils.js");
+/** Pre-init fallback; after init, {@link Actor.events} returns the EventManager emitter. */
+const fallbackEvents = new node_events_1.EventEmitter();
+let apifyClientInstance;
+let currentUserPlan = 'free';
+let currentRunId;
+let currentUserId;
+let cachedInput = undefined;
+const gracefulShutdownHandlers = {};
+/**
+ * Registered SIGINT/SIGTERM flush handlers. Tracked (module-level, like
+ * {@link gracefulShutdownHandlers}) so `_shutdownActor` and the failed-init
+ * rollback can remove them — otherwise an init retry would stack duplicates.
+ */
+const signalExitHandlers = {};
+/**
+ * Exit codes for the Actor process (Apify-compatible).
+ * Must be in the range 1-128 to avoid collision with signal exits.
+ */
+exports.EXIT_CODES = {
+    SUCCESS: 0,
+    ERROR_USER_FUNCTION_THREW: 91,
+    ERROR_UNKNOWN: 92,
+};
+function resolveCallTimeout(timeout) {
+    if (timeout === 'inherit') {
+        const remainingMs = Actor.getRemainingTime();
+        if (remainingMs == null) {
+            console.warn('[Scrapely] Using `inherit` for timeout is only possible when running on the platform and when ' +
+                'the timeout for the Actor run is set (ACTOR_TIMEOUT_AT).');
+            return undefined;
+        }
+        return Math.max(0, Math.ceil(remainingMs / 1000));
+    }
+    return timeout;
+}
+function isApiStorageConfig(storage) {
+    return (typeof storage === 'object' &&
+        storage !== null &&
+        'apiUrl' in storage &&
+        'token' in storage &&
+        'runId' in storage);
+}
+function isStorageClient(storage) {
+    return typeof storage === 'object' && storage !== null && 'datasets' in storage;
+}
+function applyConfigurationOptions(configuration, options) {
+    if (!options)
+        return;
+    for (const key of Object.keys(options)) {
+        const value = options[key];
+        if (value !== undefined) {
+            configuration.set(key, value);
+        }
+    }
+}
+class Actor {
+    /** Configuration for this Actor instance (pass to crawlers as second argument). */
+    config;
+    /** Whether this Actor instance was initialized. Set by {@link Actor.init}. */
+    initialized = false;
+    /**
+     * Tracks that init() has started installing process-global lifecycle state
+     * (storage factory with run credentials, events WebSocket, event manager,
+     * graceful-shutdown/signal handlers, charging). Deliberately separate from
+     * the public {@link initialized} flag: `_shutdownActor` must tear down
+     * partial state from a FAILED init (so it stays retryable), while
+     * `initialized` — used by `_ensureActorInit` — flips only after init fully
+     * succeeds.
+     */
+    _lifecycleStarted = false;
+    _apifyClient;
+    chargingManager;
+    /**
+     * Creates an Actor instance (Apify SDK-compatible alternative to static helpers).
+     */
+    constructor(options = {}) {
+        this.config =
+            Object.keys(options).length === 0 ? configuration_js_1.Configuration.getGlobalConfig() : new configuration_js_1.Configuration(options);
+        this._apifyClient = this.newClient();
+        this.chargingManager = new charging_js_1.ChargingManager(this.config, this._apifyClient);
+        Actor._instance ??= this;
+    }
+    /** Default ApifyClient instance for this Actor (Apify-compatible instance accessor). */
+    get apifyClient() {
+        return this._apifyClient;
+    }
+    _ensureInit(methodName) {
+        if (!this.initialized) {
+            throw new Error(`Actor.${methodName}() requires Actor.init() to be called first. ` +
+                `Hint: Use Actor.main() which calls init() for you.`);
+        }
+    }
+    static _actorConfig() {
+        return Actor.getDefaultInstance().config;
+    }
+    /**
+     * Event emitter for Actor events (same instance as the platform EventManager).
+     * Supports events: 'persistState', 'migrating', 'aborting', 'cpuInfo'.
+     *
+     * Usage:
+     * ```typescript
+     * Actor.events.on('persistState', () => {
+     *     // Save state before migration
+     * });
+     * ```
+     */
+    static get events() {
+        const actor = Actor._instance;
+        if (actor?.initialized) {
+            return actor.config.getEventManager().events;
+        }
+        return fallbackEvents;
+    }
+    /**
+     * Throws an error if the Actor was not initialized.
+     * Used internally to ensure methods are called after init().
+     */
+    static _ensureActorInit(methodName) {
+        if (!Actor.getDefaultInstance().initialized) {
+            throw new Error(`Actor.${methodName}() requires Actor.init() to be called first. ` +
+                `Hint: Use Actor.main() which calls init() for you.`);
+        }
+    }
+    /**
+     * Returns the remaining time in milliseconds until the Actor run times out.
+     * Uses the ACTOR_TIMEOUT_AT environment variable set by the platform.
+     *
+     * @returns Milliseconds remaining, or undefined if no timeout is set (not running on platform)
+     */
+    static getRemainingTime() {
+        const timeoutAt = process.env.ACTOR_TIMEOUT_AT;
+        if (!timeoutAt)
+            return undefined;
+        const timeoutDate = new Date(timeoutAt);
+        const remaining = timeoutDate.getTime() - Date.now();
+        return Math.max(0, remaining);
+    }
+    /**
+     * Initializes this Actor instance.
+     *
+     * @param options - Initialization options
+     */
+    async init(options = {}) {
+        if (this.initialized)
+            return;
+        // NOTE: `initialized` is set at the END of init — a failed platform init
+        // must stay retryable instead of leaving a half-initialized Actor.
+        Actor.installFatalChargeHandlers();
+        const config = this.config;
+        core_1.Configuration.globalConfig = configuration_js_1.Configuration.getGlobalConfig();
+        applyConfigurationOptions(config, options.configuration);
+        if (config.get('isAtHome')) {
+            config.set('purgeOnStart', false);
+        }
+        // NOTE: CDP URL is set lazily in patch-browser-pool.ts (remote browser via CDP_URL).
+        // From here on, init() mutates process-global lifecycle state (storage
+        // factory with run credentials, events WebSocket, event manager,
+        // graceful-shutdown handlers, charging). `_lifecycleStarted` marks that
+        // this state exists even before init finishes, so `_shutdownActor` can
+        // tear it down if init fails — the public `initialized` flag must NOT
+        // be used for that (it stays false until the whole init succeeds).
+        this._lifecycleStarted = true;
+        let eventManager;
+        const prevApifyClientInstance = apifyClientInstance;
+        let apifyClientAssigned = false;
+        try {
+            if (options.storage) {
+                if (isApiStorageConfig(options.storage)) {
+                    console.log(`[Scrapely] Initializing API storage for run ${options.storage.runId}`);
+                    (0, patch_storage_js_1.setApiStorage)(options.storage, config);
+                }
+                else if (isStorageClient(options.storage)) {
+                    config.useStorageClient(options.storage);
+                }
+                else {
+                    throw new Error('Actor.init() storage option must be ApiStorageConfig or StorageClient');
+                }
+            }
+            else {
+                const apiUrl = config.get('apiBaseUrl');
+                const token = config.get('token');
+                const runId = config.get('actorRunId');
+                if (!apiUrl || !token || !runId) {
+                    if (config.get('isAtHome')) {
+                        throw new Error('Missing required configuration for secure storage. ' +
+                            'Required: apiBaseUrl (SCRAPELY_API_URL), token (SCRAPELY_TOKEN/APIFY_TOKEN), actorRunId (ACTOR_RUN_ID). ' +
+                            'Containers must be started by the scrapely-server, or pass storage in Actor.init().');
+                    }
+                    // Local development without platform credentials: keep Crawlee's
+                    // default storage client (memory, or `./storage` filesystem), the
+                    // same fallback the Python SDK uses (`Smart → FS`). Storage, input
+                    // (KeyValueStore INPUT key), charging, and platform events all
+                    // degrade to local behavior — no remote run exists to talk to.
+                    console.log('[Scrapely] Local run detected — using Crawlee local storage');
+                }
+                else {
+                    console.log(`[Scrapely] Initializing API storage for run ${runId}`);
+                    (0, patch_storage_js_1.setApiStorage)({ apiUrl, token, runId }, config);
+                }
+            }
+            const runToken = (options.storage && isApiStorageConfig(options.storage)
+                ? options.storage.token
+                : undefined) ?? config.get('token');
+            const runId = (options.storage && isApiStorageConfig(options.storage)
+                ? options.storage.runId
+                : undefined) ?? config.get('actorRunId');
+            const eventsWsUrl = config.get('actorEventsWsUrl');
+            if (eventsWsUrl && runToken && runId) {
+                (0, events_client_js_1.connectEvents)(eventsWsUrl, runToken, runId);
+            }
+            configuration_js_1.Configuration.storage.enterWith(config);
+            eventManager = new scrapely_event_manager_js_1.ScrapelyEventManager(config);
+            config.useEventManager(eventManager);
+            await eventManager.init();
+            // 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)
+            if (options.gracefulShutdown !== false) {
+                const delay = options.gracefulShutdownDelayMillis ?? 0;
+                gracefulShutdownHandlers.aborting = () => {
+                    setTimeout(() => {
+                        Actor.exit().catch((err) => {
+                            console.error(`[Scrapely] Failed to exit gracefully: ${err.message}`);
+                        });
+                    }, delay);
+                };
+                this.on('aborting', gracefulShutdownHandlers.aborting);
+                gracefulShutdownHandlers.migrating = () => {
+                    setTimeout(() => {
+                        Actor.reboot().catch((err) => {
+                            console.error(`[Scrapely] Failed to reboot on migration: ${err.message}`);
+                        });
+                    }, delay);
+                };
+                this.on('migrating', gracefulShutdownHandlers.migrating);
+            }
+            apifyClientInstance = this._apifyClient;
+            apifyClientAssigned = true;
+            await this.chargingManager.init();
+            // Flush pending PPE intents before hard exit so uncertain charges can still settle.
+            const gracefulSignalExit = (signal) => {
+                const doExit = () => {
+                    process.exit(0);
+                };
+                // Bound flush so a hung network cannot block container stop forever.
+                const flushTimeout = setTimeout(doExit, 5_000);
+                Actor._shutdownActor(5)
+                    .catch((err) => {
+                    console.warn(`[Scrapely] Shutdown flush on ${signal} failed: ${err.message}`);
+                })
+                    .finally(() => {
+                    clearTimeout(flushTimeout);
+                    doExit();
+                });
+            };
+            signalExitHandlers.sigint = () => gracefulSignalExit('SIGINT');
+            signalExitHandlers.sigterm = () => gracefulSignalExit('SIGTERM');
+            process.on('SIGINT', signalExitHandlers.sigint);
+            process.on('SIGTERM', signalExitHandlers.sigterm);
+            this.initialized = true;
+        }
+        catch (err) {
+            // Rollback of partial init. Without this, a failed init would leave
+            // the events WebSocket open (auto-reconnecting with the failed run's
+            // token), the API storage factory holding stale run credentials and
+            // caches, an open event manager, and registered handlers — so an
+            // init retry would overlay another run's credentials and handlers
+            // on this same process. NOTE: charging state is intentionally NOT
+            // closed here — `charge()` requires a completed init, so a partial
+            // init cannot have admitted charges, and closing the manager would
+            // also reject charges made after a successful retry.
+            try {
+                if (signalExitHandlers.sigint) {
+                    process.removeListener('SIGINT', signalExitHandlers.sigint);
+                    signalExitHandlers.sigint = undefined;
+                }
+                if (signalExitHandlers.sigterm) {
+                    process.removeListener('SIGTERM', signalExitHandlers.sigterm);
+                    signalExitHandlers.sigterm = undefined;
+                }
+                if (gracefulShutdownHandlers.aborting) {
+                    this.off('aborting', gracefulShutdownHandlers.aborting);
+                    gracefulShutdownHandlers.aborting = undefined;
+                }
+                if (gracefulShutdownHandlers.migrating) {
+                    this.off('migrating', gracefulShutdownHandlers.migrating);
+                    gracefulShutdownHandlers.migrating = undefined;
+                }
+                if (eventManager) {
+                    await eventManager.close().catch(() => undefined);
+                }
+                (0, events_client_js_1.disconnectEvents)();
+                (0, patch_storage_js_1.disconnectStorage)();
+                if (apifyClientAssigned) {
+                    apifyClientInstance = prevApifyClientInstance;
+                }
+            }
+            finally {
+                this._lifecycleStarted = false;
+            }
+            throw err;
+        }
+    }
+    static async init(options = {}) {
+        return Actor.getDefaultInstance().init(options);
+    }
+    /**
+     * Runs the main user function that performs the job of the Actor
+     * and terminates the process when the user function finishes.
+     *
+     * @param userFunc - User function to be executed
+     * @param options - Main options (exit, init, gracefulShutdown, etc.)
+     */
+    static async main(userFunc, options) {
+        if (!userFunc || typeof userFunc !== 'function') {
+            throw new Error(`First parameter for Actor.main() must be a function (was '${userFunc === null ? 'null' : typeof userFunc}').`);
+        }
+        await Actor.init(options);
+        try {
+            const result = await userFunc();
+            await Actor._shutdownActor(options?.timeoutSecs ?? 30);
+            await new Promise((resolve) => process.stdout.write('', () => resolve()));
+            process.exit(options?.exitCode ?? 0);
+            return result;
+        }
+        catch (err) {
+            const cause = err.cause;
+            const causeStr = cause ? ` (cause: ${cause.message ?? String(cause)})` : '';
+            console.error(`[Scrapely] Actor failed: ${err.message}${causeStr}`);
+            // Still flush pending charges on failure paths before hard exit.
+            try {
+                await Actor._shutdownActor(options?.timeoutSecs ?? 30);
+            }
+            catch (shutdownErr) {
+                console.warn(`[Scrapely] Shutdown after failure failed: ${shutdownErr.message}`);
+            }
+            await new Promise((resolve) => process.stderr.write('', () => resolve()));
+            process.exit(options?.exitCode ?? 1);
+            throw err;
+        }
+    }
+    /**
+     * Gracefully exits the Actor run.
+     *
+     * @param options - Exit options
+     */
+    static async exit(messageOrOptions, options = {}) {
+        const opts = typeof messageOrOptions === 'string'
+            ? { ...options, statusMessage: messageOrOptions }
+            : { ...messageOrOptions, ...options };
+        const code = opts.exitCode ?? 0;
+        const timeoutSecs = opts.timeoutSecs ?? 30;
+        const shouldExit = opts.exit ?? true;
+        if (opts.statusMessage)
+            console.log(`[Scrapely] ${opts.statusMessage}`);
+        Actor._ensureActorInit('exit');
+        await Actor._shutdownActor(timeoutSecs);
+        if (shouldExit) {
+            await new Promise((resolve) => process.stdout.write('', () => resolve()));
+            process.exit(code);
+        }
+    }
+    static async fail(messageOrOptions, options = {}) {
+        const opts = typeof messageOrOptions === 'string'
+            ? { exitCode: 1, statusMessage: messageOrOptions, ...options }
+            : { exitCode: 1, ...messageOrOptions, ...options };
+        console.error(`[Scrapely] Actor failed: ${opts.statusMessage ?? 'Unknown error'}`);
+        await new Promise((resolve) => process.stderr.write('', () => resolve()));
+        await Actor.exit(opts);
+    }
+    static async getInput() {
+        Actor._ensureActorInit('getInput');
+        // Check for metamorph input first (Apify-compatible)
+        // When an actor is metamorphed, the input is stored under INPUT-METAMORPH-{n}
+        const metamorphCount = process.env.ACTOR_METAMORPH_COUNT;
+        if (metamorphCount) {
+            const count = parseInt(metamorphCount, 10);
+            if (count > 0) {
+                const { KeyValueStore } = await import('crawlee');
+                const store = await KeyValueStore.open();
+                const metamorphKey = `INPUT-METAMORPH-${count}`;
+                const metamorphInput = await store.getValue(metamorphKey);
+                if (metamorphInput !== null && metamorphInput !== undefined) {
+                    return metamorphInput;
+                }
+                // Fall through to regular INPUT if metamorph key not found
+            }
+        }
+        let input = null;
+        const raw = process.env.ACTOR_INPUT;
+        if (raw) {
+            // Try base64 decode first (server passes input as base64)
+            try {
+                const decoded = Buffer.from(raw, 'base64').toString('utf-8');
+                input = JSON.parse(decoded);
+            }
+            catch {
+                // If base64 decode fails, try direct JSON parse
+                input = JSON.parse(raw);
+            }
+        }
+        else {
+            const { KeyValueStore } = await import('crawlee');
+            const store = await KeyValueStore.open();
+            const inputKey = Actor._actorConfig().get('inputKey', 'INPUT');
+            input = await store.getValue(inputKey);
+        }
+        // Decrypt secret inputs after loading (must happen here, not in init(),
+        // because the input needs to be available first)
+        if (input && typeof input === 'object' && !Array.isArray(input)) {
+            return (0, secrets_js_1.decryptSecretInputs)(input);
+        }
+        return input;
+    }
+    static async getInputOrThrow() {
+        const input = await Actor.getInput();
+        if (input == null) {
+            throw new Error('Input does not exist');
+        }
+        return input;
+    }
+    /**
+     * Synchronously get the actor input (cached from first access).
+     * This matches Apify's Actor.input behavior.
+     */
+    static get input() {
+        if (cachedInput !== undefined)
+            return cachedInput ?? undefined;
+        const raw = process.env.ACTOR_INPUT;
+        if (!raw) {
+            cachedInput = null;
+            return undefined;
+        }
+        try {
+            // Try base64 decode first (server passes input as base64)
+            const decoded = Buffer.from(raw, 'base64').toString('utf-8');
+            cachedInput = JSON.parse(decoded);
+        }
+        catch {
+            try {
+                // Fallback to direct JSON parse
+                cachedInput = JSON.parse(raw);
+            }
+            catch {
+                cachedInput = null;
+                return undefined;
+            }
+        }
+        // Decrypt secret inputs after loading
+        if (cachedInput && typeof cachedInput === 'object' && !Array.isArray(cachedInput)) {
+            cachedInput = (0, secrets_js_1.decryptSecretInputs)(cachedInput);
+        }
+        return cachedInput ?? undefined;
+    }
+    static async pushData(item, eventName) {
+        return Actor.getDefaultInstance().pushData(item, eventName);
+    }
+    async pushData(item, eventName) {
+        Actor._ensureActorInit('pushData');
+        // Exact synthetic names only — prefix would block real priced events like apify-foo.
+        if (eventName === 'apify-default-dataset-item' ||
+            eventName === 'scrapely-default-dataset-item') {
+            throw new Error(`Cannot charge for synthetic event '${eventName}' manually`);
+        }
+        const { Dataset } = await import('crawlee');
+        const dataset = await Dataset.open();
+        if (eventName === undefined && !this.usesPushDataInterception(dataset)) {
+            await dataset.pushData(item);
+            return;
+        }
+        if (this.usesPushDataInterception(dataset)) {
+            return this.pushDataViaInterceptedClient(dataset, item, eventName);
+        }
+        return this.pushDataWithExplicitCharging(dataset, item, eventName);
+    }
+    usesPushDataInterception(dataset) {
+        return Boolean(dataset.client[charging_client_js_1.USES_PUSH_DATA_INTERCEPTION]);
+    }
+    async pushDataViaInterceptedClient(dataset, item, eventName) {
+        const context = { eventName };
+        await charging_client_js_1.pushDataChargingContext.run(context, async () => {
+            await dataset.pushData(item);
+        });
+        return (context.chargeResult ?? {
+            eventChargeLimitReached: false,
+            chargedCount: 0,
+            chargeableWithinLimit: {},
+        });
+    }
+    async pushDataWithExplicitCharging(dataset, items, explicitEventName) {
+        if (!this.initialized && explicitEventName === undefined) {
+            await dataset.pushData(items);
+            return;
+        }
+        const isDefaultDataset = dataset.id === this.config.get('defaultDatasetId');
+        return (0, charging_js_1.pushDataAndCharge)({
+            chargingManager: this.chargingManager,
+            items,
+            eventName: explicitEventName,
+            isDefaultDataset,
+            pushFn: async (limitedItems) => dataset.pushData(limitedItems),
+        });
+    }
+    static async getValue(key) {
+        Actor._ensureActorInit('getValue');
+        const { KeyValueStore } = await import('crawlee');
+        const store = await KeyValueStore.open();
+        return store.getValue(key);
+    }
+    /**
+     * Stores or deletes a value in the default KeyValueStore associated with the current Actor run.
+     *
+     * This is just a convenient shortcut for KeyValueStore.setValue.
+     *
+     * **Example:**
+     * ```typescript
+     * // Store an object (serialized to JSON)
+     * await Actor.setValue('OUTPUT', { foo: 'bar' });
+     *
+     * // Delete a record
+     * await Actor.setValue('my-key', null);
+     * ```
+     *
+     * @param key - Unique record key
+     * @param value - Record data. If null, the record is deleted. If no contentType is specified,
+     * value can be any JSON-serializable object. If contentType is set, value must be String or Buffer.
+     * @param options - Record options
+     */
+    static async setValue(key, value, options) {
+        Actor._ensureActorInit('setValue');
+        const { KeyValueStore } = await import('crawlee');
+        const store = await KeyValueStore.open();
+        await store.setValue(key, value, options);
+    }
+    /**
+     * Helper to resolve storage identifier to a string ID or name.
+     * Supports: string, { id: '...' }, { name: '...' }, { alias: '...' }
+     */
+    static _resolveStorageIdentifier(identifier, storageType, actorConfig = Actor._actorConfig()) {
+        if (!identifier)
+            return identifier;
+        if (typeof identifier === 'string') {
+            return identifier;
+        }
+        if ('id' in identifier) {
+            return identifier.id;
+        }
+        if ('name' in identifier) {
+            return identifier.name;
+        }
+        if ('alias' in identifier) {
+            // Try to resolve alias from ACTOR_STORAGES_JSON
+            const raw = actorConfig.get('actorStoragesJson');
+            if (raw) {
+                try {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        const decoded = Buffer.from(raw, 'base64').toString('utf-8');
+                        parsed = JSON.parse(decoded);
+                    }
+                    const id = parsed?.[storageType]?.[identifier.alias];
+                    if (typeof id === 'string' && id)
+                        return id;
+                }
+                catch {
+                    // Fall through to return alias as name
+                }
+            }
+            // Running outside platform: fall back to alias behaving like a name
+            return identifier.alias;
+        }
+        return null;
+    }
+    static _buildStorageOpenOptions(actorConfig, options) {
+        if (!options)
+            return undefined;
+        const config = options.config ?? actorConfig;
+        const storageOptions = { config };
+        if (options.forceCloud) {
+            const factory = (0, patch_storage_js_1.getApiStorageFactory)();
+            if (factory) {
+                storageOptions.storageClient = factory;
+            }
+            else {
+                const apiUrl = config.get('apiBaseUrl');
+                const token = config.get('token');
+                const runId = config.get('actorRunId');
+                if (apiUrl && token && runId) {
+                    storageOptions.storageClient = new api_storage_client_js_1.ApiStorageClientFactory({ apiUrl, token, runId });
+                }
+                else {
+                    console.warn('[Scrapely] forceCloud was requested but no API storage credentials are '
+                        + 'available (apiBaseUrl/token/actorRunId) and no storage factory is '
+                        + 'initialized — falling back to the default (local) storage client.');
+                }
+            }
+        }
+        return storageOptions;
+    }
+    static async _openDataset(actorConfig, nameOrIdOrOptions, openOptions) {
+        const { Dataset } = await import('crawlee');
+        const resolved = Actor._resolveStorageIdentifier(nameOrIdOrOptions, 'datasets', actorConfig);
+        const storageOpts = Actor._buildStorageOpenOptions(actorConfig, openOptions);
+        return Dataset.open(resolved, storageOpts);
+    }
+    static async _openKeyValueStore(actorConfig, nameOrIdOrOptions, openOptions) {
+        const { KeyValueStore } = await import('crawlee');
+        const resolved = Actor._resolveStorageIdentifier(nameOrIdOrOptions, 'keyValueStores', actorConfig);
+        const storageOpts = Actor._buildStorageOpenOptions(actorConfig, openOptions);
+        return KeyValueStore.open(resolved, storageOpts);
+    }
+    static async _openRequestQueue(actorConfig, nameOrIdOrOptions, openOptions) {
+        const { RequestQueue } = await import('crawlee');
+        const resolved = Actor._resolveStorageIdentifier(nameOrIdOrOptions, 'requestQueues', actorConfig);
+        const storageOpts = Actor._buildStorageOpenOptions(actorConfig, openOptions);
+        return RequestQueue.open(resolved, storageOpts);
+    }
+    static async openDataset(nameOrIdOrOptions, openOptions) {
+        Actor._ensureActorInit('openDataset');
+        return Actor._openDataset(Actor._actorConfig(), nameOrIdOrOptions, openOptions);
+    }
+    static async openKeyValueStore(nameOrIdOrOptions, openOptions) {
+        Actor._ensureActorInit('openKeyValueStore');
+        return Actor._openKeyValueStore(Actor._actorConfig(), nameOrIdOrOptions, openOptions);
+    }
+    static async openRequestQueue(nameOrIdOrOptions, openOptions) {
+        Actor._ensureActorInit('openRequestQueue');
+        return Actor._openRequestQueue(Actor._actorConfig(), nameOrIdOrOptions, openOptions);
+    }
+    static isAtHome() {
+        return !!Actor._actorConfig().get('isAtHome');
+    }
+    /**
+     * Returns true when the Actor run was started in standby mode
+     * (Python SDK `Actor.is_standby` parity; detected via `metaOrigin === 'STANDBY'`).
+     */
+    static isStandby() {
+        return Actor._actorConfig().get('metaOrigin') === 'STANDBY';
+    }
+    /**
+     * Returns a new {@apilink ApifyEnv} object which contains information parsed from all the environment variables.
+     *
+     * For the list of the environment variables, see the Actor documentation.
+     * If some variables are not defined or are invalid, the corresponding value in the resulting object will be null.
+     *
+     * @returns Parsed environment variables with proper types
+     */
+    static getEnv() {
+        const env = process.env;
+        // Helper to parse dates
+        const parseDate = (value) => {
+            if (!value)
+                return null;
+            const unix = Date.parse(value);
+            return unix > 0 ? new Date(unix) : null;
+        };
+        // Helper to parse integers
+        const parseIntOrNull = (value) => {
+            if (!value)
+                return null;
+            const parsed = parseInt(value, 10);
+            return isNaN(parsed) ? null : parsed;
+        };
+        // Helper to parse floats
+        const parseFloatOrNull = (value) => {
+            if (!value)
+                return null;
+            const parsed = parseFloat(value);
+            return isNaN(parsed) ? null : parsed;
+        };
+        // Helper for disableOutdatedWarning (1 or null)
+        const parseDisableWarning = (value) => {
+            return value === '1' ? 1 : null;
+        };
+        return {
+            // Apify-compatible fields (in alphabetical order as per Apify interface)
+            actorId: env.ACTOR_ID || null,
+            actorBuildId: env.ACTOR_BUILD_ID || null,
+            actorBuildNumber: env.ACTOR_BUILD_NUMBER || null,
+            actorBuildTags: env.ACTOR_BUILD_TAGS || null,
+            actorEventsWsUrl: env.ACTOR_EVENTS_WS_URL || env.ACTOR_EVENTS_WEBSOCKET_URL || null,
+            actorFullName: env.ACTOR_FULL_NAME || null,
+            actorMaxPaidDatasetItems: parseIntOrNull(env.ACTOR_MAX_PAID_DATASET_ITEMS),
+            actorPermissionLevel: env.ACTOR_PERMISSION_LEVEL || null,
+            actorRunId: env.ACTOR_RUN_ID || null,
+            actorTaskId: env.ACTOR_TASK_ID || null,
+            apiBaseUrl: env.APIFY_API_BASE_URL || env.SCRAPELY_API_URL || null,
+            apiPublicBaseUrl: env.APIFY_API_PUBLIC_BASE_URL || null,
+            chromeExecutablePath: env.APIFY_CHROME_EXECUTABLE_PATH || null,
+            containerPort: parseIntOrNull(env.ACTOR_WEB_SERVER_PORT),
+            containerUrl: env.ACTOR_WEB_SERVER_URL || null,
+            dedicatedCpus: env.ACTOR_DEDICATED_CPUS || null,
+            defaultDatasetId: env.ACTOR_DEFAULT_DATASET_ID || null,
+            defaultKeyValueStoreId: env.ACTOR_DEFAULT_KEY_VALUE_STORE_ID || null,
+            defaultRequestQueueId: env.ACTOR_DEFAULT_REQUEST_QUEUE_ID || null,
+            disableOutdatedWarning: parseDisableWarning(env.APIFY_DISABLE_OUTDATED_WARNING),
+            fact: env.APIFY_FACT || null,
+            headless: env.APIFY_HEADLESS || null,
+            inputKey: env.ACTOR_INPUT_KEY || null,
+            inputSecretsPrivateKeyFile: env.APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE || null,
+            inputSecretsPrivateKeyPassphrase: env.APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE || null,
+            isAtHome: env.APIFY_IS_AT_HOME || env.SCRAPELY_IS_AT_HOME || null,
+            localStorageDir: env.CRAWLEE_STORAGE_DIR || env.APIFY_LOCAL_STORAGE_DIR || null,
+            logFormat: env.APIFY_LOG_FORMAT || null,
+            logLevel: env.APIFY_LOG_LEVEL || null,
+            memoryMbytes: parseIntOrNull(env.ACTOR_MEMORY_MBYTES),
+            metaOrigin: env.APIFY_META_ORIGIN || env.ACTOR_META_ORIGIN || null,
+            proxyHostname: env.APIFY_PROXY_HOSTNAME || null,
+            proxyPassword: env.APIFY_PROXY_PASSWORD || null,
+            proxyPort: env.APIFY_PROXY_PORT || null,
+            proxyStatusUrl: env.APIFY_PROXY_STATUS_URL || null,
+            sdkLatestVersion: null, // Not available from env
+            startedAt: parseDate(env.ACTOR_STARTED_AT),
+            systemInfoIntervalMillis: env.APIFY_SYSTEM_INFO_INTERVAL_MILLIS || null,
+            timeoutAt: parseDate(env.ACTOR_TIMEOUT_AT),
+            token: env.APIFY_TOKEN || env.SCRAPELY_TOKEN || null,
+            userId: env.APIFY_USER_ID || null,
+            userIsPaying: env.APIFY_USER_IS_PAYING || null,
+            workflowKey: env.ACTOR_WORKFLOW_KEY || null,
+            // Scrapely-specific extensions
+            maxTotalChargeUsd: parseFloatOrNull(env.ACTOR_MAX_TOTAL_CHARGE_USD),
+            userPlan: env.SCRAPELY_USER_PLAN || null,
+            restartOnError: env.ACTOR_RESTART_ON_ERROR || null,
+        };
+    }
+    /**
+     * Full technical name of the actor (owner-username/actor-name).
+     */
+    static get fullName() {
+        return process.env.ACTOR_FULL_NAME || undefined;
+    }
+    /**
+     * ID of the Actor task, or undefined if running outside a task.
+     */
+    static get taskId() {
+        return Actor._actorConfig().get('actorTaskId') || undefined;
+    }
+    /**
+     * ID of the Actor build used in the run.
+     */
+    static get buildId() {
+        return process.env.ACTOR_BUILD_ID || undefined;
+    }
+    /**
+     * Build number of the Actor build used in the run.
+     */
+    static get buildNumber() {
+        return process.env.ACTOR_BUILD_NUMBER || undefined;
+    }
+    /**
+     * Comma-separated list of tags of the Actor build used in the run.
+     */
+    static get buildTags() {
+        return (process.env.ACTOR_BUILD_TAGS || '')
+            .split(',')
+            .map(t => t.trim())
+            .filter(t => t.length > 0);
+    }
+    /**
+     * Date when the Actor was started (ISO 8601 UTC).
+     */
+    static get startedAt() {
+        return process.env.ACTOR_STARTED_AT || undefined;
+    }
+    /**
+     * Date when the Actor will time out (ISO 8601 UTC).
+     */
+    static get timeoutAt() {
+        return process.env.ACTOR_TIMEOUT_AT || undefined;
+    }
+    /**
+     * API token of the user who started the Actor.
+     */
+    static get token() {
+        return Actor._actorConfig().get('token') || undefined;
+    }
+    /**
+     * ID of the user who started the Actor.
+     */
+    static get userId() {
+        return Actor._actorConfig().get('userId') || undefined;
+    }
+    /**
+     * Whether the user who started the Actor is a paying user.
+     */
+    static get isPaying() {
+        return Actor._actorConfig().get('userIsPaying') === true;
+    }
+    /**
+     * Public URL of the Apify API. May be used to interact with the platform programmatically.
+     */
+    static get apiPublicBaseUrl() {
+        return Actor._actorConfig().get('apiPublicBaseUrl') || undefined;
+    }
+    /**
+     * Get a single environment variable value by name.
+     * This is an Apify SDK-compatible alias for process.env[key].
+     */
+    static getenv(key) {
+        return process.env[key];
+    }
+    on(event, listener) {
+        this.config.getEventManager().on(event, listener);
+    }
+    off(event, listener) {
+        this.config.getEventManager().off(event, listener);
+    }
+    static on(event, listener) {
+        Actor.getDefaultInstance().on(event, listener);
+    }
+    static off(event, listener) {
+        Actor.getDefaultInstance().off(event, listener);
+    }
+    /**
+     * Closes the event manager, disconnects platform events, and flushes storage.
+     * Called automatically at the end of {@link Actor.main} and {@link Actor.exit}.
+     */
+    static _fatalShutdownStarted = false;
+    /** One-shot bounded reconciliation on fatal process errors. */
+    static installFatalChargeHandlers() {
+        if (Actor._fatalHandlersInstalled)
+            return;
+        Actor._fatalHandlersInstalled = true;
+        const runOnce = (reason, err) => {
+            if (Actor._fatalShutdownStarted)
+                return;
+            Actor._fatalShutdownStarted = true;
+            if (err)
+                console.error(`[Scrapely] Fatal ${reason}:`, err);
+            else
+                console.warn(`[Scrapely] Fatal ${reason} — attempting bounded charge flush`);
+            // Independent hard-exit timer: a hung flush must not leave a
+            // corrupted process alive. unref so the timer alone keeps nothing running.
+            const hardExit = setTimeout(() => process.exit(1), 10_000);
+            hardExit.unref?.();
+            void Actor._shutdownActor(5)
+                .catch(() => undefined)
+                .finally(() => {
+                // Registering an uncaughtException listener SUPPRESSES Node's
+                // default termination — a fatal error MUST terminate the process
+                // so the platform can retry the run from a clean state.
+                process.exit(1);
+            });
+        };
+        process.once('uncaughtException', (err) => runOnce('uncaughtException', err));
+        process.once('unhandledRejection', (err) => runOnce('unhandledRejection', err));
+    }
+    static async _shutdownActor(timeoutSecs = 30) {
+        const actor = Actor.getDefaultInstance();
+        // Tear down whenever init() started installing lifecycle state — including
+        // a partially initialized Actor whose init() failed. The public
+        // `initialized` flag stays false in that case, but the events WebSocket,
+        // storage factory, event manager, and handlers exist and must not leak
+        // into a retry, so that flag must NOT be used to skip this cleanup.
+        if (!actor._lifecycleStarted) {
+            return;
+        }
+        if (gracefulShutdownHandlers.aborting) {
+            Actor.off('aborting', gracefulShutdownHandlers.aborting);
+        }
+        if (gracefulShutdownHandlers.migrating) {
+            Actor.off('migrating', gracefulShutdownHandlers.migrating);
+        }
+        if (signalExitHandlers.sigint) {
+            process.removeListener('SIGINT', signalExitHandlers.sigint);
+        }
+        if (signalExitHandlers.sigterm) {
+            process.removeListener('SIGTERM', signalExitHandlers.sigterm);
+        }
+        // Best-effort: drain unresolved PPE charge intents under a hard deadline.
+        // timeoutSecs bounds the flush so hung network cannot block exit forever.
+        const flushDeadlineMs = Math.min(Math.max(1, timeoutSecs) * 1000, 30_000);
+        // Only a fully initialized run can have admitted charges; a partial init
+        // has none, and closing the manager here would also reject charges made
+        // after a successful init retry on the same instance.
+        if (actor.initialized) {
+            try {
+                const cm = actor.chargingManager;
+                // F6: reject NEW charges before the final flush so nothing can be
+                // admitted after it while teardown is closing storages/credentials.
+                if (cm && typeof cm.close === 'function') {
+                    cm.close();
+                }
+                if (cm && typeof cm.flushPending === 'function') {
+                    await Promise.race([
+                        cm.flushPending(64, flushDeadlineMs),
+                        new Promise((resolve) => setTimeout(resolve, flushDeadlineMs)),
+                    ]);
+                }
+            }
+            catch (err) {
+                console.warn(`[Scrapely] ChargingManager.flushPending failed during shutdown: ${err.message}`);
+            }
+        }
+        const eventManager = Actor._actorConfig().getEventManager();
+        await eventManager.close();
+        (0, events_client_js_1.disconnectEvents)();
+        (0, patch_storage_js_1.disconnectStorage)();
+        // Brief grace for in-flight I/O after flush (bounded).
+        await new Promise((resolve) => {
+            setTimeout(resolve, Math.min(1000, flushDeadlineMs));
+        });
+    }
+    /**
+     * Sets the status message for the current Actor run.
+     *
+     * @param message - The status message to set
+     * @param options - Optional settings for the status message
+     * @returns The updated ActorRun object, or an empty object if running locally
+     */
+    static async setStatusMessage(message, options) {
+        const { isStatusMessageTerminal, level } = options || {};
+        Actor._ensureActorInit('setStatusMessage');
+        const loggedStatusMessage = `[Status message]: ${message}`;
+        switch (level) {
+            case 'DEBUG':
+                console.debug(loggedStatusMessage);
+                break;
+            case 'WARNING':
+                console.warn(loggedStatusMessage);
+                break;
+            case 'ERROR':
+                console.error(loggedStatusMessage);
+                break;
+            default:
+                console.log(loggedStatusMessage);
+                break;
+        }
+        const config = Actor._actorConfig();
+        const client = config.getStorageClient();
+        if (typeof client.setStatusMessage === 'function') {
+            await Promise.race([
+                client.setStatusMessage(message, { isStatusMessageTerminal, level }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Setting status message timed out after 1s')), 1000)),
+            ]).catch((err) => {
+                console.warn(`[Scrapely] ${err.message}`);
+            });
+        }
+        const apiUrl = config.get('apiBaseUrl');
+        const token = config.get('token');
+        const runId = config.get('actorRunId');
+        if (!apiUrl || !token || !runId) {
+            return {};
+        }
+        const response = await fetch(`${apiUrl}/v2/actor-runs/${runId}`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({
+                statusMessage: message,
+                isStatusMessageTerminal,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to update status message: ${response.status} ${error}`);
+        }
+        const body = (await response.json());
+        return (body.data ?? {});
+    }
+    /**
+     * Creates a proxy configuration and returns a promise resolving to an instance
+     * of the ProxyConfiguration class that is already initialized.
+     *
+     * Configures connection to a proxy server with the provided options. Proxy servers
+     * are used to prevent target websites from blocking your crawlers based on IP address
+     * rate limits or blacklists. Setting proxy configuration in your crawlers automatically
+     * configures them to use the selected proxies for all connections.
+     *
+     * **Example usage:**
+     * ```javascript
+     * const proxyConfiguration = await Actor.createProxyConfiguration({
+     *     proxyUrls: ['http://user:pass@proxy1.example.com:8080'],
+     * });
+     *
+     * const crawler = new CheerioCrawler({
+     *     proxyConfiguration,
+     *     requestHandler({ proxyInfo }) {
+     *         const usedProxyUrl = proxyInfo.url; // Getting the proxy URL
+     *     },
+     * });
+     * ```
+     *
+     * For compatibility with existing Actor Input UI (Input Schema), this function returns
+     * `undefined` when `{ useApifyProxy: false }` is passed.
+     *
+     * @param options - Proxy configuration options
+     * @returns Promise resolving to ProxyConfiguration instance, or undefined
+     */
+    static async createProxyConfiguration(options = {}) {
+        return (0, proxy_configuration_js_1.createProxyConfiguration)(options);
+    }
+    /**
+     * Creates a Scrapely remote browser configuration (location and
+     * fingerprint options). Pass it to browser crawlers next to
+     * `proxyConfiguration`:
+     *
+     * ```javascript
+     * const browserConfiguration = await Actor.createBrowserConfiguration({ countryCode: 'US', os: 'windows' });
+     * const crawler = new PlaywrightCrawler({ browserConfiguration, requestHandler });
+     * ```
+     *
+     * Ignored outside the Scrapely remote browser (local runs), so the same
+     * code runs locally and on the platform.
+     */
+    static async createBrowserConfiguration(options = {}) {
+        return (0, browser_configuration_js_1.createBrowserConfiguration)(options);
+    }
+    /** @internal */
+    static _instance;
+    /**
+     * Get the default Actor instance (singleton pattern for Apify SDK compatibility).
+     * @returns The default Actor instance
+     */
+    static getDefaultInstance() {
+        Actor._instance ??= new Actor();
+        return Actor._instance;
+    }
+    /**
+     * Default Configuration instance (Apify-compatible static accessor).
+     * Used after Actor.init() without new Actor(), e.g. Actor.config.get('standbyPort').
+     */
+    static get config() {
+        return Actor.getDefaultInstance().config;
+    }
+    /**
+     * Default API client instance for the Scrapely platform.
+     */
+    static get apifyClient() {
+        return Actor.getDefaultInstance().apifyClient;
+    }
+    /**
+     * Returns a new Apify API client pointed at the Scrapely platform.
+     */
+    newClient(options) {
+        const config = this.config;
+        const clientOptions = {
+            token: options?.token ?? config.get('token') ?? '',
+            // Fall back to the client's own default when the configuration has no value,
+            // instead of forcing an empty string (which would produce a relative `/v2` base URL).
+            baseUrl: options?.baseUrl ?? config.get('apiBaseUrl'),
+            // Public URLs (getRecordPublicUrl, createItemsPublicUrl) must not be minted
+            // against a different host than the API the client talks to. Follow an explicit
+            // per-call base URL override, then the configured public base URL.
+            publicBaseUrl: options?.baseUrl ?? config.get('apiPublicBaseUrl'),
+        };
+        if (options?.token || options?.baseUrl) {
+            return (0, charging_client_js_1.createChargingClient)(clientOptions, this);
+        }
+        if (apifyClientInstance) {
+            return apifyClientInstance;
+        }
+        apifyClientInstance = (0, charging_client_js_1.createChargingClient)(clientOptions, this);
+        return apifyClientInstance;
+    }
+    static newClient(options) {
+        return Actor.getDefaultInstance().newClient(options);
+    }
+    /** Apify-compatible instance API — delegates to {@link Actor.charge}. */
+    async charge(options, count) {
+        return Actor.charge(options, count);
+    }
+    /**
+     * Charge for a custom pricing event (pay-per-event Actors).
+     */
+    static async charge(options, count) {
+        Actor._ensureActorInit('charge');
+        const chargeOptions = typeof options === 'string' ? { eventName: options, count: count ?? 1 } : options;
+        return Actor.getDefaultInstance().chargingManager.charge(chargeOptions);
+    }
+    static getChargingManager() {
+        return Actor.getDefaultInstance().chargingManager;
+    }
+    getChargingManager() {
+        return this.chargingManager;
+    }
+    /**
+     * Metamorph the current actor run into a run of another actor.
+     * This follows Apify's metamorph behavior:
+     * 1. Stores new input under INPUT-METAMORPH-{n} key in the default KVS
+     * 2. Signals the server to swap the container to the target actor's image
+     * 3. Exits the current process (the container will be replaced)
+     *
+     * @param targetActorId - The ID or username/actorName of the target actor
+     * @param input - Optional input for the target actor (uses current input if not provided)
+     * @param options - Optional build tag and content type for the target actor
+     */
+    static async metamorph(targetActorId, input, options) {
+        const config = Actor._actorConfig();
+        const apiUrl = config.get('apiBaseUrl');
+        const token = config.get('token');
+        const runId = config.get('actorRunId');
+        if (!apiUrl || !token || !runId) {
+            throw new Error('Metamorph requires apiBaseUrl, token, and actorRunId in configuration');
+        }
+        // Wire format (server contract, Python SDK parity): the server copies the
+        // current INPUT to INPUT-METAMORPH-<n> itself and tracks the metamorph
+        // count in run stats; the new input (if any) is read from the request
+        // body's `input` field and written to INPUT. `inputKey` is NOT part of
+        // the contract — the old client-side KVS write made the server overwrite
+        // our value with the stale INPUT, silently losing the new input.
+        const body = { targetActorId };
+        if (options?.build) {
+            body.build = options.build;
+        }
+        if (input !== undefined) {
+            body.input = input;
+        }
+        console.log(`[Scrapely] Metamorphosing to actor ${targetActorId}`);
+        // Signal the server to perform the metamorph
+        try {
+            const response = await fetch(`${apiUrl}/v2/actor-runs/${runId}/metamorph`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${token}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(`Metamorph request failed: ${response.status} ${error}`);
+            }
+            console.log('[Scrapely] Metamorph request accepted, exiting...');
+        }
+        catch (err) {
+            console.error(`[Scrapely] Metamorph failed: ${err.message}`);
+            throw err;
+        }
+        // Flush pending PPE intents before hard exit (same class of loss as SIGTERM).
+        try {
+            await Actor._shutdownActor(5);
+        }
+        catch (err) {
+            console.warn(`[Scrapely] flushPending during metamorph failed: ${err.message}`);
+        }
+        // Exit so the worker can restart the container with the target actor.
+        process.exit(0);
+    }
+    /**
+     * Persist runtime state across server migrations.
+     *
+     * Long-running Actor jobs may need to migrate between servers.
+     * Without state persistence, your job's progress is lost during
+     * migration, causing it to restart from the beginning on the new server.
+     *
+     * This method automatically saves your state to the key-value store
+     * whenever a `persistState` event occurs (every 60 seconds and on exit),
+     * and restores it when the Actor restarts after a migration.
+     *
+     * The state must be JSON-serializable (values must survive JSON.stringify/parse).
+     * For short-running Actors (less than a few minutes), state persistence is
+     * typically unnecessary.
+     *
+     * @param nameOrInitialState - Either the state key name (string) or default state object
+     * @param defaultValue - Default state used when no previously persisted state exists (when first param is string)
+     * @param options - Options for state persistence
+     * @returns The current state object (mutate it directly; it saves on persistState events)
+     */
+    static async useState(nameOrInitialState, defaultValue = {}, options) {
+        Actor._ensureActorInit('useState');
+        let stateKey;
+        let initialState;
+        if (typeof nameOrInitialState === 'string') {
+            stateKey = nameOrInitialState;
+            initialState = defaultValue;
+        }
+        else if (nameOrInitialState !== undefined) {
+            // Legacy: useState(initialState) stores under STATE
+            stateKey = 'STATE';
+            initialState = nameOrInitialState;
+        }
+        else {
+            stateKey = 'APIFY_GLOBAL_STATE';
+            initialState = defaultValue;
+        }
+        const { KeyValueStore } = await import('crawlee');
+        const kvStore = await KeyValueStore.open(options?.keyValueStoreName, {
+            config: options?.config ?? Actor._actorConfig(),
+        });
+        return kvStore.getAutoSavedValue(stateKey, initialState);
+    }
+    /**
+     * Reboot the Actor run.
+     *
+     * This method is designed to be called in the `migrating` event handler
+     * to speed up the migration process and ensure state consistency.
+     *
+     * After calling this, the Actor container will be stopped and restarted
+     * on a new server. Any state persisted via Actor.useState() will be
+     * automatically restored.
+     *
+     * This is an Apify-compatible method.
+     *
+     * @param options - Reboot options
+     */
+    static async reboot(options) {
+        console.log('[Scrapely] Rebooting...');
+        Actor._ensureActorInit('reboot');
+        // Emit persistState to ensure state is saved before reboot
+        Actor._actorConfig().getEventManager().emit('persistState', { isMigrating: true });
+        // Wait a moment for state to be persisted
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        // Call the reboot endpoint to signal the worker
+        const config = Actor._actorConfig();
+        const apiUrl = config.get('apiBaseUrl') || 'http://localhost:3000';
+        const token = config.get('token') || '';
+        const runId = config.get('actorRunId') || '';
+        try {
+            const response = await fetch(`${apiUrl}/v2/actor-runs/${runId}/reboot`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(`Reboot request failed: ${response.status} ${error}`);
+            }
+            console.log(`[Scrapely] Reboot request accepted (${response.status})`);
+            // Wait briefly for the reboot signal to be processed, then exit
+            const sleepMillis = options?.customAfterSleepMillis ?? Actor._actorConfig().get('metamorphAfterSleepMillis', 1000);
+            await new Promise((resolve) => setTimeout(resolve, sleepMillis));
+        }
+        catch (err) {
+            console.error(`[Scrapely] Failed to send reboot request: ${err.message}`);
+            throw err;
+        }
+        // Flush pending PPE intents before hard exit (same class of loss as SIGTERM/metamorph).
+        try {
+            await Actor._shutdownActor(5);
+        }
+        catch (err) {
+            console.warn(`[Scrapely] flushPending during reboot failed: ${err.message}`);
+        }
+        // Exit so the worker can restart the container (Apify-compatible).
+        process.exit(0);
+    }
+    /**
+     * Abort an Actor run on the Scrapely platform.
+     *
+     * @param runId - The ID of the run to abort. Defaults to the current run.
+     * @param options - Abort options
+     * @returns The ActorRun object with details about the aborted run
+     */
+    static async abort(runId, options = {}) {
+        const targetRunId = runId ?? Actor._actorConfig().get('actorRunId');
+        if (!targetRunId) {
+            throw new Error('Actor.abort() requires a run ID');
+        }
+        const { token, statusMessage, ...rest } = options;
+        const client = token ? Actor.newClient({ token }) : Actor.apifyClient;
+        if (statusMessage) {
+            await client.run(targetRunId).update({
+                statusMessage,
+                isStatusMessageTerminal: true,
+            });
+        }
+        return client.run(targetRunId).abort(rest);
+    }
+    static async addWebhook(options) {
+        if (!Actor.isAtHome()) {
+            console.warn('[Scrapely] Actor.addWebhook() is only supported on the platform. Ignoring.');
+            return undefined;
+        }
+        const runId = Actor._actorConfig().get('actorRunId');
+        if (!runId) {
+            throw new Error('Environment variable ACTOR_RUN_ID is not set!');
+        }
+        return Actor.apifyClient.webhooks().create({
+            ...options,
+            eventTypes: options.eventTypes,
+            isAdHoc: true,
+            condition: {
+                actorRunId: runId,
+            },
+        });
+    }
+    /**
+     * Runs an Actor on the platform and waits for it to finish (Apify-compatible instance API).
+     */
+    async call(actorId, input, options = {}) {
+        return Actor.call(actorId, input, options);
+    }
+    static async call(actorId, input, options = {}) {
+        const timeout = resolveCallTimeout(options.timeout);
+        const { token, ...rest } = options;
+        const client = token ? Actor.newClient({ token }) : Actor.apifyClient;
+        return client.actor(actorId).call(input, { ...rest, timeout });
+    }
+    /**
+     * Runs an Actor task on the platform and waits for it to finish (Apify-compatible instance API).
+     */
+    async callTask(taskId, input, options = {}) {
+        return Actor.callTask(taskId, input, options);
+    }
+    static async callTask(taskId, input, options = {}) {
+        const timeout = resolveCallTimeout(options.timeout);
+        const { token, ...rest } = options;
+        const client = token ? Actor.newClient({ token }) : Actor.apifyClient;
+        return client.task(taskId).call(input, { ...rest, timeout });
+    }
+    static async start(actorId, input, options = {}) {
+        const timeout = resolveCallTimeout(options.timeout);
+        const { token, ...rest } = options;
+        const client = token ? Actor.newClient({ token }) : Actor.apifyClient;
+        return client.actor(actorId).start(input, { ...rest, timeout });
+    }
+    // -------------------------------------------------------------------------
+    // Apify-compatible instance API (mirrors static methods on Actor class)
+    // -------------------------------------------------------------------------
+    async main(userFunc, options) {
+        return Actor.main(userFunc, options);
+    }
+    async exit(messageOrOptions, options = {}) {
+        return Actor.exit(messageOrOptions, options);
+    }
+    async fail(messageOrOptions, options = {}) {
+        return Actor.fail(messageOrOptions, options);
+    }
+    async getInput() {
+        this._ensureInit('getInput');
+        return Actor.getInput();
+    }
+    async getInputOrThrow() {
+        this._ensureInit('getInputOrThrow');
+        return Actor.getInputOrThrow();
+    }
+    async getValue(key) {
+        this._ensureInit('getValue');
+        return Actor.getValue(key);
+    }
+    async setValue(key, value, options) {
+        this._ensureInit('setValue');
+        return Actor.setValue(key, value, options);
+    }
+    async openDataset(nameOrIdOrOptions, openOptions) {
+        this._ensureInit('openDataset');
+        return Actor._openDataset(this.config, nameOrIdOrOptions, {
+            ...openOptions,
+            config: openOptions?.config ?? this.config,
+        });
+    }
+    async openKeyValueStore(nameOrIdOrOptions, openOptions) {
+        this._ensureInit('openKeyValueStore');
+        return Actor._openKeyValueStore(this.config, nameOrIdOrOptions, {
+            ...openOptions,
+            config: openOptions?.config ?? this.config,
+        });
+    }
+    async openRequestQueue(nameOrIdOrOptions, openOptions) {
+        this._ensureInit('openRequestQueue');
+        return Actor._openRequestQueue(this.config, nameOrIdOrOptions, {
+            ...openOptions,
+            config: openOptions?.config ?? this.config,
+        });
+    }
+    isAtHome() {
+        return !!this.config.get('isAtHome');
+    }
+    /** Instance mirror of {@link Actor.isStandby} (Python SDK `Actor.is_standby` parity). */
+    isStandby() {
+        return this.config.get('metaOrigin') === 'STANDBY';
+    }
+    getEnv() {
+        return Actor.getEnv();
+    }
+    async setStatusMessage(message, options) {
+        this._ensureInit('setStatusMessage');
+        return Actor.setStatusMessage(message, options);
+    }
+    async createProxyConfiguration(options = {}) {
+        return Actor.createProxyConfiguration(options);
+    }
+    async createBrowserConfiguration(options = {}) {
+        return Actor.createBrowserConfiguration(options);
+    }
+    async metamorph(targetActorId, input, options) {
+        return Actor.metamorph(targetActorId, input, options);
+    }
+    async reboot(options) {
+        return Actor.reboot(options);
+    }
+    async abort(runId, options = {}) {
+        return Actor.abort(runId, options);
+    }
+    async addWebhook(options) {
+        return Actor.addWebhook(options);
+    }
+    async start(actorId, input, options = {}) {
+        return Actor.start(actorId, input, options);
+    }
+    async useState(nameOrInitialState, defaultValue = {}, options) {
+        this._ensureInit('useState');
+        return Actor.useState(nameOrInitialState, defaultValue, {
+            ...options,
+            config: options?.config ?? this.config,
+        });
+    }
+    /**
+     * Apify v2-compatible utility namespace.
+     * Provides helper functions like enqueueLinks that accept the Apify v2 API signature.
+     */
+    static utils = utils_js_1.utils;
+}
+exports.Actor = Actor;