scrapely 1.2.3 → 1.2.4

package/dist/charging.js

@@ -0,0 +1,782 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChargingManager = exports.DEFAULT_DATASET_ITEM_EVENT = exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = exports.APIFY_DEFAULT_DATASET_ITEM_EVENT = exports.ChargeRejectedError = exports.ChargeUncertainError = exports.CHARGE_IDEMPOTENCY_SAFE_AGE_MS = void 0;
+exports.isDefaultDatasetItemEvent = isDefaultDatasetItemEvent;
+exports.resolveDefaultDatasetItemEventName = resolveDefaultDatasetItemEventName;
+exports.hasDefaultDatasetItemEventInPricing = hasDefaultDatasetItemEventInPricing;
+exports.mergeChargeResults = mergeChargeResults;
+exports.pushDataAndCharge = pushDataAndCharge;
+const node_crypto_1 = require("node:crypto");
+/** Client safe-replay window; server TTL is longer (35d). */
+exports.CHARGE_IDEMPOTENCY_SAFE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const PENDING_MAX_ENTRIES = 1024;
+const POST_ATTEMPTS = 3;
+class ChargeUncertainError extends Error {
+    operationId;
+    eventName;
+    count;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'ChargeUncertainError';
+        this.operationId = opts.operationId;
+        this.eventName = opts.eventName;
+        this.count = opts.count;
+    }
+}
+exports.ChargeUncertainError = ChargeUncertainError;
+/** Apify-compatible synthetic event for default-dataset items in pay-per-event actors. */
+/** Definitive platform rejection (402/400/409). Do not retry with the same key. */
+class ChargeRejectedError extends Error {
+    operationId;
+    eventName;
+    count;
+    statusCode;
+    reason;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'ChargeRejectedError';
+        this.operationId = opts.operationId;
+        this.eventName = opts.eventName;
+        this.count = opts.count;
+        this.statusCode = opts.statusCode;
+        this.reason = opts.reason;
+    }
+}
+exports.ChargeRejectedError = ChargeRejectedError;
+exports.APIFY_DEFAULT_DATASET_ITEM_EVENT = 'apify-default-dataset-item';
+/** Scrapely-native synthetic event for default-dataset items. */
+exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = 'scrapely-default-dataset-item';
+/** Apify-compatible alias — imported actors expect this constant name. */
+exports.DEFAULT_DATASET_ITEM_EVENT = exports.APIFY_DEFAULT_DATASET_ITEM_EVENT;
+function isDefaultDatasetItemEvent(eventName) {
+    return eventName === exports.APIFY_DEFAULT_DATASET_ITEM_EVENT || eventName === exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT;
+}
+function resolveDefaultDatasetItemEventName(pricingInfo) {
+    if (exports.APIFY_DEFAULT_DATASET_ITEM_EVENT in pricingInfo) {
+        return exports.APIFY_DEFAULT_DATASET_ITEM_EVENT;
+    }
+    if (exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT in pricingInfo) {
+        return exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT;
+    }
+    return exports.APIFY_DEFAULT_DATASET_ITEM_EVENT;
+}
+function hasDefaultDatasetItemEventInPricing(perEventPrices) {
+    return (exports.APIFY_DEFAULT_DATASET_ITEM_EVENT in perEventPrices ||
+        exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT in perEventPrices);
+}
+/**
+ * Events that must never be POSTed to the charge API (server derives them at settle).
+ * Explicit names only — a prefix heuristic would drop real priced events like `apify-foo`.
+ */
+function isSyntheticEvent(eventName) {
+    return isDefaultDatasetItemEvent(eventName);
+}
+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] ?? oldValue),
+        ])),
+    };
+}
+/**
+ * Pay-per-event charging for platform runs.
+ * Reports charges via POST /v2/actor-runs/:runId/charge (Redis → worker billing).
+ */
+class ChargingManager {
+    configuration;
+    apifyClient;
+    /** Set during actor shutdown; rejects new charge operations after the final flush. */
+    _closed = false;
+    /** @internal Called by Actor shutdown before the final flush. */
+    close() {
+        this._closed = true;
+    }
+    /** @internal Whether shutdown has closed this manager to new charges. */
+    isClosed() {
+        return this._closed;
+    }
+    LOCAL_CHARGING_LOG_DATASET_NAME = 'charging_log';
+    PLATFORM_CHARGING_LOG_DATASET_ID_KEY = 'CHARGING_LOG_DATASET_ID';
+    maxTotalChargeUsd;
+    isAtHome;
+    actorRunId;
+    pricingModel;
+    pricingInfo = {};
+    chargingState;
+    chargingLogDataset;
+    notPpeWarningPrinted = false;
+    /** Unresolved platform POSTs: key = idempotency UUID (never event name). */
+    pendingCharges = new Map();
+    flushInFlight = null;
+    operationTail = Promise.resolve();
+    postAttempts = POST_ATTEMPTS;
+    pendingMaxEntries = PENDING_MAX_ENTRIES;
+    idempotencySafeAgeMs = exports.CHARGE_IDEMPOTENCY_SAFE_AGE_MS;
+    constructor(configuration, apifyClient) {
+        this.configuration = configuration;
+        this.apifyClient = apifyClient;
+        this.maxTotalChargeUsd = configuration.get('maxTotalChargeUsd') || Infinity;
+        this.isAtHome = !!configuration.get('isAtHome');
+        this.actorRunId = configuration.get('actorRunId') || '';
+    }
+    /** @internal Serialize allowance calculation, side effects, and local reservation. */
+    async _withOperationLock(operation) {
+        const previous = this.operationTail;
+        let release;
+        this.operationTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    get isPayPerEvent() {
+        return this.pricingModel === 'PAY_PER_EVENT';
+    }
+    ensureInitialized() {
+        if (this.chargingState === undefined) {
+            throw new Error('ChargingManager is not initialized');
+        }
+    }
+    async fetchPricingInfo() {
+        const actorPricingInfo = this.configuration.get('actorPricingInfo');
+        const chargedEventCounts = this.configuration.get('chargedEventCounts');
+        if (actorPricingInfo && chargedEventCounts) {
+            return {
+                pricingInfo: JSON.parse(actorPricingInfo),
+                chargedEventCounts: JSON.parse(chargedEventCounts),
+                maxTotalChargeUsd: this.configuration.get('maxTotalChargeUsd') || Infinity,
+            };
+        }
+        if (this.isAtHome) {
+            if (!this.actorRunId) {
+                throw new Error('Actor run ID not found even though the Actor is running on the platform');
+            }
+            const run = await this.apifyClient.run(this.actorRunId).get();
+            if (!run) {
+                throw new Error('Actor run not found');
+            }
+            return {
+                pricingInfo: run.pricingInfo,
+                chargedEventCounts: run.chargedEventCounts,
+                maxTotalChargeUsd: run.options?.maxTotalChargeUsd || Infinity,
+            };
+        }
+        return {
+            pricingInfo: undefined,
+            chargedEventCounts: {},
+            maxTotalChargeUsd: this.configuration.get('maxTotalChargeUsd') || Infinity,
+        };
+    }
+    /**
+     * Initialize the ChargingManager by loading pricing information and charging state via platform API.
+     */
+    async init() {
+        const useChargingLogDataset = this.configuration.get('useChargingLogDataset');
+        if (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.get('testPayPerEvent') && this.isAtHome) {
+            throw new Error('Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported in a local development environment');
+        }
+        const { pricingInfo, chargedEventCounts, maxTotalChargeUsd } = await this.fetchPricingInfo();
+        if (this.configuration.get('testPayPerEvent')) {
+            this.pricingModel = 'PAY_PER_EVENT';
+        }
+        else {
+            this.pricingModel ??= pricingInfo?.pricingModel;
+        }
+        if (pricingInfo?.pricingModel === 'PAY_PER_EVENT') {
+            const events = pricingInfo.pricingPerEvent?.actorChargeEvents ?? {};
+            for (const [eventName, eventPricing] of Object.entries(events)) {
+                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 || !useChargingLogDataset) {
+            return;
+        }
+        const { Dataset, KeyValueStore } = await import('@crawlee/core');
+        if (this.isAtHome) {
+            const defaultStore = await KeyValueStore.open();
+            const storedDatasetId = await defaultStore.getValue(this.PLATFORM_CHARGING_LOG_DATASET_ID_KEY);
+            const datasetId = storedDatasetId ??
+                (await (async () => {
+                    const dataset = await this.apifyClient.datasets().getOrCreate();
+                    await defaultStore.setValue(this.PLATFORM_CHARGING_LOG_DATASET_ID_KEY, dataset.id);
+                    return dataset.id;
+                })());
+            this.chargingLogDataset = await Dataset.open(datasetId);
+        }
+        else {
+            if (this.configuration.get('purgeOnStart')) {
+                const dataset = await Dataset.open(this.LOCAL_CHARGING_LOG_DATASET_NAME);
+                await dataset.drop();
+            }
+            this.chargingLogDataset = await Dataset.open(this.LOCAL_CHARGING_LOG_DATASET_NAME);
+        }
+    }
+    getPricingInfo() {
+        if (this.chargingState === undefined) {
+            throw new Error('ChargingManager is not initialized');
+        }
+        return {
+            pricingModel: this.pricingModel,
+            maxTotalChargeUsd: Number.isFinite(this.maxTotalChargeUsd) ? this.maxTotalChargeUsd : Infinity,
+            isPayPerEvent: this.isPayPerEvent,
+            perEventPrices: Object.fromEntries(Object.entries(this.pricingInfo).map(([name, { price }]) => [name, price])),
+        };
+    }
+    getChargedEventCount(eventName) {
+        this.ensureInitialized();
+        if (isDefaultDatasetItemEvent(eventName)) {
+            return ((this.chargingState[exports.APIFY_DEFAULT_DATASET_ITEM_EVENT]?.chargeCount ?? 0) +
+                (this.chargingState[exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT]?.chargeCount ?? 0));
+        }
+        return this.chargingState[eventName]?.chargeCount ?? 0;
+    }
+    getMaxTotalChargeUsd() {
+        this.ensureInitialized();
+        return this.maxTotalChargeUsd;
+    }
+    /**
+     * Helper to calculate how many items can be pushed within charging limits.
+     * Returns the limited items and count to charge.
+     */
+    calculatePushDataLimits(params) {
+        this.ensureInitialized();
+        const { eventName, isDefaultDataset, items } = params;
+        const itemsArray = Array.isArray(items) ? items : [items];
+        if (!this.isPayPerEvent) {
+            return {
+                eventsToCharge: {},
+                limitedItems: itemsArray,
+            };
+        }
+        const defaultDatasetItemEvent = resolveDefaultDatasetItemEventName(this.pricingInfo);
+        const itemPrice = ((eventName !== undefined ? this.calculateEventPrice(eventName) : undefined) ?? 0) +
+            ((isDefaultDataset ? this.calculateEventPrice(defaultDatasetItemEvent) : undefined) ?? 0);
+        const maxChargedCount = itemPrice > 0 ? this.calculateMaxChargesByPrice(itemPrice) : Infinity;
+        // Dataset writes must never exceed the reservable budget. Direct charge()
+        // may preserve its legacy one-event overdraw behavior, but persisting an
+        // item first requires a strict allowance.
+        const itemsToKeep = Math.min(itemsArray.length, maxChargedCount);
+        const eventsToCharge = {};
+        if (eventName !== undefined && itemsToKeep > 0) {
+            eventsToCharge[eventName] = itemsToKeep;
+        }
+        if (isDefaultDataset && itemsToKeep > 0) {
+            eventsToCharge[defaultDatasetItemEvent] = itemsToKeep;
+        }
+        return {
+            limitedItems: itemsToKeep >= itemsArray.length ? itemsArray : itemsArray.slice(0, itemsToKeep),
+            eventsToCharge,
+        };
+    }
+    calculateTotalChargedAmount() {
+        this.ensureInitialized();
+        const result = Object.values(this.chargingState).reduce((sum, item) => sum + item.totalChargedAmount, 0);
+        return Number(result.toFixed(6));
+    }
+    /**
+     * How many events of a given type can still be charged for before reaching the limit;
+     * If the event is not registered, returns Infinity (free of charge)
+     */
+    calculateMaxEventChargeCountWithinLimit(eventName) {
+        this.ensureInitialized();
+        const price = this.calculateEventPrice(eventName);
+        if (!price) {
+            return Infinity;
+        }
+        return this.calculateMaxChargesByPrice(price);
+    }
+    calculateEventPrice(eventName) {
+        if (!this.isAtHome) {
+            return 1;
+        }
+        if (isDefaultDatasetItemEvent(eventName)) {
+            return (this.pricingInfo[exports.APIFY_DEFAULT_DATASET_ITEM_EVENT]?.price ??
+                this.pricingInfo[exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT]?.price);
+        }
+        return this.pricingInfo[eventName]?.price;
+    }
+    getEventPricing(eventName) {
+        const canonicalEventName = isDefaultDatasetItemEvent(eventName)
+            ? resolveDefaultDatasetItemEventName(this.pricingInfo)
+            : eventName;
+        if (this.pricingInfo[canonicalEventName]) {
+            return this.pricingInfo[canonicalEventName];
+        }
+        return {
+            price: this.isAtHome ? 0 : 1,
+            title: `Unknown event '${eventName}'`,
+        };
+    }
+    normalizeChargingEventName(eventName) {
+        if (isDefaultDatasetItemEvent(eventName)) {
+            return resolveDefaultDatasetItemEventName(this.pricingInfo);
+        }
+        return eventName;
+    }
+    calculateMaxChargesByPrice(price) {
+        const unroundedResult = (this.maxTotalChargeUsd - this.calculateTotalChargedAmount()) / price;
+        const roundedResult = Math.floor(Number(unroundedResult.toFixed(4)));
+        return Math.max(0, roundedResult);
+    }
+    getChargeableWithinLimit() {
+        if (Object.keys(this.pricingInfo).length === 0) {
+            return {};
+        }
+        return Object.fromEntries(Object.keys(this.pricingInfo).map((name) => [
+            name,
+            this.calculateMaxEventChargeCountWithinLimit(name),
+        ]));
+    }
+    quarantineStalePending() {
+        const now = Date.now();
+        for (const [key, pending] of this.pendingCharges) {
+            if (now - pending.createdAt > this.idempotencySafeAgeMs) {
+                // Unwind local reservation — dropping without reverse permanently
+                // consumes budget the same way a rejected pending used to.
+                const eventPrice = this.getEventPricing(pending.eventName).price;
+                this.applyAcceptedCount(pending.eventName, pending.count, 0, eventPrice);
+                this.pendingCharges.delete(key);
+                console.error(`[Scrapely] Quarantined stale charge intent past safe idempotency age ` +
+                    `(key=${key} event=${pending.eventName} count=${pending.count}); ` +
+                    `unwound local reservation; will not replay`);
+            }
+        }
+    }
+    /**
+     * POST a charge intent. Returns acceptedCount on success.
+     * Throws ChargeRejectedError for definitive platform rejections (no retry).
+     * Returns null when the outcome is uncertain after retries.
+     */
+    async postChargeWithRetries(intent) {
+        let lastError;
+        for (let attempt = 0; attempt < this.postAttempts; attempt++) {
+            try {
+                const response = await this.apifyClient.run(this.actorRunId).charge({
+                    eventName: intent.eventName,
+                    count: intent.count,
+                    idempotencyKey: intent.idempotencyKey,
+                });
+                const body = extractChargeResponseBody(response);
+                const accepted = readAcceptedCount(body, intent.count);
+                return accepted;
+            }
+            catch (err) {
+                lastError = err;
+                const rejected = classifyChargeHttpError(err, intent);
+                if (rejected) {
+                    throw rejected;
+                }
+                if (attempt + 1 < this.postAttempts) {
+                    await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+                }
+            }
+        }
+        console.warn(`[Scrapely] Failed to record charge for event ${intent.eventName} ` +
+            `(count=${intent.count}, key=${intent.idempotencyKey}): ` +
+            `${lastError?.message ?? lastError}`);
+        return null;
+    }
+    /** Clamp local reservation down when the server accepted fewer events. */
+    /** @internal Used by pushDataAndCharge dual-event reconciliation. */
+    applyAcceptedCount(eventName, reservedCount, acceptedCount, eventPrice) {
+        if (acceptedCount >= reservedCount) {
+            return reservedCount;
+        }
+        const price = eventPrice ?? this.getEventPricing(eventName).price;
+        const delta = reservedCount - acceptedCount;
+        const state = this.chargingState?.[eventName];
+        if (state) {
+            state.chargeCount = Math.max(0, state.chargeCount - delta);
+            state.totalChargedAmount = Math.max(0, state.totalChargedAmount - delta * price);
+        }
+        return Math.max(0, acceptedCount);
+    }
+    /**
+     * Best-effort flush of open charge intents (same keys, no local counter bump).
+     * @returns number of intents confirmed
+     */
+    /**
+     * Best-effort flush of open charge intents under the operation lock.
+     * Drains in batches until empty or deadlineMs elapses.
+     */
+    async flushPending(maxIntents = 32, deadlineMs) {
+        if (!this.actorRunId)
+            return 0;
+        // Serialize with charge/push so concurrent flush cannot double-unwind.
+        return this._withOperationLock(() => this._flushPendingExclusive(maxIntents, deadlineMs));
+    }
+    /** @internal Caller must hold the operation lock. */
+    async _flushPendingExclusive(maxIntents = 32, deadlineMs) {
+        if (!this.actorRunId)
+            return 0;
+        if (this.flushInFlight) {
+            return this.flushInFlight;
+        }
+        const deadline = deadlineMs !== undefined ? Date.now() + Math.max(0, deadlineMs) : undefined;
+        this.flushInFlight = (async () => {
+            let confirmedTotal = 0;
+            // Drain loop: keep flushing batches until empty or deadline.
+            for (;;) {
+                if (deadline !== undefined && Date.now() >= deadline)
+                    break;
+                this.quarantineStalePending();
+                if (this.pendingCharges.size === 0)
+                    break;
+                const snapshot = [...this.pendingCharges.values()].slice(0, Math.max(0, maxIntents));
+                if (snapshot.length === 0)
+                    break;
+                let confirmed = 0;
+                for (const intent of snapshot) {
+                    if (deadline !== undefined && Date.now() >= deadline)
+                        break;
+                    try {
+                        const accepted = await this.postChargeWithRetries(intent);
+                        if (accepted !== null) {
+                            const eventPrice = this.getEventPricing(intent.eventName).price;
+                            this.applyAcceptedCount(intent.eventName, intent.count, accepted, eventPrice);
+                            this.pendingCharges.delete(intent.idempotencyKey);
+                            confirmed += 1;
+                        }
+                    }
+                    catch (err) {
+                        if (err instanceof ChargeRejectedError) {
+                            const eventPrice = this.getEventPricing(intent.eventName).price;
+                            this.applyAcceptedCount(intent.eventName, intent.count, 0, eventPrice);
+                            this.pendingCharges.delete(intent.idempotencyKey);
+                            console.warn(`[Scrapely] Dropping rejected pending charge ` +
+                                `(event=${intent.eventName} key=${intent.idempotencyKey}): ${err.message}`);
+                        }
+                        else {
+                            throw err;
+                        }
+                    }
+                }
+                confirmedTotal += confirmed;
+                // No progress and still pending → stop to avoid tight loop on uncertain.
+                if (confirmed === 0)
+                    break;
+            }
+            return confirmedTotal;
+        })();
+        try {
+            return await this.flushInFlight;
+        }
+        finally {
+            this.flushInFlight = null;
+        }
+    }
+    async charge({ eventName, count = 1 }) {
+        return this._withOperationLock(() => this._chargeExclusive({ eventName, count }));
+    }
+    /** @internal Caller must hold the operation lock. */
+    async _chargeExclusive({ eventName, count = 1 }) {
+        if (this._closed) {
+            throw new Error('ChargingManager is closed (actor is shutting down); charge rejected');
+        }
+        const calculateChargeableWithinLimit = () => this.getChargeableWithinLimit();
+        const normalizedEventName = this.chargingState === undefined ? eventName : this.normalizeChargingEventName(eventName);
+        if (!this.isPayPerEvent) {
+            if (!this.notPpeWarningPrinted) {
+                console.warn('[Scrapely] Ignored attempt to charge for an event - the Actor does not use the pay-per-event pricing');
+                this.notPpeWarningPrinted = true;
+            }
+            return {
+                eventChargeLimitReached: false,
+                chargedCount: 0,
+                chargeableWithinLimit: this.chargingState === undefined ? {} : calculateChargeableWithinLimit(),
+            };
+        }
+        this.ensureInitialized();
+        if (!Number.isInteger(count) || count < 1) {
+            throw new Error('count must be a positive integer');
+        }
+        try {
+            // Already under operation lock — call exclusive path (no re-enter lock).
+            await this._flushPendingExclusive();
+        }
+        catch (err) {
+            console.warn(`[Scrapely] flushPending before charge failed: ${err.message}`);
+        }
+        const maxEventChargeCount = this.calculateMaxEventChargeCountWithinLimit(normalizedEventName);
+        let chargedCount = (() => {
+            if (count <= maxEventChargeCount) {
+                return count;
+            }
+            if (this.calculateTotalChargedAmount() <= this.maxTotalChargeUsd) {
+                return maxEventChargeCount + 1;
+            }
+            return 0;
+        })();
+        if (chargedCount === 0) {
+            return {
+                eventChargeLimitReached: count > 0,
+                chargedCount: 0,
+                chargeableWithinLimit: calculateChargeableWithinLimit(),
+            };
+        }
+        const eventPricing = this.getEventPricing(normalizedEventName);
+        const canPost = this.isAtHome &&
+            !!this.actorRunId &&
+            !isSyntheticEvent(normalizedEventName) &&
+            this.pricingInfo[normalizedEventName] !== undefined;
+        let intent;
+        if (canPost) {
+            if (this.pendingCharges.size >= this.pendingMaxEntries) {
+                console.warn(`[Scrapely] Too many unresolved charge intents (${this.pendingCharges.size}); ` +
+                    `refusing new billable charge for event ${normalizedEventName}`);
+                return {
+                    eventChargeLimitReached: false,
+                    chargedCount: 0,
+                    chargeableWithinLimit: calculateChargeableWithinLimit(),
+                };
+            }
+            intent = {
+                idempotencyKey: (0, node_crypto_1.randomUUID)(),
+                eventName: normalizedEventName,
+                count: chargedCount,
+                createdAt: Date.now(),
+            };
+            this.pendingCharges.set(intent.idempotencyKey, intent);
+        }
+        // Reserve local budget once per logical operation (no rollback on POST failure).
+        this.chargingState[normalizedEventName] ??= { chargeCount: 0, totalChargedAmount: 0 };
+        this.chargingState[normalizedEventName].chargeCount += chargedCount;
+        this.chargingState[normalizedEventName].totalChargedAmount += chargedCount * eventPricing.price;
+        if (canPost && intent) {
+            let accepted;
+            try {
+                accepted = await this.postChargeWithRetries(intent);
+            }
+            catch (err) {
+                if (err instanceof ChargeRejectedError) {
+                    // Server definitively rejected: unwind local reservation.
+                    this.pendingCharges.delete(intent.idempotencyKey);
+                    chargedCount = this.applyAcceptedCount(normalizedEventName, chargedCount, 0, eventPricing.price);
+                    return {
+                        eventChargeLimitReached: true,
+                        chargedCount: 0,
+                        chargeableWithinLimit: calculateChargeableWithinLimit(),
+                    };
+                }
+                throw err;
+            }
+            if (accepted !== null) {
+                this.pendingCharges.delete(intent.idempotencyKey);
+                chargedCount = this.applyAcceptedCount(normalizedEventName, chargedCount, accepted, eventPricing.price);
+            }
+            else {
+                throw new ChargeUncertainError(`Charge for event '${normalizedEventName}' (count=${chargedCount}) was not confirmed by the platform; operationId=${intent.idempotencyKey}`, {
+                    operationId: intent.idempotencyKey,
+                    eventName: normalizedEventName,
+                    count: chargedCount,
+                });
+            }
+        }
+        else if (this.isAtHome &&
+            !isSyntheticEvent(normalizedEventName) &&
+            this.pricingInfo[normalizedEventName] === undefined) {
+            console.warn(`[Scrapely] Attempting to charge for an unknown event '${normalizedEventName}'`);
+        }
+        if (this.chargingLogDataset !== undefined) {
+            await this.chargingLogDataset.pushData({
+                eventName: normalizedEventName,
+                eventTitle: eventPricing.title,
+                eventPriceUsd: eventPricing.price,
+                chargedCount,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        if (chargedCount < count) {
+            const subject = count === 1 ? 'instance' : 'instances';
+            console.log(`[Scrapely] Charging ${count} ${subject} of '${normalizedEventName}' event would exceed maxTotalChargeUsd - only ${chargedCount} events were charged`);
+        }
+        return {
+            eventChargeLimitReached: this.calculateMaxEventChargeCountWithinLimit(normalizedEventName) <= 0,
+            chargedCount,
+            chargeableWithinLimit: calculateChargeableWithinLimit(),
+        };
+    }
+}
+exports.ChargingManager = ChargingManager;
+/**
+ * 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
+ */
+function extractChargeResponseBody(response) {
+    if (!response || typeof response !== 'object')
+        return {};
+    const r = response;
+    // apify-client httpClient.call returns { data, statusCode, ... }
+    if (r.data && typeof r.data === 'object' && !Array.isArray(r.data)) {
+        return r.data;
+    }
+    return r;
+}
+function readAcceptedCount(body, fallback) {
+    const raw = body.acceptedCount;
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) {
+        return Math.floor(raw);
+    }
+    return fallback;
+}
+function classifyChargeHttpError(err, intent) {
+    const status = err?.statusCode ??
+        err?.status ??
+        err?.response?.statusCode ??
+        err?.response?.status;
+    // Definitive client/billing/auth outcomes — do not retry.
+    // 401/403: ownership or scoped-run authorization failures are permanent for this key.
+    if (status === 400 ||
+        status === 401 ||
+        status === 402 ||
+        status === 403 ||
+        status === 404 ||
+        status === 405 ||
+        status === 409) {
+        return new ChargeRejectedError(`Charge rejected by platform (HTTP ${status}) for event '${intent.eventName}'`, {
+            operationId: intent.idempotencyKey,
+            eventName: intent.eventName,
+            count: intent.count,
+            statusCode: status,
+            reason: status === 402 ? 'charge-limit-exceeded' : `http-${status}`,
+        });
+    }
+    const message = String(err?.message ?? err ?? '');
+    if (/charge-limit-exceeded|unknown-event|ledger-sealed|invalid-input|conflict/i.test(message)) {
+        return new ChargeRejectedError(message, {
+            operationId: intent.idempotencyKey,
+            eventName: intent.eventName,
+            count: intent.count,
+            statusCode: status,
+            reason: 'message-match',
+        });
+    }
+    return null;
+}
+async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultDataset, pushFn, }) {
+    return chargingManager._withOperationLock(async () => {
+        if (chargingManager.isClosed()) {
+            throw new Error('ChargingManager is closed (actor is shutting down); charge rejected');
+        }
+        const { limitedItems, eventsToCharge } = chargingManager.calculatePushDataLimits({
+            items,
+            eventName,
+            isDefaultDataset,
+        });
+        const itemsArray = Array.isArray(items) ? items : [items];
+        const allItemsTrimmed = itemsArray.length > 0 && limitedItems.length === 0;
+        if (limitedItems.length === 0) {
+            return {
+                eventChargeLimitReached: allItemsTrimmed,
+                chargedCount: 0,
+                chargeableWithinLimit: {},
+            };
+        }
+        // Charge BEFORE persisting so a server cap/reject cannot leave unbilled
+        // items in the dataset. Operation lock is held across both steps.
+        let chargeResult;
+        if (Object.keys(eventsToCharge).length > 0) {
+            const results = [];
+            // Synthetic/default-dataset events first (local-only); then explicit.
+            const ordered = Object.entries(eventsToCharge).sort(([a], [b]) => {
+                const aSyn = isSyntheticEvent(a) ? 0 : 1;
+                const bSyn = isSyntheticEvent(b) ? 0 : 1;
+                return aSyn - bSyn;
+            });
+            const reservedInOp = [];
+            try {
+                for (const [name, chargeCount] of ordered) {
+                    const r = await chargingManager._chargeExclusive({
+                        eventName: name,
+                        count: chargeCount,
+                    });
+                    results.push(r);
+                    reservedInOp.push({ name, reserved: r.chargedCount });
+                }
+            }
+            catch (err) {
+                // Uncertain/failure after partial multi-event reserve: unwind all
+                // prior reservations for this operation (synthetic + explicit).
+                for (const { name, reserved } of reservedInOp) {
+                    if (reserved > 0) {
+                        chargingManager.applyAcceptedCount(name, reserved, 0);
+                    }
+                }
+                throw err;
+            }
+            // Persist only what every charged event accepted.
+            // When multiple events are charged for the same items, use the
+            // minimum accepted count so storage never exceeds any billable event.
+            const acceptedForItems = Math.min(limitedItems.length, ...results.map((r) => r.chargedCount));
+            // Unwind any event that reserved more than we will persist.
+            // Critical for synthetic default-dataset (local-only): if the
+            // explicit server charge caps below the synthetic reservation,
+            // leaving the synthetic count high permanently overstates local spend.
+            for (let i = 0; i < ordered.length; i++) {
+                const [name] = ordered[i];
+                const reserved = results[i].chargedCount;
+                if (reserved > acceptedForItems) {
+                    chargingManager.applyAcceptedCount(name, reserved, acceptedForItems);
+                    results[i] = {
+                        ...results[i],
+                        chargedCount: acceptedForItems,
+                        eventChargeLimitReached: true,
+                    };
+                }
+            }
+            chargeResult = results.reduce(mergeChargeResults);
+            if (acceptedForItems <= 0) {
+                return {
+                    eventChargeLimitReached: true,
+                    chargedCount: chargeResult.chargedCount,
+                    chargeableWithinLimit: chargeResult.chargeableWithinLimit,
+                };
+            }
+            const toPersist = limitedItems.slice(0, acceptedForItems);
+            try {
+                await pushFn(Array.isArray(items) ? toPersist : toPersist[0]);
+            }
+            catch (pushErr) {
+                // Charge already accepted server-side; storage failed. Do not unwind
+                // server ledger (no reverse API). Surface error so caller can retry
+                // storage; local counters already match accepted charges.
+                console.error(`[Scrapely] Dataset push failed after charge accepted ` +
+                    `(items=${acceptedForItems}): ${pushErr.message}`);
+                throw pushErr;
+            }
+            return chargeResult;
+        }
+        // No billable events — still persist the budget-limited items.
+        await pushFn(Array.isArray(items) ? limitedItems : limitedItems[0]);
+        return {
+            eventChargeLimitReached: false,
+            chargedCount: 0,
+            chargeableWithinLimit: {},
+        };
+    });
+}