@base44-preview/sdk 0.8.48-pr.282.6dd99a0 → 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";
@@ -82,9 +82,7 @@ export function createClient(config) {
         }
         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.
+    // 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,
@@ -156,9 +154,12 @@ export function createClient(config) {
             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;
+        ? 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.

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.6dd99a0",
+  "version": "0.8.48-pr.282.7b5ff6d",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",