@base44-preview/sdk 0.8.48-pr.282.8a4c1c0 → 0.8.48-pr.282.8f60b80

package/dist/client.js

@@ -5,7 +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 { exchangeEmbedToken, takeEmbedTokenFromUrl, } from "./utils/embed-session.js";
+import { exchangeEmbedToken, frameSession, isFramed, takeEmbedTokenFromUrl, } from "./utils/embed-session.js";
 import { createFetchWithAuth } from "./utils/fetch-with-auth.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
@@ -58,34 +58,16 @@ export function createClient(config) {
     const { serverUrl = "https://base44.app", appId, analytics, 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 : "";
-    const embedOtt = takeEmbedTokenFromUrl();
-    // Asked again on every use, so a session that arrives later — from the
-    // exchange, or from a login — reaches the socket and every other module.
-    // A declaration, not a const, so this block can stay above the auth module.
-    function getToken() {
-        var _a;
-        return (_a = userAuthModule.getToken()) !== null && _a !== void 0 ? _a : (embedOtt ? null : getAccessToken());
-    }
-    const socketConfig = {
-        serverUrl,
-        mountPath: "/ws-user-apps/socket.io/",
-        transports: ["websocket"],
-        appId,
-        getToken,
-    };
-    let socket = null;
-    const getSocket = () => {
-        if (!socket) {
-            socket = RoomsSocket({
-                config: socketConfig,
-            });
-        }
-        return socket;
-    };
-    // Apps read getAccessToken() as they load and pass the result in as `token`,
-    // so on an embedded load this is the OTT: proof of an identity, not one to
-    // send as a bearer. The exchange below is what turns it into a session.
-    const token = embedOtt ? undefined : config.token;
+    // Always taken off the URL, even outside a frame: a one-time token must not
+    // be left in the address bar, in history, or in a shared link.
+    const urlOtt = takeEmbedTokenFromUrl();
+    // Only redeemed inside a frame. Opened as a normal tab, the same URL falls
+    // back to the app's own login, which works there and cannot work in a frame.
+    const embedOtt = isFramed() ? urlOtt : null;
+    const embedded = Boolean(embedOtt);
+    // The passed token is the OTT itself whenever one came in on the URL. That is
+    // not this session: it is what the exchange below trades for one.
+    const token = urlOtt !== null ? undefined : config.token;
     const headers = {
         ...optionalHeaders,
         "X-App-Id": String(appId),
@@ -134,11 +116,14 @@ export function createClient(config) {
         baseURL: `${serverUrl}/api`,
         headers,
     });
+    // Declared before the auth module so `onSessionChange` can reach it; the
+    // socket itself is still only built on first use, below.
+    let socket = null;
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
         appBaseUrl: normalizedAppBaseUrl,
         serverUrl,
         token,
-        embedded: Boolean(embedOtt),
+        embedded,
         // The socket carries its token on the handshake, so an identity change
         // only reaches it by opening a new connection — or, on logout, by
         // dropping the one still running as the user who just left.
@@ -148,17 +133,34 @@ 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.
-    // Not in a frame: a stored token there belongs to an earlier visitor, not to
-    // this session, which only the exchange below can produce.
-    if (typeof window !== "undefined" && !embedOtt) {
+    // Skipped in a frame: the session comes from the exchange below.
+    if (typeof window !== "undefined" && !embedded) {
         const accessToken = token || getAccessToken();
         if (accessToken) {
             userAuthModule.setToken(accessToken);
         }
     }
+    // Live token for every module; outside a frame it still falls back to storage.
+    const getToken = () => { var _a; return (_a = userAuthModule.getToken()) !== null && _a !== void 0 ? _a : (embedded ? null : getAccessToken()); };
+    const socketConfig = {
+        serverUrl,
+        mountPath: "/ws-user-apps/socket.io/",
+        transports: ["websocket"],
+        appId,
+        getToken,
+    };
+    const getSocket = () => {
+        if (!socket) {
+            socket = RoomsSocket({ config: socketConfig });
+        }
+        return socket;
+    };
+    // The exchange belongs to the frame, not to one client: the token is off the
+    // URL after the first `createClient`, so a second one in the same document
+    // joins the session already being negotiated rather than going anonymous.
     const session = embedOtt
-        ? exchangeEmbedToken({ serverUrl, appId, ott: embedOtt })
-        : null;
+        ? frameSession(appId, () => exchangeEmbedToken({ serverUrl, appId, ott: embedOtt }))
+        : frameSession(appId);
     // Settles once the exchanged session is applied (memory only); at once
     // otherwise. Never rejects: every request waits on it, so a failure here
     // must not turn into a rejection on each of them.
@@ -180,6 +182,21 @@ export function createClient(config) {
             console.error("Base44: applying the embedded session failed:", e);
         })
         : Promise.resolve();
+    // Everything that can wait for the session does. `aiGateway.connection()`
+    // and the agents connect URLs cannot: they hand back a value, not a promise,
+    // and a value read now would stay wrong after the session arrives. They warn
+    // instead of failing quietly.
+    let warnedEarlyRead = false;
+    const getTokenNow = () => {
+        const sessionToken = getToken();
+        if (sessionToken === null && session && !warnedEarlyRead) {
+            warnedEarlyRead = true;
+            console.warn("Base44: read a token before the embedded session was ready, so it is " +
+                "empty. Await a call such as base44.auth.me() before building a " +
+                "client or a URL that keeps the token.");
+        }
+        return sessionToken;
+    };
     if (session) {
         // Requests issued during the exchange wait for it. Registered after createAxiosClient's
         // interceptors so it runs first and the anonymous-visitor header sees the Authorization.
@@ -247,11 +264,13 @@ export function createClient(config) {
             getSocket,
             appId,
             serverUrl,
-            // Read synchronously, unlike everything else: these build a URL rather
-            // than issue a request, so during the exchange they see no token.
-            getToken,
+            getToken: getTokenNow,
+        }),
+        aiGateway: createAiGatewayModule({
+            serverUrl,
+            getToken: getTokenNow,
+            appId,
         }),
-        aiGateway: createAiGatewayModule({ serverUrl, getToken, appId }),
         appLogs: createAppLogsModule(axiosClient, appId),
         app: createAppModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
@@ -299,7 +318,7 @@ export function createClient(config) {
             // The user's token, as on the user-scoped module: the only thing this is
             // read for is the `?token=` on a channel URL handed to that user, which
             // the app's service credential must never end up in.
-            getToken,
+            getToken: getTokenNow,
         }),
         aiGateway: createAiGatewayModule({
             serverUrl,

package/dist/modules/actors.d.ts

@@ -11,9 +11,8 @@ interface ActorsConfig {
     appId: string;
     /** 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. Awaited per dial, so a session still being
-     * exchanged is in hand before the URL is built. */
-    getAuthToken(): Promise<string | null | undefined>;
+     * anonymous connects omit it. */
+    getAuthToken(): string | null | undefined | Promise<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;

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

@@ -161,7 +161,7 @@ export interface AgentsModuleConfig {
     /** Server URL */
     serverUrl?: string;
     /** Returns the current authentication token, if any */
-    getToken: () => string | null;
+    getToken: () => string | null | undefined;
 }
 /**
  * Agents module for managing AI agent conversations.
@@ -360,9 +360,7 @@ export interface AgentsModule {
      * Gets WhatsApp connection URL for an agent.
      *
      * Generates a URL that users can use to connect with the agent through WhatsApp.
-     * The URL includes authentication if a token is available. In an app a
-     * platform has embedded, that is only once the session has been exchanged —
-     * await a call such as `base44.auth.me()` before building the URL.
+     * The URL includes authentication if a token is available.
      *
      * @param agentName - The name of the agent.
      * @returns WhatsApp connection URL.
@@ -380,9 +378,7 @@ export interface AgentsModule {
      * Gets Telegram connection URL for an agent.
      *
      * Generates a URL that users can use to connect with the agent through Telegram.
-     * The URL includes authentication if a token is available. In an app a
-     * platform has embedded, that is only once the session has been exchanged —
-     * await a call such as `base44.auth.me()` before building the URL. When the user opens
+     * The URL includes authentication if a token is available. When the user opens
      * this URL, they are redirected to the agent's Telegram bot with an activation
      * code that securely links their account.
      *

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

@@ -98,11 +98,16 @@ export interface AuthModuleOptions {
      * which is how the server-side SDK reports a token it never sets explicitly.
      */
     token?: string;
-    /** Whether a host platform embedded this client in a frame. */
+    /**
+     * Whether this client runs embedded in a host platform's frame, where a
+     * session is minted by the platform and cannot be renewed by a login redirect.
+     */
     embedded?: boolean;
     /**
-     * Called when the identity changes: `true` on `setToken`, `false` on
-     * `logout`. Lets the client redial the socket, which holds its own copy.
+     * Called whenever the identity changes: `true` when a token is set, `false`
+     * on logout. Lets the client reach what holds its own copy of the identity —
+     * the realtime socket, which carries a token on the handshake and so has to
+     * open a new connection to pick one up, or drop the one it has.
      */
     onSessionChange?: (hasSession: boolean) => void;
 }
@@ -187,13 +192,13 @@ export interface AuthModule {
      */
     redirectToLogin(nextUrl: string): void;
     /**
-     * Whether a host platform embedded this app and signed its user in.
+     * Whether the app is running embedded in a host platform.
      *
-     * Only the platform can renew that session, so {@linkcode AuthModule.redirectToLogin | redirectToLogin()} and {@linkcode AuthModule.logout | logout()} show a "session ended" notice rather than a login page. Use this to render your own notice, or to hide sign-in controls that cannot work in the frame.
+     * A platform embeds an app in an iframe and signs its user in by minting a one-time token onto the frame's URL; the SDK trades it for a session as the client is created. That session is held in memory only and can be renewed only by the platform, so when it ends there is no login page to send the user to — {@linkcode AuthModule.redirectToLogin | redirectToLogin()} and {@linkcode AuthModule.logout | logout()} show a "session ended" notice instead. Use this to render your own notice or to hide sign-in and sign-out controls that cannot work inside the frame.
      *
-     * The session lives in memory, so a reload inside the frame ends it and returns `false` here. Prefer client-side navigation.
+     * Because the session lives in memory, it does not survive a full page load inside the frame: routing within the app keeps it, while a reload or a real navigation ends it and the platform has to embed the app again — and this returns `false` on that load, since nothing about it says it was embedded. Prefer client-side navigation in an embedded app.
      *
-     * @returns `true` when a host platform embedded this app.
+     * @returns `true` when the app was embedded by a host platform, `false` otherwise.
      *
      * @example
      * ```typescript
@@ -564,6 +569,9 @@ export interface InternalAuthModule extends AuthModule {
      * could not succeed without a session, not to decide that one is valid.
      */
     hasToken(): boolean;
-    /** The token currently set on the client, or `null`. */
+    /**
+     * The access token currently set on the client, or `null` when there is none.
+     * Follows {@linkcode AuthModule.setToken | setToken} and {@linkcode AuthModule.logout | logout}.
+     */
     getToken(): string | null;
 }

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

@@ -7,12 +7,6 @@
  * grant (RFC 8693), and keeps the result in memory only — never in storage — so
  * the session lives and dies with the frame.
  *
- * Taking the token off the URL is unconditional — a one-time token must not be
- * left in the address bar, in history, or in a shared link — but it is only
- * reported back inside a frame, the only place one is redeemed. It is gone once
- * the first client has taken it, so the session belongs to that client — an app
- * creates one.
- *
  * The exchange endpoint is rate limited per app, and its limiter refuses before
  * the one-time token is redeemed — so a 429 leaves the token still valid and is
  * worth retrying once.
@@ -21,6 +15,8 @@
  */
 export declare const EMBED_TOKEN_PARAM = "ott";
 /** @internal */
+export declare function frameSession(appId: string, start?: () => Promise<string | null>): Promise<string | null> | null;
+/** @internal */
 export declare function takeEmbedTokenFromUrl(): string | null;
 /** @internal */
 export declare function isFramed(): boolean;

package/dist/utils/embed-session.js

@@ -7,12 +7,6 @@
  * grant (RFC 8693), and keeps the result in memory only — never in storage — so
  * the session lives and dies with the frame.
  *
- * Taking the token off the URL is unconditional — a one-time token must not be
- * left in the address bar, in history, or in a shared link — but it is only
- * reported back inside a frame, the only place one is redeemed. It is gone once
- * the first client has taken it, so the session belongs to that client — an app
- * creates one.
- *
  * The exchange endpoint is rate limited per app, and its limiter refuses before
  * the one-time token is redeemed — so a 429 leaves the token still valid and is
  * worth retrying once.
@@ -26,6 +20,20 @@ const RATE_LIMITED = 429;
 const RATE_LIMIT_RETRY_MS = 1000;
 const EXCHANGE_TIMEOUT_MS = 15000;
 const SESSION_ENDED_ELEMENT_ID = "base44-embed-session-ended";
+const FRAME_SESSIONS_KEY = "__base44EmbedSessions";
+/** @internal */
+export function frameSession(appId, start) {
+    var _a, _b;
+    var _c;
+    if (typeof window === "undefined") {
+        return start ? start() : null;
+    }
+    const sessions = ((_a = (_c = window)[FRAME_SESSIONS_KEY]) !== null && _a !== void 0 ? _a : (_c[FRAME_SESSIONS_KEY] = {}));
+    if (!sessions[appId] && start) {
+        sessions[appId] = start();
+    }
+    return (_b = sessions[appId]) !== null && _b !== void 0 ? _b : null;
+}
 /** @internal */
 export function takeEmbedTokenFromUrl() {
     if (typeof window === "undefined" || !window.location) {
@@ -44,11 +52,16 @@ export function takeEmbedTokenFromUrl() {
     catch (e) {
         console.error("Error retrieving embed token from URL:", e);
     }
-    return isFramed() ? ott : null;
+    return ott;
 }
 /** @internal */
 export function isFramed() {
-    return typeof window !== "undefined" && window.self !== window.top;
+    try {
+        return typeof window !== "undefined" && window.self !== window.top;
+    }
+    catch (_a) {
+        return true;
+    }
 }
 /** @internal */
 export async function exchangeEmbedToken({ serverUrl, appId, ott, fetchImpl = fetch, }) {

package/dist/utils/fetch-with-auth.d.ts

@@ -40,5 +40,6 @@ export declare function createFetchWithAuth({ axios, serviceRoleAxios, appId, se
     serverUrl: string;
     functionsVersion?: string;
     platformHeaders?: Record<string, string>;
+    /** Resolves once the client's session is settled. */
     waitForAuth?: () => Promise<void>;
 }): (path: string, init?: FetchWithAuthInit) => Promise<Response>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.282.8a4c1c0",
+  "version": "0.8.48-pr.282.8f60b80",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",