@base44-preview/sdk 0.8.46-pr.272.f64ff62 → 0.8.46-pr.273.f546cdd

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

@@ -7,6 +7,7 @@
  *
  * @example
  * ```typescript
+ * // Declare message types for a deployed actor
  * declare module "@base44/sdk" {
  *   interface ActorRegistry {
  *     ChatRoom: {
@@ -35,15 +36,26 @@ type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegist
 /** Options for {@link ActorRef.connect}. */
 export interface ActorConnectOptions {
     /**
-     * The connection id, used as 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.
+     * The connection id, used as the actor's `conn.id`. Supply a stable value,
+     * such as one persisted per tab, so a reconnect reuses the same server-side
+     * identity. Omit it for an auto-generated per-connection id.
      */
     id?: string;
 }
 /** Handle for one listener registered via {@link Connection.subscribe}. */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the socket stay live. */
+    /**
+     * Removes this listener. Other listeners on the same connection, and the
+     * connection itself, stay live. To close the connection as well, call
+     * {@link Connection.close}.
+     *
+     * @example
+     * ```typescript
+     * // Stop listening without closing the connection
+     * const sub = conn.subscribe((msg) => console.log(msg));
+     * sub.unsubscribe();
+     * ```
+     */
     unsubscribe(): void;
 }
 /**
@@ -52,17 +64,62 @@ export interface ActorSubscription {
  * socket has been opened, so there's no pre-connect state to guard against.
  */
 export interface Connection<N extends string = string> {
-    /** The connection id (the value the actor sees as `conn.id`). */
+    /** The connection id, which is the value the actor sees as `conn.id`. */
     readonly id: string;
-    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    /**
+     * Registers a listener for messages sent by the actor. Any number of
+     * listeners can be registered on one connection, and each receives every
+     * message.
+     *
+     * The callback payload is typed when the actor is declared in
+     * {@link ActorRegistry}, and is `unknown` otherwise.
+     *
+     * @param callback - Called with each message the actor sends to this client.
+     * @returns An {@link ActorSubscription} that removes this one listener.
+     *
+     * @example
+     * ```typescript
+     * // Listen for messages from the actor
+     * const sub = conn.subscribe((msg) => {
+     *   if (msg.type === "message") console.log(msg.text);
+     * });
+     * ```
+     */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered by the socket until it's open; dropped after
-     * {@link close}. */
+    /**
+     * Sends a message to the actor.
+     *
+     * Messages sent before the socket finishes opening are buffered and flushed
+     * on open. Messages sent after {@link close} are dropped silently.
+     *
+     * The payload is typed when the actor is declared in {@link ActorRegistry},
+     * and is `unknown` otherwise.
+     *
+     * @param data - The message to send to the actor.
+     *
+     * @example
+     * ```typescript
+     * // Send a message to the actor
+     * conn.send({ type: "message", text: "hi" });
+     * ```
+     */
     send(data: ToServerFor<N>): void;
     /**
-     * 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}.
+     * Closes the connection, tearing down the socket, the heartbeat, and every
+     * listener registered on it. Safe to call more than once.
+     *
+     * A connection also closes itself when it fails permanently. See
+     * {@link ActorRef.connect} for how to recover from that.
+     *
+     * @example
+     * ```typescript
+     * // Close when the view that opened the connection goes away.
+     * useEffect(() => {
+     *   const conn = base44.actors.ChatRoom(roomId).connect();
+     *   conn.subscribe(setMessage);
+     *   return () => conn.close();
+     * }, [roomId]);
+     * ```
      */
     close(): void;
 }
@@ -72,13 +129,38 @@ export interface Connection<N extends string = string> {
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * Open the WebSocket and return the {@link Connection}. Idempotent while the
-     * connection is open.
+     * Opens the WebSocket to this actor instance and returns the
+     * {@link Connection}. Idempotent while the connection is open, so calling it
+     * again returns the same connection rather than opening a second socket.
+     *
+     * The returned connection is usable straight away. Messages passed to
+     * {@link Connection.send} before the socket finishes opening are buffered and
+     * flushed on open.
+     *
+     * A connection that fails permanently, for example because 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 once the
+     * cause is fixed to get a fresh {@link Connection}, then re-subscribe, as
+     * listeners do not carry over.
+     *
+     * @param options - Connection options. See {@link ActorConnectOptions}.
+     * @returns A live {@link Connection} to this actor instance.
+     *
+     * @example
+     * ```typescript
+     * // Connect to an actor instance
+     * const conn = base44.actors.ChatRoom("room-1").connect();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Reuse a stable connection id so a reconnect keeps the same
+     * // server-side identity.
+     * let id = sessionStorage.getItem("chat-conn-id") ?? crypto.randomUUID();
+     * sessionStorage.setItem("chat-conn-id", id);
      *
-     * 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.
+     * const conn = base44.actors.ChatRoom("room-1").connect({ id });
+     * ```
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
@@ -91,16 +173,62 @@ export interface ActorClient<N extends string = string> {
     (instanceId: string): ActorRef<N>;
 }
 /**
- * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors module for real-time messaging with Cloudflare Durable Object-backed
  * Actors deployed by the Base44 platform.
  *
+ * An Actor is a named server-side object with persistent state. Each instance
+ * is addressed by an id, so `base44.actors.ChatRoom("room-1")` and
+ * `base44.actors.ChatRoom("room-2")` are separate instances with separate
+ * state. Clients open a WebSocket to an instance and exchange messages with it.
+ *
+ * This module provides:
+ * - Per-instance WebSocket connections, opened with {@link ActorRef.connect}
+ * - Message listeners, registered with {@link Connection.subscribe}
+ * - Message sending, with {@link Connection.send}
+ * - Automatic reconnection with backoff, including recovery from half-open
+ *   sockets that stop delivering messages without emitting a close event
+ * - End-to-end typing of message payloads through {@link ActorRegistry}
+ *
+ * This module is available to use with a client in anonymous and user
+ * authentication modes. Connecting anonymously requires a browser environment.
+ *
+ * Connections stay open until you call {@link Connection.close}, so close them
+ * when the view that opened them goes away.
+ *
+ * @example
  * ```typescript
- * const conn = base44.actors.MyActor("room-1").connect();
- * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * // Open a connection to one instance of the ChatRoom actor.
+ * const conn = base44.actors.ChatRoom("room-1").connect();
+ *
+ * const sub = conn.subscribe((msg) => {
+ *   console.log(msg);
+ * });
+ *
  * conn.send({ type: "message", text: "hi" });
+ *
+ * // Later, when the view goes away.
  * sub.unsubscribe();
  * conn.close();
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Register the actor to type both directions of the conversation.
+ * declare module "@base44/sdk" {
+ *   interface ActorRegistry {
+ *     ChatRoom: {
+ *       toClient: { type: "joined" | "message"; from?: string; text?: string };
+ *       toServer: { type: "message"; text: string };
+ *     };
+ *   }
+ * }
+ *
+ * const conn = base44.actors.ChatRoom("room-1").connect();
+ * conn.subscribe((msg) => {
+ *   // msg is typed as the toClient union.
+ *   if (msg.type === "message") console.log(msg.text);
+ * });
+ * ```
  */
 export type ActorsModule = {
     [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.46-pr.272.f64ff62",
+  "version": "0.8.46-pr.273.f546cdd",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",