From 491c300a1fc85657b81e39f38a41e85b0719b87d Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Mon, 21 Sep 2026 23:52:20 -0400 Subject: [PATCH 1/9] docs(actors): update JSDoc for actors SDK module Rewrites JSDoc across actors.types.ts to align with established terminology and writing style: session vs instance, client vs page, incoming/outgoing message direction, and full @param/@returns/@example coverage on all public methods. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../appended-articles.json | 9 + .../typedoc-mintlify-content.js | 2 +- .../types-to-expose.json | 8 + src/actor.ts | 4 +- src/modules/actors.types.ts | 169 ++++++++++++++---- 5 files changed, 152 insertions(+), 40 deletions(-) diff --git a/scripts/mintlify-post-processing/appended-articles.json b/scripts/mintlify-post-processing/appended-articles.json index 27fb69b8..5bc68c3b 100644 --- a/scripts/mintlify-post-processing/appended-articles.json +++ b/scripts/mintlify-post-processing/appended-articles.json @@ -18,6 +18,15 @@ "type-aliases/AgentName", "interfaces/AgentNameRegistry" ], + "type-aliases/ActorsModule": [ + "interfaces/ActorRef", + "interfaces/Connection", + "interfaces/ActorConnectOptions", + "interfaces/ActorSubscription", + "interfaces/ActorClient", + "interfaces/ActorRegistry", + "interfaces/ActorNameRegistry" + ], "type-aliases/integrations": [ "interfaces/CoreIntegrations", "interfaces/CustomIntegrationsModule" diff --git a/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js b/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js index 6bf1e0ac..a4b5d004 100644 --- a/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js +++ b/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js @@ -45,7 +45,7 @@ export function convertExamplesToCodeGroup(content) { const exampleSectionRegex = /^(#{2,4})\s+(Example|Examples)\s*$([\s\S]*?)(?=^#{2,4}\s|\n<\/ResponseField>|\n\*\*\*|$(?!\n))/gm; return content.replace(exampleSectionRegex, (match, headingLevel, exampleHeading, exampleContent) => { - const codeBlockRegex = /```([\w-]*)\s*([^\n]*)\n([\s\S]*?)```/g; + const codeBlockRegex = /```([\w-]*)[ \t]*([^\n]*)\n([\s\S]*?)```/g; const examples = []; let codeMatch; diff --git a/scripts/mintlify-post-processing/types-to-expose.json b/scripts/mintlify-post-processing/types-to-expose.json index 5d7ef016..3ac0b660 100644 --- a/scripts/mintlify-post-processing/types-to-expose.json +++ b/scripts/mintlify-post-processing/types-to-expose.json @@ -1,4 +1,12 @@ [ + "ActorClient", + "ActorConnectOptions", + "ActorNameRegistry", + "ActorRef", + "ActorRegistry", + "ActorSubscription", + "ActorsModule", + "Connection", "AgentName", "AgentNameRegistry", "AgentsModule", diff --git a/src/actor.ts b/src/actor.ts index 153224cd..c4c893bc 100644 --- a/src/actor.ts +++ b/src/actor.ts @@ -28,8 +28,8 @@ export interface Storage { get(key: string): Promise; put(key: string, value: unknown): Promise; delete(key: string): Promise; - /** 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; } diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index bb55bbed..3b0d4d86 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -1,9 +1,10 @@ /** - * 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. * * @example * ```typescript @@ -20,8 +21,10 @@ 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. + * + * The generated names provide autocomplete for deployed actors. To define + * incoming and outgoing message types manually, augment {@link ActorRegistry}. */ export interface ActorNameRegistry {} @@ -39,79 +42,171 @@ type ToServerFor = N extends keyof ActorRegistry : unknown : unknown; -/** Options for {@link ActorRef.connect}. */ +/** + * Options for {@link ActorRef.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`. + * + * 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. */ id?: string; } -/** Handle for one listener registered via {@link Connection.subscribe}. */ +/** + * Represents an outgoing-message listener registered with + * {@link Connection.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 + * const sub = conn.subscribe((msg) => console.log(msg)); + * 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. + * + * {@link ActorRef.connect} returns this object while the socket connects. + * The socket buffers messages sent during connection setup until it opens. */ export interface Connection { - /** 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. + * + * @example + * ```typescript + * const conn = base44.actors.Chat("session-1").connect(); + * const sub = conn.subscribe((msg) => { + * if (msg.type === "message") console.log(msg.text); + * }); + * ``` + */ subscribe(callback: (data: ToClientFor) => 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 {@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(data: ToServerFor): 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 {@link ActorRef.connect} for how to open a fresh connection. + * + * @example + * ```typescript + * 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 an actor session selected by actor name and session ID. + * + * Call {@link connect} to open the WebSocket and get a {@link Connection}. */ export interface ActorRef { /** - * Open the WebSocket and return the {@link Connection}. Idempotent while the - * connection is open. + * 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. * - * 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 {@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)); + * ``` */ connect(options?: ActorConnectOptions): Connection; } /** - * 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 {@link ActorRegistry} or + * {@link ActorNameRegistry}. */ export interface ActorClient { + /** + * 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; } /** - * The actors module provides access to Cloudflare Durable Object-backed - * Actors deployed by the Base44 platform. + * 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.(sessionId).connect()`. + * - Subscribe to outgoing messages with {@link Connection.subscribe}. + * - Send incoming messages with {@link Connection.send}. + * - Close the connection with {@link Connection.close}. * + * 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.MyActor("room-1").connect(); - * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry + * 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(); From 3f15267cc18023e46a553e32db709bd3d22227d6 Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Mon, 21 Sep 2026 23:55:34 -0400 Subject: [PATCH 2/9] revert: remove pipeline script changes from actors JSDoc PR Co-Authored-By: Claude Sonnet 4.6 (1M context) --- scripts/mintlify-post-processing/appended-articles.json | 9 --------- .../typedoc-plugin/typedoc-mintlify-content.js | 2 +- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/scripts/mintlify-post-processing/appended-articles.json b/scripts/mintlify-post-processing/appended-articles.json index 5bc68c3b..27fb69b8 100644 --- a/scripts/mintlify-post-processing/appended-articles.json +++ b/scripts/mintlify-post-processing/appended-articles.json @@ -18,15 +18,6 @@ "type-aliases/AgentName", "interfaces/AgentNameRegistry" ], - "type-aliases/ActorsModule": [ - "interfaces/ActorRef", - "interfaces/Connection", - "interfaces/ActorConnectOptions", - "interfaces/ActorSubscription", - "interfaces/ActorClient", - "interfaces/ActorRegistry", - "interfaces/ActorNameRegistry" - ], "type-aliases/integrations": [ "interfaces/CoreIntegrations", "interfaces/CustomIntegrationsModule" diff --git a/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js b/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js index a4b5d004..6bf1e0ac 100644 --- a/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js +++ b/scripts/mintlify-post-processing/typedoc-plugin/typedoc-mintlify-content.js @@ -45,7 +45,7 @@ export function convertExamplesToCodeGroup(content) { const exampleSectionRegex = /^(#{2,4})\s+(Example|Examples)\s*$([\s\S]*?)(?=^#{2,4}\s|\n<\/ResponseField>|\n\*\*\*|$(?!\n))/gm; return content.replace(exampleSectionRegex, (match, headingLevel, exampleHeading, exampleContent) => { - const codeBlockRegex = /```([\w-]*)[ \t]*([^\n]*)\n([\s\S]*?)```/g; + const codeBlockRegex = /```([\w-]*)\s*([^\n]*)\n([\s\S]*?)```/g; const examples = []; let codeMatch; From 2877d2df67fae839705240157e8457f01c34c1aa Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:33:49 -0400 Subject: [PATCH 3/9] docs(actors): align JSDoc with docs terminology and add cross-links - Use 'session' consistently instead of 'instance' throughout descriptions - Replace implementation-focused comments with developer-facing language - Add links to sample flows, overview concepts, and types generate CLI command - Simplify field and method descriptions per style guide Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 67 ++++++++++++++----------------------- 1 file changed, 25 insertions(+), 42 deletions(-) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index 3b0d4d86..07e42f3a 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -6,6 +6,11 @@ * 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 * declare module "@base44/sdk" { @@ -21,7 +26,8 @@ export interface ActorRegistry {} /** - * Lists actor names when your project includes types generated by the CLI. + * 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 {@link ActorRegistry}. @@ -49,9 +55,11 @@ 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. + * 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; } @@ -63,12 +71,6 @@ export interface ActorConnectOptions { 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(); - * ``` */ unsubscribe(): void; } @@ -90,14 +92,6 @@ export interface 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); - * }); - * ``` */ subscribe(callback: (data: ToClientFor) => void): ActorSubscription; @@ -108,11 +102,6 @@ export interface Connection { * drops further sends. * * @param data - Incoming message to send. Typed through {@link ActorRegistry} when configured. - * - * @example - * ```typescript - * conn.send({ type: "message", text: "Hello" }); - * ``` */ send(data: ToServerFor): void; @@ -121,11 +110,6 @@ export interface Connection { * * 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(); - * ``` */ close(): void; } @@ -143,14 +127,11 @@ export interface ActorRef { * failure, such as a missing actor or denied connection, fix the cause and call * `connect()` again. Add subscriptions to the new connection. * + * 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 {@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)); - * ``` */ connect(options?: ActorConnectOptions): Connection; } @@ -169,12 +150,6 @@ export interface ActorClient { * * @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; } @@ -194,8 +169,16 @@ export interface ActorClient { * - Close the connection with {@link Connection.close}. * * 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. + * for actor concepts and terminology, [Actor Class Reference](/developers/backend/resources/actors/reference) + * for the backend class API, and [Sample Flows](/developers/backend/resources/actors/samples) + * for common patterns. + * + * ## See also + * + * - [Actors Overview](/developers/backend/resources/actors/overview) — Actor concepts, sessions, message types, storage, and timers + * - [Actor Class Reference](/developers/backend/resources/actors/reference) — Backend class API + * - [Sample Flows](/developers/backend/resources/actors/samples) — Connect a client, run ticks, schedule wakes, and persist data + * - [`types generate`](/developers/references/cli/commands/types-generate) — Generate TypeScript types from deployed actors * * ## Authentication modes * From c13a506cc24ad414bc7f00f7fa64f13c92c5bfc8 Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:43:29 -0400 Subject: [PATCH 4/9] docs(actors): append actor and connector helper types into their host pages Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../appended-articles.json | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/scripts/mintlify-post-processing/appended-articles.json b/scripts/mintlify-post-processing/appended-articles.json index 27fb69b8..e3a9a330 100644 --- a/scripts/mintlify-post-processing/appended-articles.json +++ b/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" ] } From 745b44ba090ce3c9802adb848b5af82f1d04286b Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:46:12 -0400 Subject: [PATCH 5/9] docs(actors): remove See also section from ActorsModule JSDoc Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index 07e42f3a..4cc52990 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -173,13 +173,6 @@ export interface ActorClient { * for the backend class API, and [Sample Flows](/developers/backend/resources/actors/samples) * for common patterns. * - * ## See also - * - * - [Actors Overview](/developers/backend/resources/actors/overview) — Actor concepts, sessions, message types, storage, and timers - * - [Actor Class Reference](/developers/backend/resources/actors/reference) — Backend class API - * - [Sample Flows](/developers/backend/resources/actors/samples) — Connect a client, run ticks, schedule wakes, and persist data - * - [`types generate`](/developers/references/cli/commands/types-generate) — Generate TypeScript types from deployed actors - * * ## Authentication modes * * This module is available in anonymous or user authentication mode From 9528fe67b80b8ca8a77541a31e1692b5c2ef7f58 Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:47:23 -0400 Subject: [PATCH 6/9] docs(actors): link auth modes section to manage client connections sample Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index 4cc52990..8a61b6e7 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -178,6 +178,8 @@ export interface ActorClient { * 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. + * See [Manage client connections](/developers/backend/resources/actors/samples#manage-client-connections) + * for a sample flow. * * @example * ```typescript From f8c0a448311c08f9d783f10201c63c97ce01dc81 Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:51:05 -0400 Subject: [PATCH 7/9] docs(actors): fix broken links and improve ActorsModule intro - Replace {link} cross-references with anchor links for types appended to the same page - Rewrite ActorsModule intro to lead with client capabilities Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 45 ++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index 8a61b6e7..eb54c9de 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -30,7 +30,7 @@ export interface ActorRegistry {} * 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 {@link ActorRegistry}. + * incoming and outgoing message types manually, augment [ActorRegistry](#actorregistry). */ export interface ActorNameRegistry {} @@ -49,7 +49,7 @@ type ToServerFor = N extends keyof ActorRegistry : unknown; /** - * Options for {@link ActorRef.connect}. + * Options for [ActorRef.connect](#connect). */ export interface ActorConnectOptions { /** @@ -66,7 +66,7 @@ export interface ActorConnectOptions { /** * Represents an outgoing-message listener registered with - * {@link Connection.subscribe}. + * [Connection.subscribe](#subscribe). */ export interface ActorSubscription { /** @@ -78,7 +78,7 @@ export interface ActorSubscription { /** * Represents a client's WebSocket connection to an actor session. * - * {@link ActorRef.connect} returns this object while the socket connects. + * [ActorRef.connect](#connect) returns this object while the socket connects. * The socket buffers messages sent during connection setup until it opens. */ export interface Connection { @@ -98,10 +98,10 @@ export interface Connection { /** * Sends an incoming message to the actor. * - * The socket buffers messages until it opens. After {@link close}, the socket + * The socket buffers messages until it opens. After [close](#close), the socket * drops further sends. * - * @param data - Incoming message to send. Typed through {@link ActorRegistry} when configured. + * @param data - Incoming message to send. Typed through [ActorRegistry](#actorregistry) when configured. */ send(data: ToServerFor): void; @@ -109,7 +109,7 @@ export interface Connection { * 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. + * permanently. See [ActorRef.connect](#connect) for how to open a fresh connection. */ close(): void; } @@ -117,11 +117,11 @@ export interface Connection { /** * Represents an actor session selected by actor name and session ID. * - * Call {@link connect} to open the WebSocket and get a {@link Connection}. + * Call [connect](#connect) to open the WebSocket and get a [Connection](#connection). */ export interface ActorRef { /** - * Creates or returns the {@link Connection} for this session. + * 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 @@ -131,7 +131,7 @@ export interface ActorRef { * for a sample flow. * * @param options - Optional connection settings, such as a stable connection ID. - * @returns The {@link Connection} for this actor session. + * @returns The [Connection](#connection) for this actor session. */ connect(options?: ActorConnectOptions): Connection; } @@ -139,8 +139,8 @@ export interface ActorRef { /** * Selects a session for a named actor. * - * Typed automatically when the actor is registered in {@link ActorRegistry} or - * {@link ActorNameRegistry}. + * Typed automatically when the actor is registered in [ActorRegistry](#actorregistry) or + * [ActorNameRegistry](#actornameregistry). */ export interface ActorClient { /** @@ -157,16 +157,25 @@ export interface ActorClient { /** * 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. + * Use `base44.actors` to connect clients to a running actor session. The actors + * client lets you: + * + * - Subscribe to messages the actor sends — either broadcast to all connected + * clients or sent to your client directly. + * - Send messages to the actor from the client. + * - 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. + * + * The client works in the browser and in Node.js. * * ## Connection flow * * - Connect to a session with `base44.actors.(sessionId).connect()`. - * - Subscribe to outgoing messages with {@link Connection.subscribe}. - * - Send incoming messages with {@link Connection.send}. - * - Close the connection with {@link Connection.close}. + * - Subscribe to outgoing messages with [Connection.subscribe](#subscribe). + * - Send incoming messages with [Connection.send](#send). + * - Close the connection with [Connection.close](#close). * * See [Actors Overview](/developers/backend/resources/actors/overview) * for actor concepts and terminology, [Actor Class Reference](/developers/backend/resources/actors/reference) From 7103cbaaef3b98926adb68bc597128d06cf91610 Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 00:55:49 -0400 Subject: [PATCH 8/9] docs(actors): rewrite ActorsModule intro with capability-first framing Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index eb54c9de..3880d5b8 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -155,32 +155,19 @@ export interface ActorClient { } /** - * Provides access to actors and their shared, live sessions. + * Use `base44.actors` to connect your frontend to [actor sessions](/developers/backend/resources/actors/overview), + * shared live backend processes where clients exchange messages in realtime. * - * Use `base44.actors` to connect clients to a running actor session. The actors - * client lets you: - * - * - Subscribe to messages the actor sends — either broadcast to all connected - * clients or sent to your client directly. - * - Send messages to the actor from the client. + * - Connect to a session with `base44.actors.(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. * - * The client works in the browser and in Node.js. - * - * ## Connection flow - * - * - Connect to a session with `base44.actors.(sessionId).connect()`. - * - Subscribe to outgoing messages with [Connection.subscribe](#subscribe). - * - Send incoming messages with [Connection.send](#send). - * - Close the connection with [Connection.close](#close). - * - * See [Actors Overview](/developers/backend/resources/actors/overview) - * for actor concepts and terminology, [Actor Class Reference](/developers/backend/resources/actors/reference) - * for the backend class API, and [Sample Flows](/developers/backend/resources/actors/samples) - * for common patterns. + * Learn more about [actors](/developers/backend/resources/actors/overview). * * ## Authentication modes * From 72711218dd0da0a6e0dad47496a16862ed292d6b Mon Sep 17 00:00:00 2001 From: "Abraham (Avi) Soclof" Date: Wed, 23 Sep 2026 01:04:55 -0400 Subject: [PATCH 9/9] docs(actors): update ActorsModule JSDoc and fix Connection JSDoc blank line Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/modules/actors.types.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/modules/actors.types.ts b/src/modules/actors.types.ts index 3880d5b8..bf6662f0 100644 --- a/src/modules/actors.types.ts +++ b/src/modules/actors.types.ts @@ -156,7 +156,9 @@ export interface ActorClient { /** * Use `base44.actors` to connect your frontend to [actor sessions](/developers/backend/resources/actors/overview), - * shared live backend processes where clients exchange messages in realtime. + * 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.(sessionId).connect()`. * - Subscribe to messages the actor sends using [Connection.subscribe](#subscribe), @@ -171,14 +173,17 @@ export interface ActorClient { * * ## 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. - * See [Manage client connections](/developers/backend/resources/actors/samples#manage-client-connections) - * for a sample flow. - * + * 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 + * 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" });