@base44-preview/sdk 0.8.49-pr.289.dd3fb8f → 0.8.50-pr.290.00d2bf0

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 session's entire persisted storage. A later connection starts
-     *  with the same empty storage as a new session. */
+    /** Wipe the room's entire persisted storage (match-end cleanup). Safe: a
+     *  later rejoin re-bootstraps exactly like a brand-new room. */
     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, } from "./modules/ai-gateway.types.js";
+export type { AiGatewayModule, AiGatewayConnection, AiGatewayConnectionOptions, } 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,15 +1,9 @@
 /**
- * Maps actor names to their incoming and outgoing message types.
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed Actors.
  *
- * 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.
+ * This is separate from {@link ActorNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
  *
  * @example
  * ```typescript
@@ -26,11 +20,8 @@
 export interface ActorRegistry {
 }
 /**
- * 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}.
+ * 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.
  */
 export interface ActorNameRegistry {
 }
@@ -41,135 +32,71 @@ 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 {
     /**
-     * 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.
+     * 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.
      */
     id?: string;
 }
-/**
- * Represents an outgoing-message listener registered with
- * {@link Connection.subscribe}.
- */
+/** Handle for one listener registered via {@link Connection.subscribe}. */
 export interface ActorSubscription {
-    /**
-     * Removes this listener. Other listeners and the socket stay open.
-     */
+    /** Remove this listener; other listeners and the socket stay live. */
     unsubscribe(): void;
 }
 /**
- * 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.
+ * 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.
  */
 export interface Connection<N extends string = string> {
-    /** Connection ID that the actor receives as `conn.id`. */
+    /** The connection id (the value the actor sees as `conn.id`). */
     readonly id: string;
-    /**
-     * 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.
-     */
+    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /**
-     * 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.
-     */
+    /** Send a message. Buffered by the socket until it's open; dropped after
+     * {@link close}. */
     send(data: ToServerFor<N>): void;
     /**
-     * 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.
+     * 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}.
      */
     close(): void;
 }
 /**
- * Represents an actor session selected by actor name and session ID.
- *
- * Call {@link connect} to open the WebSocket and get a {@link Connection}.
+ * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
+ * {@link connect} to open the socket and get a {@link Connection}.
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * 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.
-     *
-     * See [Connect a client to a session](/developers/backend/resources/actors/samples#connect-a-client-to-a-session)
-     * for a sample flow.
+     * Open the WebSocket and return the {@link Connection}. Idempotent while the
+     * connection is open.
      *
-     * @param options - Optional connection settings, such as a stable connection ID.
-     * @returns The {@link Connection} for this actor 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.
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**
- * Selects a session for a named actor.
- *
- * Typed automatically when the actor is registered in {@link ActorRegistry} or
- * {@link ActorNameRegistry}.
+ * 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}.
  */
 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>;
 }
 /**
- * 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}.
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
  *
- * 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.
- *
- * ## 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.
- *
- * @example
  * ```typescript
- * const conn = base44.actors.Chat("session-1").connect({ id: "tab-1" });
- * const sub = conn.subscribe((msg) => console.log(msg));
+ * const conn = base44.actors.MyActor("room-1").connect();
+ * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();

package/dist/modules/ai-gateway.js

@@ -1,11 +1,19 @@
 import { getAccessToken } from "../utils/auth-utils.js";
+const PROVIDER_PATHS = {
+    openai: "openai",
+    typesafe: "typesafe",
+};
 export function createAiGatewayModule({ serverUrl, token, appId, }) {
-    const connection = () => {
+    const connection = ({ provider = "openai" } = {}) => {
         var _a;
-        return ({
-            baseURL: `${serverUrl}/api/apps/${appId}/ai/openai/v1`,
+        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`,
             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 gateway's OpenAI-compatible Chat Completions endpoint. */
+    /** Base URL of the selected gateway provider. */
     baseURL: string;
     /**
      * Bearer token that authenticates the request. Empty string when the caller is
@@ -10,6 +10,11 @@ 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
@@ -34,13 +39,17 @@ export interface AiGatewayModuleConfig {
  * against the provider directly, no separate account, API key, or billing
  * setup with the underlying model provider required.
  *
+ * By default, `connection()` uses the OpenAI-compatible provider. Pass
+ * `{ provider: "typesafe" }` to connect to TypeSafe for structured evaluations
+ * with `@ai-sdk/typesafe-ai`.
+ *
  * Call `connection()` from a backend function rather than the browser. This
  * keeps your instructions, tools, and business logic server-side, and lets
  * you enforce your own auth, rate, and spend limits around the call. The
  * `token` it returns is the caller's regular session token, the same one
  * used for every other SDK call.
  *
- * ## Models
+ * ## OpenAI-compatible 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
@@ -69,7 +78,9 @@ export interface AiGatewayModule {
     /**
      * Gets the connection details for the Base44 AI Gateway.
      *
-     * Returns the `baseURL` and `token` to pass to any OpenAI-compatible client.
+     * 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 gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`).
      *
@@ -135,5 +146,5 @@ export interface AiGatewayModule {
      * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });
      * ```
      */
-    connection(): AiGatewayConnection;
+    connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
 }

package/dist/modules/entities.types.d.ts

@@ -950,6 +950,16 @@ type DynamicEntitiesModule = {
  * - **Anonymous or User authentication** (`base44.entities`): Access is scoped to the current user's permissions. Anonymous users can only access public entities, while authenticated users can access entities they have permission to view or modify.
  * - **Service role authentication** (`base44.asServiceRole.entities`): Operations bypass entity access rules and field-level security entirely. Can read and write any record in any entity.
  *
+ * ## How denied reads and writes differ
+ *
+ * Row-level security handles reads and writes differently.
+ *
+ * | Operation | When a rule denies it |
+ * | --- | --- |
+ * | `list()`, `filter()` | Returns an empty result, the same as if nothing matched. No error is thrown. |
+ * | `get()` | Throws a not-found error, whether or not the record exists. |
+ * | `create()`, `update()` | Throws a permission error with HTTP 403. |
+ *
  * ## Entity Handlers
  *
  * An entity handler is the object you get when you access an entity through `base44.entities.EntityName`. Every entity in your app automatically gets a handler with CRUD methods for managing records.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.49-pr.289.dd3fb8f",
+  "version": "0.8.50-pr.290.00d2bf0",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",