@base44-preview/sdk 0.8.44-pr.267.4549331 → 0.8.44-pr.270.91862eb

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.
  *
@@ -52,7 +52,7 @@ import { createActorsModule, resolveActorsHost } from "./modules/actors.js";
  */
 export function createClient(config) {
     var _a, _b, _c;
-    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
+    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, analytics: analyticsOptions, functionsVersion, headers: optionalHeaders, } = config;
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
     const socketConfig = {
@@ -110,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,
@@ -127,11 +136,26 @@ export function createClient(config) {
     }
     const actorsModule = createActorsModule({
         appId,
-        // serverUrl is often relative/empty (same-origin app); PartySocket needs an
-        // absolute host, so fall back to the page origin.
+        // 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: () => 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({
@@ -169,6 +193,7 @@ export function createClient(config) {
             serverUrl,
             appId,
             userAuthModule,
+            options: analyticsOptions,
         }),
         actors: actorsModule.module,
         cleanup: () => {

package/dist/client.types.d.ts

@@ -7,7 +7,7 @@ import type { FunctionsModule } from "./modules/functions.types.js";
 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 { AnalyticsModule, CreateClientAnalyticsOptions } from "./modules/analytics.types.js";
 import type { ActorsModule } from "./modules/actors.types.js";
 /**
  * Options for creating a Base44 client.
@@ -15,8 +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.
+     *
+     * 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.
@@ -70,6 +82,22 @@ export interface CreateClientConfig {
      * @internal
      */
     headers?: Record<string, string>;
+    /**
+     * Analytics configuration for this client.
+     *
+     * By default, analytics is enabled and starts as soon as the client is created: a persistent visitor ID is stored in `localStorage` and automatic events are sent.
+     *
+     * Set `consent: "pending"` to keep analytics dormant until the visitor makes a consent decision, then call {@linkcode AnalyticsModule.optIn | analytics.optIn()} or {@linkcode AnalyticsModule.optOut | analytics.optOut()}. Set `enabled: false` to turn the analytics module off entirely.
+     *
+     * @example
+     * ```typescript
+     * const base44 = createClient({
+     *   appId: 'my-app-id',
+     *   analytics: { consent: 'pending' }
+     * });
+     * ```
+     */
+    analytics?: CreateClientAnalyticsOptions;
     /**
      * Additional client options.
      */

package/dist/modules/actors.d.ts

@@ -1,21 +1,47 @@
 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;
-    /** Current user access token, if authenticated. Rides the WS query so the
-     * platform proxy can authenticate the connection; anonymous connects omit it. */
+    /** 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 PartySocket dials (it strips the scheme and connects wss, ws
+    /** 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 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).
+ * 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,8 +1,32 @@
-import PartySocket from "partysocket";
-// 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;
+// 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 live connection to an actor instance. Only obtainable from
  * {@link ActorRef.connect}, so `subscribe`/`send` are always valid — the socket
@@ -14,23 +38,54 @@ class Connection {
         this.onClose = onClose;
         this.listeners = new Set();
         this.heartbeat = null;
+        this.closed = false;
         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 } : {}),
-                };
-            },
-        });
+        // 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.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)}`;
+                }
+                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;
+                }
+            }
+            // 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 lastMsg = Date.now();
         const bumpAlive = () => { lastMsg = Date.now(); };
@@ -53,7 +108,11 @@ class Connection {
         this.heartbeat = setInterval(() => {
             if (Date.now() - lastMsg > DEAD_MS) {
                 bumpAlive(); // avoid a reconnect storm while the new socket comes up
-                ws.reconnect();
+                // 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 {
@@ -73,9 +132,15 @@ class Connection {
         };
     }
     send(data) {
+        // after close() the socket would buffer forever (unbounded enqueue)
+        if (this.closed)
+            return;
         this.ws.send(JSON.stringify(data));
     }
     close() {
+        if (this.closed)
+            return;
+        this.closed = true;
         if (this.heartbeat) {
             clearInterval(this.heartbeat);
             this.heartbeat = null;
@@ -104,10 +169,38 @@ function makeActorRef(actorName, instanceId, config, connections) {
     };
 }
 /**
- * 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).
+ * 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;

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

@@ -56,9 +56,14 @@ export interface Connection<N extends string = string> {
     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 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;
 }
 /**
@@ -66,7 +71,15 @@ export interface Connection<N extends string = string> {
  * {@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. */
+    /**
+     * 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.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
+import { TrackEventParams, AnalyticsModuleOptions, AnalyticsConsentStatus, CreateClientAnalyticsOptions } from "./analytics.types";
 import type { InternalAuthModule } from "./auth.types";
 export declare const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
 export declare const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_event__";
@@ -11,9 +11,20 @@ export interface AnalyticsModuleArgs {
     serverUrl: string;
     appId: string;
     userAuthModule: InternalAuthModule;
+    options?: CreateClientAnalyticsOptions;
 }
-export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, }: AnalyticsModuleArgs) => {
+/**
+ * The effective analytics consent status. `"granted"` when no client set one
+ * explicitly, preserving the legacy always-on behavior.
+ *
+ * @internal
+ */
+export declare function getAnalyticsConsentStatus(): AnalyticsConsentStatus;
+export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, options, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
+    optIn: () => void;
+    optOut: () => void;
+    getConsentStatus: typeof getAnalyticsConsentStatus;
     cleanup: () => void;
 };
 /**

package/dist/modules/analytics.js

@@ -25,22 +25,84 @@ 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,
+    // Consent status shared by every client on the page. `null` means no
+    // client set one explicitly, which keeps the legacy behavior (granted).
+    consent: null,
     config: {
         ...defaultConfiguration,
         ...getAnalyticsConfigFromUrlParams(),
     },
 }));
-export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, }) => {
+// Lower ranks are more restrictive. Used to merge the consent status of
+// multiple clients created on the same page: the shared state (and therefore
+// the shared persistent id) can only honor one status, so the most
+// restrictive explicitly-configured one wins.
+const CONSENT_RESTRICTIVENESS = {
+    denied: 0,
+    pending: 1,
+    granted: 2,
+};
+function applyInitialConsent(consent) {
+    if (!consent)
+        return;
+    const current = analyticsSharedState.consent;
+    if (current === null ||
+        CONSENT_RESTRICTIVENESS[consent] < CONSENT_RESTRICTIVENESS[current]) {
+        analyticsSharedState.consent = consent;
+    }
+}
+/**
+ * The effective analytics consent status. `"granted"` when no client set one
+ * explicitly, preserving the legacy always-on behavior.
+ *
+ * @internal
+ */
+export function getAnalyticsConsentStatus() {
     var _a;
+    return (_a = analyticsSharedState.consent) !== null && _a !== void 0 ? _a : "granted";
+}
+function clearPersistedAnalyticsSessionId() {
+    if (typeof window === "undefined")
+        return;
+    try {
+        localStorage.removeItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY);
+    }
+    catch (_a) {
+        // Storage unavailable — nothing was persisted, so nothing to clear.
+    }
+}
+export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, options, }) => {
+    var _a;
+    // Consent gates more than this module: getAnalyticsSessionId() also backs
+    // the anonymous-id HTTP header and the socket handshake, so the client's
+    // consent choice must be recorded even when the early returns below make
+    // the module itself a no-op.
+    applyInitialConsent(options === null || options === void 0 ? void 0 : options.consent);
     // prevent overflow of events //
     const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
     // Disable analytics on React Native. It defines `window` but not `document`,
     // so the per-callsite `typeof window` guards below aren't enough to keep it
     // from touching `document` (e.g. `document.referrer` on init). Node/SSR is
     // still handled by those `window` guards, so this doesn't affect it.
-    if (!((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled) || isReactNative) {
+    if (!((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled) ||
+        (options === null || options === void 0 ? void 0 : options.enabled) === false ||
+        isReactNative) {
         return {
             track: () => { },
+            // Consent still matters with the event pipeline off: it decides whether
+            // the persistent id may back the anonymous-id header and socket
+            // handshake, so opting in/out has to work here too.
+            optIn: () => {
+                analyticsSharedState.consent = "granted";
+            },
+            optOut: () => {
+                analyticsSharedState.consent = "denied";
+                clearPersistedAnalyticsSessionId();
+            },
+            getConsentStatus: getAnalyticsConsentStatus,
             cleanup: () => { },
         };
     }
@@ -87,6 +149,12 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         });
     };
     const track = (params) => {
+        const consent = getAnalyticsConsentStatus();
+        // Denied: drop. Pending: buffer in memory (no network, no storage) so the
+        // events can be delivered if the visitor opts in later.
+        if (consent === "denied") {
+            return;
+        }
         if (analyticsSharedState.requestsQueue.length >= maxQueueSize) {
             return;
         }
@@ -95,7 +163,9 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             ...params,
             ...intrinsicData,
         });
-        startProcessing();
+        if (consent === "granted") {
+            startProcessing();
+        }
     };
     const onDocVisible = () => {
         startAnalyticsProcessor(flush, {
@@ -123,25 +193,66 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             onDocVisible();
         }
     };
-    const cleanup = () => {
+    // Everything with a side effect beyond this module — the persistent id,
+    // automatic events, timers, network — starts in activate(), so a client
+    // created with consent "pending" or "denied" stays fully dormant until the
+    // visitor opts in.
+    let isActive = false;
+    const activate = () => {
+        if (isActive)
+            return;
+        isActive = true;
+        // start the flusing process ///
+        startProcessing();
+        // start the heart beat processor //
+        clearHeartBeatProcessor = startHeartBeatProcessor(track);
+        // track the referrer event //
+        trackInitializationEvent(track);
+        // start the visibility change listener //
+        if (typeof window !== "undefined") {
+            window.addEventListener("visibilitychange", onVisibilityChange);
+        }
+    };
+    const deactivate = () => {
+        if (!isActive)
+            return;
+        isActive = false;
         stopAnalyticsProcessor();
         clearHeartBeatProcessor === null || clearHeartBeatProcessor === void 0 ? void 0 : clearHeartBeatProcessor();
+        clearHeartBeatProcessor = undefined;
         if (typeof window !== "undefined") {
             window.removeEventListener("visibilitychange", onVisibilityChange);
         }
     };
-    // start the flusing process ///
-    startProcessing();
-    // start the heart beat processor //
-    clearHeartBeatProcessor = startHeartBeatProcessor(track);
-    // track the referrer event //
-    trackInitializationEvent(track);
-    // start the visibility change listener //
-    if (typeof window !== "undefined") {
-        window.addEventListener("visibilitychange", onVisibilityChange);
+    const optIn = () => {
+        analyticsSharedState.consent = "granted";
+        // Persist the id now rather than on the next event: this adopts the
+        // ephemeral pre-consent id (see getAnalyticsSessionId), keeping the
+        // visitor's identity continuous across the consent grant.
+        getAnalyticsSessionId();
+        activate();
+    };
+    const optOut = () => {
+        analyticsSharedState.consent = "denied";
+        deactivate();
+        // Drop anything buffered while consent was pending, and forget the
+        // identity: both the persisted id and the memoized session context.
+        analyticsSharedState.requestsQueue.length = 0;
+        analyticsSharedState.sessionStartTime = null;
+        resetAnalyticsSessionContext();
+        clearPersistedAnalyticsSessionId();
+    };
+    const cleanup = () => {
+        deactivate();
+    };
+    if (getAnalyticsConsentStatus() === "granted") {
+        activate();
     }
     return {
         track,
+        optIn,
+        optOut,
+        getConsentStatus: getAnalyticsConsentStatus,
         cleanup,
     };
 };
@@ -216,9 +327,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,20 +415,36 @@ 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() {
+    var _a;
     if (typeof window === "undefined") {
-        return generateUuid();
+        return getFallbackSessionId();
+    }
+    // Until consent is granted, never read or write the persistent id — hand out
+    // a per-page-load ephemeral id instead. The anonymous-id HTTP header and the
+    // socket handshake resolve their id through here too, so this single gate
+    // covers every place a persistent identifier could be minted pre-consent.
+    if (getAnalyticsConsentStatus() !== "granted") {
+        return getFallbackSessionId();
     }
     try {
         const sessionId = localStorage.getItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY);
         if (!sessionId) {
-            const newSessionId = generateUuid();
+            // Adopt the ephemeral pre-consent id when one was handed out, so the
+            // visitor keeps a single identity across the consent grant.
+            const newSessionId = (_a = analyticsSharedState.fallbackSessionId) !== null && _a !== void 0 ? _a : generateUuid();
             localStorage.setItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY, newSessionId);
             return newSessionId;
         }
         return sessionId;
     }
-    catch (_a) {
-        return generateUuid();
+    catch (_b) {
+        return getFallbackSessionId();
     }
 }

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

@@ -67,6 +67,41 @@ export type AnalyticsModuleOptions = {
     batchSize?: number;
     heartBeatInterval?: number;
 };
+/**
+ * Consent status for analytics tracking.
+ *
+ * - `"granted"`: Analytics is fully active. The SDK persists a visitor ID in `localStorage`, sends automatic events, and delivers tracked events to the server.
+ * - `"pending"`: Analytics is dormant while waiting for a consent decision. No visitor ID is persisted and nothing is sent to the server. Events passed to {@linkcode AnalyticsModule.track | track()} are buffered in memory and delivered if consent is later granted with {@linkcode AnalyticsModule.optIn | optIn()}.
+ * - `"denied"`: Analytics is off. No visitor ID is persisted, nothing is sent to the server, and tracked events are discarded.
+ */
+export type AnalyticsConsentStatus = "granted" | "denied" | "pending";
+/**
+ * Analytics configuration for {@linkcode createClient | createClient()}.
+ *
+ * Controls whether analytics runs and whether it waits for a consent decision before persisting a visitor ID or sending events.
+ */
+export type CreateClientAnalyticsOptions = {
+    /**
+     * Whether the analytics module is enabled.
+     *
+     * When `false`, {@linkcode AnalyticsModule.track | track()} is a no-op and no automatic events are sent, regardless of consent status.
+     *
+     * @defaultValue `true`
+     */
+    enabled?: boolean;
+    /**
+     * Initial consent status for analytics.
+     *
+     * Defaults to `"granted"`, which preserves the SDK's original behavior: analytics starts as soon as the client is created.
+     *
+     * Set to `"pending"` when your app needs a consent decision (for example, from a cookie banner) before tracking starts. The client is still created immediately, but analytics stays dormant — no visitor ID is written to `localStorage`, no automatic events fire, and tracked events are buffered in memory. Call {@linkcode AnalyticsModule.optIn | optIn()} once consent is granted, or {@linkcode AnalyticsModule.optOut | optOut()} if it's refused.
+     *
+     * When multiple clients are created on the same page, the most restrictive explicitly-configured consent status wins (`"denied"` over `"pending"` over `"granted"`).
+     *
+     * @defaultValue `"granted"`
+     */
+    consent?: AnalyticsConsentStatus;
+};
 /**
  * Analytics module for tracking custom events in your app.
  *
@@ -81,6 +116,10 @@ export type AnalyticsModuleOptions = {
  * - Choose clear, descriptive event names in snake_case like `signup_button_click` or `purchase_completed` rather than generic names like `click`.
  * - Include relevant context in your properties such as identifiers like `product_id`, measurements like `price`, and flags like `is_first_purchase`.
  *
+ * ## Consent
+ *
+ * Apps that need a consent decision (for example, from a cookie banner) before tracking starts can create the client with `analytics: { consent: 'pending' }` and then call {@linkcode optIn | optIn()} or {@linkcode optOut | optOut()} once the visitor decides. See {@linkcode CreateClientAnalyticsOptions} for details.
+ *
  * ## Authentication Modes
  *
  * This module is only available in user authentication mode (`base44.analytics`).
@@ -119,4 +158,56 @@ export interface AnalyticsModule {
      * ```
      */
     track(params: TrackEventParams): void;
+    /**
+     * Grants analytics consent and activates tracking.
+     *
+     * Use this after the visitor accepts analytics in your consent flow (for example, a cookie banner). It sets the consent status to `"granted"`, persists the visitor ID, starts automatic events, and delivers any events buffered while consent was `"pending"`.
+     *
+     * The visitor keeps a single identity across the consent grant: the temporary in-memory ID used before consent is adopted as the persistent ID.
+     *
+     * Calling this when consent is already `"granted"` has no effect.
+     *
+     * @example
+     * ```typescript
+     * // Create the client without tracking, then activate it once the
+     * // visitor accepts analytics in your consent banner.
+     * const base44 = createClient({
+     *   appId: 'my-app-id',
+     *   analytics: { consent: 'pending' }
+     * });
+     *
+     * onConsentBannerAccept(() => {
+     *   base44.analytics.optIn();
+     * });
+     * ```
+     */
+    optIn(): void;
+    /**
+     * Revokes analytics consent and deactivates tracking.
+     *
+     * Use this when the visitor declines analytics in your consent flow, or withdraws consent later. It sets the consent status to `"denied"`, stops automatic events, discards any buffered events, and removes the persistent visitor ID from `localStorage`.
+     *
+     * Tracking can be re-enabled later with {@linkcode optIn | optIn()}.
+     *
+     * @example
+     * ```typescript
+     * onConsentBannerDecline(() => {
+     *   base44.analytics.optOut();
+     * });
+     * ```
+     */
+    optOut(): void;
+    /**
+     * Gets the current analytics consent status.
+     *
+     * @returns The current consent status: `"granted"`, `"denied"`, or `"pending"`.
+     *
+     * @example
+     * ```typescript
+     * if (base44.analytics.getConsentStatus() === 'pending') {
+     *   showConsentBanner();
+     * }
+     * ```
+     */
+    getConsentStatus(): AnalyticsConsentStatus;
 }

package/dist/utils/axios-client.js

@@ -132,8 +132,10 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.44-pr.267.4549331",
+  "version": "0.8.44-pr.270.91862eb",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",