scrapely 1.2.3 → 1.2.5

package/dist/actor.d.ts

@@ -0,0 +1,703 @@
+import './log-env.js';
+import { EventEmitter } from 'node:events';
+/** Actor permission level - matches Apify's ACTOR_PERMISSION_LEVEL enum */
+export declare enum ACTOR_PERMISSION_LEVEL {
+    /** User has no special permissions */
+    NONE = "NONE",
+    /** User can run the actor */
+    RUN = "RUN",
+    /** User can modify the actor */
+    WRITE = "WRITE",
+    /** User has full administrative access */
+    ADMIN = "ADMIN"
+}
+import { ApifyClient } from 'scrapely-client';
+import type { ActorRun, Webhook } from 'scrapely-client';
+import type { ActorCallOptions, ActorStartOptions, RunAbortOptions, TaskCallOptions } from 'scrapely-client';
+import { type EventTypeName } from '@crawlee/core';
+import { Configuration, type ConfigurationOptions } from './configuration.js';
+import type { StorageClient } from '@crawlee/types';
+import { type ApiStorageConfig } from './storage/api-storage-client.js';
+import { ChargingManager, type ChargeOptions as ChargingChargeOptions, type ChargeResult as ChargingChargeResult } from './charging.js';
+import { createProxyConfiguration, type CreateProxyConfigurationOptions } from './proxy-configuration.js';
+import { type BrowserConfiguration, type BrowserConfigurationOptions } from './browser-configuration.js';
+import type { Dataset, KeyValueStore, RequestQueue } from 'crawlee';
+/** User function passed to {@link Actor.main} (Apify-compatible). */
+export type UserFunc<T = unknown> = () => T | Promise<T>;
+type Dictionary = Record<string, any>;
+/** Value types returned by {@link Actor.getInput} (Apify-compatible). */
+export type ActorInput = Dictionary | string | Buffer;
+export interface Token {
+    token?: string;
+}
+/** Apify-compatible: run timeout in seconds, or 'inherit' (the time remaining in this run). */
+export interface Timeout {
+    timeout?: TimeoutOption;
+}
+/**
+ * Exit codes for the Actor process (Apify-compatible).
+ * Must be in the range 1-128 to avoid collision with signal exits.
+ */
+export declare const EXIT_CODES: {
+    SUCCESS: number;
+    ERROR_USER_FUNCTION_THREW: number;
+    ERROR_UNKNOWN: number;
+};
+export interface CallOptions extends Omit<ActorCallOptions, 'timeout'>, Token {
+    timeout?: TimeoutOption;
+}
+export interface StartOptions extends Omit<ActorStartOptions, 'waitForFinish' | 'timeout'>, Token {
+    timeout?: TimeoutOption;
+}
+export interface CallTaskOptions extends Omit<TaskCallOptions, 'timeout'>, Token {
+    timeout?: TimeoutOption;
+}
+export interface AbortOptions extends RunAbortOptions, Token {
+    statusMessage?: string;
+}
+/** Billing context for storage operations */
+export interface BillingContext {
+    runId: string;
+    userId: string;
+}
+export type { ConfigurationOptions } from './configuration.js';
+/**
+ * Options for Actor.init()
+ */
+export interface InitOptions {
+    /** Crawlee configuration overrides (env vars still take precedence). */
+    configuration?: ConfigurationOptions;
+    /** API storage config or custom {@link StorageClient} for local/testing. */
+    storage?: ApiStorageConfig | StorageClient;
+    /**
+     * Whether to automatically handle platform shutdown signals.
+     * When enabled, `Actor.exit()` is called on `aborting` events and `Actor.reboot()` on `migrating` events.
+     * @default true
+     */
+    gracefulShutdown?: boolean;
+    /**
+     * Delay in milliseconds before calling `Actor.exit()`/`Actor.reboot()` on `aborting`/`migrating` events.
+     * @default 0
+     */
+    gracefulShutdownDelayMillis?: number;
+}
+/**
+ * Options for Actor.exit()
+ */
+export interface ExitOptions {
+    /** Exit with given status message */
+    statusMessage?: string;
+    /**
+     * Amount of time, in seconds, to wait for all event handlers to finish before exiting the process.
+     * @default 30
+     */
+    timeoutSecs?: number;
+    /** Exit code, defaults to 0 */
+    exitCode?: number;
+    /** Call `process.exit()`? Defaults to true */
+    exit?: boolean;
+}
+/**
+ * Options for Actor.setValue() / KeyValueStore.setValue()
+ */
+export interface RecordOptions {
+    /** Content type of the value. If specified, value must be a String or Buffer. */
+    contentType?: string;
+    /** If set to true, the set-record API call will not be retried if it times out. */
+    doNotRetryTimeouts?: boolean;
+    /** Specifies a custom timeout for the set-record API call, in seconds. */
+    timeoutSecs?: number;
+}
+/**
+ * Options for Actor.setStatusMessage()
+ */
+export interface SetStatusMessageOptions {
+    /** If true, the status message will be marked as terminal (final status of the run) */
+    isStatusMessageTerminal?: boolean;
+    /** Log level for the status message: 'DEBUG', 'INFO', 'WARNING', 'ERROR' */
+    level?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
+}
+/**
+ * Options for Actor.addWebhook()
+ */
+export interface WebhookOptions {
+    /** Array of event types to trigger the webhook */
+    eventTypes: string[];
+    /** URL to receive the webhook POST request */
+    requestUrl: string;
+    /** Payload template for the webhook body */
+    payloadTemplate?: string;
+    /** Idempotency key to prevent duplicate webhooks on actor restart */
+    idempotencyKey?: string;
+    /** Headers template for the webhook request */
+    headersTemplate?: string;
+    /** Description of the webhook */
+    description?: string;
+    /** If true, ignore SSL errors when sending the webhook */
+    ignoreSslErrors?: boolean;
+    /** If true, the webhook will not retry on failure */
+    doNotRetry?: boolean;
+    /** If true, the webhook will interpolate strings in the payloadTemplate and headersTemplate */
+    shouldInterpolateStrings?: boolean;
+    /** If true, indicates the webhook is an Apify integration */
+    isApifyIntegration?: boolean;
+}
+/**
+ * Options for timeout in call/start methods.
+ * Can be a number in seconds, or 'inherit' to use the remaining time of the current run.
+ */
+export type TimeoutOption = number | 'inherit';
+/**
+ * Options for Actor.main()
+ */
+export interface MainOptions extends ExitOptions, InitOptions {
+}
+/**
+ * Options for Actor.useState()
+ */
+export interface UseStateOptions {
+    /** Name of the key-value store to use for state persistence */
+    keyValueStoreName?: string;
+    /** Configuration object (for advanced use) */
+    config?: any;
+}
+/**
+ * Options for Actor.openDataset(), openKeyValueStore(), and openRequestQueue() (Apify-compatible).
+ */
+export interface OpenStorageOptions {
+    /**
+     * If set to `true`, cloud storage is used even when `CRAWLEE_STORAGE_DIR` / `APIFY_LOCAL_STORAGE_DIR` is set.
+     */
+    forceCloud?: boolean;
+    /** SDK configuration instance (advanced use). */
+    config?: Configuration;
+}
+type StorageIdentifierArg = string | null | {
+    id: string;
+} | {
+    name: string;
+} | {
+    alias: string;
+};
+/**
+ * Options for Actor.metamorph()
+ */
+export interface MetamorphOptions {
+    /** Content type for the input. If not specified, input is expected to be JSON */
+    contentType?: string;
+    /** Tag or number of the target Actor build to metamorph into */
+    build?: string;
+}
+/**
+ * Options for Actor.reboot()
+ */
+export interface RebootOptions {
+    /** @internal */
+    customAfterSleepMillis?: number;
+}
+/** Result of a charge operation (Apify-compatible). */
+export type ChargeResult = ChargingChargeResult;
+/**
+ * Parsed representation of the environment variables.
+ * This object is returned by the {@apilink Actor.getEnv} function.
+ * Fully compatible with Apify's ApifyEnv interface.
+ */
+export interface ApifyEnv {
+    /** ID of the Actor (ACTOR_ID) */
+    actorId: string | null;
+    /** ID of the Actor build used in the run (ACTOR_BUILD_ID) */
+    actorBuildId: string | null;
+    /** Build number of the Actor build (ACTOR_BUILD_NUMBER) */
+    actorBuildNumber: string | null;
+    /** Comma-separated list of build tags (ACTOR_BUILD_TAGS) */
+    actorBuildTags: string | null;
+    /** WebSocket URL for Actor events (ACTOR_EVENTS_WS_URL) */
+    actorEventsWsUrl: string | null;
+    /** Full name of the actor (owner/actor-name) (ACTOR_FULL_NAME) */
+    actorFullName: string | null;
+    /** Maximum paid dataset items (ACTOR_MAX_PAID_DATASET_ITEMS) */
+    actorMaxPaidDatasetItems: number | null;
+    /** Permission level the Actor is run under (ACTOR_PERMISSION_LEVEL) */
+    actorPermissionLevel: ACTOR_PERMISSION_LEVEL | null;
+    /** ID of the Actor run (ACTOR_RUN_ID) */
+    actorRunId: string | null;
+    /** ID of the Actor task (ACTOR_TASK_ID) */
+    actorTaskId: string | null;
+    /** Base URL for the API (APIFY_API_BASE_URL) */
+    apiBaseUrl: string | null;
+    /** Public base URL of the API (APIFY_API_PUBLIC_BASE_URL) */
+    apiPublicBaseUrl: string | null;
+    /** Chrome executable path (APIFY_CHROME_EXECUTABLE_PATH) */
+    chromeExecutablePath: string | null;
+    /** Container port (ACTOR_WEB_SERVER_PORT) */
+    containerPort: number | null;
+    /** Container URL (ACTOR_WEB_SERVER_URL) */
+    containerUrl: string | null;
+    /** Dedicated CPUs (ACTOR_DEDICATED_CPUS) */
+    dedicatedCpus: string | null;
+    /** ID of the default dataset (ACTOR_DEFAULT_DATASET_ID) */
+    defaultDatasetId: string | null;
+    /** ID of the default key-value store (ACTOR_DEFAULT_KEY_VALUE_STORE_ID) */
+    defaultKeyValueStoreId: string | null;
+    /** ID of the default request queue (ACTOR_DEFAULT_REQUEST_QUEUE_ID) */
+    defaultRequestQueueId: string | null;
+    /** Disable outdated warning (APIFY_DISABLE_OUTDATED_WARNING) */
+    disableOutdatedWarning: 1 | null;
+    /** Fact (APIFY_FACT) */
+    fact: string | null;
+    /** If "1", run in headless mode (APIFY_HEADLESS) */
+    headless: string | null;
+    /** Input key (ACTOR_INPUT_KEY) */
+    inputKey: string | null;
+    /** Input secrets private key file (APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE) */
+    inputSecretsPrivateKeyFile: string | null;
+    /** Input secrets private key passphrase (APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE) */
+    inputSecretsPrivateKeyPassphrase: string | null;
+    /** If set to "1", running on Apify servers (APIFY_IS_AT_HOME) */
+    isAtHome: string | null;
+    /** Local storage directory (CRAWLEE_STORAGE_DIR) */
+    localStorageDir: string | null;
+    /** Log format (APIFY_LOG_FORMAT) */
+    logFormat: string | null;
+    /** Log level - DEBUG, INFO, WARNING, ERROR (APIFY_LOG_LEVEL) */
+    logLevel: string | null;
+    /** Amount of memory allocated for the Actor, in megabytes (ACTOR_MEMORY_MBYTES) */
+    memoryMbytes: number | null;
+    /** Origin for the Actor run - how it was started (APIFY_META_ORIGIN) */
+    metaOrigin: string | null;
+    /** Proxy hostname (APIFY_PROXY_HOSTNAME) */
+    proxyHostname: string | null;
+    /** Proxy password (APIFY_PROXY_PASSWORD) */
+    proxyPassword: string | null;
+    /** Proxy port (APIFY_PROXY_PORT) */
+    proxyPort: string | null;
+    /** Proxy status URL (APIFY_PROXY_STATUS_URL) */
+    proxyStatusUrl: string | null;
+    /** SDK latest version */
+    sdkLatestVersion: string | null;
+    /** Date when the Actor was started (ACTOR_STARTED_AT) */
+    startedAt: Date | null;
+    /** System info interval in millis (APIFY_SYSTEM_INFO_INTERVAL_MILLIS) */
+    systemInfoIntervalMillis: string | null;
+    /** Date when the Actor will time out (ACTOR_TIMEOUT_AT) */
+    timeoutAt: Date | null;
+    /** Authentication token (APIFY_TOKEN or SCRAPELY_TOKEN) */
+    token: string | null;
+    /** ID of the user who started the Actor (APIFY_USER_ID) */
+    userId: string | null;
+    /** If "1", the user is a paying user (APIFY_USER_IS_PAYING) */
+    userIsPaying: string | null;
+    /** Workflow key (ACTOR_WORKFLOW_KEY) */
+    workflowKey: string | null;
+    /** Maximum total charge in USD (ACTOR_MAX_TOTAL_CHARGE_USD) - Scrapely extension */
+    maxTotalChargeUsd: number | null;
+    /** User's plan (SCRAPELY_USER_PLAN) - Scrapely extension */
+    userPlan: string | null;
+    /** Restart on error flag (ACTOR_RESTART_ON_ERROR) - Scrapely extension */
+    restartOnError: string | null;
+}
+export declare class Actor {
+    /** Configuration for this Actor instance (pass to crawlers as second argument). */
+    readonly config: Configuration;
+    /** Whether this Actor instance was initialized. Set by {@link Actor.init}. */
+    initialized: boolean;
+    /**
+     * 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.
+     */
+    private _lifecycleStarted;
+    private readonly _apifyClient;
+    private readonly chargingManager;
+    /**
+     * Creates an Actor instance (Apify SDK-compatible alternative to static helpers).
+     */
+    constructor(options?: ConfigurationOptions);
+    /** Default ApifyClient instance for this Actor (Apify-compatible instance accessor). */
+    get apifyClient(): ApifyClient;
+    private _ensureInit;
+    private static _actorConfig;
+    /**
+     * 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(): EventEmitter;
+    /**
+     * Throws an error if the Actor was not initialized.
+     * Used internally to ensure methods are called after init().
+     */
+    private static _ensureActorInit;
+    /**
+     * 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(): number | undefined;
+    /**
+     * Initializes this Actor instance.
+     *
+     * @param options - Initialization options
+     */
+    init(options?: InitOptions): Promise<void>;
+    static init(options?: InitOptions): Promise<void>;
+    /**
+     * 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 main<T>(userFunc: UserFunc<T>, options?: MainOptions): Promise<T>;
+    /**
+     * Gracefully exits the Actor run.
+     *
+     * @param options - Exit options
+     */
+    static exit(messageOrOptions?: string | ExitOptions, options?: ExitOptions): Promise<void>;
+    static fail(messageOrOptions?: string | ExitOptions, options?: ExitOptions): Promise<void>;
+    static getInput<T = ActorInput>(): Promise<T | null>;
+    static getInputOrThrow<T = ActorInput>(): Promise<T>;
+    /**
+     * Synchronously get the actor input (cached from first access).
+     * This matches Apify's Actor.input behavior.
+     */
+    static get input(): Record<string, any> | undefined;
+    /**
+     * Stores an object or an array of objects to the default {@apilink Dataset} of the current Actor run.
+     *
+     * This is just a convenient shortcut for {@apilink Dataset.pushData}.
+     *
+     * **IMPORTANT**: Make sure to use the `await` keyword when calling `pushData()`,
+     * otherwise the Actor process might finish before the data are stored!
+     *
+     * @param item - Object or array of objects containing data to be stored in the default dataset.
+     * The objects must be serializable to JSON and the JSON representation of each object must be smaller than 9MB.
+     * @returns Promise that resolves when the data has been stored
+     */
+    static pushData<Data extends Record<string, any>>(item: Data | Data[]): Promise<void>;
+    /**
+     * Stores an object or an array of objects to the default {@apilink Dataset} of the current Actor run.
+     *
+     * This is just a convenient shortcut for {@apilink Dataset.pushData}.
+     *
+     * **IMPORTANT**: Make sure to use the `await` keyword when calling `pushData()`,
+     * otherwise the Actor process might finish before the data are stored!
+     *
+     * @param item - Object or array of objects containing data to be stored in the default dataset.
+     * The objects must be serializable to JSON and the JSON representation of each object must be smaller than 9MB.
+     * @param eventName - Event name for pay-per-event pricing. If provided, the method will
+     * attempt to charge for each pushed item.
+     * @returns ChargeResult indicating if the user's spending limit was reached
+     */
+    static pushData<Data extends Record<string, any>>(item: Data | Data[], eventName: string): Promise<ChargeResult>;
+    pushData<Data extends Record<string, any>>(item: Data | Data[], eventName?: string): Promise<void | ChargeResult>;
+    private usesPushDataInterception;
+    private pushDataViaInterceptedClient;
+    private pushDataWithExplicitCharging;
+    static getValue<T>(key: string): Promise<T | null>;
+    /**
+     * 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 setValue<T>(key: string, value: T | null, options?: RecordOptions): Promise<void>;
+    /**
+     * Helper to resolve storage identifier to a string ID or name.
+     * Supports: string, { id: '...' }, { name: '...' }, { alias: '...' }
+     */
+    private static _resolveStorageIdentifier;
+    private static _buildStorageOpenOptions;
+    private static _openDataset;
+    private static _openKeyValueStore;
+    private static _openRequestQueue;
+    static openDataset<T extends Record<string, any>>(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<Dataset<T>>;
+    static openKeyValueStore(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<KeyValueStore>;
+    static openRequestQueue(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<RequestQueue>;
+    static isAtHome(): boolean;
+    /**
+     * Returns true when the Actor run was started in standby mode
+     * (Python SDK `Actor.is_standby` parity; detected via `metaOrigin === 'STANDBY'`).
+     */
+    static isStandby(): boolean;
+    /**
+     * 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(): ApifyEnv;
+    /**
+     * Full technical name of the actor (owner-username/actor-name).
+     */
+    static get fullName(): string | undefined;
+    /**
+     * ID of the Actor task, or undefined if running outside a task.
+     */
+    static get taskId(): string | undefined;
+    /**
+     * ID of the Actor build used in the run.
+     */
+    static get buildId(): string | undefined;
+    /**
+     * Build number of the Actor build used in the run.
+     */
+    static get buildNumber(): string | undefined;
+    /**
+     * Comma-separated list of tags of the Actor build used in the run.
+     */
+    static get buildTags(): string[];
+    /**
+     * Date when the Actor was started (ISO 8601 UTC).
+     */
+    static get startedAt(): string | undefined;
+    /**
+     * Date when the Actor will time out (ISO 8601 UTC).
+     */
+    static get timeoutAt(): string | undefined;
+    /**
+     * API token of the user who started the Actor.
+     */
+    static get token(): string | undefined;
+    /**
+     * ID of the user who started the Actor.
+     */
+    static get userId(): string | undefined;
+    /**
+     * Whether the user who started the Actor is a paying user.
+     */
+    static get isPaying(): boolean;
+    /**
+     * Public URL of the Apify API. May be used to interact with the platform programmatically.
+     */
+    static get apiPublicBaseUrl(): string | undefined;
+    /**
+     * Get a single environment variable value by name.
+     * This is an Apify SDK-compatible alias for process.env[key].
+     */
+    static getenv(key: string): string | undefined;
+    on(event: EventTypeName | 'cpuInfo', listener: (...args: any[]) => void): void;
+    off(event: EventTypeName | 'cpuInfo', listener?: (...args: any[]) => void): void;
+    static on(event: EventTypeName | 'cpuInfo', listener: (...args: any[]) => void): void;
+    static off(event: EventTypeName | 'cpuInfo', listener?: (...args: any[]) => void): void;
+    /**
+     * Closes the event manager, disconnects platform events, and flushes storage.
+     * Called automatically at the end of {@link Actor.main} and {@link Actor.exit}.
+     */
+    private static _fatalShutdownStarted;
+    /** One-shot bounded reconciliation on fatal process errors. */
+    private static installFatalChargeHandlers;
+    private static _shutdownActor;
+    /**
+     * 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 setStatusMessage(message: string, options?: SetStatusMessageOptions): Promise<ActorRun>;
+    /**
+     * 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 createProxyConfiguration(options?: CreateProxyConfigurationOptions): Promise<ReturnType<typeof createProxyConfiguration>>;
+    /**
+     * 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 createBrowserConfiguration(options?: BrowserConfigurationOptions): Promise<BrowserConfiguration>;
+    /** @internal */
+    private static _instance;
+    /**
+     * Get the default Actor instance (singleton pattern for Apify SDK compatibility).
+     * @returns The default Actor instance
+     */
+    static getDefaultInstance(): Actor;
+    /**
+     * Default Configuration instance (Apify-compatible static accessor).
+     * Used after Actor.init() without new Actor(), e.g. Actor.config.get('standbyPort').
+     */
+    static get config(): Configuration;
+    /**
+     * Default API client instance for the Scrapely platform.
+     */
+    static get apifyClient(): ApifyClient;
+    /**
+     * Returns a new Apify API client pointed at the Scrapely platform.
+     */
+    newClient(options?: {
+        token?: string;
+        baseUrl?: string;
+    }): ApifyClient;
+    static newClient(options?: {
+        token?: string;
+        baseUrl?: string;
+    }): ApifyClient;
+    /** Apify-compatible instance API — delegates to {@link Actor.charge}. */
+    charge(options: ChargingChargeOptions | string, count?: number): Promise<ChargeResult>;
+    /**
+     * Charge for a custom pricing event (pay-per-event Actors).
+     */
+    static charge(options: ChargingChargeOptions | string, count?: number): Promise<ChargeResult>;
+    static getChargingManager(): ChargingManager;
+    getChargingManager(): 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 metamorph(targetActorId: string, input?: Record<string, any> | string | Buffer, options?: MetamorphOptions): Promise<void>;
+    /**
+     * 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 useState<State extends Dictionary = Dictionary>(nameOrInitialState?: string | State, defaultValue?: State, options?: UseStateOptions): Promise<State>;
+    /**
+     * 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 reboot(options?: RebootOptions): Promise<void>;
+    /**
+     * 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 abort(runId?: string, options?: AbortOptions): Promise<ActorRun>;
+    static addWebhook(options: WebhookOptions): Promise<Webhook | undefined>;
+    /**
+     * Runs an Actor on the platform and waits for it to finish (Apify-compatible instance API).
+     */
+    call(actorId: string, input?: unknown, options?: CallOptions): Promise<ActorRun>;
+    static call(actorId: string, input?: unknown, options?: CallOptions): Promise<ActorRun>;
+    /**
+     * Runs an Actor task on the platform and waits for it to finish (Apify-compatible instance API).
+     */
+    callTask(taskId: string, input?: Dictionary, options?: CallTaskOptions): Promise<ActorRun>;
+    static callTask(taskId: string, input?: Dictionary, options?: CallTaskOptions): Promise<ActorRun>;
+    static start(actorId: string, input?: Dictionary, options?: StartOptions): Promise<ActorRun>;
+    main<T>(userFunc: UserFunc<T>, options?: MainOptions): Promise<T>;
+    exit(messageOrOptions?: string | ExitOptions, options?: ExitOptions): Promise<void>;
+    fail(messageOrOptions?: string | ExitOptions, options?: ExitOptions): Promise<void>;
+    getInput<T = ActorInput>(): Promise<T | null>;
+    getInputOrThrow<T = ActorInput>(): Promise<T>;
+    getValue<T>(key: string): Promise<T | null>;
+    setValue<T>(key: string, value: T | null, options?: RecordOptions): Promise<void>;
+    openDataset<T extends Record<string, any>>(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<Dataset<T>>;
+    openKeyValueStore(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<KeyValueStore>;
+    openRequestQueue(nameOrIdOrOptions?: string | null | StorageIdentifierArg, openOptions?: OpenStorageOptions): Promise<RequestQueue>;
+    isAtHome(): boolean;
+    /** Instance mirror of {@link Actor.isStandby} (Python SDK `Actor.is_standby` parity). */
+    isStandby(): boolean;
+    getEnv(): ApifyEnv;
+    setStatusMessage(message: string, options?: SetStatusMessageOptions): Promise<ActorRun>;
+    createProxyConfiguration(options?: CreateProxyConfigurationOptions): Promise<ReturnType<typeof createProxyConfiguration>>;
+    createBrowserConfiguration(options?: BrowserConfigurationOptions): Promise<BrowserConfiguration>;
+    metamorph(targetActorId: string, input?: Record<string, any> | string | Buffer, options?: MetamorphOptions): Promise<void>;
+    reboot(options?: RebootOptions): Promise<void>;
+    abort(runId?: string, options?: AbortOptions): Promise<ActorRun>;
+    addWebhook(options: WebhookOptions): Promise<Webhook | undefined>;
+    start(actorId: string, input?: Dictionary, options?: StartOptions): Promise<ActorRun>;
+    useState<State extends Dictionary = Dictionary>(nameOrInitialState?: string | State, defaultValue?: State, options?: UseStateOptions): Promise<State>;
+    /**
+     * Apify v2-compatible utility namespace.
+     * Provides helper functions like enqueueLinks that accept the Apify v2 API signature.
+     */
+    static readonly utils: {
+        enqueueLinks: typeof import("./utils.js").enqueueLinks;
+    };
+}