@base44-preview/sdk 0.8.43-pr.261.f8cbcf8 → 0.8.44-pr.260.59c4ba5

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 { createActorsModule, resolveActorsHost } from "./modules/actors.js";
+import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
  *
@@ -110,6 +110,15 @@ export function createClient(config) {
         token: serviceToken,
         interceptResponses: false,
     });
+    // Dedicated client for actor connection-token mints: no onError (a legacy
+    // actor answers every mint with an expected 409 before the proxy fallback,
+    // which must not reach the app's error handler — the actors module forwards
+    // genuine failures itself via onMintError) and no constructor token
+    // (auth is per-request so a login/logout is picked up on every reconnect).
+    const actorsAxiosClient = createAxiosClient({
+        baseURL: `${serverUrl}/api`,
+        headers,
+    });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
         appBaseUrl: normalizedAppBaseUrl,
         serverUrl,
@@ -127,11 +136,26 @@ export function createClient(config) {
     }
     const actorsModule = createActorsModule({
         appId,
-        // serverUrl is often relative/empty (same-origin app); PartySocket needs an
-        // absolute host, so fall back to the page origin.
+        // serverUrl is often relative/empty (same-origin app); the proxy-fallback
+        // URL needs an absolute host, so fall back to the page origin.
         host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined),
         functionsVersion,
         getAuthToken: () => token || getAccessToken(),
+        mintConnectionToken: async (actorName, room, connectionId) => {
+            const authToken = token || getAccessToken();
+            return await actorsAxiosClient.post(`/apps/${appId}/actors/${encodeURIComponent(actorName)}/connection-token`, { room, connection_id: connectionId }, {
+                headers: {
+                    ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+                    // The mint endpoint resolves draft vs published from this header;
+                    // only the functions axios clients send it by default.
+                    ...(functionsVersion
+                        ? { "Base44-Functions-Version": functionsVersion }
+                        : {}),
+                },
+            });
+        },
+        transport: options === null || options === void 0 ? void 0 : options.actorsTransport,
+        onMintError: options === null || options === void 0 ? void 0 : options.onError,
     });
     const userModules = {
         entities: createEntitiesModule({

package/dist/client.types.d.ts

@@ -15,8 +15,20 @@ import type { ActorsModule } from "./modules/actors.types.js";
 export interface CreateClientOptions {
     /**
      * Optional error handler that will be called whenever an API error occurs.
+     *
+     * Also receives {@link ActorsModule | actors} connection failures. Errors
+     * are usually {@linkcode Base44Error} instances — check `error.status`.
      */
     onError?: (error: Error) => void;
+    /**
+     * Forces the actors transport. `"auto"` (default) connects directly to the
+     * actor and falls back to the platform proxy when the app's actors don't
+     * support direct connections; `"proxy"` always uses the platform proxy
+     * (ops rollback — no connection-token calls); `"direct"` disables the
+     * fallback (validation environments).
+     * @internal
+     */
+    actorsTransport?: "auto" | "proxy" | "direct";
 }
 /**
  * Configuration for creating a Base44 client.

package/dist/modules/actors.d.ts

@@ -1,21 +1,47 @@
 import type { ActorRef } from "./actors.types.js";
+/** Credentials minted by the platform for one direct actor connection. */
+export interface ActorConnectionCredentials {
+    /** Direct actor endpoint, already carrying `?_pk=<connectionId>`. */
+    websocket_url: string;
+    /** Short-lived JWT bound to (app, actor, room, connectionId); appended to
+     * the URL as `token=` since browsers can't set WebSocket headers. */
+    token: string;
+}
 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. */
+    /** Current user access token, if authenticated. Rides the WS query on the
+     * proxy-fallback path 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;
-    /** Absolute host PartySocket dials (it strips the scheme and connects wss, ws
+    /** Absolute host for the proxy-fallback URL (scheme is swapped to wss, ws
      * for localhost). Resolved by {@link resolveActorsHost}. */
     host: string;
+    /** Mints a direct-connect credential for one (actor, room, connection).
+     * Called per connection attempt: the token's expiry is checked at upgrade,
+     * so every reconnect needs a fresh one. */
+    mintConnectionToken(actorName: string, room: string, connectionId: string): Promise<ActorConnectionCredentials>;
+    /** @internal Ops escape hatch: "proxy" never mints (legacy path only),
+     * "direct" never falls back. Default "auto". */
+    transport?: "auto" | "proxy" | "direct";
+    /** Called when a mint fails for a reason other than the expected
+     * direct→proxy fallback (which recovers by itself). Wired to the client's
+     * `options.onError`. */
+    onMintError?: (error: Error) => void;
 }
 /**
- * Absolute host for the actor WebSocket. PartySocket needs an absolute host and
- * can't resolve a relative/empty `serverUrl` (same-origin apps use a relative
- * `/api`, so `serverUrl` is often `""`), so fall back to the page origin.
- * PartySocket handles the scheme (https→wss, ws for localhost).
+ * The legacy platform-proxy URL, byte-for-byte what PartySocket built before
+ * the direct path existed: same scheme swap (including its localhost-needs-a-
+ * port quirk), case-preserved party segment, `_pk` first in the query. The
+ * `handler` param is load-bearing — the proxy reads it for the actor name.
+ */
+export declare function buildProxyActorUrl(rawHost: string, actorName: string, instanceId: string, connectionId: string, appId: string, token: string | null | undefined, functionsVersion?: string): string;
+/**
+ * Absolute host for the proxy-fallback actor URL. A relative/empty `serverUrl`
+ * can't be dialed (same-origin apps use a relative `/api`, so `serverUrl` is
+ * often `""`), so fall back to the page origin.
  */
 export declare function resolveActorsHost(serverUrl: string, browserOrigin?: string): string;
 export declare function createActorsModule(config: ActorsConfig): {

package/dist/modules/actors.js

@@ -1,8 +1,32 @@
-import PartySocket from "partysocket";
-// Heartbeat / half-open detection: PartySocket only reconnects on a close/error
+import { WebSocket as ReconnectingWebSocket } from "partysocket";
+// Heartbeat / half-open detection: the socket 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;
+// Mint responses that mean "direct can't serve this connection, the proxy can":
+// 409 = legacy-family actor script, 503 = direct connections not provisioned,
+// 422 = no principal (e.g. anonymous outside a browser) or an id/room only the
+// proxy's looser validation accepts, 405 = a backend that predates the mint
+// endpoint (its actor deploy routes catch the path via `{handler_name:path}`
+// but not the POST method — and the real endpoint never 405s a POST). The
+// proxy serves migrated actors too, so falling back is always safe.
+const PROXY_FALLBACK_STATUSES = new Set([405, 409, 422, 503]);
+// Mint responses no retry can fix (bad request / forbidden / not found): the
+// connection closes instead of re-minting forever; a fresh connect() re-probes.
+// 401 is deliberately absent — the auth token is re-read on every attempt, so a
+// login recovers on the next retry. Disjoint from PROXY_FALLBACK_STATUSES.
+const TERMINAL_MINT_STATUSES = new Set([400, 403, 404]);
+/** The mint's rejection can be anything; a `Base44Error` carries a numeric
+ * `.status` (absent for network failures). */
+function mintErrorStatus(err) {
+    const status = err && typeof err === "object"
+        ? err.status
+        : undefined;
+    return typeof status === "number" ? status : undefined;
+}
+function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
 /**
  * A live connection to an actor instance. Only obtainable from
  * {@link ActorRef.connect}, so `subscribe`/`send` are always valid — the socket
@@ -14,23 +38,54 @@ class Connection {
         this.onClose = onClose;
         this.listeners = new Set();
         this.heartbeat = null;
+        this.closed = false;
         this.id = (_a = options === null || options === void 0 ? void 0 : options.id) !== null && _a !== void 0 ? _a : crypto.randomUUID();
-        const ws = new PartySocket({
-            host: config.host,
-            party: actorName,
-            room: instanceId,
-            id: this.id,
-            // Re-read on every (re)connect so a login/logout is picked up.
-            query: () => {
-                const token = config.getAuthToken();
-                return {
-                    app_id: config.appId,
-                    handler: actorName,
-                    ...(token ? { token } : {}),
-                    ...(config.functionsVersion ? { fv: config.functionsVersion } : {}),
-                };
-            },
-        });
+        // Direct-first with proxy fallback, decided per connection attempt. Once a
+        // mint answers with a fallback status the choice is sticky for this
+        // socket's lifetime (a fresh connect() after close() probes direct again,
+        // picking up actors migrated in the meantime). Any other mint failure
+        // rejects, which ReconnectingWebSocket retries with backoff — except the
+        // terminal statuses, which close this connection for good.
+        let useProxy = config.transport === "proxy";
+        const urlProvider = async () => {
+            var _a;
+            if (this.closed)
+                throw new Error("Actor connection is closed");
+            if (!useProxy) {
+                try {
+                    const { websocket_url, token } = await config.mintConnectionToken(actorName, instanceId, this.id);
+                    const sep = websocket_url.includes("?") ? "&" : "?";
+                    return `${websocket_url}${sep}token=${encodeURIComponent(token)}`;
+                }
+                catch (err) {
+                    const status = mintErrorStatus(err);
+                    const isFallback = config.transport !== "direct" &&
+                        status !== undefined &&
+                        PROXY_FALLBACK_STATUSES.has(status);
+                    if (!isFallback) {
+                        if (status !== undefined && TERMINAL_MINT_STATUSES.has(status)) {
+                            // close() before notifying: ws.close() stops the redial the
+                            // rethrow below would otherwise schedule, and a handler that
+                            // immediately calls connect() gets a clean new connection.
+                            this.close();
+                        }
+                        // Reported from here because the socket's error event only
+                        // preserves `err.message`, never `.status`.
+                        try {
+                            (_a = config.onMintError) === null || _a === void 0 ? void 0 : _a.call(config, toError(err));
+                        }
+                        catch (_b) {
+                            // an app handler must not break the dial loop or mask `err`
+                        }
+                        throw err;
+                    }
+                    useProxy = true;
+                }
+            }
+            // Rebuilt per attempt so a login/logout is picked up on reconnect.
+            return buildProxyActorUrl(config.host, actorName, instanceId, this.id, config.appId, config.getAuthToken(), config.functionsVersion);
+        };
+        const ws = new ReconnectingWebSocket(urlProvider);
         this.ws = ws;
         let lastMsg = Date.now();
         const bumpAlive = () => { lastMsg = Date.now(); };
@@ -53,7 +108,11 @@ class Connection {
         this.heartbeat = setInterval(() => {
             if (Date.now() - lastMsg > DEAD_MS) {
                 bumpAlive(); // avoid a reconnect storm while the new socket comes up
-                ws.reconnect();
+                // Only kick a half-open socket (OPEN but silent). When it isn't open
+                // the socket is already redialing with backoff, and reconnect() would
+                // reset that backoff into a mint call every DEAD_MS.
+                if (ws.readyState === ws.OPEN)
+                    ws.reconnect();
                 return;
             }
             try {
@@ -73,9 +132,15 @@ class Connection {
         };
     }
     send(data) {
+        // after close() the socket would buffer forever (unbounded enqueue)
+        if (this.closed)
+            return;
         this.ws.send(JSON.stringify(data));
     }
     close() {
+        if (this.closed)
+            return;
+        this.closed = true;
         if (this.heartbeat) {
             clearInterval(this.heartbeat);
             this.heartbeat = null;
@@ -104,10 +169,38 @@ function makeActorRef(actorName, instanceId, config, connections) {
     };
 }
 /**
- * Absolute host for the actor WebSocket. PartySocket needs an absolute host and
- * can't resolve a relative/empty `serverUrl` (same-origin apps use a relative
- * `/api`, so `serverUrl` is often `""`), so fall back to the page origin.
- * PartySocket handles the scheme (https→wss, ws for localhost).
+ * The legacy platform-proxy URL, byte-for-byte what PartySocket built before
+ * the direct path existed: same scheme swap (including its localhost-needs-a-
+ * port quirk), case-preserved party segment, `_pk` first in the query. The
+ * `handler` param is load-bearing — the proxy reads it for the actor name.
+ */
+export function buildProxyActorUrl(rawHost, actorName, instanceId, connectionId, appId, token, functionsVersion) {
+    let host = rawHost.replace(/^(http|https|ws|wss):\/\//, "");
+    if (host.endsWith("/"))
+        host = host.slice(0, -1);
+    const insecure = host.startsWith("localhost:") ||
+        host.startsWith("127.0.0.1:") ||
+        host.startsWith("192.168.") ||
+        host.startsWith("10.") ||
+        (host.startsWith("172.") &&
+            host.split(".")[1] >= "16" &&
+            host.split(".")[1] <= "31") ||
+        host.startsWith("[::ffff:7f00:1]:");
+    const query = new URLSearchParams([
+        ["_pk", connectionId],
+        ["app_id", appId],
+        ["handler", actorName],
+    ]);
+    if (token)
+        query.append("token", token);
+    if (functionsVersion)
+        query.append("fv", functionsVersion);
+    return `${insecure ? "ws" : "wss"}://${host}/parties/${actorName}/${instanceId}?${query}`;
+}
+/**
+ * Absolute host for the proxy-fallback actor URL. A relative/empty `serverUrl`
+ * can't be dialed (same-origin apps use a relative `/api`, so `serverUrl` is
+ * often `""`), so fall back to the page origin.
  */
 export function resolveActorsHost(serverUrl, browserOrigin) {
     return serverUrl && !serverUrl.startsWith("/") ? serverUrl : browserOrigin !== null && browserOrigin !== void 0 ? browserOrigin : serverUrl;

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

@@ -56,9 +56,14 @@ export interface Connection<N extends string = string> {
     readonly id: string;
     /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered by the socket until it's open. */
+    /** Send a message. Buffered by the socket until it's open; dropped after
+     * {@link close}. */
     send(data: ToServerFor<N>): void;
-    /** Tear down the socket, heartbeat, and all listeners. */
+    /**
+     * 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;
 }
 /**
@@ -66,7 +71,15 @@ export interface Connection<N extends string = string> {
  * {@link connect} to open the socket and get a {@link Connection}.
  */
 export interface ActorRef<N extends string = string> {
-    /** Open the WebSocket and return the {@link Connection}. Idempotent. */
+    /**
+     * Open the WebSocket and return the {@link Connection}. Idempotent while the
+     * connection is open.
+     *
+     * 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>;
 }
 /**

package/dist/modules/analytics.js

@@ -25,6 +25,9 @@ const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () =
     wasInitializationTracked: false,
     sessionContext: null,
     sessionStartTime: null,
+    // Memoized session id for when `localStorage` can't persist one — see
+    // getAnalyticsSessionId.
+    fallbackSessionId: null,
     config: {
         ...defaultConfiguration,
         ...getAnalyticsConfigFromUrlParams(),
@@ -216,9 +219,11 @@ function trackSessionDurationEvent(track) {
     });
 }
 function getEventIntrinsicData() {
+    var _a, _b;
     return {
         timestamp: new Date().toISOString(),
-        pageUrl: typeof window !== "undefined" ? window.location.pathname : null,
+        // `window.location` is absent on React Native, so read it optionally.
+        pageUrl: typeof window !== "undefined" ? (_b = (_a = window.location) === null || _a === void 0 ? void 0 : _a.pathname) !== null && _b !== void 0 ? _b : null : null,
     };
 }
 function transformEventDataToApiRequestData(sessionContext) {
@@ -302,9 +307,15 @@ export function getAnalyticsConfigFromUrlParams() {
     // return the config object //
     return { enabled: analyticsEnable === "true" };
 }
+// When the id can't be persisted (React Native has no `localStorage`), keep
+// it stable for the process instead of minting a fresh one per call.
+function getFallbackSessionId() {
+    var _a;
+    return ((_a = analyticsSharedState.fallbackSessionId) !== null && _a !== void 0 ? _a : (analyticsSharedState.fallbackSessionId = generateUuid()));
+}
 export function getAnalyticsSessionId() {
     if (typeof window === "undefined") {
-        return generateUuid();
+        return getFallbackSessionId();
     }
     try {
         const sessionId = localStorage.getItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY);
@@ -316,6 +327,6 @@ export function getAnalyticsSessionId() {
         return sessionId;
     }
     catch (_a) {
-        return generateUuid();
+        return getFallbackSessionId();
     }
 }

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

@@ -134,12 +134,15 @@ export interface AuthModule {
     /**
      * Updates the current authenticated user's information.
      *
-     * You can update `role` and any [custom fields](/developers/backend/resources/entities/user-schema#custom-fields) defined in your
-     * User entity schema.
-     * The `role` value must be either `'user'` or `'admin'`.
+     * You can update any [custom fields](/developers/backend/resources/entities/user-schema#custom-fields)
+     * defined in your User entity schema.
+     *
+     * Updating `role` requires editor access on the app.
+     *
      * <Note>
-     * The following fields are read-only and can't be changed with this method:
-     * `id`, `email`, `full_name`, `created_date`, `updated_date`, and `created_by`.
+     * These fields can't be changed with this method:
+     * `id`, `email`, `full_name`, `created_date`, `updated_date`, `created_by`,
+     * and `collaborator_role`.
      * </Note>
      *
      * @param data - Object containing the fields to update.
@@ -147,9 +150,8 @@ export interface AuthModule {
      *
      * @example
      * ```typescript
-     * // Update role and custom fields defined in your User entity
+     * // Update custom fields defined in your User entity
      * await base44.auth.updateMe({
-     *   role: 'admin',
      *   bio: 'Software developer',
      *   preferences: { theme: 'dark' }
      * });

package/dist/utils/axios-client.js

@@ -132,8 +132,10 @@ export function createAxiosClient({ baseURL, headers = {}, token, interceptRespo
     client.interceptors.request.use((config) => {
         // `window.location` is absent on React Native (where `window` still exists),
         // so guard on it before reading `.href`.
-        if (typeof window !== "undefined" && window.location) {
-            config.headers.set("X-Origin-URL", window.location.href);
+        if (typeof window !== "undefined") {
+            if (window.location) {
+                config.headers.set("X-Origin-URL", window.location.href);
+            }
             // On unauthenticated requests, attach a stable anonymous visitor id so the
             // backend can support anonymous agent access (conversation grouping + ownership).
             // Authenticated requests are identified by their Authorization header instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.43-pr.261.f8cbcf8",
+  "version": "0.8.44-pr.260.59c4ba5",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",