@base44-preview/platform 0.0.0-stage → 0.1.0-pr.312.2ef55e3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 base44
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @base44/platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```sh
+npm install @base44/platform
+```
+
+This package implements the read-only white-label builder socket contract: a
+partner's browser watches the builder chat of up to eight apps over the platform's
+shared socket. It is independent of the app SDK (`@base44/sdk`).
+The workspace must have white-label sockets enabled; this SDK does not open sessions.
+
+```ts
+import { createPlatformClient } from "@base44/platform";
+
+const client = createPlatformClient({
+  socketUrl, // the session's socket_url, from POST /api/service/socket-sessions
+  async getSessionToken() {
+    const response = await fetch("/api/builder-socket-session", { method: "POST" });
+    if (!response.ok) throw new Error("Session request failed");
+    return (await response.json()).session_token;
+  },
+});
+const builder = client.builder.init({
+  onError(error) { showConnectionError(error.code); },
+});
+const subscription = builder.subscribe(appId, {
+  onSnapshot(snapshot) { replaceAppState(snapshot); },
+  async onEvent(event) { await applyEvent(event); }, // awaited before the next event
+  onError(error) { showSubscriptionError(error.code); },
+});
+await builder.connect();
+// On view teardown:
+subscription.unsubscribe();
+builder.close();
+```
+
+## Sessions
+
+`/api/builder-socket-session` is your backend's route, not an SDK endpoint. It opens a
+socket session with its workspace key (`apps:watch` scope) through
+`POST /api/service/socket-sessions` with `{ app_ids }`, and returns only the
+`session_token` and `socket_url` to the browser. Pass `socket_url` as `socketUrl`. Never pass the workspace key or any other server
+credential to this client. Subscribe only to apps on the session's allowlist; your
+backend adds or removes apps with `PUT`/`DELETE /api/service/socket-sessions/{session_id}/rooms/{app_id}`.
+
+A session lasts one hour and is never extended. The token goes exclusively in
+CONNECT `auth.session_token`, never a URL, and the SDK keeps it in memory only. It
+is reused across automatic reconnects. `getSessionToken` is called when a builder
+session first connects, and again only when the server rejects the cached token or
+expires the session; the SDK then reconnects once with the new token. Retrieval has
+a twenty-second timeout and reports `session_unavailable` on failure.
+
+One live socket per session: a newer connection with the same token replaces the
+older one, which stops with `session_replaced`. Open one session per page.
+
+## Lifecycle
+
+`createPlatformClient({ socketUrl, getSessionToken })` creates a lightweight module
+container: no Socket.IO instance, timers, token request or network activity. Its
+`builder` module follows the server SDK's module-factory pattern.
+
+`client.builder.init({ onError })` synchronously creates an independent `BuilderSession`
+without connecting. Repeated calls create separate sessions, each owning its own
+socket, listeners, subscriptions and cleanup. Close the returned session when its
+view is disposed; the root client and other sessions remain usable.
+
+`builder.connect()` resolves on CONNECT, before any snapshot. The socket uses the
+default namespace on `/ws/socket.io/`, WebSocket only, with a dedicated manager.
+Transport reconnection uses five attempts, starting at one second and capped at ten
+seconds with jitter; each attempt has a twenty-second timeout. A temporary server
+refusal is retried the same way. After exhaustion, a refusal or `session_replaced`,
+fix the cause and call `builder.connect()`.
+
+`builder.subscribe(appId, options)` returns a handle with `appId`, `active` and
+idempotent `unsubscribe()`. App IDs are 24 lowercase hexadecimal characters. One
+subscription per app and at most eight subscriptions are allowed per builder session.
+Subscriptions can be created before connecting. `builder.close()` is terminal for that
+session; call `client.builder.init(...)` again to start another.
+
+## Snapshots and events
+
+There is no replay cursor. Every join, including each rejoin after a reconnect, is
+answered with a `Snapshot`: the app's current `status` and its last 50 public
+messages. After a main-conversation rewrite (undo, restore, sync), the SDK delivers
+`conversation.changed` and rejoins the room, so a fresh snapshot follows. Treat a
+snapshot as the app's current state. The app's live events follow it, including
+those that landed while it was read. It holds only the last 50 messages, so merge
+by `id` if you keep longer history.
+
+Delivery is serialized **per app**, snapshots included; a slow app does not block
+others. Callbacks must settle; they cannot be forcibly cancelled. The client bounds
+pending delivery to 1,000 items per app. Error observers are synchronous notifications;
+their exceptions are isolated so they cannot interrupt another app's delivery.
+
+## Public shapes
+
+- `PlatformClientOptions` (`client.types.ts`): `socketUrl`, `getSessionToken`.
+- `BuilderModule` (`modules/builder.types.ts`): lazy `init(options)` factory.
+- `BuilderInitOptions`: connection-level `onError` observer.
+- `BuilderSession`: `connect()`, `subscribe(appId, options)`, `close()`.
+- `SubscriptionOptions`: required `onSnapshot`, `onEvent` and `onError`.
+- `PlatformSubscription`: read-only `appId`, `active`, and `unsubscribe()`.
+- `PlatformEvent`, `PlatformEventMap`, `PlatformSnapshot`, `ToolCall`, `GuardApproval`
+  (`modules/builder.events.types.ts`), derived from the generated event types.
+- Error codes in `errors.types.ts`.
+
+`PlatformEvent` is a **discriminated union**: switch on `event.type` to narrow
+`event.data`. Each delivery contains `type`, `appId` and `data`. On the wire every
+event is `{room, data}`; the SDK routes by `room` and validates the envelope, while
+payload schemas and private-field filtering are the server's. Omitted keys mean
+unchanged and explicit null clears. Events carrying `branch_id` belong to that branch;
+null or absent is main. Unknown event names are not forwarded. `PlatformSnapshot` is
+the service's `Snapshot` plus the app's `room`. Structural filtering does not promise
+redaction of generated prose or user content.
+
+## Event types
+
+The socket protocol is defined by the service's AsyncAPI document, committed as
+`asyncapi.json`. `src/modules/builder.events.generated.ts` is generated from it with
+`json-schema-to-typescript`: one type per schema, named after the backend model
+(`Message`, `StatusObject`, `QueueState`, one `*Call` per tool, one `*Approval` per
+guard), plus `ServerEventMap` and `ClientMessageMap`. Never edit it by hand.
+
+To pick up a protocol change:
+
+```sh
+# Production serves only beta and GA events, so point at a dev backend while events are alpha.
+npm run sync:asyncapi -w @base44/platform -- http://localhost:8000/api/asyncapi.json
+npm run gen:events -w @base44/platform
+```
+
+`sync:asyncapi` also reads `ASYNCAPI_URL`, defaults to production, and refuses a
+document with no messages. CI runs `npm run check:events` and fails when the
+generated file differs from what `asyncapi.json` produces.
+
+## Reference docs
+
+Every exported shape and field has JSDoc. `npm run docs` validates it into `docs`.
+`npm run create-docs` runs the app SDK's TypeDoc and Mintlify pipeline for this package,
+and `npm run copy-docs-local -- --target <mintlify-docs>` copies the result into
+`developers/references/platform-sdk/docs`. The pipeline's config for this package lives
+in `scripts/mintlify-post-processing/`. The Socket messages page is built in mintlify-docs from
+the service's AsyncAPI document, not here.
+
+`PlatformSocketError` extends `Error` with `code` and optional `appId`. Original
+exceptions, payloads and credentials are never attached.
+
+| Error code | Action |
+| --- | --- |
+| `connection_denied` | The session was rejected even with a fresh token: the workspace, key or session is not usable. |
+| `session_unavailable` | `getSessionToken` failed or timed out; no provider details are forwarded. |
+| `session_replaced` | Another connection with the same session took over. Stop, or open a new session. |
+| `connection_failed` | Transport failure or exhausted retries; call `connect()` after fixing connectivity. |
+| `access_denied` | The join was refused: the app is not on the session's allowlist, or joins were rate limited. |
+| `access_revoked` | The app left the session's allowlist; do not resubscribe. |
+| `snapshot_unavailable` | Joined, but the snapshot failed. Live events still flow; the subscription stays active. |
+| `subscription_limit` | Release a subscription before adding another. |
+| `delivery_overflow` | 1,000 deliveries queued for the app; subscribe again for a fresh snapshot. |
+| `protocol_error` | Invalid routing or envelope. Stop and investigate. |
+| `handler_failed` | An application callback failed; fix it and subscribe again. |
+| `client_closed` | The builder session was explicitly closed; initialize another session. |
+
+No SDK dependency, package version or lockfile changes are required. Socket.IO
+remains the existing SDK dependency. Chat commands and HTTP APIs are outside this entry point.

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import type { PlatformClient, PlatformClientOptions } from "./client.types.js";
+/**
+ * Creates a platform client.
+ *
+ * This is the entry point of the Platform SDK. The client gives your white-label app editor
+ * access to the platform's modules, such as [`builder`](/developers/references/platform-sdk/docs/interfaces/builder).
+ *
+ * @param options - Configuration object for the client.
+ * @returns A configured platform client with access to the platform's modules.
+ * @throws {TypeError} When `socketUrl` isn't an HTTP or HTTPS origin.
+ *
+ * @example
+ * ```typescript
+ * // Create a client for your app editor
+ * import { createPlatformClient } from '@base44/platform';
+ *
+ * const client = createPlatformClient({
+ *   socketUrl,
+ *   async getSessionToken() {
+ *     const response = await fetch('/api/builder-socket-session', { method: 'POST' });
+ *     const { session_token } = await response.json();
+ *     return session_token;
+ *   },
+ * });
+ *
+ * // Use the client to follow the AI chat in an app
+ * const builder = client.builder.init({ onError: (error) => console.error(error.code) });
+ * await builder.connect();
+ * ```
+ */
+export declare function createPlatformClient(options: PlatformClientOptions): PlatformClient;

package/dist/client.js

@@ -0,0 +1,37 @@
+import { createBuilder } from "./modules/builder.js";
+/**
+ * Creates a platform client.
+ *
+ * This is the entry point of the Platform SDK. The client gives your white-label app editor
+ * access to the platform's modules, such as [`builder`](/developers/references/platform-sdk/docs/interfaces/builder).
+ *
+ * @param options - Configuration object for the client.
+ * @returns A configured platform client with access to the platform's modules.
+ * @throws {TypeError} When `socketUrl` isn't an HTTP or HTTPS origin.
+ *
+ * @example
+ * ```typescript
+ * // Create a client for your app editor
+ * import { createPlatformClient } from '@base44/platform';
+ *
+ * const client = createPlatformClient({
+ *   socketUrl,
+ *   async getSessionToken() {
+ *     const response = await fetch('/api/builder-socket-session', { method: 'POST' });
+ *     const { session_token } = await response.json();
+ *     return session_token;
+ *   },
+ * });
+ *
+ * // Use the client to follow the AI chat in an app
+ * const builder = client.builder.init({ onError: (error) => console.error(error.code) });
+ * await builder.connect();
+ * ```
+ */
+export function createPlatformClient(options) {
+    const url = new URL(options.socketUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+        throw new TypeError("socketUrl must be an HTTP(S) origin without credentials, path, query or fragment");
+    }
+    return Object.freeze({ builder: Object.freeze(createBuilder({ ...options, socketUrl: url.origin })) });
+}

package/dist/client.types.d.ts

@@ -0,0 +1,36 @@
+import type { BuilderModule } from "./modules/builder.types.js";
+/**
+ * Options for {@linkcode createPlatformClient | createPlatformClient()}.
+ *
+ * The client runs in the browser and never sees your workspace API key. Your server opens a socket
+ * session with the key and hands the browser only the session's token and socket URL.
+ */
+export interface PlatformClientOptions {
+    /**
+     * Origin of the platform socket.
+     *
+     * Use the `socket_url` your server receives from `POST /api/service/socket-sessions`. It's the same
+     * for every session in an environment, so your server can pass it to the page once. It must be an
+     * origin with no path, query, fragment, or credentials.
+     */
+    socketUrl: string;
+    /**
+     * Returns a socket session token from your server.
+     *
+     * Your server opens a session with `POST /api/service/socket-sessions` and returns its
+     * `session_token`. The client calls this when it connects, and again when the token expires.
+     * Return a new token on every call.
+     *
+     * @returns The session token, or a promise resolving to it.
+     */
+    getSessionToken: () => string | Promise<string>;
+}
+/**
+ * The platform client.
+ *
+ * Provides access to the platform's modules.
+ */
+export interface PlatformClient {
+    /** [Builder module](/developers/references/platform-sdk/docs/interfaces/builder) for following the AI chat in your users' apps live. */
+    readonly builder: BuilderModule;
+}

package/dist/client.types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+import type { PlatformSocketErrorCode } from "./errors.types.js";
+/**
+ * The error the SDK reports when something goes wrong in a builder session.
+ *
+ * You don't create it. The SDK passes it to your `onError` callbacks, `connect()` rejects with it,
+ * and `subscribe()` throws it. Check `code` to see what happened, then look the code up below:
+ * - [Session error codes](#sessionerrorcode) go to the `onError` you pass to `init()`. The whole
+ *   session is affected, and `appId` isn't set.
+ * - [App error codes](#apperrorcode) go to the subscription's `onError`. Only that app is affected,
+ *   and `appId` says which one.
+ *
+ * The error never carries the session token, a callback's exception, or the server's exception text.
+ *
+ * @example
+ * ```typescript
+ * // Handle session and app errors
+ * const builder = client.builder.init({
+ *   // Session error codes: the whole session is affected
+ *   onError(error) {
+ *     if (error.code === 'session_revoked') showSignedOut();
+ *   },
+ * });
+ *
+ * builder.subscribe(appId, {
+ *   onSnapshot: renderChat,
+ *   onEvent: applyEvent,
+ *   // App error codes: only this app is affected, and error.appId says which
+ *   onError(error) {
+ *     if (error.code === 'access_revoked') hideLiveUpdates(error.appId);
+ *   },
+ * });
+ * ```
+ */
+export declare class PlatformSocketError extends Error {
+    /** What happened. One of the [session error codes](#sessionerrorcode) or [app error codes](#apperrorcode). */
+    readonly code: PlatformSocketErrorCode;
+    /** ID of the app the error is about. Set for app error codes, and not set for session error codes. */
+    readonly appId?: string;
+    /**
+     * Creates an error. The SDK creates these; you don't need to.
+     *
+     * @param code - Error code.
+     * @param appId - ID of the app the error is about.
+     * @internal
+     */
+    constructor(code: PlatformSocketErrorCode, appId?: string);
+}

package/dist/errors.js

@@ -0,0 +1,47 @@
+/**
+ * The error the SDK reports when something goes wrong in a builder session.
+ *
+ * You don't create it. The SDK passes it to your `onError` callbacks, `connect()` rejects with it,
+ * and `subscribe()` throws it. Check `code` to see what happened, then look the code up below:
+ * - [Session error codes](#sessionerrorcode) go to the `onError` you pass to `init()`. The whole
+ *   session is affected, and `appId` isn't set.
+ * - [App error codes](#apperrorcode) go to the subscription's `onError`. Only that app is affected,
+ *   and `appId` says which one.
+ *
+ * The error never carries the session token, a callback's exception, or the server's exception text.
+ *
+ * @example
+ * ```typescript
+ * // Handle session and app errors
+ * const builder = client.builder.init({
+ *   // Session error codes: the whole session is affected
+ *   onError(error) {
+ *     if (error.code === 'session_revoked') showSignedOut();
+ *   },
+ * });
+ *
+ * builder.subscribe(appId, {
+ *   onSnapshot: renderChat,
+ *   onEvent: applyEvent,
+ *   // App error codes: only this app is affected, and error.appId says which
+ *   onError(error) {
+ *     if (error.code === 'access_revoked') hideLiveUpdates(error.appId);
+ *   },
+ * });
+ * ```
+ */
+export class PlatformSocketError extends Error {
+    /**
+     * Creates an error. The SDK creates these; you don't need to.
+     *
+     * @param code - Error code.
+     * @param appId - ID of the app the error is about.
+     * @internal
+     */
+    constructor(code, appId) {
+        super(`Platform socket: ${code}`);
+        this.name = "PlatformSocketError";
+        this.code = code;
+        this.appId = appId;
+    }
+}

package/dist/errors.types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Codes of errors that affect the whole session. They go to the `onError` you pass to `init()`, and
+ * `connect()` rejects with them. Retryable means the same call can succeed again without changing anything.
+ */
+export type SessionErrorCode = 
+/**
+ * `getSessionToken` threw, took longer than 20 seconds or returned no token.
+ *
+ * Check the endpoint that opens sessions, then call `connect()` again. Retryable.
+ */
+"session_unavailable"
+/**
+ * Base44 refused the session even with a fresh token: the token is invalid, or live updates aren't enabled for the workspace.
+ *
+ * Check that your server opens a new session on every call. Not retryable.
+ */
+ | "connection_denied"
+/**
+ * The socket couldn't connect after five retries, or the server closed it.
+ *
+ * Call `connect()` again, for example when the tab next gets focus. Retryable.
+ */
+ | "connection_failed"
+/**
+ * Your server or an admin ended the session, or its key lost access.
+ *
+ * Open a new session from your server if the page should still follow apps. Not retryable.
+ */
+ | "session_revoked"
+/**
+ * Another socket connected with the same session token.
+ *
+ * Use one session per tab. Don't reconnect automatically; call `connect()` only to take the session back on purpose. Not retryable.
+ */
+ | "session_replaced"
+/**
+ * A session frame didn't match the protocol.
+ *
+ * Update the SDK, then call `connect()` again. Not retryable.
+ */
+ | "protocol_error"
+/**
+ * You called `connect()` or `subscribe()` after `close()`.
+ *
+ * Create a new session with `init()`. Not retryable.
+ */
+ | "client_closed";
+/**
+ * Codes of errors for one app. They go to the subscription's `onError`, and `subscribe()` throws
+ * `subscription_limit`. Every one ends the subscription except `snapshot_unavailable`.
+ */
+export type AppErrorCode = 
+/**
+ * The app isn't on the session's allowlist, or the socket joins too often.
+ *
+ * Add the app to the session from your server, then subscribe again. Not retryable.
+ */
+"access_denied"
+/**
+ * The app left the session's allowlist, or its workspace.
+ *
+ * Stop showing the app's live updates. Not retryable.
+ */
+ | "access_revoked"
+/**
+ * The subscription is active but its snapshot failed. Events keep arriving.
+ *
+ * Load the app's messages over the Apps API instead.
+ */
+ | "snapshot_unavailable"
+/**
+ * The session already has eight subscriptions.
+ *
+ * Unsubscribe from an app, or open another session. Not retryable.
+ */
+ | "subscription_limit"
+/**
+ * More than 1,000 deliveries waited for your callbacks.
+ *
+ * Make the callbacks faster, then subscribe again for a fresh snapshot. Retryable.
+ */
+ | "delivery_overflow"
+/**
+ * Your `onSnapshot` or `onEvent` callback threw or rejected.
+ *
+ * Fix the callback, then subscribe again. Not retryable.
+ */
+ | "handler_failed"
+/**
+ * An event for this app didn't match the protocol.
+ *
+ * Update the SDK, then subscribe again. Not retryable.
+ */
+ | "protocol_error";
+/** Every code a {@link PlatformSocketError} reports. */
+export type PlatformSocketErrorCode = SessionErrorCode | AppErrorCode;

package/dist/errors.types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/** Browser platform modules, separate from the runtime and server SDKs. */
+export { createPlatformClient } from "./client.js";
+export { PlatformSocketError } from "./errors.js";
+export type { AppErrorCode, PlatformSocketErrorCode, SessionErrorCode } from "./errors.types.js";
+export type { PlatformClient, PlatformClientOptions } from "./client.types.js";
+export type { BuilderModule, BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./modules/builder.types.js";
+export type { GuardApproval, PlatformEvent, PlatformEventMap, PlatformSnapshot, ToolCall } from "./modules/builder.events.types.js";
+export type * from "./modules/builder.events.generated.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+/** Browser platform modules, separate from the runtime and server SDKs. */
+export { createPlatformClient } from "./client.js";
+export { PlatformSocketError } from "./errors.js";

package/dist/modules/builder-protocol.d.ts

@@ -0,0 +1,21 @@
+import type { PlatformEvent, PlatformEventMap, PlatformSnapshot } from "./builder.events.types.js";
+/** App events delivered to `onEvent`: every server event except the session events the socket handles. */
+export declare const eventNames: ("message.updated" | "message.removed" | "app.status_changed" | "preview.reload_requested" | "preview.navigation_requested" | "queue.updated" | "task.progressed" | "image.resolved" | "conversation.changed" | "files.changed" | "branch.deleted" | "repository.changed" | "pull_request.changed")[];
+/** Notices that name an app room, by the error code each one reports. A new notice fails to compile until it has one. */
+export declare const roomNotices: {
+    readonly "room.access_denied": "access_denied";
+    readonly "room.access_revoked": "access_revoked";
+    readonly "room.snapshot_unavailable": "snapshot_unavailable";
+};
+export declare const sessionEndings: {
+    readonly expired: "session_expired";
+    readonly revoked: "session_revoked";
+    readonly replaced: "session_replaced";
+};
+export declare const appPattern: RegExp;
+export declare const roomFor: (appId: string) => string;
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function appFromRoom(value: unknown): string | undefined;
+/** Every event is `{room, data}`; payload schemas are the service's, so only the envelope is validated. */
+export declare function decode(type: keyof PlatformEventMap, appId: string, raw: unknown): PlatformEvent;
+export declare function decodeSnapshot(raw: unknown): PlatformSnapshot;

package/dist/modules/builder-protocol.js

@@ -0,0 +1,39 @@
+import { serverEventNames } from "./builder.events.generated.js";
+const sessionEvents = ["app.snapshot", "session.ended"];
+/** App events delivered to `onEvent`: every server event except the session events the socket handles. */
+export const eventNames = serverEventNames.filter((name) => !sessionEvents.includes(name) && !name.startsWith("room."));
+/** Notices that name an app room, by the error code each one reports. A new notice fails to compile until it has one. */
+export const roomNotices = {
+    "room.access_denied": "access_denied",
+    "room.access_revoked": "access_revoked",
+    "room.snapshot_unavailable": "snapshot_unavailable",
+};
+// `expired` never reaches the partner: the session renews its token.
+export const sessionEndings = {
+    expired: "session_expired",
+    revoked: "session_revoked",
+    replaced: "session_replaced",
+};
+export const appPattern = /^[a-f0-9]{24}$/;
+export const roomFor = (appId) => `/apps/${appId}`;
+export function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid frame");
+    return value;
+}
+export function appFromRoom(value) {
+    return typeof value === "string" && /^\/apps\/[a-f0-9]{24}$/.test(value) ? value.slice(6) : undefined;
+}
+/** Every event is `{room, data}`; payload schemas are the service's, so only the envelope is validated. */
+export function decode(type, appId, raw) {
+    return { type, appId, data: object(object(raw).data) };
+}
+export function decodeSnapshot(raw) {
+    const frame = object(raw);
+    const data = object(frame.data);
+    if (!appFromRoom(frame.room) || !Array.isArray(data.messages) || (data.status !== null && typeof data.status !== "object")) {
+        throw new Error("Invalid snapshot");
+    }
+    const queue = data.queue !== null && typeof data.queue === "object" ? { queue: data.queue } : {};
+    return { room: frame.room, status: data.status, messages: data.messages, ...queue };
+}

package/dist/modules/builder-socket.d.ts

@@ -0,0 +1,42 @@
+import type { PlatformClientOptions } from "../client.types.js";
+import type { BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./builder.types.js";
+/** @internal */
+export declare class BuilderSocket implements BuilderSession {
+    private readonly socket;
+    private readonly subscriptions;
+    private readonly options;
+    private closed;
+    private token?;
+    private tokenFresh;
+    private ending?;
+    private denialRetries;
+    private retryTimer?;
+    private authAttempt;
+    private cancelAuth?;
+    private connecting?;
+    private resolveConnect?;
+    private rejectConnect?;
+    constructor(config: PlatformClientOptions, options: BuilderInitOptions);
+    /** Connect with the session token. Resolves on CONNECT, before snapshots arrive.
+     * Transport loss retries up to five times and rejoins active subscriptions.
+     * Call again after a failure or `session_replaced`; concurrent calls share one attempt.
+     */
+    connect(): Promise<void>;
+    /** Subscribe before or after connecting. One subscription per app, maximum eight, each on the
+     * session's allowlist. Snapshots and events are awaited in order per app; a failed callback,
+     * an invalid frame or a server refusal ends the subscription.
+     */
+    subscribe(appId: string, options: SubscriptionOptions): PlatformSubscription;
+    /** Stop delivery, cancel reconnection and release all listeners. Idempotent and terminal. */
+    close(): void;
+    private join;
+    private authenticate;
+    /** A connect the server refused. Transport errors are Socket.IO's to retry. */
+    private refused;
+    private retryDenied;
+    private clearConnecting;
+    private connectionError;
+    private sessionEnded;
+    private roomNotice;
+    private protocolError;
+}