@base44-preview/sdk 0.8.37-pr.212.00d8065 → 0.8.37-pr.212.f0764ee

package/dist/{realtime-handler.d.ts → actor.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Type-only base class for Realtime Handlers.
+ * Type-only base class for Actors.
  *
- * Import and extend this in your handler files:
- *   import { RealtimeHandler } from "@base44/sdk";
- *   export class MyHandler extends RealtimeHandler { ... }
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
  *
  * At deploy time the bundler replaces this import with the compiled
  * Cloudflare Durable Object implementation — this file provides types only.
@@ -11,7 +11,7 @@
 import type { Base44Client } from "./client.types.js";
 /**
  * A single client connection. `Send` is the message type this connection accepts
- * via {@link send} — the handler's *outgoing* (server→client) messages.
+ * via {@link send} — the actor's *outgoing* (server→client) messages.
  */
 export interface Conn<Send = unknown> {
     /** Unique per-connection id (one per socket/tab), the same value the client
@@ -30,21 +30,21 @@ export interface Storage {
     delete(key: string): Promise<boolean>;
 }
 /**
- * Base class for a Realtime Handler.
+ * Base class for an Actor.
  *
- * @typeParam Incoming - messages this handler *receives* from clients
+ * @typeParam Incoming - messages this actor *receives* from clients
  *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
- * @typeParam Outgoing - messages this handler *sends* to clients
+ * @typeParam Outgoing - messages this actor *sends* to clients
  *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
  *
  * With a generated `schema.jsonc`, wire both from the registry so they can't drift
  * from the client's types:
  * ```ts
- * type Reg = RealtimeHandlerRegistry["MyHandler"];
- * class MyHandler extends RealtimeHandler<Reg["toServer"], Reg["toClient"]> { ... }
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
  * ```
  */
-export declare abstract class RealtimeHandler<Incoming = unknown, Outgoing = unknown> {
+export declare abstract class Actor<Incoming = unknown, Outgoing = unknown> {
     abstract handleConnect(conn: Conn<Outgoing>): void | Promise<void>;
     abstract handleMessage(conn: Conn<Outgoing>, msg: Incoming): void | Promise<void>;
     abstract handleClose(conn: Conn<Outgoing>): void | Promise<void>;

package/dist/{realtime-handler.js → actor.js}

@@ -1,29 +1,29 @@
 /**
- * Type-only base class for Realtime Handlers.
+ * Type-only base class for Actors.
  *
- * Import and extend this in your handler files:
- *   import { RealtimeHandler } from "@base44/sdk";
- *   export class MyHandler extends RealtimeHandler { ... }
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
  *
  * At deploy time the bundler replaces this import with the compiled
  * Cloudflare Durable Object implementation — this file provides types only.
  */
 /**
- * Base class for a Realtime Handler.
+ * Base class for an Actor.
  *
- * @typeParam Incoming - messages this handler *receives* from clients
+ * @typeParam Incoming - messages this actor *receives* from clients
  *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
- * @typeParam Outgoing - messages this handler *sends* to clients
+ * @typeParam Outgoing - messages this actor *sends* to clients
  *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
  *
  * With a generated `schema.jsonc`, wire both from the registry so they can't drift
  * from the client's types:
  * ```ts
- * type Reg = RealtimeHandlerRegistry["MyHandler"];
- * class MyHandler extends RealtimeHandler<Reg["toServer"], Reg["toClient"]> { ... }
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
  * ```
  */
-export class RealtimeHandler {
+export class Actor {
     constructor() {
         /**
          * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
@@ -39,22 +39,22 @@ export class RealtimeHandler {
     }
     onStart() { }
     broadcast(_data) {
-        throw new Error("RealtimeHandler.broadcast() is only available inside a deployed handler");
+        throw new Error("Actor.broadcast() is only available inside a deployed actor");
     }
     getConnections() {
-        throw new Error("RealtimeHandler.getConnections() is only available inside a deployed handler");
+        throw new Error("Actor.getConnections() is only available inside a deployed actor");
     }
     startLoop(_ms) {
-        throw new Error("RealtimeHandler.startLoop() is only available inside a deployed handler");
+        throw new Error("Actor.startLoop() is only available inside a deployed actor");
     }
     stopLoop() {
-        throw new Error("RealtimeHandler.stopLoop() is only available inside a deployed handler");
+        throw new Error("Actor.stopLoop() is only available inside a deployed actor");
     }
     get instanceId() {
-        throw new Error("RealtimeHandler.instanceId is only available inside a deployed handler");
+        throw new Error("Actor.instanceId is only available inside a deployed actor");
     }
     get storage() {
-        throw new Error("RealtimeHandler.storage is only available inside a deployed handler");
+        throw new Error("Actor.storage is only available inside a deployed actor");
     }
     /**
      * SDK client acting **as the connected user** — every entity call respects
@@ -66,7 +66,7 @@ export class RealtimeHandler {
      */
     createClientFromConnection(conn) {
         void conn;
-        throw new Error("RealtimeHandler.createClientFromConnection() is only available inside a deployed handler");
+        throw new Error("Actor.createClientFromConnection() is only available inside a deployed actor");
     }
     /**
      * Service-role SDK client — bypasses RLS. For work with **no user in scope**
@@ -74,6 +74,6 @@ export class RealtimeHandler {
      * `createClientFromConnection(conn)`.
      */
     createServiceClient() {
-        throw new Error("RealtimeHandler.createServiceClient() is only available inside a deployed handler");
+        throw new Error("Actor.createServiceClient() is only available inside a deployed actor");
     }
 }

package/dist/client.js

@@ -12,7 +12,7 @@ import { createAppLogsModule } from "./modules/app-logs.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
 import { createAnalyticsModule } from "./modules/analytics.js";
-import { createRealtimeModule } from "./modules/realtime.js";
+import { createActorsModule } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
  *
@@ -179,17 +179,17 @@ export function createClient(config) {
             appId,
             userAuthModule,
         }),
-        realtime: createRealtimeModule({
+        actors: createActorsModule({
             appId,
             dispatcherWsUrl: resolvedDispatcherWsUrl,
             webSocketImpl,
-            getToken: async (handlerName, instanceId, connId) => {
+            getToken: async (actorName, instanceId, connId) => {
                 // axiosClient interceptors unwrap response.data, so the result is the body directly.
                 // conn_id rides inside the signed token (not a WS query param) so it survives
-                // proxies that strip params; the dispatcher forwards it as the handler's conn.id.
+                // proxies that strip params; the dispatcher forwards it as the actor's conn.id.
                 // Base44-Functions-Version rides along (like function calls) so live apps get
-                // tokens for the *published* realtime script and previews get the draft.
-                const data = await axiosClient.post(`/apps/${appId}/realtime-token`, { handler_name: handlerName, instance_id: instanceId, conn_id: connId }, functionsVersion
+                // tokens for the *published* actor script and previews get the draft.
+                const data = await axiosClient.post(`/apps/${appId}/actor-token`, { handler_name: actorName, instance_id: instanceId, conn_id: connId }, functionsVersion
                     ? { headers: { "Base44-Functions-Version": functionsVersion } }
                     : undefined);
                 return data.token;

package/dist/client.types.d.ts

@@ -8,7 +8,7 @@ import type { AgentsModule } from "./modules/agents.types.js";
 import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
-import type { RealtimeModule } from "./modules/realtime.types.js";
+import type { ActorsModule } from "./modules/actors.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -111,8 +111,8 @@ export interface Base44Client {
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
-    /** {@link RealtimeModule | Realtime module} for subscribing to and sending messages via Cloudflare Durable Object-backed RealtimeHandlers. */
-    realtime: RealtimeModule;
+    /** {@link ActorsModule | Actors module} for subscribing to and sending messages via Cloudflare Durable Object-backed Actors. */
+    actors: ActorsModule;
     /** {@link AuthModule | Auth module} for user authentication and management. */
     auth: AuthModule;
     /** {@link UserConnectorsModule | Connectors module} for app-user OAuth flows. */

package/dist/index.d.ts

@@ -11,9 +11,9 @@ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./mod
 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 { AppLogsModule } from "./modules/app-logs.types.js";
-export type { RealtimeModule, RealtimeHandlerClient, RealtimeHandlerNameRegistry, RealtimeHandlerRegistry, } from "./modules/realtime.types.js";
+export type { ActorsModule, ActorClient, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
-export { RealtimeHandler, type Conn } from "./realtime-handler.js";
+export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

package/dist/index.js

@@ -3,4 +3,4 @@ import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export * from "./types.js";
-export { RealtimeHandler } from "./realtime-handler.js";
+export { Actor } from "./actor.js";

package/dist/modules/{realtime.d.ts → actors.d.ts}

@@ -1,21 +1,21 @@
-export declare function createRealtimeModule(config: {
+export declare function createActorsModule(config: {
     appId: string;
-    getToken(handlerName: string, instanceId: string, connId: string): Promise<string>;
+    getToken(actorName: string, instanceId: string, connId: string): Promise<string>;
     dispatcherWsUrl: string;
     /** WebSocket implementation for runtimes without a global one (Node < 22). */
     webSocketImpl?: unknown;
-}): Record<string, RealtimeHandler>;
-/** Handle for an active realtime subscription. */
-interface RealtimeSubscription {
-    /** This connection's id — the same value the handler receives as `conn.id`. */
+}): Record<string, ActorClient>;
+/** Handle for an active actor subscription. */
+interface ActorSubscription {
+    /** This connection's id — the same value the actor receives as `conn.id`. */
     id: string;
     /** Close the subscription and its underlying socket. */
     unsubscribe(): void;
 }
-interface RealtimeHandler {
+interface ActorClient {
     subscribe(instanceId: string, callback: (data: unknown) => void, options?: {
         id?: string;
-    }): RealtimeSubscription;
+    }): ActorSubscription;
     send(instanceId: string, data: unknown): void;
 }
 export {};

package/dist/modules/{realtime.js → actors.js}

@@ -1,32 +1,32 @@
 import PartySocket from "partysocket";
-// Module-level map: "HandlerName:instanceId" → active socket
+// Module-level map: "ActorName:instanceId" → active socket
 const activeSockets = new Map();
-function socketKey(handlerName, instanceId) {
-    return `${handlerName}:${instanceId}`;
+function socketKey(actorName, instanceId) {
+    return `${actorName}:${instanceId}`;
 }
-export function createRealtimeModule(config) {
+export function createActorsModule(config) {
     return new Proxy({}, {
-        get(_, handlerName) {
+        get(_, actorName) {
             return {
                 subscribe(instanceId, callback, options) {
                     var _a, _b;
-                    const key = socketKey(handlerName, instanceId);
+                    const key = socketKey(actorName, instanceId);
                     // close existing if any
                     (_a = activeSockets.get(key)) === null || _a === void 0 ? void 0 : _a.close();
                     // Connection id: caller-supplied (stable — reuse across reconnects/tabs as
                     // you see fit) or auto-generated per subscription. It travels INSIDE the
-                    // signed realtime token (never as a WS query param, which proxies strip);
+                    // signed actor token (never as a WS query param, which proxies strip);
                     // the dispatcher forwards the verified claim as partyserver's _pk, so the
-                    // handler sees this exact value as conn.id. Reconnects re-mint the token
+                    // actor sees this exact value as conn.id. Reconnects re-mint the token
                     // with the same id, so conn.id is stable across reconnects.
                     const connId = (_b = options === null || options === void 0 ? void 0 : options.id) !== null && _b !== void 0 ? _b : crypto.randomUUID();
                     // query as async fn: called on every (re)connect, fetches a fresh token each time
                     const ws = new PartySocket({
                         host: config.dispatcherWsUrl,
-                        party: handlerName,
+                        party: actorName,
                         room: instanceId,
                         ...(config.webSocketImpl ? { WebSocket: config.webSocketImpl } : {}),
-                        query: () => config.getToken(handlerName, instanceId, connId).then((token) => ({ token })),
+                        query: () => config.getToken(actorName, instanceId, connId).then((token) => ({ token })),
                     });
                     activeSockets.set(key, ws);
                     // Heartbeat / half-open detection. PartySocket only reconnects on a
@@ -68,7 +68,7 @@ export function createRealtimeModule(config) {
                         }
                     }, PING_MS);
                     return {
-                        id: connId, // the connection id (same value the handler sees as conn.id)
+                        id: connId, // the connection id (same value the actor sees as conn.id)
                         unsubscribe() {
                             clearInterval(heartbeat);
                             activeSockets.delete(key);
@@ -77,10 +77,10 @@ export function createRealtimeModule(config) {
                     };
                 },
                 send(instanceId, data) {
-                    const key = socketKey(handlerName, instanceId);
+                    const key = socketKey(actorName, instanceId);
                     const ws = activeSockets.get(key);
                     if (!ws)
-                        throw new Error(`No active subscription for ${handlerName}:${instanceId}`);
+                        throw new Error(`No active subscription for ${actorName}:${instanceId}`);
                     ws.send(JSON.stringify(data));
                 },
             };

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

@@ -0,0 +1,77 @@
+/**
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed Actors.
+ *
+ * This is separate from {@link ActorNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
+ *
+ * @example
+ * ```typescript
+ * declare module "@base44/sdk" {
+ *   interface ActorRegistry {
+ *     ChatRoom: {
+ *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
+ *       toServer: { type: "message"; text: string };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+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.
+ */
+export interface ActorNameRegistry {
+}
+type AllActorNames = keyof ActorRegistry | keyof ActorNameRegistry;
+type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toClient: infer I;
+} ? I : unknown : unknown;
+type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toServer: infer O;
+} ? O : unknown : unknown;
+/**
+ * Client for a single named Actor.
+ * Typed automatically when the actor is registered in {@link ActorRegistry}.
+ */
+export interface ActorClient<N extends string = string> {
+    /**
+     * Open a WebSocket subscription. Returns a {@link ActorSubscription} with the
+     * connection `id` (same value the actor sees as `conn.id`) and an `unsubscribe()` method.
+     *
+     * Pass `options.id` to control the connection id (e.g. a stable per-tab id so a
+     * reconnect reuses the same server-side connection); omit it for an auto-generated
+     * per-connection id.
+     */
+    subscribe(instanceId: string, callback: (data: ToClientFor<N>) => void, options?: {
+        id?: string;
+    }): ActorSubscription;
+    /** Send a message over the open socket. Throws if not subscribed. */
+    send(instanceId: string, data: ToServerFor<N>): void;
+}
+/** Handle for an active actor subscription. */
+export interface ActorSubscription {
+    /** This connection's id — the same value the actor receives as `conn.id`. */
+    id: string;
+    /** Close the subscription and its underlying socket. */
+    unsubscribe(): void;
+}
+/**
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
+ *
+ * Actor names are accessed as dynamic properties on this module:
+ * ```typescript
+ * const sub = await base44.actors.MyActor.subscribe("room-1", (msg) => {
+ *   console.log(msg); // typed if MyActor is in ActorRegistry
+ * });
+ * const { id, unsubscribe } = sub;
+ * unsubscribe();
+ * ```
+ */
+export type ActorsModule = {
+    [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;
+} & Record<string, ActorClient>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.37-pr.212.00d8065",
+  "version": "0.8.37-pr.212.f0764ee",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,77 +0,0 @@
-/**
- * Extend this interface to add typed `subscribe` callbacks and `send` payloads
- * for your deployed RealtimeHandlers.
- *
- * This is separate from {@link RealtimeHandlerNameRegistry} (which is auto-generated
- * by `base44 types generate`), so there are no conflicts.
- *
- * @example
- * ```typescript
- * declare module "@base44/sdk" {
- *   interface RealtimeHandlerRegistry {
- *     ChatRoom: {
- *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
- *       toServer: { type: "message"; text: string };
- *     };
- *   }
- * }
- * ```
- */
-export interface RealtimeHandlerRegistry {
-}
-/**
- * Auto-populated by `base44 types generate` with the names of your deployed handlers.
- * Do not edit this interface manually — use {@link RealtimeHandlerRegistry} for message types.
- */
-export interface RealtimeHandlerNameRegistry {
-}
-type AllHandlerNames = keyof RealtimeHandlerRegistry | keyof RealtimeHandlerNameRegistry;
-type ToClientFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
-    toClient: infer I;
-} ? I : unknown : unknown;
-type ToServerFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
-    toServer: infer O;
-} ? O : unknown : unknown;
-/**
- * Client for a single named RealtimeHandler.
- * Typed automatically when the handler is registered in {@link RealtimeHandlerRegistry}.
- */
-export interface RealtimeHandlerClient<N extends string = string> {
-    /**
-     * Open a WebSocket subscription. Returns a {@link RealtimeSubscription} with the
-     * connection `id` (same value the handler sees as `conn.id`) and an `unsubscribe()` method.
-     *
-     * Pass `options.id` to control the connection id (e.g. a stable per-tab id so a
-     * reconnect reuses the same server-side connection); omit it for an auto-generated
-     * per-connection id.
-     */
-    subscribe(instanceId: string, callback: (data: ToClientFor<N>) => void, options?: {
-        id?: string;
-    }): RealtimeSubscription;
-    /** Send a message over the open socket. Throws if not subscribed. */
-    send(instanceId: string, data: ToServerFor<N>): void;
-}
-/** Handle for an active realtime subscription. */
-export interface RealtimeSubscription {
-    /** This connection's id — the same value the handler receives as `conn.id`. */
-    id: string;
-    /** Close the subscription and its underlying socket. */
-    unsubscribe(): void;
-}
-/**
- * The realtime module provides access to Cloudflare Durable Object-backed
- * RealtimeHandlers deployed by the Base44 platform.
- *
- * Handler names are accessed as dynamic properties on this module:
- * ```typescript
- * const sub = await base44.realtime.MyHandler.subscribe("room-1", (msg) => {
- *   console.log(msg); // typed if MyHandler is in RealtimeHandlerRegistry
- * });
- * const { id, unsubscribe } = sub;
- * unsubscribe();
- * ```
- */
-export type RealtimeModule = {
-    [K in AllHandlerNames]: K extends keyof RealtimeHandlerRegistry ? RealtimeHandlerClient<string & K> : RealtimeHandlerClient;
-} & Record<string, RealtimeHandlerClient>;
-export {};