refactor!: validate arguments with zod instead of ow

docs/02_concepts/02_error-handling.md

@@ -24,6 +24,27 @@ try {
 }
 ```
 
+## Invalid arguments
+
+Before sending a request, the client validates the arguments you passed. When a value doesn't match the expected shape, the client throws an <ApiLink to="class/ArgumentValidationError">`ArgumentValidationError`</ApiLink> without reaching the API. Its `message` names the offending field and the value it received. For programmatic inspection, `issues` carries the structured [zod](https://zod.dev) issues and `cause` carries the original `ZodError`.
+
+```js
+import { ApifyClient, ArgumentValidationError } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+try {
+    await client.dataset('my-dataset').listItems({ limit: 'ten' });
+} catch (error) {
+    if (error instanceof ArgumentValidationError) {
+        // Invalid input: expected number, received string at `limit`, got `ten`
+        console.log(error.message);
+        // [{ code: 'invalid_type', expected: 'number', path: ['limit'], ... }]
+        console.log(error.issues);
+    }
+}
+```
+
 ## Retries with exponential backoff
 
 The client automatically retries requests that fail due to network errors, Apify API internal errors (HTTP 500+), or rate limit errors (HTTP 429). By default, the client retries up to 8 times with exponential backoff starting at 500ms.

docs/04_upgrading/upgrading_v3.md

@@ -0,0 +1,76 @@
+---
+id: upgrading-to-v3
+title: Upgrading to v3
+sidebar_label: Upgrading to v3
+description: 'Breaking changes to be aware of when upgrading to version 3 of the Apify API client for JavaScript.'
+---
+
+import ApiLink from '@theme/ApiLink';
+
+This page summarizes the breaking changes when upgrading from v2 to v3 of `apify-client`.
+
+## Argument validation switched from `ow` to `zod`
+
+The client now validates the arguments you pass with [zod](https://zod.dev) instead of `ow`. This changes what gets thrown for invalid arguments, and tightens a few gaps `ow` used to let through silently.
+
+### A new error type
+
+Invalid arguments now throw an <ApiLink to="class/ArgumentValidationError">`ArgumentValidationError`</ApiLink> (exported from `apify-client`), not `ow`'s `ArgumentError`. Its message is a plain, human-readable sentence naming the offending field and the value it received, rather than `ow`'s JSON dump:
+
+```diff
+- Expected property string `countryCode` to match `/^[A-Z]{2}$/`, got `CZE` in object   // v2 (ow)
++ Invalid string: must match pattern /^[A-Z]{2}$/ at `countryCode`, got `CZE`            // v3 (zod)
+```
+
+The structured zod issues are available on `issues`, and the original `ZodError` on `cause`:
+
+```js
+import { ApifyClient, ArgumentValidationError } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+try {
+    await client.dataset('my-dataset').listItems({ limit: 'ten' });
+} catch (error) {
+    if (error instanceof ArgumentValidationError) {
+        console.log(error.message); // Invalid input: expected number, received string at `limit`, got `ten`
+        console.log(error.issues); // [{ code: 'invalid_type', expected: 'number', path: ['limit'], ... }]
+    }
+}
+```
+
+If you were matching on `ow`'s `ArgumentError`, switch to `ArgumentValidationError`. If you were parsing the old message text, use `issues` instead.
+
+### Arrays and functions no longer pass where a plain object is expected
+
+`ow`'s object check let arrays and functions through wherever a plain object was expected. Zod's does not, so passing one now throws instead of reaching the API with a nonsensical body. This affects `update()` / `create()` fields, `TaskClient.start()` / `call()` input, the storage `schema` option, `DatasetClient.pushItems()` items, and `RequestQueueClient.addRequest()` / `batchAddRequests()` requests.
+
+```js
+// Now throws: Invalid input: expected object, received array
+await client.actor('my-actor').update([{ name: 'my-actor' }]);
+```
+
+`Date`, `Map`, `Set` and other class instances still pass as objects, same as under `ow`.
+
+### `Infinity` and invalid `Date`s are now rejected
+
+`ow` only checked the type, so `Infinity` passed as a number and an invalid `Date` passed as a date. Zod additionally requires a *finite* number and a *valid* date, so both now throw:
+
+```js
+// Now throws: Invalid input: expected a finite number at `timeout`, got `Infinity`
+await client.actor('my-actor').call(undefined, { timeout: Infinity });
+
+// Now throws: Invalid input: expected a valid date at `startedBefore`
+//             Invalid input: expected string, received Date at `startedBefore`
+await client.actor('my-actor').runs().list({ startedBefore: new Date('nonsense') });
+```
+
+The second example reports a line per arm, because `startedBefore` accepts either a `Date` or a string.
+
+This affects numeric options such as `waitSecs`, `timeout` and `memory`, and date options such as `startedBefore` / `startedAfter`. `KeyValueStoreClient.setRecord()` rejects `NaN` and `Infinity` as a record value too, since `JSON.stringify()` turns both into `null`.
+
+### A few always-rejected options are gone from the types
+
+Some options were declared in the TypeScript types but always rejected by the client's own validation before a request was ever sent: `chunkSize` on `DatasetClient.downloadItems()` and `createItemsPublicUrl()`, and `signature` on `createItemsPublicUrl()` and `createKeysPublicUrl()`. These are no longer part of the option types, so passing them is now a compile-time error instead of a runtime throw.
+
+The reverse also happened: `chunkSize` now works on every paginating `list()` method. In v2 only `DatasetClient.listItems()` accepted it - everywhere else it type-checked and then threw.

package.json

@@ -77,10 +77,10 @@
         "async-retry": "^1.3.3",
         "axios": "^1.16.0",
         "content-type": "^1.0.5",
-        "ow": "^0.28.2",
         "proxy-agent": "^6.5.0",
         "tslib": "^2.5.0",
-        "type-fest": "^4.0.0"
+        "type-fest": "^4.0.0",
+        "zod": "^4.0.0"
     },
     "devDependencies": {
         "@apify/oxlint-config": "^0.3.0",

rsbuild.config.ts

@@ -3,6 +3,8 @@ import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';
 
 import { version } from './package.json';
 
+const MAX_BUNDLE_BYTES = 320 * 1024;
+
 const nodeOnlyModules = /^proxy-agent$/;
 const unusedInBrowserBuiltins = ['os', 'zlib', 'util'];
 const builtinAliases = Object.fromEntries(
@@ -33,7 +35,11 @@ export default defineConfig({
         minify: {
             jsOptions: {
                 minimizerOptions: {
-                    mangle: false,
+                    // Class names are load-bearing: `ApifyApiError` and `InvalidResponseBodyError` take
+                    // their `name` from `constructor.name`, and `ResourceClient.waitForFinish()` parses
+                    // the client name out of it.
+                    compress: { keep_classnames: true },
+                    mangle: { keep_classnames: true },
                 },
             },
         },
@@ -52,10 +58,17 @@ export default defineConfig({
             };
             config.optimization = {
                 ...config.optimization,
-                providedExports: false,
-                usedExports: false,
                 splitChunks: false,
-                minimize: false,
+            };
+            // A regression guard, not a target: the bundle sits at ~288 kB, so this only fails the
+            // build on an unnoticed jump. A `zod` minor is the likeliest cause, since it is a runtime
+            // dependency on a caret range - bumping this constant is the expected response.
+            config.performance = {
+                hints: 'error',
+                maxAssetSize: MAX_BUNDLE_BYTES,
+                maxEntrypointSize: MAX_BUNDLE_BYTES,
+                // The source map is many times the size of the bundle and ships separately.
+                assetFilter: (filename) => filename === 'bundle.js',
             };
             config.plugins = [...(config.plugins ?? []), new rspack.IgnorePlugin({ resourceRegExp: nodeOnlyModules })];
             config.resolve = {