feat(platform)!: Socket messages page, and getSession with the socket path from the session

[amitbardos]

Stacked on #312. Merge that first; GitHub then retargets this PR to main.

Two parts, in separate commits so they can be reviewed apart. The weekly AsyncAPI sync workflow moved to #318, which waits for the backend deploy. #317 is folded in here and closed.

1. Socket messages page and JSDoc links (4a0a781…c8db94c)

• One event catalog. events-to-mdx.mjs renders only protocol/socket-messages: every message on the connection in both directions, the { room, data } envelope as fields, and the examples the document publishes. The builder events page is gone, since the callbacks' JSDoc already says how the client delivers each message. onEvent links to the protocol page, which the docs list beside the session endpoints (base44-dev/mintlify-docs#2479). protocol isn't in the category map, so copy-docs-local keeps it out of the Platform SDK nav.
• asyncapi.json is synced with sync:asyncapi from the document base44-dev/apper#29607 serves, and gen:events regenerated the types. TaskProgressed.event_type is now the five task values, and current/total are integers.
• The JSDoc links "Create socket session" to /api-reference/create-socket-session.

2. getSession and the socket path from the session (10d8bae, breaking, 0.2.0)

The browser passes one function instead of socketUrl and getSessionToken, and the socket path comes from the session instead of the hard-coded /ws/socket.io/.

const client = createPlatformClient();
const builder = client.builder.init({
  async getSession() {
    const response = await fetch('/api/builder-socket-session', { method: 'POST' });
    return response.json(); // the Create socket session body, unchanged
  },
  onError,
});

• builder.init({ getSession, onError }): getSession: () => Promise<SocketSession>, where SocketSession is { session_token, socket_url, socket_path }. Other keys (session_id, expires_in) are ignored. getSession is called everywhere getSessionToken was called before: the first connect, renewal after session.ended with reason expired, and the single renewal after a connection_denied on a cached token. The 20-second timeout and the cancellation in authenticate() are unchanged.
• The socket is created on the first connect(), because the address is known only after the first session. Transport reconnects keep using the cached session.
• A new address means a new socket. If a renewed session has a different socket_url or socket_path, the SDK doesn't call the old socket's auth callback. It removes the old socket's listeners, disconnects it, opens a socket at the new address, and rejoins every active subscription.
• Validation. socket_url must be an HTTP(S) origin with no credentials, path, query or fragment (the same check as before). socket_path must be an absolute path with no query or fragment, and can't start with //.
• createPlatformClient() takes no arguments. No options are left. TypeScript callers that still pass { socketUrl, getSessionToken } get a compile error instead of having the values silently ignored. An optional parameter can be added later without a breaking change. PlatformClientOptions is removed.
• A bad session is session_unavailable, whether the token, the URL or the path is invalid. connect() rejects with it and onError receives it. No TypeError is thrown. The code already meant that the session endpoint gave the SDK nothing usable.
• Version 0.2.0, with a new CHANGELOG.md. JSDoc, examples, README.md, unit, type and package tests are updated. SocketSession is listed on the builder reference page.

Tests

PATH=/opt/homebrew/bin:$PATH npm test in packages/platform:

 Test Files  2 passed (2)
      Tests  42 passed (42)
ℹ pass 5
ℹ fail 0

npm run check:events reports builder.events.generated.ts is up to date. npm run create-docs, run after the tests, writes 20 messages to protocol/socket-messages.mdx. npm run lint is clean.

New unit tests cover: the path taken from the session, extra keys in the body ignored, renewal at a new address moving the socket and rejoining both subscriptions, a failed renewal, a late session after close(), and 11 invalid bodies.

Needs attention

• Publishing 0.2.0. package.json is already at 0.2.0, so manual-publish.yml with version: 0.2.0 fails ("Version not changed"), and with minor it would publish 0.3.0. Either add --allow-same-version to the workflow, or set package.json back to 0.1.0 and publish with minor.
• One release. feat(platform): generate event types from AsyncAPI, and Mintlify docs for @base44/platform #312 renames the event types (a breaking change) without a version bump. Publish feat(platform): generate event types from AsyncAPI, and Mintlify docs for @base44/platform #312 and this PR together as 0.2.0, and don't publish from main between the two merges.

🤖 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.313.e45e431

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.313.e45e431"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.53-pr.313.e45e431"
  }
}

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

---

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