@base44-preview/sdk 0.8.52-pr.307.064de09 → 0.8.53-pr.289.39e1f1f

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,22 @@
 /**
- * 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 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.
+ *
+ * To generate types from deployed actors instead, 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 +27,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 [ActorRegistry](#actorregistry).
  */
 export interface ActorNameRegistry {
 }
@@ -32,71 +42,173 @@ 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 [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 the same client if it reconnects, use a stable
+     * value, such as an ID stored per browser tab. If you omit this property, the
+     * SDK generates a connection ID.
+     *
+     * For more about connection IDs, see
+     * [connections](/developers/backend/resources/actors/reference#connections).
      */
     id?: string;
 }
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/**
+ * Represents a listener for messages from the actor, registered with
+ * [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 connection to an actor session.
+ *
+ * [ActorRef.connect](#connect) returns this object. The socket buffers messages
+ * you send before it opens.
  */
 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 socket buffers messages until it opens. After you call [close](#close),
+     * the socket drops further sends.
+     *
+     * @param data - Message to send to the actor. The type comes from [ActorRegistry](#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. To open a new connection, call
+     * [ActorRef.connect](#connect) again.
+     *
+     * @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 [connect](#connect) to open the WebSocket and get a [Connection](#connection).
  */
 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](#connection) for this session.
+     *
+     * Repeated calls return the same connection until it closes. If the connection
+     * fails permanently, for example because the actor doesn't exist or the actor
+     * denies the connection, fix the cause and call `connect()` again. Then
+     * subscribe again on the new connection.
+     *
+     * 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](#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
+ * [ActorRegistry](#actorregistry). [ActorNameRegistry](#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.
+ * Connects your frontend to [actor sessions](/developers/backend/resources/actors/overview),
+ * shared live backend processes where clients can exchange messages in realtime.
  *
+ * The following table lists what you can do with the actors module:
+ *
+ * | Member | Purpose |
+ * |---|---|
+ * | [`connect()`](#connect) | Opens a connection to a session. Clients that use the same actor name and session ID join the same session. |
+ * | [`subscribe()`](#subscribe) | Receives messages from an actor. |
+ * | [`send()`](#send) | Sends a message to an actor. |
+ * | [`ActorRegistry`](#actorregistry) | Defines message types for autocomplete and compile-time safety. |
+ *
+ * ## Authentication modes
+ *
+ * This module is available in anonymous and user authentication modes.
+ * Apps that require login can reject anonymous connections in the actor's `handleConnect()` method.
+ * To learn more, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).
+ *
+ * @example
  * ```typescript
- * const conn = base44.actors.MyActor("room-1").connect();
- * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * // Connect, subscribe, send, and close
+ * const conn = base44.actors.chatRoom("session-1").connect({ id: "tab-1" });
+ * const sub = conn.subscribe((msg) => console.log(msg));
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.52-pr.307.064de09",
+  "version": "0.8.53-pr.289.39e1f1f",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",