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

package/dist/modules/builder.events.generated.js

@@ -0,0 +1,3 @@
+// Generated from asyncapi.json by scripts/gen-events.mjs. Do not edit; run `npm run gen:events`.
+/** @internal */
+export const serverEventNames = ["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", "session.ended", "room.access_denied", "room.access_revoked", "room.snapshot_unavailable", "app.snapshot"];

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

@@ -0,0 +1,58 @@
+import type { Message, QueueState, ServerEventMap, Snapshot } from "./builder.events.generated.js";
+/**
+ * Maps each live event name to the type of its `data` payload.
+ *
+ * Generated from the service's AsyncAPI document, so it covers every app event the service sends.
+ * The client handles the session events `app.snapshot`, `session.ended` and `room.*` itself, and
+ * reports them through `onSnapshot` and `onError` instead.
+ */
+export type PlatformEventMap = {
+    [K in keyof ServerEventMap as K extends "app.snapshot" | "session.ended" | `room.${string}` ? never : K]: ServerEventMap[K];
+};
+/**
+ * One live event for a subscribed app.
+ *
+ * Check `type` to narrow `data` to that event's payload. A key missing from `data` means the value
+ * is unchanged, and an explicit `null` clears it. For every event and its payload, see
+ * [Socket messages](/developers/references/platform-sdk/socket-messages).
+ *
+ * @example
+ * ```typescript
+ * // Narrow an event by type
+ * function onEvent(event: PlatformEvent) {
+ *   if (event.type === "message.updated") {
+ *     const { message } = event.data;
+ *     console.log(`Message ${message.id} changed`);
+ *   }
+ * }
+ * ```
+ */
+export type PlatformEvent = {
+    [K in keyof PlatformEventMap]: {
+        /** Event name. Narrows the type of `data`. */
+        type: K;
+        /** ID of the app the event belongs to. */
+        appId: string;
+        /** Event payload. */
+        data: PlatformEventMap[K];
+    };
+}[keyof PlatformEventMap];
+/**
+ * An app's current state.
+ *
+ * Arrives after every join and rejoin, and after a rewrite of the main conversation. Replace
+ * everything you hold for the app with it. It holds only the last 50 messages.
+ */
+export interface PlatformSnapshot extends Omit<Snapshot, "queue"> {
+    /** The app's room, `/apps/{app_id}`. */
+    room: string;
+    /** The main branch's prompt queue. Missing when the server sends none. */
+    queue?: QueueState;
+}
+/**
+ * One tool call in a message's `tool_calls`. Checking `name` narrows it to that tool's call and
+ * `OtherToolCall`, which covers tools the SDK doesn't know, so check a field with `in` before using it.
+ */
+export type ToolCall = NonNullable<Message["tool_calls"]>[number];
+/** Why a safety guard parked a tool call for approval. Check `guard` to narrow it. */
+export type GuardApproval = NonNullable<ToolCall["approval"]>;

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

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

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

@@ -0,0 +1,162 @@
+import type { PlatformEvent, PlatformSnapshot } from "./builder.events.types.js";
+import type { PlatformSocketError } from "../errors.js";
+/** Options for {@linkcode BuilderModule.init | init()}. */
+export interface BuilderInitOptions {
+    /**
+     * Called on errors that affect the whole session, such as a failed connection or an ended session.
+     * Errors for one app go to that subscription's `onError` instead. See the
+     * [error codes](/developers/references/platform-sdk/docs/classes/PlatformSocketError#platformsocketerrorcode).
+     */
+    onError: (error: PlatformSocketError) => void;
+}
+/**
+ * Builder module for following the AI chat in your users' apps live.
+ *
+ * Each session holds one socket and up to eight app subscriptions. For each app you get a
+ * snapshot of its chat, then every change as it happens:
+ * - New and updated chat messages, with the AI's tool calls.
+ * - The AI's status, from processing to ready.
+ * - Preview reloads and navigation, the prompt queue, and generated images.
+ *
+ * The module does nothing until you call {@linkcode init | init()}.
+ */
+export interface BuilderModule {
+    /**
+     * Creates a builder session without connecting it.
+     *
+     * Call {@linkcode BuilderSession.connect | connect()} on the returned session to open the socket.
+     * Each session is independent, with its own socket, token and subscriptions.
+     *
+     * @param options - Session options.
+     * @returns The new session.
+     *
+     * @example
+     * ```typescript
+     * // Create and connect a session
+     * const builder = client.builder.init({
+     *   onError(error) {
+     *     console.error('Builder session error', error.code);
+     *   },
+     * });
+     * await builder.connect();
+     * ```
+     */
+    init(options: BuilderInitOptions): BuilderSession;
+}
+/**
+ * A `BuilderSession`: one socket with its app subscriptions and its reconnection. Use its methods
+ * to connect, follow apps and close.
+ */
+export interface BuilderSession {
+    /**
+     * Connects the session's socket.
+     *
+     * Resolves once the socket connects, before any snapshot arrives. If the connection drops, the
+     * session retries five times and rejoins every active subscription, each with a fresh snapshot.
+     * An expired or rejected token is replaced once through `getSessionToken`. Concurrent calls share
+     * one attempt. Call it again after a failure or a `session_replaced` error.
+     *
+     * @returns Promise that resolves when the socket connects.
+     * @throws {PlatformSocketError} With `connection_denied`, `connection_failed` or `session_unavailable`
+     * when the session can't connect, or `client_closed` when the session is closed first.
+     *
+     * @example
+     * ```typescript
+     * // Connect and handle failure
+     * try {
+     *   await builder.connect();
+     * } catch (error) {
+     *   console.error('Could not connect', error.code);
+     * }
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Subscribes to one app's chat.
+     *
+     * You can subscribe before or after connecting. Each app can have one subscription per session,
+     * and a session can have up to eight. The app must be on the session's allowlist. The
+     * subscription first receives a snapshot of the app, then each live event.
+     *
+     * Callbacks for an app run one at a time, in order, and the session waits for a returned promise
+     * before the next one. A slow app doesn't hold up the others. If more than 1,000 deliveries wait
+     * for one app, its subscription ends with `delivery_overflow`.
+     *
+     * @param appId - ID of the app to follow, 24 lowercase hexadecimal characters.
+     * @param options - Callbacks for the app's snapshots, events and errors.
+     * @returns The subscription.
+     * @throws {TypeError} When `appId` isn't a valid app ID or the app already has a subscription.
+     * @throws {PlatformSocketError} With `subscription_limit` when the session has eight subscriptions.
+     *
+     * @example
+     * ```typescript
+     * // Follow an app
+     * const subscription = builder.subscribe(appId, {
+     *   onSnapshot(snapshot) {
+     *     renderChat(snapshot.messages);
+     *   },
+     *   onEvent(event) {
+     *     if (event.type === 'message.updated') upsertMessage(event.data.message);
+     *   },
+     *   onError(error) {
+     *     console.error(`App ${error.appId}`, error.code);
+     *   },
+     * });
+     * ```
+     */
+    subscribe(appId: string, options: SubscriptionOptions): PlatformSubscription;
+    /**
+     * Closes the session.
+     *
+     * Ends every subscription, stops reconnecting and disconnects the socket. Calling it again does
+     * nothing. A closed session can't be reused, so call [`init()`](/developers/references/platform-sdk/docs/interfaces/builder#init)
+     * for a new one.
+     *
+     * @example
+     * ```typescript
+     * // Close a session
+     * builder.close();
+     * ```
+     */
+    close(): void;
+}
+/** Callbacks for one app subscription. */
+export interface SubscriptionOptions {
+    /**
+     * Called with the app's current state, a [`PlatformSnapshot`](#platformsnapshot). Replace everything you hold for the app with it.
+     *
+     * Arrives after every join and rejoin, and after the main conversation is rewritten by an undo,
+     * restore or sync. Live events follow it. It holds only the last 50 messages, so merge by message
+     * ID to keep older history.
+     */
+    onSnapshot: (snapshot: PlatformSnapshot) => void | Promise<void>;
+    /**
+     * Called with each live event, a [`PlatformEvent`](#platformevent). Events for an app arrive one at a time, in order. If the callback
+     * throws or rejects, the subscription ends with `handler_failed`. New event types can be added at
+     * any time, so ignore types you don't handle. For every event and its payload,
+     * see [Socket messages](/developers/references/platform-sdk/socket-messages).
+     */
+    onEvent: (event: PlatformEvent) => void | Promise<void>;
+    /**
+     * Called on errors for this app. Every error ends the subscription except `snapshot_unavailable`.
+     * See the [error codes](/developers/references/platform-sdk/docs/classes/PlatformSocketError#platformsocketerrorcode).
+     */
+    onError: (error: PlatformSocketError) => void;
+}
+/** One app subscription. */
+export interface PlatformSubscription {
+    /** ID of the app. */
+    readonly appId: string;
+    /** Whether the subscription still receives updates. It turns false after an error or {@linkcode unsubscribe | unsubscribe()}. */
+    readonly active: boolean;
+    /**
+     * Stops updates for the app and frees its subscription slot. Calling it again does nothing.
+     *
+     * @example
+     * ```typescript
+     * // Stop following an app
+     * subscription.unsubscribe();
+     * ```
+     */
+    unsubscribe(): void;
+}

package/dist/modules/builder.types.js

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

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.312.2ef55e3",
+  "description": "Browser client for building on the Base44 platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "gen:events": "node scripts/gen-events.mjs",
+    "check:events": "node scripts/gen-events.mjs --check",
+    "sync:asyncapi": "node scripts/sync-asyncapi.mjs",
+    "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",
+    "create-docs": "npm run create-docs:generate && npm run create-docs:process",
+    "create-docs-local": "npm run create-docs && npm run copy-docs-local",
+    "copy-docs-local": "node ../sdk/scripts/mintlify-post-processing/copy-to-local-docs.js --package-dir .",
+    "create-docs:generate": "node -e \"fs.rmSync('docs',{recursive:true,force:true})\" && typedoc --options typedoc.mintlify.json",
+    "create-docs:process": "node ../sdk/scripts/mintlify-post-processing/file-processing/file-processing.js --package-dir ."
+  },
+  "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",
+  "devDependencies": {
+    "json-schema-to-typescript": "16.0.0"
+  }
 }