[ozsay]

Stacked on #316 (base is that branch; retarget to main once it merges).

Summary

• platform.webhooks.verifyEvent(rawBody, headers, { publicKeys, toleranceSeconds? }) verifies Standard Webhooks v1a (Ed25519) signatures with WebCrypto only, so it runs on Node 20+, Deno, Bun and edge runtimes. Returns a typed WebhookEvent; nothing is parsed before the signature passes. Makes no network calls.
• platform.webhooks.createHandler({ publicKeys, on, onEvent, onSuccess, onError, toleranceSeconds? }) returns a fetch-style (request: Request) => Promise<Response>:
  • reads the raw body, verifies, and answers the webhook.test.v1 activation challenge itself (callbacks never see the probe);
  • runs onEvent, then the per-type handler from on (event narrowed per key), then onSuccess;
  • responds 204 on success (including types without a handler and unknown types), 400 on a verification failure, 500 on misconfigured keys (receiver_misconfigured), an unreadable body (request_failed) or a throwing callback (handler_failed);
  • onSuccess / onError may return a Response to override the default.
• Errors: WebhookVerificationError (400) vs WebhookConfigurationError (missing/malformed keys, or unsupported_runtime when WebCrypto can't import Ed25519; 500). Base44 retries any non-2xx; the status only shows which side failed in its delivery log.
• Unknown event types arrive as { type: "unknown", name, data }, matching the client's PlatformEvent; onEvent and on.unknown receive them, and they're answered 204.
• Configuration: createPlatformServer() takes no options (nothing in the server entrypoint calls an API, so receivers need no API key). Each module takes what it needs per call. The webhooks module takes publicKeys on every call that verifies (verifyEvent, createHandler); there is no module-level init/config. No env reads, no key fetching.
• Types: per-event data interfaces and WebhookEventMap are generated from the schemas published at https://base44.com/webhooks/schemas by npm run generate:webhooks (event list in scripts/webhook-event-types.json; --from <dir> for a local apper checkout).
• Adds engines.node >=20, README section, two examples (verifyEvent + switch, and createHandler), and json-schema-to-typescript as a devDependency.
• Mintlify reference: the server entrypoint is now in the reference. The pipeline expects one flat TypeDoc module, so a docs-only entry (scripts/mintlify-post-processing/reference.ts, with its own tsconfig.docs.json so nothing ships in dist) re-exports both entrypoints. New pages are createPlatformServer, the webhooks module, and the two webhook error classes with their codes. The functions nav group is renamed from "Client" to "Clients". The client's pages are byte-identical to main's output. Server JSDoc was rewritten to the docs guidelines.

Test plan

• npm test -w @base44/platform (type tests incl. per-handler narrowing, 63 unit tests incl. tamper/relabel/stale/rotation/config and handler status/callback ordering, typedoc, packed-package runtime and declaration checks)
• npm run create-docs -w @base44/platform; client pages diffed against main's output (identical)
• npx eslint packages/platform

🤖 Generated with Claude Code

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.54-pr.319.a12cfb1

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.54-pr.319.a12cfb1"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.54-pr.319.a12cfb1"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.54-pr.319.a12cfb1
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[github-actions]

🚀 Package Preview Available! (@base44/platform)

---

Install this PR's preview build with npm:

npm i @base44-preview/platform@0.2.0-pr.319.a12cfb1

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/platform:

npm i "@base44/platform@npm:@base44-preview/platform@0.2.0-pr.319.a12cfb1"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/platform": "npm:@base44-preview/platform@0.2.0-pr.319.a12cfb1"
  }
}

• 📦 Preview Package: @base44-preview/platform@0.2.0-pr.319.a12cfb1
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}