feat(platform)!: getSession with the socket path from the session, and asyncapi.json from production

[amitbardos]

Based on main now that #312 is merged.

Three commits. #317 and #318 are folded in here and closed. The Socket messages page is no longer generated in this repo: mintlify-docs builds it from the AsyncAPI document production serves (base44-dev/mintlify-docs#2479), and the JSDoc links to it at /developers/references/apps-api/sections/socket-messages.

1. asyncapi.json from production (2316986)

The committed document is the one production serves now that base44-dev/apper#29607 has deployed (identical to https://app.base44.com/api/asyncapi.json), and gen:events regenerated the types. TaskProgressed.event_type is now the five task values, and current/total are integers.

2. getSession and the socket path from the session (686327c, 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 written against what 0.1.0 shipped (Base44PlatformClient, serverUrl), including the type renames from feat(platform): generate event types from AsyncAPI, and Mintlify docs for @base44/platform #312. JSDoc, examples, README.md, unit, type and package tests are updated. SocketSession is listed on the builder reference page.

3. Hourly AsyncAPI sync (5bea8e5)

.github/workflows/sync-asyncapi.yml runs every hour, like mintlify-docs' OpenAPI syncs, and on workflow_dispatch. It first compares production's document with the committed one, so an hour with nothing new stops before npm ci. Otherwise it runs sync:asyncapi and gen:events. If asyncapi.json or the generated types changed, it builds the docs, runs the Platform SDK tests and opens or updates one rolling PR on bot/platform-asyncapi-sync, rebuilt from main on every run. When nothing changed, it closes a leftover sync PR. It uses the pinned actions/checkout and actions/setup-node, the Wix gateway proxy and the runner's gh, and adds no dependencies. Production already serves a document identical to the committed one, so a run today finds no diff. After merging, trigger it once by hand.

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, completes. 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 is on main and breaking without a version bump. Don't publish from main until this PR merges; then publish both as 0.2.0.

🤖 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.0299b5a

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.0299b5a"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.53-pr.313.0299b5a"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.53-pr.313.0299b5a
• 🔗 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.313.0299b5a

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.313.0299b5a"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/platform": "npm:@base44-preview/platform@0.2.0-pr.313.0299b5a"
  }
}

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

---

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