apify 4.0.0-beta.39 → 4.0.0-beta.41

package/README.md

@@ -26,7 +26,7 @@ import { Actor } from 'apify';
 
 await Actor.init();
 
-const input = (await Actor.getInput()) ?? {};
+const input = await Actor.getInput();
 await Actor.setValue('OUTPUT', {
     message: 'Hello from Apify SDK!',
     input,

package/dist/actor.d.ts

@@ -673,17 +673,17 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
     /**
      * Gets the Actor input value from the default {@link KeyValueStore} associated with the current Actor run.
      *
-     * This is just a convenient shortcut for [`keyValueStore.getValue('INPUT')`](core/class/KeyValueStore#getValue).
-     * For example, calling the following code:
-     * ```js
-     * const input = await Actor.getInput();
-     * ```
+     * The input is the record stored under the configured input key (`ACTOR_INPUT_KEY`, default `INPUT`).
+     * A record stored as `application/octet-stream` — which is what a local input file without an
+     * extension is read as — is parsed with JSON5 when it parses, and returned as a `Buffer` otherwise.
      *
-     * is equivalent to:
-     * ```js
-     * const store = await Actor.openKeyValueStore();
-     * await store.getValue('INPUT');
-     * ```
+     * When running locally and the store holds no such record, the input is read from a `<inputKey>` or
+     * `<inputKey>.json` file in the current working directory instead.
+     *
+     * Throws an {@link ActorInputError} when no input is found (`code: 'NOT_FOUND'`), when both input
+     * files exist in the working directory (`'MULTIPLE_FILES'`), when a JSON input does not parse
+     * (`'PARSE_FAILED'`) or when its secret fields cannot be decrypted (`'DECRYPTION_FAILED'`). If your
+     * Actor can run without input, catch the `'NOT_FOUND'` case and rethrow the rest.
      *
      * Note that the `getInput()` function does not cache the value read from the key-value store.
      * If you need to use the input multiple times in your Actor,
@@ -695,16 +695,20 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @returns
      *   Returns a promise that resolves to an object, string
      *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
-     *   on the MIME content type of the record, or `null`
-     *   if the record is missing.
+     *   on the MIME content type of the record.
+     * @throws {ActorInputError} When the input cannot be produced; see `code`.
      * @ignore
      */
-    getInput<T = Dictionary | string | Buffer>(): Promise<T | null>;
+    getInput<T = Dictionary | string | Buffer>(): Promise<T>;
     /**
-     * Gets the Actor input value just like the {@link Actor.getInput} method,
-     * but throws if it is not found.
+     * Reads the input from a `<inputKey>` or `<inputKey>.json` file in the working directory, for local runs
+     * whose default key-value store holds no input record. Mirrors how `ApifyFileSystemStorageBackend` adopts
+     * such files inside the store directory: the `.json` file is JSON, the bare one is bytes that
+     * {@link parseInputValue} tries as JSON5. Both files present is an error rather than a guess.
+     *
+     * @returns `undefined` when running on the platform or when neither file exists.
      */
-    getInputOrThrow<T = Dictionary | string | Buffer>(): Promise<T>;
+    private readInputFromWorkingDirectory;
     /**
      * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
      *
@@ -1218,16 +1222,28 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
     /**
      * Gets the Actor input value from the default {@link KeyValueStore} associated with the current Actor run.
      *
-     * This is just a convenient shortcut for {@link KeyValueStore.getValue | `keyValueStore.getValue('INPUT')`}.
-     * For example, calling the following code:
+     * The input is the record stored under the configured input key (`ACTOR_INPUT_KEY`, default `INPUT`):
      * ```js
      * const input = await Actor.getInput();
      * ```
      *
-     * is equivalent to:
+     * A record stored as `application/octet-stream` — which is what a local input file without an
+     * extension is read as — is parsed with JSON5 when it parses, and returned as a `Buffer` otherwise.
+     *
+     * When running locally and the store holds no such record, the input is read from a `<inputKey>` or
+     * `<inputKey>.json` file in the current working directory instead.
+     *
+     * Throws an {@link ActorInputError} when no input is found (`code: 'NOT_FOUND'`), when both input
+     * files exist in the working directory (`'MULTIPLE_FILES'`), when a JSON input does not parse
+     * (`'PARSE_FAILED'`) or when its secret fields cannot be decrypted (`'DECRYPTION_FAILED'`). If your
+     * Actor can run without input, catch the `'NOT_FOUND'` case and rethrow the rest:
      * ```js
-     * const store = await Actor.openKeyValueStore();
-     * await store.getValue('INPUT');
+     * let input = {};
+     * try {
+     *     input = await Actor.getInput();
+     * } catch (error) {
+     *     if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;
+     * }
      * ```
      *
      * Note that the `getInput()` function does not cache the value read from the key-value store.
@@ -1239,15 +1255,10 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @returns
      *   Returns a promise that resolves to an object, string
      *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
-     *   on the MIME content type of the record, or `null`
-     *   if the record is missing.
-     */
-    static getInput<T = Dictionary | string | Buffer>(): Promise<T | null>;
-    /**
-     * Gets the Actor input value just like the {@link Actor.getInput} method,
-     * but throws if it is not found.
+     *   on the MIME content type of the record.
+     * @throws {ActorInputError} When the input cannot be produced; see `code`.
      */
-    static getInputOrThrow<T = Dictionary | string | Buffer>(): Promise<T>;
+    static getInput<T = Dictionary | string | Buffer>(): Promise<T>;
     /**
      * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
      *
@@ -1375,6 +1386,12 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @internal
      */
     static setDefaultInstance(instance?: Actor): void;
+    /**
+     * The same choice crawlee's `ServiceLocator` makes for its implicit default backend, with the
+     * input-aware {@link ApifyFileSystemStorageBackend} in place of crawlee's — crawlee has no
+     * notion of a run input.
+     */
+    private createLocalStorageBackend;
     /**
      * crawlee's service locator is set-once, so a backend registered before `init()` wins and the
      * Actor cannot install its own over it. Replaces the resulting `ServiceConflictError` with the

package/dist/actor.js

@@ -1,5 +1,7 @@
 import { createPrivateKey } from 'node:crypto';
-import { Dataset, EventType, KeyValueStore, purgeDefaultStorages, rejectOperationInTransaction, RequestQueue, ServiceLocator, serviceLocator, } from '@crawlee/core';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Dataset, EventType, KeyValueStore, MemoryStorageBackend, purgeDefaultStorages, rejectOperationInTransaction, RequestQueue, serviceLocator, } from '@crawlee/core';
 import { sleep } from '@crawlee/utils';
 import { ApifyClient } from 'apify-client';
 import { z } from 'zod';
@@ -8,15 +10,29 @@ import { decryptInputSecrets } from '@apify/input_secrets';
 import log from '@apify/log';
 import { addTimeoutToPromise } from '@apify/timeout';
 import { parseArgument } from '@apify/validations';
+import { ApifyFileSystemStorageBackend } from './apify_file_system_storage_backend.js';
 import { ApifyStorageBackend } from './apify_storage_backend.js';
 import { ChargingManager, DEFAULT_DATASET_ITEM_EVENT } from './charging.js';
 import { ChargingDatasetBackend, ChargingStorageBackend } from './charging_storage_backend.js';
 import { Configuration } from './configuration.js';
+import { ActorInputError } from './errors.js';
 import { getDefaultsFromInputSchema, noActorInputSchemaDefinedMarker, readInputSchema } from './input-schemas.js';
 import { PlatformEventManager } from './platform_event_manager.js';
 import { ProxyConfiguration } from './proxy_configuration.js';
 import { SmartApifyStorageBackend } from './smart_apify_storage_backend.js';
-import { checkCrawleeVersion, getSystemInfo, isNonEmptyObject, printOutdatedSdkWarning, snakeCaseToCamelCase, } from './utils.js';
+import { BINARY_CONTENT_TYPE, checkCrawleeVersion, getSystemInfo, isNonEmptyObject, JSON_CONTENT_TYPE, parseInputValue, printOutdatedSdkWarning, snakeCaseToCamelCase, } from './utils.js';
+/**
+ * {@link parseInputValue} with the parser error wrapped as an {@link ActorInputError}, so a malformed
+ * JSON input reports where it came from.
+ */
+function parseInput(value, contentType, source) {
+    try {
+        return parseInputValue(value, contentType);
+    }
+    catch (cause) {
+        throw new ActorInputError('PARSE_FAILED', `The input in ${source} is not valid JSON.`, { cause });
+    }
+}
 /**
  * Exit codes for the Actor process.
  * The error codes must be in the range 1-128, to avoid collision with signal exits
@@ -797,17 +813,17 @@ export class Actor {
     /**
      * Gets the Actor input value from the default {@link KeyValueStore} associated with the current Actor run.
      *
-     * This is just a convenient shortcut for [`keyValueStore.getValue('INPUT')`](core/class/KeyValueStore#getValue).
-     * For example, calling the following code:
-     * ```js
-     * const input = await Actor.getInput();
-     * ```
+     * The input is the record stored under the configured input key (`ACTOR_INPUT_KEY`, default `INPUT`).
+     * A record stored as `application/octet-stream` — which is what a local input file without an
+     * extension is read as — is parsed with JSON5 when it parses, and returned as a `Buffer` otherwise.
      *
-     * is equivalent to:
-     * ```js
-     * const store = await Actor.openKeyValueStore();
-     * await store.getValue('INPUT');
-     * ```
+     * When running locally and the store holds no such record, the input is read from a `<inputKey>` or
+     * `<inputKey>.json` file in the current working directory instead.
+     *
+     * Throws an {@link ActorInputError} when no input is found (`code: 'NOT_FOUND'`), when both input
+     * files exist in the working directory (`'MULTIPLE_FILES'`), when a JSON input does not parse
+     * (`'PARSE_FAILED'`) or when its secret fields cannot be decrypted (`'DECRYPTION_FAILED'`). If your
+     * Actor can run without input, catch the `'NOT_FOUND'` case and rethrow the rest.
      *
      * Note that the `getInput()` function does not cache the value read from the key-value store.
      * If you need to use the input multiple times in your Actor,
@@ -819,21 +835,39 @@ export class Actor {
      * @returns
      *   Returns a promise that resolves to an object, string
      *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
-     *   on the MIME content type of the record, or `null`
-     *   if the record is missing.
+     *   on the MIME content type of the record.
+     * @throws {ActorInputError} When the input cannot be produced; see `code`.
      * @ignore
      */
     async getInput() {
         this.ensureActorInit('getInput');
-        const { inputSecretsPrivateKeyFile, inputSecretsPrivateKeyPassphrase } = this.configuration;
-        const rawInput = await this.getValue(this.configuration.inputKey);
+        const { inputKey, inputSecretsPrivateKeyFile, inputSecretsPrivateKeyPassphrase } = this.configuration;
+        const store = await this.openKeyValueStore();
+        const record = await store.getRecord(inputKey);
+        const rawInput = record
+            ? parseInput(record.value, record.contentType, `the "${inputKey}" record of the default key-value store`)
+            : await this.readInputFromWorkingDirectory(inputKey);
+        if (rawInput == null) {
+            const locations = [`the "${inputKey}" record of the default key-value store`];
+            if (!this.configuration.isAtHome) {
+                locations.push(`a "${inputKey}" or "${inputKey}.json" file in the working directory`);
+            }
+            throw new ActorInputError('NOT_FOUND', `Input does not exist. Expected ${locations.join(' or ')}.`);
+        }
         let input = rawInput;
         if (isNonEmptyObject(rawInput) && inputSecretsPrivateKeyFile && inputSecretsPrivateKeyPassphrase) {
-            const privateKey = createPrivateKey({
-                key: Buffer.from(inputSecretsPrivateKeyFile, 'base64'),
-                passphrase: inputSecretsPrivateKeyPassphrase,
-            });
-            input = decryptInputSecrets({ input: rawInput, privateKey });
+            try {
+                const privateKey = createPrivateKey({
+                    key: Buffer.from(inputSecretsPrivateKeyFile, 'base64'),
+                    passphrase: inputSecretsPrivateKeyPassphrase,
+                });
+                input = decryptInputSecrets({ input: rawInput, privateKey });
+            }
+            catch (cause) {
+                throw new ActorInputError('DECRYPTION_FAILED', 'Failed to decrypt the secret fields of the input.', {
+                    cause,
+                });
+            }
         }
         if (isNonEmptyObject(input) && !Buffer.isBuffer(input)) {
             input = await this.inferDefaultsFromInputSchema(input);
@@ -841,15 +875,37 @@ export class Actor {
         return input;
     }
     /**
-     * Gets the Actor input value just like the {@link Actor.getInput} method,
-     * but throws if it is not found.
+     * Reads the input from a `<inputKey>` or `<inputKey>.json` file in the working directory, for local runs
+     * whose default key-value store holds no input record. Mirrors how `ApifyFileSystemStorageBackend` adopts
+     * such files inside the store directory: the `.json` file is JSON, the bare one is bytes that
+     * {@link parseInputValue} tries as JSON5. Both files present is an error rather than a guess.
+     *
+     * @returns `undefined` when running on the platform or when neither file exists.
      */
-    async getInputOrThrow() {
-        const input = await this.getInput();
-        if (input == null) {
-            throw new Error('Input does not exist');
+    async readInputFromWorkingDirectory(inputKey) {
+        if (this.configuration.isAtHome) {
+            return undefined;
         }
-        return input;
+        const candidates = [
+            { filename: inputKey, contentType: BINARY_CONTENT_TYPE },
+            { filename: `${inputKey}.json`, contentType: JSON_CONTENT_TYPE },
+        ];
+        const found = [];
+        for (const candidate of candidates) {
+            const path = join(process.cwd(), candidate.filename);
+            const stats = await stat(path).catch(() => null);
+            if (stats?.isFile()) {
+                found.push({ ...candidate, path });
+            }
+        }
+        if (found.length > 1) {
+            throw new ActorInputError('MULTIPLE_FILES', `Found multiple input files in the working directory: ${found.map((file) => `"${file.filename}"`).join(', ')}. Keep only one of them.`);
+        }
+        if (found.length === 0) {
+            return undefined;
+        }
+        const [file] = found;
+        return parseInput(await readFile(file.path), file.contentType, `the "${file.filename}" file in the working directory`);
     }
     /**
      * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
@@ -1463,16 +1519,28 @@ export class Actor {
     /**
      * Gets the Actor input value from the default {@link KeyValueStore} associated with the current Actor run.
      *
-     * This is just a convenient shortcut for {@link KeyValueStore.getValue | `keyValueStore.getValue('INPUT')`}.
-     * For example, calling the following code:
+     * The input is the record stored under the configured input key (`ACTOR_INPUT_KEY`, default `INPUT`):
      * ```js
      * const input = await Actor.getInput();
      * ```
      *
-     * is equivalent to:
+     * A record stored as `application/octet-stream` — which is what a local input file without an
+     * extension is read as — is parsed with JSON5 when it parses, and returned as a `Buffer` otherwise.
+     *
+     * When running locally and the store holds no such record, the input is read from a `<inputKey>` or
+     * `<inputKey>.json` file in the current working directory instead.
+     *
+     * Throws an {@link ActorInputError} when no input is found (`code: 'NOT_FOUND'`), when both input
+     * files exist in the working directory (`'MULTIPLE_FILES'`), when a JSON input does not parse
+     * (`'PARSE_FAILED'`) or when its secret fields cannot be decrypted (`'DECRYPTION_FAILED'`). If your
+     * Actor can run without input, catch the `'NOT_FOUND'` case and rethrow the rest:
      * ```js
-     * const store = await Actor.openKeyValueStore();
-     * await store.getValue('INPUT');
+     * let input = {};
+     * try {
+     *     input = await Actor.getInput();
+     * } catch (error) {
+     *     if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;
+     * }
      * ```
      *
      * Note that the `getInput()` function does not cache the value read from the key-value store.
@@ -1484,19 +1552,12 @@ export class Actor {
      * @returns
      *   Returns a promise that resolves to an object, string
      *   or [`Buffer`](https://nodejs.org/api/buffer.html), depending
-     *   on the MIME content type of the record, or `null`
-     *   if the record is missing.
+     *   on the MIME content type of the record.
+     * @throws {ActorInputError} When the input cannot be produced; see `code`.
      */
     static async getInput() {
         return Actor.getDefaultInstance().getInput();
     }
-    /**
-     * Gets the Actor input value just like the {@link Actor.getInput} method,
-     * but throws if it is not found.
-     */
-    static async getInputOrThrow() {
-        return Actor.getDefaultInstance().getInputOrThrow();
-    }
     /**
      * Opens a key-value store and returns a promise resolving to an instance of the {@link KeyValueStore} class.
      *
@@ -1668,10 +1729,27 @@ export class Actor {
                 configuration: this.configuration,
                 requestQueueAccess: this.#requestQueueAccess,
             }), charging),
-            localStorageBackend: new ChargingStorageBackend(new ServiceLocator(this.configuration).getStorageBackend(), charging),
+            localStorageBackend: new ChargingStorageBackend(this.createLocalStorageBackend(), charging),
             configuration: this.configuration,
         }));
     }
+    /**
+     * The same choice crawlee's `ServiceLocator` makes for its implicit default backend, with the
+     * input-aware {@link ApifyFileSystemStorageBackend} in place of crawlee's — crawlee has no
+     * notion of a run input.
+     */
+    createLocalStorageBackend() {
+        const { persistStorage, storageDir, inputKey } = this.configuration;
+        const logger = serviceLocator.getLogger();
+        if (!persistStorage) {
+            return new MemoryStorageBackend({ logger: logger.child({ prefix: 'MemoryStorageBackend' }) });
+        }
+        return new ApifyFileSystemStorageBackend({
+            localDataDirectory: storageDir,
+            inputKey,
+            logger: logger.child({ prefix: 'ApifyFileSystemStorageBackend' }),
+        });
+    }
     /** Whether items reaching the run's default dataset are counted for pay-per-event charging. */
     #chargesDefaultDatasetItems() {
         const installed = serviceLocator.getStorageBackend();

package/dist/apify_file_system_storage_backend.d.ts

@@ -0,0 +1,34 @@
+import type { AdoptionCandidate, FileSystemStorageOptions, KeyValueStoreHookOptions, PurgeableKeyValueStoreBackend } from '@crawlee/fs-storage';
+import { FileSystemStorageBackend } from '@crawlee/fs-storage';
+export interface ApifyFileSystemStorageOptions extends FileSystemStorageOptions {
+    /**
+     * The key the Actor input is read from — `Configuration.inputKey` (`ACTOR_INPUT_KEY`).
+     *
+     * `INPUT` is treated as an input key regardless of this setting, so a project's `INPUT.json` stays
+     * intact when the Apify CLI redirects the run to a temporary key.
+     *
+     * @default 'INPUT'
+     */
+    inputKey?: string;
+}
+/**
+ * Crawlee's file-system storage backend, aware of the Actor input.
+ *
+ * Locally the input arrives in the default key-value store as a bare `INPUT` or `INPUT.json` file with
+ * no metadata sidecar — written by the Apify CLI, a project template, or by hand. This backend adopts
+ * such a file as the record under the input key when the store is opened (both files present fails the
+ * open), and keeps the input keys when the default store is purged on start. Everything else is
+ * inherited from {@link FileSystemStorageBackend}.
+ *
+ * `Actor` installs it as the local backend; pass an instance to `Actor.init({ storage })` only if you
+ * need to construct it yourself.
+ */
+export declare class ApifyFileSystemStorageBackend extends FileSystemStorageBackend {
+    /** `INPUT` plus the configured input key, deduplicated. */
+    private readonly inputKeys;
+    constructor(options: ApifyFileSystemStorageOptions);
+    /** Claims a bare `<key>` or `<key>.json` in the default store for each input key, ahead of the generic sweep. */
+    protected keyValueStoreAdoptionCandidates(options: KeyValueStoreHookOptions): AdoptionCandidate[];
+    /** Spares the input keys in the default store; every other run-scoped store is emptied. */
+    protected purgeKeyValueStore(store: PurgeableKeyValueStoreBackend, options: KeyValueStoreHookOptions): Promise<void>;
+}

package/dist/apify_file_system_storage_backend.js

@@ -0,0 +1,41 @@
+import { FileSystemStorageBackend } from '@crawlee/fs-storage';
+import { KEY_VALUE_STORE_KEYS } from '@apify/consts';
+import { BINARY_CONTENT_TYPE, JSON_CONTENT_TYPE } from './utils.js';
+/**
+ * Crawlee's file-system storage backend, aware of the Actor input.
+ *
+ * Locally the input arrives in the default key-value store as a bare `INPUT` or `INPUT.json` file with
+ * no metadata sidecar — written by the Apify CLI, a project template, or by hand. This backend adopts
+ * such a file as the record under the input key when the store is opened (both files present fails the
+ * open), and keeps the input keys when the default store is purged on start. Everything else is
+ * inherited from {@link FileSystemStorageBackend}.
+ *
+ * `Actor` installs it as the local backend; pass an instance to `Actor.init({ storage })` only if you
+ * need to construct it yourself.
+ */
+export class ApifyFileSystemStorageBackend extends FileSystemStorageBackend {
+    /** `INPUT` plus the configured input key, deduplicated. */
+    inputKeys;
+    constructor(options) {
+        const { inputKey = KEY_VALUE_STORE_KEYS.INPUT, ...fileSystemOptions } = options;
+        super(fileSystemOptions);
+        this.inputKeys = [...new Set([KEY_VALUE_STORE_KEYS.INPUT, inputKey])];
+    }
+    /** Claims a bare `<key>` or `<key>.json` in the default store for each input key, ahead of the generic sweep. */
+    keyValueStoreAdoptionCandidates(options) {
+        const inputCandidates = options.isDefaultStore
+            ? this.inputKeys.map((key) => ({
+                key,
+                files: [
+                    { filename: key, contentType: BINARY_CONTENT_TYPE },
+                    { filename: `${key}.json`, contentType: JSON_CONTENT_TYPE },
+                ],
+            }))
+            : [];
+        return [...inputCandidates, ...super.keyValueStoreAdoptionCandidates(options)];
+    }
+    /** Spares the input keys in the default store; every other run-scoped store is emptied. */
+    async purgeKeyValueStore(store, options) {
+        await (options.isDefaultStore ? store.purgeExcept([...this.inputKeys]) : store.purge());
+    }
+}

package/dist/configuration.d.ts

@@ -9,7 +9,6 @@ export declare const apifyConfigFields: {
     persistStorage: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodBoolean, unknown>>>;
     storageDir: ConfigField<z.ZodDefault<z.ZodString>>;
     containerized: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodBoolean, unknown>>>;
-    inputKey: ConfigField<z.ZodDefault<z.ZodString>>;
     memoryMbytes: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodNumber, unknown>>>;
     availableMemoryRatio: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodNumber, unknown>>>;
     disableBrowserSandbox: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodBoolean, unknown>>>;
@@ -22,6 +21,7 @@ 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>>;
     metamorphAfterSleepMillis: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodNumber, unknown>>>;
     actorEventsWsUrl: ConfigField<z.ZodOptional<z.ZodString>>;
     token: ConfigField<z.ZodOptional<z.ZodString>>;

package/dist/configuration.js

@@ -20,7 +20,6 @@ export const apifyConfigFields = {
     // 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.
-    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,
@@ -51,6 +50,13 @@ export const apifyConfigFields = {
         APIFY_ENV_VARS.DEFAULT_REQUEST_QUEUE_ID,
     ]),
     // Apify-specific fields
+    // Crawlee has no notion of a run input; `CRAWLEE_INPUT_KEY` stays as the
+    // lowest-priority alias because the Apify CLI sets all three variables.
+    inputKey: field(z.string().default('INPUT'), [
+        ACTOR_ENV_VARS.INPUT_KEY,
+        APIFY_ENV_VARS.INPUT_KEY,
+        'CRAWLEE_INPUT_KEY',
+    ]),
     metamorphAfterSleepMillis: field(coerceNumber.default(300_000), APIFY_ENV_VARS.METAMORPH_AFTER_SLEEP_MILLIS),
     actorEventsWsUrl: field(z.string().optional(), [
         ACTOR_ENV_VARS.EVENTS_WEBSOCKET_URL,

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/** Why {@link Actor.getInput} could not produce the input. */
+export type ActorInputErrorCode = 
+/** No input record in the default key-value store, and locally no input file in the working directory either. */
+'NOT_FOUND'
+/** Both `<inputKey>` and `<inputKey>.json` exist in the working directory, so neither is picked. */
+ | 'MULTIPLE_FILES'
+/** The secret fields of the input could not be decrypted; `cause` holds the underlying error. */
+ | 'DECRYPTION_FAILED'
+/** A JSON input record or file does not parse; `cause` holds the parser error. */
+ | 'PARSE_FAILED';
+/**
+ * Thrown by {@link Actor.getInput} when the Actor input cannot be produced. `code` says why, and
+ * `cause` carries the underlying error where there is one. Anything else thrown by `getInput()`, such as
+ * an Apify API error, is not an input problem and is passed through as is.
+ *
+ * ```js
+ * try {
+ *     input = await Actor.getInput();
+ * } catch (error) {
+ *     if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;
+ *     input = {};
+ * }
+ * ```
+ */
+export declare class ActorInputError extends Error {
+    readonly name = "ActorInputError";
+    readonly code: ActorInputErrorCode;
+    constructor(code: ActorInputErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+/**
+ * Thrown by {@link Actor.getInput} when the Actor input cannot be produced. `code` says why, and
+ * `cause` carries the underlying error where there is one. Anything else thrown by `getInput()`, such as
+ * an Apify API error, is not an input problem and is passed through as is.
+ *
+ * ```js
+ * try {
+ *     input = await Actor.getInput();
+ * } catch (error) {
+ *     if (!(error instanceof ActorInputError) || error.code !== 'NOT_FOUND') throw error;
+ *     input = {};
+ * }
+ * ```
+ */
+export class ActorInputError extends Error {
+    name = 'ActorInputError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export * from './actor.js';
 export { ApifyStorageBackend, type ApifyStorageBackendOptions } from './apify_storage_backend.js';
+export { ApifyFileSystemStorageBackend, type ApifyFileSystemStorageOptions, } from './apify_file_system_storage_backend.js';
 export type { RequestQueueAccessMode } from './apify_request_queue_backend.js';
 export { ArgumentValidationError } from './utils.js';
+export { ActorInputError, type ActorInputErrorCode } from './errors.js';
 export { createTransformRequestFunction, type GlobInput, type PseudoUrlInput, type UrlPatternFilters, type UrlPatternRequestOptions, } from './enqueue_links_filters.js';
 export type { OpenStorageOptions, StorageAlias, StorageId, StorageName, StorageIdentifier } from './storage.js';
 export { ChargeOptions, ChargeResult, ActorPricingInfo, ChargingManager } from './charging.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './actor.js';
 export { ApifyStorageBackend } from './apify_storage_backend.js';
+export { ApifyFileSystemStorageBackend, } from './apify_file_system_storage_backend.js';
 export { ArgumentValidationError } from './utils.js';
+export { ActorInputError } from './errors.js';
 export { createTransformRequestFunction, } from './enqueue_links_filters.js';
 export { ChargingManager } from './charging.js';
 export * from './configuration.js';

package/dist/utils.d.ts

@@ -5,6 +5,17 @@ export { ArgumentValidationError } from '@apify/validations';
  * @internal
  */
 export declare function isNonEmptyObject(value: unknown): value is Record<string, unknown>;
+/** Content type of a JSON record, as `KeyValueStore` and the file-system adoption write it. */
+export declare const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+/** Content type of raw bytes, which is what a local input file without an extension is adopted as. */
+export declare const BINARY_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Parses a raw input record the way `KeyValueStore.getValue` would, with one exception:
+ * `application/octet-stream` — the type a local input file without an extension is adopted as — is
+ * tried as JSON5 first, so such a file still yields an object. Bytes that do not parse come back as they are.
+ * @internal
+ */
+export declare function parseInputValue(value: Buffer | ArrayBuffer, contentType: string | null): unknown;
 /**
  * Converts a `SNAKE_CASE` string to `camelCase` (previously provided by `@crawlee/utils`).
  * @internal

package/dist/utils.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { type } from 'node:os';
 import { normalize } from 'node:path';
+import { parseValue } from '@crawlee/core';
 // @ts-ignore if we enable resolveJsonModule, we end up with `src` folder in `dist`
 import crawleePkgJson from '@crawlee/core/package.json' with { type: 'json' };
 // @ts-ignore if we enable resolveJsonModule, we end up with `src` folder in `dist`
@@ -21,6 +22,28 @@ const require = createRequire(import.meta.url);
 export function isNonEmptyObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
 }
+/** Content type of a JSON record, as `KeyValueStore` and the file-system adoption write it. */
+export const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+/** Content type of raw bytes, which is what a local input file without an extension is adopted as. */
+export const BINARY_CONTENT_TYPE = 'application/octet-stream';
+/**
+ * Parses a raw input record the way `KeyValueStore.getValue` would, with one exception:
+ * `application/octet-stream` — the type a local input file without an extension is adopted as — is
+ * tried as JSON5 first, so such a file still yields an object. Bytes that do not parse come back as they are.
+ * @internal
+ */
+export function parseInputValue(value, contentType) {
+    const mediaType = contentType?.split(';')[0].trim().toLowerCase();
+    if (mediaType === BINARY_CONTENT_TYPE) {
+        try {
+            return parseValue(value, JSON_CONTENT_TYPE);
+        }
+        catch {
+            return value;
+        }
+    }
+    return parseValue(value, contentType);
+}
 /**
  * Converts a `SNAKE_CASE` string to `camelCase` (previously provided by `@crawlee/utils`).
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify",
-  "version": "4.0.0-beta.39",
+  "version": "4.0.0-beta.41",
   "description": "The scalable web crawling and scraping library for JavaScript/Node.js. Enables development of data extraction and web automation jobs (not only) with headless Chrome and Puppeteer.",
   "engines": {
     "node": ">=22.0.0"
@@ -61,9 +61,10 @@
     "@apify/timeout": "^1.0.1",
     "@apify/utilities": "^3.0.1",
     "@apify/validations": "^1.1.0",
-    "@crawlee/core": ">=4.0.0-beta.194 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
-    "@crawlee/types": ">=4.0.0-beta.194 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
-    "@crawlee/utils": ">=4.0.0-beta.194 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
+    "@crawlee/core": ">=4.0.0-beta.198 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
+    "@crawlee/fs-storage": ">=4.0.0-beta.198 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
+    "@crawlee/types": ">=4.0.0-beta.198 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
+    "@crawlee/utils": ">=4.0.0-beta.198 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
     "apify-client": "^3.0.0-beta.26",
     "minimatch": "^10.2.6",
     "semver": "^7.8.5",
@@ -81,7 +82,7 @@
     "@types/tough-cookie": "^4.0.5",
     "@types/ws": "^8.18.1",
     "commitlint": "^21.2.2",
-    "crawlee": ">=4.0.0-beta.194 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
+    "crawlee": ">=4.0.0-beta.198 <4.0.0-rc.0 || >4.0.0-rc.0 <5.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "oxfmt": "0.64.0",
@@ -97,7 +98,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "10.33.4",
+      "version": "12.6.0",
       "onFail": "warn"
     }
   },