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" ] } 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..bf6662f0 100644 --- a/src/modules/actors.types.ts +++ b/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 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 { - /** 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) => 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): 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 { /** - * 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; } /** - * 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 { + /** + * 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; } /** - * 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.(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();