@base44-preview/sdk 0.8.53-pr.308.2df7905 → 0.8.53-pr.311.53c78b4

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 room's entire persisted storage (match-end cleanup). Safe: a
-     *  later rejoin re-bootstraps exactly like a brand-new room. */
+    /** Deletes all persisted storage for the session. A later connection starts
+     *  with empty storage, the same as a new session. */
     deleteAll(): Promise<void>;
 }
 /**

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

@@ -1,15 +1,23 @@
 /**
- * Extend this interface to add typed `subscribe` callbacks and `send` payloads
- * for your deployed Actors.
+ * Maps actor names to their incoming and outgoing message types.
  *
- * This is separate from {@link ActorNameRegistry} (which is auto-generated
- * by `base44 types generate`), so there are no conflicts.
+ * Extend this interface when you want typed actor
+ * messages without generating types with the CLI:
+ * -  `toServer`: Defines incoming messages that a client sends to the actor.
+ * - `toClient`:  Defines outgoing messages that the actor sends to connected clients.
+ *
+ * To generate types from deployed actors, use the
+ * [`types generate`](/developers/references/cli/commands/types-generate) CLI command.
+ *
+ * To learn how incoming and outgoing messages work, see
+ * [message types](/developers/backend/resources/actors/overview#message-types).
  *
  * @example
  * ```typescript
+ * // Type messages for an actor
  * declare module "@base44/sdk" {
  *   interface ActorRegistry {
- *     ChatRoom: {
+ *     chatRoom: {
  *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
  *       toServer: { type: "message"; text: string };
  *     };
@@ -20,8 +28,11 @@
 export interface 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.
+ * Lists actor names when your project includes types generated by the CLI
+ * with [`types generate`](/developers/references/cli/commands/types-generate).
+ *
+ * The generated names provide autocomplete for deployed actors. To define
+ * incoming and outgoing message types manually, augment {@linkcode ActorRegistry}.
  */
 export interface ActorNameRegistry {
 }
@@ -32,75 +43,169 @@ 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}. */
+/**
+ * Configures the connection that {@linkcode ActorRef.connect | connect()} opens.
+ */
 export interface ActorConnectOptions {
     /**
-     * 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.
+     * Connection ID that the actor receives as `conn.id`.
+     *
+     * To let the actor recognize a client when it reconnects, use a stable
+     * value, such as an ID stored per browser tab. If you omit this property, the
+     * SDK generates a new connection ID.
      */
     id?: string;
 }
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/**
+ * Represents a listener for messages from the actor, registered with
+ * {@linkcode Connection.subscribe | subscribe()}.
+ */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the socket stay live. */
+    /**
+     * Removes this listener. Other listeners and the socket stay open.
+     *
+     * @example
+     * ```typescript
+     * // Remove a listener
+     * sub.unsubscribe();
+     * ```
+     */
     unsubscribe(): void;
 }
 /**
- * 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.
+ * Represents a client's [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) connection to an actor session, returned after calling
+ * [`connect()`](#connect). The WebSocket queues messages you send before it opens.
+ *
+ * Learn more about
+ * [connections](/developers/backend/resources/actors/reference#connections).
  */
 export interface Connection<N extends string = string> {
-    /** The connection id (the value the actor sees as `conn.id`). */
+    /** Connection ID that the actor receives as `conn.id`. */
     readonly id: string;
-    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    /**
+     * Registers a listener for messages from the actor.
+     *
+     * You can register multiple listeners on the same connection.
+     *
+     * @param callback - Callback that runs for each message the actor sends to this connection.
+     * @returns A subscription handle. Call `unsubscribe()` on it to remove this listener without closing the socket.
+     *
+     * @example
+     * ```typescript
+     * // Listen for messages from the actor
+     * const sub = conn.subscribe((msg) => {
+     *   console.log(msg);
+     * });
+     *
+     * // Stop listening without closing the socket.
+     * sub.unsubscribe();
+     * ```
+     */
     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.
+     *
+     * The WebSocket queues messages until it opens. When you call {@linkcode Connection.close | close()},
+     * the WebSocket drops any messages you send afterward.
+     *
+     * @param data - Message to send to the actor. The type comes from {@linkcode ActorRegistry} when you register the actor there.
+     *
+     * @example
+     * ```typescript
+     * // Send a message to the actor
+     * conn.send({ type: "message", text: "Hello" });
+     * ```
+     */
     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 and removes all listeners.
+     *
+     * You can call this method more than once. A connection also closes itself
+     * when it fails permanently.
+     *
+     * @example
+     * ```typescript
+     * // Close the connection
+     * conn.close();
+     * ```
      */
     close(): void;
 }
 /**
- * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
- * {@link connect} to open the socket and get a {@link Connection}.
+ * Represents a reference to an actor session, identified by actor name and session ID.
+ *
+ * Call {@linkcode ActorRef.connect | connect()} to open the WebSocket and get a [connection](/developers/backend/resources/actors/overview#connections).
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * Open the WebSocket and return the {@link Connection}. Idempotent while the
-     * connection is open.
+     * Creates or returns the connection for this session.
+     *
+     * Calling `connect()` again on the same session reference returns the same
+     * connection until it closes.
+     *
+     * For a sample flow, see
+     * [connect a client to a session](/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).
      *
-     * 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.
+     * @param options - Optional connection settings, such as a stable connection ID.
+     * @returns The connection for this actor session.
+     *
+     * @example
+     * ```typescript
+     * // Connect to a session
+     * const conn = base44.actors.chatRoom("session-1").connect({ id: "tab-1" });
+     * ```
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**
- * 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}.
+ * Selects a session for a named actor.
+ *
+ * TypeScript infers message types when you register the actor in
+ * {@linkcode ActorRegistry}. {@linkcode ActorNameRegistry}
+ * provides autocomplete for actor names only.
  */
 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
+     * // Select a session
+     * const session = base44.actors.chatRoom("session-1");
+     * ```
+     */
     (instanceId: string): ActorRef<N>;
 }
 /**
- * The actors module provides access to Cloudflare Durable Object-backed
- * Actors deployed by the Base44 platform.
+ * Actors module for interacting with [actors](/developers/backend/resources/actors/overview) from your app.
  *
- * ```typescript
- * 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();
- * ```
+ * An actor is a long-running backend process that multiple clients connect to simultaneously. A session
+ * is a running instance of an actor, identified by the actor name and a session ID. Each
+ * session manages its own state, storage, and client connections independently.
+ *
+ * The actors module provides the functionality to:
+ *
+ * - Manage connections: {@link ActorRef.connect | Open} and {@link Connection.close | close} a WebSocket connection to a session.
+ * - Exchange messages: {@link Connection.send | Send} and {@link Connection.subscribe | listen} for messages to and from an actor.
+ * - Manage subscriptions: {@link Connection.subscribe | Subscribe} and {@link ActorSubscription.unsubscribe | unsubscribe} from actor messages without closing the connection.
+ *
+ * For a sample flow, see
+ * [connect a client to a session](/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).
+ *
+ * ## Authentication modes
+ *
+ * This module is available to use with a client in anonymous or user authentication mode. Access it
+ * through `base44.actors`. It isn't available in
+ * [service role authentication mode](/developers/references/sdk/getting-started/client#service-role).
+ *
+ * The actor receives each client's [identity](/developers/backend/resources/actors/reference#connections)
+ * when the client connects. A client that hasn't logged in connects as anonymous, and a client that
+ * has [logged in](/developers/references/sdk/docs/interfaces/auth) connects as authenticated.
  */
 export type ActorsModule = {
     [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;

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

@@ -470,7 +470,7 @@ export interface UserConnectorsModule {
      * authenticate with the external service. The scopes and integration type are
      * derived from the connector configuration in the backend.
      *
-     * @param connectorId - The ID of the app user connector configured in your workspace. The AI builder inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.
+     * @param connectorId - The ID of the app user connector configured in your workspace. The AI inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.
      * @returns Promise resolving to the redirect URL string.
      *
      * @example
@@ -489,7 +489,7 @@ export interface UserConnectorsModule {
      * Removes the stored OAuth credentials for the currently authenticated app user's
      * connection to the specified connector.
      *
-     * @param connectorId - The ID of the app user connector configured in your workspace. The AI builder inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.
+     * @param connectorId - The ID of the app user connector configured in your workspace. The AI inserts this ID into generated code when it sets up the connector flow. You can also retrieve it from the workspace connectors API.
      * @returns Promise resolving when the connection has been removed.
      *
      * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.53-pr.308.2df7905",
+  "version": "0.8.53-pr.311.53c78b4",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",