@base44-preview/sdk 0.8.43-pr.259.3f82534 → 0.8.43-pr.260.d28232f

package/dist/actor.d.ts

@@ -9,13 +9,6 @@
  * 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.
@@ -25,8 +18,6 @@ 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;
 }
@@ -95,10 +86,9 @@ 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). 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.
+     * 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.
      * Example: `const rows = await this.client.entities.Score.list();`
      */
     protected get client(): Base44Client;

package/dist/actor.js

@@ -74,10 +74,9 @@ 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). 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.
+     * 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.
      * Example: `const rows = await this.client.entities.Score.list();`
      */
     get client() {

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.
  *
@@ -94,13 +94,6 @@ 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}` } : {}),
@@ -117,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,
@@ -134,13 +136,26 @@ export function createClient(config) {
     }
     const actorsModule = createActorsModule({
         appId,
-        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.
+        // 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: () => userAuthModule.getToken(),
+        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,10 +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.
-     * Actor connection failures are contextual `ActorConnectionError` instances.
-     * Retryable Actor failures may be reported more than once.
+     *
+     * 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/index.d.ts

@@ -12,9 +12,8 @@ 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 ActorConnectionIdentity, type Conn } from "./actor.js";
-export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
+export { Actor, type Conn } from "./actor.js";
+export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase, } 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,5 +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 { ActorConnectionError } from "./modules/actors.error.js";
 export { Actor } from "./actor.js";

package/dist/modules/actors.d.ts

@@ -1,22 +1,47 @@
-import { type AxiosInstance } from "axios";
-import { ActorConnectionError } from "./actors.error.js";
 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;
-    connectionClient: AxiosInstance;
-    onError?: (error: ActorConnectionError) => void;
-    /** Current user access token, if authenticated. */
+    /** 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 used when a legacy Actor falls back to the Apper proxy. */
+    /** 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 legacy Actor WebSocket. A relative/empty `serverUrl`
- * cannot identify the Apper proxy, so same-origin apps fall back to the page
- * origin.
+ * 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,150 +1,97 @@
-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
+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;
-// 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;
+// 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 connection to an actor instance. Only obtainable from {@link ActorRef.connect}.
+ * 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.
  */
 class Connection {
-    constructor(actorName, instanceId, config, options, getAnonymousId, onClose) {
-        this.actorName = actorName;
-        this.instanceId = instanceId;
+    constructor(actorName, instanceId, config, options, onClose) {
+        var _a;
         this.onClose = onClose;
         this.listeners = new Set();
-        this.errorListeners = new Set();
         this.heartbeat = null;
-        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 () => {
+        this.closed = false;
+        this.id = (_a = options === null || options === void 0 ? void 0 : options.id) !== null && _a !== void 0 ? _a : crypto.randomUUID();
+        // 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.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);
+            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)}`;
                 }
-                else {
-                    this.reportAttemptFailure(connectionError);
+                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;
                 }
-                throw connectionError;
             }
-        }, undefined, { startClosed: 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 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));
-        });
+        let lastMsg = Date.now();
+        const bumpAlive = () => { lastMsg = Date.now(); };
+        ws.addEventListener("open", bumpAlive);
         ws.addEventListener("message", (ev) => {
-            markAlive();
-            silentReconnects = 0;
+            bumpAlive();
             let data;
             try {
                 data = JSON.parse(ev.data);
@@ -159,176 +106,58 @@ class Connection {
                 listener(data);
         });
         this.heartbeat = setInterval(() => {
-            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;
-                }
+            if (Date.now() - lastMsg > DEAD_MS) {
+                bumpAlive(); // avoid a reconnect storm while the new socket comes up
+                // 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 {
                 // The deployed shim echoes __ping → __pong (base44-userapp-bundler
-                // shim/actor.ts); without that, an idle room reconnects on a widening
-                // interval (DEAD_MS up to MAX_DEAD_MS).
+                // shim/actor.ts); without that, an idle room reconnects every DEAD_MS.
                 ws.send(JSON.stringify({ type: "__ping" }));
             }
             catch (_a) {
-                // The next watchdog tick will reconnect if the link stays half-open.
+                // not open; the watchdog above will reconnect
             }
         }, PING_MS);
-        ws.reconnect();
     }
     subscribe(callback) {
-        this.assertNotClosed();
         this.listeners.add(callback);
         return {
             unsubscribe: () => { this.listeners.delete(callback); },
         };
     }
     send(data) {
-        this.assertNotClosed();
+        // after close() the socket would buffer forever (unbounded enqueue)
+        if (this.closed)
+            return;
         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)
+        if (this.closed)
             return;
-        this.isClosed = true;
-        this.closedError = error;
+        this.closed = true;
         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, getAnonymousId, connections) {
-    assertValidInstanceId(instanceId);
+function makeActorRef(actorName, instanceId, config, connections) {
     let conn = null;
     return {
         connect(options) {
-            // 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");
-                }
+            if (conn)
                 return conn;
-            }
-            const c = new Connection(actorName, instanceId, config, options, getAnonymousId, () => {
+            const c = new Connection(actorName, instanceId, config, options, () => {
                 connections.delete(c);
                 if (conn === c)
                     conn = null; // allow a fresh connect() after close
@@ -340,91 +169,53 @@ function makeActorRef(actorName, instanceId, config, getAnonymousId, connections
     };
 }
 /**
- * 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.
+ * 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;
 }
-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, getAnonymousId, connections);
+            return (instanceId) => makeActorRef(key, instanceId, config, connections);
         },
     });
     return {

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

@@ -1,4 +1,3 @@
-import type { ActorConnectionError } from "./actors.error.js";
 /**
  * Extend this interface to add typed `subscribe` callbacks and `send` payloads
  * for your deployed Actors.
@@ -37,44 +36,34 @@ 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) 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.
+     * (e.g. persisted per tab) 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 connection listener. */
+/** Handle for one listener registered via {@link Connection.subscribe}. */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the connection stay live. */
+    /** Remove this listener; other listeners and the socket stay live. */
     unsubscribe(): void;
 }
 /**
- * A connection to an actor instance, returned by {@link ActorRef.connect}.
+ * A live connection to an actor instance, returned by {@link ActorRef.connect}.
+ * `subscribe`/`send` are always valid — you only get a `Connection` once the
+ * socket has been opened, so there's no pre-connect state to guard against.
  */
 export interface Connection<N extends string = string> {
     /** The connection id (the value the actor sees as `conn.id`). */
     readonly id: string;
-    /** 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. */
+    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered until open; throws instead of buffering after close. */
+    /** 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;
 }
 /**
@@ -83,9 +72,13 @@ export interface Connection<N extends string = string> {
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * 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.
+     * 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.js

@@ -81,13 +81,10 @@ 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 accessToken = options.token;
+    let hasAccessToken = Boolean(options.token);
     return {
         hasToken() {
-            return Boolean(accessToken);
-        },
-        getToken() {
-            return accessToken;
+            return hasAccessToken;
         },
         // Get current user information
         async me() {
@@ -154,7 +151,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // flight would otherwise resolve into callers that run after the logout.
             clearPendingMe();
             resetAnalyticsSessionContext();
-            accessToken = undefined;
+            hasAccessToken = false;
             // Only do the rest if in a browser environment
             if (typeof window !== "undefined") {
                 // Remove token from localStorage
@@ -183,7 +180,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // resolved for the previous one must not be handed to later callers.
             clearPendingMe();
             resetAnalyticsSessionContext();
-            accessToken = token;
+            hasAccessToken = true;
             // 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,6 +537,4 @@ 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/modules/connectors.js

@@ -1,3 +1,11 @@
+const CONNECTOR_API_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+]);
 /**
  * Creates the Connectors module for the Base44 SDK.
  *
@@ -68,6 +76,56 @@ export function createConnectorsModule(axios, appId) {
                 connectionConfig: (_a = data.connection_config) !== null && _a !== void 0 ? _a : null,
             };
         },
+        async callApi(integrationType, request) {
+            assertNonEmptyString(integrationType, "Integration type");
+            return proxyCall(axios, `/apps/${appId}/connectors/${integrationType}/call`, request);
+        },
+    };
+}
+function assertNonEmptyString(value, label) {
+    if (!value || typeof value !== "string") {
+        throw new Error(`${label} is required and must be a string`);
+    }
+}
+/**
+ * POST a request to the connector proxy and normalize the response.
+ *
+ * The proxy reports upstream outcomes in the body rather than as HTTP status, so
+ * a provider 4xx/5xx arrives here as a resolved response with `success: false` —
+ * only Base44-side failures reject through the axios error interceptor.
+ *
+ * @internal
+ */
+async function proxyCall(axios, url, request) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    if (!request || typeof request !== "object") {
+        throw new Error("Request is required and must be an object");
+    }
+    assertNonEmptyString(request.path, "Request path");
+    const method = (_a = request.method) !== null && _a !== void 0 ? _a : "GET";
+    if (!CONNECTOR_API_METHODS.has(method)) {
+        throw new Error("Request method must be one of GET, POST, PUT, PATCH, DELETE, or HEAD");
+    }
+    const response = await axios.post(url, {
+        method,
+        // Omitted rather than sent as null so the proxy applies the connector's
+        // declared default host.
+        ...(request.host === undefined ? {} : { host: request.host }),
+        path: request.path,
+        query: (_b = request.query) !== null && _b !== void 0 ? _b : {},
+        headers: (_c = request.headers) !== null && _c !== void 0 ? _c : {},
+        body: (_d = request.body) !== null && _d !== void 0 ? _d : null,
+    });
+    const data = response;
+    return {
+        success: data.success,
+        phase: data.phase,
+        status: (_e = data.status_code) !== null && _e !== void 0 ? _e : null,
+        data: data.data,
+        dataBase64: (_f = data.data_base64) !== null && _f !== void 0 ? _f : null,
+        contentType: (_g = data.content_type) !== null && _g !== void 0 ? _g : null,
+        headers: (_h = data.headers) !== null && _h !== void 0 ? _h : {},
+        creditsCharged: (_j = data.credits_charged) !== null && _j !== void 0 ? _j : 0,
     };
 }
 /**

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

@@ -41,6 +41,81 @@ export interface AppUserConnectorConnectionResponse {
     /** Key-value configuration for the connection, or `null` if the connector does not provide one. */
     connectionConfig: Record<string, string> | null;
 }
+/**
+ * How far a metered connector call progressed through the Base44 proxy.
+ *
+ * Only `not_sent` proves that the provider did not execute the request.
+ * `timed_out` and `sent_unconfirmed` may have executed upstream, so do not
+ * automatically retry non-idempotent requests based on those phases.
+ */
+export type ConnectorApiResponsePhase = "not_sent" | "responded" | "timed_out" | "sent_unconfirmed";
+/**
+ * A request to forward to a metered connector's API through the Base44 proxy.
+ */
+export interface ConnectorApiRequest {
+    /** HTTP method for the upstream request. Defaults to `'GET'`. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+    /**
+     * Which of the connector's API hosts to call, by the name it declares.
+     * Omit for its default host (the first one declared). Only relevant for
+     * connectors that expose more than one host.
+     */
+    host?: string;
+    /**
+     * Path relative to the connector's API root, starting with `/`, such as `'/2/tweets'`.
+     *
+     * Must not be an absolute URL. Query parameters may be included here or passed
+     * separately as {@link query}; either way they are forwarded and priced identically.
+     */
+    path: string;
+    /** Query parameters. Merged into the request URL alongside any already present in {@link path}. */
+    query?: Record<string, string | number | boolean | Array<string | number>>;
+    /** Extra request headers. Only headers the connector explicitly allows are forwarded; the rest are dropped. */
+    headers?: Record<string, string>;
+    /** JSON request body. Ignored for `GET` and `HEAD`. */
+    body?: unknown;
+}
+/**
+ * The upstream API's response, as returned by the Base44 connector proxy.
+ */
+export interface ConnectorApiResponse<T = unknown> {
+    /** `true` only when the upstream API returned a 2xx status. Proxy and upstream errors are `false`. */
+    success: boolean;
+    /** How far the call progressed. Only `not_sent` proves the provider did not execute it. */
+    phase: ConnectorApiResponsePhase;
+    /** The upstream HTTP status code, or `null` when no response was received. */
+    status: number | null;
+    /**
+     * The parsed upstream response body, or proxy error details when no response
+     * was received. `null` when the response was binary — see {@link dataBase64}.
+     */
+    data: T;
+    /**
+     * The response body base64-encoded, for the media types the connector declares
+     * as binary (images, PDFs). Set instead of {@link data}, never alongside it.
+     */
+    dataBase64: string | null;
+    /** The response media type, set only alongside {@link dataBase64}. */
+    contentType: string | null;
+    /** The subset of upstream response headers the connector exposes, typically rate-limit counters. */
+    headers: Record<string, string>;
+    /** Integration credits billed to the workspace for this call. */
+    creditsCharged: number;
+}
+/**
+ * Raw proxy response shape. Mapped to {@link ConnectorApiResponse} before being returned.
+ * @internal
+ */
+export interface ConnectorProxyRawResponse {
+    success: boolean;
+    phase: ConnectorApiResponsePhase;
+    status_code: number | null;
+    data: unknown;
+    data_base64: string | null;
+    content_type: string | null;
+    headers: Record<string, string>;
+    credits_charged: number;
+}
 /**
  * Connectors module for managing OAuth tokens for external services.
  *
@@ -71,6 +146,18 @@ export interface AppUserConnectorConnectionResponse {
  * 3. In a backend function, call {@linkcode getCurrentAppUserConnection | getCurrentAppUserConnection()} using the service role client (`base44.asServiceRole.connectors`) with the connector ID to retrieve the app user's token.
  * 4. Use the returned `accessToken` to call the external service's API directly. Some connectors also return a `connectionConfig` with additional values such as a subdomain for building the API URL.
  *
+ * ## Metered connectors
+ *
+ * A few [platform connectors](#shared-connectors) are backed by paid third-party APIs that charge Base44 per call. For those, the OAuth token is **not** available to your code — {@linkcode getConnection | getConnection()} rejects with a `403`. Call them with {@linkcode callApi | callApi()} instead: Base44 attaches the credential server-side, forwards the request, and bills your workspace's integration credits for the call.
+ *
+ * This applies to platform connectors only. A workspace-registered or app user connector runs on **your own** OAuth app, so the provider invoices you directly and there is nothing for Base44 to meter — those keep normal token access via {@linkcode getWorkspaceConnection | getWorkspaceConnection()} and {@linkcode getCurrentAppUserConnection | getCurrentAppUserConnection()}.
+ *
+ * Two things to keep in mind when writing against a metered connector:
+ *
+ * - **Cost varies by endpoint, sometimes sharply.** The same connector can charge two orders of magnitude more for one endpoint than another, so avoid putting an expensive call inside a loop and batch wherever the provider supports it. Each response reports what it actually cost as `creditsCharged`.
+ * - **Provider and transport outcomes are returned, not thrown.** A provider `4xx`/`5xx` or a connection failure comes back as `success: false` with its `phase`; authorization, quota, and invalid proxy requests reject the promise.
+ * - **Only `phase: 'not_sent'` proves the provider did not execute the request.** A timeout or in-flight failure may have executed upstream, so do not automatically retry a non-idempotent call unless the provider supports an idempotency key.
+ *
  * ## Available connectors
  *
  * The connectors below can be used as shared connectors or as app user connectors. For a shared platform connector, pass the integration type string to {@linkcode getConnection | getConnection()}. For a connector you register in Workspace Settings with your own OAuth app, use the connector ID with {@linkcode getWorkspaceConnection | getWorkspaceConnection()} for a shared token, or with {@linkcode getCurrentAppUserConnection | getCurrentAppUserConnection()} for a per-user token.
@@ -328,6 +415,41 @@ export interface ConnectorsModule {
      * ```
      */
     getCurrentAppUserConnection(connectorId: string): Promise<AppUserConnectorConnectionResponse>;
+    /**
+     * Calls a [metered connector's](#metered-connectors) API through the Base44 proxy.
+     *
+     * Use this for a shared platform connector identified by an integration type. Base44 adds the OAuth credential to the outgoing request, forwards it, and bills the workspace for the call, so you never handle the token yourself.
+     *
+     * @param integrationType - The type of integration, such as `'x'`. See [Available connectors](#available-connectors).
+     * @param request - The upstream request to forward. See {@link ConnectorApiRequest}.
+     * @returns Promise resolving to a {@link ConnectorApiResponse}. Note that an upstream error is reported in `success` and `status`, not thrown — only Base44-side failures reject.
+     *
+     * @example
+     * ```typescript
+     * // Post to X
+     * const res = await base44.asServiceRole.connectors.callApi('x', {
+     *   method: 'POST',
+     *   path: '/2/tweets',
+     *   body: { text: 'Shipped!' },
+     * });
+     *
+     * if (!res.success) {
+     *   console.error('X rejected the post', res.status, res.data);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Read, with query parameters and a look at what the call cost
+     * const res = await base44.asServiceRole.connectors.callApi('x', {
+     *   path: '/2/tweets/search/recent',
+     *   query: { query: 'base44', max_results: 10 },
+     * });
+     *
+     * console.log(`${res.creditsCharged} credits`, res.data);
+     * ```
+     */
+    callApi<T = unknown>(integrationType: ConnectorIntegrationType, request: ConnectorApiRequest): Promise<ConnectorApiResponse<T>>;
 }
 /**
  * User-scoped connectors module for managing app user OAuth connections.

package/dist/utils/axios-client.js

@@ -132,13 +132,14 @@ 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.
-            if (!config.headers.get("Authorization") &&
-                !config.headers.get("X-Base44-Anonymous-Id")) {
+            if (!config.headers.get("Authorization")) {
                 config.headers.set("X-Base44-Anonymous-Id", getAnalyticsSessionId());
             }
         }
@@ -186,11 +187,11 @@ export function createAxiosClient({ baseURL, headers = {}, token, interceptRespo
             }
             return response.data;
         }, (error) => {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
             const message = ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.message) ||
                 ((_d = (_c = error.response) === null || _c === void 0 ? void 0 : _c.data) === null || _d === void 0 ? void 0 : _d.detail) ||
                 error.message;
-            const base44Error = new Base44Error(message, (_e = error.response) === null || _e === void 0 ? void 0 : _e.status, (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.data) === null || _g === void 0 ? void 0 : _g.code, (_h = error.response) === null || _h === void 0 ? void 0 : _h.data, error);
+            const base44Error = new Base44Error(message, (_e = error.response) === null || _e === void 0 ? void 0 : _e.status, (_m = (_h = (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.data) === null || _g === void 0 ? void 0 : _g.code) !== null && _h !== void 0 ? _h : (_l = (_k = (_j = error.response) === null || _j === void 0 ? void 0 : _j.headers) === null || _k === void 0 ? void 0 : _k.get) === null || _l === void 0 ? void 0 : _l.call(_k, "x-base44-connector-error")) !== null && _m !== void 0 ? _m : (_p = (_o = error.response) === null || _o === void 0 ? void 0 : _o.headers) === null || _p === void 0 ? void 0 : _p["x-base44-connector-error"], (_q = error.response) === null || _q === void 0 ? void 0 : _q.data, error);
             // Log errors in development
             if (process.env.NODE_ENV !== "production") {
                 safeErrorLog("[Base44 SDK Error]", base44Error);

package/package.json

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

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

@@ -1,14 +0,0 @@
-/** 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

@@ -1,15 +0,0 @@
-/** 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;
-    }
-}