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

package/dist/configuration.d.ts

@@ -1,34 +1,62 @@
-import type { ConfigurationOptions as CoreConfigurationOptions } from '@crawlee/core';
+import type { ConfigField, FieldsInput, FieldsOutput } from '@crawlee/core';
 import { Configuration as CoreConfiguration } from '@crawlee/core';
-import type { META_ORIGINS } from '@apify/consts';
-export interface ConfigurationOptions extends CoreConfigurationOptions {
-    metamorphAfterSleepMillis?: number;
-    actorEventsWsUrl?: string;
-    token?: string;
-    actorId?: string;
-    actorRunId?: string;
-    actorTaskId?: string;
-    apiBaseUrl?: string;
-    apiPublicBaseUrl?: string;
-    containerPort?: number;
-    containerUrl?: string;
-    proxyHostname?: string;
-    proxyPassword?: string;
-    proxyPort?: number;
-    proxyStatusUrl?: string;
-    /**
-     * @deprecated use `containerPort` instead
-     */
-    standbyPort?: number;
-    standbyUrl?: string;
-    isAtHome?: boolean;
-    userId?: string;
-    inputSecretsPrivateKeyPassphrase?: string;
-    inputSecretsPrivateKeyFile?: string;
-    maxTotalChargeUsd?: number;
-    metaOrigin?: (typeof META_ORIGINS)[keyof typeof META_ORIGINS];
-    testPayPerEvent?: boolean;
-    useChargingLogDataset?: boolean;
+import { z } from 'zod';
+export declare const apifyConfigFields: {
+    defaultDatasetId: ConfigField<z.ZodDefault<z.ZodString>>;
+    defaultKeyValueStoreId: ConfigField<z.ZodDefault<z.ZodString>>;
+    defaultRequestQueueId: ConfigField<z.ZodDefault<z.ZodString>>;
+    inputKey: ConfigField<z.ZodDefault<z.ZodString>>;
+    memoryMbytes: ConfigField<z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>>;
+    availableMemoryRatio: ConfigField<any>;
+    disableBrowserSandbox: ConfigField<any>;
+    persistStateIntervalMillis: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>>;
+    headless: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+    xvfb: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+    chromeExecutablePath: ConfigField<z.ZodOptional<z.ZodString>>;
+    defaultBrowserPath: ConfigField<z.ZodOptional<z.ZodString>>;
+    purgeOnStart: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+    metamorphAfterSleepMillis: ConfigField<any>;
+    actorEventsWsUrl: ConfigField<z.ZodOptional<z.ZodString>>;
+    token: ConfigField<z.ZodOptional<z.ZodString>>;
+    actorId: ConfigField<z.ZodOptional<z.ZodString>>;
+    actorRunId: ConfigField<z.ZodOptional<z.ZodString>>;
+    actorTaskId: ConfigField<z.ZodOptional<z.ZodString>>;
+    apiBaseUrl: ConfigField<z.ZodDefault<z.ZodString>>;
+    apiPublicBaseUrl: ConfigField<z.ZodDefault<z.ZodString>>;
+    containerPort: ConfigField<any>;
+    containerUrl: ConfigField<z.ZodDefault<z.ZodString>>;
+    proxyHostname: ConfigField<z.ZodDefault<z.ZodString>>;
+    proxyPassword: ConfigField<z.ZodOptional<z.ZodString>>;
+    proxyPort: ConfigField<any>;
+    proxyStatusUrl: ConfigField<z.ZodDefault<z.ZodString>>;
+    /** @deprecated use `containerPort` instead */
+    standbyPort: ConfigField<any>;
+    standbyUrl: ConfigField<z.ZodOptional<z.ZodString>>;
+    isAtHome: ConfigField<any>;
+    userId: ConfigField<z.ZodOptional<z.ZodString>>;
+    userIsPaying: ConfigField<z.ZodOptional<z.ZodString>>;
+    actorPermissionLevel: ConfigField<z.ZodOptional<z.ZodString>>;
+    inputSecretsPrivateKeyPassphrase: ConfigField<z.ZodOptional<z.ZodString>>;
+    inputSecretsPrivateKeyFile: ConfigField<z.ZodOptional<z.ZodString>>;
+    maxTotalChargeUsd: ConfigField<any>;
+    metaOrigin: ConfigField<z.ZodOptional<z.ZodString>>;
+    testPayPerEvent: ConfigField<any>;
+    useChargingLogDataset: ConfigField<any>;
+    actorPricingInfo: ConfigField<z.ZodOptional<z.ZodString>>;
+    chargedEventCounts: ConfigField<z.ZodOptional<z.ZodString>>;
+    actorStoragesJson: ConfigField<z.ZodOptional<z.ZodString>>;
+    storageClientOptions: ConfigField<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    maxUsedCpuRatio: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>>;
+    systemInfoIntervalMillis: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>>;
+    logLevel: ConfigField<z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | null | undefined, unknown>, z.ZodEnum<typeof import("@apify/log").LogLevel>>>>;
+    persistStorage: ConfigField<z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+    containerized: ConfigField<z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+};
+export type ApifyConfigurationInput = FieldsInput<typeof apifyConfigFields>;
+export type ApifyResolvedConfigValues = FieldsOutput<typeof apifyConfigFields>;
+/** @deprecated Use {@link ApifyConfigurationInput} instead. */
+export type ConfigurationOptions = ApifyConfigurationInput;
+export interface Configuration extends ApifyResolvedConfigValues {
 }
 /**
  * `Configuration` is a value object holding the SDK configuration. We can use it in two ways:
@@ -37,38 +65,34 @@ export interface ConfigurationOptions extends CoreConfigurationOptions {
  *
  *    ```javascript
  *    import { Actor } from 'apify';
- *    import { BasicCrawler } from 'crawlee';
  *
  *    const sdk = new Actor({ token: '123' });
- *    console.log(sdk.config.get('token')); // '123'
- *
- *    const crawler = new BasicCrawler({
- *        // ... crawler options
- *    }, sdk.config);
+ *    console.log(sdk.config.token); // '123'
  *    ```
  *
  * 2. To get the global configuration (singleton instance). It will respect the environment variables.
  *
  *    ```javascript
- *    import { BasicCrawler, Configuration } from 'crawlee';
+ *    import { Configuration } from 'apify';
  *
- *    // Get the global configuration
  *    const config = Configuration.getGlobalConfig();
- *    // Set the 'persistStateIntervalMillis' option
- *    // of global configuration to 30 seconds
- *    config.set('persistStateIntervalMillis', 30_000);
- *
- *    // No need to pass the configuration to the crawler,
- *    // as it's using the global configuration by default
- *    const crawler = new BasicCrawler();
+ *    console.log(config.headless);
+ *    console.log(config.persistStateIntervalMillis);
  *    ```
  *
+ * Configuration is immutable — values are set via the constructor and cannot be changed afterwards.
+ * The priority order for resolving values is (highest to lowest):
+ *
+ * ```text
+ * constructor options > environment variables > crawlee.json > schema defaults
+ * ```
+ *
  * ## Supported Configuration Options
  *
  * Key | Environment Variable | Default Value
  * ---|---|---
  * `memoryMbytes` | `ACTOR_MEMORY_MBYTES` | -
- * `headless` | `APIFY_HEADLESS` | -
+ * `headless` | `APIFY_HEADLESS` | `true`
  * `persistStateIntervalMillis` | `APIFY_PERSIST_STATE_INTERVAL_MILLIS` | `60e3`
  * `token` | `APIFY_TOKEN` | -
  * `isAtHome` | `APIFY_IS_AT_HOME` | -
@@ -102,95 +126,18 @@ export interface ConfigurationOptions extends CoreConfigurationOptions {
  * `defaultBrowserPath` | `APIFY_DEFAULT_BROWSER_PATH` | -
  */
 export declare class Configuration extends CoreConfiguration {
-    /** @inheritDoc */
+    /** @internal */
     static globalConfig?: Configuration;
-    protected static ENV_MAP: {
-        APIFY_AVAILABLE_MEMORY_RATIO: string;
-        APIFY_PURGE_ON_START: string;
-        APIFY_MEMORY_MBYTES: string;
-        APIFY_DEFAULT_DATASET_ID: string;
-        APIFY_DEFAULT_KEY_VALUE_STORE_ID: string;
-        APIFY_DEFAULT_REQUEST_QUEUE_ID: string;
-        APIFY_INPUT_KEY: string;
-        APIFY_PERSIST_STATE_INTERVAL_MILLIS: string;
-        APIFY_HEADLESS: string;
-        APIFY_XVFB: string;
-        APIFY_CHROME_EXECUTABLE_PATH: string;
-        APIFY_DEFAULT_BROWSER_PATH: string;
-        APIFY_DISABLE_BROWSER_SANDBOX: string;
-        APIFY_TOKEN: string;
-        APIFY_METAMORPH_AFTER_SLEEP_MILLIS: string;
-        APIFY_TEST_PERSIST_INTERVAL_MILLIS: string;
-        APIFY_ACTOR_EVENTS_WS_URL: string;
-        APIFY_ACTOR_ID: string;
-        APIFY_API_BASE_URL: string;
-        APIFY_API_PUBLIC_BASE_URL: string;
-        APIFY_IS_AT_HOME: string;
-        APIFY_ACTOR_RUN_ID: string;
-        APIFY_ACTOR_TASK_ID: string;
-        APIFY_CONTAINER_PORT: string;
-        APIFY_CONTAINER_URL: string;
-        APIFY_USER_ID: string;
-        APIFY_PROXY_HOSTNAME: string;
-        APIFY_PROXY_PASSWORD: string;
-        APIFY_PROXY_STATUS_URL: string;
-        APIFY_PROXY_PORT: string;
-        APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE: string;
-        APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE: string;
-        APIFY_META_ORIGIN: string;
-        ACTOR_DEFAULT_DATASET_ID: string;
-        ACTOR_DEFAULT_KEY_VALUE_STORE_ID: string;
-        ACTOR_DEFAULT_REQUEST_QUEUE_ID: string;
-        ACTOR_EVENTS_WEBSOCKET_URL: string;
-        ACTOR_ID: string;
-        ACTOR_INPUT_KEY: string;
-        ACTOR_MEMORY_MBYTES: string;
-        ACTOR_RUN_ID: string;
-        ACTOR_STANDBY_PORT: string;
-        ACTOR_STANDBY_URL: string;
-        ACTOR_TASK_ID: string;
-        ACTOR_WEB_SERVER_PORT: string;
-        ACTOR_WEB_SERVER_URL: string;
-        ACTOR_MAX_TOTAL_CHARGE_USD: string;
-        ACTOR_TEST_PAY_PER_EVENT: string;
-        ACTOR_USE_CHARGING_LOG_DATASET: string;
-    };
-    protected static INTEGER_VARS: string[];
-    protected static BOOLEAN_VARS: string[];
-    protected static DEFAULTS: {
-        defaultKeyValueStoreId: string;
-        defaultDatasetId: string;
-        defaultRequestQueueId: string;
-        inputKey: string;
-        apiBaseUrl: string;
-        apiPublicBaseUrl: string;
-        proxyStatusUrl: string;
-        proxyHostname: string;
-        proxyPort: number;
-        containerPort: number;
-        containerUrl: string;
-        standbyPort: number;
-        metamorphAfterSleepMillis: number;
-        persistStateIntervalMillis: number;
-        testPayPerEvent: boolean;
-        useChargingLogDataset: boolean;
-    };
-    /**
-     * @inheritDoc
-     */
-    get<T extends keyof ConfigurationOptions, U extends ConfigurationOptions[T]>(key: T, defaultValue?: U): U;
-    /**
-     * @inheritDoc
-     */
-    set(key: keyof ConfigurationOptions, value?: any): void;
+    protected static fields: Record<string, ConfigField>;
+    constructor(options?: ApifyConfigurationInput);
     /**
      * @inheritDoc
+     *
+     * Returns the SDK's global {@link Configuration} singleton (an
+     * Apify-typed default that parses `APIFY_*` env vars). During an Actor run
+     * the active configuration is held by crawlee's `serviceLocator`, which is
+     * what crawlee internals resolve against; this singleton is only the
+     * fallback for code reaching for a configuration without an explicit one.
      */
     static getGlobalConfig(): Configuration;
-    /**
-     * Resets global configuration instance. The default instance holds configuration based on env vars,
-     * if we want to change them, we need to first reset the global state. Used mainly for testing purposes.
-     */
-    static resetGlobalState(): void;
 }
-//# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.js

@@ -1,5 +1,91 @@
-import { Configuration as CoreConfiguration } from '@crawlee/core';
-import { ACTOR_ENV_VARS, APIFY_ENV_VARS, LOCAL_ACTOR_ENV_VARS, LOCAL_APIFY_ENV_VARS, } from '@apify/consts';
+/* eslint-disable no-use-before-define */
+import { coerceBoolean, coerceNumber, Configuration as CoreConfiguration, crawleeConfigFields, field, } from '@crawlee/core';
+import { z } from 'zod';
+import { ACTOR_ENV_VARS, APIFY_ENV_VARS, LOCAL_ACTOR_ENV_VARS, LOCAL_APIFY_ENV_VARS } from '@apify/consts';
+// Evaluated lazily (per Configuration construction, not at import) so the
+// at-home defaults for `availableMemoryRatio` / `disableBrowserSandbox` below
+// react to `APIFY_IS_AT_HOME` even if it changes after import (tests, embedding).
+// Reads the env var, not the resolved `isAtHome` field, so an explicit
+// `new Configuration({ isAtHome: true })` won't flip these — env is the source.
+const isAtHome = () => !!process.env[APIFY_ENV_VARS.IS_AT_HOME];
+function withApifyEnv(base, apifyEnvVars, schema) {
+    const crawleeVars = base.envVar == null ? [] : [base.envVar].flat();
+    return field((schema ?? base.schema), [...[apifyEnvVars].flat(), ...crawleeVars]);
+}
+// --- Apify config field definitions ---
+export const apifyConfigFields = {
+    // Inherit all crawlee fields as-is.
+    ...crawleeConfigFields,
+    // Crawlee fields the SDK extends with ACTOR_/APIFY_ env-var aliases (which
+    // take precedence; crawlee's own CRAWLEE_* var is reused as the fallback,
+    // never re-typed). A schema is passed only where the SDK needs a different
+    // default than crawlee's.
+    defaultDatasetId: withApifyEnv(crawleeConfigFields.defaultDatasetId, [ACTOR_ENV_VARS.DEFAULT_DATASET_ID, APIFY_ENV_VARS.DEFAULT_DATASET_ID], z.string().default(LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_DATASET_ID])),
+    defaultKeyValueStoreId: withApifyEnv(crawleeConfigFields.defaultKeyValueStoreId, [ACTOR_ENV_VARS.DEFAULT_KEY_VALUE_STORE_ID, APIFY_ENV_VARS.DEFAULT_KEY_VALUE_STORE_ID], z.string().default(LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_KEY_VALUE_STORE_ID])),
+    defaultRequestQueueId: withApifyEnv(crawleeConfigFields.defaultRequestQueueId, [ACTOR_ENV_VARS.DEFAULT_REQUEST_QUEUE_ID, APIFY_ENV_VARS.DEFAULT_REQUEST_QUEUE_ID], z.string().default(LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_REQUEST_QUEUE_ID])),
+    inputKey: withApifyEnv(crawleeConfigFields.inputKey, [ACTOR_ENV_VARS.INPUT_KEY, APIFY_ENV_VARS.INPUT_KEY]),
+    memoryMbytes: withApifyEnv(crawleeConfigFields.memoryMbytes, [
+        ACTOR_ENV_VARS.MEMORY_MBYTES,
+        APIFY_ENV_VARS.MEMORY_MBYTES,
+    ]),
+    availableMemoryRatio: withApifyEnv(crawleeConfigFields.availableMemoryRatio, 'APIFY_AVAILABLE_MEMORY_RATIO', coerceNumber.default(() => (isAtHome() ? 1 : 0.25))),
+    disableBrowserSandbox: withApifyEnv(crawleeConfigFields.disableBrowserSandbox, 'APIFY_DISABLE_BROWSER_SANDBOX', coerceBoolean.optional().default(() => (isAtHome() ? true : undefined))),
+    persistStateIntervalMillis: withApifyEnv(crawleeConfigFields.persistStateIntervalMillis, [
+        APIFY_ENV_VARS.PERSIST_STATE_INTERVAL_MILLIS,
+        'APIFY_TEST_PERSIST_INTERVAL_MILLIS',
+    ]),
+    headless: withApifyEnv(crawleeConfigFields.headless, APIFY_ENV_VARS.HEADLESS),
+    xvfb: withApifyEnv(crawleeConfigFields.xvfb, APIFY_ENV_VARS.XVFB),
+    chromeExecutablePath: withApifyEnv(crawleeConfigFields.chromeExecutablePath, APIFY_ENV_VARS.CHROME_EXECUTABLE_PATH),
+    defaultBrowserPath: withApifyEnv(crawleeConfigFields.defaultBrowserPath, 'APIFY_DEFAULT_BROWSER_PATH'),
+    purgeOnStart: withApifyEnv(crawleeConfigFields.purgeOnStart, APIFY_ENV_VARS.PURGE_ON_START),
+    // Apify-specific fields
+    metamorphAfterSleepMillis: field(coerceNumber.default(300_000), APIFY_ENV_VARS.METAMORPH_AFTER_SLEEP_MILLIS),
+    actorEventsWsUrl: field(z.string().optional(), [
+        ACTOR_ENV_VARS.EVENTS_WEBSOCKET_URL,
+        APIFY_ENV_VARS.ACTOR_EVENTS_WS_URL,
+    ]),
+    token: field(z.string().optional(), APIFY_ENV_VARS.TOKEN),
+    actorId: field(z.string().optional(), [ACTOR_ENV_VARS.ID, APIFY_ENV_VARS.ACTOR_ID]),
+    actorRunId: field(z.string().optional(), [ACTOR_ENV_VARS.RUN_ID, APIFY_ENV_VARS.ACTOR_RUN_ID]),
+    actorTaskId: field(z.string().optional(), [ACTOR_ENV_VARS.TASK_ID, APIFY_ENV_VARS.ACTOR_TASK_ID]),
+    apiBaseUrl: field(z.string().default('https://api.apify.com'), APIFY_ENV_VARS.API_BASE_URL),
+    apiPublicBaseUrl: field(z.string().default('https://api.apify.com'), APIFY_ENV_VARS.API_PUBLIC_BASE_URL),
+    containerPort: field(coerceNumber.default(+LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.WEB_SERVER_PORT]), [
+        ACTOR_ENV_VARS.WEB_SERVER_PORT,
+        APIFY_ENV_VARS.CONTAINER_PORT,
+    ]),
+    containerUrl: field(z.string().default(LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.WEB_SERVER_URL]), [
+        ACTOR_ENV_VARS.WEB_SERVER_URL,
+        APIFY_ENV_VARS.CONTAINER_URL,
+    ]),
+    proxyHostname: field(z.string().default(LOCAL_APIFY_ENV_VARS[APIFY_ENV_VARS.PROXY_HOSTNAME]), APIFY_ENV_VARS.PROXY_HOSTNAME),
+    proxyPassword: field(z.string().optional(), APIFY_ENV_VARS.PROXY_PASSWORD),
+    proxyPort: field(coerceNumber.default(+LOCAL_APIFY_ENV_VARS[APIFY_ENV_VARS.PROXY_PORT]), APIFY_ENV_VARS.PROXY_PORT),
+    proxyStatusUrl: field(z.string().default('http://proxy.apify.com'), APIFY_ENV_VARS.PROXY_STATUS_URL),
+    /** @deprecated use `containerPort` instead */
+    standbyPort: field(coerceNumber.default(+LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.STANDBY_PORT]), ACTOR_ENV_VARS.STANDBY_PORT),
+    standbyUrl: field(z.string().optional(), ACTOR_ENV_VARS.STANDBY_URL),
+    isAtHome: field(coerceBoolean.default(false), APIFY_ENV_VARS.IS_AT_HOME),
+    userId: field(z.string().optional(), APIFY_ENV_VARS.USER_ID),
+    userIsPaying: field(z.string().optional(), APIFY_ENV_VARS.USER_IS_PAYING),
+    actorPermissionLevel: field(z.string().optional(), ACTOR_ENV_VARS.PERMISSION_LEVEL),
+    inputSecretsPrivateKeyPassphrase: field(z.string().optional(), APIFY_ENV_VARS.INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE),
+    inputSecretsPrivateKeyFile: field(z.string().optional(), APIFY_ENV_VARS.INPUT_SECRETS_PRIVATE_KEY_FILE),
+    // `0` is treated as "no limit" (mirrors the Apify platform contract).
+    maxTotalChargeUsd: field(coerceNumber.transform((val) => (val === 0 ? Infinity : val)).default(Infinity), ACTOR_ENV_VARS.MAX_TOTAL_CHARGE_USD),
+    metaOrigin: field(z.string().optional(), APIFY_ENV_VARS.META_ORIGIN),
+    testPayPerEvent: field(coerceBoolean.default(false), 'ACTOR_TEST_PAY_PER_EVENT'),
+    useChargingLogDataset: field(coerceBoolean.default(false), 'ACTOR_USE_CHARGING_LOG_DATASET'),
+    // Pay-per-event charging metadata injected by the platform (JSON strings).
+    actorPricingInfo: field(z.string().optional(), 'APIFY_ACTOR_PRICING_INFO'),
+    chargedEventCounts: field(z.string().optional(), 'APIFY_CHARGED_ACTOR_EVENT_COUNTS'),
+    actorStoragesJson: field(z.string().optional(), 'ACTOR_STORAGES_JSON'),
+    // Grab-bag of ApifyClient constructor options; the `storageDir` key is
+    // pulled out separately for local storage emulation, the rest is spread
+    // into `new ApifyClient({...})` in `Actor.newClient()`. No env var alias.
+    storageClientOptions: field(z.record(z.string(), z.unknown()).optional()),
+};
 /**
  * `Configuration` is a value object holding the SDK configuration. We can use it in two ways:
  *
@@ -7,38 +93,34 @@ import { ACTOR_ENV_VARS, APIFY_ENV_VARS, LOCAL_ACTOR_ENV_VARS, LOCAL_APIFY_ENV_V
  *
  *    ```javascript
  *    import { Actor } from 'apify';
- *    import { BasicCrawler } from 'crawlee';
  *
  *    const sdk = new Actor({ token: '123' });
- *    console.log(sdk.config.get('token')); // '123'
- *
- *    const crawler = new BasicCrawler({
- *        // ... crawler options
- *    }, sdk.config);
+ *    console.log(sdk.config.token); // '123'
  *    ```
  *
  * 2. To get the global configuration (singleton instance). It will respect the environment variables.
  *
  *    ```javascript
- *    import { BasicCrawler, Configuration } from 'crawlee';
+ *    import { Configuration } from 'apify';
  *
- *    // Get the global configuration
  *    const config = Configuration.getGlobalConfig();
- *    // Set the 'persistStateIntervalMillis' option
- *    // of global configuration to 30 seconds
- *    config.set('persistStateIntervalMillis', 30_000);
- *
- *    // No need to pass the configuration to the crawler,
- *    // as it's using the global configuration by default
- *    const crawler = new BasicCrawler();
+ *    console.log(config.headless);
+ *    console.log(config.persistStateIntervalMillis);
  *    ```
  *
+ * Configuration is immutable — values are set via the constructor and cannot be changed afterwards.
+ * The priority order for resolving values is (highest to lowest):
+ *
+ * ```text
+ * constructor options > environment variables > crawlee.json > schema defaults
+ * ```
+ *
  * ## Supported Configuration Options
  *
  * Key | Environment Variable | Default Value
  * ---|---|---
  * `memoryMbytes` | `ACTOR_MEMORY_MBYTES` | -
- * `headless` | `APIFY_HEADLESS` | -
+ * `headless` | `APIFY_HEADLESS` | `true`
  * `persistStateIntervalMillis` | `APIFY_PERSIST_STATE_INTERVAL_MILLIS` | `60e3`
  * `token` | `APIFY_TOKEN` | -
  * `isAtHome` | `APIFY_IS_AT_HOME` | -
@@ -71,137 +153,28 @@ import { ACTOR_ENV_VARS, APIFY_ENV_VARS, LOCAL_ACTOR_ENV_VARS, LOCAL_APIFY_ENV_V
  * `chromeExecutablePath` | `APIFY_CHROME_EXECUTABLE_PATH` | -
  * `defaultBrowserPath` | `APIFY_DEFAULT_BROWSER_PATH` | -
  */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Configuration extends CoreConfiguration {
-    /** @inheritDoc */
-    // eslint-disable-next-line no-use-before-define -- Self-reference
+    /** @internal */
     static globalConfig;
-    // maps environment variables to config keys (e.g. `APIFY_MEMORY_MBYTES` to `memoryMbytes`)
-    static ENV_MAP = {
-        // regular crawlee env vars are also supported
-        ...CoreConfiguration.ENV_MAP,
-        // support crawlee env vars prefixed with `APIFY_` too
-        APIFY_AVAILABLE_MEMORY_RATIO: 'availableMemoryRatio',
-        APIFY_PURGE_ON_START: 'purgeOnStart',
-        APIFY_MEMORY_MBYTES: 'memoryMbytes',
-        APIFY_DEFAULT_DATASET_ID: 'defaultDatasetId',
-        APIFY_DEFAULT_KEY_VALUE_STORE_ID: 'defaultKeyValueStoreId',
-        APIFY_DEFAULT_REQUEST_QUEUE_ID: 'defaultRequestQueueId',
-        APIFY_INPUT_KEY: 'inputKey',
-        APIFY_PERSIST_STATE_INTERVAL_MILLIS: 'persistStateIntervalMillis',
-        APIFY_HEADLESS: 'headless',
-        APIFY_XVFB: 'xvfb',
-        APIFY_CHROME_EXECUTABLE_PATH: 'chromeExecutablePath',
-        APIFY_DEFAULT_BROWSER_PATH: 'defaultBrowserPath',
-        APIFY_DISABLE_BROWSER_SANDBOX: 'disableBrowserSandbox',
-        // as well as apify specific ones
-        APIFY_TOKEN: 'token',
-        APIFY_METAMORPH_AFTER_SLEEP_MILLIS: 'metamorphAfterSleepMillis',
-        APIFY_TEST_PERSIST_INTERVAL_MILLIS: 'persistStateIntervalMillis', // for BC, seems to be unused
-        APIFY_ACTOR_EVENTS_WS_URL: 'actorEventsWsUrl',
-        APIFY_ACTOR_ID: 'actorId',
-        APIFY_API_BASE_URL: 'apiBaseUrl',
-        APIFY_API_PUBLIC_BASE_URL: 'apiPublicBaseUrl',
-        APIFY_IS_AT_HOME: 'isAtHome',
-        APIFY_ACTOR_RUN_ID: 'actorRunId',
-        APIFY_ACTOR_TASK_ID: 'actorTaskId',
-        APIFY_CONTAINER_PORT: 'containerPort',
-        APIFY_CONTAINER_URL: 'containerUrl',
-        APIFY_USER_ID: 'userId',
-        APIFY_PROXY_HOSTNAME: 'proxyHostname',
-        APIFY_PROXY_PASSWORD: 'proxyPassword',
-        APIFY_PROXY_STATUS_URL: 'proxyStatusUrl',
-        APIFY_PROXY_PORT: 'proxyPort',
-        APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE: 'inputSecretsPrivateKeyFile',
-        APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE: 'inputSecretsPrivateKeyPassphrase',
-        APIFY_META_ORIGIN: 'metaOrigin',
-        // Actor env vars
-        ACTOR_DEFAULT_DATASET_ID: 'defaultDatasetId',
-        ACTOR_DEFAULT_KEY_VALUE_STORE_ID: 'defaultKeyValueStoreId',
-        ACTOR_DEFAULT_REQUEST_QUEUE_ID: 'defaultRequestQueueId',
-        ACTOR_EVENTS_WEBSOCKET_URL: 'actorEventsWsUrl',
-        ACTOR_ID: 'actorId',
-        ACTOR_INPUT_KEY: 'inputKey',
-        ACTOR_MEMORY_MBYTES: 'memoryMbytes',
-        ACTOR_RUN_ID: 'actorRunId',
-        ACTOR_STANDBY_PORT: 'standbyPort',
-        ACTOR_STANDBY_URL: 'standbyUrl',
-        ACTOR_TASK_ID: 'actorTaskId',
-        ACTOR_WEB_SERVER_PORT: 'containerPort',
-        ACTOR_WEB_SERVER_URL: 'containerUrl',
-        ACTOR_MAX_TOTAL_CHARGE_USD: 'maxTotalChargeUsd',
-        ACTOR_TEST_PAY_PER_EVENT: 'testPayPerEvent',
-        ACTOR_USE_CHARGING_LOG_DATASET: 'useChargingLogDataset',
-    };
-    static INTEGER_VARS = [
-        ...CoreConfiguration.INTEGER_VARS,
-        'proxyPort',
-        'containerPort',
-        'metamorphAfterSleepMillis',
-        'maxTotalChargeUsd',
-    ];
-    static BOOLEAN_VARS = [
-        ...CoreConfiguration.BOOLEAN_VARS,
-        'isAtHome',
-        'testPayPerEvent',
-        'useChargingLogDataset',
-    ];
-    static DEFAULTS = {
-        ...CoreConfiguration.DEFAULTS,
-        defaultKeyValueStoreId: LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_KEY_VALUE_STORE_ID],
-        defaultDatasetId: LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_DATASET_ID],
-        defaultRequestQueueId: LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.DEFAULT_REQUEST_QUEUE_ID],
-        inputKey: 'INPUT',
-        apiBaseUrl: 'https://api.apify.com',
-        apiPublicBaseUrl: 'https://api.apify.com',
-        proxyStatusUrl: 'http://proxy.apify.com',
-        proxyHostname: LOCAL_APIFY_ENV_VARS[APIFY_ENV_VARS.PROXY_HOSTNAME],
-        proxyPort: +LOCAL_APIFY_ENV_VARS[APIFY_ENV_VARS.PROXY_PORT],
-        containerPort: +LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.WEB_SERVER_PORT],
-        containerUrl: LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.WEB_SERVER_URL],
-        standbyPort: +LOCAL_ACTOR_ENV_VARS[ACTOR_ENV_VARS.STANDBY_PORT],
-        metamorphAfterSleepMillis: 300e3,
-        persistStateIntervalMillis: 60e3, // This value is mentioned in jsdoc in `events.js`, if you update it here, update it there too.
-        testPayPerEvent: false,
-        useChargingLogDataset: false,
-    };
-    /**
-     * @inheritDoc
-     */
-    get(key, defaultValue) {
-        return super.get(key, defaultValue);
-    }
-    /**
-     * @inheritDoc
-     */
-    set(key, value) {
-        super.set(key, value);
+    static fields = apifyConfigFields;
+    constructor(options = {}) {
+        // `super` types its options against crawlee's field set; ours is a
+        // superset (apifyConfigFields spreads crawleeConfigFields), so the
+        // shapes are runtime-compatible but not TS-assignable — hence the cast.
+        super(options);
     }
     /**
      * @inheritDoc
+     *
+     * Returns the SDK's global {@link Configuration} singleton (an
+     * Apify-typed default that parses `APIFY_*` env vars). During an Actor run
+     * the active configuration is held by crawlee's `serviceLocator`, which is
+     * what crawlee internals resolve against; this singleton is only the
+     * fallback for code reaching for a configuration without an explicit one.
      */
     static getGlobalConfig() {
-        if (Configuration.storage.getStore()) {
-            return Configuration.storage.getStore();
-        }
         Configuration.globalConfig ??= new Configuration();
         return Configuration.globalConfig;
     }
-    /**
-     * Resets global configuration instance. The default instance holds configuration based on env vars,
-     * if we want to change them, we need to first reset the global state. Used mainly for testing purposes.
-     */
-    static resetGlobalState() {
-        delete this.globalConfig;
-    }
 }
-// monkey patch the core class so it respects the new options too
-CoreConfiguration.getGlobalConfig = Configuration.getGlobalConfig;
-// @ts-expect-error protected property
-CoreConfiguration.ENV_MAP = Configuration.ENV_MAP;
-// @ts-expect-error protected property
-CoreConfiguration.INTEGER_VARS = Configuration.INTEGER_VARS;
-// @ts-expect-error protected property
-CoreConfiguration.BOOLEAN_VARS = Configuration.BOOLEAN_VARS;
-// @ts-expect-error protected property
-CoreConfiguration.DEFAULTS = Configuration.DEFAULTS;
-//# sourceMappingURL=configuration.js.map

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export * from './actor.js';
-export * from './charging.js';
+export type { OpenStorageOptions, StorageAlias, StorageId, StorageName, StorageIdentifier, StorageIdentifierWithoutAlias, } from './storage.js';
+export { ChargeOptions, ChargeResult, ActorPricingInfo, ChargingManager } from './charging.js';
 export * from './configuration.js';
 export * from './proxy_configuration.js';
 export * from './platform_event_manager.js';
 export * from './key_value_store.js';
 export { Dataset, DatasetDataOptions, DatasetIteratorOptions, DatasetConsumer, DatasetMapper, DatasetReducer, DatasetOptions, DatasetContent, RequestQueue, QueueOperationInfo, RequestQueueOperationOptions, RequestQueueOptions, KeyConsumer, KeyValueStoreOptions, RecordOptions, KeyValueStoreIteratorOptions, log, Log, LoggerOptions, LogLevel, Logger, LoggerJson, LoggerText, } from '@crawlee/core';
 export { ApifyClient, ApifyClientOptions } from 'apify-client';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,9 +1,8 @@
 export * from './actor.js';
-export * from './charging.js';
+export { ChargingManager } from './charging.js';
 export * from './configuration.js';
 export * from './proxy_configuration.js';
 export * from './platform_event_manager.js';
 export * from './key_value_store.js';
 export { Dataset, RequestQueue, log, Log, LogLevel, Logger, LoggerJson, LoggerText, } from '@crawlee/core';
 export { ApifyClient } from 'apify-client';
-//# sourceMappingURL=index.js.map

package/dist/input-schemas.d.ts

@@ -0,0 +1,7 @@
+import type { Dictionary } from '@crawlee/utils';
+/**
+ * @ignore
+ */
+export declare const noActorInputSchemaDefinedMarker: unique symbol;
+export declare const readInputSchema: () => Dictionary | null | typeof noActorInputSchemaDefinedMarker;
+export declare const getDefaultsFromInputSchema: (inputSchema: any) => Record<string, unknown>;

package/dist/input-schemas.js

@@ -0,0 +1,58 @@
+// TODO: https://github.com/apify/apify-shared-js/issues/547
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+// These paths are used *if* there is no `input` field in the actor.json configuration file!
+const DEFAULT_INPUT_SCHEMA_PATHS = [
+    ['.actor', 'INPUT_SCHEMA.json'],
+    ['INPUT_SCHEMA.json'],
+    ['.actor', 'input_schema.json'],
+    ['input_schema.json'],
+];
+const ACTOR_SPECIFICATION_FOLDER = '.actor';
+const LOCAL_CONFIG_NAME = 'actor.json';
+const readJSONIfExists = (path) => {
+    if (existsSync(path)) {
+        const content = readFileSync(path, 'utf8');
+        return JSON.parse(content);
+    }
+    return null;
+};
+/**
+ * @ignore
+ */
+export const noActorInputSchemaDefinedMarker = Symbol.for('apify.noActorInputSchemaDefined');
+export const readInputSchema = () => {
+    const localConfig = readJSONIfExists(join(process.cwd(), ACTOR_SPECIFICATION_FOLDER, LOCAL_CONFIG_NAME));
+    // Input schema nested in the actor config
+    if (typeof localConfig?.input === 'object') {
+        return localConfig.input;
+    }
+    // Input schema path from the actor config
+    if (typeof localConfig?.input === 'string') {
+        const fullPath = join(process.cwd(), ACTOR_SPECIFICATION_FOLDER, localConfig.input);
+        return readJSONIfExists(fullPath);
+    }
+    // Try to find it from possible default paths
+    for (const path of DEFAULT_INPUT_SCHEMA_PATHS) {
+        const fullPath = join(process.cwd(), ...path);
+        const result = readJSONIfExists(fullPath);
+        if (result) {
+            return result;
+        }
+    }
+    // If we are in an Actor context, BUT we do not have an input schema defined, we want to skip the warning
+    if (!localConfig?.input) {
+        return noActorInputSchemaDefinedMarker;
+    }
+    return null;
+};
+export const getDefaultsFromInputSchema = (inputSchema) => {
+    const defaults = {};
+    for (const [key, fieldSchema] of Object.entries(inputSchema.properties)) {
+        if (fieldSchema.default !== undefined) {
+            defaults[key] = fieldSchema.default;
+        }
+    }
+    return defaults;
+};

package/dist/key_value_store.d.ts

@@ -1,4 +1,4 @@
-import type { StorageManagerOptions } from '@crawlee/core';
+import type { StorageOpenOptions } from '@crawlee/core';
 import { KeyValueStore as CoreKeyValueStore } from '@crawlee/core';
 /**
  * @inheritDoc
@@ -7,11 +7,15 @@ export declare class KeyValueStore extends CoreKeyValueStore {
     /**
      * Returns a URL for the given key that may be used to publicly
      * access the value in the remote key-value store.
+     *
+     * On the Apify platform the URL is signed with the store's
+     * `urlSigningSecretKey` so that anyone with the URL can read the record
+     * without authentication. Locally we delegate to crawlee's default
+     * implementation (which produces a `file://` URL or returns `undefined`).
      */
-    getPublicUrl(key: string): string;
+    getPublicUrl(key: string): Promise<string | undefined>;
     /**
      * @inheritDoc
      */
-    static open(storeIdOrName?: string | null, options?: StorageManagerOptions): Promise<KeyValueStore>;
+    static open(storeIdOrName?: string | null, options?: StorageOpenOptions): Promise<KeyValueStore>;
 }
-//# sourceMappingURL=key_value_store.d.ts.map