Add platform browser client for white-label sockets

[ozsay]

Summary

Add @base44/sdk/platform/client for browser subscriptions to the white-label builder socket. This is an independent PR against main, using #283 as the packaging reference; it does not include or depend on that PR's platform-server implementation. Shared package/build configuration conflicts can be reconciled when the entries merge.

import { Base44PlatformClient } from "@base44/sdk/platform/client";

const client = new Base44PlatformClient({
  serverUrl,
  refreshToken: fetchBrowserTokenFromPartnerBackend,
});
const builder = client.builder.init({ onError: showConnectionError });
const subscription = builder.subscribe(appId, {
  afterSeq: savedCursor,
  onEvent: applyAndPersistEvent,
  onJoined: persistReplayBoundary,
  onError: showSubscriptionError,
});
await builder.connect();

• Lightweight client with lazy builder.init(...); independent builder sessions own connect/subscribe/close. Shared refreshToken runs only when a builder connects. Public models live in *.types.ts files following the module conventions in Add @base44/sdk/platform/server entry point #283.
• Fixed /partner namespace and /ws-whitelabel/socket.io/ path, WebSocket-only transport, fresh CONNECT auth.token on each connection attempt, and no write channel.
• Typed public events for app/message updates, directives, queue snapshots, task progress and image resolution. Preserve existing field names, nested shapes, omission/null semantics and branch metadata.
• Serialize application callbacks per app; resume after the last successfully applied cursor. Bound pending delivery, stop explicitly on resync/handler/protocol errors, and isolate other apps. Refresh the connection when adding subscriptions after retirement so late old-stream frames cannot enter a replacement subscription.
• Field-level JSDoc, a complete usage/recovery reference, compiled example, and validated generated documentation.
• Separate build output and package entry point, preserving runtime and legacy deep imports. Existing Socket.IO dependency, runtime source, lockfile and package version remain unchanged.

Validation

• 326 unit tests passed, including a real Socket.IO client against a local Engine.IO/Socket.IO protocol fixture exercising auth, reconnect and replay.
• Type tests, lint, runtime/platform builds and documentation validation passed.
• Seven packed-package tests passed: independent imports, legacy deep imports, entry-point isolation, and NodeNext/Bundler/legacy Node declaration resolution.
• git diff --check passed.

The local fixture is not a deployed-preview validation. Real browser-token integration and workspace enablement remain backend rollout prerequisites. No live provisioning, deployment, token issuance or external documentation publication was performed.

Intent (for reviewers & PR Autofix)

What this PR does

Implement the browser side of the white-label socket contract as a separate public SDK entry point, with documented types and reliable cursor handling.

Key decisions & why

• Keep this branch independent of Add @base44/sdk/platform/server entry point #283; reuse its packaging and module-factory conventions while leaving server SDK work separate.
• Root construction creates no socket, timers, or token requests. Socket ownership belongs to independent builder sessions, leaving room for other modules. All public model/type declarations live in *.types.ts files; refreshToken is shared client configuration.
• Keep Socket.IO as the existing dependency, per the clarified requirement. There are no new dependencies or lockfile changes.
• Advance cursors only after awaited application callbacks succeed; a failed callback must not cause reconnect to skip an unapplied event. Never silently reset cursors after replay errors.
• Refresh the transport before replacing retired subscriptions because the wire contract has no leave acknowledgement or subscription generation identifier.

What NOT to touch

The lack of API keys, token minting, chat commands, raw write events and HTTP fallback in the browser client is intentional. Preserve original public field names and independent entry points. Do not add private backend models or implementation details to this public package.

Tradeoffs / follow-ups

The backend token verifier and real deployment verification remain prerequisites. Snapshot/replay reconciliation is coordinated by the partner backend. This is at-least-once recovery with bounded retention, not exactly-once delivery. Package configuration conflicts with #283 will be resolved later.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.48-pr.286.a571e29

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.48-pr.286.a571e29"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.48-pr.286.a571e29"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.48-pr.286.a571e29
• 🔗 View this commit on GitHub

---

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