refactor: collapse SDK pricing models into relaxing apify-client subclasses

The SDK kept full standalone pydantic copies of apify-client's four Actor
pricing-info models (plus ActorChargeEvent / PricingPerEvent) and a
_from_client_pricing_info converter. The copies existed only because the
platform's APIFY_ACTOR_PRICING_INFO env var omits fields apify-client v3
marks required (apifyMarginPercentage, createdAt, startedAt, per-event
eventDescription, per-variant trialMinutes / pricePerUnitUsd / unitName).

Replace the copies with thin subclasses of the apify-client models that
relax only those omitted fields to optional. Since each subclass is-a
apify-client model, the charging manager can isinstance-check against the
client base, so Run.pricing_info from the API flows through unchanged and
the converter is removed.

Configuration.actor_pricing_info keeps its exact discriminated-union shape,
so there is no public API change. Also fixes a latent bug: event_price_usd
is now correctly optional (inherited), so tier-priced pay-per-event Actors
no longer fail env-var validation; such events are skipped in the
flat-price charging path.

Author: vdusek

src/apify/_charging.py

@@ -9,6 +9,10 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
+import apify_client._models as _client_models
+from apify_client._models import (
+    ActorChargeEvent as _ClientActorChargeEvent,
+)
 from apify_client._models import (
     FlatPricePerMonthActorPricingInfo as _ClientFlatPricePerMonth,
 )
@@ -21,6 +25,9 @@
 from apify_client._models import (
     PricePerDatasetItemActorPricingInfo as _ClientPricePerDatasetItem,
 )
+from apify_client._models import (
+    PricingPerEvent as _ClientPricingPerEvent,
+)
 
 from apify._utils import ReentrantLock, docs_group, ensure_context
 from apify.log import logger
@@ -47,72 +54,78 @@
 
 # --- SDK-side Actor pricing-info models ---------------------------------------------------------------
 #
-# The Apify platform serializes Actor pricing info into the `APIFY_ACTOR_PRICING_INFO` env var, but it
-# omits several metadata fields that `apify-client` v3 treats as required (`apifyMarginPercentage`,
-# `createdAt`, `startedAt`, per-event `eventDescription`). The SDK keeps its own minimal copy with
-# those fields optional so `Configuration` validates the env var without injecting fake defaults.
+# These are thin subclasses of the `apify-client` pricing models. The Apify platform serializes Actor
+# pricing info into the `APIFY_ACTOR_PRICING_INFO` env var (parsed by `Configuration.actor_pricing_info`),
+# but omits several fields that `apify-client` v3 marks as required (`apifyMarginPercentage`, `createdAt`,
+# `startedAt`, per-event `eventDescription`, and per-variant `trialMinutes` / `pricePerUnitUsd` / `unitName`).
+# Each subclass relaxes only those omitted fields to optional, so the env var deserializes without faking
+# values. Because every subclass is-a `apify-client` model, the API-returned `Run.pricing_info` (already an
+# `apify-client` instance) flows through the same code paths without conversion.
 
 
-class CommonActorPricingInfo(BaseModel):
+class _RelaxedPricingMetadata(BaseModel):
+    """Mixin relaxing the `CommonActorPricingInfo` metadata fields the platform env var omits."""
+
     model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     apify_margin_percentage: Annotated[float | None, Field(alias='apifyMarginPercentage')] = None
     created_at: Annotated[datetime | None, Field(alias='createdAt')] = None
     started_at: Annotated[datetime | None, Field(alias='startedAt')] = None
-    notified_about_future_change_at: Annotated[datetime | None, Field(alias='notifiedAboutFutureChangeAt')] = None
-    notified_about_change_at: Annotated[datetime | None, Field(alias='notifiedAboutChangeAt')] = None
-    reason_for_change: Annotated[str | None, Field(alias='reasonForChange')] = None
 
 
 @docs_group('Charging')
-class FreeActorPricingInfo(CommonActorPricingInfo):
-    pricing_model: Annotated[Literal['FREE'], Field(alias='pricingModel')]
+class ActorChargeEvent(_ClientActorChargeEvent):
+    # `event_description` is required in apify-client but omitted from the env var.
+    event_description: Annotated[str | None, Field(alias='eventDescription')] = None
 
 
 @docs_group('Charging')
-class FlatPricePerMonthActorPricingInfo(CommonActorPricingInfo):
-    pricing_model: Annotated[Literal['FLAT_PRICE_PER_MONTH'], Field(alias='pricingModel')]
-    trial_minutes: Annotated[int | None, Field(alias='trialMinutes')] = None
-    price_per_unit_usd: Annotated[float | None, Field(alias='pricePerUnitUsd')] = None
+class PricingPerEvent(_ClientPricingPerEvent):
+    actor_charge_events: Annotated[dict[str, ActorChargeEvent] | None, Field(alias='actorChargeEvents')] = None
 
 
 @docs_group('Charging')
-class PricePerDatasetItemActorPricingInfo(CommonActorPricingInfo):
-    pricing_model: Annotated[Literal['PRICE_PER_DATASET_ITEM'], Field(alias='pricingModel')]
-    unit_name: Annotated[str | None, Field(alias='unitName')] = None
-    price_per_unit_usd: Annotated[float | None, Field(alias='pricePerUnitUsd')] = None
+class FreeActorPricingInfo(_RelaxedPricingMetadata, _ClientFree):
+    pass
 
 
 @docs_group('Charging')
-class ActorChargeEvent(BaseModel):
-    model_config = ConfigDict(populate_by_name=True, extra='allow')
-
-    event_price_usd: Annotated[float, Field(alias='eventPriceUsd')]
-    event_title: Annotated[str, Field(alias='eventTitle')]
-    event_description: Annotated[str | None, Field(alias='eventDescription')] = None
+class FlatPricePerMonthActorPricingInfo(_RelaxedPricingMetadata, _ClientFlatPricePerMonth):
+    trial_minutes: Annotated[int | None, Field(alias='trialMinutes')] = None
+    price_per_unit_usd: Annotated[float | None, Field(alias='pricePerUnitUsd')] = None
 
 
 @docs_group('Charging')
-class PricingPerEvent(BaseModel):
-    model_config = ConfigDict(populate_by_name=True, extra='allow')
-
-    actor_charge_events: Annotated[dict[str, ActorChargeEvent] | None, Field(alias='actorChargeEvents')] = None
+class PricePerDatasetItemActorPricingInfo(_RelaxedPricingMetadata, _ClientPricePerDatasetItem):
+    unit_name: Annotated[str | None, Field(alias='unitName')] = None
+    # `price_per_unit_usd` is already optional in apify-client - inherited.
 
 
 @docs_group('Charging')
-class PayPerEventActorPricingInfo(CommonActorPricingInfo):
-    pricing_model: Annotated[Literal['PAY_PER_EVENT'], Field(alias='pricingModel')]
+class PayPerEventActorPricingInfo(_RelaxedPricingMetadata, _ClientPayPerEvent):
+    # Re-typed to the relaxed element so an omitted `eventDescription` validates; the field stays required.
     pricing_per_event: Annotated[PricingPerEvent, Field(alias='pricingPerEvent')]
-    minimal_max_total_charge_usd: Annotated[float | None, Field(alias='minimalMaxTotalChargeUsd')] = None
 
 
-ActorPricingInfoModel = (
-    FreeActorPricingInfo
-    | FlatPricePerMonthActorPricingInfo
-    | PricePerDatasetItemActorPricingInfo
-    | PayPerEventActorPricingInfo
-)
-"""Discriminated union of Actor pricing-info models, keyed by `pricing_model`."""
+ActorPricingInfoModel = _ClientFree | _ClientFlatPricePerMonth | _ClientPricePerDatasetItem | _ClientPayPerEvent
+"""Common supertype of both env-var-parsed SDK subclasses and the API-returned `Run.pricing_info`."""
+
+# apify-client ships these models with deferred forward refs (`__pydantic_complete__` is False), so the
+# subclasses must be rebuilt - with the `TieredPricing*` names in scope - before the env-var discriminated
+# union can validate standalone.
+_pricing_rebuild_namespace = vars(_client_models) | {
+    'ActorChargeEvent': ActorChargeEvent,
+    'PricingPerEvent': PricingPerEvent,
+}
+for _pricing_model in (
+    ActorChargeEvent,
+    PricingPerEvent,
+    FreeActorPricingInfo,
+    FlatPricePerMonthActorPricingInfo,
+    PricePerDatasetItemActorPricingInfo,
+    PayPerEventActorPricingInfo,
+):
+    _pricing_model.model_rebuild(_types_namespace=_pricing_rebuild_namespace)
 
 
 @docs_group('Charging')
@@ -278,10 +291,13 @@ async def __aenter__(self) -> None:
         else:
             self._pricing_model = pricing_info.pricing_model if pricing_info else None
 
-        # Load per-event pricing information
-        if pricing_info is not None and isinstance(pricing_info, PayPerEventActorPricingInfo):
+        # Load per-event pricing information. Check against the apify-client base so both env-var-parsed
+        # SDK subclasses and the API-returned model match.
+        if isinstance(pricing_info, _ClientPayPerEvent):
             actor_charge_events = pricing_info.pricing_per_event.actor_charge_events or {}
             for event_name, event_pricing in actor_charge_events.items():
+                if event_pricing.event_price_usd is None:
+                    continue  # tier-priced event - not chargeable via the SDK's flat-price path
                 self._pricing_info[event_name] = PricingInfoItem(
                     price=Decimal(str(event_pricing.event_price_usd)),
                     title=event_pricing.event_title,
@@ -510,7 +526,7 @@ async def _fetch_pricing_info(self) -> _FetchedPricingInfoDict:
 
             max_charge = run.options.max_total_charge_usd
             return _FetchedPricingInfoDict(
-                pricing_info=_from_client_pricing_info(run.pricing_info),
+                pricing_info=run.pricing_info,
                 charged_event_counts=run.charged_event_counts or {},
                 max_total_charge_usd=Decimal(str(max_charge)) if max_charge is not None else Decimal('inf'),
             )
@@ -549,23 +565,3 @@ class _FetchedPricingInfoDict(TypedDict):
     pricing_info: ActorPricingInfoModel | None
     charged_event_counts: dict[str, int]
     max_total_charge_usd: Decimal
-
-
-def _from_client_pricing_info(
-    pricing_info: _ClientFree | _ClientFlatPricePerMonth | _ClientPricePerDatasetItem | _ClientPayPerEvent | None,
-) -> ActorPricingInfoModel | None:
-    """Project an `apify-client` pricing-info model (from `Run.pricingInfo`) into the SDK's pricing model.
-
-    The SDK keeps its own minimal pydantic copies so the platform's `APIFY_ACTOR_PRICING_INFO` env var
-    (which omits some metadata fields apify-client treats as required) deserializes cleanly. The API
-    response uses apify-client's models, so we convert here on the boundary.
-    """
-    if pricing_info is None:
-        return None
-    if isinstance(pricing_info, _ClientPayPerEvent):
-        return PayPerEventActorPricingInfo.model_validate(pricing_info.model_dump(by_alias=True))
-    if isinstance(pricing_info, _ClientFlatPricePerMonth):
-        return FlatPricePerMonthActorPricingInfo.model_validate(pricing_info.model_dump(by_alias=True))
-    if isinstance(pricing_info, _ClientPricePerDatasetItem):
-        return PricePerDatasetItemActorPricingInfo.model_validate(pricing_info.model_dump(by_alias=True))
-    return FreeActorPricingInfo.model_validate(pricing_info.model_dump(by_alias=True))

tests/unit/actor/test_charging_manager.py

@@ -184,6 +184,32 @@ async def test_get_pricing_info_structure(mock_client: MagicMock) -> None:
         assert info.per_event_prices['search'] == Decimal('0.01')
 
 
+async def test_tier_priced_event_is_skipped(mock_client: MagicMock) -> None:
+    """A tier-priced PPE event (no eventPriceUsd) must parse and be skipped, not crash."""
+    pricing_info = PayPerEventActorPricingInfo.model_validate(
+        {
+            'pricingModel': 'PAY_PER_EVENT',
+            'pricingPerEvent': {
+                'actorChargeEvents': {
+                    'flat': {'eventPriceUsd': 0.02, 'eventTitle': 'Flat event'},
+                    'tiered': {'eventTitle': 'Tiered event', 'eventTieredPricingUsd': {}},
+                }
+            },
+        }
+    )
+    config = _make_config(
+        test_pay_per_event=True,
+        actor_pricing_info=pricing_info,
+        charged_event_counts={},
+        max_total_charge_usd=Decimal('10.00'),
+    )
+    cm = ChargingManagerImplementation(config, mock_client)
+    async with cm:
+        info = cm.get_pricing_info()
+        # The flat event is registered with its price; the tier-priced event is skipped.
+        assert info.per_event_prices == {'flat': Decimal('0.02')}
+
+
 async def test_get_charged_event_count_unknown_event(mock_client: MagicMock) -> None:
     """Test get_charged_event_count returns 0 for unknown events."""
     config = _make_config(actor_pricing_info=None, charged_event_counts={})