@base44-preview/sdk 0.8.39-pr.237.783a84a → 0.8.40-pr.212.5212229

package/dist/actor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * 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.
+ */
+/**
+ * A single client connection. `Send` is the message type this connection accepts
+ * 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
+     *  receives from `subscribe()`. Use this — not userId — to identify a distinct
+     *  client, so multiple tabs of the same user are separate connections. */
+    id: string;
+    userId: string;
+    appId: string;
+    instanceId: string;
+    send(data: Send): void;
+    reject(code: number, reason: string): void;
+}
+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. */
+    deleteAll(): Promise<void>;
+}
+/**
+ * Base class for an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @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 = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+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>;
+    abstract handleTick(): void | Promise<void>;
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart(): void | Promise<void>;
+    /**
+     * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+     * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+     * and stops (letting the Durable Object hibernate — no compute cost) when it
+     * returns false. The platform owns scheduling, rescheduling, self-heal, and
+     * error-safety — you don't call {@link startLoop}/{@link stopLoop}.
+     *
+     * Re-evaluated after every connect/message/close and on every tick, so keep it
+     * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+     */
+    protected tickIntervalMs: number;
+    protected shouldTick?(): boolean;
+    protected broadcast(_data: Outgoing): void;
+    protected getConnections(): Conn<Outgoing>[];
+    protected startLoop(_ms: number): Promise<void>;
+    protected stopLoop(): Promise<void>;
+    protected get instanceId(): string;
+    protected get storage(): Storage;
+}

package/dist/actor.js

@@ -0,0 +1,63 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * 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 an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @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 = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export class Actor {
+    constructor() {
+        /**
+         * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+         * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+         * and stops (letting the Durable Object hibernate — no compute cost) when it
+         * returns false. The platform owns scheduling, rescheduling, self-heal, and
+         * error-safety — you don't call {@link startLoop}/{@link stopLoop}.
+         *
+         * Re-evaluated after every connect/message/close and on every tick, so keep it
+         * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+         */
+        this.tickIntervalMs = 100;
+    }
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart() { }
+    broadcast(_data) {
+        throw new Error("Actor.broadcast() is only available inside a deployed actor");
+    }
+    getConnections() {
+        throw new Error("Actor.getConnections() is only available inside a deployed actor");
+    }
+    startLoop(_ms) {
+        throw new Error("Actor.startLoop() is only available inside a deployed actor");
+    }
+    stopLoop() {
+        throw new Error("Actor.stopLoop() is only available inside a deployed actor");
+    }
+    get instanceId() {
+        throw new Error("Actor.instanceId is only available inside a deployed actor");
+    }
+    get storage() {
+        throw new Error("Actor.storage is only available inside a deployed actor");
+    }
+}

package/dist/client.js

@@ -12,6 +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 { createActorsModule } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
  *
@@ -51,9 +52,27 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  */
 export function createClient(config) {
     var _a, _b;
-    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
+    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, dispatcherWsUrl, webSocketImpl, } = config;
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
+    // Derive the dispatcher WebSocket URL if not explicitly provided. Default to
+    // the app's OWN origin (the app URL proxies /parties to the backend) so the
+    // socket is same-origin with the running app, not the API host: prefer an
+    // explicit appBaseUrl, then the browser origin, then fall back to serverUrl
+    // (Node/SSR, where there's no window). Convert https:// → wss:// (http → ws)
+    // and strip the trailing slash.
+    const resolvedDispatcherWsUrl = (() => {
+        var _a, _b;
+        if (dispatcherWsUrl)
+            return dispatcherWsUrl.replace(/\/$/, "");
+        const appOrigin = normalizedAppBaseUrl ||
+            // React Native has a bare `window` with no `location`, so guard both.
+            (typeof window !== "undefined" ? (_b = (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin) !== null && _b !== void 0 ? _b : "" : "");
+        return (appOrigin || serverUrl)
+            .replace(/\/$/, "")
+            .replace(/^https:\/\//, "wss://")
+            .replace(/^http:\/\//, "ws://");
+    })();
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -160,6 +179,15 @@ export function createClient(config) {
             appId,
             userAuthModule,
         }),
+        actors: createActorsModule({
+            appId,
+            dispatcherWsUrl: resolvedDispatcherWsUrl,
+            webSocketImpl,
+            functionsVersion,
+            // Same credential as function calls; the platform proxy authenticates the
+            // WS connection with it (anonymous when absent) — no pre-connect token mint.
+            getAuthToken: () => token || getAccessToken(),
+        }),
         cleanup: () => {
             userModules.analytics.cleanup();
             if (socket) {

package/dist/client.types.d.ts

@@ -8,6 +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 { ActorsModule } from "./modules/actors.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -73,6 +74,28 @@ export interface CreateClientConfig {
      * Additional client options.
      */
     options?: CreateClientOptions;
+    /**
+     * Base WebSocket URL for the Cloudflare Durable Object dispatcher.
+     *
+     * Defaults to the app's own origin (`appBaseUrl`, else the browser's
+     * `window.location.origin`, else `serverUrl`) with `https://` replaced by
+     * `wss://` (or `http://` by `ws://`) — so the realtime socket is same-origin
+     * with the running app, which proxies `/parties` to the backend.
+     * Override when the dispatcher lives at a different host than the app.
+     */
+    dispatcherWsUrl?: string;
+    /**
+     * WebSocket implementation for realtime subscriptions in environments
+     * without a global `WebSocket` (Node.js < 22). Browsers and Node ≥ 22
+     * don't need this.
+     *
+     * @example
+     * ```typescript
+     * import WS from "ws";
+     * const base44 = createClient({ appId, webSocketImpl: WS });
+     * ```
+     */
+    webSocketImpl?: unknown;
 }
 /**
  * The Base44 client instance.
@@ -88,6 +111,8 @@ export interface Base44Client {
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
+    /** {@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,7 +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 { ActorsModule, ActorClient, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.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,3 +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 { Actor } from "./actor.js";

package/dist/modules/actors.d.ts

@@ -0,0 +1,15 @@
+import type { ActorRoom } from "./actors.types.js";
+interface ActorsConfig {
+    appId: string;
+    /** Current user access token, if authenticated. Rides the WS query so the
+     * platform proxy can authenticate the connection; anonymous connects omit it. */
+    getAuthToken(): string | null | undefined;
+    /** Same semantics as function calls: editors with a non-prod version get the
+     * draft actor script; everyone else gets the published one. */
+    functionsVersion?: string;
+    dispatcherWsUrl: string;
+    /** WebSocket implementation for runtimes without a global one (Node < 22). */
+    webSocketImpl?: unknown;
+}
+export declare function createActorsModule(config: ActorsConfig): Record<string, (instanceId: string) => ActorRoom>;
+export {};

package/dist/modules/actors.js

@@ -0,0 +1,112 @@
+import PartySocket from "partysocket";
+// Heartbeat / half-open detection: PartySocket only reconnects on a close/error
+// event, so ping periodically and force a reconnect if nothing returns in DEAD_MS.
+const PING_MS = 1000;
+const DEAD_MS = 3000;
+class Room {
+    constructor(actorName, instanceId, config) {
+        this.actorName = actorName;
+        this.instanceId = instanceId;
+        this.config = config;
+        this.ws = null;
+        this.listeners = new Set();
+        this.heartbeat = null;
+        this.connId = null;
+    }
+    get id() {
+        if (!this.connId) {
+            throw new Error(`${this.actorName}:${this.instanceId}: connect() before reading id`);
+        }
+        return this.connId;
+    }
+    connect(options) {
+        var _a;
+        if (this.ws)
+            return this;
+        // The client picks its own conn id; it becomes _pk → the actor's conn.id.
+        const connId = (_a = options === null || options === void 0 ? void 0 : options.id) !== null && _a !== void 0 ? _a : crypto.randomUUID();
+        this.connId = connId;
+        const ws = new PartySocket({
+            host: this.config.dispatcherWsUrl,
+            party: this.actorName,
+            room: this.instanceId,
+            id: connId,
+            ...(this.config.webSocketImpl ? { WebSocket: this.config.webSocketImpl } : {}),
+            // Re-read on every (re)connect so a login/logout is picked up.
+            query: () => {
+                const token = this.config.getAuthToken();
+                return {
+                    app_id: this.config.appId,
+                    handler: this.actorName,
+                    ...(token ? { token } : {}),
+                    ...(this.config.functionsVersion ? { fv: this.config.functionsVersion } : {}),
+                };
+            },
+        });
+        this.ws = ws;
+        let lastMsg = Date.now();
+        const bumpAlive = () => { lastMsg = Date.now(); };
+        ws.addEventListener("open", bumpAlive);
+        ws.addEventListener("message", (ev) => {
+            bumpAlive();
+            let data;
+            try {
+                data = JSON.parse(ev.data);
+            }
+            catch (_a) {
+                return; // ignore malformed
+            }
+            const msgType = data && typeof data === "object" ? data.type : undefined;
+            if (msgType === "__pong")
+                return; // platform message — never surface it
+            for (const listener of this.listeners)
+                listener(data);
+        });
+        this.heartbeat = setInterval(() => {
+            if (Date.now() - lastMsg > DEAD_MS) {
+                bumpAlive(); // avoid a reconnect storm while the new socket comes up
+                ws.reconnect();
+                return;
+            }
+            try {
+                ws.send(JSON.stringify({ type: "__ping" }));
+            }
+            catch (_a) {
+                // socket not open; the watchdog above will force a reconnect
+            }
+        }, PING_MS);
+        return this;
+    }
+    subscribe(callback) {
+        if (!this.ws) {
+            throw new Error(`${this.actorName}:${this.instanceId}: connect() before subscribe()`);
+        }
+        this.listeners.add(callback);
+        return {
+            unsubscribe: () => { this.listeners.delete(callback); },
+        };
+    }
+    send(data) {
+        if (!this.ws) {
+            throw new Error(`${this.actorName}:${this.instanceId}: connect() before send()`);
+        }
+        this.ws.send(JSON.stringify(data));
+    }
+    close() {
+        var _a;
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+        this.listeners.clear();
+        (_a = this.ws) === null || _a === void 0 ? void 0 : _a.close();
+        this.ws = null;
+    }
+}
+export function createActorsModule(config) {
+    return new Proxy({}, {
+        get(_, actorName) {
+            return (instanceId) => new Room(actorName, instanceId, config);
+        },
+    });
+}

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

@@ -0,0 +1,89 @@
+/**
+ * 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;
+/** Options for {@link ActorRoom.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.
+     */
+    id?: string;
+}
+/** Handle for one listener registered via {@link ActorRoom.subscribe}. */
+export interface ActorSubscription {
+    /** Remove this listener; other listeners and the socket stay live. */
+    unsubscribe(): void;
+}
+/**
+ * A single actor room. Obtained from {@link ActorClient} (`actors.MyActor(id)`)
+ * and made live with {@link connect}. The handle IS the connection: one socket,
+ * any number of {@link subscribe} listeners.
+ */
+export interface ActorRoom<N extends string = string> {
+    /** The connection id (the value the actor sees as `conn.id`). Throws before {@link connect}. */
+    readonly id: string;
+    /** Open the WebSocket (required before subscribe/send). Idempotent; returns this. */
+    connect(options?: ActorConnectOptions): this;
+    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
+    /** Send a message. Throws before {@link connect}; buffered by the socket until open. */
+    send(data: ToServerFor<N>): void;
+    /** Tear down the socket, heartbeat, and all listeners. */
+    close(): void;
+}
+/**
+ * Client for a single named Actor — call it with a room id to get an
+ * {@link ActorRoom}. Typed automatically when the actor is registered in
+ * {@link ActorRegistry}.
+ */
+export interface ActorClient<N extends string = string> {
+    (instanceId: string): ActorRoom<N>;
+}
+/**
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
+ *
+ * ```typescript
+ * const room = base44.actors.MyActor("room-1").connect();
+ * const sub = room.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * room.send({ type: "message", text: "hi" });
+ * sub.unsubscribe();
+ * room.close();
+ * ```
+ */
+export type ActorsModule = {
+    [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;
+} & Record<string, ActorClient>;
+export {};

package/dist/modules/actors.types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/sso.d.ts

@@ -5,7 +5,6 @@ import { SsoModule } from "./sso.types";
  *
  * @param axios - Axios instance
  * @param appId - Application ID
- * @param userToken - User authentication token
  * @returns SSO module with authentication methods
  * @internal
  */

package/dist/modules/sso.js

@@ -3,7 +3,6 @@
  *
  * @param axios - Axios instance
  * @param appId - Application ID
- * @param userToken - User authentication token
  * @returns SSO module with authentication methods
  * @internal
  */
@@ -14,5 +13,10 @@ export function createSsoModule(axios, appId) {
             const url = `/apps/${appId}/auth/sso/accesstoken/${userid}`;
             return axios.get(url);
         },
+        // Get the stored SSO OIDC ID token for a specific user
+        async getIdToken(userid) {
+            const url = `/apps/${appId}/auth/sso/idtoken/${userid}`;
+            return axios.get(url);
+        },
     };
 }

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

@@ -8,9 +8,9 @@ export interface SsoAccessTokenResponse {
 /**
  * SSO (Single Sign-On) module for managing SSO authentication.
  *
- * This module provides methods for retrieving SSO access tokens for users.
- * These tokens allow you to authenticate Base44 users with external
- * systems or services.
+ * This module provides methods for retrieving SSO tokens for users. These
+ * tokens allow you to authenticate Base44 users with external systems or
+ * services.
  *
  * This module is only available to use with a client in service role authentication mode, which means it can only be used in backend environments.
  *
@@ -41,4 +41,28 @@ export interface SsoModule {
      * ```
      */
     getAccessToken(userid: string): Promise<SsoAccessTokenResponse>;
+    /**
+     * Gets the stored SSO OIDC ID token for the current app user.
+     *
+     * The service-role client must include an on-behalf-of token for the same
+     * user specified by `userid`. This method returns the stored token as-is and
+     * does not refresh it.
+     *
+     * @param userid - The current app user's ID.
+     * @returns Promise resolving to the raw ID-token string.
+     *
+     * @example
+     * ```typescript
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const user = await base44.auth.me();
+     *   const idToken = await base44.asServiceRole.sso.getIdToken(user.id);
+     *
+     *   return Response.json({ idToken });
+     * });
+     * ```
+     */
+    getIdToken(userid: string): Promise<string>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.39-pr.237.783a84a",
+  "version": "0.8.40-pr.212.5212229",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,8 @@
     "create-docs:process": "node scripts/mintlify-post-processing/file-processing/file-processing.js"
   },
   "dependencies": {
-    "axios": "^1.17.0",
+    "axios": "^1.18.1",
+    "partysocket": "^0.0.23",
     "socket.io-client": "^4.8.3",
     "uuid": "^13.0.2"
   },