fix: address apify-client v3 adaptation review findings

- new_client: scale max timeout tier 12x (was 24x); drop private apify_client._consts import via conditional kwargs
- call/call_task: annotate -> Run (they never return None)
- key-value store: fix error message copied from the dataset client
- Webhook: drop description/should_interpolate_strings (not in the v4 ad-hoc representation); restore request_url validation
- charging: report tier-priced charge attempts accurately instead of as "unknown event"
- storage clients: drop redundant int() coercions and a RequestQueueStats round-trip
- re-export ActorEnvVars/ApifyEnvVars from apify; drop redundant pydantic[email] extra
- docs: refresh upgrading guide and CLAUDE.md; fix stale test annotations

Author: vdusek

.rules.md

@@ -4,7 +4,7 @@ This file provides guidance to programming agents when working with code in this
 
 ## Project Overview
 
-The Apify SDK for Python (`apify` package on PyPI) is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. It provides Actor lifecycle management, storage access (datasets, key-value stores, request queues), event handling, proxy configuration, and pay-per-event charging. It builds on top of the [Crawlee](https://crawlee.dev/python) web scraping framework and the [Apify API Client](https://docs.apify.com/api/client/python). Supports Python 3.10–3.14. Build system: hatchling.
+The Apify SDK for Python (`apify` package on PyPI) is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. It provides Actor lifecycle management, storage access (datasets, key-value stores, request queues), event handling, proxy configuration, and pay-per-event charging. It builds on top of the [Crawlee](https://crawlee.dev/python) web scraping framework and the [Apify API Client](https://docs.apify.com/api/client/python). Supports Python 3.11–3.14. Build system: hatchling.
 
 ## Common Commands
 
@@ -46,7 +46,7 @@ uv run poe e2e-tests
 ## Code Style
 
 - **Formatter/Linter**: Ruff (line length 120, single quotes for inline, double quotes for docstrings)
-- **Type checker**: ty (targets Python 3.10)
+- **Type checker**: ty (targets Python 3.11)
 - **All ruff rules enabled** with specific ignores — see `pyproject.toml` `[tool.ruff.lint]` for the full ignore list
 - Tests are exempt from docstring rules (`D`), assert warnings (`S101`), and private member access (`SLF001`)
 - Unused imports are allowed in `__init__.py` files (re-exports)
@@ -71,7 +71,7 @@ uv run poe e2e-tests
 
 - **`_proxy_configuration.py`** — `ProxyConfiguration` manages Apify proxy setup (residential, datacenter, groups, country targeting).
 
-- **`_models.py`** — Pydantic models for API data structures (Actor runs, webhooks, pricing info, etc.).
+- **`_webhook.py`** — The `Webhook` dataclass (ad-hoc / persistent webhook definition) and the `to_client_representations` helper. Response and data models are no longer defined in the SDK — they come from `apify-client` v3 (e.g. `Run`, the Actor pricing-info models).
 
 ### Storage Clients (`src/apify/storage_clients/`)
 
@@ -101,8 +101,9 @@ Optional integration (`apify[scrapy]` extra) providing Scrapy scheduler, middlew
 ### Key Dependencies
 
 - **`crawlee`** — Base framework providing storage abstractions, event system, configuration, service locator pattern
-- **`apify-client`** — HTTP client for the Apify API (`ApifyClientAsync`)
-- **`apify-shared`** — Shared constants and utilities (`ApifyEnvVars`, `ActorEnvVars`, etc.)
+- **`apify-client`** — HTTP client for the Apify API (`ApifyClientAsync`); also the source of response and data models (`Run`, pricing info, webhook representations)
+
+The SDK no longer depends on `apify-shared`. The platform env-var enums (`ApifyEnvVars`, `ActorEnvVars`) are vendored in `apify._consts` and re-exported from the top-level `apify` package.
 
 ## Testing
 

docs/04_upgrading/upgrading_to_v4.md

@@ -55,6 +55,22 @@ The deprecated `latest_sdk_version`, `log_format`, and `standby_port` fields hav
 
 The SDK is now built on [`apify-client`](https://docs.apify.com/api/client/python) v3 and no longer depends on `apify-shared`. The sections below cover the user-visible consequences; see the client's [Upgrading to v3](https://docs.apify.com/api/client/python/docs/upgrading/upgrading-to-v3) guide for the full list of changes in the client itself.
 
+### Environment variable enums moved
+
+If you imported the platform environment-variable enums from `apify_shared.consts` (`ApifyEnvVars`, `ActorEnvVars`), import them from `apify` instead — they are now vendored in the SDK and re-exported from the top-level package.
+
+**Before (v3.x):**
+
+```python
+from apify_shared.consts import ApifyEnvVars
+```
+
+**Now (v4.0):**
+
+```python
+from apify import ApifyEnvVars
+```
+
 ## Typed responses
 
 `Actor.start`, `Actor.abort`, `Actor.call`, and `Actor.call_task` now return `apify_client._models.Run` instead of the SDK-side `ActorRun`. Both are [Pydantic](https://docs.pydantic.dev/latest/) models with the same snake_case fields, so field access is unchanged — only the type and import path differ. The SDK no longer ships its own response models (`apify._models` has been removed); response shapes come from `apify-client`.
@@ -89,7 +105,7 @@ The Actor pricing-info models exposed through `Actor.configuration.actor_pricing
 
 ## `Webhook` API simplified
 
-The `Webhook` model has been slimmed down to only the fields a user sets when defining a webhook. Server-populated response fields (`id`, `created_at`, `modified_at`, `user_id`, `is_ad_hoc`, `condition`, `last_dispatch`, `stats`) and the unused `WebhookCondition` helper class have been removed. `Webhook` is now a plain `@dataclass` instead of a Pydantic `BaseModel` — construct it with snake_case kwargs; `.model_dump()` / `.model_validate()` are gone.
+The `Webhook` model has been slimmed down to only the fields a user sets when defining a webhook. Server-populated response fields (`id`, `created_at`, `modified_at`, `user_id`, `is_ad_hoc`, `condition`, `last_dispatch`, `stats`) and the unused `WebhookCondition` helper class have been removed. The `description` and `should_interpolate_strings` fields have also been removed — they are not part of the ad-hoc webhook representation (`event_types`, `request_url`, `payload_template`, `headers_template`) that `Actor.start` / `Actor.call` / `Actor.call_task` and `Actor.add_webhook` now send. `Webhook` is now a plain `@dataclass` instead of a Pydantic `BaseModel` — construct it with snake_case kwargs; `.model_dump()` / `.model_validate()` are gone.
 
 The retry and idempotency kwargs that used to live on `Actor.add_webhook` have moved onto the `Webhook` instance itself.
 
@@ -130,7 +146,7 @@ The `webhooks` argument on `Actor.start`, `Actor.call`, and `Actor.call_task` st
 
 ## `Actor.new_client` — `timeout` scales all tiers
 
-`apify-client` v3 split its single timeout into four tiers (short / medium / long / max). `Actor.new_client(timeout=...)` still takes a single `timedelta`; the SDK uses it as the medium-tier baseline and scales the other tiers proportionally (short = `timeout / 6`, long = `timeout * 12`, max = `timeout * 24`). The public signature is unchanged — no migration needed.
+`apify-client` v3 split its single timeout into four tiers (short / medium / long / max). `Actor.new_client(timeout=...)` still takes a single `timedelta`; the SDK uses it as the medium-tier baseline and scales the other tiers proportionally (short = `timeout / 6`, long = `timeout * 12`, max = `timeout * 12`). The public signature is unchanged — no migration needed.
 
 ## Using the client from `Actor.new_client`
 

pyproject.toml

@@ -41,7 +41,7 @@ dependencies = [
     "impit>=0.8.0",
     "lazy-object-proxy>=1.11.0",
     "more_itertools>=10.2.0",
-    "pydantic[email]>=2.11.0",
+    "pydantic>=2.11.0",
     "typing-extensions>=4.1.0",
     "websockets>=14.0",
     "yarl>=1.18.0",

src/apify/__init__.py

@@ -14,6 +14,7 @@
 
 from apify._actor import Actor
 from apify._configuration import Configuration
+from apify._consts import ActorEnvVars, ApifyEnvVars
 from apify._proxy_configuration import ProxyConfiguration, ProxyInfo
 from apify._webhook import Webhook
 from apify.events._types import ActorEventTypes
@@ -22,7 +23,9 @@
 
 __all__ = [
     'Actor',
+    'ActorEnvVars',
     'ActorEventTypes',
+    'ApifyEnvVars',
     'Configuration',
     'Event',
     'EventAbortingData',

src/apify/_actor.py

@@ -13,14 +13,6 @@
 from pydantic import AliasChoices
 
 from apify_client import ApifyClientAsync
-from apify_client._consts import (
-    DEFAULT_MAX_RETRIES,
-    DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-    DEFAULT_TIMEOUT_LONG,
-    DEFAULT_TIMEOUT_MAX,
-    DEFAULT_TIMEOUT_MEDIUM,
-    DEFAULT_TIMEOUT_SHORT,
-)
 from crawlee import service_locator
 from crawlee.errors import ServiceConflictError
 from crawlee.events import (
@@ -516,20 +508,28 @@ def new_client(
             timeout: Baseline HTTP timeout for medium-duration API operations. The underlying client uses
                 separate timeout tiers for short/medium/long/max-duration calls; passing a value here scales
                 all four tiers proportionally (short = `timeout / 6`, long = `timeout * 12`,
-                max = `timeout * 24`).
+                max = `timeout * 12`).
         """
-        return ApifyClientAsync(
-            token=token or self.configuration.token,
-            api_url=api_url or self.configuration.api_base_url,
-            max_retries=max_retries if max_retries is not None else DEFAULT_MAX_RETRIES,
-            min_delay_between_retries=min_delay_between_retries
-            if min_delay_between_retries is not None
-            else DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-            timeout_short=timeout / 6 if timeout is not None else DEFAULT_TIMEOUT_SHORT,
-            timeout_medium=timeout if timeout is not None else DEFAULT_TIMEOUT_MEDIUM,
-            timeout_long=timeout * 12 if timeout is not None else DEFAULT_TIMEOUT_LONG,
-            timeout_max=timeout * 24 if timeout is not None else DEFAULT_TIMEOUT_MAX,
-        )
+        # Forward only the explicitly provided options; omitting the rest lets `ApifyClientAsync` apply its
+        # own defaults, so the SDK doesn't have to import and re-pass the client's private default constants.
+        client_kwargs: dict[str, Any] = {
+            'token': token or self.configuration.token,
+            'api_url': api_url or self.configuration.api_base_url,
+        }
+        if max_retries is not None:
+            client_kwargs['max_retries'] = max_retries
+        if min_delay_between_retries is not None:
+            client_kwargs['min_delay_between_retries'] = min_delay_between_retries
+        if timeout is not None:
+            # `apify-client` v3 splits the timeout into four tiers; scale them from the single baseline,
+            # mirroring the client's default ratios (medium = baseline, short = baseline / 6,
+            # long = max = baseline * 12).
+            client_kwargs['timeout_short'] = timeout / 6
+            client_kwargs['timeout_medium'] = timeout
+            client_kwargs['timeout_long'] = timeout * 12
+            client_kwargs['timeout_max'] = timeout * 12
+
+        return ApifyClientAsync(**client_kwargs)
 
     @_ensure_context
     async def open_dataset(
@@ -998,7 +998,7 @@ async def call(
         webhooks: list[Webhook] | None = None,
         wait: timedelta | None = None,
         logger: logging.Logger | None | Literal['default'] = 'default',
-    ) -> Run | None:
+    ) -> Run:
         """Start an Actor on the Apify Platform and wait for it to finish before returning.
 
         It waits indefinitely, unless the wait argument is provided.
@@ -1076,7 +1076,7 @@ async def call_task(
         webhooks: list[Webhook] | None = None,
         wait: timedelta | None = None,
         token: str | None = None,
-    ) -> Run | None:
+    ) -> Run:
         """Start an Actor task on the Apify Platform and wait for it to finish before returning.
 
         It waits indefinitely, unless the wait argument is provided.
@@ -1260,9 +1260,6 @@ async def add_webhook(self, webhook: Webhook, *, idempotency_key: str | None = N
             webhook: The webhook to be added. It is automatically bound to the current Actor run.
             idempotency_key: Deprecated. Pass `idempotency_key` on the `Webhook` instance instead.
                 Will be removed in version 5.0.0.
-
-        Returns:
-            The created webhook.
         """
         if idempotency_key is not None:
             warnings.warn(

src/apify/_charging.py

@@ -262,6 +262,7 @@ def __init__(self, configuration: Configuration, client: ApifyClientAsync) -> No
 
         self._charging_state: dict[str, ChargingStateItem] = {}
         self._pricing_info: dict[str, PricingInfoItem] = {}
+        self._tier_priced_events: set[str] = set()
 
         self._not_ppe_warning_printed = False
         self.active = False
@@ -297,7 +298,10 @@ async def __aenter__(self) -> None:
             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
+                    # Tier-priced event - not chargeable via the SDK's flat-price path; tracked so a later
+                    # charge attempt is reported accurately rather than as an "unknown event".
+                    self._tier_priced_events.add(event_name)
+                    continue
                 self._pricing_info[event_name] = PricingInfoItem(
                     price=Decimal(str(event_pricing.event_price_usd)),
                     title=event_pricing.event_title,
@@ -401,6 +405,10 @@ async def charge(self, event_name: str, count: int = 1) -> ChargeResult:
                     pass
                 elif event_name in self._pricing_info:
                     await self._client.run(self._actor_run_id).charge(event_name, count=charged_count)
+                elif event_name in self._tier_priced_events:
+                    logger.warning(
+                        f"Event '{event_name}' is tier-priced and is not chargeable via the pay-per-event API."
+                    )
                 else:
                     logger.warning(f"Attempting to charge for an unknown event '{event_name}'")
 

src/apify/_configuration.py

@@ -81,7 +81,7 @@ def _parse_actor_pricing_info(data: Any) -> Any:
     if data is None or data == '':
         return None
     pricing_info = json.loads(data) if isinstance(data, str) else data
-    if isinstance(pricing_info, dict) and not pricing_info.get('pricingModel'):
+    if isinstance(pricing_info, dict) and not (pricing_info.get('pricingModel') or pricing_info.get('pricing_model')):
         return None
     return pricing_info
 

src/apify/_webhook.py

@@ -4,6 +4,7 @@
 from typing import TYPE_CHECKING
 
 from apify_client._models import WebhookRepresentation
+from crawlee._utils.urls import validate_http_url
 
 from apify._utils import docs_group
 
@@ -41,11 +42,9 @@ class Webhook:
     do_not_retry: bool | None = None
     """Whether to skip retrying the request on failure."""
 
-    description: str | None = None
-    """Human-readable description of the webhook."""
-
-    should_interpolate_strings: bool | None = None
-    """Whether to interpolate variables in string fields of the payload."""
+    def __post_init__(self) -> None:
+        # Fail fast on a malformed URL at construction time instead of deferring the error to the API call.
+        validate_http_url(self.request_url)
 
 
 def to_client_representations(webhooks: list[Webhook] | None) -> list[WebhookRepresentation] | None:

src/apify/storage_clients/_apify/_dataset_client.py

@@ -69,7 +69,7 @@ async def get_metadata(self) -> DatasetMetadata:
             created_at=metadata.created_at,
             modified_at=metadata.modified_at,
             accessed_at=metadata.accessed_at,
-            item_count=int(metadata.item_count),
+            item_count=metadata.item_count,
         )
 
     @classmethod

src/apify/storage_clients/_apify/_key_value_store_client.py

@@ -46,7 +46,7 @@ async def get_metadata(self) -> ApifyKeyValueStoreMetadata:
         metadata = await self._api_client.get()
 
         if metadata is None:
-            raise ValueError('Failed to retrieve dataset metadata.')
+            raise ValueError('Failed to retrieve key-value store metadata.')
 
         return ApifyKeyValueStoreMetadata(
             id=metadata.id,
@@ -148,7 +148,7 @@ async def iterate_keys(
             for item in list_key_page.items:
                 record_metadata = KeyValueStoreRecordMetadata(
                     key=item.key,
-                    size=int(item.size),
+                    size=item.size,
                     content_type='application/octet-stream',  # Content type not available from list_keys
                 )
                 yield record_metadata