scrapely 1.2.33 → 1.2.34

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.34] - 2026-10-19
+
+- Initial public release.

package/NOTICE

@@ -1,26 +1,12 @@
-Scrapely SDK for JavaScript/TypeScript (npm package "scrapely")
-===============================================================
-
-Copyright (c) 2025-2026 TeraShift GmbH (Scrape.ly).
-
-This package is licensed under the ISC License (see LICENSE), except for
-the files listed below, which are derived from apify-sdk-js
-(https://github.com/apify/apify-sdk-js),
-Copyright Apify Technologies s.r.o., licensed under the Apache License,
-Version 2.0 (see LICENSE-APACHE). Those files have been modified by
-TeraShift GmbH and remain under the Apache License, Version 2.0:
-
-  - src/actor.ts (from src/actor.ts)
-  - src/charging.ts (from src/charging.ts)
-  - src/scrapely-proxy-configuration.ts (from src/proxy_configuration.ts)
-
-You may obtain a copy of the Apache License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-This product includes software developed by Apify Technologies s.r.o.
-(https://apify.com/). The original source code is available at
-https://github.com/apify/apify-sdk-js.
-
-Scrape.ly is not affiliated with Apify. Apify is a trademark of
-Apify Technologies s.r.o.
+scrapely
+Copyright (c) 2025-2026 TeraShift GmbH (Scrape.ly)
+
+Licensed under the ISC License (see LICENSE), except for the files below,
+which are derived from apify-sdk-js (https://github.com/apify/apify-sdk-js),
+Copyright Apify Technologies s.r.o., and remain under the Apache License,
+Version 2.0 (see LICENSE-APACHE). They have been modified by TeraShift GmbH:
+
+  - src/actor.ts
+  - src/charging.ts
+  - src/configuration.ts
+  - src/scrapely-proxy-configuration.ts

package/README.md

@@ -62,6 +62,5 @@ On the platform, browser crawlers connect to a remote Chromium over CDP instead
 
 ## License
 
-ISC (see [LICENSE](./LICENSE)), except for a few files derived from the Apache-2.0 licensed
-[apify-sdk-js](https://github.com/apify/apify-sdk-js), which stay under the Apache License 2.0
+ISC (see [LICENSE](./LICENSE)), except for a few files that stay under the Apache License 2.0
 (see [LICENSE-APACHE](./LICENSE-APACHE) and [NOTICE](./NOTICE)).

package/dist/actor.d.ts

@@ -1,6 +1,6 @@
 import './log-env.js';
 import { EventEmitter } from 'node:events';
-/** Actor permission level - matches Apify's ACTOR_PERMISSION_LEVEL enum */
+/** Actor permission level. */
 export declare enum ACTOR_PERMISSION_LEVEL {
     /** User has no special permissions */
     NONE = "NONE",
@@ -44,20 +44,20 @@ import { createProxyConfiguration, type CreateProxyConfigurationOptions } from '
 import { type BrowserConfiguration, type BrowserConfigurationOptions } from './browser-configuration.js';
 import { type Clearance, type SolveOptions, type SolverVendorStatus } from './solver.js';
 import type { Dataset, KeyValueStore, RequestQueue } from 'crawlee';
-/** User function passed to {@link Actor.main} (Apify-compatible). */
+/** User function passed to {@link Actor.main}. */
 export type UserFunc<T = unknown> = () => T | Promise<T>;
 type Dictionary = Record<string, any>;
-/** Value types returned by {@link Actor.getInput} (Apify-compatible). */
+/** Value types returned by {@link Actor.getInput}. */
 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). */
+/** 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).
+ * Exit codes for the Actor process.
  * Must be in the range 1-128 to avoid collision with signal exits.
  */
 export declare const EXIT_CODES: {
@@ -161,7 +161,7 @@ export interface WebhookOptions {
     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 */
+    /** If true, indicates the webhook is a platform integration */
     isApifyIntegration?: boolean;
 }
 /**
@@ -184,7 +184,7 @@ export interface UseStateOptions {
     config?: any;
 }
 /**
- * Options for Actor.openDataset(), openKeyValueStore(), and openRequestQueue() (Apify-compatible).
+ * Options for Actor.openDataset(), openKeyValueStore(), and openRequestQueue().
  */
 export interface OpenStorageOptions {
     /**
@@ -217,12 +217,11 @@ export interface RebootOptions {
     /** @internal */
     customAfterSleepMillis?: number;
 }
-/** Result of a charge operation (Apify-compatible). */
+/** Result of a charge operation. */
 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) */
@@ -275,7 +274,7 @@ export interface ApifyEnv {
     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) */
+    /** If set to "1", running on the platform (APIFY_IS_AT_HOME) */
     isAtHome: string | null;
     /** Local storage directory (CRAWLEE_STORAGE_DIR) */
     localStorageDir: string | null;
@@ -337,10 +336,10 @@ export declare class Actor {
     private _apifyClient;
     private readonly chargingManager;
     /**
-     * Creates an Actor instance (Apify SDK-compatible alternative to static helpers).
+     * Creates an Actor instance (alternative to the static helpers).
      */
     constructor(options?: ConfigurationOptions);
-    /** Default ApifyClient instance for this Actor (Apify-compatible instance accessor). */
+    /** Default ApifyClient instance for this Actor (instance accessor). */
     get apifyClient(): ApifyClient;
     private _ensureInit;
     private static _actorConfig;
@@ -540,12 +539,12 @@ export declare class Actor {
      */
     static get isPaying(): boolean;
     /**
-     * Public URL of the Apify API. May be used to interact with the platform programmatically.
+     * Public URL of the platform 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].
+     * Alias for process.env[key].
      */
     static getenv(key: string): string | undefined;
     on(event: EventTypeName | 'cpuInfo', listener: (...args: any[]) => void): void;
@@ -639,12 +638,12 @@ export declare class Actor {
     /** @internal */
     private static _instance;
     /**
-     * Get the default Actor instance (singleton pattern for Apify SDK compatibility).
+     * Get the default Actor instance (singleton).
      * @returns The default Actor instance
      */
     static getDefaultInstance(): Actor;
     /**
-     * Default Configuration instance (Apify-compatible static accessor).
+     * Default Configuration instance (static accessor).
      * Used after Actor.init() without new Actor(), e.g. Actor.config.get('standbyPort').
      */
     static get config(): Configuration;
@@ -653,7 +652,7 @@ export declare class Actor {
      */
     static get apifyClient(): ApifyClient;
     /**
-     * Returns a new Apify API client pointed at the Scrapely platform.
+     * Returns a new API client (ApifyClient) pointed at the Scrapely platform.
      */
     newClient(options?: {
         token?: string;
@@ -663,7 +662,7 @@ export declare class Actor {
         token?: string;
         baseUrl?: string;
     }): ApifyClient;
-    /** Apify-compatible instance API — delegates to {@link Actor.charge}. */
+    /** 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).
@@ -673,7 +672,7 @@ export declare class Actor {
     getChargingManager(): ChargingManager;
     /**
      * Metamorph the current actor run into a run of another actor.
-     * This follows Apify's metamorph behavior:
+     * 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)
@@ -714,8 +713,6 @@ export declare class Actor {
      * 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>;
@@ -729,12 +726,12 @@ export declare class Actor {
     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).
+     * Runs an Actor on the platform and waits for it to finish (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).
+     * Runs an Actor task on the platform and waits for it to finish (instance API).
      */
     callTask(taskId: string, input?: Dictionary, options?: CallTaskOptions): Promise<ActorRun>;
     static callTask(taskId: string, input?: Dictionary, options?: CallTaskOptions): Promise<ActorRun>;
@@ -763,11 +760,21 @@ export declare class Actor {
     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.
+     * Utility namespace.
+     * Provides helper functions like enqueueLinks that accept the v2-style call signature.
      */
     static readonly utils: {
         enqueueLinks: typeof import("./utils.js").enqueueLinks;
+        requestAsBrowser: typeof import("./utils.js").requestAsBrowser;
+        getRandomUserAgent: typeof import("./utils.js").getRandomUserAgent;
+        sleep: (millis?: number) => any;
+        downloadListOfUrls: (options: any) => any;
+        extractUrls: (options: any) => any;
+        htmlToText: (html: any) => any;
+        isDocker: (forceReset?: boolean) => any;
+        readonly log: any;
+        readonly puppeteer: any;
+        readonly playwright: any;
     };
 }
 /** Resolves once stdout and stderr have flushed their buffers, or after `maxMs`. */

package/dist/actor.js

@@ -8,7 +8,7 @@ exports.waitForStdioDrain = waitForStdioDrain;
 // Modified by TeraShift GmbH. See LICENSE-APACHE and NOTICE.
 require("./log-env.js");
 const node_events_1 = require("node:events");
-/** Actor permission level - matches Apify's ACTOR_PERMISSION_LEVEL enum */
+/** Actor permission level. */
 var ACTOR_PERMISSION_LEVEL;
 (function (ACTOR_PERMISSION_LEVEL) {
     /** User has no special permissions */
@@ -57,7 +57,7 @@ const gracefulShutdownHandlers = {};
  */
 const signalExitHandlers = {};
 /**
- * Exit codes for the Actor process (Apify-compatible).
+ * Exit codes for the Actor process.
  * Must be in the range 1-128 to avoid collision with signal exits.
  */
 exports.EXIT_CODES = {
@@ -116,7 +116,7 @@ class Actor {
     _apifyClient;
     chargingManager;
     /**
-     * Creates an Actor instance (Apify SDK-compatible alternative to static helpers).
+     * Creates an Actor instance (alternative to the static helpers).
      */
     constructor(options = {}) {
         this.config =
@@ -124,7 +124,7 @@ class Actor {
         this.chargingManager = new charging_js_1.ChargingManager(this.config, () => this.apifyClient);
         Actor._instance ??= this;
     }
-    /** Default ApifyClient instance for this Actor (Apify-compatible instance accessor). */
+    /** Default ApifyClient instance for this Actor (instance accessor). */
     get apifyClient() {
         this._apifyClient ??= this.newClient();
         return this._apifyClient;
@@ -407,7 +407,7 @@ class Actor {
         const timeoutSecs = opts.timeoutSecs ?? 30;
         const shouldExit = opts.exit ?? true;
         Actor._ensureActorInit('exit');
-        // Apify parity: the exit/fail message becomes the run's terminal status
+        // The exit/fail message becomes the run's terminal status
         // message. Stored before teardown, while the run and process are alive.
         if (opts.statusMessage)
             await Actor._persistTerminalStatusMessage(opts.statusMessage, code);
@@ -427,7 +427,7 @@ class Actor {
     }
     static async getInput() {
         Actor._ensureActorInit('getInput');
-        // Check for metamorph input first (Apify-compatible)
+        // Check for metamorph input first
         // When an actor is metamorphed, the input is stored under INPUT-METAMORPH-{n}
         const metamorphCount = process.env.ACTOR_METAMORPH_COUNT;
         if (metamorphCount) {
@@ -545,6 +545,7 @@ class Actor {
                     chargePer: opts.chargePer ?? 'row',
                     isDefaultDataset,
                     pushFn: async (rows) => { await dataset.pushData(rows); },
+                    validateItems: await crawleeItemValidator(),
                 });
             }
             if (opts.chargePer !== undefined && opts.chargePer !== 'row')
@@ -565,10 +566,11 @@ class Actor {
                 eventName: opts.eventName,
                 isDefaultDataset: false,
                 pushFn: async (rows) => { await dataset.pushData(rows); },
+                validateItems: await crawleeItemValidator(),
             });
         }
         const eventName = eventNameOrOptions;
-        // Exact synthetic names only — prefix would block real priced events like apify-foo.
+        // Exact synthetic names only — prefix would block real priced events.
         if (eventName === 'apify-default-dataset-item' ||
             eventName === 'scrapely-default-dataset-item') {
             throw new Error(`Cannot charge for synthetic event '${eventName}' manually`);
@@ -623,6 +625,7 @@ class Actor {
             eventName: explicitEventName,
             isDefaultDataset,
             pushFn: async (limitedItems) => dataset.pushData(limitedItems),
+            validateItems: await crawleeItemValidator(),
         });
     }
     static async getValue(key) {
@@ -833,7 +836,7 @@ class Actor {
             return value === '1' ? 1 : null;
         };
         return {
-            // Apify-compatible fields (in alphabetical order as per Apify interface)
+            // Fields in alphabetical order
             actorId: env.ACTOR_ID || null,
             actorBuildId: env.ACTOR_BUILD_ID || null,
             actorBuildNumber: env.ACTOR_BUILD_NUMBER || null,
@@ -947,14 +950,14 @@ class Actor {
         return Actor._actorConfig().get('userIsPaying') === true;
     }
     /**
-     * Public URL of the Apify API. May be used to interact with the platform programmatically.
+     * Public URL of the platform API. May be used to interact with the platform programmatically.
      */
     static get apiPublicBaseUrl() {
         return Actor._actorConfig().get('apiPublicBaseUrl') || undefined;
     }
     /**
      * Get a single environment variable value by name.
-     * This is an Apify SDK-compatible alias for process.env[key].
+     * Alias for process.env[key].
      */
     static getenv(key) {
         return process.env[key];
@@ -1243,7 +1246,7 @@ class Actor {
     /** @internal */
     static _instance;
     /**
-     * Get the default Actor instance (singleton pattern for Apify SDK compatibility).
+     * Get the default Actor instance (singleton).
      * @returns The default Actor instance
      */
     static getDefaultInstance() {
@@ -1251,7 +1254,7 @@ class Actor {
         return Actor._instance;
     }
     /**
-     * Default Configuration instance (Apify-compatible static accessor).
+     * Default Configuration instance (static accessor).
      * Used after Actor.init() without new Actor(), e.g. Actor.config.get('standbyPort').
      */
     static get config() {
@@ -1264,7 +1267,7 @@ class Actor {
         return Actor.getDefaultInstance().apifyClient;
     }
     /**
-     * Returns a new Apify API client pointed at the Scrapely platform.
+     * Returns a new API client (ApifyClient) pointed at the Scrapely platform.
      */
     newClient(options) {
         const config = this.config;
@@ -1290,7 +1293,7 @@ class Actor {
     static newClient(options) {
         return Actor.getDefaultInstance().newClient(options);
     }
-    /** Apify-compatible instance API — delegates to {@link Actor.charge}. */
+    /** Instance API — delegates to {@link Actor.charge}. */
     async charge(options, count) {
         return Actor.charge(options, count);
     }
@@ -1310,7 +1313,7 @@ class Actor {
     }
     /**
      * Metamorph the current actor run into a run of another actor.
-     * This follows Apify's metamorph behavior:
+     * 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)
@@ -1424,8 +1427,6 @@ class Actor {
      * on a new server. Any state persisted via Actor.useState() will be
      * automatically restored.
      *
-     * This is an Apify-compatible method.
-     *
      * @param options - Reboot options
      */
     static async reboot(options) {
@@ -1468,7 +1469,7 @@ class Actor {
         catch (err) {
             console.warn(`[Scrapely] flushPending during reboot failed: ${err.message}`);
         }
-        // Exit so the worker can restart the container (Apify-compatible).
+        // Exit so the worker can restart the container.
         process.exit(0);
     }
     /**
@@ -1512,7 +1513,7 @@ class Actor {
         });
     }
     /**
-     * Runs an Actor on the platform and waits for it to finish (Apify-compatible instance API).
+     * Runs an Actor on the platform and waits for it to finish (instance API).
      */
     async call(actorId, input, options = {}) {
         return Actor.call(actorId, input, options);
@@ -1524,7 +1525,7 @@ class Actor {
         return client.actor(actorId).call(input, { ...rest, timeout });
     }
     /**
-     * Runs an Actor task on the platform and waits for it to finish (Apify-compatible instance API).
+     * Runs an Actor task on the platform and waits for it to finish (instance API).
      */
     async callTask(taskId, input, options = {}) {
         return Actor.callTask(taskId, input, options);
@@ -1542,7 +1543,7 @@ class Actor {
         return client.actor(actorId).start(input, { ...rest, timeout });
     }
     // -------------------------------------------------------------------------
-    // Apify-compatible instance API (mirrors static methods on Actor class)
+    // Instance API (mirrors static methods on Actor class)
     // -------------------------------------------------------------------------
     async main(userFunc, options) {
         return Actor.main(userFunc, options);
@@ -1633,8 +1634,8 @@ class Actor {
         });
     }
     /**
-     * Apify v2-compatible utility namespace.
-     * Provides helper functions like enqueueLinks that accept the Apify v2 API signature.
+     * Utility namespace.
+     * Provides helper functions like enqueueLinks that accept the v2-style call signature.
      */
     static utils = utils_js_1.utils;
 }
@@ -1658,3 +1659,18 @@ async function waitForStdioDrain(maxMs, streams = [process.stdout, process.stder
     if (timer)
         clearTimeout(timer);
 }
+/**
+ * Crawlee's own item rules (an object, serializable, at most ~9 MB), checked
+ * before a charge: Dataset.pushData would refuse such an item only after it
+ * was charged. Undefined when this crawlee version does not export the check.
+ */
+async function crawleeItemValidator() {
+    const core = (await import('@crawlee/core'));
+    const check = core.checkAndSerialize;
+    if (typeof check !== 'function')
+        return undefined;
+    // Same limit as Dataset.pushData (MAX_PAYLOAD_SIZE_BYTES minus its 0.01% safety buffer).
+    const max = 9 * 1024 * 1024;
+    const limit = max - Math.ceil(max * 0.0001);
+    return (items) => items.forEach((item, index) => check(item, limit, index));
+}

package/dist/charging.d.ts

@@ -13,7 +13,7 @@ export declare class ChargeUncertainError extends Error {
         count: number;
     });
 }
-/** Apify-compatible synthetic event for default-dataset items in pay-per-event actors. */
+/** Synthetic event for default-dataset items in pay-per-event actors. */
 /** Definitive platform rejection (402/400/409). Do not retry with the same key. */
 export declare class ChargeRejectedError extends Error {
     readonly operationId: string;
@@ -43,7 +43,7 @@ export declare function refuseDefaultDatasetPush(itemCount: number): boolean;
 export declare const APIFY_DEFAULT_DATASET_ITEM_EVENT = "apify-default-dataset-item";
 /** Scrapely-native synthetic event for default-dataset items. */
 export declare const SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = "scrapely-default-dataset-item";
-/** Apify-compatible alias — imported actors expect this constant name. */
+/** Alias — imported actors expect this constant name. */
 export declare const DEFAULT_DATASET_ITEM_EVENT = "apify-default-dataset-item";
 export declare function isDefaultDatasetItemEvent(eventName: string): boolean;
 export declare function resolveDefaultDatasetItemEventName(pricingInfo: Record<string, unknown>): string;
@@ -169,8 +169,23 @@ export declare class ChargingManager {
     private lastAcceptedOperationId;
     /** Voids not yet confirmed by the platform; retried before the next push and at exit. */
     private pendingVoids;
+    /**
+     * @internal Platform charges for results that were not stored and that the
+     * platform definitively refused to void (event -> count). They stay billed,
+     * so the next push of that event uses them instead of charging again.
+     */
+    _voidRefusedCredit: Record<string, number>;
     /** Unresolved platform POSTs: key = idempotency UUID (never event name). */
     private readonly pendingCharges;
+    /**
+     * Record in the run's default key-value store that mirrors pendingCharges,
+     * so a container crash does not lose them: settlement re-applies them under
+     * their own idempotency keys. One record per container, so a restarted
+     * container never overwrites its predecessor's.
+     */
+    private readonly pendingRecordKey;
+    /** Intent keys last written to that record ('' = nothing written / empty). */
+    private persistedPendingSig;
     private flushInFlight;
     private operationTail;
     private readonly postAttempts;
@@ -248,6 +263,11 @@ export declare class ChargingManager {
     private postChargeWithRetries;
     /** @internal Idempotency key of the charge accepted by the last _chargeExclusive call, if any. */
     _takeLastAcceptedOperationId(): string | undefined;
+    /**
+     * @internal Mirror the unconfirmed charges to the run's default key-value
+     * store (best effort, only when the set changed since the last write).
+     */
+    _persistPendingCharges(): Promise<void>;
     /**
      * @internal Reverse an accepted charge whose items were never stored
      * (POST /v2/actor-runs/:runId/charge/void), then unwind the local
@@ -260,6 +280,21 @@ export declare class ChargingManager {
      * means it never applied.
      */
     _cancelUncertainCharge(eventName: string, operationId: string, reservedCount: number): Promise<boolean>;
+    /**
+     * @internal Void (or cancel, when unconfirmed) a whole charge and say what
+     * happened: 'voided' (confirmed, local reservation released), 'stands' (a
+     * definitive answer that it cannot be voided) or 'unknown' (queued for retry,
+     * reservation kept).
+     */
+    _voidOutcome(eventName: string, operationId: string, reservedCount: number, uncertain: boolean): Promise<'voided' | 'stands' | 'unknown'>;
+    /** @internal A charge for `count` unstored results stands (void refused): keep it as credit. */
+    _noteUnvoidable(eventName: string, count: number): void;
+    /** @internal Use credit for a whole charge of `count` events (all or nothing); returns the count used. */
+    _takeVoidCredit(eventName: string, count: number): number;
+    /** @internal */
+    _returnVoidCredit(eventName: string, count: number): void;
+    /** @internal Void (or cancel) a charge for results that were not stored; a refused void becomes credit. */
+    _voidOrCredit(eventName: string, operationId: string, reservedCount: number, uncertain: boolean): Promise<'voided' | 'stands' | 'unknown'>;
     _voidCharge(eventName: string, operationId: string, reservedCount: number, notFoundMeansVoided?: boolean, deadline?: number): Promise<boolean>;
     /**
      * @internal Retry unconfirmed voids (caller holds the operation lock).
@@ -284,12 +319,20 @@ export declare class ChargingManager {
     /** @internal Caller must hold the operation lock. */
     _chargeExclusive({ eventName, count }: ChargeOptions): Promise<ChargeResult>;
 }
-export declare function pushDataAndCharge<T>({ chargingManager, items, eventName, isDefaultDataset, pushFn, }: {
+/**
+ * @internal Fail before anything is charged when an item cannot be serialized
+ * for the dataset (circular reference, BigInt, a bare function or undefined):
+ * the push would otherwise fail after the charge, with nothing stored.
+ */
+export declare function assertItemsSerializable(items: unknown[]): void;
+export declare function pushDataAndCharge<T>({ chargingManager, items, eventName, isDefaultDataset, pushFn, validateItems, }: {
     chargingManager: ChargingManager;
     items: T | T[];
     eventName: string | undefined;
     isDefaultDataset: boolean;
     pushFn: (limitedItems: T | T[]) => Promise<void>;
+    /** Extra checks the storage would make after the charge (e.g. crawlee's object / size rules). */
+    validateItems?: (items: T[]) => void;
 }): Promise<ChargeResult>;
 /** Validate `{ eventName: eventsPerRow }` for a multi-event push. */
 export declare function validateRowCharges(charges: unknown): Record<string, number>;
@@ -301,7 +344,7 @@ export declare function validateRowCharges(charges: unknown): Record<string, num
  * the rows that are kept, so no row is stored part-paid and no event is billed
  * for a row that was not stored. Unpriced events are ignored.
  */
-export declare function pushDataWithCharges<T>({ chargingManager, items, charges, isDefaultDataset, pushFn, chargePer, }: {
+export declare function pushDataWithCharges<T>({ chargingManager, items, charges, isDefaultDataset, pushFn, chargePer, validateItems, }: {
     chargingManager: ChargingManager;
     items: T | T[];
     charges: Record<string, number>;
@@ -309,6 +352,8 @@ export declare function pushDataWithCharges<T>({ chargingManager, items, charges
     pushFn: (rows: T | T[]) => Promise<void>;
     /** 'batch': charge `charges` once for the whole push; all rows stored if accepted, none if refused. */
     chargePer?: 'row' | 'batch';
+    /** Extra checks the storage would make after the charge (e.g. crawlee's object / size rules). */
+    validateItems?: (items: T[]) => void;
 }): Promise<ChargeResult>;
 /**
  * @internal True when a dataset push certainly stored nothing: the storage API