apify 4.0.0-beta.12 → 4.0.0-beta.13

package/dist/apify_storage_client.d.ts

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { CreateDatasetClientOptions, CreateKeyValueStoreClientOptions, CreateRequestQueueClientOptions, DatasetClient, KeyValueStoreClient, RequestQueueClient, StorageClient } from '@crawlee/types';
+import type { ApifyClient } from 'apify-client';
+import { type ChargeResult, type ChargingManager } from './charging.js';
+import type { Configuration } from './configuration.js';
+type StorageType = 'Dataset' | 'KeyValueStore' | 'RequestQueue';
+/** Marks a dataset client whose `pushItems` charges for pay-per-event. @internal */
+export declare const USES_PUSH_DATA_INTERCEPTION: unique symbol;
+/**
+ * Context of a single `Actor.pushData()` call, shared with the intercepted
+ * `pushItems()` calls so they can (1) know which event to charge and
+ * (2) aggregate the {@link ChargeResult} across the multiple `pushItems()`
+ * calls a single `pushData()` may trigger (Crawlee batches large pushes).
+ */
+export interface PpeAwarePushDataContext {
+    eventName: string | undefined;
+    chargeResult?: ChargeResult;
+}
+export declare const pushDataChargingContext: AsyncLocalStorage<PpeAwarePushDataContext>;
+/**
+ * Bridges `apify-client`'s synchronous resource accessors (`dataset(id)`,
+ * `keyValueStore(id)`, `requestQueue(id, options?)`) to crawlee v4's
+ * `StorageClient` interface (async factory methods accepting either an `id`
+ * or a `name`).
+ *
+ * For the run's default dataset it transparently swaps in a charging-aware
+ * dataset client (pay-per-event on `Actor.pushData()`), provided a charging
+ * manager is supplied and a default-dataset-item price is configured.
+ *
+ * `storageExists()` lets `Dataset.open(idOrName)` resolve a string to an id
+ * first (when one exists on the platform) and fall back to a name otherwise —
+ * otherwise crawlee's `resolveStorageIdentifier` treats every string as a name
+ * and the SDK would silently create a new storage named like the passed id.
+ */
+export declare class ApifyStorageClient implements StorageClient {
+    private readonly client;
+    private readonly config?;
+    private readonly getChargingManager?;
+    constructor(client: ApifyClient, config?: Configuration | undefined, getChargingManager?: (() => ChargingManager) | undefined);
+    storageExists(id: string, type: StorageType): Promise<boolean>;
+    createDatasetClient(options?: CreateDatasetClientOptions): Promise<DatasetClient>;
+    createKeyValueStoreClient(options?: CreateKeyValueStoreClientOptions): Promise<KeyValueStoreClient>;
+    createRequestQueueClient(options?: CreateRequestQueueClientOptions): Promise<RequestQueueClient>;
+    /**
+     * Returns a charging-aware dataset client when `id` is the run's default
+     * dataset and a default-dataset-item price is configured; otherwise
+     * `undefined` (caller uses the plain client).
+     */
+    private chargingDatasetClient;
+    private resolveId;
+    private resourceClient;
+    private collectionClient;
+}
+export {};

package/dist/apify_storage_client.js

@@ -0,0 +1,152 @@
+/* eslint-disable max-classes-per-file */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { DatasetClient as ApifyDatasetClient } from 'apify-client';
+import { DEFAULT_DATASET_ITEM_EVENT, mergeChargeResults, pushDataAndCharge, } from './charging.js';
+const DEFAULT_ID_CONFIG_KEY = {
+    Dataset: 'defaultDatasetId',
+    KeyValueStore: 'defaultKeyValueStoreId',
+    RequestQueue: 'defaultRequestQueueId',
+};
+/** Marks a dataset client whose `pushItems` charges for pay-per-event. @internal */
+export const USES_PUSH_DATA_INTERCEPTION = Symbol('apify:uses-push-data-interception');
+export const pushDataChargingContext = new AsyncLocalStorage();
+/**
+ * Default `DatasetClient` that charges for pushed items (pay-per-event). Used
+ * only for the run's default dataset when a `apify-default-dataset-item` price
+ * is configured; for everything else the plain `apify-client` dataset client is
+ * used.
+ */
+class PpeAwareDatasetClient extends ApifyDatasetClient {
+    getChargingManager;
+    constructor(options, getChargingManager) {
+        super(options);
+        this.getChargingManager = getChargingManager;
+    }
+    normalizeItems(items) {
+        if (typeof items === 'string') {
+            const parsed = JSON.parse(items);
+            return Array.isArray(parsed) ? parsed : [parsed];
+        }
+        if (Array.isArray(items)) {
+            return items.flatMap((item) => typeof item === 'string' ? JSON.parse(item) : item);
+        }
+        return [items];
+    }
+    async pushItems(items) {
+        const context = pushDataChargingContext.getStore();
+        // A single JSON string may encode multiple items (e.g. '[{...},{...}]'),
+        // which the charging logic would miscount — parse strings into arrays so
+        // each logical item is counted individually.
+        const normalizedItems = this.normalizeItems(items);
+        const result = await pushDataAndCharge({
+            chargingManager: this.getChargingManager(),
+            items: normalizedItems,
+            eventName: context?.eventName,
+            isDefaultDataset: true,
+            // stringify for faster validation in the Apify client
+            pushFn: async (limitedItems) => super.pushItems(JSON.stringify(limitedItems)),
+        });
+        if (!context)
+            return;
+        // One `Actor.pushData()` may map to several `pushItems()` calls — aggregate.
+        context.chargeResult =
+            context.chargeResult === undefined ? result : mergeChargeResults(context.chargeResult, result);
+    }
+}
+/**
+ * Bridges `apify-client`'s synchronous resource accessors (`dataset(id)`,
+ * `keyValueStore(id)`, `requestQueue(id, options?)`) to crawlee v4's
+ * `StorageClient` interface (async factory methods accepting either an `id`
+ * or a `name`).
+ *
+ * For the run's default dataset it transparently swaps in a charging-aware
+ * dataset client (pay-per-event on `Actor.pushData()`), provided a charging
+ * manager is supplied and a default-dataset-item price is configured.
+ *
+ * `storageExists()` lets `Dataset.open(idOrName)` resolve a string to an id
+ * first (when one exists on the platform) and fall back to a name otherwise —
+ * otherwise crawlee's `resolveStorageIdentifier` treats every string as a name
+ * and the SDK would silently create a new storage named like the passed id.
+ */
+export class ApifyStorageClient {
+    client;
+    config;
+    getChargingManager;
+    constructor(client, config, getChargingManager) {
+        this.client = client;
+        this.config = config;
+        this.getChargingManager = getChargingManager;
+    }
+    async storageExists(id, type) {
+        // Apify's `GET /v2/{kind}/{idOrName}` matches by either id or name;
+        // confirm it was an *id* match so crawlee can fall through to `{ name }`.
+        const info = await this.resourceClient(id, type).get();
+        return info?.id === id;
+    }
+    async createDatasetClient(options) {
+        const id = await this.resolveId(options, 'Dataset');
+        const datasetClient = this.chargingDatasetClient(id) ?? this.client.dataset(id);
+        // apify-client's resource clients overlap with `@crawlee/types`' shapes
+        // but don't implement the v4-added members (`getMetadata`,
+        // `getRecordPublicUrl`), so cast through.
+        return datasetClient;
+    }
+    async createKeyValueStoreClient(options) {
+        const id = await this.resolveId(options, 'KeyValueStore');
+        return this.client.keyValueStore(id);
+    }
+    async createRequestQueueClient(options) {
+        const id = await this.resolveId(options, 'RequestQueue');
+        return this.client.requestQueue(id, options?.clientKey ? { clientKey: options.clientKey } : undefined);
+    }
+    /**
+     * Returns a charging-aware dataset client when `id` is the run's default
+     * dataset and a default-dataset-item price is configured; otherwise
+     * `undefined` (caller uses the plain client).
+     */
+    chargingDatasetClient(id) {
+        const { getChargingManager } = this;
+        if (!getChargingManager)
+            return undefined;
+        if (id !== this.config?.defaultDatasetId)
+            return undefined;
+        const hasDefaultDatasetItemEvent = DEFAULT_DATASET_ITEM_EVENT in getChargingManager().getPricingInfo().perEventPrices;
+        if (!hasDefaultDatasetItemEvent)
+            return undefined;
+        const datasetClient = new PpeAwareDatasetClient({
+            id,
+            baseUrl: this.client.baseUrl,
+            publicBaseUrl: this.client.publicBaseUrl,
+            apifyClient: this.client,
+            httpClient: this.client.httpClient,
+        }, getChargingManager);
+        Object.assign(datasetClient, {
+            [USES_PUSH_DATA_INTERCEPTION]: true,
+        });
+        return datasetClient;
+    }
+    async resolveId(options, type) {
+        if (options?.id)
+            return options.id;
+        if (options?.name) {
+            return (await this.collectionClient(type).getOrCreate(options.name)).id;
+        }
+        // No id/name (crawlee's `__default__` alias): use the default storage
+        // id from the run's environment. apify-client rejects an empty id.
+        return this.config?.[DEFAULT_ID_CONFIG_KEY[type]] ?? '';
+    }
+    resourceClient(id, type) {
+        if (type === 'Dataset')
+            return this.client.dataset(id);
+        if (type === 'KeyValueStore')
+            return this.client.keyValueStore(id);
+        return this.client.requestQueue(id);
+    }
+    collectionClient(type) {
+        if (type === 'Dataset')
+            return this.client.datasets();
+        if (type === 'KeyValueStore')
+            return this.client.keyValueStores();
+        return this.client.requestQueues();
+    }
+}

package/dist/charging.d.ts

@@ -1,5 +1,6 @@
 import type { ActorRunPricingInfo, ApifyClient } from 'apify-client';
 import type { Configuration } from './configuration.js';
+export declare const DEFAULT_DATASET_ITEM_EVENT = "apify-default-dataset-item";
 export interface ChargeOptions {
     /**
      * The name of the event type to charge for.
@@ -48,10 +49,12 @@ export interface ActorPricingInfo {
     isPayPerEvent: boolean;
     perEventPrices: Record<string, number>;
 }
+export declare function mergeChargeResults(a: ChargeResult, b: ChargeResult): ChargeResult;
 /**
  * Handles pay-per-event charging.
  */
 export declare class ChargingManager {
+    private configuration;
     private readonly LOCAL_CHARGING_LOG_DATASET_NAME;
     private readonly PLATFORM_CHARGING_LOG_DATASET_ID_KEY;
     private maxTotalChargeUsd;
@@ -67,6 +70,7 @@ export declare class ChargingManager {
     private apifyClient;
     constructor(configuration: Configuration, apifyClient: ApifyClient);
     private get isPayPerEvent();
+    private fetchPricingInfo;
     /**
      * Initialize the ChargingManager by loading pricing information and charging state via Apify API.
      */
@@ -82,9 +86,17 @@ export declare class ChargingManager {
      * This method attempts to charge for the specified number of events, but may charge fewer
      * if doing so would exceed the total budget limit (`maxTotalChargeUsd`).
      *
+     * **Important:** When using the `count` parameter to charge for multiple events at once,
+     * be aware that the charge may be partially fulfilled, i.e. `chargedCount` can be less
+     * than the requested `count`. Always check the returned `chargedCount` to know how many
+     * events were actually charged, and only perform that much work. If your work is
+     * meaningfully divisible into individual units, prefer calling `charge()` once per unit
+     * rather than batching via `count` — this gives finer control over budget consumption
+     * and avoids situations where more work is requested than the budget allows.
+     *
      * @param options The name of the event to charge for and the number of events to be charged.
      */
-    charge({ eventName, count, }: ChargeOptions): Promise<ChargeResult>;
+    charge({ eventName, count }: ChargeOptions): Promise<ChargeResult>;
     /**
      * Get the number of events with given name that the Actor has charged for so far.
      */
@@ -99,5 +111,34 @@ export declare class ChargingManager {
      * If the event is not registered, returns Infinity (free of charge)
      */
     calculateMaxEventChargeCountWithinLimit(eventName: string): number;
+    private calculateEventPrice;
+    private calculateMaxChargesByPrice;
+    /**
+     * Helper to calculate how many items can be pushed within charging limits.
+     * Returns the limited items and count to charge.
+     */
+    calculatePushDataLimits<T>({ items, eventName, isDefaultDataset, }: {
+        items: T | T[];
+        eventName: string | undefined;
+        isDefaultDataset: boolean;
+    }): {
+        limitedItems: T[];
+        eventsToCharge: Record<string, number>;
+    };
 }
-//# sourceMappingURL=charging.d.ts.map
+/**
+ * Helper for PPE-aware pushing of data to the dataset.
+ *
+ * 1. Calculate limits based on budget
+ * 2. Push limited items via the provided callback
+ * 3. Charge for the events
+ *
+ * @internal
+ */
+export declare function pushDataAndCharge<T>({ chargingManager, items, eventName, isDefaultDataset, pushFn, }: {
+    chargingManager: ChargingManager;
+    items: T | T[];
+    eventName: string | undefined;
+    isDefaultDataset: boolean;
+    pushFn: (limitedItems: T | T[]) => Promise<void>;
+}): Promise<ChargeResult>;

package/dist/charging.js

@@ -1,9 +1,21 @@
 import { Dataset, KeyValueStore } from '@crawlee/core';
 import log from '@apify/log';
+export const DEFAULT_DATASET_ITEM_EVENT = 'apify-default-dataset-item';
+export function mergeChargeResults(a, b) {
+    return {
+        eventChargeLimitReached: a.eventChargeLimitReached || b.eventChargeLimitReached,
+        chargedCount: a.chargedCount + b.chargedCount,
+        chargeableWithinLimit: Object.fromEntries(Object.entries(a.chargeableWithinLimit).map(([key, oldValue]) => [
+            key,
+            Math.min(oldValue, b.chargeableWithinLimit[key]),
+        ])),
+    };
+}
 /**
  * Handles pay-per-event charging.
  */
 export class ChargingManager {
+    configuration;
     LOCAL_CHARGING_LOG_DATASET_NAME = 'charging_log';
     PLATFORM_CHARGING_LOG_DATASET_ID_KEY = 'CHARGING_LOG_DATASET_ID';
     maxTotalChargeUsd;
@@ -18,32 +30,25 @@ export class ChargingManager {
     chargingLogDataset;
     apifyClient;
     constructor(configuration, apifyClient) {
-        this.maxTotalChargeUsd =
-            configuration.get('maxTotalChargeUsd') || Infinity; // convert `0` to `Infinity` in case the value is an empty string
-        this.isAtHome = configuration.get('isAtHome');
-        this.actorRunId = configuration.get('actorRunId');
-        this.purgeChargingLogDataset = configuration.get('purgeOnStart');
-        this.useChargingLogDataset = configuration.get('useChargingLogDataset');
-        if (this.useChargingLogDataset && this.isAtHome) {
-            throw new Error('Using the ACTOR_USE_CHARGING_LOG_DATASET environment variable is only supported in a local development environment');
-        }
-        if (configuration.get('testPayPerEvent')) {
-            if (this.isAtHome) {
-                throw new Error('Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported in a local development environment');
-            }
-            this.pricingModel = 'PAY_PER_EVENT';
-        }
+        this.configuration = configuration;
+        this.maxTotalChargeUsd = configuration.maxTotalChargeUsd || Infinity; // convert `0` to `Infinity` in case the value is an empty string
+        this.isAtHome = configuration.isAtHome;
+        this.actorRunId = configuration.actorRunId;
+        this.purgeChargingLogDataset = configuration.purgeOnStart;
+        this.useChargingLogDataset = configuration.useChargingLogDataset;
         this.apifyClient = apifyClient;
     }
     get isPayPerEvent() {
         return this.pricingModel === 'PAY_PER_EVENT';
     }
-    /**
-     * Initialize the ChargingManager by loading pricing information and charging state via Apify API.
-     */
-    async init() {
-        this.chargingState = {};
-        // Retrieve pricing information
+    async fetchPricingInfo() {
+        if (this.configuration.actorPricingInfo && this.configuration.chargedEventCounts) {
+            return {
+                pricingInfo: JSON.parse(this.configuration.actorPricingInfo),
+                chargedEventCounts: JSON.parse(this.configuration.chargedEventCounts),
+                maxTotalChargeUsd: this.configuration.maxTotalChargeUsd || Infinity,
+            };
+        }
         if (this.isAtHome) {
             if (this.actorRunId === undefined) {
                 throw new Error('Actor run ID not found even though the Actor is running on Apify');
@@ -52,25 +57,55 @@ export class ChargingManager {
             if (run === undefined) {
                 throw new Error('Actor run not found');
             }
-            this.pricingModel = run.pricingInfo?.pricingModel;
-            // Load per-event pricing information
-            if (run.pricingInfo?.pricingModel === 'PAY_PER_EVENT') {
-                for (const [eventName, eventPricing] of Object.entries(run.pricingInfo.pricingPerEvent.actorChargeEvents)) {
-                    this.pricingInfo[eventName] = {
-                        price: eventPricing.eventPriceUsd,
-                        title: eventPricing.eventTitle,
-                    };
-                }
-                this.maxTotalChargeUsd =
-                    run.options.maxTotalChargeUsd ?? this.maxTotalChargeUsd;
+            return {
+                pricingInfo: run.pricingInfo,
+                chargedEventCounts: run.chargedEventCounts,
+                maxTotalChargeUsd: run.options.maxTotalChargeUsd || Infinity,
+            };
+        }
+        return {
+            pricingInfo: undefined,
+            chargedEventCounts: {},
+            maxTotalChargeUsd: this.configuration.maxTotalChargeUsd || Infinity,
+        };
+    }
+    /**
+     * Initialize the ChargingManager by loading pricing information and charging state via Apify API.
+     */
+    async init() {
+        // Validate config - it may have changed since the instantiation
+        if (this.useChargingLogDataset && this.isAtHome) {
+            throw new Error('Using the ACTOR_USE_CHARGING_LOG_DATASET environment variable is only supported in a local development environment');
+        }
+        if (this.configuration.testPayPerEvent) {
+            if (this.isAtHome) {
+                throw new Error('Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported in a local development environment');
             }
-            // Load charged event counts
-            for (const [eventName, chargeCount] of Object.entries(run.chargedEventCounts ?? {})) {
-                this.chargingState[eventName] = {
-                    chargeCount,
-                    totalChargedAmount: chargeCount * (this.pricingInfo[eventName]?.price ?? 0),
+        }
+        // Retrieve pricing information
+        const { pricingInfo, chargedEventCounts, maxTotalChargeUsd } = await this.fetchPricingInfo();
+        if (this.configuration.testPayPerEvent) {
+            this.pricingModel = 'PAY_PER_EVENT';
+        }
+        else {
+            this.pricingModel ??= pricingInfo?.pricingModel;
+        }
+        // Load per-event pricing information
+        if (pricingInfo?.pricingModel === 'PAY_PER_EVENT') {
+            for (const [eventName, eventPricing] of Object.entries(pricingInfo.pricingPerEvent.actorChargeEvents)) {
+                this.pricingInfo[eventName] = {
+                    price: eventPricing.eventPriceUsd,
+                    title: eventPricing.eventTitle,
                 };
             }
+            this.maxTotalChargeUsd = maxTotalChargeUsd;
+        }
+        this.chargingState = {};
+        for (const [eventName, chargeCount] of Object.entries(chargedEventCounts ?? {})) {
+            this.chargingState[eventName] = {
+                chargeCount,
+                totalChargedAmount: chargeCount * (this.pricingInfo[eventName]?.price ?? 0),
+            };
         }
         if (!this.isPayPerEvent || !this.useChargingLogDataset) {
             return;
@@ -118,13 +153,18 @@ export class ChargingManager {
      * This method attempts to charge for the specified number of events, but may charge fewer
      * if doing so would exceed the total budget limit (`maxTotalChargeUsd`).
      *
+     * **Important:** When using the `count` parameter to charge for multiple events at once,
+     * be aware that the charge may be partially fulfilled, i.e. `chargedCount` can be less
+     * than the requested `count`. Always check the returned `chargedCount` to know how many
+     * events were actually charged, and only perform that much work. If your work is
+     * meaningfully divisible into individual units, prefer calling `charge()` once per unit
+     * rather than batching via `count` — this gives finer control over budget consumption
+     * and avoids situations where more work is requested than the budget allows.
+     *
      * @param options The name of the event to charge for and the number of events to be charged.
      */
-    async charge({ eventName, count = 1, }) {
-        const calculateChargeableWithinLimit = () => Object.fromEntries(Object.keys(this.pricingInfo).map((name) => [
-            name,
-            this.calculateMaxEventChargeCountWithinLimit(name),
-        ]));
+    async charge({ eventName, count = 1 }) {
+        const calculateChargeableWithinLimit = () => Object.fromEntries(Object.keys(this.pricingInfo).map((name) => [name, this.calculateMaxEventChargeCountWithinLimit(name)]));
         if (!this.isPayPerEvent) {
             if (!this.notPpeWarningPrinted) {
                 log.warning('Ignored attempt to charge for an event - the Actor does not use the pay-per-event pricing');
@@ -140,7 +180,19 @@ export class ChargingManager {
             throw new Error('ChargingManager is not initialized');
         }
         /* START OF CRITICAL SECTION - no awaits here */
-        const chargedCount = Math.min(count, this.calculateMaxEventChargeCountWithinLimit(eventName));
+        const maxEventChargeCount = this.calculateMaxEventChargeCountWithinLimit(eventName);
+        const chargedCount = (() => {
+            if (count <= maxEventChargeCount) {
+                return count;
+            }
+            // If the caller tries to charge more than the budget allows, overcharge by one event
+            // so that the Actor is detected by the platform and terminated.
+            // But don't do this if already strictly over the budget - no point piling on charges.
+            if (this.calculateTotalChargedAmount() <= this.maxTotalChargeUsd) {
+                return maxEventChargeCount + 1;
+            }
+            return 0;
+        })();
         if (chargedCount === 0) {
             return {
                 eventChargeLimitReached: count > 0, // Only true if user wanted to charge but couldn't
@@ -157,14 +209,15 @@ export class ChargingManager {
             totalChargedAmount: 0,
         };
         this.chargingState[eventName].chargeCount += chargedCount;
-        this.chargingState[eventName].totalChargedAmount +=
-            chargedCount * pricingInfo.price;
+        this.chargingState[eventName].totalChargedAmount += chargedCount * pricingInfo.price;
         /* END OF CRITICAL SECTION */
         if (this.isAtHome) {
-            if (this.pricingInfo[eventName] !== undefined) {
-                await this.apifyClient
-                    .run(this.actorRunId)
-                    .charge({ eventName, count: chargedCount });
+            if (eventName.startsWith('apify-')) {
+                // Synthetic events (e.g. apify-default-dataset-item) are tracked locally only,
+                // the platform handles them automatically based on dataset writes.
+            }
+            else if (this.pricingInfo[eventName] !== undefined) {
+                await this.apifyClient.run(this.actorRunId).charge({ eventName, count: chargedCount });
             }
             else {
                 log.warning(`Attempting to charge for an unknown event '${eventName}'`);
@@ -226,14 +279,103 @@ export class ChargingManager {
         if (this.chargingState === undefined) {
             throw new Error('ChargingManager is not initialized');
         }
-        const price = this.isAtHome ? this.pricingInfo[eventName].price : 1; // Use a nonzero price for local development so that the maximum budget can be reached
+        const price = this.calculateEventPrice(eventName);
         if (!price) {
             return Infinity;
         }
+        return this.calculateMaxChargesByPrice(price);
+    }
+    calculateEventPrice(eventName) {
+        return this.isAtHome ? this.pricingInfo[eventName]?.price : 1; // Use a nonzero price for local development so that the maximum budget can be reached
+    }
+    calculateMaxChargesByPrice(price) {
+        // The raw number of events allowed by the budget
+        const unroundedResult = (this.maxTotalChargeUsd - this.calculateTotalChargedAmount()) / price;
         // First round as Math.floor(4.9999999999999999) will incorrectly return 5
-        return Math.floor(Number(((this.maxTotalChargeUsd -
-            this.calculateTotalChargedAmount()) /
-            price).toFixed(4)));
+        const roundedResult = Math.floor(Number(unroundedResult.toFixed(4)));
+        return Math.max(0, roundedResult);
+    }
+    /**
+     * Helper to calculate how many items can be pushed within charging limits.
+     * Returns the limited items and count to charge.
+     */
+    calculatePushDataLimits({ items, eventName, isDefaultDataset, }) {
+        if (this.chargingState === undefined) {
+            throw new Error('ChargingManager is not initialized');
+        }
+        const itemsArray = Array.isArray(items) ? items : [items];
+        if (!this.isPayPerEvent) {
+            return {
+                limitedItems: itemsArray,
+                eventsToCharge: {},
+            };
+        }
+        const itemPrice = ((eventName !== undefined ? this.calculateEventPrice(eventName) : undefined) ?? 0) +
+            ((isDefaultDataset ? this.calculateEventPrice(DEFAULT_DATASET_ITEM_EVENT) : undefined) ?? 0);
+        const maxChargedCount = itemPrice > 0 ? this.calculateMaxChargesByPrice(itemPrice) : Infinity;
+        const itemsToKeep = (() => {
+            if (maxChargedCount >= itemsArray.length) {
+                return itemsArray.length;
+            }
+            // If the caller tries to push items even though the limit is depleted, overcharge by one
+            // so that the Platform terminates the run.
+            // But don't do this if already strictly over the budget - no point piling on charges.
+            if (itemsArray.length > 0 &&
+                maxChargedCount === 0 &&
+                this.calculateTotalChargedAmount() <= this.maxTotalChargeUsd) {
+                return 1;
+            }
+            return maxChargedCount;
+        })();
+        const eventsToCharge = {};
+        if (eventName !== undefined && itemsToKeep > 0) {
+            eventsToCharge[eventName] = itemsToKeep;
+        }
+        if (isDefaultDataset && itemsToKeep > 0) {
+            eventsToCharge[DEFAULT_DATASET_ITEM_EVENT] = itemsToKeep;
+        }
+        return {
+            limitedItems: itemsToKeep >= itemsArray.length ? itemsArray : itemsArray.slice(0, itemsToKeep),
+            eventsToCharge,
+        };
+    }
+}
+/**
+ * Helper for PPE-aware pushing of data to the dataset.
+ *
+ * 1. Calculate limits based on budget
+ * 2. Push limited items via the provided callback
+ * 3. Charge for the events
+ *
+ * @internal
+ */
+export async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultDataset, pushFn, }) {
+    const { limitedItems, eventsToCharge } = chargingManager.calculatePushDataLimits({
+        items,
+        eventName,
+        isDefaultDataset,
+    });
+    if (limitedItems.length > 0) {
+        // Preserve original call shape for single items
+        await pushFn(Array.isArray(items) ? limitedItems : limitedItems[0]);
+    }
+    if (Object.keys(eventsToCharge).length > 0) {
+        const results = {};
+        await Promise.all(Object.entries(eventsToCharge).map(async ([name, count]) => {
+            results[name] = await chargingManager.charge({
+                eventName: name,
+                count,
+            });
+        }));
+        // Merge all charge results so that eventChargeLimitReached reflects
+        // whether ANY of the charged events hit their limit.
+        return Object.values(results).reduce(mergeChargeResults);
     }
+    const itemsArray = Array.isArray(items) ? items : [items];
+    const allItemsTrimmed = itemsArray.length > 0 && limitedItems.length === 0;
+    return {
+        eventChargeLimitReached: allItemsTrimmed,
+        chargedCount: 0,
+        chargeableWithinLimit: {},
+    };
 }
-//# sourceMappingURL=charging.js.map