@base44-preview/sdk 0.8.40-pr.242.b74cef0 → 0.8.41-pr.244.e7d6747

package/dist/actor.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
+ *
+ * At deploy time the bundler replaces this import with the compiled
+ * Cloudflare Durable Object implementation — this file provides types only.
+ */
+import type { Base44Client } from "./client";
+/**
+ * A single client connection. `Send` is the message type this connection accepts
+ * via {@link send} — the actor's *outgoing* (server→client) messages.
+ */
+export interface Conn<Send = unknown> {
+    /** Unique per-connection id (one per socket/tab), the same value the client
+     *  receives from `subscribe()`. Identifies a distinct client, so multiple
+     *  tabs are separate connections. */
+    id: string;
+    send(data: Send): void;
+    reject(code: number, reason: string): void;
+}
+export interface Storage {
+    get<T>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Wipe the room's entire persisted storage (match-end cleanup). Safe: a
+     *  later rejoin re-bootstraps exactly like a brand-new room. */
+    deleteAll(): Promise<void>;
+}
+/**
+ * Base class for an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this actor *sends* to clients
+ *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
+ *
+ * With a generated `schema.jsonc`, wire both from the registry so they can't drift
+ * from the client's types:
+ * ```ts
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export declare abstract class Actor<Incoming = unknown, Outgoing = unknown> {
+    abstract handleConnect(conn: Conn<Outgoing>): void | Promise<void>;
+    abstract handleMessage(conn: Conn<Outgoing>, msg: Incoming): void | Promise<void>;
+    abstract handleClose(conn: Conn<Outgoing>): void | Promise<void>;
+    abstract handleTick(): void | Promise<void>;
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart(): void | Promise<void>;
+    /**
+     * Optional handler for scheduled wakes. Runs when a timer armed via
+     * {@link schedule} comes due, receiving the same `key` that was scheduled.
+     * The schedule is one-shot: it fires once and is cleared before this runs.
+     */
+    protected handleWake(_key: string): void | Promise<void>;
+    /**
+     * Arm a one-shot wake at `at` (epoch ms or a `Date`), identified by `key`.
+     * When it comes due the platform calls {@link handleWake} with this `key`.
+     * Scheduling the same `key` again reschedules it.
+     */
+    protected schedule(_key: string, _at: number | Date): Promise<void>;
+    /** Cancel a pending wake previously armed with {@link schedule}. */
+    protected cancelSchedule(_key: string): Promise<void>;
+    /**
+     * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+     * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+     * and stops (letting the Durable Object hibernate — no compute cost) when it
+     * returns false. The platform owns scheduling, rescheduling, self-heal, and
+     * error-safety.
+     *
+     * Re-evaluated after every connect/message/close and on every tick, so keep it
+     * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+     */
+    protected tickIntervalMs: number;
+    protected shouldTick?(): boolean;
+    protected broadcast(_data: Outgoing): void;
+    protected getConnections(): Conn<Outgoing>[];
+    protected get instanceId(): string;
+    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.
+     * Example: `const rows = await this.client.entities.Score.list();`
+     */
+    protected get client(): Base44Client;
+}

package/dist/actor.js

@@ -0,0 +1,85 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
+ *
+ * At deploy time the bundler replaces this import with the compiled
+ * Cloudflare Durable Object implementation — this file provides types only.
+ */
+/**
+ * Base class for an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this actor *sends* to clients
+ *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
+ *
+ * With a generated `schema.jsonc`, wire both from the registry so they can't drift
+ * from the client's types:
+ * ```ts
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export class Actor {
+    constructor() {
+        /**
+         * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+         * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+         * and stops (letting the Durable Object hibernate — no compute cost) when it
+         * returns false. The platform owns scheduling, rescheduling, self-heal, and
+         * error-safety.
+         *
+         * Re-evaluated after every connect/message/close and on every tick, so keep it
+         * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+         */
+        this.tickIntervalMs = 100;
+    }
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart() { }
+    /**
+     * Optional handler for scheduled wakes. Runs when a timer armed via
+     * {@link schedule} comes due, receiving the same `key` that was scheduled.
+     * The schedule is one-shot: it fires once and is cleared before this runs.
+     */
+    handleWake(_key) { }
+    /**
+     * Arm a one-shot wake at `at` (epoch ms or a `Date`), identified by `key`.
+     * When it comes due the platform calls {@link handleWake} with this `key`.
+     * Scheduling the same `key` again reschedules it.
+     */
+    schedule(_key, _at) {
+        throw new Error("Actor.schedule() is only available inside a deployed actor");
+    }
+    /** Cancel a pending wake previously armed with {@link schedule}. */
+    cancelSchedule(_key) {
+        throw new Error("Actor.cancelSchedule() is only available inside a deployed actor");
+    }
+    broadcast(_data) {
+        throw new Error("Actor.broadcast() is only available inside a deployed actor");
+    }
+    getConnections() {
+        throw new Error("Actor.getConnections() is only available inside a deployed actor");
+    }
+    get instanceId() {
+        throw new Error("Actor.instanceId is only available inside a deployed actor");
+    }
+    get storage() {
+        throw new Error("Actor.storage is only available inside a deployed actor");
+    }
+    /**
+     * 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.
+     * Example: `const rows = await this.client.entities.Score.list();`
+     */
+    get client() {
+        throw new Error("Actor.client is only available inside a deployed actor");
+    }
+}

package/dist/client.js

@@ -5,6 +5,7 @@ import { createAuthModule } from "./modules/auth.js";
 import { createSsoModule } from "./modules/sso.js";
 import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
+import { redeemSessionHandoffCode } from "./utils/session-handoff.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
@@ -12,6 +13,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";
 /**
  * Creates a Base44 client.
  *
@@ -50,7 +52,7 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  * ```
  */
 export function createClient(config) {
-    var _a, _b;
+    var _a, _b, _c;
     const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
@@ -117,12 +119,42 @@ export function createClient(config) {
     // requests during construction (notably analytics, which fires an init
     // event whose flush calls auth.me()). Without this, the first User/me
     // request is built before setToken runs and goes out unauthenticated.
+    //
+    // Precedence: an explicit config token wins (legacy behavior); then a PKCE
+    // session-code handoff in the URL (base44-dev/apper#17216 §5.2) — the user
+    // just completed a login, so it outranks any stored token, mirroring how
+    // getAccessToken prefers a URL access_token over localStorage; then the
+    // legacy capture. When the server spoke legacy — including after a backend
+    // rollback — redeemSessionHandoffCode() returns null synchronously and the
+    // legacy capture below runs unchanged.
+    let tokenBootstrap = null;
     if (typeof window !== "undefined") {
-        const accessToken = token || getAccessToken();
-        if (accessToken) {
-            userAuthModule.setToken(accessToken);
+        const sessionExchange = token ? null : redeemSessionHandoffCode();
+        if (sessionExchange) {
+            tokenBootstrap = sessionExchange.then((exchangedToken) => {
+                // On exchange failure, fall back to any stored token rather than
+                // leaving auth state empty (same fallback getAccessToken applies).
+                const accessToken = exchangedToken || getAccessToken();
+                if (accessToken) {
+                    userAuthModule.setToken(accessToken);
+                }
+            });
+        }
+        else {
+            const accessToken = token || getAccessToken();
+            if (accessToken) {
+                userAuthModule.setToken(accessToken);
+            }
         }
     }
+    const actorsModule = createActorsModule({
+        appId,
+        // serverUrl is often relative/empty (same-origin app); PartySocket needs an
+        // absolute host, so fall back to the page origin.
+        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined),
+        functionsVersion,
+        getAuthToken: () => token || getAccessToken(),
+    });
     const userModules = {
         entities: createEntitiesModule({
             axios: axiosClient,
@@ -142,7 +174,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_a = functionsAxiosClient.defaults) === null || _a === void 0 ? void 0 : _a.baseURL,
+            baseURL: (_b = functionsAxiosClient.defaults) === null || _b === void 0 ? void 0 : _b.baseURL,
         }),
         agents: createAgentsModule({
             axios: axiosClient,
@@ -160,8 +192,10 @@ export function createClient(config) {
             appId,
             userAuthModule,
         }),
+        actors: actorsModule.module,
         cleanup: () => {
             userModules.analytics.cleanup();
+            actorsModule.closeAll();
             if (socket) {
                 socket.disconnect();
             }
@@ -185,7 +219,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_b = serviceRoleFunctionsAxiosClient.defaults) === null || _b === void 0 ? void 0 : _b.baseURL,
+            baseURL: (_c = serviceRoleFunctionsAxiosClient.defaults) === null || _c === void 0 ? void 0 : _c.baseURL,
         }),
         agents: createAgentsModule({
             axios: serviceRoleAxiosClient,
@@ -207,6 +241,13 @@ export function createClient(config) {
         // We perform this check asynchronously to not block client creation
         setTimeout(async () => {
             try {
+                // A pending session-code exchange must settle before the auth probe.
+                // Probing early would see no token, redirect to login, and abandon
+                // the in-flight exchange — minting a fresh code on every round, i.e.
+                // a login loop (the exact BUG-787 failure shape).
+                if (tokenBootstrap) {
+                    await tokenBootstrap;
+                }
                 const isAuthenticated = await userModules.auth.isAuthenticated();
                 if (!isAuthenticated) {
                     userModules.auth.redirectToLogin(window.location.href);

package/dist/client.types.d.ts

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

package/dist/index.d.ts

@@ -11,7 +11,9 @@ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./mod
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
+export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
+export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

package/dist/index.js

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

package/dist/modules/actors.d.ts

@@ -0,0 +1,25 @@
+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. */
+    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}. */
+    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).
+ */
+export declare function resolveActorsHost(serverUrl: string, browserOrigin?: string): string;
+export declare function createActorsModule(config: ActorsConfig): {
+    module: Record<string, (instanceId: string) => ActorRef>;
+    closeAll: () => void;
+};
+export {};

package/dist/modules/actors.js

@@ -0,0 +1,135 @@
+import PartySocket from "partysocket";
+// Heartbeat / half-open detection: PartySocket only reconnects on a close/error
+// event, so ping periodically and force a reconnect if nothing returns in DEAD_MS.
+const PING_MS = 1000;
+const DEAD_MS = 3000;
+/**
+ * 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, onClose) {
+        var _a;
+        this.onClose = onClose;
+        this.listeners = 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.ws = ws;
+        let lastMsg = Date.now();
+        const bumpAlive = () => { lastMsg = Date.now(); };
+        ws.addEventListener("open", bumpAlive);
+        ws.addEventListener("message", (ev) => {
+            bumpAlive();
+            let data;
+            try {
+                data = JSON.parse(ev.data);
+            }
+            catch (_a) {
+                return;
+            }
+            const msgType = data && typeof data === "object" ? data.type : undefined;
+            if (msgType === "__pong")
+                return;
+            for (const listener of this.listeners)
+                listener(data);
+        });
+        this.heartbeat = setInterval(() => {
+            if (Date.now() - lastMsg > DEAD_MS) {
+                bumpAlive(); // avoid a reconnect storm while the new socket comes up
+                ws.reconnect();
+                return;
+            }
+            try {
+                // The deployed shim echoes __ping → __pong (base44-userapp-bundler
+                // shim/actor.ts); without that, an idle room reconnects every DEAD_MS.
+                ws.send(JSON.stringify({ type: "__ping" }));
+            }
+            catch (_a) {
+                // not open; the watchdog above will reconnect
+            }
+        }, PING_MS);
+    }
+    subscribe(callback) {
+        this.listeners.add(callback);
+        return {
+            unsubscribe: () => { this.listeners.delete(callback); },
+        };
+    }
+    send(data) {
+        this.ws.send(JSON.stringify(data));
+    }
+    close() {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+        this.listeners.clear();
+        this.ws.close();
+        this.onClose();
+    }
+}
+/** Handle for one actor instance: `connect()` opens the socket (idempotent). */
+function makeActorRef(actorName, instanceId, config, connections) {
+    let conn = null;
+    return {
+        connect(options) {
+            if (conn)
+                return conn;
+            const c = new Connection(actorName, instanceId, config, options, () => {
+                connections.delete(c);
+                if (conn === c)
+                    conn = null; // allow a fresh connect() after close
+            });
+            conn = c;
+            connections.add(c);
+            return c;
+        },
+    };
+}
+/**
+ * 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).
+ */
+export function resolveActorsHost(serverUrl, browserOrigin) {
+    return serverUrl && !serverUrl.startsWith("/") ? serverUrl : browserOrigin !== null && browserOrigin !== void 0 ? browserOrigin : serverUrl;
+}
+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();
+    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 {
+        module,
+        closeAll: () => {
+            for (const c of [...connections])
+                c.close();
+        },
+    };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed Actors.
+ *
+ * This is separate from {@link ActorNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
+ *
+ * @example
+ * ```typescript
+ * declare module "@base44/sdk" {
+ *   interface ActorRegistry {
+ *     ChatRoom: {
+ *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
+ *       toServer: { type: "message"; text: string };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface ActorRegistry {
+}
+/**
+ * Auto-populated by `base44 types generate` with the names of your deployed actors.
+ * Do not edit this interface manually — use {@link ActorRegistry} for message types.
+ */
+export interface ActorNameRegistry {
+}
+type AllActorNames = keyof ActorRegistry | keyof ActorNameRegistry;
+type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toClient: infer I;
+} ? I : unknown : unknown;
+type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toServer: infer O;
+} ? O : unknown : unknown;
+/** Options for {@link ActorRef.connect}. */
+export interface ActorConnectOptions {
+    /**
+     * The connection id — becomes the actor's `conn.id`. Supply a stable value
+     * (e.g. persisted per tab) so a reconnect reuses the same server-side
+     * identity; omit for an auto-generated per-connection id.
+     */
+    id?: string;
+}
+/** Handle for one listener registered via {@link Connection.subscribe}. */
+export interface ActorSubscription {
+    /** Remove this listener; other listeners and the socket 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.
+ */
+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. */
+    subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
+    /** Send a message. Buffered by the socket until it's open. */
+    send(data: ToServerFor<N>): void;
+    /** Tear down the socket, heartbeat, and all listeners. */
+    close(): void;
+}
+/**
+ * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
+ * {@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. */
+    connect(options?: ActorConnectOptions): Connection<N>;
+}
+/**
+ * Client for a single named Actor — call it with an instance id to get an
+ * {@link ActorRef}. Typed automatically when the actor is registered in
+ * {@link ActorRegistry}.
+ */
+export interface ActorClient<N extends string = string> {
+    (instanceId: string): ActorRef<N>;
+}
+/**
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
+ *
+ * ```typescript
+ * const conn = base44.actors.MyActor("room-1").connect();
+ * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * conn.send({ type: "message", text: "hi" });
+ * sub.unsubscribe();
+ * conn.close();
+ * ```
+ */
+export type ActorsModule = {
+    [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;
+} & Record<string, ActorClient>;
+export {};

package/dist/modules/actors.types.js

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

package/dist/modules/auth.js

@@ -1,4 +1,4 @@
-import { getLoginUrl } from "../utils/auth-utils.js";
+import { prepareSessionHandoffKickoff } from "../utils/session-handoff.js";
 function isInsideIframe() {
     if (typeof window === "undefined")
         return false;
@@ -83,11 +83,8 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             const redirectUrl = nextUrl
                 ? new URL(nextUrl, window.location.origin).toString()
                 : window.location.href;
-            // A foreign origin (e.g. local dev) can't resolve the app by Host, so
-            // the login URL must carry the app id; same-origin keeps the bare path.
-            const loginUrl = options.appBaseUrl
-                ? getLoginUrl(redirectUrl, { serverUrl: options.appBaseUrl, appId })
-                : `/login?from_url=${encodeURIComponent(redirectUrl)}`;
+            // Build the login URL
+            const loginUrl = `${options.appBaseUrl}/login?from_url=${encodeURIComponent(redirectUrl)}`;
             // Redirect to the login page
             window.location.href = loginUrl;
         },
@@ -108,11 +105,32 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             }
             const loginUrl = `${options.appBaseUrl}/api${authPath}?${queryParams}`;
             // When running inside an iframe, use a popup to avoid OAuth providers
-            // blocking iframe navigation.
+            // blocking iframe navigation. Popups stay on the exact legacy kickoff:
+            // they deliver the token via postMessage and never redeem a code (the
+            // backend skips the code mint when popup_origin is present).
             if (isInsideIframe()) {
                 const popupLoginUrl = `${loginUrl}&popup_origin=${encodeURIComponent(window.location.origin)}`;
                 return loginViaPopup(popupLoginUrl, redirectUrl, window.location.origin);
             }
+            // Full-page SSO redirect: offer the PKCE session-code handoff
+            // (base44-dev/apper#17216 §5.2). The backend decides per request whether
+            // to use it; a server that answers with the legacy ?access_token= —
+            // including after a backend rollback — is honored unchanged at
+            // redemption. If PKCE can't be prepared locally, kick off with the
+            // unmodified legacy URL (version=2 without a valid challenge is a 400
+            // at /login, so it's all-or-nothing).
+            if (provider === "sso") {
+                prepareSessionHandoffKickoff()
+                    .then((pkceQuery) => {
+                    window.location.href = pkceQuery
+                        ? `${loginUrl}${pkceQuery}`
+                        : loginUrl;
+                })
+                    .catch(() => {
+                    window.location.href = loginUrl;
+                });
+                return;
+            }
             // Default: full-page redirect
             window.location.href = loginUrl;
         },

package/dist/utils/session-handoff.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PKCE-bound one-time session-code handoff for SSO logins
+ * (base44-dev/apper#17216 §5.2).
+ *
+ * The SDK OFFERS the handoff at login kickoff (`version=2` + S256
+ * `code_challenge`) and the backend DECIDES per request: it only emits a
+ * `session_code` when every server-side gate holds (verified custom domain,
+ * non-private app, feature flag ON). In every other case — older backends,
+ * excluded apps, and critically a BACKEND ROLLBACK — the server keeps
+ * delivering the legacy `?access_token=` URL param, which the SDK digests
+ * exactly as before. This is a negotiation, never a deprecation: the legacy
+ * path must keep working here forever.
+ *
+ * Fail-open rule for kickoff: never send `version=2` unless this browser can
+ * actually complete the exchange (WebCrypto, sessionStorage that persists,
+ * fetch). The server 400s a `version=2` login without a valid challenge, and
+ * an opted-in login whose verifier is lost can never redeem its code — both
+ * are avoided by simply not opting in and letting the legacy path run.
+ */
+/** sessionStorage key for the PKCE verifier. Per-tab by design (RFC 7636: the
+ * verifier never leaves the browser); a login that completes in a different
+ * tab loses it — a named, expected failure mode, see redeemSessionHandoffCode. */
+export declare const PKCE_VERIFIER_STORAGE_KEY = "base44_pkce_verifier";
+/**
+ * Prepares the PKCE opt-in for an SSO login kickoff.
+ *
+ * Generates a verifier, persists it in sessionStorage (verified by read-back —
+ * a write that doesn't stick means the exchange could never succeed), and
+ * returns the query-string suffix to append to the login URL:
+ * `&version=2&code_challenge=<S256>&code_challenge_method=S256`.
+ *
+ * Returns `null` on ANY failure or missing capability, in which case the
+ * caller must use the unmodified legacy login URL. Never throws.
+ *
+ * @internal
+ */
+export declare function prepareSessionHandoffKickoff(): Promise<string | null>;
+/**
+ * Redeems a PKCE session-code handoff from the current URL, if one is present.
+ *
+ * Returns `null` synchronously when the URL carries no handoff — including
+ * when it carries a legacy `?access_token=` (the legacy capture wins outright;
+ * this is what makes a backend rollback safe). Otherwise strips the handoff
+ * params from the URL immediately and returns a promise resolving to the
+ * exchanged access token, or `null` when the exchange fails. Never rejects,
+ * never redirects: a failed exchange leaves the app unauthenticated and lets
+ * its normal login flow take over (each retry mints a fresh code, so this
+ * self-heals rather than looping).
+ *
+ * @internal
+ */
+export declare function redeemSessionHandoffCode(): Promise<string | null> | null;

package/dist/utils/session-handoff.js

@@ -0,0 +1,184 @@
+/**
+ * PKCE-bound one-time session-code handoff for SSO logins
+ * (base44-dev/apper#17216 §5.2).
+ *
+ * The SDK OFFERS the handoff at login kickoff (`version=2` + S256
+ * `code_challenge`) and the backend DECIDES per request: it only emits a
+ * `session_code` when every server-side gate holds (verified custom domain,
+ * non-private app, feature flag ON). In every other case — older backends,
+ * excluded apps, and critically a BACKEND ROLLBACK — the server keeps
+ * delivering the legacy `?access_token=` URL param, which the SDK digests
+ * exactly as before. This is a negotiation, never a deprecation: the legacy
+ * path must keep working here forever.
+ *
+ * Fail-open rule for kickoff: never send `version=2` unless this browser can
+ * actually complete the exchange (WebCrypto, sessionStorage that persists,
+ * fetch). The server 400s a `version=2` login without a valid challenge, and
+ * an opted-in login whose verifier is lost can never redeem its code — both
+ * are avoided by simply not opting in and letting the legacy path run.
+ */
+/** sessionStorage key for the PKCE verifier. Per-tab by design (RFC 7636: the
+ * verifier never leaves the browser); a login that completes in a different
+ * tab loses it — a named, expected failure mode, see redeemSessionHandoffCode. */
+export const PKCE_VERIFIER_STORAGE_KEY = "base44_pkce_verifier";
+/** Server-side format for challenge/verifier: base64url of 32 bytes, 43 chars. */
+const BASE64URL_43 = /^[A-Za-z0-9_-]{43}$/;
+function base64UrlEncode(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Prepares the PKCE opt-in for an SSO login kickoff.
+ *
+ * Generates a verifier, persists it in sessionStorage (verified by read-back —
+ * a write that doesn't stick means the exchange could never succeed), and
+ * returns the query-string suffix to append to the login URL:
+ * `&version=2&code_challenge=<S256>&code_challenge_method=S256`.
+ *
+ * Returns `null` on ANY failure or missing capability, in which case the
+ * caller must use the unmodified legacy login URL. Never throws.
+ *
+ * @internal
+ */
+export async function prepareSessionHandoffKickoff() {
+    var _a;
+    try {
+        if (typeof window === "undefined")
+            return null;
+        const crypto = globalThis.crypto;
+        if (!(crypto === null || crypto === void 0 ? void 0 : crypto.getRandomValues) || !((_a = crypto.subtle) === null || _a === void 0 ? void 0 : _a.digest))
+            return null;
+        // The exchange at redemption time needs fetch; don't opt in without it.
+        if (typeof fetch !== "function")
+            return null;
+        const verifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+        const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+        const challenge = base64UrlEncode(new Uint8Array(digest));
+        // The server rejects a malformed opt-in with a 400 at /login; a malformed
+        // challenge here must therefore mean "don't opt in", never "send anyway".
+        if (!BASE64URL_43.test(challenge))
+            return null;
+        // Store last, after everything else succeeded, and verify the write took
+        // (sandboxed iframes and lockdown modes can throw OR silently drop it).
+        window.sessionStorage.setItem(PKCE_VERIFIER_STORAGE_KEY, verifier);
+        if (window.sessionStorage.getItem(PKCE_VERIFIER_STORAGE_KEY) !== verifier) {
+            return null;
+        }
+        return `&version=2&code_challenge=${challenge}&code_challenge_method=S256`;
+    }
+    catch (_b) {
+        return null;
+    }
+}
+/**
+ * Redeems a PKCE session-code handoff from the current URL, if one is present.
+ *
+ * Returns `null` synchronously when the URL carries no handoff — including
+ * when it carries a legacy `?access_token=` (the legacy capture wins outright;
+ * this is what makes a backend rollback safe). Otherwise strips the handoff
+ * params from the URL immediately and returns a promise resolving to the
+ * exchanged access token, or `null` when the exchange fails. Never rejects,
+ * never redirects: a failed exchange leaves the app unauthenticated and lets
+ * its normal login flow take over (each retry mints a fresh code, so this
+ * self-heals rather than looping).
+ *
+ * @internal
+ */
+export function redeemSessionHandoffCode() {
+    if (typeof window === "undefined" || !window.location)
+        return null;
+    let code = null;
+    let exchangePath = null;
+    let urlParams;
+    try {
+        urlParams = new URLSearchParams(window.location.search);
+        code = urlParams.get("session_code");
+        exchangePath = urlParams.get("session_exchange_path");
+        if (!code || !exchangePath)
+            return null;
+        // A server speaking legacy is authoritative: if an access_token is in the
+        // URL (the two are never both sent by a real backend), take the legacy
+        // path and ignore the code entirely.
+        if (urlParams.get("access_token"))
+            return null;
+        // Strip the one-time params right away so the code doesn't linger in the
+        // URL/history or get re-submitted on reload. `is_new_user` stays in the
+        // URL exactly as the legacy flow leaves it.
+        urlParams.delete("session_code");
+        urlParams.delete("session_exchange_path");
+        const newUrl = `${window.location.pathname}${urlParams.toString() ? `?${urlParams.toString()}` : ""}${window.location.hash}`;
+        window.history.replaceState({}, typeof document !== "undefined" ? document.title : "", newUrl);
+    }
+    catch (e) {
+        console.error("Error reading session handoff params from URL:", e);
+        return null;
+    }
+    return exchangeSessionHandoffCode(code, exchangePath);
+}
+async function exchangeSessionHandoffCode(code, exchangePath) {
+    // The verifier is one-shot: take it out of storage no matter how the
+    // exchange ends (a failed PKCE check doesn't burn the code server-side,
+    // but a stale verifier can never match a future login's challenge).
+    let verifier = null;
+    try {
+        verifier = window.sessionStorage.getItem(PKCE_VERIFIER_STORAGE_KEY);
+        if (verifier !== null) {
+            window.sessionStorage.removeItem(PKCE_VERIFIER_STORAGE_KEY);
+        }
+    }
+    catch (_a) {
+        verifier = null;
+    }
+    // SECURITY: the exchange path arrives via the URL, so treat it as tainted.
+    // POSTing the code + verifier to an attacker-chosen origin would hand over
+    // both halves of the PKCE proof — enforce same-origin, path-only semantics.
+    let exchangeUrl;
+    try {
+        exchangeUrl = new URL(exchangePath, window.location.origin);
+    }
+    catch (_b) {
+        console.error("Invalid session_exchange_path; skipping token exchange.");
+        return null;
+    }
+    if (exchangeUrl.origin !== window.location.origin) {
+        console.error("Cross-origin session_exchange_path rejected; skipping token exchange.");
+        return null;
+    }
+    if (typeof fetch !== "function")
+        return null;
+    try {
+        const response = await fetch(exchangeUrl.toString(), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                code,
+                ...(verifier ? { code_verifier: verifier } : {}),
+            }),
+        });
+        if (!response.ok) {
+            if (!verifier) {
+                // Named failure mode (base44-dev/apper#17216): the login completed in
+                // a different tab/window than it started in, so the per-tab PKCE
+                // verifier is gone and the server fails closed. Logging in again from
+                // this tab works.
+                console.warn("Base44 SDK: SSO login could not be completed because it finished " +
+                    "in a different browser tab than it started in (missing PKCE " +
+                    "verifier). Please log in again.");
+            }
+            else {
+                console.error(`Base44 SDK: SSO session-code exchange failed (HTTP ${response.status}).`);
+            }
+            return null;
+        }
+        const data = await response.json();
+        const accessToken = data === null || data === void 0 ? void 0 : data.access_token;
+        return typeof accessToken === "string" && accessToken ? accessToken : null;
+    }
+    catch (e) {
+        console.error("Base44 SDK: SSO session-code exchange failed:", e);
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.40-pr.242.b74cef0",
+  "version": "0.8.41-pr.244.e7d6747",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "axios": "^1.18.1",
+    "partysocket": "^0.0.23",
     "socket.io-client": "^4.8.3",
     "uuid": "^13.0.2"
   },