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

package/dist/client.js

@@ -9,7 +9,6 @@ import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
-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";
@@ -53,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 = {
@@ -188,13 +187,13 @@ export function createClient(config) {
         }),
         aiGateway: createAiGatewayModule({ serverUrl, token, appId }),
         appLogs: createAppLogsModule(axiosClient, appId),
-        app: createAppModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
         analytics: createAnalyticsModule({
             axiosClient,
             serverUrl,
             appId,
             userAuthModule,
+            options: analyticsOptions,
         }),
         actors: actorsModule.module,
         cleanup: () => {

package/dist/client.types.d.ts

@@ -7,8 +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 { AppModule } from "./modules/app.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.
@@ -83,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.
      */
@@ -102,8 +117,6 @@ export interface Base44Client {
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
-    /** {@link AppModule | App module} for reading the app's own public configuration. */
-    app: AppModule;
     /** {@link ActorsModule | Actors module} for subscribing to and sending messages via Cloudflare Durable Object-backed Actors. */
     actors: ActorsModule;
     /** {@link AuthModule | Auth module} for user authentication and management. */

package/dist/index.d.ts

@@ -11,7 +11,6 @@ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./mod
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
-export type { AppModule, AppPublicSettings, AppPublicSettingsResponse, } from "./modules/app.types.js";
 export type { ActorsModule, ActorClient, ActorRef, Connection, ActorSubscription, ActorConnectOptions, ActorNameRegistry, ActorRegistry, } from "./modules/actors.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export { Actor, type Conn } from "./actor.js";

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

@@ -28,22 +28,81 @@ const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () =
     // 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: () => { },
         };
     }
@@ -90,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;
         }
@@ -98,7 +163,9 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             ...params,
             ...intrinsicData,
         });
-        startProcessing();
+        if (consent === "granted") {
+            startProcessing();
+        }
     };
     const onDocVisible = () => {
         startAnalyticsProcessor(flush, {
@@ -126,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,
     };
 };
@@ -314,19 +422,29 @@ function getFallbackSessionId() {
     return ((_a = analyticsSharedState.fallbackSessionId) !== null && _a !== void 0 ? _a : (analyticsSharedState.fallbackSessionId = generateUuid()));
 }
 export function getAnalyticsSessionId() {
+    var _a;
     if (typeof window === "undefined") {
         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) {
+    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/modules/app.types.d.ts

@@ -1,55 +1,3 @@
-/**
- * The app's access policy: whether the app is reachable without an account, and
- * who may sign in.
- */
-export type AppPublicSettings = "private_with_login" | "public_with_login" | "public_without_login" | "workspace_with_login" | string;
-/**
- * The app's public configuration, as returned by {@link AppModule.getPublicSettings}.
- */
-export interface AppPublicSettingsResponse {
-    /** The app's ID. */
-    id: string;
-    /** The app's access policy. */
-    public_settings: AppPublicSettings;
-}
-/**
- * App module for reading the app's own public configuration.
- *
- * Use it to discover how the app is gated before rendering it, so a private app
- * can send the visitor to login instead of rendering an empty shell.
- *
- * ## Authentication Modes
- *
- * This module is available to use with a client in all authentication modes. The
- * client's token, when it has one, is sent with the request — a signed-in visitor
- * who has no access to the app is reported differently from an anonymous one.
- */
-export interface AppModule {
-    /**
-     * Get the app's public configuration.
-     *
-     * Rejects with a {@linkcode Base44Error} when the visitor may not open the app:
-     * `status` is `403` and `data.extra_data.reason` says why — `"auth_required"`
-     * when the visitor must sign in, `"user_not_registered"` when the signed-in
-     * visitor has no access to this app.
-     *
-     * @returns Promise resolving to the app's ID and access policy.
-     *
-     * @example
-     * ```typescript
-     * // Decide what to render before the app boots
-     * try {
-     *   const { public_settings } = await base44.app.getPublicSettings();
-     *   console.log('App access policy:', public_settings);
-     * } catch (error) {
-     *   if (error.status === 403) {
-     *     console.log('Blocked because:', error.data?.extra_data?.reason);
-     *   }
-     * }
-     * ```
-     */
-    getPublicSettings(): Promise<AppPublicSettingsResponse>;
-}
 /**
  * @internal
  */
@@ -114,7 +62,7 @@ export interface AppLike {
     agents?: Record<string, any>;
     logo_url?: string;
     slug?: string;
-    public_settings?: AppPublicSettings;
+    public_settings?: "private_with_login" | "public_with_login" | "public_without_login" | "workspace_with_login" | string;
     is_blocked?: boolean;
     github_repo_url?: string;
     main_page?: string;

package/package.json

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

package/dist/modules/app.d.ts

@@ -1,11 +0,0 @@
-import { AxiosInstance } from "axios";
-import { AppModule } from "./app.types";
-/**
- * Creates the app module for the Base44 SDK.
- *
- * @param axios - Axios instance
- * @param appId - Application ID
- * @returns App module for reading the app's own configuration
- * @internal
- */
-export declare function createAppModule(axios: AxiosInstance, appId: string): AppModule;

package/dist/modules/app.js

@@ -1,15 +0,0 @@
-/**
- * Creates the app module for the Base44 SDK.
- *
- * @param axios - Axios instance
- * @param appId - Application ID
- * @returns App module for reading the app's own configuration
- * @internal
- */
-export function createAppModule(axios, appId) {
-    return {
-        async getPublicSettings() {
-            return axios.get(`/apps/public/prod/public-settings/by-id/${appId}`);
-        },
-    };
-}