@base44-preview/sdk 0.8.52-pr.305.d6c90ab → 0.8.53-pr.289.39e1f1f

package/dist/actor.d.ts

@@ -25,8 +25,8 @@ export interface Storage {
     get<T>(key: string): Promise<T | undefined>;
     put(key: string, value: unknown): Promise<void>;
     delete(key: string): Promise<boolean>;
-    /** Wipe the room's entire persisted storage (match-end cleanup). Safe: a
-     *  later rejoin re-bootstraps exactly like a brand-new room. */
+    /** Deletes all persisted storage for the session. A later connection starts
+     *  with empty storage, the same as a new session. */
     deleteAll(): Promise<void>;
 }
 /**

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

@@ -1,15 +1,22 @@
 /**
- * Extend this interface to add typed `subscribe` callbacks and `send` payloads
- * for your deployed Actors.
+ * Maps actor names to their incoming and outgoing message types.
  *
- * This is separate from {@link ActorNameRegistry} (which is auto-generated
- * by `base44 types generate`), so there are no conflicts.
+ * Extend this interface through module augmentation when you want typed actor
+ * messages without generating types with the CLI. For each actor, `toServer`
+ * defines incoming messages that a client sends to the actor. `toClient` defines
+ * outgoing messages that the actor sends to connected clients.
+ *
+ * To generate types from deployed actors instead, use the
+ * [`types generate`](/developers/references/cli/commands/types-generate) CLI command.
+ * To learn how incoming and outgoing messages work, see
+ * [message types](/developers/backend/resources/actors/overview#message-types).
  *
  * @example
  * ```typescript
+ * // Type messages for an actor
  * declare module "@base44/sdk" {
  *   interface ActorRegistry {
- *     ChatRoom: {
+ *     chatRoom: {
  *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
  *       toServer: { type: "message"; text: string };
  *     };
@@ -20,8 +27,11 @@
 export interface ActorRegistry {
 }
 /**
- * Auto-populated by `base44 types generate` with the names of your deployed actors.
- * Do not edit this interface manually — use {@link ActorRegistry} for message types.
+ * Lists actor names when your project includes types generated by the CLI
+ * with [`types generate`](/developers/references/cli/commands/types-generate).
+ *
+ * The generated names provide autocomplete for deployed actors. To define
+ * incoming and outgoing message types manually, augment [ActorRegistry](#actorregistry).
  */
 export interface ActorNameRegistry {
 }
@@ -32,71 +42,173 @@ type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegist
 type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
     toServer: infer O;
 } ? O : unknown : unknown;
-/** Options for {@link ActorRef.connect}. */
+/**
+ * Configures the connection that [ActorRef.connect](#connect) opens.
+ */
 export interface ActorConnectOptions {
     /**
-     * The connection id — becomes the actor's `conn.id`. Supply a stable value
-     * (e.g. persisted per tab) so a reconnect reuses the same server-side
-     * identity; omit for an auto-generated per-connection id.
+     * Connection ID that the actor receives as `conn.id`.
+     *
+     * To let the actor recognize the same client if it reconnects, use a stable
+     * value, such as an ID stored per browser tab. If you omit this property, the
+     * SDK generates a connection ID.
+     *
+     * For more about connection IDs, see
+     * [connections](/developers/backend/resources/actors/reference#connections).
      */
     id?: string;
 }
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/**
+ * Represents a listener for messages from the actor, registered with
+ * [Connection.subscribe](#subscribe).
+ */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the socket stay live. */
+    /**
+     * Removes this listener. Other listeners and the socket stay open.
+     *
+     * @example
+     * ```typescript
+     * // Remove a listener
+     * sub.unsubscribe();
+     * ```
+     */
     unsubscribe(): void;
 }
 /**
- * A live connection to an actor instance, returned by {@link ActorRef.connect}.
- * `subscribe`/`send` are always valid — you only get a `Connection` once the
- * socket has been opened, so there's no pre-connect state to guard against.
+ * Represents a client's WebSocket connection to an actor session.
+ *
+ * [ActorRef.connect](#connect) returns this object. The socket buffers messages
+ * you send before it opens.
  */
 export interface Connection<N extends string = string> {
-    /** The connection id (the value the actor sees as `conn.id`). */
+    /** Connection ID that the actor receives as `conn.id`. */
     readonly id: string;
-    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    /**
+     * Registers a listener for messages from the actor.
+     *
+     * You can register multiple listeners on the same connection.
+     *
+     * @param callback - Callback that runs for each message the actor sends to this connection.
+     * @returns A subscription handle. Call `unsubscribe()` on it to remove this listener without closing the socket.
+     *
+     * @example
+     * ```typescript
+     * // Listen for messages from the actor
+     * const sub = conn.subscribe((msg) => {
+     *   console.log(msg);
+     * });
+     *
+     * // Stop listening without closing the socket.
+     * sub.unsubscribe();
+     * ```
+     */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered by the socket until it's open; dropped after
-     * {@link close}. */
+    /**
+     * Sends a message to the actor.
+     *
+     * The socket buffers messages until it opens. After you call [close](#close),
+     * the socket drops further sends.
+     *
+     * @param data - Message to send to the actor. The type comes from [ActorRegistry](#actorregistry) when you register the actor there.
+     *
+     * @example
+     * ```typescript
+     * // Send a message to the actor
+     * conn.send({ type: "message", text: "Hello" });
+     * ```
+     */
     send(data: ToServerFor<N>): void;
     /**
-     * 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}.
+     * Closes the connection and removes all listeners.
+     *
+     * You can call this method more than once. A connection also closes itself
+     * when it fails permanently. To open a new connection, call
+     * [ActorRef.connect](#connect) again.
+     *
+     * @example
+     * ```typescript
+     * // Close the connection
+     * conn.close();
+     * ```
      */
     close(): void;
 }
 /**
- * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
- * {@link connect} to open the socket and get a {@link Connection}.
+ * Represents a reference to an actor session, identified by actor name and session ID.
+ *
+ * Call [connect](#connect) to open the WebSocket and get a [Connection](#connection).
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * Open the WebSocket and return the {@link Connection}. Idempotent while the
-     * connection is open.
+     * Creates or returns the [Connection](#connection) for this session.
+     *
+     * Repeated calls return the same connection until it closes. If the connection
+     * fails permanently, for example because the actor doesn't exist or the actor
+     * denies the connection, fix the cause and call `connect()` again. Then
+     * subscribe again on the new connection.
+     *
+     * For a sample flow, see
+     * [connect a client to a session](/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).
      *
-     * 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.
+     * @param options - Optional connection settings, such as a stable connection ID.
+     * @returns The [Connection](#connection) for this actor session.
+     *
+     * @example
+     * ```typescript
+     * // Connect to a session
+     * const conn = base44.actors.chatRoom("session-1").connect({ id: "tab-1" });
+     * ```
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**
- * Client for a single named Actor — call it with an instance id to get an
- * {@link ActorRef}. Typed automatically when the actor is registered in
- * {@link ActorRegistry}.
+ * Selects a session for a named actor.
+ *
+ * TypeScript infers message types when you register the actor in
+ * [ActorRegistry](#actorregistry). [ActorNameRegistry](#actornameregistry)
+ * provides autocomplete for actor names only.
  */
 export interface ActorClient<N extends string = string> {
+    /**
+     * Gets a reference to an actor session.
+     *
+     * Clients that specify the same actor name and session ID join the same session.
+     *
+     * @param instanceId - Session ID that identifies which session to connect to.
+     * @returns A reference to the actor session.
+     *
+     * @example
+     * ```typescript
+     * // Select a session
+     * const session = base44.actors.chatRoom("session-1");
+     * ```
+     */
     (instanceId: string): ActorRef<N>;
 }
 /**
- * The actors module provides access to Cloudflare Durable Object-backed
- * Actors deployed by the Base44 platform.
+ * Connects your frontend to [actor sessions](/developers/backend/resources/actors/overview),
+ * shared live backend processes where clients can exchange messages in realtime.
  *
+ * The following table lists what you can do with the actors module:
+ *
+ * | Member | Purpose |
+ * |---|---|
+ * | [`connect()`](#connect) | Opens a connection to a session. Clients that use the same actor name and session ID join the same session. |
+ * | [`subscribe()`](#subscribe) | Receives messages from an actor. |
+ * | [`send()`](#send) | Sends a message to an actor. |
+ * | [`ActorRegistry`](#actorregistry) | Defines message types for autocomplete and compile-time safety. |
+ *
+ * ## Authentication modes
+ *
+ * This module is available in anonymous and user authentication modes.
+ * Apps that require login can reject anonymous connections in the actor's `handleConnect()` method.
+ * To learn more, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).
+ *
+ * @example
  * ```typescript
- * const conn = base44.actors.MyActor("room-1").connect();
- * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * // Connect, subscribe, send, and close
+ * const conn = base44.actors.chatRoom("session-1").connect({ id: "tab-1" });
+ * const sub = conn.subscribe((msg) => console.log(msg));
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();

package/dist/modules/ai-gateway.types.d.ts

@@ -42,7 +42,7 @@ export interface AiGatewayModuleConfig {
 /**
  * AI Gateway module for calling Base44's managed AI models from your own code.
  *
- * Call `connection()` to get a `baseURL`, `token`, and `headers` that
+ * `connection()` hands you a `baseURL`, `token`, and `headers` that
  * authenticate as your Base44 app. An OpenAI-compatible client is any library, such as the `openai`
  * SDK or the Vercel AI SDK, that has the same request and response format
  * as OpenAI's API and lets you point it at a custom `baseURL`
@@ -51,9 +51,9 @@ export interface AiGatewayModuleConfig {
  * against the provider directly, no separate account, API key, or billing
  * setup with the underlying model provider required.
  *
- * The optional `provider` picks the API you connect to:
+ * `connection()` takes an optional `provider`, and each provider serves a different API:
  *
- * - `openai`, the default: OpenAI-compatible chat completions, image, and video endpoints.
+ * - `openai` (default): OpenAI-compatible chat completions and image endpoints.
  * - `typesafe`: structured evaluations with the `jev` model.
  *
  * Call `connection()` from a backend function rather than the browser. This
@@ -71,32 +71,20 @@ export interface AiGatewayModuleConfig {
  *
  * The gateway also serves OpenAI's image endpoints, `/images/generations`
  * and `/images/edits`, so you can generate images and edit them using
- * reference images. Image requests use their own set of models. Pass
+ * reference images. Image requests use their own set of models: pass
  * `'automatic'` to let Base44 choose one, or pin a model such as
  * `'gemini_3_1_flash_image'` or `'gpt_image_2'`. For request options, the
  * full model list, and limits, see [Generate images with the AI Gateway](/developers/references/sdk/getting-started/ai-gateway-images).
  *
- * ## Video
- *
- * The gateway also serves OpenAI's video endpoints, `/videos`, so you can
- * generate video from a prompt, from a still image, or from existing media.
- * Video generation is asynchronous. `POST /videos` returns a job, and you poll
- * `GET /videos/{id}` until its status is `completed` or `failed`, which can
- * take minutes. Video models are their own set, and there's no `automatic`
- * option, so pin a model such as `'veo_3_1_fast'` or `'seedance_2'`. For
- * request options, the full model list, and limits, see
- * [Generate video with the AI Gateway](/developers/references/sdk/getting-started/ai-gateway-video).
- *
  * ## Structured evaluations
  *
  * The `typesafe` provider runs the `jev` evaluation model through
  * `@ai-sdk/typesafe-ai` and `experimental_evaluate` from the `ai` package,
- * version 7.0.105 or later. Pass `evaluationModel("jev")`, and note that the
- * gateway rejects other model IDs, such as `"jev-latest"`. Give it some app
- * state and a set of questions, each a `choice`, `score`, or `boolean`. Choice
- * and score answers come back with `probabilities` per option, and boolean
- * answers with a single `probability` of `true`. Use it to classify, score, or
- * route records, then
+ * version 7.0.105 or later. Pass `evaluationModel("jev")`; the gateway rejects
+ * other model IDs, such as `"jev-latest"`. Give it some app state and a set of
+ * questions, each a `choice`, `score`, or `boolean`. Choice and score answers
+ * come back with `probabilities` per option; boolean answers with a single
+ * `probability` of `true`. Use it to classify, score, or route records, then
  * apply your own thresholds and actions in code.
  *
  * ## Authentication Modes
@@ -104,7 +92,7 @@ export interface AiGatewayModuleConfig {
  * The mode determines which token `connection()` returns:
  *
  * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token.
- * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. Use it from backend functions, because apps that restrict Core integrations, the default for new apps, reject user-token gateway calls on public apps. It also works when there's no signed-in user, such as from a scheduled automation.
+ * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. Use it from backend functions: apps that restrict Core integrations, the default for new apps, reject user-token gateway calls on public apps. It also works when there's no signed-in user, such as from a scheduled automation.
  *
  * ## Billing and limits
  *
@@ -212,30 +200,6 @@ export interface AiGatewayModule {
      *
      * @example
      * ```typescript
-     * // Start a video and record the job to poll later
-     * import { createClientFromRequest } from "@base44/sdk";
-     *
-     * // Runs inside a backend function
-     * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
-     *
-     * const response = await fetch(`${baseURL}/videos`, {
-     *   method: "POST",
-     *   headers: { ...headers, Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-     *   body: JSON.stringify({
-     *     model: "veo_3_1_fast",
-     *     prompt: "A lighthouse beam sweeping across a calm sea at dawn",
-     *     seconds: 8,
-     *   }),
-     * });
-     *
-     * // Video generation takes minutes, so store the id and poll it from a later request
-     * const { id } = await response.json();
-     * await base44.asServiceRole.entities.Clip.update(clipId, { video_id: id });
-     * ```
-     *
-     * @example
-     * ```typescript
      * // Route a support ticket with a structured evaluation
      * import { createClientFromRequest } from "@base44/sdk";
      * import { experimental_evaluate as evaluate } from "ai";

package/dist/modules/analytics.d.ts

@@ -1,6 +1,6 @@
 import { AxiosInstance } from "axios";
 import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
-import type { InternalAuthModule } from "./auth.types";
+import type { AuthModule } from "./auth.types";
 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__";
@@ -10,7 +10,7 @@ export interface AnalyticsModuleArgs {
     axiosClient: AxiosInstance;
     serverUrl: string;
     appId: string;
-    userAuthModule: InternalAuthModule;
+    userAuthModule: AuthModule;
     enabled: boolean;
 }
 export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }: AnalyticsModuleArgs) => {

package/dist/modules/analytics.js

@@ -196,9 +196,33 @@ function trackInitializationEvent(track) {
         eventName: ANALYTICS_INITIALIZATION_EVENT_NAME,
         properties: {
             referrer: document === null || document === void 0 ? void 0 : document.referrer,
+            ...getAttributionParams(),
         },
     });
 }
+// Allowlist, never the whole query string: landing URLs carry PII
+// (e.g. `utm_email`) and tokens.
+const ATTRIBUTION_PARAM_KEYS = [
+    "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id",
+    "gclid", "gbraid", "wbraid", "gad_source", "gad_campaignid",
+    "fbclid", "msclkid", "ttclid", "li_fat_id",
+];
+function getAttributionParams() {
+    try {
+        const params = new URLSearchParams(window.location.search);
+        const out = {};
+        for (const key of ATTRIBUTION_PARAM_KEYS) {
+            const value = params.get(key);
+            if (value)
+                out[key] = value.slice(0, 500);
+        }
+        return out;
+    }
+    catch (_a) {
+        // React Native has no `window.location`.
+        return {};
+    }
+}
 function setSessionDurationTimerStart() {
     if (typeof window === "undefined" ||
         analyticsSharedState.sessionStartTime !== null) {

package/dist/modules/auth.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { AuthModuleOptions, InternalAuthModule } from "./auth.types";
+import { AuthModuleOptions, AuthModule } from "./auth.types";
 /**
  * Creates the auth module for the Base44 SDK.
  *
@@ -10,4 +10,4 @@ import { AuthModuleOptions, InternalAuthModule } from "./auth.types";
  * @returns Auth module with authentication and user management methods
  * @internal
  */
-export declare function createAuthModule(axios: AxiosInstance, functionsAxiosClient: AxiosInstance, appId: string, options: AuthModuleOptions): InternalAuthModule;
+export declare function createAuthModule(axios: AxiosInstance, functionsAxiosClient: AxiosInstance, appId: string, options: AuthModuleOptions): AuthModule;

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

@@ -321,6 +321,20 @@ export interface AuthModule {
      * ```
      */
     isAuthenticated(): Promise<boolean>;
+    /**
+     * Checks whether an access token is currently set on the client.
+     *
+     * Reports only that a token is present, not that it's valid: an expired or revoked token still returns `true`. Use it to skip requests that can't succeed without a session, such as {@linkcode me | me()} for an anonymous visitor, and use {@linkcode isAuthenticated | isAuthenticated()} to confirm a session with the server. The token is the one passed to {@linkcode createClient | createClient()} or set with {@linkcode setToken | setToken()}, and {@linkcode logout | logout()} clears it. A session held only in an HTTP-only cookie isn't visible to the client and returns `false`.
+     *
+     * @returns `true` if the client has an access token, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * // Skip the user lookup for anonymous visitors
+     * const user = base44.auth.hasToken() ? await base44.auth.me() : null;
+     * ```
+     */
+    hasToken(): boolean;
     /**
      * Invites a user to the app.
      *
@@ -523,20 +537,3 @@ export interface AuthModule {
      */
     changePassword(params: ChangePasswordParams): Promise<any>;
 }
-/**
- * The auth module as constructed internally, before it is narrowed to
- * {@link AuthModule} on the public client. Not exported from the package
- * index — SDK consumers see only {@link AuthModule}.
- *
- * @internal
- */
-export interface InternalAuthModule extends AuthModule {
-    /**
-     * Whether an access token is currently set on the client.
-     *
-     * Reports only the presence of a token, never its validity — an expired or
-     * revoked token still reads as `true`. Callers use this to skip requests that
-     * could not succeed without a session, not to decide that one is valid.
-     */
-    hasToken(): boolean;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.52-pr.305.d6c90ab",
+  "version": "0.8.53-pr.289.39e1f1f",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",