feat!: validate API responses with zod schemas generated from the OpenAPI spec

[vdusek]

Closes: #1027

Description

This PR adds runtime validation of API responses using Zod schemas generated from the OpenAPI specification, similar to how the Python API client validates responses with Pydantic.

It follows up on #985, which introduced generated TypeScript types via openapi-typescript.

Schema generation

• pnpm generate:models now generates both:
  • src/generated/api.ts — TypeScript types
  • src/generated/schemas.ts — Zod schemas
• The nightly regenerate_models.yaml workflow regenerates both.
  • Schemas are generated by a small custom OpenAPI-to-Zod emitter in scripts/schema_emitter.mts.
• The generated schemas intentionally:
  • use loose objects, so unknown response fields are preserved,
  • treat string enums as open, so unknown enum values are accepted,
  • use z.date() for date-time, because parseDateFields() runs before validation,
  • fail generation on unsupported JSON Schema keywords instead of silently ignoring them.

I also considered existing generators - hey-api, orval, kubb. None of them supports all the behaviors above natively, so the custom code would not disappear; it would move into resolvers or post-processing. Since our specification uses only a small subset of JSON Schema and all 240 generated schemas are cross-checked at compile time against the independently generated TypeScript types, keeping the emitter local seems like a better solution, and thanks to that to also avoid another dependency.

Validation

• parseResponse() now unwraps the API response, parses date fields, and validates the result. All resource methods in the base clients go through it.
• Invalid responses throw a new ResponseValidationError, which includes:
  • the request method and URL,
  • validation issues,
  • the original cause,
  • a message identifying the offending fields.
• The API deviations found along the way were fixed in the specification itself (fix(openapi): align schemas with actual API responses apify-docs#2932), so there are no hand-written schema overrides now.

Tests

• The mock server now uses spec-shaped fixtures generated from OpenAPI examples (test/mock_server/fixtures.ts), with their validity checked in fixtures.test.ts.
• Tests that intentionally use synthetic responses, such as pagination, timeout, and URL-encoding tests, mock the validation step.
• The integration suite remains the main check for real API/spec drift and passes on this branch.

Breaking changes

• Responses that do not match the OpenAPI specification now throw ResponseValidationError.
• ScheduleClient.getLog() now returns ScheduleInvoked[] instead of string, matching the actual API response.
• TaskPublicConfig now follows the specification:
  • publishedAt is optional and read-only,
  • categorization is removed.

All breaking changes are documented in the v3 upgrading guide.

Bundle size

The browser bundle grows from 288 kB to 327 kB due to the generated schemas. The limit in rsbuild.config.ts is increased to 360 kB.

✍️ Drafted by Claude Code

[github-actions]

⚠️ There are broken links in the documentation.

See more at https://github.com/apify/apify-client-js/actions/runs/33656440345#summary-100336057352

[B4nan]

The date parsing changes reminded me of #522, we should open this topic on slack in some public channel and agree on the direction.

[vdusek]

The date parsing changes reminded me of #522, we should open this topic on slack in some public channel and agree on the direction.

Sure, but I guess it does not block this PR, right? And we can do it later as a separate PR.

[B4nan]

Yeah, that should be resolved separately, including an entry in the upgrading guide.