@base44-preview/sdk 0.8.48-pr.284.e0a8d2f → 0.8.48-pr.286.d14ea24

package/README.md

@@ -151,3 +151,12 @@ npm run create-docs
 cd docs
 mintlify dev
 ```
+
+### Platform browser subscriptions
+
+The separate `@base44/sdk/platform/client` entry point subscribes to public builder
+updates through the white-label socket. It supports typed events, bounded delivery,
+and reconnect replay using browser credentials supplied by your backend.
+See [setup, public contract and recovery](platform-docs/client.md) and the
+[TypeScript example](examples/platform-client.ts). Backend token integration and
+workspace rollout are prerequisites; never use an API key in the browser.

package/dist/platform/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/platform/client/client.js

@@ -0,0 +1,12 @@
+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) {
+        const url = new URL(options.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");
+        }
+        this.builder = Object.freeze(createBuilder({ ...options, serverUrl: url.origin }));
+    }
+}

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

@@ -0,0 +1,7 @@
+/** 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;
+    /** Refresh a browser credential through your backend; called on every builder connection attempt. */
+    refreshToken: () => string | Promise<string>;
+}

package/dist/platform/client/client.types.js

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

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

@@ -0,0 +1,10 @@
+import type { PlatformSocketErrorCode } from "./errors.types.js";
+/** Sanitized failure. Original 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/platform/client/errors.js

@@ -0,0 +1,10 @@
+/** Sanitized failure. Original 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/platform/client/errors.types.d.ts

@@ -0,0 +1,2 @@
+/** Server subscription failures and client transport/processing failures. */
+export type PlatformSocketErrorCode = "invalid_room" | "invalid_cursor" | "access_denied" | "subscription_limit" | "resync_required" | "stream_unavailable" | "connection_denied" | "connection_failed" | "token_unavailable" | "protocol_error" | "handler_failed" | "client_closed";

package/dist/platform/client/errors.types.js

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

package/dist/platform/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 { AppUpdate, ChatMessage, ToolCall, ToolDisplayProjection, ToolQuestionOption, ToolQuestion, ToolQuestionArguments, ToolSecretField, ToolSecretArguments, ToolPackageOperation, ToolPackageArguments, ToolPlanUpdate, ToolPlanArguments, ToolMediaArguments, ToolQuestionAnswer, ToolQuestionInput, ToolOutcome, QueueItem, QueueUpdate, TaskUpdate, ImageReady, Directive, PlatformEventMap, PlatformEvent, Joined } from "./modules/builder.events.types.js";

package/dist/platform/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/platform/client/modules/builder-protocol.d.ts

@@ -0,0 +1,11 @@
+import type { Joined, PlatformEvent, PlatformEventMap } from "./builder.events.types.js";
+export declare const eventNames: readonly ["update_model", "directive", "queue_update", "task_update", "image_ready"];
+export declare const errorCodes: readonly ["invalid_room", "invalid_cursor", "access_denied", "subscription_limit", "resync_required", "stream_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 string(value: unknown): string;
+export declare function appFromRoom(value: unknown): string | undefined;
+export declare function eventApp(type: keyof PlatformEventMap, raw: unknown): string | undefined;
+export declare function decode(type: keyof PlatformEventMap, appId: string, raw: unknown): PlatformEvent;
+export declare function decodeJoined(raw: unknown): Joined;

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

@@ -0,0 +1,39 @@
+export const eventNames = ["update_model", "directive", "queue_update", "task_update", "image_ready"];
+export const errorCodes = ["invalid_room", "invalid_cursor", "access_denied", "subscription_limit", "resync_required", "stream_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 string(value) {
+    if (typeof value !== "string" || !value)
+        throw new Error("Invalid string");
+    return value;
+}
+export function appFromRoom(value) {
+    return typeof value === "string" && /^\/apps\/[a-f0-9]{24}$/.test(value) ? value.slice(6) : undefined;
+}
+export function eventApp(type, raw) {
+    const frame = object(raw);
+    return type === "queue_update"
+        ? typeof frame.app_id === "string" && appPattern.test(frame.app_id) ? frame.app_id : undefined
+        : appFromRoom(frame.room);
+}
+export function decode(type, appId, raw) {
+    const frame = object(raw);
+    const seq = string(frame.seq);
+    const wrapped = type === "update_model" || type === "task_update" || type === "image_ready";
+    const { seq: _, ...flat } = frame;
+    const data = wrapped ? object(JSON.parse(string(frame.data))) : flat;
+    // Payload schemas are owned by the service; only decode/validate the transport envelope here.
+    return { type, appId, seq, data };
+}
+export function decodeJoined(raw) {
+    const frame = object(raw);
+    if (!appFromRoom(frame.room) || !Number.isInteger(frame.max_entries) || !Number.isInteger(frame.inactivity_expiry_seconds))
+        throw new Error("Invalid boundary");
+    string(frame.seq);
+    return frame;
+}

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

@@ -0,0 +1,35 @@
+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 needsFreshConnection;
+    private generation;
+    private authAttempt;
+    private cancelAuth?;
+    private connecting?;
+    private resolveConnect?;
+    private rejectConnect?;
+    constructor(config: PlatformClientOptions, options: BuilderInitOptions);
+    /** Connect using a freshly obtained token. Resolves on CONNECT, not on app replay completion.
+     * Unexpected transport loss retries up to five times and rejoins active subscriptions.
+     * Call again after addressing a connection/auth failure; concurrent calls share one attempt.
+     */
+    connect(): Promise<void>;
+    /** Subscribe before or after connecting. One subscription per app, maximum eight.
+     * Events and boundary callbacks are awaited in order per app. Failed application,
+     * invalid frames or server errors end the subscription without advancing its cursor.
+     */
+    subscribe(appId: string, options: SubscriptionOptions): PlatformSubscription;
+    /** Stop delivery, cancel reconnection and release all listeners. Idempotent and terminal. */
+    close(): void;
+    private join;
+    private authenticate;
+    private clearConnecting;
+    private connectionError;
+    private serverError;
+    private protocolError;
+}

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

@@ -0,0 +1,213 @@
+import { io } from "socket.io-client";
+import { PlatformSocketError } from "../errors.js";
+import { appFromRoom, appPattern, decode, decodeJoined, errorCodes, eventApp, eventNames, object, roomFor } from "./builder-protocol.js";
+import { notify, Subscription } from "./builder-subscription.js";
+/** @internal */
+export class BuilderSocket {
+    constructor(config, options) {
+        this.subscriptions = new Map();
+        this.closed = false;
+        this.needsFreshConnection = false;
+        this.generation = 0;
+        this.authAttempt = 0;
+        this.options = { ...config, onError: options.onError };
+        this.socket = io(`${config.serverUrl}/partner`, {
+            path: "/ws-whitelabel/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;
+            const generation = ++this.generation;
+            this.needsFreshConnection = false;
+            for (const subscription of this.subscriptions.values())
+                this.join(subscription, generation);
+            (_a = this.resolveConnect) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.clearConnecting();
+        });
+        this.socket.on("disconnect", (reason) => {
+            ++this.generation;
+            ++this.authAttempt;
+            if (reason === "io server disconnect")
+                this.connectionError(new PlatformSocketError("connection_failed"));
+        });
+        this.socket.on("connect_error", (error) => {
+            var _a;
+            this.connectionError(new PlatformSocketError(((_a = error.data) === null || _a === void 0 ? void 0 : _a.code) === "connection_denied" ? "connection_denied" : "connection_failed"));
+        });
+        this.socket.io.on("reconnect_failed", () => this.connectionError(new PlatformSocketError("connection_failed")));
+        this.socket.on("joined", (raw) => {
+            var _a;
+            try {
+                const joined = decodeJoined(raw);
+                (_a = this.subscriptions.get(appFromRoom(joined.room))) === null || _a === void 0 ? void 0 : _a.joined(joined);
+            }
+            catch (_b) {
+                this.protocolError(raw);
+            }
+        });
+        this.socket.on("error", (raw) => this.serverError(raw));
+        for (const type of eventNames)
+            this.socket.on(type, (raw) => {
+                var _a;
+                try {
+                    const appId = eventApp(type, raw);
+                    if (!appId)
+                        throw new Error("Invalid app");
+                    (_a = this.subscriptions.get(appId)) === null || _a === void 0 ? void 0 : _a.event(decode(type, appId, raw));
+                }
+                catch (_b) {
+                    this.protocolError(raw);
+                }
+            });
+    }
+    /** Connect using a freshly obtained token. Resolves on CONNECT, not on app replay completion.
+     * Unexpected transport loss retries up to five times and rejoins active subscriptions.
+     * Call again after addressing a connection/auth failure; 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.
+     * Events and boundary callbacks are awaited in order per app. Failed application,
+     * invalid frames or server errors end the subscription without advancing its cursor.
+     */
+    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 (options.afterSeq !== undefined && (typeof options.afterSeq !== "string" || !options.afterSeq))
+            throw new TypeError("afterSeq must be a nonempty opaque cursor");
+        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);
+            this.needsFreshConnection = true;
+            if (this.socket.connected)
+                this.socket.emit("leave", roomFor(appId));
+        });
+        this.subscriptions.set(appId, subscription);
+        if (this.socket.connected && this.needsFreshConnection) {
+            // Leave has no acknowledgement; a new transport fences late events from retired streams.
+            this.socket.disconnect();
+            void this.connect().catch(() => { }); // Connection errors are delivered through onError.
+        }
+        else if (this.socket.connected) {
+            this.join(subscription, this.generation);
+        }
+        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);
+        ++this.generation;
+        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, generation) {
+        subscription.join((cursor) => {
+            if (this.socket.connected && generation === this.generation) {
+                this.socket.emit("join", roomFor(subscription.appId), cursor === undefined ? {} : { after_seq: cursor });
+            }
+        });
+    }
+    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("Token timeout")), 20000);
+            this.cancelAuth = () => { clearTimeout(timer); reject(new Error("Cancelled")); };
+        });
+        try {
+            const token = await Promise.race([Promise.resolve().then(() => this.options.refreshToken()), timeout]);
+            if (this.closed || attempt !== this.authAttempt)
+                return;
+            if (typeof token !== "string" || !token.trim())
+                throw new Error("Missing token");
+            callback({ token });
+        }
+        catch (_b) {
+            if (this.closed || attempt !== this.authAttempt)
+                return;
+            this.socket.disconnect();
+            this.connectionError(new PlatformSocketError("token_unavailable"));
+        }
+        finally {
+            clearTimeout(timer);
+            if (attempt === this.authAttempt)
+                this.cancelAuth = undefined;
+        }
+    }
+    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);
+    }
+    serverError(raw) {
+        var _a;
+        try {
+            const frame = object(raw);
+            const code = errorCodes.find((code) => code === frame.code);
+            if (!code)
+                throw new Error("Unknown error");
+            const appId = appFromRoom(frame.room);
+            if (appId)
+                (_a = this.subscriptions.get(appId)) === null || _a === void 0 ? void 0 : _a.fail(code);
+            else if (frame.room === null)
+                this.connectionError(new PlatformSocketError(code));
+            else
+                throw new Error("Invalid room");
+        }
+        catch (_b) {
+            this.protocolError(raw);
+        }
+    }
+    protocolError(raw) {
+        var _a, _b;
+        const frame = raw && typeof raw === "object" ? raw : {};
+        const appId = (_a = appFromRoom(frame.room)) !== null && _a !== void 0 ? _a : (typeof frame.app_id === "string" && appPattern.test(frame.app_id) ? frame.app_id : undefined);
+        if (appId)
+            (_b = this.subscriptions.get(appId)) === null || _b === void 0 ? void 0 : _b.fail("protocol_error");
+        else {
+            // Unknown routing means no app cursor can safely advance past this frame.
+            for (const subscription of [...this.subscriptions.values()])
+                subscription.fail("protocol_error");
+            this.connectionError(new PlatformSocketError("protocol_error"));
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { Joined, PlatformEvent } 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;
+    cursor: string | undefined;
+    active: boolean;
+    private ready;
+    private pending;
+    private tail;
+    constructor(appId: string, options: SubscriptionOptions, remove: () => void);
+    enqueue(work: () => void | Promise<void>): void;
+    join(send: (cursor?: string) => void): void;
+    event(event: PlatformEvent): void;
+    joined(joined: Joined): void;
+    fail(code: PlatformSocketErrorCode): void;
+    unsubscribe(): void;
+}

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

@@ -0,0 +1,69 @@
+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.ready = false;
+        this.pending = 0;
+        this.tail = Promise.resolve();
+        this.cursor = options.afterSeq;
+    }
+    enqueue(work) {
+        if (!this.active)
+            return;
+        if (this.pending >= 1000) {
+            this.fail("resync_required");
+            return;
+        }
+        this.pending++;
+        this.tail = this.tail.then(async () => {
+            if (this.active)
+                await work();
+        }).catch(() => this.fail("handler_failed")).finally(() => { this.pending--; });
+    }
+    join(send) {
+        this.enqueue(() => { this.ready = false; send(this.cursor); });
+    }
+    event(event) {
+        this.enqueue(async () => {
+            // A fresh subscription starts at joined, not at any old in-flight room events.
+            if ((!this.ready && this.cursor === undefined) || event.seq === this.cursor)
+                return;
+            await this.options.onEvent(event);
+            if (this.active)
+                this.cursor = event.seq;
+        });
+    }
+    joined(joined) {
+        this.enqueue(async () => {
+            var _a, _b;
+            await ((_b = (_a = this.options).onJoined) === null || _b === void 0 ? void 0 : _b.call(_a, joined));
+            if (this.active) {
+                this.cursor = joined.seq;
+                this.ready = true;
+            }
+        });
+    }
+    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/platform/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/platform/client/modules/builder.events.types.d.ts

@@ -0,0 +1,280 @@
+/** A reviewed file, execution, or entity activity summary. */
+export interface ToolDisplayProjection {
+    /** 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 reviewed selectable answer to a builder question. */
+export interface ToolQuestionOption {
+    /** Visible option label. */
+    label: string;
+}
+/** A reviewed builder question. Image/HTML source and private design context are excluded. */
+export interface ToolQuestion {
+    /** Visible question text. */
+    question?: string;
+    /** Existing question category. */
+    type?: string;
+    /** Optional visible supporting text. */
+    description?: string;
+    /** Whether more than one answer may be selected. */
+    multi_select?: boolean;
+    /** Optional existing plan section identifier. */
+    covers?: string;
+    /** Reviewed selectable options. */
+    options?: ToolQuestionOption[];
+}
+/** Reviewed question arguments, serialized in `ToolCall.arguments_string`. */
+export interface ToolQuestionArguments {
+    /** Questions presented by a clarifying-question tool. */
+    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;
+}
+/** Reviewed secret-form arguments, serialized in `ToolCall.arguments_string`. */
+export interface ToolSecretArguments {
+    /** Requested secret fields. */
+    secrets_schema: ToolSecretField[];
+}
+/** A reviewed package operation. Versions and package-manager output are excluded. */
+export interface ToolPackageOperation {
+    /** Package name. */
+    name: string;
+    /** Requested package operation. */
+    action?: string;
+}
+/** Reviewed package arguments, serialized in `ToolCall.arguments_string`. */
+export interface ToolPackageArguments {
+    /** Requested package operations. */
+    packages: ToolPackageOperation[];
+}
+/** A reviewed add-only builder plan update. */
+export interface ToolPlanUpdate {
+    /** Existing update action. */
+    action?: string;
+    /** Plan section key. */
+    section?: string;
+    /** Optional user-facing section label. */
+    section_label?: string;
+    /** Reviewed plan point. */
+    text?: string;
+}
+/** Reviewed plan arguments, serialized in `ToolCall.arguments_string`. */
+export interface ToolPlanArguments {
+    /** Plan updates in their emitted order. */
+    updates?: ToolPlanUpdate[];
+    /** Base plan sections the builder considers sufficiently specified. */
+    sections_with_enough?: string[];
+}
+/** Reviewed generated-media arguments, serialized in `ToolCall.arguments_string`. */
+export interface ToolMediaArguments {
+    /** Visible media label. */
+    label?: string;
+    /** Requested image or video aspect ratio. */
+    aspect_ratio?: string;
+}
+/** A reviewed answer to a clarifying question. Secret-form input is never included. */
+export interface ToolQuestionAnswer {
+    /** Zero-based question index. */
+    question_index?: number;
+    /** Labels selected by the user. */
+    selected_labels?: string[];
+    /** User-provided free-text answer. Structural filtering does not redact prose. */
+    custom_text?: string;
+}
+/** Reviewed clarifying-question input. */
+export interface ToolQuestionInput {
+    /** Answers supplied to the question card. */
+    answers: ToolQuestionAnswer[];
+}
+/** Fixed reviewed completion text. Raw tool results and errors are never included. */
+export type ToolOutcome = "Secret configuration completed." | "Package installation completed." | "Plan updated.";
+/** Public progress of an existing builder tool. */
+export interface ToolCall {
+    /** Stable tool call identifier, when included in the update. */
+    id?: string;
+    /** Tool name displayed by the builder. */
+    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 reviewed operation. */
+    auto_approved?: boolean | null;
+    /** Whether the reviewed mutation was applied. */
+    mutation_applied?: boolean | null;
+    /** Existing serialized interaction category; no raw interaction payload. */
+    waiting_on?: {
+        /** Kind of response expected. */
+        kind?: "approval" | "choice" | "input" | null;
+    } | null;
+    /**
+     * JSON containing one reviewed argument shape: ToolQuestionArguments,
+     * ToolSecretArguments, ToolPackageArguments, ToolPlanArguments, or ToolMediaArguments.
+     * It is omitted for all other tools and malformed/partial streaming arguments.
+     */
+    arguments_string?: string;
+    /** Reviewed activity metadata for file, execution, or entity tools. */
+    display_projection?: ToolDisplayProjection;
+    /** Reviewed clarifying-question answers only. */
+    user_input?: ToolQuestionInput;
+    /** Fixed reviewed success outcome only. */
+    results?: ToolOutcome;
+}
+/** Public message replacement. Omitted properties are not synthesized by the SDK. */
+export interface ChatMessage {
+    /** Existing message identifier; replace a message with the same identifier. */
+    id?: string;
+    /** Public message author category. System messages are never delivered. */
+    role?: "user" | "assistant";
+    /** Generated or user-authored text. Structural filtering is not prose redaction. */
+    content?: string | null;
+    /** Attached file URLs. */
+    file_urls?: string[] | null;
+    /** Public tool progress with optional reviewed interaction details. */
+    tool_calls?: ToolCall[] | null;
+    /** Message timestamp, without author identity. */
+    metadata?: {
+        /** Existing timestamp string. */
+        created_date?: string | null;
+    } | null;
+    /** Existing checkpoint reference; mutations remain on the partner backend. */
+    checkpoint_id?: string | null;
+}
+/** Partial app update. Omitted keys mean unchanged; explicit null means clear. */
+export interface AppUpdate {
+    /** Public builder state, without error diagnostics or billing context. */
+    status?: {
+        /** Current builder state. */
+        state?: "ready" | "processing" | "error";
+        /** Existing state timestamp. */
+        last_updated_date?: string | null;
+    } | null;
+    /** Whole-message replacement by identifier, not a recursive message patch. */
+    _last_msg?: ChatMessage | null;
+    /** Conversation containing the replacement message. */
+    _last_msg_conversation_id?: string | null;
+    /** Existing branch scope, if supplied by the producer. */
+    _scope_branch_id?: string | null;
+    /** Whether to reload the app preview. */
+    sandbox_should_reload?: boolean | null;
+    /** Existing preview navigation target. */
+    navigate_preview_to?: string | null;
+    /** Existing forced preview navigation target. */
+    navigate_preview_force_to?: string | null;
+}
+/** Public queued builder request. */
+export interface QueueItem {
+    /** Stable queue item identifier. */
+    id: string;
+    /** User-authored request text. */
+    content: string;
+    /** Attached file URLs. */
+    file_urls?: string[] | null;
+    /** Existing creation timestamp. */
+    created_at: string;
+    /** Existing branch scope. */
+    branch_id?: string | null;
+}
+/** Full public queue snapshot, replacing the previous queue. */
+export interface QueueUpdate {
+    /** App owning this queue. */
+    app_id: string;
+    /** Existing branch scope. */
+    branch_id?: string | null;
+    /** Current 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;
+}
+/** Public tool task progress. */
+export interface TaskUpdate {
+    /** Existing task lifecycle event. */
+    event_type: "task_started" | "task_progress" | "task_completed" | "task_failed" | "task_cancelled";
+    /** Associated tool call. */
+    tool_call_id?: string | null;
+    /** Associated chat message. */
+    message_id?: string | null;
+    /** Existing branch scope. */
+    branch_id?: string | null;
+    /** Numeric progress only; diagnostic/free-text messages are withheld. */
+    progress?: {
+        /** Completed work units. */
+        current?: number | null;
+        /** Total work units, when known. */
+        total?: number | null;
+        /** Producer-supplied percentage. */
+        percentage?: number | null;
+    } | null;
+}
+/** Placeholder resolution or image-generation completion. */
+export interface ImageReady {
+    /** Placeholder being resolved. */
+    placeholder_url: string;
+    /** Existing generation state. */
+    status: "pending" | "completed" | "failed";
+    /** Resolved image URL, or null when unavailable. */
+    image_url?: string | null;
+}
+/** Invalidation notice; fetch current state through the partner backend. */
+export interface Directive {
+    /** Canonical app room. */
+    room: string;
+    /** Public invalidation category. */
+    type: "conversation_changed" | "app_files_changed";
+    /** Existing branch scope. */
+    branch_id?: string | null;
+}
+/** Mapping of wire event names to decoded public payloads. */
+export interface PlatformEventMap {
+    /** Partial builder/app update. */
+    update_model: AppUpdate;
+    /** Conversation or file invalidation. */
+    directive: Directive;
+    /** Full queue snapshot. */
+    queue_update: QueueUpdate;
+    /** Numeric tool progress. */
+    task_update: TaskUpdate;
+    /** Image placeholder resolution. */
+    image_ready: ImageReady;
+}
+/** Ordered delivery with decoded data and the original event name and cursor. */
+export type PlatformEvent = {
+    [K in keyof PlatformEventMap]: {
+        /** Original socket event name; narrows the payload type. */
+        type: K;
+        /** Authorized app receiving this event. */
+        appId: string;
+        /** Opaque replay cursor. Never parse, compare or increment it. */
+        seq: string;
+        /** Decoded payload; existing field names and omission/null semantics are retained. */
+        data: PlatformEventMap[K];
+    };
+}[keyof PlatformEventMap];
+/** Server replay boundary, delivered after all retained events through that boundary. */
+export interface Joined {
+    /** Canonical app room. */
+    room: string;
+    /** Opaque boundary cursor; not an initial app snapshot. */
+    seq: string;
+    /** Server retention limit (currently 2,000 events per app). */
+    max_entries: number;
+    /** Server inactivity expiry (currently 3,600 seconds). */
+    inactivity_expiry_seconds: number;
+}

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

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

package/dist/platform/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/platform/client/modules/builder.types.d.ts

@@ -0,0 +1,48 @@
+import type { Joined, PlatformEvent } 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 a refreshed browser token; resolves on CONNECT, before app replay completes.
+     * Transport loss retries five times and rejoins active subscriptions from applied cursors.
+     * Call again after fixing connection/auth failures. Concurrent calls share one attempt.
+     */
+    connect(): Promise<void>;
+    /** Subscribe before or after connecting. One subscription per app, up to eight per session.
+     * Callbacks run serially per app; errors stop delivery without advancing the cursor.
+     */
+    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 {
+    /** Last successfully applied cursor for this app; omit for a fresh live boundary. */
+    afterSeq?: string;
+    /** Apply each event. Delivery is serial per app; rejection pauses this subscription. */
+    onEvent: (event: PlatformEvent) => void | Promise<void>;
+    /** Handle subscription errors. Reconcile on resync_required; never silently reset a cursor. */
+    onError: (error: PlatformSocketError) => void;
+    /** Optional replay-complete notification, awaited before advancing to the boundary cursor. */
+    onJoined?: (joined: Joined) => void | Promise<void>;
+}
+/** Subscription lifetime and last successfully applied cursor. */
+export interface PlatformSubscription {
+    /** App identifier. */
+    readonly appId: string;
+    /** Last applied event/boundary cursor; persist alongside the state it describes. */
+    readonly cursor: string | undefined;
+    /** 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/platform/client/modules/builder.types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.284.e0a8d2f",
+  "version": "0.8.48-pr.286.d14ea24",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,8 +9,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
-    "lint": "eslint src",
+    "build": "npm run build:runtime && npm run build:platform",
+    "lint": "eslint src platform-src examples/platform-client.ts",
     "test": "npm run test:types && vitest run",
     "test:types": "tsc --noEmit -p tsconfig.type-tests.json",
     "test:unit": "vitest run tests/unit",
@@ -23,7 +23,11 @@
     "create-docs-local": "npm run create-docs && npm run copy-docs-local",
     "copy-docs-local": "node scripts/mintlify-post-processing/copy-to-local-docs.js",
     "create-docs:generate": "typedoc",
-    "create-docs:process": "node scripts/mintlify-post-processing/file-processing/file-processing.js"
+    "create-docs:process": "node scripts/mintlify-post-processing/file-processing/file-processing.js",
+    "build:runtime": "tsc",
+    "build:platform": "tsc -p tsconfig.platform.json",
+    "docs:platform-client": "typedoc --options typedoc.platform-client.json",
+    "test:package": "npm run build && node --test tests/package/platform-client.test.mjs"
   },
   "dependencies": {
     "axios": "^1.18.1",
@@ -63,5 +67,36 @@
   "bugs": {
     "url": "https://github.com/base44/javascript-sdk/issues"
   },
-  "homepage": "https://github.com/base44/javascript-sdk#readme"
+  "homepage": "https://github.com/base44/javascript-sdk#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/*.d.ts": "./dist/*.d.ts",
+    "./dist/*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./dist/*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*",
+    "./platform/client": {
+      "types": "./dist/platform/client/index.d.ts",
+      "default": "./dist/platform/client/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "platform/client": [
+        "dist/platform/client/index.d.ts"
+      ],
+      "*": [
+        "*"
+      ]
+    }
+  }
 }