@base44-preview/sdk 0.8.48-pr.288.6247e7c → 0.8.48-pr.289.b9ea964

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

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, Change
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
-export type { AiGatewayModule, AiGatewayConnection, AiGatewayConnectionOptions, } from "./modules/ai-gateway.types.js";
+export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { AppModule, AppPublicSettings, AppPublicSettingsResponse, } from "./modules/app.types.js";
 export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";

package/dist/modules/actors.types.d.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 {
 }
@@ -32,71 +35,163 @@ 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}. */
+/**
+ * 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<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.
+     *
+     * @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<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 {@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<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 {@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<N extends string = string> {
     /**
-     * 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<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 {@link ActorRegistry} or
+ * {@link 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.
+     *
+     * @example
+     * ```typescript
+     * const session = base44.actors.Chat("lobby-1");
+     * const conn = session.connect();
+     * ```
+     */
     (instanceId: string): ActorRef<N>;
 }
 /**
- * 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.<ActorName>(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();

package/dist/modules/ai-gateway.js

@@ -1,19 +1,11 @@
 import { getAccessToken } from "../utils/auth-utils.js";
-const PROVIDER_PATHS = {
-    openai: "openai",
-    typesafe: "typesafe",
-};
 export function createAiGatewayModule({ serverUrl, token, appId, }) {
-    const connection = ({ provider = "openai" } = {}) => {
+    const connection = () => {
         var _a;
-        if (!Object.prototype.hasOwnProperty.call(PROVIDER_PATHS, provider)) {
-            throw new Error(`Unsupported AI Gateway provider: ${provider}`);
-        }
-        const providerPath = PROVIDER_PATHS[provider];
-        return {
-            baseURL: `${serverUrl}/api/apps/${appId}/ai/${providerPath}/v1`,
+        return ({
+            baseURL: `${serverUrl}/api/apps/${appId}/ai/openai/v1`,
             token: (_a = token !== null && token !== void 0 ? token : getAccessToken()) !== null && _a !== void 0 ? _a : "",
-        };
+        });
     };
     return {
         connection,

package/dist/modules/ai-gateway.types.d.ts

@@ -2,7 +2,7 @@
  * Connection details for the Base44 AI Gateway.
  */
 export interface AiGatewayConnection {
-    /** Base URL of the selected gateway provider. */
+    /** Base URL of the gateway's OpenAI-compatible Chat Completions endpoint. */
     baseURL: string;
     /**
      * Bearer token that authenticates the request. Empty string when the caller is
@@ -10,11 +10,6 @@ export interface AiGatewayConnection {
      */
     token: string;
 }
-/** Options for selecting an AI Gateway provider. */
-export interface AiGatewayConnectionOptions {
-    /** Gateway provider to connect to. Defaults to `openai`. */
-    provider?: "openai" | "typesafe";
-}
 /**
  * Configuration for the AI Gateway module.
  * @internal
@@ -31,10 +26,13 @@ export interface AiGatewayModuleConfig {
  * AI Gateway module for calling Base44's managed AI models from your own code.
  *
  * `connection()` hands you a `baseURL` and `token` that authenticate as your
- * Base44 app. It defaults to the OpenAI-compatible Chat Completions provider;
- * pass `{ provider: "typesafe" }` for the TypeSafe evaluation provider. Pass
- * the returned values to the corresponding client with no separate provider
- * account, API key, or billing setup.
+ * Base44 app. An OpenAI-compatible client is any library, such as the `openai`
+ * SDK or the Vercel AI SDK, that has the same request and response format
+ * as OpenAI's Chat Completions API and lets you point it at a custom `baseURL`
+ * instead of OpenAI's own servers. Pass `connection()`'s values to one of
+ * these clients and it works against Base44's gateway exactly as it would
+ * against the provider directly, no separate account, API key, or billing
+ * setup with the underlying model provider required.
  *
  * Call `connection()` from a backend function rather than the browser. This
  * keeps your instructions, tools, and business logic server-side, and lets
@@ -42,13 +40,7 @@ export interface AiGatewayModuleConfig {
  * `token` it returns is the caller's regular session token, the same one
  * used for every other SDK call.
  *
- * ## Providers
- *
- * - **OpenAI-compatible** (default): Works with clients such as the `openai`
- *   SDK or Vercel AI SDK clients that accept a custom `baseURL`.
- * - **TypeSafe**: Works with `@ai-sdk/typesafe-ai` for structured evaluations.
- *
- * ## OpenAI-compatible models
+ * ## Models
  *
  * You can use any of the [models available through `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm).
  * Pass `'automatic'` to let Base44 choose one, or pin a specific model such
@@ -77,15 +69,13 @@ export interface AiGatewayModule {
     /**
      * Gets the connection details for the Base44 AI Gateway.
      *
-     * Returns the `baseURL` and `token` to pass to the selected provider client.
-     *
-     * @param options - Provider selection. Omit it to use the OpenAI-compatible gateway.
+     * Returns the `baseURL` and `token` to pass to any OpenAI-compatible client.
      *
      * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`).
      *
      * @example
      * ```typescript
-     * // Call an OpenAI-compatible model directly
+     * // Call a model directly
      * import { createClientFromRequest } from "@base44/sdk";
      * import OpenAI from "openai";
      *
@@ -145,5 +135,5 @@ export interface AiGatewayModule {
      * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });
      * ```
      */
-    connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
+    connection(): AiGatewayConnection;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.288.6247e7c",
+  "version": "0.8.48-pr.289.b9ea964",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",