@base44-preview/sdk 0.8.48-pr.280.cc2ee4a → 0.8.48-pr.280.cd0dea6

package/dist/client.js

@@ -16,6 +16,7 @@ import { RoomsSocket } from "./utils/socket-utils.js";
 import { createAnalyticsModule } from "./modules/analytics.js";
 import { createExperimentsModule } from "./modules/experiments.js";
 import { createExposureTracker } from "./modules/experiment-exposures.js";
+import { EXPERIMENTS_CONTEXT_HEADER, getBrowserExperimentsContext, readExperimentsContext } from "./modules/experiments-context.js";
 import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
@@ -55,10 +56,11 @@ import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
  * ```
  */
 export function createClient(config) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     const { serverUrl = "https://base44.app", appId, analytics, 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 : "";
+    const experimentsContext = (_a = config.experiments) !== null && _a !== void 0 ? _a : getBrowserExperimentsContext(appId);
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -75,9 +77,14 @@ export function createClient(config) {
         }
         return socket;
     };
+    const { [EXPERIMENTS_CONTEXT_HEADER]: inheritedExperimentsContext, ...requestHeaders } = optionalHeaders !== null && optionalHeaders !== void 0 ? optionalHeaders : {};
     const headers = {
-        ...optionalHeaders,
+        ...requestHeaders,
         "X-App-Id": String(appId),
+        ...(experimentsContext ? {
+            "Base44-Visitor-Id": experimentsContext.identity.visitorId,
+            "Base44-Experiment-Preview": JSON.stringify((_b = experimentsContext.preview) !== null && _b !== void 0 ? _b : {}),
+        } : {}),
     };
     const functionHeaders = functionsVersion
         ? {
@@ -123,13 +130,18 @@ export function createClient(config) {
         baseURL: `${serverUrl}/api`,
         headers,
     });
+    const exposureTracker = createExposureTracker({
+        axiosClient,
+        appId,
+        enabled: (_c = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _c !== void 0 ? _c : true,
+        source: typeof window === "undefined" ? "backend" : "browser",
+        pageUrl: experimentsContext === null || experimentsContext === void 0 ? void 0 : experimentsContext.pageUrl,
+    });
     const experiments = createExperimentsModule({
         getAuth: () => userAuthModule,
-        trackExposure: createExposureTracker({
-            axiosClient,
-            appId,
-            enabled: (_a = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _a !== void 0 ? _a : true,
-        }).track,
+        trackExposure: exposureTracker.track,
+        flushExposures: exposureTracker.flush,
+        context: experimentsContext,
     });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
         appBaseUrl: normalizedAppBaseUrl,
@@ -147,11 +159,19 @@ export function createClient(config) {
             userAuthModule.setToken(accessToken);
         }
     }
+    if (experimentsContext) {
+        const { userId, status } = experimentsContext.identity;
+        // The document's cookie identity may differ from this client's localStorage token.
+        const needsClientIdentity = typeof window !== "undefined" && userAuthModule.hasToken() &&
+            experimentsContext.config.experiments.some((experiment) => experiment.assign_by === "user");
+        experiments.onAuthStateChange(status === "pending" || needsClientIdentity ? { status: "pending" } :
+            userId ? { status: "authenticated", userId } : { status: "anonymous" });
+    }
     const actorsModule = createActorsModule({
         appId,
         // 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" ? (_b = window.location) === null || _b === void 0 ? void 0 : _b.origin : undefined),
+        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_d = window.location) === null || _d === void 0 ? void 0 : _d.origin : undefined),
         functionsVersion,
         getAuthToken: () => token || getAccessToken(),
         mintConnectionToken: async (actorName, room, connectionId) => {
@@ -190,7 +210,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_c = functionsAxiosClient.defaults) === null || _c === void 0 ? void 0 : _c.baseURL,
+            baseURL: (_e = functionsAxiosClient.defaults) === null || _e === void 0 ? void 0 : _e.baseURL,
         }),
         agents: createAgentsModule({
             axios: axiosClient,
@@ -208,7 +228,9 @@ export function createClient(config) {
             serverUrl,
             appId,
             userAuthModule,
-            enabled: (_d = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _d !== void 0 ? _d : true,
+            enabled: (_f = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _f !== void 0 ? _f : true,
+            getVisitorId: experiments.visitorId,
+            experimentsContext,
         }),
         actors: actorsModule.module,
         cleanup: () => {
@@ -238,7 +260,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_e = serviceRoleFunctionsAxiosClient.defaults) === null || _e === void 0 ? void 0 : _e.baseURL,
+            baseURL: (_g = serviceRoleFunctionsAxiosClient.defaults) === null || _g === void 0 ? void 0 : _g.baseURL,
         }),
         agents: createAgentsModule({
             axios: serviceRoleAxiosClient,
@@ -281,7 +303,10 @@ export function createClient(config) {
             appId: String(appId),
             serverUrl,
             functionsVersion,
-            platformHeaders: optionalHeaders,
+            platformHeaders: {
+                ...headers,
+                ...(inheritedExperimentsContext ? { [EXPERIMENTS_CONTEXT_HEADER]: inheritedExperimentsContext } : {}),
+            },
         }),
         /**
          * Sets a new authentication token for all subsequent requests.
@@ -433,6 +458,10 @@ export function createClientFromRequest(request) {
     }
     // Prepare additional headers to propagate
     const additionalHeaders = {};
+    const encodedExperiments = request.headers.get(EXPERIMENTS_CONTEXT_HEADER);
+    const experimentsContext = readExperimentsContext(encodedExperiments, appId);
+    if (experimentsContext && encodedExperiments)
+        additionalHeaders[EXPERIMENTS_CONTEXT_HEADER] = encodedExperiments;
     if (stateHeader) {
         additionalHeaders["Base44-State"] = stateHeader;
     }
@@ -453,5 +482,6 @@ export function createClientFromRequest(request) {
         serviceToken: serviceRoleToken,
         functionsVersion: functionsVersion !== null && functionsVersion !== void 0 ? functionsVersion : undefined,
         headers: additionalHeaders,
+        experiments: experimentsContext ? { ...experimentsContext, pageUrl: request.url ? new URL(request.url).pathname : "/" } : undefined,
     });
 }

package/dist/client.types.d.ts

@@ -10,6 +10,7 @@ import type { AppLogsModule } from "./modules/app-logs.types.js";
 import type { AppModule } from "./modules/app.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
 import type { ExperimentsModule } from "./modules/experiments.types.js";
+import type { ExperimentsContext } from "./modules/experiments-config.types.js";
 import type { ActorsModule } from "./modules/actors.types.js";
 import type { FetchWithAuthInit } from "./utils/fetch-with-auth.js";
 /**
@@ -80,6 +81,12 @@ export interface CreateClientConfig {
      * Omit this option to preserve the default analytics behavior.
      */
     analytics?: CreateClientAnalyticsConfig;
+    /**
+     * Platform-validated context for local flag evaluation. Request-scoped on servers.
+     * Automatically read from the platform bootstrap in browsers and trusted headers
+     * by createClientFromRequest(). Not an authorization credential.
+     */
+    experiments?: ExperimentsContext;
     /**
      * User authentication token. Used to authenticate as a specific user.
      *
@@ -135,7 +142,7 @@ export interface Base44Client {
     connectors: UserConnectorsModule;
     /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
     entities: EntitiesModule;
-    /** {@link ExperimentsModule | Experiments module} for browser feature flags and exposures. */
+    /** {@link ExperimentsModule | Experiments module} for local feature flags and exposures. */
     experiments: ExperimentsModule;
     /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
     functions: FunctionsModule;

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientAnalyticsConfig, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
+export { evaluateExperiments } from "./modules/experiments-evaluator.js";
+export type { ExperimentsConfig, ExperimentsContext, ExperimentsIdentity } from "./modules/experiments-config.types.js";
 export type { ExperimentsModule, ExperimentsSnapshot, } from "./modules/experiments.types.js";
 export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";

package/dist/index.js

@@ -3,4 +3,5 @@ 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 { evaluateExperiments } from "./modules/experiments-evaluator.js";
 export { Actor } from "./actor.js";

package/dist/modules/analytics-queue.d.ts

@@ -0,0 +1,12 @@
+import type { AxiosInstance } from "axios";
+import type { AnalyticsApiRequestData, AnalyticsModuleOptions } from "./analytics.types.js";
+type Event = AnalyticsApiRequestData & {
+    event_id?: string;
+};
+/** @internal One transport queue per client, shared by goals and exposures. */
+export declare function getAnalyticsQueue(axiosClient: AxiosInstance, appId: string, config: AnalyticsModuleOptions): {
+    enqueue(event: Event | Promise<Event>, authorization: string | null, userId: string | null | Promise<string | null>): void;
+    flush(): Promise<void>;
+    cleanup(): void;
+};
+export {};

package/dist/modules/analytics-queue.js

@@ -0,0 +1,128 @@
+const DELIVERY_BUDGET_MS = 5000;
+const queues = new WeakMap();
+/** @internal One transport queue per client, shared by goals and exposures. */
+export function getAnalyticsQueue(axiosClient, appId, config) {
+    let queue = queues.get(axiosClient);
+    if (!queue) {
+        queue = createAnalyticsQueue(axiosClient, appId, config);
+        queues.set(axiosClient, queue);
+    }
+    return queue;
+}
+function createAnalyticsQueue(axiosClient, appId, config) {
+    const entries = [];
+    const pending = new Set();
+    let timer;
+    function deliver(batch) {
+        const controller = new AbortController();
+        const deadlineAt = Date.now() + DELIVERY_BUDGET_MS;
+        const deadline = new Promise((resolve) => {
+            controller.signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        const timeout = setTimeout(() => controller.abort(), DELIVERY_BUDGET_MS);
+        function send(prepared) {
+            var _a;
+            const groups = new Map();
+            for (const entry of prepared) {
+                const key = JSON.stringify([entry.authorization, entry.userId, entry.event.session_id]);
+                const group = (_a = groups.get(key)) !== null && _a !== void 0 ? _a : [];
+                group.push(entry);
+                groups.set(key, group);
+            }
+            return Promise.all([...groups.values()].map(async (group) => {
+                var _a, _b;
+                const events = group.map(({ event }) => event);
+                const exposures = events.filter((event) => event.event_name === "__experiment_exposure__");
+                const attempts = exposures.length ? 3 : 1;
+                for (let attempt = 0; attempt < attempts; attempt++) {
+                    try {
+                        if (controller.signal.aborted)
+                            return;
+                        await axiosClient.request({
+                            method: "POST", url: `/apps/${appId}/analytics/track/batch`,
+                            headers: { Authorization: group[0].authorization },
+                            // Ordinary goals have no backend deduplication and remain single-attempt.
+                            data: { events: attempt === 0 ? events : exposures },
+                            timeout: Math.max(1, deadlineAt - Date.now()), signal: controller.signal,
+                        });
+                        return;
+                    }
+                    catch (error) {
+                        const status = (_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status) !== null && _b !== void 0 ? _b : error.status;
+                        if (controller.signal.aborted || attempt === attempts - 1 ||
+                            (status !== undefined && (status < 500 || status >= 600)))
+                            return;
+                        await new Promise((resolve) => setTimeout(resolve, attempt === 0 ? 100 : 500));
+                    }
+                }
+            }));
+        }
+        const delivery = (async () => {
+            const ready = [];
+            const requests = [];
+            let wake = () => { };
+            let preparedAll = false;
+            const preparation = Promise.all(batch.map(async (entry) => {
+                const [event, userId] = await Promise.all([entry.event, entry.userId]);
+                if (event && !controller.signal.aborted)
+                    ready.push({ event, userId, authorization: entry.authorization });
+                wake();
+            })).then(() => { preparedAll = true; wake(); });
+            while (!preparedAll || ready.length) {
+                if (!ready.length && !preparedAll)
+                    await Promise.race([
+                        new Promise((resolve) => { wake = resolve; }), deadline,
+                    ]);
+                if (controller.signal.aborted)
+                    return;
+                // Coalesce this turn's resolved identities without waiting for unrelated auth I/O.
+                let turnTimer;
+                await Promise.race([preparation, new Promise((resolve) => { turnTimer = setTimeout(resolve, 0); })]);
+                clearTimeout(turnTimer);
+                if (ready.length)
+                    requests.push(send(ready.splice(0)));
+            }
+            await Promise.all(requests);
+        })();
+        // Identity lookup and transports that ignore cancellation must also be bounded.
+        const settlement = Promise.race([delivery, deadline]).catch(() => { }).finally(() => {
+            clearTimeout(timeout);
+            controller.abort();
+            pending.delete(settlement);
+        });
+        pending.add(settlement);
+    }
+    function schedule() {
+        var _a;
+        if (timer || entries.length === 0)
+            return;
+        timer = setTimeout(() => {
+            var _a;
+            timer = undefined;
+            deliver(entries.splice(0, (_a = config.batchSize) !== null && _a !== void 0 ? _a : 30));
+            schedule();
+        }, (_a = config.throttleTime) !== null && _a !== void 0 ? _a : 1000);
+    }
+    return {
+        enqueue(event, authorization, userId) {
+            var _a;
+            if (entries.length >= ((_a = config.maxQueueSize) !== null && _a !== void 0 ? _a : 1000))
+                return;
+            entries.push({ event: Promise.resolve(event).catch(() => undefined), authorization,
+                userId: Promise.resolve(userId).catch(() => null) });
+            schedule();
+        },
+        async flush() {
+            var _a;
+            clearTimeout(timer);
+            timer = undefined;
+            while (entries.length)
+                deliver(entries.splice(0, (_a = config.batchSize) !== null && _a !== void 0 ? _a : 30));
+            await Promise.all([...pending]);
+        },
+        cleanup() {
+            clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/modules/analytics.d.ts

@@ -1,21 +1,44 @@
 import { AxiosInstance } from "axios";
-import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
+import { TrackEventParams, AnalyticsModuleOptions, SessionContext } from "./analytics.types";
 import type { InternalAuthModule } from "./auth.types";
+import type { ExperimentsContext } from "./experiments-config.types.js";
 export declare const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
 export declare const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_event__";
 export declare const ANALYTICS_SESSION_DURATION_EVENT_NAME = "__session_duration_event__";
 export declare const ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY = "analytics-enable";
 export declare const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
+declare function createAnalyticsState(): {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    fallbackSessionId: string | null;
+    config: Required<AnalyticsModuleOptions>;
+};
+type AnalyticsState = ReturnType<typeof createAnalyticsState>;
+/** @internal */
+export declare function getAnalyticsState(axiosClient: AxiosInstance): AnalyticsState;
 export interface AnalyticsModuleArgs {
     axiosClient: AxiosInstance;
     serverUrl: string;
     appId: string;
     userAuthModule: InternalAuthModule;
     enabled: boolean;
+    getVisitorId?: () => string | undefined;
+    experimentsContext?: ExperimentsContext;
 }
 /** @internal */
-export declare function isAnalyticsEnabled(enabled: boolean): boolean;
-export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }: AnalyticsModuleArgs) => {
+export declare function isAnalyticsEnabled(enabled: boolean, state?: {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    fallbackSessionId: string | null;
+    config: Required<AnalyticsModuleOptions>;
+}): boolean;
+export declare const createAnalyticsModule: ({ axiosClient, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
     cleanup: () => void;
 };
@@ -29,6 +52,15 @@ export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, us
  *
  * @internal
  */
-export declare function resetAnalyticsSessionContext(): void;
+export declare function resetAnalyticsSessionContext(axiosClient?: AxiosInstance): void;
 export declare function getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
-export declare function getAnalyticsSessionId(): string;
+export declare function getAnalyticsSessionId(state?: {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    fallbackSessionId: string | null;
+    config: Required<AnalyticsModuleOptions>;
+}): string;
+export {};