@base44-preview/platform 0.0.0 → 0.1.0-pr.316.3f570db

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

@@ -0,0 +1,171 @@
+# @base44/platform
+
+```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 { Base44PlatformClient } from "@base44/platform";
+
+const client = new Base44PlatformClient({
+  serverUrl: "https://base44.app",
+  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` to the browser. 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
+
+`new Base44PlatformClient({ serverUrl, 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`): `serverUrl`, `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()`.
+- Event/message models live in `modules/builder.events.types.ts`; error codes in `errors.types.ts`.
+
+Every exported shape and field has JSDoc. Run `npm run docs` for
+validated reference pages in `docs`. `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.
+
+| Event | Data contract |
+| --- | --- |
+| `message.updated` | `MessageUpdated`: the whole `message`, optional `conversation_id`. Replace the message with the same `id`. |
+| `message.removed` | `MessageRemoved`: `message_id`, optional `conversation_id`. Sent when a message is deleted or hidden; an unknown ID is a no-op. |
+| `app.status_changed` | `AppStatusChanged`: `status` (`AppStatus`), null clears it. |
+| `preview.reload_requested` | Reload the app preview. |
+| `preview.navigation_requested` | `PreviewNavigationRequested`: `path`, and `force` to navigate even when the user moved away. |
+| `queue.updated` | `QueueUpdated`: `items`, `is_paused`, optional `processed_item_id`. Replaces the entire queue. |
+| `task.progressed` | `TaskProgressed`: optional `tool_call_id`, `message_id`, `event_type`, numeric `progress`. |
+| `image.resolved` | `ImageResolved`: `placeholder_url`, `status` (`pending`, `completed`, `failed`), nullable `image_url`. Replace the placeholder wherever it appears. |
+| `conversation.changed` | The conversation was rewritten. On main, a fresh snapshot follows. |
+| `files.changed`, `branch.deleted`, `repository.changed`, `pull_request.changed` | Re-read signals with no content. |
+
+`ChatMessage` has optional `id`, `role` (`user`/`assistant`), text/null `content`,
+`tool_calls`, timestamp-only `metadata.created_date`, `checkpoint_id`, and scalar
+`additional_message_params` (`client_creation_id`, `plan_mode`, `plan_approved`,
+`skip_ai_response`, `system_message_type`). `ToolCall` has optional `id`, `name`,
+`status`, `requires_user_input`, `auto_approved`, `mutation_applied` and
+`waiting_on.kind` (`approval`/`choice`/`input`). Each builder tool and guard declares
+which of its parts are public; a tool with no declaration shows only these fields.
+
+| Field | Public contract |
+| --- | --- |
+| `arguments` | One of `ToolQuestionArguments`, `ToolSecretArguments`, `ToolPackageArguments`, `ToolPlanArguments`, `ToolPrdArguments` (`generate_prd`, the plan in plan mode) or `ToolMediaArguments`, narrowed by the tool's `name`. Absent for other tools and partial streaming arguments. |
+| `display` | File activity has `file_paths` and optional `content_empty`; execution activity has `summary` and `writes_entities`; entity activity has `entity_name` and `record_count`. |
+| `user_input` | `ToolQuestionInput` only, for clarifying-question answers (`selected_label` for single-select, `selected_labels` for multi-select). Secret-form values are never exposed. |
+| `results` | Once the call is not waiting on a guard: `ToolMediaResult` for image generation, or a URL string for game images and backgrounds (the placeholder `image.resolved` replaces) and videos (the finished video). |
+| `approval` | While a call waits on a safety guard: `ToolGuardApproval` with `guard`, and `reason` and `details` where the guard declares them (shell-command approvals carry only `guard`). |
+
+In plan mode the message `content` beside a `generate_prd` call can be empty; render the
+plan from its arguments. Approving a plan, answering a question and approving a
+guarded call are HTTP actions of your backend. `Snapshot` contains `room`, `status`
+(`AppStatus`: optional `state` of `ready`/`processing`/`error`, nullable
+`last_updated_date`, and nullable `turn_id`, the user message that started the turn),
+`messages`, and `queue` (`SnapshotQueue`: the main branch's `items` and `is_paused`;
+absent from older servers). Dates remain wire strings. Structural filtering
+does not promise redaction of generated prose or user content.
+
+`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/client.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformClientOptions } from "./client.types.js";
+import type { BuilderModule } from "./modules/builder.types.js";
+/** Browser platform client. Construction creates no sockets, timers or network requests. */
+export declare class Base44PlatformClient {
+    /** Lazy builder subscriptions with independent session lifecycles. */
+    readonly builder: BuilderModule;
+    /** Configure shared service/auth settings; each module initializes its own resources. */
+    constructor(options: PlatformClientOptions);
+}

package/dist/client/client.js

@@ -0,0 +1,9 @@
+import { normalizeServerUrl } from "../shared/server-url.js";
+import { createBuilder } from "./modules/builder.js";
+/** Browser platform client. Construction creates no sockets, timers or network requests. */
+export class Base44PlatformClient {
+    /** Configure shared service/auth settings; each module initializes its own resources. */
+    constructor(options) {
+        this.builder = Object.freeze(createBuilder({ ...options, serverUrl: normalizeServerUrl(options.serverUrl) }));
+    }
+}

package/dist/client/client.types.d.ts

@@ -0,0 +1,12 @@
+/** Shared configuration for browser platform modules. Never supply an API key. */
+export interface PlatformClientOptions {
+    /** Origin of the platform service, e.g. https://base44.app. No path/query/credentials. */
+    serverUrl: string;
+    /**
+     * Return a socket-session token from your backend, which opens the session with its
+     * workspace key (`POST /api/service/socket-sessions`) for the apps this page watches.
+     * Called when a builder session first connects, and again only after the server
+     * rejects or expires the current session. Sessions last one hour.
+     */
+    getSessionToken: () => string | Promise<string>;
+}

package/dist/client/client.types.js

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

package/dist/client/errors.d.ts

@@ -0,0 +1,10 @@
+import type { PlatformSocketErrorCode } from "./errors.types.js";
+/** Sanitized failure. Original session-token provider, handler and server exceptions are not retained. */
+export declare class PlatformSocketError extends Error {
+    /** Stable machine-readable category. */
+    readonly code: PlatformSocketErrorCode;
+    /** Associated app, when the server identifies a valid room. */
+    readonly appId?: string;
+    /** Create a sanitized error with no credential-bearing cause or payload. */
+    constructor(code: PlatformSocketErrorCode, appId?: string);
+}

package/dist/client/errors.js

@@ -0,0 +1,10 @@
+/** Sanitized failure. Original session-token provider, handler and server exceptions are not retained. */
+export class PlatformSocketError extends Error {
+    /** Create a sanitized error with no credential-bearing cause or payload. */
+    constructor(code, appId) {
+        super(`Platform socket: ${code}`);
+        this.name = "PlatformSocketError";
+        this.code = code;
+        this.appId = appId;
+    }
+}

package/dist/client/errors.types.d.ts

@@ -0,0 +1,2 @@
+/** Server refusals and client transport/processing failures. */
+export type PlatformSocketErrorCode = "connection_denied" | "connection_failed" | "session_unavailable" | "session_revoked" | "session_replaced" | "access_denied" | "access_revoked" | "snapshot_unavailable" | "subscription_limit" | "delivery_overflow" | "protocol_error" | "handler_failed" | "client_closed";

package/dist/client/errors.types.js

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

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+/** Browser platform modules, separate from the runtime and server SDKs. */
+export { Base44PlatformClient } from "./client.js";
+export { PlatformSocketError } from "./errors.js";
+export type { PlatformSocketErrorCode } from "./errors.types.js";
+export type { PlatformClientOptions } from "./client.types.js";
+export type { BuilderModule, BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./modules/builder.types.js";
+export type { AppStatus, AppStatusChanged, BranchScoped, ChatMessage, ImageResolved, MessageParams, MessageRemoved, MessageUpdated, PlatformEvent, PlatformEventMap, PreviewNavigationRequested, QueueItem, QueueUpdated, Snapshot, SnapshotQueue, TaskProgressed, ToolArguments, ToolCall, ToolDisplay, ToolEntityMutationArguments, ToolGuardApproval, ToolMediaArguments, ToolMediaResult, ToolPackageArguments, ToolPackageOperation, ToolPlanArguments, ToolPlanUpdate, ToolPrdArguments, ToolQuestion, ToolQuestionAnswer, ToolQuestionArguments, ToolQuestionInput, ToolQuestionOption, ToolSecretArguments, ToolSecretField, } from "./modules/builder.events.types.js";

package/dist/client/index.js

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

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

@@ -0,0 +1,15 @@
+import type { PlatformEvent, PlatformEventMap, Snapshot } from "./builder.events.types.js";
+export declare const eventNames: readonly ["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. */
+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 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): Snapshot;

package/dist/client/modules/builder-protocol.js

@@ -0,0 +1,34 @@
+export 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. */
+export const roomNotices = {
+    "room.access_denied": "access_denied",
+    "room.access_revoked": "access_revoked",
+    "room.snapshot_unavailable": "snapshot_unavailable",
+};
+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/client/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;
+}

package/dist/client/modules/builder-socket.js

@@ -0,0 +1,252 @@
+import { io } from "socket.io-client";
+import { PlatformSocketError } from "../errors.js";
+import { appFromRoom, appPattern, decode, decodeSnapshot, eventNames, object, roomFor, roomNotices } from "./builder-protocol.js";
+import { notify, Subscription } from "./builder-subscription.js";
+const MAX_DENIAL_RETRIES = 5;
+/** @internal */
+export class BuilderSocket {
+    constructor(config, options) {
+        this.subscriptions = new Map();
+        this.closed = false;
+        this.tokenFresh = false;
+        this.denialRetries = 0;
+        this.authAttempt = 0;
+        this.options = { ...config, onError: options.onError };
+        this.socket = io(config.serverUrl, {
+            path: "/ws/socket.io/", transports: ["websocket"], autoConnect: false,
+            forceNew: true, reconnectionAttempts: 5, reconnectionDelay: 1000, reconnectionDelayMax: 10000,
+            timeout: 20000,
+            auth: (callback) => { void this.authenticate(callback); },
+        });
+        this.socket.on("connect", () => {
+            var _a;
+            this.tokenFresh = false;
+            this.denialRetries = 0;
+            for (const subscription of this.subscriptions.values())
+                this.join(subscription);
+            (_a = this.resolveConnect) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.clearConnecting();
+        });
+        this.socket.on("disconnect", (reason) => {
+            ++this.authAttempt;
+            if (this.closed || reason !== "io server disconnect")
+                return; // Transport loss reconnects by itself.
+            const ending = this.ending;
+            this.ending = undefined;
+            if (ending === "session_expired")
+                this.socket.connect(); // Renew through getSessionToken.
+            else
+                this.connectionError(new PlatformSocketError(ending !== null && ending !== void 0 ? ending : "connection_failed"));
+        });
+        this.socket.on("connect_error", (error) => this.refused(error));
+        this.socket.io.on("reconnect_failed", () => this.connectionError(new PlatformSocketError("connection_failed")));
+        this.socket.on("app.snapshot", (raw) => {
+            var _a;
+            try {
+                const snapshot = decodeSnapshot(raw);
+                (_a = this.subscriptions.get(appFromRoom(snapshot.room))) === null || _a === void 0 ? void 0 : _a.snapshot(snapshot);
+            }
+            catch (_b) {
+                this.protocolError(raw);
+            }
+        });
+        this.socket.on("session.ended", (raw) => this.sessionEnded(raw));
+        for (const [name, code] of Object.entries(roomNotices))
+            this.socket.on(name, (raw) => this.roomNotice(code, raw));
+        for (const type of eventNames)
+            this.socket.on(type, (raw) => {
+                try {
+                    const appId = appFromRoom(object(raw).room);
+                    if (!appId)
+                        throw new Error("Invalid app");
+                    const event = decode(type, appId, raw);
+                    const subscription = this.subscriptions.get(appId);
+                    subscription === null || subscription === void 0 ? void 0 : subscription.event(event);
+                    // The server does not resend a snapshot after a rewrite of main: rejoining asks for one.
+                    if (subscription && event.type === "conversation.changed" && event.data.branch_id == null)
+                        this.join(subscription);
+                }
+                catch (_a) {
+                    this.protocolError(raw);
+                }
+            });
+    }
+    /** 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() {
+        if (this.closed)
+            return Promise.reject(new PlatformSocketError("client_closed"));
+        if (this.socket.connected)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        const promise = new Promise((resolve, reject) => {
+            this.resolveConnect = resolve;
+            this.rejectConnect = reject;
+        });
+        this.connecting = promise;
+        this.socket.connect();
+        return promise;
+    }
+    /** 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, options) {
+        if (this.closed)
+            throw new PlatformSocketError("client_closed");
+        if (!appPattern.test(appId))
+            throw new TypeError("appId must be 24 lowercase hexadecimal characters");
+        if (this.subscriptions.has(appId))
+            throw new TypeError("An app may only have one subscription per builder session");
+        if (this.subscriptions.size >= 8)
+            throw new PlatformSocketError("subscription_limit", appId);
+        const subscription = new Subscription(appId, { ...options }, () => {
+            this.subscriptions.delete(appId);
+            if (this.socket.connected)
+                this.socket.emit("leave", roomFor(appId));
+        });
+        this.subscriptions.set(appId, subscription);
+        if (this.socket.connected)
+            this.join(subscription);
+        return subscription;
+    }
+    /** Stop delivery, cancel reconnection and release all listeners. Idempotent and terminal. */
+    close() {
+        var _a, _b;
+        if (this.closed)
+            return;
+        this.closed = true;
+        ++this.authAttempt;
+        (_a = this.cancelAuth) === null || _a === void 0 ? void 0 : _a.call(this);
+        clearTimeout(this.retryTimer);
+        for (const subscription of this.subscriptions.values())
+            subscription.unsubscribe();
+        (_b = this.rejectConnect) === null || _b === void 0 ? void 0 : _b.call(this, new PlatformSocketError("client_closed"));
+        this.clearConnecting();
+        this.socket.removeAllListeners();
+        this.socket.io.removeAllListeners();
+        this.socket.disconnect();
+    }
+    join(subscription) {
+        this.socket.emit("join", roomFor(subscription.appId));
+    }
+    async authenticate(callback) {
+        var _a;
+        const attempt = ++this.authAttempt;
+        (_a = this.cancelAuth) === null || _a === void 0 ? void 0 : _a.call(this);
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("Session token timeout")), 20000);
+            this.cancelAuth = () => { clearTimeout(timer); reject(new Error("Cancelled")); };
+        });
+        try {
+            if (!this.token) {
+                const token = await Promise.race([Promise.resolve().then(() => this.options.getSessionToken()), timeout]);
+                if (this.closed || attempt !== this.authAttempt)
+                    return;
+                if (typeof token !== "string" || !token.trim())
+                    throw new Error("Missing session token");
+                this.token = token;
+                this.tokenFresh = true;
+            }
+            callback({ session_token: this.token });
+        }
+        catch (_b) {
+            if (this.closed || attempt !== this.authAttempt)
+                return;
+            this.socket.disconnect();
+            this.connectionError(new PlatformSocketError("session_unavailable"));
+        }
+        finally {
+            clearTimeout(timer);
+            if (attempt === this.authAttempt)
+                this.cancelAuth = undefined;
+        }
+    }
+    /** A connect the server refused. Transport errors are Socket.IO's to retry. */
+    refused(error) {
+        var _a;
+        if (this.closed || error.message !== "connection_denied")
+            return;
+        if (((_a = error.data) === null || _a === void 0 ? void 0 : _a.retryable) === true) {
+            this.retryDenied();
+            return;
+        }
+        // A token this attempt did not just fetch may have expired: renew it once.
+        const renew = !this.tokenFresh;
+        this.token = undefined;
+        if (renew)
+            this.socket.connect();
+        else
+            this.connectionError(new PlatformSocketError("connection_denied"));
+    }
+    retryDenied() {
+        if (++this.denialRetries > MAX_DENIAL_RETRIES) {
+            this.denialRetries = 0;
+            this.connectionError(new PlatformSocketError("connection_failed"));
+            return;
+        }
+        const delay = Math.min(1000 * 2 ** (this.denialRetries - 1), 10000) * (0.5 + Math.random() / 2);
+        this.retryTimer = setTimeout(() => { this.retryTimer = undefined; if (!this.closed)
+            this.socket.connect(); }, delay);
+    }
+    clearConnecting() {
+        this.connecting = undefined;
+        this.resolveConnect = undefined;
+        this.rejectConnect = undefined;
+    }
+    connectionError(error) {
+        var _a;
+        (_a = this.rejectConnect) === null || _a === void 0 ? void 0 : _a.call(this, error);
+        this.clearConnecting();
+        if (!this.closed)
+            notify(this.options.onError, error);
+    }
+    sessionEnded(raw) {
+        try {
+            const reason = object(object(raw).data).reason;
+            const ending = reason === "expired" ? "session_expired"
+                : reason === "revoked" ? "session_revoked"
+                    : reason === "replaced" ? "session_replaced" : undefined;
+            if (!ending)
+                throw new Error("Unknown reason");
+            // The server disconnects next; the disconnect handler renews or stops.
+            this.token = undefined;
+            this.ending = ending;
+        }
+        catch (_a) {
+            this.protocolError(raw);
+        }
+    }
+    roomNotice(code, raw) {
+        try {
+            const appId = appFromRoom(object(raw).room);
+            if (!appId)
+                throw new Error("Invalid app");
+            const subscription = this.subscriptions.get(appId);
+            if (code === "snapshot_unavailable")
+                subscription === null || subscription === void 0 ? void 0 : subscription.warn(code);
+            else
+                subscription === null || subscription === void 0 ? void 0 : subscription.fail(code);
+        }
+        catch (_a) {
+            this.protocolError(raw);
+        }
+    }
+    protocolError(raw) {
+        var _a;
+        const frame = raw && typeof raw === "object" ? raw : {};
+        const appId = appFromRoom(frame.room);
+        if (appId)
+            (_a = this.subscriptions.get(appId)) === null || _a === void 0 ? void 0 : _a.fail("protocol_error");
+        else {
+            // Unknown routing: no app can be told which update it missed.
+            for (const subscription of [...this.subscriptions.values()])
+                subscription.fail("protocol_error");
+            this.connectionError(new PlatformSocketError("protocol_error"));
+        }
+    }
+}

package/dist/client/modules/builder-subscription.d.ts

@@ -0,0 +1,23 @@
+import type { PlatformEvent, Snapshot } from "./builder.events.types.js";
+import { PlatformSocketError } from "../errors.js";
+import type { PlatformSocketErrorCode } from "../errors.types.js";
+import type { PlatformSubscription, SubscriptionOptions } from "./builder.types.js";
+/** @internal */
+export declare function notify(callback: (error: PlatformSocketError) => void, error: PlatformSocketError): void;
+/** @internal */
+export declare class Subscription implements PlatformSubscription {
+    readonly appId: string;
+    private options;
+    private remove;
+    active: boolean;
+    private pending;
+    private tail;
+    constructor(appId: string, options: SubscriptionOptions, remove: () => void);
+    private enqueue;
+    event(event: PlatformEvent): void;
+    snapshot(snapshot: Snapshot): void;
+    /** A non-fatal problem; the subscription keeps receiving events. */
+    warn(code: PlatformSocketErrorCode): void;
+    fail(code: PlatformSocketErrorCode): void;
+    unsubscribe(): void;
+}

package/dist/client/modules/builder-subscription.js

@@ -0,0 +1,55 @@
+import { PlatformSocketError } from "../errors.js";
+/** @internal */
+export function notify(callback, error) {
+    try {
+        callback(error);
+    }
+    catch ( /* An error observer cannot interrupt other app subscriptions. */_a) { /* An error observer cannot interrupt other app subscriptions. */ }
+}
+/** @internal */
+export class Subscription {
+    constructor(appId, options, remove) {
+        this.appId = appId;
+        this.options = options;
+        this.remove = remove;
+        this.active = true;
+        this.pending = 0;
+        this.tail = Promise.resolve();
+    }
+    enqueue(work) {
+        if (!this.active)
+            return;
+        if (this.pending >= 1000) {
+            this.fail("delivery_overflow");
+            return;
+        }
+        this.pending++;
+        this.tail = this.tail.then(async () => {
+            if (this.active)
+                await work();
+        }).catch(() => this.fail("handler_failed")).finally(() => { this.pending--; });
+    }
+    event(event) {
+        this.enqueue(() => this.options.onEvent(event));
+    }
+    snapshot(snapshot) {
+        this.enqueue(() => this.options.onSnapshot(snapshot));
+    }
+    /** A non-fatal problem; the subscription keeps receiving events. */
+    warn(code) {
+        if (this.active)
+            notify(this.options.onError, new PlatformSocketError(code, this.appId));
+    }
+    fail(code) {
+        if (!this.active)
+            return;
+        this.unsubscribe();
+        notify(this.options.onError, new PlatformSocketError(code, this.appId));
+    }
+    unsubscribe() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.remove();
+    }
+}

package/dist/client/modules/builder.d.ts

@@ -0,0 +1,4 @@
+import type { PlatformClientOptions } from "../client.types.js";
+import type { BuilderModule } from "./builder.types.js";
+/** @internal */
+export declare function createBuilder(config: PlatformClientOptions): BuilderModule;

package/dist/client/modules/builder.events.types.d.ts

@@ -0,0 +1,368 @@
+/** Activity a file, execution or entity tool declared public. */
+export interface ToolDisplay {
+    /** Changed file paths for a file operation. Source bodies and diffs are never included. */
+    file_paths?: string[];
+    /** Whether a file write intentionally used empty content. */
+    content_empty?: boolean;
+    /** Reviewed execution activity summary. Commands and execution output are never included. */
+    summary?: string;
+    /** Whether a reviewed execution action changed entity data. */
+    writes_entities?: boolean;
+    /** Entity type affected by an entity operation. Records and query values are never included. */
+    entity_name?: string;
+    /** Number of records affected when supplied by the producer. */
+    record_count?: number;
+}
+/** A selectable answer to a builder question. */
+export interface ToolQuestionOption {
+    /** Visible option label. */
+    label?: string;
+}
+/** A builder question. Image/HTML source and private design context are excluded. */
+export interface ToolQuestion {
+    /** Visible question text. */
+    question?: string;
+    /** Question category. */
+    type?: string;
+    /** Optional visible supporting text. */
+    description?: string;
+    /** Whether more than one answer may be selected. */
+    multi_select?: boolean;
+    /** Plan section the question covers. */
+    covers?: string;
+    /** Selectable options; a bare string option is its label. */
+    options?: (ToolQuestionOption | string)[];
+}
+/** `ask_clarifying_questions` and `ask_plan_questions` arguments. */
+export interface ToolQuestionArguments {
+    /** Questions presented to the user. */
+    questions?: ToolQuestion[];
+}
+/** A requested secret field. The secret value is never sent over the socket. */
+export interface ToolSecretField {
+    /** Requested secret name. */
+    secretName?: string;
+    /** Optional explanation of where to obtain it. */
+    description?: string;
+}
+/** `set_secrets` arguments. */
+export interface ToolSecretArguments {
+    /** Requested secret fields. */
+    secrets_schema?: ToolSecretField[];
+}
+/** A package operation. Versions and package-manager output are excluded. */
+export interface ToolPackageOperation {
+    /** Package name. */
+    name?: string;
+    /** Requested package operation. */
+    action?: string;
+}
+/** `install_npm_package` arguments. */
+export interface ToolPackageArguments {
+    /** Requested package operations. */
+    packages?: ToolPackageOperation[];
+}
+/** An add-only builder plan update. */
+export interface ToolPlanUpdate {
+    /** Update action. */
+    action?: string;
+    /** Plan section key. */
+    section?: string;
+    /** Optional user-facing section label. */
+    section_label?: string;
+    /** Plan point. */
+    text?: string;
+}
+/** `update_plan` arguments. */
+export interface ToolPlanArguments {
+    /** Plan updates in their emitted order. */
+    updates?: ToolPlanUpdate[];
+    /** Base plan sections the builder considers sufficiently specified. */
+    sections_with_enough?: string[];
+}
+/** `generate_prd` arguments: the user's own plan. In plan mode the message `content` beside it can be empty. */
+export interface ToolPrdArguments {
+    /** App or feature name. */
+    app_name?: string;
+    /** What is being built and why. */
+    intent_and_goal?: string;
+    /** Who uses it and their roles. */
+    audience_and_roles?: string;
+    /** End-to-end user flows. */
+    core_flows?: string[];
+    /** Specific technical requirements. */
+    technical_requirements?: string;
+    /** Design preferences. */
+    design_preferences?: string;
+    /** Build or plan declaration, when the builder asks for one. */
+    prd_type?: string;
+    /** Store platform settled in planning, for e-commerce plans. */
+    store_platform?: string;
+    /** Engine settled in planning, for game plans. */
+    game_engine?: string;
+}
+/** Image, game-image and video generation arguments. */
+export interface ToolMediaArguments {
+    /** Visible media label. */
+    label?: string;
+    /** Requested image or video aspect ratio. */
+    aspect_ratio?: string;
+}
+/** `update_entities` and `delete_entities` arguments; the entity is in `display.entity_name`. */
+export interface ToolEntityMutationArguments {
+    /** The agent's summary of the change. Queries and record values are never included. */
+    summary?: string;
+}
+/** The public arguments of a tool that declares them; narrow by the tool call's `name`. */
+export type ToolArguments = ToolQuestionArguments | ToolSecretArguments | ToolPackageArguments | ToolPlanArguments | ToolPrdArguments | ToolMediaArguments | ToolEntityMutationArguments;
+/** Generated-media state. Raw generation prompts and IDs are never included. */
+export interface ToolMediaResult {
+    /** Placeholder URL, used to associate an `image.resolved` event with this tool. */
+    placeholder_url?: string;
+    /** Current media-generation status. */
+    status?: "pending" | "completed" | "failed";
+    /** Generated asset URL, once available. */
+    image_url?: string | null;
+}
+/** An answer to a clarifying question. Secret-form input is never included. */
+export interface ToolQuestionAnswer {
+    /** Zero-based question index. */
+    question_index?: number;
+    /** Label selected for a single-select question. */
+    selected_label?: string;
+    /** Labels selected for a multi-select question. */
+    selected_labels?: string[];
+    /** User-provided free-text answer. Structural filtering does not redact prose. */
+    custom_text?: string;
+}
+/** Clarifying-question answers. */
+export interface ToolQuestionInput {
+    /** Answers supplied to the question card. */
+    answers?: ToolQuestionAnswer[];
+}
+/** Why a safety guard parked a call for approval. Only present while the call waits. */
+export interface ToolGuardApproval {
+    /** Guard identifier, e.g. `exec_tool_send_email` or `bash_approval`. */
+    guard: string;
+    /** Human-readable reason, for guards whose reason never quotes input (not shell commands). */
+    reason?: string;
+    /** The details the guard declares public; commands and record data are never included. */
+    details?: {
+        /** Entity method the code calls, e.g. `delete`. */
+        method?: string;
+        /** The agent's summary of what the code does. */
+        summary?: string;
+        /** Entity whose access rules change. */
+        entity_name?: string;
+        /** How the access rules change. */
+        change_type?: string;
+        /** Access operations whose rules change. */
+        changed_ops?: string[];
+        /** Backend function under test. */
+        function_name?: string;
+        /** The guard could not verify the function's source. */
+        inspection_failed?: boolean;
+    };
+}
+/** Public progress of a builder tool call. Only what the tool and its guard declare public is present. */
+export interface ToolCall {
+    /** Stable tool call identifier. */
+    id?: string;
+    /** Tool name. */
+    name?: string;
+    /** Current execution state. */
+    status?: "running" | "success" | "error" | "stopped" | "waiting_for_user_input";
+    /** Whether the tool needs a user response through the partner backend. */
+    requires_user_input?: boolean;
+    /** Whether the builder auto-approved the operation. */
+    auto_approved?: boolean;
+    /** Whether the mutation was applied. */
+    mutation_applied?: boolean | null;
+    /** Kind of response a parked call waits for. */
+    waiting_on?: {
+        /** Kind of response expected. */
+        kind?: "approval" | "choice" | "input";
+    };
+    /** The tool's public arguments; absent for tools that declare none and for partial streaming arguments. */
+    arguments?: ToolArguments;
+    /** What a file, execution or entity tool touched. */
+    display?: ToolDisplay;
+    /** Clarifying-question answers. */
+    user_input?: ToolQuestionInput;
+    /** Generated media, once the call is not waiting on a guard: the image tool's state, or a URL alone
+     * (a game asset's placeholder, which `image.resolved` replaces, or a finished video). */
+    results?: ToolMediaResult | string;
+    /** A parked call's guard, and its reason and details where the guard declares them. */
+    approval?: ToolGuardApproval;
+}
+/** Scalar parameters a chat UI needs while a turn runs. */
+export interface MessageParams {
+    /** Identifier the sending client attached, to match its optimistic message. */
+    client_creation_id?: string;
+    /** The message was sent in plan mode. */
+    plan_mode?: boolean;
+    /** The message approves a plan. */
+    plan_approved?: boolean;
+    /** The message expects no AI reply. */
+    skip_ai_response?: boolean;
+    /** System message category. */
+    system_message_type?: string;
+}
+/** A public chat message. Replace the message with the same `id` as a whole. */
+export interface ChatMessage {
+    /** Message identifier. */
+    id?: string;
+    /** Author category. System and hidden messages are never delivered. */
+    role?: "user" | "assistant";
+    /** Message text; structured content is withheld. Structural filtering is not prose redaction. */
+    content?: string | null;
+    /** Public tool progress. */
+    tool_calls?: ToolCall[] | null;
+    /** Message timestamp, without author identity. */
+    metadata?: {
+        /** ISO timestamp string. */
+        created_date?: string;
+    };
+    /** Checkpoint reference; mutations remain on the partner backend. */
+    checkpoint_id?: string | null;
+    /** Scalar message parameters. */
+    additional_message_params?: MessageParams;
+}
+/** Public builder state, without error diagnostics or billing context. */
+export interface AppStatus {
+    /** Current builder state. */
+    state?: "ready" | "processing" | "error";
+    /** State timestamp. */
+    last_updated_date?: string | null;
+    /** The user message that started the turn, when a turn set this state. Quote it to Base44 support. */
+    turn_id?: string | null;
+}
+/** Branch scope carried by app events. Null or absent is the main branch. */
+export interface BranchScoped {
+    /** Branch the change belongs to; null is main. */
+    branch_id?: string | null;
+}
+/** `message.updated`: a chat message was added or replaced. */
+export interface MessageUpdated extends BranchScoped {
+    /** The whole message; replace the one with the same `id`. */
+    message: ChatMessage;
+    /** Conversation containing the message. */
+    conversation_id?: string | null;
+}
+/** `message.removed`: a message was removed or hidden. An `id` the viewer never saw is a no-op. */
+export interface MessageRemoved extends BranchScoped {
+    /** Identifier of the message to remove. */
+    message_id: string;
+    /** Conversation that contained the message. */
+    conversation_id?: string | null;
+}
+/** `app.status_changed`: a turn started, finished or failed. */
+export interface AppStatusChanged extends BranchScoped {
+    /** The new state; null clears it. */
+    status: AppStatus | null;
+}
+/** `preview.navigation_requested`: show this page of the app in the preview. */
+export interface PreviewNavigationRequested extends BranchScoped {
+    /** App path to show. */
+    path: string;
+    /** Navigate even when the user has moved away from the page. */
+    force: boolean;
+}
+/** A queued builder request. */
+export interface QueueItem {
+    /** Queue item identifier. */
+    id?: string;
+    /** User-authored request text. */
+    content?: string;
+    /** Creation timestamp. */
+    created_at?: string;
+    /** Branch the request belongs to. */
+    branch_id?: string | null;
+}
+/** `queue.updated`: the whole prompt queue, replacing the previous one. */
+export interface QueueUpdated extends BranchScoped {
+    /** Pending items. */
+    items?: QueueItem[];
+    /** Whether queue processing is paused. */
+    is_paused?: boolean;
+    /** Identifier of the item just processed, when supplied. */
+    processed_item_id?: string | null;
+}
+/** `task.progressed`: progress of a long-running tool. */
+export interface TaskProgressed extends BranchScoped {
+    /** Associated tool call. */
+    tool_call_id?: string | null;
+    /** Associated chat message. */
+    message_id?: string | null;
+    /** Task lifecycle event, e.g. `task_progress`. */
+    event_type?: string | null;
+    /** Numeric progress only; diagnostic text is withheld. */
+    progress?: {
+        /** Completed work units. */
+        current?: number | null;
+        /** Total work units, when known. */
+        total?: number | null;
+        /** Producer-supplied percentage. */
+        percentage?: number | null;
+    } | null;
+}
+/** `image.resolved`: a generated image finished or failed. Replace its `placeholder_url` wherever it appears. */
+export type ImageResolved = ToolMediaResult;
+/** Mapping of public event names to their payloads. */
+export interface PlatformEventMap {
+    /** A chat message was added or replaced. */
+    "message.updated": MessageUpdated;
+    /** A chat message was removed or hidden. */
+    "message.removed": MessageRemoved;
+    /** The builder started, finished or failed a turn. */
+    "app.status_changed": AppStatusChanged;
+    /** Reload the app preview. */
+    "preview.reload_requested": BranchScoped;
+    /** Show a page of the app in the preview. */
+    "preview.navigation_requested": PreviewNavigationRequested;
+    /** The whole prompt queue. */
+    "queue.updated": QueueUpdated;
+    /** Progress of a long-running tool. */
+    "task.progressed": TaskProgressed;
+    /** A generated image finished or failed. */
+    "image.resolved": ImageResolved;
+    /** The conversation was rewritten (undo, restore, sync). On main, the SDK rejoins for a fresh snapshot. */
+    "conversation.changed": BranchScoped;
+    /** The app's files changed outside a chat turn. Re-read them. */
+    "files.changed": BranchScoped;
+    /** A branch was deleted. */
+    "branch.deleted": BranchScoped;
+    /** The imported app's repository changed. */
+    "repository.changed": BranchScoped;
+    /** The imported app's pull request changed. */
+    "pull_request.changed": BranchScoped;
+}
+/** Ordered delivery of one public event. */
+export type PlatformEvent = {
+    [K in keyof PlatformEventMap]: {
+        /** Public event name; narrows the payload type. */
+        type: K;
+        /** Authorized app receiving this event. */
+        appId: string;
+        /** Event payload. Omitted keys mean unchanged; explicit null clears. */
+        data: PlatformEventMap[K];
+    };
+}[keyof PlatformEventMap];
+/** An app's current state: sent after every join and rejoin, and after a main-conversation rewrite. */
+export interface Snapshot {
+    /** Canonical app room. */
+    room: string;
+    /** Current builder state. */
+    status: AppStatus | null;
+    /** The last 50 public messages, oldest first. */
+    messages: ChatMessage[];
+    /** The main branch's prompt queue. Replace it, as with `queue.updated`. Absent from older servers. */
+    queue?: SnapshotQueue;
+}
+/** The prompt queue in a snapshot. */
+export interface SnapshotQueue {
+    /** Pending items. */
+    items: QueueItem[];
+    /** Whether queue processing is paused. */
+    is_paused: boolean;
+}

package/dist/client/modules/builder.events.types.js

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

package/dist/client/modules/builder.js

@@ -0,0 +1,7 @@
+import { BuilderSocket } from "./builder-socket.js";
+/** @internal */
+export function createBuilder(config) {
+    return {
+        init(options) { return new BuilderSocket(config, options); },
+    };
+}

package/dist/client/modules/builder.types.d.ts

@@ -0,0 +1,47 @@
+import type { PlatformEvent, Snapshot } from "./builder.events.types.js";
+import type { PlatformSocketError } from "../errors.js";
+/** Options for an independent builder socket session. */
+export interface BuilderInitOptions {
+    /** Connection-level errors, sanitized to exclude tokens and server exception text. */
+    onError: (error: PlatformSocketError) => void;
+}
+/** Lazy builder module; no socket exists until init is called. */
+export interface BuilderModule {
+    /** Create an independent session without connecting. Call connect on the returned session. */
+    init(options: BuilderInitOptions): BuilderSession;
+}
+/** One builder socket session. Owns its subscriptions and connection lifecycle. */
+export interface BuilderSession {
+    /** Connect with the session token; resolves on CONNECT, before snapshots arrive.
+     * Transport loss retries five times and rejoins active subscriptions, each with a fresh
+     * snapshot. An expired or rejected session is replaced once through `getSessionToken`.
+     * 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, up to eight per session,
+     * and each app must be on the session's allowlist. Callbacks run serially per app.
+     */
+    subscribe(appId: string, options: SubscriptionOptions): PlatformSubscription;
+    /** Stop this session, its subscriptions and reconnection. Idempotent and terminal. */
+    close(): void;
+}
+/** One app subscription; at most eight may be active per builder session. */
+export interface SubscriptionOptions {
+    /** Replace this app's state. Arrives after every join and rejoin, and after a main-conversation
+     * rewrite (undo, restore, sync). Live events follow it; it holds only the last 50 messages.
+     */
+    onSnapshot: (snapshot: Snapshot) => void | Promise<void>;
+    /** Apply each live event. Delivery is serial per app; a rejection ends this subscription. */
+    onEvent: (event: PlatformEvent) => void | Promise<void>;
+    /** Subscription errors. Only `snapshot_unavailable` leaves the subscription active. */
+    onError: (error: PlatformSocketError) => void;
+}
+/** One app subscription's lifetime. */
+export interface PlatformSubscription {
+    /** App identifier. */
+    readonly appId: string;
+    /** True while subscribed; false after an error or explicit unsubscribe. */
+    readonly active: boolean;
+    /** Stop this app's delivery and release its subscription slot. Idempotent. */
+    unsubscribe(): void;
+}

package/dist/client/modules/builder.types.js

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

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+/** Server platform modules, authenticated with a workspace API key. */
+export { createBase44PlatformServer } from "./server.js";
+export type { Base44PlatformServer, PlatformServerOptions } from "./server.types.js";

package/dist/server/index.js

@@ -0,0 +1,2 @@
+/** Server platform modules, authenticated with a workspace API key. */
+export { createBase44PlatformServer } from "./server.js";

package/dist/server/server.d.ts

@@ -0,0 +1,3 @@
+import type { Base44PlatformServer, PlatformServerOptions } from "./server.types.js";
+/** Create a server platform client, authenticated with a workspace API key. Performs no network requests. */
+export declare function createBase44PlatformServer(options: PlatformServerOptions): Base44PlatformServer;

package/dist/server/server.js

@@ -0,0 +1,8 @@
+import { normalizeServerUrl } from "../shared/server-url.js";
+/** Create a server platform client, authenticated with a workspace API key. Performs no network requests. */
+export function createBase44PlatformServer(options) {
+    if (!options.apiKey)
+        throw new TypeError("apiKey is required");
+    normalizeServerUrl(options.serverUrl);
+    return Object.freeze({});
+}

package/dist/server/server.types.d.ts

@@ -0,0 +1,10 @@
+/** Shared configuration for server platform modules. */
+export interface PlatformServerOptions {
+    /** Origin of the platform service, e.g. https://base44.app. No path/query/credentials. */
+    serverUrl: string;
+    /** Workspace API key. Keep it on your server; never ship it to a browser. */
+    apiKey: string;
+}
+/** Server platform client, returned by `createBase44PlatformServer`. Modules are added as properties. */
+export interface Base44PlatformServer {
+}

package/dist/server/server.types.js

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

package/dist/shared/server-url.d.ts

@@ -0,0 +1,2 @@
+/** Validate a platform origin and return it normalized. Shared by the client and server entrypoints. */
+export declare function normalizeServerUrl(serverUrl: string): string;

package/dist/shared/server-url.js

@@ -0,0 +1,8 @@
+/** Validate a platform origin and return it normalized. Shared by the client and server entrypoints. */
+export function normalizeServerUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+        throw new TypeError("serverUrl must be an HTTP(S) origin without credentials, path, query or fragment");
+    }
+    return url.origin;
+}

package/package.json

@@ -1,7 +1,60 @@
 {
   "name": "@base44-preview/platform",
-  "version": "0.0.0",
-  "description": "Preview builds of @base44/platform, published from PRs. Not for production use.",
+  "version": "0.1.0-pr.316.3f570db",
+  "description": "Client and server SDK for building on the Base44 platform",
+  "main": "dist/client/index.js",
+  "types": "dist/client/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "docs": "typedoc",
+    "test": "npm run test:types && npm run test:unit && npm run docs && npm run test:package",
+    "test:types": "tsc --noEmit -p tsconfig.type-tests.json",
+    "test:unit": "vitest run",
+    "test:package": "npm run build && node --test tests/package.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "keywords": [
+    "base44",
+    "platform",
+    "white-label"
+  ],
+  "author": "Base44",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/base44/javascript-sdk.git", "directory": "packages/platform" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/base44/javascript-sdk.git",
+    "directory": "packages/platform"
+  },
+  "bugs": {
+    "url": "https://github.com/base44/javascript-sdk/issues"
+  },
+  "homepage": "https://github.com/base44/javascript-sdk/tree/main/packages/platform#readme",
+  "typesVersions": {
+    "*": {
+      "server": [
+        "dist/server/index.d.ts"
+      ]
+    }
+  }
 }