@base44-preview/platform 0.0.0 → 0.1.0-pr.319.850fe58

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,225 @@
+# @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();
+```
+
+## Receiving webhooks (server)
+
+`@base44/platform/server` verifies Base44 outbound webhooks and answers the endpoint
+activation challenge. It uses WebCrypto only (Node 20+, Deno, Bun, Workers, edge runtimes) and
+makes no network calls: pass your workspace's public keys (`whpk_…`) explicitly.
+
+The simplest route is `createHandler`. It reads the raw body, verifies it, answers the
+activation challenge and picks the status code: 400 for a delivery that fails verification,
+500 when your keys are misconfigured or a callback throws (Base44 retries), 204 otherwise,
+including for event types you have no handler for.
+
+```ts
+import { Base44PlatformServer } from "@base44/platform/server";
+
+const platform = new Base44PlatformServer({
+  serverUrl: "https://base44.app",
+  apiKey: process.env.BASE44_API_KEY!,
+  webhooks: { publicKeys: process.env.BASE44_WEBHOOK_PUBLIC_KEYS },
+});
+
+export const POST = platform.webhooks.createHandler({
+  on: {
+    "app.deleted.v1": async event => forget(event.data.app_id), // event is narrowed per type
+  },
+  onEvent: event => log(event.type),      // every event, before its handler
+  onSuccess: event => {},                 // return a Response to replace the 204
+  onError: (error, event) => report(error), // return a Response to replace the 400/500
+});
+```
+
+For full control, verify and dispatch yourself:
+
+```ts
+export async function POST(request: Request) {
+  const rawBody = await request.text(); // exactly as received
+  let event;
+  try {
+    event = await platform.webhooks.verifyEvent(rawBody, request.headers);
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
+    throw error; // missing/malformed keys: a 500, so Base44 retries
+  }
+  switch (event.type) {
+    case "webhook.test.v1": return Response.json({ challenge: event.data.challenge }); // activates the endpoint
+    case "app.deleted.v1": await forget(event.data.app_id); break;
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+Delivery is at least once with no ordering guarantee: deduplicate on `event.id`, and answer
+2xx to event types you do not handle. Event types are generated from the schemas published at
+`https://base44.com/webhooks/schemas`; run `npm run generate:webhooks` to refresh them.
+
+## 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;
+}