@base44-preview/sdk 0.8.48-pr.282.6ea0687 → 0.8.48-pr.282.7b5ff6d

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, 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";
@@ -59,7 +59,9 @@ export function createClient(config) {
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
     const embedOtt = takeEmbedTokenFromUrl();
-    // A declaration, not a const: this block sits above the auth module.
+    // 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());
@@ -80,8 +82,7 @@ export function createClient(config) {
         }
         return socket;
     };
-    // Apps pass getAccessToken() in as `token`, which in a frame is the OTT —
-    // what the exchange trades for a session, never a bearer itself.
+    // In a frame the caller's token is the OTT itself, which is not a session.
     const token = embedOtt ? undefined : config.token;
     const headers = {
         ...optionalHeaders,
@@ -136,26 +137,32 @@ export function createClient(config) {
         serverUrl,
         token,
         embedded: Boolean(embedOtt),
-        // The socket carries its token on the handshake, so it can only pick a
-        // new one up by redialling — or, on logout, by dropping what it has.
+        // 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.
         onSessionChange: (hasSession) => hasSession ? socket === null || socket === void 0 ? void 0 : socket.reconnect() : socket === null || socket === void 0 ? void 0 : socket.disconnect(),
     });
     // Apply the access token before any module that may issue authenticated
     // 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 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) {
         const accessToken = token || getAccessToken();
         if (accessToken) {
             userAuthModule.setToken(accessToken);
         }
     }
+    // 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;
-    // Never rejects: every request waits on it, so one failure here must not
-    // become a rejection on each of them.
+        ? 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.
     const authReady = session
         ? session
             .then((sessionToken) => {
@@ -164,6 +171,8 @@ export function createClient(config) {
                 userAuthModule.setToken(sessionToken, false);
                 return;
             }
+            // The app is about to run anonymous. Say why, once, instead of
+            // leaving only the 401s that follow.
             const error = new Error("Base44: the embed token was refused, so this app is not signed in.");
             console.error(error.message);
             (_a = options === null || options === void 0 ? void 0 : options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error);
@@ -173,8 +182,8 @@ export function createClient(config) {
         })
         : Promise.resolve();
     if (session) {
-        // Registered after createAxiosClient's so it runs first (axios unshifts),
-        // letting the anonymous-visitor header see the Authorization we just set.
+        // 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.
         for (const client of [axiosClient, functionsAxiosClient]) {
             client.interceptors.request.use(async (requestConfig) => {
                 await authReady;
@@ -239,7 +248,8 @@ export function createClient(config) {
             getSocket,
             appId,
             serverUrl,
-            // Sync, unlike everything else: these return a URL, not a promise.
+            // Read synchronously, unlike everything else: these build a URL rather
+            // than issue a request, so during the exchange they see no token.
             getToken,
         }),
         aiGateway: createAiGatewayModule({ serverUrl, getToken, appId }),
@@ -287,8 +297,9 @@ export function createClient(config) {
             getSocket,
             appId,
             serverUrl,
-            // The user's token, deliberately: this is read only for the `?token=` on
-            // a channel URL handed to that user. Never the service credential.
+            // 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,
         }),
         aiGateway: createAiGatewayModule({

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

@@ -9,9 +9,7 @@
  *
  * 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.
+ * reported back inside a frame, the only place one is redeemed.
  *
  * 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
@@ -21,6 +19,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

@@ -9,9 +9,7 @@
  *
  * 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.
+ * reported back inside a frame, the only place one is redeemed.
  *
  * 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
@@ -26,6 +24,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) {

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/dist/utils/socket-utils.d.ts

@@ -4,6 +4,7 @@ export interface RoomsSocketConfig {
     mountPath: string;
     transports: string[];
     appId: string;
+    /** Asked on every connect, so the socket always carries the current session. */
     getToken: () => string | null;
 }
 export type TSocketRoom = string;

package/package.json

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