docs(actors): update JSDoc for actors SDK module

scripts/mintlify-post-processing/appended-articles.json

@@ -2,7 +2,10 @@
   "interfaces/ConnectorsModule": [
     "type-aliases/ConnectorIntegrationType",
     "interfaces/ConnectorIntegrationTypeRegistry",
-    "interfaces/UserConnectorsModule"
+    "interfaces/UserConnectorsModule",
+    "interfaces/ConnectorApiRequest",
+    "interfaces/ConnectorApiResponse",
+    "type-aliases/ConnectorApiResponsePhase"
   ],
   "type-aliases/EntitiesModule": [
     "interfaces/EntityHandler",
@@ -21,5 +24,14 @@
   "type-aliases/integrations": [
     "interfaces/CoreIntegrations",
     "interfaces/CustomIntegrationsModule"
+  ],
+  "type-aliases/ActorsModule": [
+    "interfaces/ActorRef",
+    "interfaces/Connection",
+    "interfaces/ActorConnectOptions",
+    "interfaces/ActorSubscription",
+    "interfaces/ActorClient",
+    "interfaces/ActorRegistry",
+    "interfaces/ActorNameRegistry"
   ]
 }

scripts/mintlify-post-processing/types-to-expose.json

@@ -1,4 +1,12 @@
 [
+  "ActorClient",
+  "ActorConnectOptions",
+  "ActorNameRegistry",
+  "ActorRef",
+  "ActorRegistry",
+  "ActorSubscription",
+  "ActorsModule",
+  "Connection",
   "AgentName",
   "AgentNameRegistry",
   "AgentsModule",

src/actor.ts

@@ -28,8 +28,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. */
+  /** Wipe the session's entire persisted storage. A later connection starts
+   *  with the same empty storage as a new session. */
   deleteAll(): Promise<void>;
 }
 

src/modules/actors.types.ts

@@ -1,9 +1,15 @@
 /**
- * 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.
+ * See [Typing messages in the client](/developers/backend/resources/actors/overview#typing-messages-in-the-client)
+ * for how to define your message types.
  *
  * @example
  * ```typescript
@@ -20,8 +26,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 {}
 
@@ -39,79 +48,144 @@ type ToServerFor<N extends string> = N extends keyof ActorRegistry
     : unknown
   : unknown;
 
-/** Options for {@link ActorRef.connect}. */
+/**
+ * Options for [ActorRef.connect](#connect).
+ */
 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`.
+   *
+   * Use a stable value, such as one stored per browser tab, so the actor
+   * can recognize the same client if it reconnects. If omitted, the SDK generates one.
+   *
+   * See [Connection ID](/developers/backend/resources/actors/overview#connection-id)
+   * for more details.
    */
   id?: string;
 }
 
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/**
+ * Represents an outgoing-message listener 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.
+   */
   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 while the socket connects.
+ * The socket buffers messages sent during connection setup until 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 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.
+   */
   subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
 
-  /** Send a message. Buffered by the socket until it's open; dropped after
-   * {@link close}. */
+  /**
+   * Sends an incoming message to the actor.
+   *
+   * The socket buffers messages until it opens. After [close](#close), the socket
+   * drops further sends.
+   *
+   * @param data - Incoming message to send. Typed through [ActorRegistry](#actorregistry) when configured.
+   */
   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.
+   *
+   * Safe to call more than once. A connection also closes itself when it fails
+   * permanently. See [ActorRef.connect](#connect) for how to open a fresh connection.
    */
   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 an actor session selected 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. 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.
    *
-   * 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.
+   * See [Connect a client to a session](/developers/backend/resources/actors/samples#connect-a-client-to-a-session)
+   * for a sample flow.
+   *
+   * @param options - Optional connection settings, such as a stable connection ID.
+   * @returns The [Connection](#connection) for this actor session.
    */
   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.
+ *
+ * Typed automatically when the actor is registered in [ActorRegistry](#actorregistry) or
+ * [ActorNameRegistry](#actornameregistry).
  */
 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.
+   */
   (instanceId: string): ActorRef<N>;
 }
 
 /**
- * The actors module provides access to Cloudflare Durable Object-backed
- * Actors deployed by the Base44 platform.
+ * Use `base44.actors` to connect your frontend to [actor sessions](/developers/backend/resources/actors/overview),
+ * shared live backend processes where clients can exchange messages in realtime.
+ * 
+ * With the Actors SDK module you can: 
+ *
+ * - Connect to a session with `base44.actors.<ActorName>(sessionId).connect()`.
+ * - Subscribe to messages the actor sends using [Connection.subscribe](#subscribe),
+ *   either broadcast to all clients or sent directly to your client.
+ * - Send messages to the actor with [Connection.send](#send).
+ * - Share a session across multiple clients: any clients with the same actor
+ *   name and session ID connect to the same session.
+ * - Type your messages using [ActorRegistry](#actorregistry) for autocomplete
+ *   and compile-time safety.
+ *
+ * Learn more about [actors](/developers/backend/resources/actors/overview).
  *
+ * ## Authentication modes
+ *
+ * This module is available in anonymous or user authentication mode. 
+ * Apps that require login can reject anonymous connections in the actor's `handleConnect()` method.
+ * Learn more about [managing client connections](/developers/backend/resources/actors/samples#manage-client-connections). 
+
+
+ * @example
+ * 
+ * The following example displays the general lifecycle of a client connected to an actor named `Chat`:  
+ *  
  * ```typescript
- * const conn = base44.actors.MyActor("room-1").connect();
- * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * Example 
+ * const conn = base44.actors.Chat("session-1").connect({ id: "tab-1" });
+ * const sub = conn.subscribe((msg) => console.log(msg));
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();