feat(platform)!: one getSession pass-through, and the socket path from the session

[amitbardos]

Stacked on #313. Merge that first.

The browser now passes one function, getSession, instead of socketUrl and getSessionToken. 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,
});

What changed

• getSession on builder.init(), next to onError: () => Promise<SocketSession>, where SocketSession is { session_token, socket_url, socket_path }. The SDK reads those three keys and ignores the others (session_id, expires_in). 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 (tokenFresh / retryDenied are unchanged). The 20-second timeout and the cancellation in authenticate() are unchanged.
• The socket is created on the first connect(). init() no longer creates one, 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 the connect handler rejoins every active subscription, each with a fresh snapshot. An address that hasn't changed reuses the socket.
• Validation. socket_url is checked as before (an HTTP(S) origin with no credentials, path, query or fragment). socket_path must be an absolute path with no query or fragment, and can't start with //. The token must be a non-empty string.
• Version 0.2.0. CHANGELOG.md is new: the package had nowhere to keep release notes, and the publish workflow's GitHub Release body is generic. It has the breaking change and a before/after snippet.
• JSDoc, examples, README.md, unit, type and package tests are updated. SocketSession is listed on the builder reference page (types-to-expose.json, appended-articles.json), so its fields are documented.

Decisions

• createPlatformClient() takes no arguments. With socketUrl and getSessionToken gone, there are no options left, and an empty options object would only be noise. TypeScript callers that still pass { socketUrl, getSessionToken } get a compile error ("Expected 0 arguments") instead of having the values silently ignored. If an option is needed later, an optional parameter can be added without a breaking change. PlatformClientOptions is removed.
• A bad session is session_unavailable, whether the token is missing, the socket_url is invalid or the socket_path is invalid. connect() rejects with it and onError receives it. The code already meant that "your session endpoint gave the SDK nothing usable", and a new code would be one more case for partners to handle. The JSDoc says it's retryable, except that an invalid field has to be fixed on the server first. No TypeError is thrown any more.

Tests

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

 Test Files  2 passed (2)
      Tests  42 passed (42)
✔ the tarball contains the compiled entry point and no source or test trees
✔ the client resolves from the installed package without the runtime SDK
✔ published declarations resolve with NodeNext
✔ published declarations resolve with Bundler
✔ published declarations resolve with Node
ℹ pass 5
ℹ fail 0

npm run check:events:

builder.events.generated.ts is up to date.

npm run create-docs (run after npm test):

✓ Post-processing complete!
Wrote 20 messages to protocol/socket-messages.mdx

npm run lint at the root is clean.

New unit tests: the path is taken from the session, extra keys in the body are ignored, renewal at a new address moves the socket and rejoins both subscriptions, a failed renewal stops the socket without authenticating it, a late session after close() opens nothing, and 11 invalid bodies (bad token, URL or path) are session_unavailable with no socket created. The real-handshake test (socket.test.js) connects on /live/socket.io/ from the session body.

Needs attention

• Publishing 0.2.0. package.json is already at 0.2.0. If manual-publish.yml is run with version: 0.2.0, npm version 0.2.0 fails with "Version not changed", and with minor it would publish 0.3.0. I didn't touch the workflow. Before publishing, either add --allow-same-version to the workflow or set package.json back to 0.1.0 and publish with minor.
• Docs: base44-dev/mintlify-docs#2479 has the regenerated reference and the updated guide.

🤖 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.317.4163f48

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.317.4163f48"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.53-pr.317.4163f48"
  }
}

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

---

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

[amitbardos]

Folded into #313 (same commit, feat(platform)!: take the socket session from one getSession pass-through). The weekly sync workflow moves out of #313 into its own PR.