scrapely-python 0.1.0__py3-none-any.whl

scrapely/charging.py

@@ -0,0 +1,1143 @@
+"""
+Charging manager for pay-per-event pricing.
+
+Each charge() call is one logical operation with a unique Idempotency-Key.
+Failed POSTs keep a pending intent for flush/retry; later charge() calls are
+never treated as retries of a previous operation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from decimal import Decimal
+from threading import RLock
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+from .pricing_types import (
+    ActorPricingInfoResult,
+    ChargeResult,
+    PayPerEventActorPricingInfo,
+    PricingModel,
+    PricingPerEvent,
+)
+
+if TYPE_CHECKING:
+    from .configuration import Configuration
+    from .storage.api_client import ApiClient
+
+logger = logging.getLogger(__name__)
+
+# Apify-compatible synthetic event for default-dataset items in pay-per-event actors.
+APIFY_DEFAULT_DATASET_ITEM_EVENT = 'apify-default-dataset-item'
+
+# Scrapely-native synthetic event for default-dataset items.
+SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = 'scrapely-default-dataset-item'
+
+# Apify-compatible alias — imported actors expect this constant name.
+DEFAULT_DATASET_ITEM_EVENT = APIFY_DEFAULT_DATASET_ITEM_EVENT
+
+# Must stay below server CHARGE_IDEMPOTENCY_TTL (35d). Do not replay past this age.
+CHARGE_IDEMPOTENCY_SAFE_AGE_SECS = 30 * 24 * 60 * 60
+
+# Soft cap on open unresolved intents. Refuse NEW billable charges when full.
+_PENDING_MAX_ENTRIES = 1024
+
+# Immediate same-key POST attempts before leaving intent pending / raising.
+_POST_ATTEMPTS = 3
+
+# Local-only dataset collecting one entry per logical charge operation
+# (JS ChargingManager LOCAL_CHARGING_LOG_DATASET_NAME parity).
+LOCAL_CHARGING_LOG_DATASET_NAME = 'charging_log'
+
+
+def is_default_dataset_item_event(event_name: str) -> bool:
+    """Check if event name is a default dataset item event."""
+    return event_name in (APIFY_DEFAULT_DATASET_ITEM_EVENT, SCRAPELY_DEFAULT_DATASET_ITEM_EVENT)
+
+
+def resolve_default_dataset_item_event_name(pricing_info: dict) -> str:
+    """Resolve the default dataset item event name from pricing info."""
+    if APIFY_DEFAULT_DATASET_ITEM_EVENT in pricing_info:
+        return APIFY_DEFAULT_DATASET_ITEM_EVENT
+    if SCRAPELY_DEFAULT_DATASET_ITEM_EVENT in pricing_info:
+        return SCRAPELY_DEFAULT_DATASET_ITEM_EVENT
+    return APIFY_DEFAULT_DATASET_ITEM_EVENT
+
+
+def has_default_dataset_item_event_in_pricing(per_event_prices: dict) -> bool:
+    """Check if default dataset item event pricing is configured."""
+    return (
+        APIFY_DEFAULT_DATASET_ITEM_EVENT in per_event_prices or
+        SCRAPELY_DEFAULT_DATASET_ITEM_EVENT in per_event_prices
+    )
+
+
+# Backwards-compatible alias for the pre-rename camelCase name.
+# Deprecated — use ``has_default_dataset_item_event_in_pricing`` instead.
+hasDefaultDatasetItemEventInPricing = has_default_dataset_item_event_in_pricing
+
+
+def merge_charge_results(a: ChargeResult, b: ChargeResult) -> ChargeResult:
+    """Merge two :class:`ChargeResult` objects (Node SDK ``mergeChargeResults`` parity).
+
+    Sums charged counts, ORs the limit-reached flag, and keeps the most
+    restrictive remaining-limit per event type.
+    """
+    def _min_optional(x: Optional[int], y: Optional[int]) -> Optional[int]:
+        # None means "no limit known" — the least restrictive value.
+        if x is None:
+            return y
+        if y is None:
+            return x
+        return min(x, y)
+
+    merged_limits: Dict[str, Optional[int]] = {
+        key: _min_optional(value, b.chargeable_within_limit.get(key, value))
+        for key, value in a.chargeable_within_limit.items()
+    }
+    return ChargeResult(
+        event_charge_limit_reached=a.event_charge_limit_reached or b.event_charge_limit_reached,
+        charged_count=a.charged_count + b.charged_count,
+        chargeable_within_limit=merged_limits,
+    )
+
+
+class ChargeUncertainError(Exception):
+    """Raised when a charge POST could not be confirmed after retries.
+
+    Local budget still reserves the count for this operation. The intent remains
+    pending for later flush with the same Idempotency-Key. Do not assume the
+    platform did or did not apply the charge.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation_id: str,
+        event_name: str,
+        count: int,
+    ) -> None:
+        super().__init__(message)
+        self.operation_id = operation_id
+        self.event_name = event_name
+        self.count = count
+
+
+class ChargeRejectedError(Exception):
+    """Definitive platform rejection (402/400/409). Do not retry with the same key."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation_id: str,
+        event_name: str,
+        count: int,
+        status_code: Optional[int] = None,
+        reason: str = 'rejected',
+    ) -> None:
+        super().__init__(message)
+        self.operation_id = operation_id
+        self.event_name = event_name
+        self.count = count
+        self.status_code = status_code
+        self.reason = reason
+
+
+class ChargingManager:
+    """Manages charging for pay-per-event Actors.
+
+    Tracks event counts and enforces spending limits.
+    Provides fine-grained access to pay-per-event functionality.
+    """
+
+    _PENDING_MAX_ENTRIES = _PENDING_MAX_ENTRIES
+    _IDEMPOTENCY_SAFE_AGE_SECS = CHARGE_IDEMPOTENCY_SAFE_AGE_SECS
+    _POST_ATTEMPTS = _POST_ATTEMPTS
+
+    def __init__(self, config: 'Configuration', client: 'ApiClient'):
+        """Initialize the charging manager.
+
+        Args:
+            config: Configuration instance
+            client: API client for making charge requests
+        """
+        self._config = config
+        # Optional in practice: guards treat a missing client as "cannot bill".
+        self._client: Optional['ApiClient'] = client
+        self._pricing_info: Optional[PayPerEventActorPricingInfo] = None
+        self._charged_events: Dict[str, int] = {}
+        self._max_total_charge_usd: Optional[Decimal] = None
+        self._total_charged_usd: Decimal = Decimal('0.0')
+        self._charge_lock = RLock()
+        self._flush_lock = asyncio.Lock()
+        # Serializes budget calculation/reservation with PPE-aware dataset pushes.
+        # The threading lock protects synchronous state mutation; this async lock
+        # protects invariants across awaited push operations.
+        self._operation_lock = asyncio.Lock()
+        # Set during actor shutdown; rejects new charge operations after final flush.
+        self._closed = False
+        self._per_event_prices: Dict[str, Decimal] = {}
+        self._is_at_home = bool(config.get('is_at_home'))
+        # Prefer run_id from the API client (storage credentials) over env config.
+        client_run_id = getattr(client, 'run_id', None) if client is not None else None
+        self._actor_run_id: Optional[str] = client_run_id or config.get('actor_run_id')
+        self._initialized = False
+        self._not_ppe_warning_printed = False
+        # Unresolved platform-billable intents: idempotency_key -> metadata.
+        # Identity is the UUID key only — never keyed by event_name.
+        self._pending_charge_keys: Dict[str, Dict[str, Any]] = {}
+        # Optional local charging-log dataset (ACTOR_USE_CHARGING_LOG_DATASET).
+        self._charging_log_dataset: Any = None
+
+    def close(self) -> None:
+        """Mark the manager closed; subsequent charge/push operations are rejected."""
+        self._closed = True
+
+    @property
+    def charge_lock(self) -> RLock:
+        """Lock to synchronize charge operations."""
+        return self._charge_lock
+
+    def _load_pricing_data(self, pricing_data: Any) -> None:
+        """Populate PPE price map from a pricing info object/dict."""
+        if not isinstance(pricing_data, dict):
+            return
+
+        # Worker may inject either the full ActorPricingInfo or just pricingPerEvent.
+        model = pricing_data.get('pricingModel')
+        pricing_per_event = pricing_data.get('pricingPerEvent') or {}
+        actor_charge_events = pricing_per_event.get('actorChargeEvents') or pricing_per_event
+
+        if model and model != PricingModel.PAY_PER_EVENT.value and model != 'PAY_PER_EVENT':
+            return
+        if not actor_charge_events and model not in (PricingModel.PAY_PER_EVENT.value, 'PAY_PER_EVENT'):
+            return
+
+        per_event = {}
+        for event_name, event_data in (actor_charge_events or {}).items():
+            if not isinstance(event_data, dict):
+                continue
+            price = event_data.get('eventPriceUsd', event_data.get('event_price_usd', 0))
+            per_event[event_name] = PricingPerEvent(
+                event_price_usd=Decimal(str(price or 0)),
+                event_description=event_data.get('eventDescription') or event_data.get('eventTitle'),
+            )
+
+        if not per_event and model not in (PricingModel.PAY_PER_EVENT.value, 'PAY_PER_EVENT'):
+            return
+
+        self._pricing_info = PayPerEventActorPricingInfo(pricing_per_event=per_event)
+        self._per_event_prices = {
+            name: info.event_price_usd
+            for name, info in per_event.items()
+        }
+
+        default_event = pricing_data.get('defaultDatasetItemEventName')
+        if default_event and default_event not in self._per_event_prices:
+            self._per_event_prices[default_event] = Decimal('0')
+
+    async def init(self) -> None:
+        """Initialize the charging manager (JS ChargingManager.init parity).
+
+        Loads pricing info, prior charged counts and the budget from the
+        environment (when complete) or the platform run API, honors
+        ACTOR_TEST_PAY_PER_EVENT, and opens the optional charging-log dataset.
+        """
+        if self._initialized:
+            return
+
+        use_charging_log_dataset = bool(self._config.get('use_charging_log_dataset'))
+        if use_charging_log_dataset and self._is_at_home:
+            raise RuntimeError(
+                'Using the ACTOR_USE_CHARGING_LOG_DATASET environment variable is only supported '
+                'in a local development environment'
+            )
+
+        test_pay_per_event = bool(self._config.get('test_pay_per_event'))
+        if test_pay_per_event and self._is_at_home:
+            raise RuntimeError(
+                'Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported '
+                'in a local development environment'
+            )
+
+        pricing_data = await self._fetch_pricing_data()
+
+        # Load max total charge (absent/zero means no cap — JS `|| Infinity` parity).
+        max_charge = pricing_data.get('max_total_charge_usd')
+        self._max_total_charge_usd = Decimal(str(max_charge)) if max_charge else None
+
+        # Load pricing info (env when complete, otherwise the run API at home).
+        pricing_info_raw = pricing_data.get('pricing_info')
+        if pricing_info_raw:
+            try:
+                parsed = json.loads(pricing_info_raw) if isinstance(pricing_info_raw, str) else pricing_info_raw
+                self._load_pricing_data(parsed)
+            except (json.JSONDecodeError, TypeError, ValueError) as e:
+                logger.warning(f'Failed to parse actor pricing info: {e}')
+
+        # ACTOR_TEST_PAY_PER_EVENT forces pay-per-event mode locally even
+        # without configured pricing (every event then costs $1).
+        if test_pay_per_event and self._pricing_info is None:
+            self._pricing_info = PayPerEventActorPricingInfo(pricing_per_event={})
+
+        # Load charged event counts
+        charged_counts = pricing_data.get('charged_event_counts')
+        if charged_counts:
+            try:
+                if isinstance(charged_counts, str):
+                    self._charged_events = json.loads(charged_counts)
+                else:
+                    self._charged_events = dict(charged_counts)
+            except (json.JSONDecodeError, TypeError):
+                logger.warning('Failed to parse charged event counts')
+
+        # Recompute total charged from prior counts when prices are known.
+        self._total_charged_usd = Decimal('0.0')
+        for event_name, event_count in self._charged_events.items():
+            price = self._per_event_prices.get(event_name, Decimal('0'))
+            self._total_charged_usd += price * Decimal(str(event_count or 0))
+
+        self._initialized = True
+
+        # Optional charging-log dataset (pay-per-event runs only). The platform
+        # branch of the JS SDK is unreachable here because the environment
+        # variable is rejected at home above.
+        if self._pricing_info is not None and use_charging_log_dataset:
+            try:
+                await self._open_charging_log_dataset()
+            except Exception as e:
+                logger.warning('Failed to open the charging log dataset: %s', e)
+
+    async def _fetch_pricing_data(self) -> Dict[str, Any]:
+        """Resolve pricing info, charged counts and budget (JS fetchPricingInfo parity).
+
+        Prefers environment variables when both pricing info and charged counts are
+        present; on the platform an incomplete configuration falls back to the run API.
+        """
+        pricing_info_raw = self._config.get('actor_pricing_info')
+        charged_counts = self._config.get('charged_event_counts')
+        if pricing_info_raw and charged_counts:
+            return {
+                'pricing_info': pricing_info_raw,
+                'charged_event_counts': charged_counts,
+                'max_total_charge_usd': self._config.get('max_total_charge_usd'),
+            }
+
+        if self._is_at_home:
+            if not self._actor_run_id:
+                raise RuntimeError(
+                    'Actor run ID not found even though the Actor is running on the platform'
+                )
+            if self._client is not None:
+                run = None
+                try:
+                    run = await self._client.get_json(f'/v2/actor-runs/{self._actor_run_id}')
+                except Exception as e:
+                    logger.warning(
+                        'Failed to fetch actor run %s for pricing info: %s',
+                        self._actor_run_id,
+                        e,
+                    )
+                if run is None:
+                    raise RuntimeError('Actor run not found')
+                options = run.get('options') or {}
+                return {
+                    'pricing_info': run.get('pricingInfo'),
+                    'charged_event_counts': run.get('chargedEventCounts') or {},
+                    'max_total_charge_usd': options.get('maxTotalChargeUsd'),
+                }
+            logger.warning('No API client available; cannot fetch run pricing info')
+
+        return {
+            'pricing_info': pricing_info_raw,
+            'charged_event_counts': charged_counts,
+            'max_total_charge_usd': self._config.get('max_total_charge_usd'),
+        }
+
+    def _calculate_event_price(self, event_name: str) -> Optional[Decimal]:
+        """Effective unit price for affordability (JS calculateEventPrice parity).
+
+        Locally every event costs $1 so budgets constrain during development;
+        on the platform unregistered events are free (None).
+        """
+        if not self._is_at_home:
+            return Decimal('1')
+        if is_default_dataset_item_event(event_name):
+            if APIFY_DEFAULT_DATASET_ITEM_EVENT in self._per_event_prices:
+                return self._per_event_prices[APIFY_DEFAULT_DATASET_ITEM_EVENT]
+            return self._per_event_prices.get(SCRAPELY_DEFAULT_DATASET_ITEM_EVENT)
+        return self._per_event_prices.get(event_name)
+
+    def _get_event_pricing(self, event_name: str) -> tuple[Decimal, str]:
+        """Unit price and title used for reservation/logging (JS getEventPricing parity)."""
+        canonical_event_name = (
+            resolve_default_dataset_item_event_name(self._per_event_prices)
+            if is_default_dataset_item_event(event_name)
+            else event_name
+        )
+
+        price = self._per_event_prices.get(canonical_event_name)
+        if price is not None:
+            info = (
+                self._pricing_info.pricing_per_event.get(canonical_event_name)
+                if self._pricing_info is not None
+                else None
+            )
+            title = info.event_description if info is not None and info.event_description else canonical_event_name
+            return price, title
+
+        # Unknown event: free on the platform, $1 locally.
+        price = Decimal('0') if self._is_at_home else Decimal('1')
+        return price, f"Unknown event '{event_name}'"
+
+    async def _open_charging_log_dataset(self) -> None:
+        """Open the local charging-log dataset (JS parity: local development only)."""
+        from crawlee.storages import Dataset
+
+        if self._config.get('purge_on_start'):
+            dataset = await Dataset.open(name=LOCAL_CHARGING_LOG_DATASET_NAME)
+            await dataset.drop()
+        self._charging_log_dataset = await Dataset.open(name=LOCAL_CHARGING_LOG_DATASET_NAME)
+
+    def _snapshot_pending(self) -> List[tuple[str, Dict[str, Any]]]:
+        with self._charge_lock:
+            return [(k, dict(v)) for k, v in self._pending_charge_keys.items()]
+
+    def _drop_pending(self, idempotency_key: str) -> None:
+        with self._charge_lock:
+            self._pending_charge_keys.pop(idempotency_key, None)
+
+    def _unwind_reservation(self, event_name: str, count: int) -> None:
+        """Subtract a previously reserved local count/spend (reject or partial accept)."""
+        if count <= 0:
+            return
+        with self._charge_lock:
+            event_price = self._per_event_prices.get(event_name, Decimal('0'))
+            if event_name in self._charged_events:
+                self._charged_events[event_name] = max(
+                    0, self._charged_events[event_name] - count
+                )
+            self._total_charged_usd = max(
+                Decimal('0'),
+                self._total_charged_usd - event_price * Decimal(count),
+            )
+
+    def _quarantine_stale_pending(self) -> None:
+        """Remove intents older than the safe replay window (fail closed, no replay).
+
+        Unwinds the local reservation so quarantining cannot permanently consume budget.
+        """
+        now = time.monotonic()
+        stale: List[tuple[str, Dict[str, Any]]] = []
+        with self._charge_lock:
+            for key, pending in self._pending_charge_keys.items():
+                age = now - float(pending.get('created_at', now) or now)
+                if age > self._IDEMPOTENCY_SAFE_AGE_SECS:
+                    stale.append((key, dict(pending)))
+            for key, _pending in stale:
+                self._pending_charge_keys.pop(key, None)
+        for key, pending in stale:
+            event_name = str(pending.get('event_name') or '')
+            count = int(pending.get('count', 0) or 0)
+            if event_name and count > 0:
+                self._unwind_reservation(event_name, count)
+            logger.error(
+                'Quarantined stale charge intent past safe idempotency age '
+                '(key=%s event=%s count=%s); unwound local reservation; will not replay',
+                key,
+                pending.get('event_name'),
+                pending.get('count'),
+            )
+
+    async def _post_charge_once(
+        self,
+        *,
+        event_name: str,
+        count: int,
+        idempotency_key: str,
+    ) -> Dict[str, Any]:
+        if self._client is None:
+            raise RuntimeError('ChargingManager has no API client; cannot post charge intent')
+        response = await self._client.post(
+            f'/v2/actor-runs/{self._actor_run_id}/charge',
+            json_data={
+                'eventName': event_name,
+                'count': count,
+            },
+            headers={'Idempotency-Key': idempotency_key},
+        )
+        if isinstance(response, dict):
+            return response
+        # httpx.Response-like
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                return body
+        except Exception:
+            pass
+        return {}
+
+    async def _post_charge_with_retries(
+        self,
+        *,
+        event_name: str,
+        count: int,
+        idempotency_key: str,
+    ) -> Optional[int]:
+        """POST charge; return acceptedCount on success, None if uncertain.
+
+        Raises ChargeRejectedError for definitive platform rejections.
+        Same idempotency key on every attempt.
+        """
+        last_error: Optional[BaseException] = None
+        for attempt in range(self._POST_ATTEMPTS):
+            try:
+                body = await self._post_charge_once(
+                    event_name=event_name,
+                    count=count,
+                    idempotency_key=idempotency_key,
+                )
+                return _read_accepted_count(body, count)
+            except Exception as e:
+                last_error = e
+                rejected = _classify_charge_http_error(
+                    e,
+                    operation_id=idempotency_key,
+                    event_name=event_name,
+                    count=count,
+                )
+                if rejected is not None:
+                    raise rejected from e
+                if attempt + 1 < self._POST_ATTEMPTS:
+                    await asyncio.sleep(0.25 * (attempt + 1))
+        if last_error is not None:
+            logger.warning(
+                'Failed to record charge for event %s (count=%s, key=%s): %s',
+                event_name,
+                count,
+                idempotency_key,
+                last_error,
+            )
+        return None
+
+    async def flush_pending(
+        self, *, max_intents: int = 32, deadline_ms: float | None = None
+    ) -> int:
+        """Best-effort flush under the operation lock; drain until empty or deadline."""
+        if not self._is_at_home or self._client is None or not self._actor_run_id:
+            return 0
+        async with self._operation_lock:
+            return await self._flush_pending_exclusive(
+                max_intents=max_intents, deadline_ms=deadline_ms
+            )
+
+    async def _flush_pending_exclusive(
+        self, *, max_intents: int = 32, deadline_ms: float | None = None
+    ) -> int:
+        """Caller must hold _operation_lock."""
+        if not self._is_at_home or self._client is None or not self._actor_run_id:
+            return 0
+
+        import time
+
+        deadline = None if deadline_ms is None else (time.monotonic() + max(0.0, deadline_ms) / 1000.0)
+        confirmed_total = 0
+        async with self._flush_lock:
+            while True:
+                if deadline is not None and time.monotonic() >= deadline:
+                    break
+                self._quarantine_stale_pending()
+                snapshot = self._snapshot_pending()[: max(0, max_intents)]
+                if not snapshot:
+                    break
+                confirmed = 0
+                for idempotency_key, pending in snapshot:
+                    if deadline is not None and time.monotonic() >= deadline:
+                        break
+                    event_name = str(pending.get('event_name') or '')
+                    count = int(pending.get('count', 0) or 0)
+                    if not event_name or count <= 0:
+                        self._drop_pending(idempotency_key)
+                        continue
+                    try:
+                        accepted = await self._post_charge_with_retries(
+                            event_name=event_name,
+                            count=count,
+                            idempotency_key=idempotency_key,
+                        )
+                    except ChargeRejectedError as err:
+                        self._unwind_reservation(event_name, count)
+                        self._drop_pending(idempotency_key)
+                        logger.warning(
+                            'Dropping rejected pending charge (event=%s key=%s): %s',
+                            event_name,
+                            idempotency_key,
+                            err,
+                        )
+                        continue
+                    if accepted is not None:
+                        if accepted < count:
+                            self._unwind_reservation(event_name, count - accepted)
+                        self._drop_pending(idempotency_key)
+                        confirmed += 1
+                confirmed_total += confirmed
+                if confirmed == 0:
+                    break
+        return confirmed_total
+
+    async def charge(self, event_name: str, count: int = 1) -> ChargeResult:
+        """Atomically reserve and submit one logical charge operation."""
+        async with self._operation_lock:
+            return await self._charge_exclusive(event_name, count)
+
+    async def _charge_exclusive(self, event_name: str, count: int = 1) -> ChargeResult:
+        if self._closed:
+            raise RuntimeError('ChargingManager is closed (actor is shutting down); charge rejected')
+        """Charge for a specified number of events.
+
+        Args:
+            event_name: Name of the event to charge
+            count: Number of events to charge
+
+        Returns:
+            ChargeResult indicating if the limit was reached
+
+        Raises:
+            ChargeUncertainError: POST could not be confirmed after retries; the
+                operation remains reserved locally and pending for flush.
+        """
+        if not self._initialized:
+            await self.init()
+
+        # Not a PPE actor — ignore charges (matches JS ChargingManager).
+        if self._pricing_info is None:
+            if not self._not_ppe_warning_printed:
+                logger.warning(
+                    'Ignored attempt to charge for an event - the Actor does not use the pay-per-event pricing'
+                )
+                self._not_ppe_warning_printed = True
+            return ChargeResult(
+                chargeable_within_limit={},
+                charged_count=0,
+                event_charge_limit_reached=False,
+            )
+
+        if not isinstance(count, int) or isinstance(count, bool) or count < 1:
+            raise ValueError('count must be a positive integer')
+
+        # Best-effort: clear older unresolved intents before starting a new one.
+        try:
+            await self._flush_pending_exclusive()
+        except Exception as e:
+            logger.warning('flush_pending before charge failed: %s', e)
+
+        idempotency_key: Optional[str] = None
+        chargeable_count = 0
+        will_post = False
+
+        with self._charge_lock:
+            event_price, event_title = self._get_event_pricing(event_name)
+            affordability_price = self._calculate_event_price(event_name) or Decimal('0')
+
+            # JS ChargingManager parity: canPost requires isAtHome — a local
+            # process with an API client/run ID must never post platform charges.
+            can_post_base = (
+                self._is_at_home
+                and bool(self._actor_run_id)
+                and self._client is not None
+                and not is_default_dataset_item_event(event_name)
+                and event_name in self._per_event_prices
+            )
+
+            # Budget gate (JS parity): trim unaffordable counts, but keep the
+            # legacy one-event overdraw while the budget is not yet exceeded.
+            chargeable_count = count
+            if self._max_total_charge_usd is not None and affordability_price > 0:
+                remaining = self._max_total_charge_usd - self._total_charged_usd
+                max_count_by_limit = max(0, int(remaining / affordability_price))
+                if count > max_count_by_limit:
+                    chargeable_count = (
+                        max_count_by_limit + 1
+                        if self._total_charged_usd <= self._max_total_charge_usd
+                        else 0
+                    )
+
+            if chargeable_count <= 0:
+                return ChargeResult(
+                    chargeable_within_limit=self._compute_chargeable(),
+                    charged_count=0,
+                    event_charge_limit_reached=True,
+                )
+
+            will_post = can_post_base and chargeable_count > 0
+
+            if will_post:
+                if len(self._pending_charge_keys) >= self._PENDING_MAX_ENTRIES:
+                    logger.warning(
+                        'Too many unresolved charge intents (%s); refusing new '
+                        'billable charge for event %s until pending POSTs succeed',
+                        len(self._pending_charge_keys),
+                        event_name,
+                    )
+                    return ChargeResult(
+                        chargeable_within_limit=self._compute_chargeable(),
+                        charged_count=0,
+                        event_charge_limit_reached=False,
+                    )
+                idempotency_key = str(uuid.uuid4())
+                self._pending_charge_keys[idempotency_key] = {
+                    'idempotency_key': idempotency_key,
+                    'created_at': time.monotonic(),
+                    'event_name': event_name,
+                    'count': chargeable_count,
+                }
+
+            # Reserve local budget once per logical operation.
+            if event_name not in self._charged_events:
+                self._charged_events[event_name] = 0
+            self._charged_events[event_name] += chargeable_count
+            self._total_charged_usd += event_price * Decimal(chargeable_count)
+
+            result = ChargeResult(
+                chargeable_within_limit=self._compute_chargeable(),
+                charged_count=chargeable_count,
+                event_charge_limit_reached=self._is_event_limit_reached(event_name),
+            )
+
+        # Record charge with the platform.
+        # Synthetic default-dataset events are tracked locally only.
+        if will_post and idempotency_key is not None:
+            try:
+                accepted = await self._post_charge_with_retries(
+                    event_name=event_name,
+                    count=chargeable_count,
+                    idempotency_key=idempotency_key,
+                )
+            except ChargeRejectedError:
+                # Server definitively rejected: unwind local reservation.
+                self._drop_pending(idempotency_key)
+                self._unwind_reservation(event_name, chargeable_count)
+                return ChargeResult(
+                    chargeable_within_limit=self._compute_chargeable(),
+                    charged_count=0,
+                    event_charge_limit_reached=True,
+                )
+            if accepted is not None:
+                self._drop_pending(idempotency_key)
+                if accepted < chargeable_count:
+                    self._unwind_reservation(event_name, chargeable_count - accepted)
+                    chargeable_count = accepted
+                    result = ChargeResult(
+                        chargeable_within_limit=self._compute_chargeable(),
+                        charged_count=chargeable_count,
+                        event_charge_limit_reached=self._is_event_limit_reached(event_name),
+                    )
+            else:
+                raise ChargeUncertainError(
+                    f'Charge for event {event_name!r} (count={chargeable_count}) '
+                    f'was not confirmed by the platform; operation_id={idempotency_key}',
+                    operation_id=idempotency_key,
+                    event_name=event_name,
+                    count=chargeable_count,
+                )
+        elif (
+            chargeable_count > 0
+            and self._is_at_home
+            and not is_default_dataset_item_event(event_name)
+            and event_name not in self._per_event_prices
+            and self._pricing_info is not None
+        ):
+            logger.warning("Attempting to charge for an unknown event '%s'", event_name)
+
+        if self._charging_log_dataset is not None:
+            try:
+                await self._charging_log_dataset.push_data({
+                    'eventName': event_name,
+                    'eventTitle': event_title,
+                    'eventPriceUsd': float(event_price),
+                    'chargedCount': chargeable_count,
+                    'timestamp': datetime.now(timezone.utc).isoformat(),
+                })
+            except Exception as log_err:
+                logger.warning('Failed to append charging log entry: %s', log_err)
+
+        if chargeable_count < count:
+            subject = 'instance' if count == 1 else 'instances'
+            logger.info(
+                "Charging %s %s of '%s' event would exceed maxTotalChargeUsd - "
+                'only %s events were charged',
+                count,
+                subject,
+                event_name,
+                chargeable_count,
+            )
+
+        return result
+
+    def calculate_max_event_charge_count_within_limit(self, event_name: str) -> Optional[int]:
+        """Calculate how many events can be charged before reaching the limit.
+
+        Args:
+            event_name: Name of the inspected event
+
+        Returns:
+            Maximum count that can be charged, or None if no limit
+        """
+        if self._max_total_charge_usd is None:
+            return None
+
+        event_price = self._calculate_event_price(event_name)
+        if event_price is None or event_price <= 0:
+            return None
+
+        remaining = self._max_total_charge_usd - self._total_charged_usd
+        return max(0, int(remaining / event_price))
+
+    def calculate_total_charged_amount(self) -> Decimal:
+        """Calculate the total amount charged so far.
+
+        Returns:
+            Total charged amount in USD
+        """
+        return self._total_charged_usd
+
+    def compute_chargeable(self) -> Dict[str, Optional[int]]:
+        """Compute max events of each type that can be charged within budget.
+
+        Returns:
+            Dictionary of event names to maximum chargeable counts
+        """
+        result = {}
+        for event_name in self._per_event_prices:
+            result[event_name] = self.calculate_max_event_charge_count_within_limit(event_name)
+        return result
+
+    def compute_push_data_limit(
+        self,
+        items_count: int,
+        event_name: str,
+        *,
+        is_default_dataset: bool = False,
+    ) -> int:
+        """Compute how many items can be pushed and charged within budget.
+
+        Accounts for both the explicit event and the default dataset item event.
+
+        Args:
+            items_count: Number of items to push
+            event_name: Explicit event name to charge for each item
+            is_default_dataset: Whether pushing to default dataset
+
+        Returns:
+            Maximum number of items that can be pushed within budget
+        """
+        # Calculate combined price per item (effective prices: $1 per event locally)
+        explicit_price = (
+            self._calculate_event_price(event_name) or Decimal('0') if event_name else Decimal('0')
+        )
+        default_price = Decimal('0')
+
+        if is_default_dataset:
+            default_event = self._config.get('default_dataset_item_event_name')
+            if not default_event:
+                default_event = resolve_default_dataset_item_event_name(self._per_event_prices)
+            if default_event:
+                default_price = self._calculate_event_price(default_event) or Decimal('0')
+
+        combined_price = explicit_price + default_price
+
+        if combined_price <= 0:
+            return items_count
+
+        if self._max_total_charge_usd is None:
+            return items_count
+
+        remaining = self._max_total_charge_usd - self._total_charged_usd
+        max_items = int(remaining / combined_price)
+
+        return min(items_count, max(0, max_items))
+
+    def get_charged_event_count(self, event_name: str) -> int:
+        """Get the number of events charged so far.
+
+        Args:
+            event_name: Name of the inspected event
+
+        Returns:
+            Number of events charged
+        """
+        if is_default_dataset_item_event(event_name):
+            return (
+                self._charged_events.get(APIFY_DEFAULT_DATASET_ITEM_EVENT, 0)
+                + self._charged_events.get(SCRAPELY_DEFAULT_DATASET_ITEM_EVENT, 0)
+            )
+        return self._charged_events.get(event_name, 0)
+
+    def get_max_total_charge_usd(self) -> Decimal:
+        """Get the configured maximum total charge.
+
+        Returns:
+            Maximum total charge in USD
+        """
+        # No configured cap (or zero) means unlimited — JS returns Infinity.
+        return self._max_total_charge_usd if self._max_total_charge_usd else Decimal('Infinity')
+
+    def get_pricing_info(self) -> ActorPricingInfoResult:
+        """Retrieve detailed pricing information for the current Actor run.
+
+        Returns:
+            ActorPricingInfoResult with pricing details
+        """
+        return ActorPricingInfoResult(
+            is_pay_per_event=self._pricing_info is not None,
+            max_total_charge_usd=(
+                self.get_max_total_charge_usd()
+                if self.get_max_total_charge_usd().is_finite()
+                else float('inf')
+            ),
+            per_event_prices=self._per_event_prices,
+            pricing_model=PricingModel.PAY_PER_EVENT if self._pricing_info else None,
+        )
+
+    def is_event_charge_limit_reached(self, event_name: str) -> bool:
+        """Check if the budget is insufficient to charge even one more event.
+
+        Args:
+            event_name: Name of the event to check
+
+        Returns:
+            True if no more events of this type can be charged
+        """
+        event_price = self._calculate_event_price(event_name) or Decimal('0')
+
+        if self._max_total_charge_usd is None:
+            return False
+
+        remaining = self._max_total_charge_usd - self._total_charged_usd
+        return remaining < event_price
+
+    def _compute_chargeable(self) -> Dict[str, Optional[int]]:
+        """Internal method to compute chargeable counts."""
+        return self.compute_chargeable()
+
+    def _is_event_limit_reached(self, event_name: str) -> bool:
+        """Internal method to check if event limit is reached."""
+        return self.is_event_charge_limit_reached(event_name)
+
+    def get_charged_events(self) -> Dict[str, int]:
+        """Get the count of charged events by event name.
+
+        Returns:
+            Dictionary of event names to counts
+        """
+        return self._charged_events.copy()
+
+    def get_total_charged_usd(self) -> Decimal:
+        """Get the total amount charged in USD.
+
+        Returns:
+            Total charged amount
+        """
+        return self._total_charged_usd
+
+
+
+def _read_accepted_count(body: Any, fallback: int) -> int:
+    if not isinstance(body, dict):
+        return fallback
+    # Support both bare body and {data: ...} envelopes.
+    data = body.get('data') if isinstance(body.get('data'), dict) else body
+    raw = data.get('acceptedCount') if isinstance(data, dict) else None
+    if isinstance(raw, (int, float)) and raw >= 0:
+        return int(raw)
+    return fallback
+
+
+def _classify_charge_http_error(
+    err: BaseException,
+    *,
+    operation_id: str,
+    event_name: str,
+    count: int,
+) -> Optional[ChargeRejectedError]:
+    status = getattr(err, 'status_code', None)
+    if status is None:
+        response = getattr(err, 'response', None)
+        status = getattr(response, 'status_code', None) if response is not None else None
+
+    # 401/403: ownership or scoped-run authorization failures are permanent.
+    if status in (400, 401, 402, 403, 404, 405, 409):
+        return ChargeRejectedError(
+            f'Charge rejected by platform (HTTP {status}) for event {event_name!r}',
+            operation_id=operation_id,
+            event_name=event_name,
+            count=count,
+            status_code=int(status) if status is not None else None,
+            reason='charge-limit-exceeded' if status == 402 else f'http-{status}',
+        )
+
+    message = str(err)
+    if any(
+        token in message.lower()
+        for token in (
+            'charge-limit-exceeded',
+            'unknown-event',
+            'ledger-sealed',
+            'invalid-input',
+            'conflict',
+        )
+    ):
+        return ChargeRejectedError(
+            message,
+            operation_id=operation_id,
+            event_name=event_name,
+            count=count,
+            status_code=int(status) if isinstance(status, int) else None,
+            reason='message-match',
+        )
+    return None
+
+
+async def push_data_and_charge(
+    charging_manager: ChargingManager,
+    items: Union[Dict[str, Any], List[Dict[str, Any]]],
+    event_name: Optional[str],
+    is_default_dataset: bool,
+    push_fn: Any,
+) -> ChargeResult:
+    """Push data to dataset and charge for each item.
+
+    Limits items to remaining budget before push (JS parity).
+
+    Args:
+        charging_manager: Charging manager instance
+        items: Items to push
+        event_name: Event name for charging
+        is_default_dataset: Whether pushing to default dataset
+        push_fn: Function to push items
+
+    Returns:
+        ChargeResult
+    """
+    if not isinstance(items, list):
+        items = [items]
+
+    async with charging_manager._operation_lock:
+        if charging_manager._closed:
+            raise RuntimeError('ChargingManager is closed (actor is shutting down); charge rejected')
+        # Non-PPE actors push everything without charging (JS calculatePushDataLimits
+        # parity: `if (!this.isPayPerEvent) return { limitedItems, eventsToCharge: {} }`).
+        is_ppe = charging_manager._pricing_info is not None
+
+        resolved_event = event_name
+        if is_ppe and not resolved_event and is_default_dataset:
+            fallback_event = charging_manager._config.get('default_dataset_item_event_name')
+            if not fallback_event:
+                fallback_event = resolve_default_dataset_item_event_name(
+                    charging_manager._per_event_prices
+                )
+            if fallback_event:
+                resolved_event = fallback_event
+
+        limited_count = len(items)
+        if is_ppe and resolved_event:
+            # Keep the explicit event separate from the implicit default-dataset
+            # event. Passing resolved_event here would count the default price twice.
+            limited_count = charging_manager.compute_push_data_limit(
+                len(items),
+                event_name or '',
+                is_default_dataset=is_default_dataset,
+            )
+
+        limited_items = items[:limited_count] if limited_count < len(items) else items
+
+        if not limited_items:
+            return ChargeResult(
+                chargeable_within_limit=charging_manager.compute_chargeable(),
+                charged_count=0,
+                event_charge_limit_reached=len(items) > 0 and limited_count == 0,
+            )
+
+        # Charge BEFORE persisting so a server cap/reject cannot leave unbilled
+        # items in the dataset. Operation lock is held across both steps.
+        if is_ppe and resolved_event:
+            results: List[ChargeResult] = []
+            default_event: Optional[str] = None
+            if is_default_dataset:
+                default_event = charging_manager._config.get('default_dataset_item_event_name')
+                if not default_event:
+                    default_event = resolve_default_dataset_item_event_name(
+                        charging_manager._per_event_prices
+                    )
+
+            # Synthetic storage event first (local-only); then explicit billable event.
+            reserved_in_op: list[tuple[str, int]] = []
+            try:
+                if default_event:
+                    r = await charging_manager._charge_exclusive(default_event, len(limited_items))
+                    results.append(r)
+                    reserved_in_op.append((default_event, r.charged_count))
+                if event_name and event_name != default_event:
+                    r = await charging_manager._charge_exclusive(event_name, len(limited_items))
+                    results.append(r)
+                    reserved_in_op.append((event_name, r.charged_count))
+            except Exception:
+                for name, reserved in reserved_in_op:
+                    if reserved > 0:
+                        charging_manager._unwind_reservation(name, reserved)
+                raise
+
+            if results:
+                # Pair each result with the event it reserved so we can unwind
+                # over-reservations when the min accepted count is lower.
+                charged_events: List[tuple[str, ChargeResult]] = []
+                if default_event:
+                    charged_events.append((default_event, results[0]))
+                if event_name and event_name != default_event:
+                    charged_events.append((event_name, results[-1]))
+
+                accepted_for_items = min(
+                    len(limited_items),
+                    *(result.charged_count for result in results),
+                )
+                # Unwind any event that reserved more than we will persist
+                # (synthetic default-dataset is local-only and otherwise sticks).
+                for name, result in charged_events:
+                    if result.charged_count > accepted_for_items:
+                        charging_manager._unwind_reservation(
+                            name, result.charged_count - accepted_for_items
+                        )
+                if accepted_for_items > 0:
+                    try:
+                        await push_fn(limited_items[:accepted_for_items])
+                    except Exception as push_err:
+                        logger.error(
+                            'Dataset push failed after charge accepted (items=%s): %s',
+                            accepted_for_items,
+                            push_err,
+                        )
+                        raise
+                return ChargeResult(
+                    chargeable_within_limit=charging_manager.compute_chargeable(),
+                    charged_count=accepted_for_items * len(results) if results else 0,
+                    event_charge_limit_reached=any(
+                        result.event_charge_limit_reached for result in results
+                    )
+                    or accepted_for_items < len(limited_items),
+                )
+
+
+        # No billable events — still persist the budget-limited items.
+        await push_fn(limited_items)
+        return ChargeResult(
+            chargeable_within_limit=charging_manager.compute_chargeable(),
+            charged_count=0,
+            event_charge_limit_reached=False,
+        )