feat(platform): generate event types from AsyncAPI, and Mintlify docs for @base44/platform

[amitbardos]

Generates the @base44/platform event types from the service's AsyncAPI document and runs the app SDK's Mintlify pipeline for the package.

• packages/platform/asyncapi.json: the committed protocol document (alpha, from base44-dev/mintlify-docs#2426). npm run sync:asyncapi -- <url> (or ASYNCAPI_URL) refreshes it and refuses a document with no messages. Production serves none while events are alpha, so point it at a dev backend (http://localhost:8000/api/asyncapi.json) until beta.
• npm run gen:events writes src/modules/builder.events.generated.ts with json-schema-to-typescript: one type per schema, plus ServerEventMap, ClientMessageMap and the runtime event-name list. PlatformEventMap, PlatformEvent, PlatformSnapshot, ToolCall and GuardApproval derive from it. A new backend event needs only a sync and a regen.
• Breaking type names: the backend model names replace the hand-written ones (ChatMessage → Message, AppStatus → StatusObject, Snapshot → PlatformSnapshot, SnapshotQueue → QueueState, Tool*Arguments → per-tool *Call variants). Runtime behavior is unchanged.
• CI: npm run check:events in unit-tests.yml fails when the generated file drifts from asyncapi.json.
• Docs: file-processing.js and copy-to-local-docs.js take --package-dir. @base44/sdk output is byte-identical (checked the generated content and the docs.json update against main). The platform reference lands in mintlify-docs developers/references/platform-sdk/docs (pushed to base44-dev/mintlify-docs#2426). The Socket messages page documents the service's protocol, so mintlify-docs builds it from the AsyncAPI document production serves; this package only links to it.
• JSDoc rewritten in the app SDK's voice with examples. serverUrl is the session's socket_url.

Needs attention before merge

• New devDependency json-schema-to-typescript@16.0.0, locked in package-lock.json from registry.npmjs.org.
• 286 of 412 schema properties have no description in the backend, so the generator falls back to the field title (Turn ID.). Adding Field(description=...) in the backend fixes this, and also fixes the Socket messages page.

🤖 Generated with Claude Code

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.53-pr.312.2bf40bc

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.53-pr.312.2bf40bc"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.53-pr.312.2bf40bc"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.53-pr.312.2bf40bc
• 🔗 View this commit on GitHub

---

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

[ozsay]

Double-checked head 3090447: one correctness issue to fix before merge, plus two small documentation corrections.

PlatformSnapshot.queue is required in the type but can be absent at runtime. PlatformSnapshot extends Snapshot inherits queue: QueueState, while decodeSnapshot still omits it when the incoming queue is missing or null. The existing real-socket test sends snapshots without a queue, so this is an already-supported input. The new type test permits snapshot.queue.items; I built this revision and reproduced TypeError: Cannot read properties of undefined (reading 'items') for both missing and null queues.

The smallest compatibility-preserving fix is to retain optionality in the SDK wrapper:

export interface PlatformSnapshot extends Omit<Snapshot, "queue"> {
  room: string;
  queue?: QueueState;
}

Update the type test accordingly. Alternatively, the decoder would need to guarantee a queue value for every accepted snapshot.

Small documentation corrections:

• The PR body's lockfile warning is stale: package-lock.json is committed, the added resolved URLs use registry.npmjs.org, and the CI job containing npm ci passed.
• ToolCall's “Check name to narrow it to that tool's call” JSDoc overstates the guarantee: OtherToolCall.name: string remains in the narrowed union. The type test already accounts for this with "results" in call; qualify the wording to reflect that.

The factory and option renames are acceptable for this new package with no users; no compatibility objection there. Broad generated exports and placeholder field descriptions are advisory, not merge blockers.

Validation: platform build, type checks, and all 27 unit tests passed locally. The queue failure was reproduced separately against the built decoder. I did not regenerate the docs.

[github-actions]

🚀 Package Preview Available! (@base44/platform)

---

Install this PR's preview build with npm:

npm i @base44-preview/platform@0.1.0-pr.312.2bf40bc

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.1.0-pr.312.2bf40bc"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/platform": "npm:@base44-preview/platform@0.1.0-pr.312.2bf40bc"
  }
}

• 📦 Preview Package: @base44-preview/platform@0.1.0-pr.312.2bf40bc
• 🔗 View this commit on GitHub

---

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

[amitbardos]

Thanks @ozsay. Fixed in dd8b394:

• PlatformSnapshot keeps queue optional (extends Omit<Snapshot, "queue"> with queue?: QueueState), matching what decodeSnapshot delivers. The type test checks that snapshot.queue?.items compiles and snapshot.queue.items doesn't.
• The ToolCall JSDoc says narrowing by name keeps OtherToolCall in the union, so check a field with in before using it.
• The stale lockfile note is gone from the description.

One more change since your review, in 419e113: the events page is no longer generated here. It documents the service's protocol, so mintlify-docs builds it from the AsyncAPI document production serves, like the REST references (base44-dev/mintlify-docs#2479). events-to-mdx.mjs, create-docs:events and the Events nav category are removed, and the JSDoc links to /developers/references/apps-api/sections/socket-messages.

Could you take another look?

🤖 Generated with Claude Code