@base44-preview/sdk 0.8.43-pr.257.a72bddf → 0.8.43-pr.259.3f82534

package/dist/actor.d.ts

@@ -9,6 +9,13 @@
  * Cloudflare Durable Object implementation — this file provides types only.
  */
 import type { Base44Client } from "./client";
+export type ActorConnectionIdentity = Readonly<{
+    type: "authenticated";
+    userId: string;
+}> | Readonly<{
+    type: "anonymous";
+    anonymousId: string;
+}>;
 /**
  * A single client connection. `Send` is the message type this connection accepts
  * via {@link send} — the actor's *outgoing* (server→client) messages.
@@ -18,6 +25,8 @@ export interface Conn<Send = unknown> {
      *  receives from `subscribe()`. Identifies a distinct client, so multiple
      *  tabs are separate connections. */
     id: string;
+    /** Identity verified by the Actor Worker. Legacy Actors may not provide it. */
+    identity?: ActorConnectionIdentity;
     send(data: Send): void;
     reject(code: number, reason: string): void;
 }
@@ -86,9 +95,10 @@ export declare abstract class Actor<Incoming = unknown, Outgoing = unknown> {
     protected get storage(): Storage;
     /**
      * Anonymous Base44 client scoped to this actor instance — no user or service
-     * auth, so entity access is RLS-gated (same as a logged-out visitor). Always
-     * operates on production data: an actor runs server-side with no per-connection
-     * identity, so a Test DB preview selected in the editor does not apply here.
+     * auth, so entity access is RLS-gated (same as a logged-out visitor). A
+     * connection's verified `identity` is context only and is never applied to this
+     * client. Always operates on production data, so a Test DB preview selected in
+     * the editor does not apply here.
      * Example: `const rows = await this.client.entities.Score.list();`
      */
     protected get client(): Base44Client;

package/dist/actor.js

@@ -74,9 +74,10 @@ export class Actor {
     }
     /**
      * Anonymous Base44 client scoped to this actor instance — no user or service
-     * auth, so entity access is RLS-gated (same as a logged-out visitor). Always
-     * operates on production data: an actor runs server-side with no per-connection
-     * identity, so a Test DB preview selected in the editor does not apply here.
+     * auth, so entity access is RLS-gated (same as a logged-out visitor). A
+     * connection's verified `identity` is context only and is never applied to this
+     * client. Always operates on production data, so a Test DB preview selected in
+     * the editor does not apply here.
      * Example: `const rows = await this.client.entities.Score.list();`
      */
     get client() {

package/dist/client.js

@@ -94,6 +94,13 @@ export function createClient(config) {
         interceptResponses: false,
         onError: options === null || options === void 0 ? void 0 : options.onError,
     });
+    // Actors keeps raw responses for 409 routing and owns error reporting so
+    // response-validation failures use the same onError path as request failures.
+    const actorConnectionClient = createAxiosClient({
+        baseURL: `${serverUrl}/api`,
+        headers,
+        interceptResponses: false,
+    });
     const serviceRoleHeaders = {
         ...headers,
         ...(token ? { "on-behalf-of": `Bearer ${token}` } : {}),
@@ -127,11 +134,13 @@ 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.
+        connectionClient: actorConnectionClient,
+        onError: options === null || options === void 0 ? void 0 : options.onError,
+        // serverUrl is often relative/empty in same-origin apps, while the legacy
+        // WebSocket fallback needs an absolute host.
         host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined),
         functionsVersion,
-        getAuthToken: () => token || getAccessToken(),
+        getAuthToken: () => userAuthModule.getToken(),
     });
     const userModules = {
         entities: createEntitiesModule({

package/dist/client.types.d.ts

@@ -15,6 +15,8 @@ import type { ActorsModule } from "./modules/actors.types.js";
 export interface CreateClientOptions {
     /**
      * Optional error handler that will be called whenever an API error occurs.
+     * Actor connection failures are contextual `ActorConnectionError` instances.
+     * Retryable Actor failures may be reported more than once.
      */
     onError?: (error: Error) => void;
 }

package/dist/index.d.ts

@@ -12,8 +12,9 @@ export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, Age
 export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
+export { ActorConnectionError } from "./modules/actors.error.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
-export { Actor, type Conn } from "./actor.js";
+export { Actor, type ActorConnectionIdentity, 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,5 @@ 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 { ActorConnectionError } from "./modules/actors.error.js";
 export { Actor } from "./actor.js";

package/dist/modules/actors.d.ts

@@ -1,21 +1,22 @@
+import { type AxiosInstance } from "axios";
+import { ActorConnectionError } from "./actors.error.js";
 import type { ActorRef } 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. */
+    connectionClient: AxiosInstance;
+    onError?: (error: ActorConnectionError) => void;
+    /** Current user access token, if authenticated. */
     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
-     * for localhost). Resolved by {@link resolveActorsHost}. */
+    /** Absolute host used when a legacy Actor falls back to the Apper proxy. */
     host: string;
 }
 /**
- * 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).
+ * Absolute host for the legacy Actor WebSocket. A relative/empty `serverUrl`
+ * cannot identify the Apper proxy, so same-origin apps 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.error.d.ts

@@ -0,0 +1,14 @@
+/** Contextual error for an Actor bootstrap, WebSocket, or closed-connection failure. */
+export declare class ActorConnectionError extends Error {
+    readonly actorName: string;
+    readonly instanceId: string;
+    readonly connectionId: string;
+    readonly cause: unknown;
+    /** HTTP response status, when the failure came from the bootstrap request. */
+    readonly status?: number;
+    /** WebSocket close code, when the far end closed the connection. */
+    readonly closeCode?: number;
+    /** WebSocket close reason, when the far end supplied one. */
+    readonly closeReason?: string;
+    constructor(actorName: string, instanceId: string, connectionId: string, cause: unknown, status?: number, closeCode?: number, closeReason?: string);
+}

package/dist/modules/actors.error.js

@@ -0,0 +1,15 @@
+/** Contextual error for an Actor bootstrap, WebSocket, or closed-connection failure. */
+export class ActorConnectionError extends Error {
+    constructor(actorName, instanceId, connectionId, cause, status, closeCode, closeReason) {
+        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        super(`Actor "${actorName}" instance "${instanceId}" connection "${connectionId}": ${causeMessage}`);
+        this.actorName = actorName;
+        this.instanceId = instanceId;
+        this.connectionId = connectionId;
+        this.cause = cause;
+        this.name = "ActorConnectionError";
+        this.status = status;
+        this.closeCode = closeCode;
+        this.closeReason = closeReason;
+    }
+}

package/dist/modules/actors.js

@@ -1,42 +1,150 @@
-import PartySocket from "partysocket";
+import { isAxiosError } from "axios";
+import PartySocket, { WebSocket as ReconnectingWebSocket } from "partysocket";
+import { getAnalyticsSessionId } from "./analytics.js";
+import { generateUuid } from "../utils/common.js";
+import { ActorConnectionError } from "./actors.error.js";
+// Both mirror the Actor Worker dispatcher's own validation (see
+// workers/base44-dispatcher/src/actor-routing.ts) so a request it would reject
+// fails here instead. Rejection happens on the WebSocket *upgrade*, which
+// reaches the browser as an opaque 1006 with no status to act on, so failing
+// fast client-side is the only way to report the real reason.
+const CONNECTION_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const INSTANCE_ID_RE = /^[\x20-\x2e\x30-\x7e]{1,256}$/;
+const RETRYABLE_BOOTSTRAP_STATUSES = new Set([401, 408, 425, 429]);
 // 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;
+// While heartbeat reconnects keep coming back silent, the dead window doubles up
+// to this cap. Every heartbeat re-dial buys a connection-token POST against a
+// per-app rate limit, so a link that reopens but never delivers a frame must not
+// hold the DEAD_MS cadence forever. Any inbound frame resets the window.
+const MAX_DEAD_MS = 60000;
+// PartySocket retries forever (`maxRetries: Infinity`) and every attempt costs a
+// connection-token POST, so a connection that can never be admitted needs a
+// bound. Close codes cannot provide one: the dispatcher refuses the upgrade over
+// HTTP (opaque 1006 on the client), and 1000 arrives both from
+// `conn.reject(1000, ...)` and from a graceful worker shutdown. Counting
+// attempts measures "retrying is not working" directly instead.
+//
+// ~25-40s under PartySocket's 1-5s base delay x1.3 growth (10s cap): long enough
+// to ride out a deploy, short enough to stop a rejection loop quickly.
+const MAX_CONSECUTIVE_FAILURES = 6;
+// A socket that holds this long proves retrying works, so the budget resets.
+// Matches PartySocket's own `minUptime`.
+const STABLE_MS = 5000;
 /**
- * A live connection to an actor instance. Only obtainable from
- * {@link ActorRef.connect}, so `subscribe`/`send` are always valid — the socket
- * exists for this object's whole lifetime.
+ * A connection to an actor instance. Only obtainable from {@link ActorRef.connect}.
  */
 class Connection {
-    constructor(actorName, instanceId, config, options, onClose) {
-        var _a;
+    constructor(actorName, instanceId, config, options, getAnonymousId, onClose) {
+        this.actorName = actorName;
+        this.instanceId = instanceId;
         this.onClose = onClose;
         this.listeners = new Set();
+        this.errorListeners = new Set();
         this.heartbeat = null;
-        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 } : {}),
-                };
-            },
-        });
+        this.isClosed = false;
+        this.closedError = null;
+        /** Attempts since the last socket that stayed up for {@link STABLE_MS}. */
+        this.consecutiveFailures = 0;
+        this.stabilityTimer = null;
+        this.id = resolveConnectionId(options === null || options === void 0 ? void 0 : options.id);
+        this.globalOnError = config.onError;
+        this.addErrorListener(options === null || options === void 0 ? void 0 : options.onError);
+        let bootstrapErrorAwaitingSocketEvent = false;
+        const ws = new ReconnectingWebSocket(async () => {
+            var _a;
+            if (this.closedError)
+                throw this.closedError;
+            bootstrapErrorAwaitingSocketEvent = false;
+            try {
+                return await resolveActorWebSocketUrl(actorName, instanceId, this.id, getAnonymousId, config);
+            }
+            catch (error) {
+                const status = isAxiosError(error) ? (_a = error.response) === null || _a === void 0 ? void 0 : _a.status : undefined;
+                const connectionError = this.createError(error, status);
+                bootstrapErrorAwaitingSocketEvent = true;
+                if (isTerminalBootstrapError(error)) {
+                    this.reportError(connectionError, true);
+                }
+                else if (status === undefined) {
+                    // The request never reached the server (offline, DNS, aborted), so
+                    // it consumes nothing and will succeed once connectivity returns.
+                    // Charging the budget here would kill the connection over a tunnel.
+                    this.reportError(connectionError);
+                }
+                else {
+                    this.reportAttemptFailure(connectionError);
+                }
+                throw connectionError;
+            }
+        }, undefined, { startClosed: true });
         this.ws = ws;
-        let lastMsg = Date.now();
-        const bumpAlive = () => { lastMsg = Date.now(); };
-        ws.addEventListener("open", bumpAlive);
+        let lastActivityAt = null;
+        let socketOpened = false;
+        let reconnectingForHeartbeat = false;
+        /** Watchdog trips with no inbound frame since: gates the one-per-outage
+         *  silence report and widens the dead window. Reset by any message. */
+        let silentReconnects = 0;
+        let closeSequence = 0;
+        let suppressedCloseSequence = 0;
+        const markAlive = () => { lastActivityAt = Date.now(); };
+        const markDisconnected = () => { lastActivityAt = null; };
+        ws.addEventListener("open", () => {
+            socketOpened = true;
+            markAlive();
+            this.armStability();
+        });
+        ws.addEventListener("close", (event) => {
+            const closedSocketWasOpen = socketOpened;
+            socketOpened = false;
+            markDisconnected();
+            this.clearStability();
+            const currentCloseSequence = ++closeSequence;
+            // A heartbeat-driven reconnect is not a failed attempt: a legacy Actor
+            // without the __pong shim reconnects every DEAD_MS by design, so charging
+            // the budget for those would tear down every legacy connection.
+            if (this.isClosed || reconnectingForHeartbeat || !closedSocketWasOpen)
+                return;
+            // PartySocket emits a synthetic close before its error event. Defer so
+            // that transport errors are reported once with their real cause.
+            queueMicrotask(() => {
+                if (this.isClosed || suppressedCloseSequence === currentCloseSequence)
+                    return;
+                const reason = event.reason
+                    ? `WebSocket closed with code ${event.code}: ${event.reason}`
+                    : `WebSocket closed with code ${event.code}`;
+                const connectionError = this.createError(new Error(reason), undefined, event.code, event.reason || undefined);
+                if (isTerminalSocketCloseCode(event.code)) {
+                    this.reportError(connectionError, true);
+                }
+                else {
+                    this.reportAttemptFailure(connectionError);
+                }
+            });
+        });
+        ws.addEventListener("error", (event) => {
+            markDisconnected();
+            suppressedCloseSequence = closeSequence;
+            if (this.isClosed)
+                return;
+            if (bootstrapErrorAwaitingSocketEvent) {
+                bootstrapErrorAwaitingSocketEvent = false;
+                return;
+            }
+            const cause = event.error instanceof Error
+                ? event.error
+                : new Error(event.message || "Actor WebSocket error");
+            // Also the only signal for a refused *upgrade* (bad token, unknown or
+            // throwing Actor): the dispatcher answers over HTTP, the socket never
+            // opens, and the close listener above skips it — so the budget applied
+            // here is what stops a permanently unroutable connection.
+            this.reportAttemptFailure(this.createError(cause));
+        });
         ws.addEventListener("message", (ev) => {
-            bumpAlive();
+            markAlive();
+            silentReconnects = 0;
             let data;
             try {
                 data = JSON.parse(ev.data);
@@ -51,48 +159,176 @@ class Connection {
                 listener(data);
         });
         this.heartbeat = setInterval(() => {
-            if (Date.now() - lastMsg > DEAD_MS) {
-                bumpAlive(); // avoid a reconnect storm while the new socket comes up
-                ws.reconnect();
+            if (lastActivityAt === null || ws.readyState !== ws.OPEN)
+                return;
+            const deadMs = Math.min(DEAD_MS * 2 ** silentReconnects, MAX_DEAD_MS);
+            if (Date.now() - lastActivityAt > deadMs) {
+                lastActivityAt = null;
+                // One report per silent stretch: reopen → silence → re-dial cycles are
+                // one outage to the app, not a new failure every window.
+                if (silentReconnects === 0) {
+                    this.reportError(this.createError(new Error("Actor WebSocket stopped responding")));
+                }
+                silentReconnects += 1;
+                reconnectingForHeartbeat = true;
+                try {
+                    ws.reconnect(1000, "heartbeat timeout");
+                }
+                finally {
+                    reconnectingForHeartbeat = false;
+                }
                 return;
             }
             try {
                 // The deployed shim echoes __ping → __pong (base44-userapp-bundler
-                // shim/actor.ts); without that, an idle room reconnects every DEAD_MS.
+                // shim/actor.ts); without that, an idle room reconnects on a widening
+                // interval (DEAD_MS up to MAX_DEAD_MS).
                 ws.send(JSON.stringify({ type: "__ping" }));
             }
             catch (_a) {
-                // not open; the watchdog above will reconnect
+                // The next watchdog tick will reconnect if the link stays half-open.
             }
         }, PING_MS);
+        ws.reconnect();
     }
     subscribe(callback) {
+        this.assertNotClosed();
         this.listeners.add(callback);
         return {
             unsubscribe: () => { this.listeners.delete(callback); },
         };
     }
     send(data) {
+        this.assertNotClosed();
         this.ws.send(JSON.stringify(data));
     }
+    get closed() {
+        return this.isClosed;
+    }
+    addErrorListener(listener) {
+        if (!listener)
+            return { unsubscribe: () => { } };
+        this.assertNotClosed();
+        this.errorListeners.add(listener);
+        return {
+            unsubscribe: () => { this.errorListeners.delete(listener); },
+        };
+    }
     close() {
+        this.teardown(this.createError(new Error("Connection is closed")));
+    }
+    assertNotClosed() {
+        if (!this.closedError)
+            return;
+        throw this.createError(this.closedError.cause, this.closedError.status, this.closedError.closeCode, this.closedError.closeReason);
+    }
+    createError(cause, status, closeCode, closeReason) {
+        return new ActorConnectionError(this.actorName, this.instanceId, this.id, cause, status, closeCode, closeReason);
+    }
+    reportError(error, terminal = false) {
+        const handlers = new Set(this.errorListeners);
+        if (this.globalOnError)
+            handlers.add(this.globalOnError);
+        if (terminal)
+            this.teardown(error);
+        for (const handler of handlers) {
+            try {
+                handler(error);
+            }
+            catch (_a) {
+                // Error observers must not replace the failure PartySocket receives.
+            }
+        }
+    }
+    /**
+     * Report a failed connection attempt, and give up once the budget is spent.
+     * This is the only bound on retries for failures a close code cannot classify
+     * — see {@link MAX_CONSECUTIVE_FAILURES}.
+     */
+    reportAttemptFailure(error) {
+        this.clearStability();
+        const exhausted = ++this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+        this.reportError(error, exhausted);
+    }
+    armStability() {
+        this.clearStability();
+        this.stabilityTimer = setTimeout(() => {
+            this.stabilityTimer = null;
+            this.consecutiveFailures = 0;
+        }, STABLE_MS);
+    }
+    clearStability() {
+        if (this.stabilityTimer) {
+            clearTimeout(this.stabilityTimer);
+            this.stabilityTimer = null;
+        }
+    }
+    teardown(error) {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.closedError = error;
         if (this.heartbeat) {
             clearInterval(this.heartbeat);
             this.heartbeat = null;
         }
         this.listeners.clear();
+        this.errorListeners.clear();
+        this.clearStability();
         this.ws.close();
         this.onClose();
     }
 }
+/**
+ * Whether a close code proves a retry can never succeed.
+ *
+ * Only 1000 and 3000-4999 can reach us as a deliberate server-side choice — the
+ * WebSocket API rejects every other code passed to `close()`, so the rest are
+ * generated by the transport (1006 on a dropped link or a refused upgrade, 1001
+ * on shutdown, 1011 on a server error) and are all worth retrying.
+ *
+ * Of those two, only 3000-4999 carries app intent: `conn.reject(code, reason)`
+ * picks it, and the Actor's decision will not differ on the next attempt. 1000
+ * is ambiguous — `reject(1000, ...)` and a graceful worker shutdown are
+ * indistinguishable on the wire — so it is left to the attempt budget, which
+ * reconnects through a deploy but still gives up on a rejection loop.
+ */
+function isTerminalSocketCloseCode(code) {
+    return code >= 3000 && code <= 4999;
+}
+function isTerminalBootstrapError(error) {
+    var _a;
+    if (!isAxiosError(error))
+        return true;
+    const status = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status;
+    return status !== undefined
+        && status >= 400
+        && status < 500
+        && !RETRYABLE_BOOTSTRAP_STATUSES.has(status);
+}
 /** Handle for one actor instance: `connect()` opens the socket (idempotent). */
-function makeActorRef(actorName, instanceId, config, connections) {
+function makeActorRef(actorName, instanceId, config, getAnonymousId, connections) {
+    assertValidInstanceId(instanceId);
     let conn = null;
     return {
         connect(options) {
-            if (conn)
+            // Before the conflict check below, so a malformed id reports as malformed
+            // rather than as a mismatch against the live connection's (always valid) id.
+            if ((options === null || options === void 0 ? void 0 : options.id) !== undefined)
+                assertValidConnectionId(options.id);
+            if (conn) {
+                if ((options === null || options === void 0 ? void 0 : options.id) !== undefined && options.id !== conn.id) {
+                    throw new Error(`Actor connection is already open with id "${conn.id}"; cannot reuse it with id "${options.id}"`);
+                }
+                if (options === null || options === void 0 ? void 0 : options.onError) {
+                    // Registering here would be unremovable: the subscription that
+                    // addErrorListener returns has nowhere to go, so a handler recreated
+                    // per render would accumulate for the connection's whole life.
+                    throw new Error("Actor connection is already open; use connection.addErrorListener() to add an error handler");
+                }
                 return conn;
-            const c = new Connection(actorName, instanceId, config, options, () => {
+            }
+            const c = new Connection(actorName, instanceId, config, options, getAnonymousId, () => {
                 connections.delete(c);
                 if (conn === c)
                     conn = null; // allow a fresh connect() after close
@@ -104,25 +340,91 @@ 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).
+ * Absolute host for the legacy Actor WebSocket. A relative/empty `serverUrl`
+ * cannot identify the Apper proxy, so same-origin apps fall back to the page
+ * origin.
  */
 export function resolveActorsHost(serverUrl, browserOrigin) {
     return serverUrl && !serverUrl.startsWith("/") ? serverUrl : browserOrigin !== null && browserOrigin !== void 0 ? browserOrigin : serverUrl;
 }
+function assertValidConnectionId(id) {
+    if (!CONNECTION_ID_RE.test(id)) {
+        throw new Error("Actor connection id must be 1-64 letters, numbers, underscores, or hyphens");
+    }
+}
+function assertValidInstanceId(instanceId) {
+    if (!INSTANCE_ID_RE.test(instanceId)) {
+        throw new Error(`Actor instance id "${instanceId}" must be 1-256 printable ASCII characters and cannot contain "/"`);
+    }
+}
+function resolveConnectionId(id) {
+    var _a, _b, _c;
+    if (id !== undefined) {
+        assertValidConnectionId(id);
+        return id;
+    }
+    return (_c = (_b = (_a = globalThis.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : generateUuid();
+}
+function legacyActorWebSocketUrl(actorName, instanceId, connectionId, authToken, config) {
+    const url = new URL(new PartySocket({
+        host: config.host,
+        party: actorName,
+        room: instanceId,
+        id: connectionId,
+        startClosed: true,
+    }).roomUrl);
+    url.searchParams.set("_pk", connectionId);
+    url.searchParams.set("app_id", config.appId);
+    url.searchParams.set("handler", actorName);
+    if (authToken)
+        url.searchParams.set("token", authToken);
+    if (config.functionsVersion)
+        url.searchParams.set("fv", config.functionsVersion);
+    return url.toString();
+}
+async function resolveActorWebSocketUrl(actorName, instanceId, connectionId, getAnonymousId, config) {
+    var _a, _b;
+    const authToken = config.getAuthToken();
+    const anonymousId = authToken ? null : getAnonymousId();
+    const response = await config.connectionClient.post(`/apps/${encodeURIComponent(config.appId)}/actors/${encodeURIComponent(actorName)}/connection-token`, { room: instanceId, connection_id: connectionId }, {
+        headers: {
+            Authorization: authToken ? `Bearer ${authToken}` : null,
+            "X-Base44-Anonymous-Id": anonymousId,
+            ...(config.functionsVersion
+                ? { "Base44-Functions-Version": config.functionsVersion }
+                : {}),
+        },
+        validateStatus: (status) => (status >= 200 && status < 300) || status === 409,
+    });
+    if (response.status === 409) {
+        return legacyActorWebSocketUrl(actorName, instanceId, connectionId, authToken, config);
+    }
+    const websocketUrl = (_a = response.data) === null || _a === void 0 ? void 0 : _a.websocket_url;
+    const token = (_b = response.data) === null || _b === void 0 ? void 0 : _b.token;
+    if (typeof websocketUrl !== "string" || !websocketUrl || typeof token !== "string" || !token) {
+        throw new Error("Invalid Actor connection response");
+    }
+    const url = new URL(websocketUrl);
+    if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+        throw new Error("Invalid Actor WebSocket URL");
+    }
+    url.searchParams.set("_pk", connectionId);
+    url.searchParams.set("token", token);
+    return url.toString();
+}
 export function createActorsModule(config) {
     // Live connections this client opened, so client.cleanup() can reclaim any the
     // app forgot to close() (each connection removes itself here on close).
     const connections = new Set();
+    let anonymousId;
+    const getAnonymousId = () => anonymousId !== null && anonymousId !== void 0 ? anonymousId : (anonymousId = getAnalyticsSessionId());
     const module = new Proxy({}, {
         get(_, key) {
             // Symbols and `then` resolve to undefined (so the module isn't mistaken
             // for a thenable when awaited); any string key is an actor name.
             if (typeof key !== "string" || key === "then")
                 return undefined;
-            return (instanceId) => makeActorRef(key, instanceId, config, connections);
+            return (instanceId) => makeActorRef(key, instanceId, config, getAnonymousId, connections);
         },
     });
     return {

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

@@ -1,3 +1,4 @@
+import type { ActorConnectionError } from "./actors.error.js";
 /**
  * Extend this interface to add typed `subscribe` callbacks and `send` payloads
  * for your deployed Actors.
@@ -36,27 +37,42 @@ type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegist
 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.
+     * (e.g. persisted per tab) containing 1–64 letters, numbers, underscores, or
+     * hyphens so a reconnect reuses the same server-side identity; omit for an
+     * auto-generated per-connection id.
      */
     id?: string;
+    /**
+     * Called when this connection's bootstrap or WebSocket fails. Retryable
+     * failures may be reported more than once — the connection keeps retrying
+     * until it either succeeds or exhausts its attempt budget, and the final
+     * report before it gives up is the one where {@link Connection.closed}
+     * becomes `true`.
+     *
+     * Accepted only on the call that creates the connection: a later
+     * `connect({ onError })` throws, because a handler registered then could
+     * never be removed. Use {@link Connection.addErrorListener} for that.
+     */
+    onError?: (error: ActorConnectionError) => void;
 }
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/** Handle for one connection listener. */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the socket stay live. */
+    /** Remove this listener; other listeners and the connection stay live. */
     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.
+ * A connection to an actor instance, returned by {@link ActorRef.connect}.
  */
 export interface Connection<N extends string = string> {
     /** The connection id (the value the actor sees as `conn.id`). */
     readonly id: string;
-    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    /** Whether this connection has been explicitly or terminally closed. */
+    readonly closed: boolean;
+    /** Register a detachable connection-error listener. Throws if the connection has closed. */
+    addErrorListener(listener?: (error: ActorConnectionError) => void): ActorSubscription;
+    /** Register a message listener. Throws if the connection has closed. */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered by the socket until it's open. */
+    /** Send a message. Buffered until open; throws instead of buffering after close. */
     send(data: ToServerFor<N>): void;
     /** Tear down the socket, heartbeat, and all listeners. */
     close(): void;
@@ -66,7 +82,11 @@ 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}. Repeated calls reuse
+     * the live connection; a conflicting explicit id, or an `onError` handler the
+     * reused connection could not later detach, throws.
+     */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**

package/dist/modules/auth.js

@@ -81,10 +81,13 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
     // Tracked here rather than read off `axios.defaults` so the answer stays tied
     // to the identity transitions below (`setToken`, `logout`) instead of to the
     // header a caller may have set on the instance directly.
-    let hasAccessToken = Boolean(options.token);
+    let accessToken = options.token;
     return {
         hasToken() {
-            return hasAccessToken;
+            return Boolean(accessToken);
+        },
+        getToken() {
+            return accessToken;
         },
         // Get current user information
         async me() {
@@ -151,7 +154,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // flight would otherwise resolve into callers that run after the logout.
             clearPendingMe();
             resetAnalyticsSessionContext();
-            hasAccessToken = false;
+            accessToken = undefined;
             // Only do the rest if in a browser environment
             if (typeof window !== "undefined") {
                 // Remove token from localStorage
@@ -180,7 +183,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // resolved for the previous one must not be handed to later callers.
             clearPendingMe();
             resetAnalyticsSessionContext();
-            hasAccessToken = true;
+            accessToken = token;
             // handle token change for axios clients
             axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;
             functionsAxiosClient.defaults.headers.common["Authorization"] = `Bearer ${token}`;

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

@@ -537,4 +537,6 @@ export interface InternalAuthModule extends AuthModule {
      * could not succeed without a session, not to decide that one is valid.
      */
     hasToken(): boolean;
+    /** Current access token used by internal transports. */
+    getToken(): string | undefined;
 }

package/dist/utils/axios-client.js

@@ -137,7 +137,8 @@ export function createAxiosClient({ baseURL, headers = {}, token, interceptRespo
             // 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.
-            if (!config.headers.get("Authorization")) {
+            if (!config.headers.get("Authorization") &&
+                !config.headers.get("X-Base44-Anonymous-Id")) {
                 config.headers.set("X-Base44-Anonymous-Id", getAnalyticsSessionId());
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.43-pr.257.a72bddf",
+  "version": "0.8.43-pr.259.3f82534",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",