@base44-preview/sdk 0.8.48-pr.289.b9ea964 → 0.8.48-pr.301.c32fae8

package/README.md

@@ -151,3 +151,12 @@ npm run create-docs
 cd docs
 mintlify dev
 ```
+
+### Platform SDK
+
+The browser client for the Base44 platform lives in this repo as a separate
+package, [`@base44/platform`](packages/platform). It watches public builder
+updates for up to eight apps over the platform socket, using a socket-session
+token your backend opens with its workspace key. It does not depend on
+`@base44/sdk`. White-label sockets must be enabled for the workspace; never use
+an API key in the browser.

package/dist/actor.d.ts

@@ -25,8 +25,8 @@ export interface Storage {
     get<T>(key: string): Promise<T | undefined>;
     put(key: string, value: unknown): Promise<void>;
     delete(key: string): Promise<boolean>;
-    /** Wipe the session's entire persisted storage. A later connection starts
-     *  with the same empty storage as a new session. */
+    /** Wipe the room's entire persisted storage (match-end cleanup). Safe: a
+     *  later rejoin re-bootstraps exactly like a brand-new room. */
     deleteAll(): Promise<void>;
 }
 /**

package/dist/modules/actors.types.d.ts

@@ -1,10 +1,9 @@
 /**
- * Maps actor names to their incoming and outgoing message types.
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed Actors.
  *
- * Extend this interface through module augmentation when you want typed actor
- * messages without generating types with the CLI. For each actor, `toServer`
- * defines incoming messages that a client sends to the actor. `toClient` defines
- * outgoing messages that the actor sends to connected clients.
+ * This is separate from {@link ActorNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
  *
  * @example
  * ```typescript
@@ -21,10 +20,8 @@
 export interface ActorRegistry {
 }
 /**
- * Lists actor names when your project includes types generated by the CLI.
- *
- * The generated names provide autocomplete for deployed actors. To define
- * incoming and outgoing message types manually, augment {@link ActorRegistry}.
+ * Auto-populated by `base44 types generate` with the names of your deployed actors.
+ * Do not edit this interface manually — use {@link ActorRegistry} for message types.
  */
 export interface ActorNameRegistry {
 }
@@ -35,163 +32,71 @@ type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegist
 type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
     toServer: infer O;
 } ? O : unknown : unknown;
-/**
- * Options for {@link ActorRef.connect}.
- */
+/** Options for {@link ActorRef.connect}. */
 export interface ActorConnectOptions {
     /**
-     * Connection ID that the actor receives as `conn.id`.
-     *
-     * Specify a stable value, such as a value persisted per client, so
-     * reconnections from that client reuse the same connection ID. Omit this property
-     * to generate an ID.
+     * The connection id — becomes the actor's `conn.id`. Supply a stable value
+     * (e.g. persisted per tab) so a reconnect reuses the same server-side
+     * identity; omit for an auto-generated per-connection id.
      */
     id?: string;
 }
-/**
- * Represents an outgoing-message listener registered with
- * {@link Connection.subscribe}.
- */
+/** Handle for one listener registered via {@link Connection.subscribe}. */
 export interface ActorSubscription {
-    /**
-     * Removes this listener. Other listeners and the socket stay open.
-     *
-     * @example
-     * ```typescript
-     * const sub = conn.subscribe((msg) => console.log(msg));
-     * sub.unsubscribe();
-     * ```
-     */
+    /** Remove this listener; other listeners and the socket stay live. */
     unsubscribe(): void;
 }
 /**
- * Represents a client's WebSocket connection to an actor session.
- *
- * {@link ActorRef.connect} returns this object while the socket connects.
- * The socket buffers messages sent during connection setup until it opens.
+ * A live connection to an actor instance, returned by {@link ActorRef.connect}.
+ * `subscribe`/`send` are always valid — you only get a `Connection` once the
+ * socket has been opened, so there's no pre-connect state to guard against.
  */
 export interface Connection<N extends string = string> {
-    /** Connection ID that the actor receives as `conn.id`. */
+    /** The connection id (the value the actor sees as `conn.id`). */
     readonly id: string;
-    /**
-     * Registers a listener for outgoing messages from the actor.
-     *
-     * You can register multiple listeners on the same connection.
-     *
-     * @param callback - Called with each outgoing message sent to this connection.
-     * @returns A handle you can use to remove this listener without closing the socket.
-     *
-     * @example
-     * ```typescript
-     * const conn = base44.actors.Chat("session-1").connect();
-     * const sub = conn.subscribe((msg) => {
-     *   if (msg.type === "message") console.log(msg.text);
-     * });
-     * ```
-     */
+    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /**
-     * Sends an incoming message to the actor.
-     *
-     * The socket buffers messages until it opens. After {@link close}, the socket
-     * drops further sends.
-     *
-     * @param data - Incoming message to send. Typed through {@link ActorRegistry} when configured.
-     *
-     * @example
-     * ```typescript
-     * conn.send({ type: "message", text: "Hello" });
-     * ```
-     */
+    /** Send a message. Buffered by the socket until it's open; dropped after
+     * {@link close}. */
     send(data: ToServerFor<N>): void;
     /**
-     * Closes the connection and removes all listeners.
-     *
-     * Safe to call more than once. A connection also closes itself when it fails
-     * permanently. See {@link ActorRef.connect} for how to open a fresh connection.
-     *
-     * @example
-     * ```typescript
-     * conn.close();
-     * ```
+     * Tear down the socket, heartbeat, and all listeners. Safe to call more
+     * than once. A connection also closes itself when it fails permanently —
+     * see {@link ActorRef.connect}.
      */
     close(): void;
 }
 /**
- * Represents an actor session selected by actor name and session ID.
- *
- * Call {@link connect} to open the WebSocket and get a {@link Connection}.
+ * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
+ * {@link connect} to open the socket and get a {@link Connection}.
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * Creates or returns the {@link Connection} for this session.
-     *
-     * Repeated calls return the same connection until it closes. After a permanent
-     * failure, such as a missing actor or denied connection, fix the cause and call
-     * `connect()` again. Add subscriptions to the new connection.
+     * Open the WebSocket and return the {@link Connection}. Idempotent while the
+     * connection is open.
      *
-     * @param options - Optional connection settings, such as a stable connection ID.
-     * @returns The {@link Connection} for this actor session.
-     *
-     * @example
-     * ```typescript
-     * const conn = base44.actors.Chat("session-1").connect({ id: "tab-abc" });
-     * conn.subscribe((msg) => console.log(msg));
-     * ```
+     * A connection that fails permanently (for example, the actor doesn't exist
+     * or the caller isn't allowed to connect) closes itself and reports the
+     * error to the client's `onError` handler. Call `connect()` again after
+     * fixing the cause to get a fresh {@link Connection}, and re-subscribe.
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**
- * Selects a session for a named actor.
- *
- * Typed automatically when the actor is registered in {@link ActorRegistry} or
- * {@link ActorNameRegistry}.
+ * Client for a single named Actor — call it with an instance id to get an
+ * {@link ActorRef}. Typed automatically when the actor is registered in
+ * {@link ActorRegistry}.
  */
 export interface ActorClient<N extends string = string> {
-    /**
-     * Gets a reference to an actor session.
-     *
-     * Clients that specify the same actor name and session ID join the same session.
-     *
-     * @param instanceId - Session ID that identifies which session to connect to.
-     * @returns A reference to the actor session.
-     *
-     * @example
-     * ```typescript
-     * const session = base44.actors.Chat("lobby-1");
-     * const conn = session.connect();
-     * ```
-     */
     (instanceId: string): ActorRef<N>;
 }
 /**
- * Provides access to actors and their shared, live sessions.
- *
- * Select an actor by name and session ID, then connect a client to the
- * session. Clients in the same session can exchange realtime messages through the
- * actor. The client works in the browser and in Node.
- *
- * ## Connection flow
- *
- * - Connect to a session with `base44.actors.<ActorName>(sessionId).connect()`.
- * - Subscribe to outgoing messages with {@link Connection.subscribe}.
- * - Send incoming messages with {@link Connection.send}.
- * - Close the connection with {@link Connection.close}.
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
  *
- * See [Actors Overview](/developers/backend/resources/actors/overview)
- * for actor concepts and terminology, and the [Actor Class Reference](/developers/backend/resources/actors/reference)
- * for the backend class API.
- *
- * ## Authentication modes
- *
- * This module is available in anonymous or user authentication mode
- * (`base44.actors`). It isn't available with service role authentication. Apps that
- * require login can reject anonymous connections in the actor's `handleConnect()` method.
- *
- * @example
  * ```typescript
- * const conn = base44.actors.Chat("session-1").connect({ id: "tab-1" });
- * const sub = conn.subscribe((msg) => console.log(msg));
+ * const conn = base44.actors.MyActor("room-1").connect();
+ * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.289.b9ea964",
+  "version": "0.8.48-pr.301.c32fae8",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,9 +8,12 @@
   "files": [
     "dist"
   ],
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "build": "tsc",
-    "lint": "eslint src",
+    "lint": "eslint src packages/platform/src packages/platform/examples",
     "test": "npm run test:types && vitest run",
     "test:types": "tsc --noEmit -p tsconfig.type-tests.json",
     "test:unit": "vitest run tests/unit",
@@ -23,7 +26,9 @@
     "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:platform": "npm run build -w @base44/platform",
+    "test:platform": "npm test -w @base44/platform"
   },
   "dependencies": {
     "axios": "^1.18.1",