@base44-preview/sdk 0.8.48-pr.276.4f760f9 → 0.8.48-pr.280.2c0d8bc

package/dist/client.js

@@ -14,6 +14,8 @@ import { createAppModule } from "./modules/app.js";
 import { createUsersModule } from "./modules/users.js";
 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 { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
@@ -53,7 +55,7 @@ import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
  * ```
  */
 export function createClient(config) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     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 : "";
@@ -121,10 +123,19 @@ export function createClient(config) {
         baseURL: `${serverUrl}/api`,
         headers,
     });
+    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,
+    });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
         appBaseUrl: normalizedAppBaseUrl,
         serverUrl,
         token,
+        onAuthStateChange: experiments.onAuthStateChange,
     });
     // Apply the access token before any module that may issue authenticated
     // requests during construction (notably analytics, which fires an init
@@ -140,7 +151,7 @@ export function createClient(config) {
         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" ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined),
+        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_b = window.location) === null || _b === void 0 ? void 0 : _b.origin : undefined),
         functionsVersion,
         getAuthToken: () => token || getAccessToken(),
         mintConnectionToken: async (actorName, room, connectionId) => {
@@ -168,6 +179,7 @@ export function createClient(config) {
         integrations: createIntegrationsModule(axiosClient, appId),
         connectors: createUserConnectorsModule(axiosClient, appId),
         auth: userAuthModule,
+        experiments: experiments.module,
         functions: createFunctionsModule(functionsAxiosClient, appId, {
             getAuthHeaders: () => {
                 const headers = {};
@@ -178,7 +190,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_b = functionsAxiosClient.defaults) === null || _b === void 0 ? void 0 : _b.baseURL,
+            baseURL: (_c = functionsAxiosClient.defaults) === null || _c === void 0 ? void 0 : _c.baseURL,
         }),
         agents: createAgentsModule({
             axios: axiosClient,
@@ -196,11 +208,12 @@ export function createClient(config) {
             serverUrl,
             appId,
             userAuthModule,
-            enabled: (_c = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _c !== void 0 ? _c : true,
+            enabled: (_d = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _d !== void 0 ? _d : true,
         }),
         actors: actorsModule.module,
         cleanup: () => {
             userModules.analytics.cleanup();
+            experiments.cleanup();
             actorsModule.closeAll();
             if (socket) {
                 socket.disconnect();
@@ -225,7 +238,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_d = serviceRoleFunctionsAxiosClient.defaults) === null || _d === void 0 ? void 0 : _d.baseURL,
+            baseURL: (_e = serviceRoleFunctionsAxiosClient.defaults) === null || _e === void 0 ? void 0 : _e.baseURL,
         }),
         agents: createAgentsModule({
             axios: serviceRoleAxiosClient,

package/dist/client.types.d.ts

@@ -9,6 +9,7 @@ import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 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 { ActorsModule } from "./modules/actors.types.js";
 import type { FetchWithAuthInit } from "./utils/fetch-with-auth.js";
 /**
@@ -39,9 +40,9 @@ export interface CreateClientAnalyticsConfig {
     /**
      * Whether app analytics is enabled for this client.
      *
-     * When disabled, automatic analytics and calls to `analytics.track()` are
-     * no-ops. The SDK does not create an analytics session identifier, start
-     * heartbeat timers, or send analytics requests.
+     * When disabled, automatic analytics, experiment exposures and calls to
+     * `analytics.track()` are no-ops. The SDK does not create an analytics session
+     * identifier, start heartbeat timers, or send analytics requests.
      *
      * @defaultValue `true`
      */
@@ -134,6 +135,8 @@ 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. */
+    experiments: ExperimentsModule;
     /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
     functions: FunctionsModule;
     /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */

package/dist/index.d.ts

@@ -4,6 +4,7 @@ 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 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";
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
@@ -18,14 +19,3 @@ export { Actor, type Conn } from "./actor.js";
 export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";
-export type { CreateIapClientOptions, IapInternalOptions, } from "./iap/index.js";
-export type { IapConfig, IapConfiguredProductType, IapModule, IapProductConfig, IapSetupReport, } from "./iap/iap.types.js";
-export type { IapEvent, IapEventHandler, IapEventType, IapExpiryReason, IapRenewReason, IapStartReason, } from "./iap/events/events.types.js";
-export type { EntitlementQuery, Entitlements, IapExpirationReason, IapRevocation, IapSubscriptionOffer, IapSubscriptionStatus, OwnedNonConsumable, OwnedNonRenewingSubscription, SubscriptionQuery, SubscriptionState, TransactionQuery, } from "./iap/read/read.types.js";
-export type { HandleNotificationResult } from "./iap/ingest/notifications.js";
-export type { RecordTransactionOptions, RecordTransactionResult, SyncPayload, SyncResult, } from "./iap/ingest/device.types.js";
-export type { IapConsumptionOutcome, IapConsumptionRequestRecord, IapNotificationOutcome, IapNotificationRecord, IapRecordSource, IapSubscriptionRecord, IapTransactionRecord, } from "./iap/store/rows.types.js";
-export type { IapEntityName, IapEntitySchema, IapSchemaField, } from "./iap/store/schemas.js";
-export type { ConsumptionRequestBody, IapDeliveryStatus, IapRefundPreference, IapServerApiConfig, IapServerApiModule, SendAttempt, SendAttemptResult, TestNotificationResult, TestNotificationStatus, } from "./iap/server-api/server-api.types.js";
-export type { IapApiErrorCode, IapConfigErrorCode, IapSetupErrorCode, IapStoreErrorCode, IapVerificationErrorCode, } from "./iap/errors.types.js";
-export type { DecodedNotification, DecodedNotificationData, DecodedNotificationSummary, DecodedRenewalInfo, DecodedTransaction, IapAppleSubscriptionStatus, IapConsumptionRequestReason, IapEnvironment, IapExpirationIntent, IapOfferDiscountType, IapOfferType, IapOwnershipType, IapProductType, IapRevocationType, IapTransactionReason, } from "./iap/verify/verify.types.js";

package/dist/modules/analytics.d.ts

@@ -13,6 +13,8 @@ export interface AnalyticsModuleArgs {
     userAuthModule: InternalAuthModule;
     enabled: boolean;
 }
+/** @internal */
+export declare function isAnalyticsEnabled(enabled: boolean): boolean;
 export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
     cleanup: () => void;

package/dist/modules/analytics.js

@@ -33,15 +33,18 @@ const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () =
         ...getAnalyticsConfigFromUrlParams(),
     },
 }));
+/** @internal */
+export function isAnalyticsEnabled(enabled) {
+    return enabled && analyticsSharedState.config.enabled && !isReactNative;
+}
 export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }) => {
-    var _a;
     // 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 (!enabled || !((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled) || isReactNative) {
+    if (!isAnalyticsEnabled(enabled)) {
         return {
             track: () => { },
             cleanup: () => { },

package/dist/modules/auth.js

@@ -75,20 +75,47 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
     // requests would leave the app rendering a stale identity after logout or a
     // session swap.
     let pendingMe = null;
+    let identityGeneration = 0;
     const clearPendingMe = () => {
+        identityGeneration += 1;
         pendingMe = null;
     };
     // Tracked here rather than read off `axios.defaults` so the answer stays tied
     // to the identity transitions below (`setToken`, `logout`) instead of to the
     // header a caller may have set on the instance directly.
     let hasAccessToken = Boolean(options.token);
+    const notifyAuthState = (state) => {
+        var _a;
+        try {
+            (_a = options.onAuthStateChange) === null || _a === void 0 ? void 0 : _a.call(options, state);
+        }
+        catch (_b) {
+            // Optional observers must not interrupt authentication or logout redirects.
+        }
+    };
     return {
         hasToken() {
             return hasAccessToken;
         },
         // Get current user information
         async me() {
-            const request = pendingMe !== null && pendingMe !== void 0 ? pendingMe : axios.get(`/apps/${appId}/entities/User/me`).finally(() => {
+            const generation = identityGeneration;
+            const request = pendingMe !== null && pendingMe !== void 0 ? pendingMe : axios.get(`/apps/${appId}/entities/User/me`).then((user) => {
+                if (generation === identityGeneration) {
+                    notifyAuthState({ status: "authenticated", userId: user.id });
+                }
+                return user;
+            }, (error) => {
+                var _a, _b;
+                if (generation === identityGeneration) {
+                    const authError = error;
+                    const status = (_a = authError === null || authError === void 0 ? void 0 : authError.status) !== null && _a !== void 0 ? _a : (_b = authError === null || authError === void 0 ? void 0 : authError.response) === null || _b === void 0 ? void 0 : _b.status;
+                    notifyAuthState({
+                        status: status === 401 || status === 403 ? "anonymous" : "error",
+                    });
+                }
+                throw error;
+            }).finally(() => {
                 // Only retire this request if it is still the shared one. An identity
                 // change mid-flight clears `pendingMe` and the next caller starts a
                 // fresh request; an unconditional clear here would retire that newer
@@ -152,6 +179,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             clearPendingMe();
             resetAnalyticsSessionContext();
             hasAccessToken = false;
+            notifyAuthState({ status: "anonymous" });
             // Only do the rest if in a browser environment
             if (typeof window !== "undefined") {
                 // Remove token from localStorage
@@ -184,6 +212,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // handle token change for axios clients
             axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;
             functionsAxiosClient.defaults.headers.common["Authorization"] = `Bearer ${token}`;
+            notifyAuthState({ status: "pending" });
             // Save token to localStorage if requested
             if (saveToStorage &&
                 typeof window !== "undefined" &&

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

@@ -84,6 +84,17 @@ export interface ResetPasswordParams {
     /** New password to set. */
     newPassword: string;
 }
+/** @internal */
+export type AuthState = {
+    status: "pending";
+} | {
+    status: "anonymous";
+} | {
+    status: "authenticated";
+    userId: string;
+} | {
+    status: "error";
+};
 /**
  * Configuration options for the auth module.
  */
@@ -98,6 +109,8 @@ export interface AuthModuleOptions {
      * which is how the server-side SDK reports a token it never sets explicitly.
      */
     token?: string;
+    /** @internal */
+    onAuthStateChange?: (state: AuthState) => void;
 }
 /**
  * Authentication module for managing user authentication and authorization. The module automatically stores tokens in local storage when available and manages authorization headers for API requests.

package/dist/modules/experiment-exposures.d.ts

@@ -0,0 +1,16 @@
+import type { AxiosInstance } from "axios";
+/** @internal */
+export declare function createExposureTracker({ axiosClient, appId, enabled, }: {
+    axiosClient: AxiosInstance;
+    appId: string;
+    enabled: boolean;
+}): {
+    track(assignment: {
+        experiment_id: string;
+        run_version: number;
+        variant_key: string;
+    }, identity: {
+        visitorId: string;
+        userId: string | null;
+    }): void;
+};

package/dist/modules/experiment-exposures.js

@@ -0,0 +1,45 @@
+import { isAnalyticsEnabled } from "./analytics.js";
+/** @internal */
+export function createExposureTracker({ axiosClient, appId, enabled, }) {
+    const exposed = new Set();
+    return {
+        track(assignment, identity) {
+            var _a;
+            if (typeof window === "undefined" || !isAnalyticsEnabled(enabled))
+                return;
+            const { experiment_id, run_version, variant_key } = assignment;
+            const key = JSON.stringify([
+                experiment_id,
+                run_version,
+                variant_key,
+                identity.userId,
+                identity.visitorId,
+            ]);
+            if (exposed.has(key))
+                return;
+            exposed.add(key);
+            // Pin the event's auth before an account change can alter Axios defaults.
+            const authorization = identity.userId
+                ? ((_a = axiosClient.defaults.headers.common.Authorization) !== null && _a !== void 0 ? _a : null)
+                : null;
+            void axiosClient
+                .request({
+                method: "POST",
+                url: `/apps/${appId}/analytics/track/batch`,
+                headers: { Authorization: authorization },
+                data: {
+                    events: [
+                        {
+                            event_name: "__experiment_exposure__",
+                            timestamp: new Date().toISOString(),
+                            session_id: identity.visitorId,
+                            page_url: window.location.pathname,
+                            properties: { experiment_id, run_version, variant_key },
+                        },
+                    ],
+                },
+            })
+                .catch(() => exposed.delete(key));
+        },
+    };
+}

package/dist/modules/experiments-runtime.types.d.ts

@@ -0,0 +1,19 @@
+/** @internal */
+export interface ExperimentAssignment {
+    experiment_id: string;
+    flag_key: string;
+    run_version: number;
+    variant_key: string;
+    preview: boolean;
+}
+/** @internal */
+export interface ExperimentsRuntime {
+    flags: Record<string, boolean>;
+    assignments: ExperimentAssignment[];
+    visitorId: string;
+    userId: string | null;
+    pendingUser: boolean;
+    setUser(id: string | null): void;
+}
+/** @internal */
+export declare function getExperimentsRuntime(): ExperimentsRuntime | undefined;

package/dist/modules/experiments-runtime.types.js

@@ -0,0 +1,7 @@
+/** @internal */
+export function getExperimentsRuntime() {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    return window
+        .__B44_EXPERIMENTS__;
+}

package/dist/modules/experiments.d.ts

@@ -0,0 +1,12 @@
+import type { AuthState, InternalAuthModule } from "./auth.types.js";
+import type { ExperimentsModule } from "./experiments.types.js";
+import type { createExposureTracker } from "./experiment-exposures.js";
+/** @internal */
+export declare function createExperimentsModule({ getAuth, trackExposure, }: {
+    getAuth: () => InternalAuthModule;
+    trackExposure: ReturnType<typeof createExposureTracker>["track"];
+}): {
+    module: ExperimentsModule;
+    onAuthStateChange: (next: AuthState) => void;
+    cleanup(): void;
+};

package/dist/modules/experiments.js

@@ -0,0 +1,150 @@
+import { getExperimentsRuntime, } from "./experiments-runtime.types.js";
+const EMPTY = Object.freeze({
+    flags: Object.freeze({}),
+    isLoading: false,
+});
+/** @internal */
+export function createExperimentsModule({ getAuth, trackExposure, }) {
+    let runtime;
+    let state;
+    let snapshot = EMPTY;
+    let active = false;
+    let disposed = false;
+    let generation = 0;
+    let pending;
+    const listeners = new Set();
+    const readyWaiters = new Set();
+    function settleReady() {
+        if (snapshot.isLoading)
+            return;
+        for (const resolve of readyWaiters)
+            resolve(snapshot);
+        readyWaiters.clear();
+    }
+    function publish() {
+        const isLoading = !!runtime && (state === null || state === void 0 ? void 0 : state.status) === "pending";
+        const flags = runtime &&
+            ((state === null || state === void 0 ? void 0 : state.status) === "authenticated" || (state === null || state === void 0 ? void 0 : state.status) === "anonymous")
+            ? runtime.flags
+            : EMPTY.flags;
+        if (snapshot.isLoading === isLoading &&
+            Object.keys(snapshot.flags).length === Object.keys(flags).length &&
+            Object.keys(flags).every((key) => Object.prototype.hasOwnProperty.call(snapshot.flags, key) &&
+                snapshot.flags[key] === flags[key])) {
+            settleReady();
+            return;
+        }
+        snapshot = Object.freeze({ flags: Object.freeze({ ...flags }), isLoading });
+        settleReady();
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (_a) {
+                /* Observers must not interrupt authentication. */
+            }
+        }
+    }
+    function applyIdentity() {
+        if (runtime) {
+            const userId = (state === null || state === void 0 ? void 0 : state.status) === "authenticated" ? state.userId : null;
+            if (runtime.userId !== userId || runtime.pendingUser)
+                runtime.setUser(userId);
+        }
+        publish();
+    }
+    function resolveIdentity() {
+        if (!runtime || pending || disposed)
+            return;
+        state = { status: "pending" };
+        applyIdentity();
+        const currentGeneration = generation;
+        pending = getAuth()
+            .me()
+            .then(() => { }, () => { })
+            .finally(() => {
+            if (currentGeneration === generation)
+                pending = undefined;
+        });
+    }
+    function activate() {
+        if (disposed)
+            return;
+        active = true;
+        runtime = getExperimentsRuntime();
+        if (!runtime) {
+            publish();
+            return;
+        }
+        if (!state)
+            state = getAuth().hasToken()
+                ? { status: "pending" }
+                : { status: "anonymous" };
+        applyIdentity();
+        if (state.status === "pending")
+            resolveIdentity();
+    }
+    function onAuthStateChange(next) {
+        if (disposed)
+            return;
+        state = next;
+        if (next.status === "pending" || next.status === "anonymous") {
+            generation++;
+            pending = undefined;
+        }
+        if (!active)
+            return;
+        runtime = getExperimentsRuntime();
+        applyIdentity();
+        if (next.status === "pending")
+            resolveIdentity();
+    }
+    const module = {
+        isEnabled(flagKey, fallback = false) {
+            activate();
+            if (!Object.prototype.hasOwnProperty.call(snapshot.flags, flagKey))
+                return fallback;
+            const assignment = runtime === null || runtime === void 0 ? void 0 : runtime.assignments.find((item) => item.flag_key === flagKey && !item.preview);
+            if (runtime && assignment)
+                trackExposure(assignment, runtime);
+            return snapshot.flags[flagKey];
+        },
+        getSnapshot() {
+            activate();
+            return snapshot;
+        },
+        subscribe(listener) {
+            activate();
+            if (!disposed)
+                listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async ready() {
+            activate();
+            if ((state === null || state === void 0 ? void 0 : state.status) === "error") {
+                // Wait for auth.me() to release its shared, failed request before retrying.
+                await pending;
+                if ((state === null || state === void 0 ? void 0 : state.status) === "error")
+                    resolveIdentity();
+            }
+            if (snapshot.isLoading)
+                return new Promise((resolve) => readyWaiters.add(resolve));
+            return snapshot;
+        },
+    };
+    return {
+        module,
+        onAuthStateChange,
+        cleanup() {
+            disposed = true;
+            generation++;
+            pending = undefined;
+            runtime = undefined;
+            snapshot = EMPTY;
+            settleReady();
+            listeners.clear();
+        },
+    };
+}

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

@@ -0,0 +1,95 @@
+/** A stable, read-only view of the browser's current feature flags. */
+export interface ExperimentsSnapshot {
+    /** Resolved flags. Empty when the runtime is absent or identity is unresolved. */
+    readonly flags: Readonly<Record<string, boolean>>;
+    /** Whether the SDK is resolving the signed-in user's identity. */
+    readonly isLoading: boolean;
+}
+/**
+ * Reads feature flags evaluated by the Base44 browser runtime.
+ *
+ * - Reads flags and reports experiment exposures when a flag is used.
+ * - Synchronizes assignments with this client's SDK login, token changes, and logout.
+ * - Provides readiness and subscriptions without requiring React.
+ *
+ * Available as `base44.experiments` for anonymous and signed-in app visitors,
+ * not in service role mode. Use one client for the app whose runtime is on the page.
+ * The platform must inject the Experiments runtime before this module can evaluate
+ * flags. Without it, including on servers and Workers, reads return their fallback;
+ * this module does not provide server-side evaluation or hydration guarantees.
+ * Goal conversions use the existing {@link AnalyticsModule | analytics module}.
+ * Visitor-keyed conversion attribution requires matching runtime and analytics
+ * visitor IDs; blocked browser storage is not currently supported for attribution.
+ */
+export interface ExperimentsModule {
+    /**
+     * Reads a flag and reports a best-effort exposure for its current assignment.
+     *
+     * The first use resolves identity through {@link AuthModule.me | auth.me()}
+     * when the client has a token. Reads return the fallback while identity is
+     * pending or could not be resolved. Await {@link ExperimentsModule.ready | ready()}
+     * or subscribe to updates before displaying authenticated variants.
+     *
+     * Call only where the feature is used: a read counts as exposure, not proof of
+     * visibility. Preview overrides and flags without an assignment are not tracked.
+     * Exposures respect the client's analytics setting, are deduplicated per client,
+     * experiment run, variant and identity, and retry only on a later read after failure.
+     *
+     * @param flagKey - Feature flag key defined in your app.
+     * @param fallback - Value for an unavailable flag or unresolved identity. Defaults to `false`.
+     * @returns The evaluated boolean, or the fallback when unavailable.
+     * @example
+     * ```typescript
+     * await base44.experiments.ready();
+     * const showNewCheckout = base44.experiments.isEnabled('new_checkout');
+     * ```
+     */
+    isEnabled(flagKey: string, fallback?: boolean): boolean;
+    /**
+     * Returns the current flags and identity-loading state without tracking exposures.
+     *
+     * Starts lazy identity resolution if needed. The returned object retains its
+     * reference until its values change, for use with external-store subscriptions.
+     * Use {@link ExperimentsModule.isEnabled | isEnabled()} at the feature boundary
+     * to record exposure rather than displaying a variant directly from this snapshot.
+     *
+     * @returns A stable, read-only snapshot.
+     * @example
+     * ```typescript
+     * const { isLoading } = base44.experiments.getSnapshot();
+     * ```
+     */
+    getSnapshot(): ExperimentsSnapshot;
+    /**
+     * Listens for flag or loading-state changes caused by this client's SDK auth flows.
+     *
+     * Does not poll for platform configuration changes or observe token writes outside
+     * the SDK. {@link Base44Client.cleanup | cleanup()} removes all listeners.
+     *
+     * @param listener - Callback invoked when the snapshot changes.
+     * @returns A function that removes the listener.
+     * @example
+     * ```typescript
+     * const unsubscribe = base44.experiments.subscribe(() => {
+     *   renderCheckout(base44.experiments.isEnabled('new_checkout'));
+     * });
+     * unsubscribe();
+     * ```
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Waits for the current identity lookup, including a token change during that lookup.
+     *
+     * Resolves with empty flags after an identity lookup failure; calling again retries
+     * the lookup. Missing runtimes resolve immediately. This does not wait for a future
+     * runtime injection or for exposure delivery, and never records an exposure itself.
+     *
+     * @returns A snapshot after the current identity lookup settles.
+     * @example
+     * ```typescript
+     * await base44.experiments.ready();
+     * renderCheckout(base44.experiments.isEnabled('new_checkout'));
+     * ```
+     */
+    ready(): Promise<ExperimentsSnapshot>;
+}