feat!: support Payload 4

[maximseshuk]

What

Moves the plugin to Payload 4.0.0-canary.38 and prepares v1.0.0-beta.1. The version in package.json is already 1.0.0-beta.1. This PR adds no tag.

Breaking changes:

• Requires Payload 4.0.0-canary.38, Next.js 16.4+ and Node.js 24.15+. Payload 3 users stay on 0.x.
• Renamed options: metadata → info, specEndpoint → path, interactiveAuth.endpoint → interactiveAuth.path, docs UI specEndpoint → specURL. Old names throw at startup.
• securityWhen is now security, and filters.excludeWhen moves into filters.excludeOperations.
• custom.openapi.security takes 'public' or 'secured' instead of true or false.
• Extension transform gets one object, and an error in it fails the request.
• servers no longer comes from the Host header.

Also new: Payload 4 endpoints (validate, upload instructions, file download, API key reveal, document access), the access, servers, trustedHosts and interactiveAuth.collection options, folders and tags, definePlugin, and opt-out telemetry. Request bodies, query params and responses now match what Payload reads and sends. The repo moves to shared tooling 0.2.3, and the docs site gets a v1 (Beta) version.

Full list: .github/releases/v1.0.0-beta.1.md and docs/v1/upgrade-guide.mdx.

Why

Payload 4 changes routes, config and generated types, so 0.x does not work with it. The rename and security changes clean up the options before v1.

How I tested it

Unit tests (151) and integration tests (78) against the dev app with SQLite. The integration tests validate the 3.2, 3.1 and 3.0 output with an OpenAPI validator. Each of the 3 commits passes typecheck, lint, tests and build on its own.

Checklist

• pnpm typecheck && pnpm lint && pnpm format && pnpm test:unit pass
• Tests added or updated for the behavior change
• README.md and docs/ updated if users will notice the change
• Commit subjects follow Conventional Commits (fix: ..., feat: ...)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
payload-plugin-openapi	🟢 Ready	View Preview	Oct 8, 2026, 4:14 PM

💡 Tip: Enable Automations to automatically generate PRs for you.