@depup/base44__sdk 0.8.40-depup.0 → 0.8.41-depup.0

package/README.md

@@ -13,15 +13,16 @@ npm install @depup/base44__sdk
 
 | Field | Value |
 |-------|-------|
-| Original | [@base44/sdk](https://www.npmjs.com/package/@base44/sdk) @ 0.8.40 |
-| Processed | 2026-07-21 |
+| Original | [@base44/sdk](https://www.npmjs.com/package/@base44/sdk) @ 0.8.41 |
+| Processed | 2026-07-29 |
 | Smoke test | passed |
-| Deps updated | 1 |
+| Deps updated | 2 |
 
 ## Dependency Changes
 
 | Dependency | From | To |
 |------------|------|-----|
+| partysocket | ^0.0.23 | ^1.3.0 |
 | uuid | ^13.0.2 | ^14.0.1 |
 
 ---

package/changes.json

@@ -1,10 +1,14 @@
 {
   "bumped": {
+    "partysocket": {
+      "from": "^0.0.23",
+      "to": "^1.3.0"
+    },
     "uuid": {
       "from": "^13.0.2",
       "to": "^14.0.1"
     }
   },
-  "timestamp": "2026-07-21T16:02:37.704Z",
-  "totalUpdated": 1
+  "timestamp": "2026-07-29T16:33:33.820Z",
+  "totalUpdated": 2
 }

package/dist/actor.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
+ *
+ * At deploy time the bundler replaces this import with the compiled
+ * Cloudflare Durable Object implementation — this file provides types only.
+ */
+import type { Base44Client } from "./client";
+/**
+ * A single client connection. `Send` is the message type this connection accepts
+ * via {@link send} — the actor's *outgoing* (server→client) messages.
+ */
+export interface Conn<Send = unknown> {
+    /** Unique per-connection id (one per socket/tab), the same value the client
+     *  receives from `subscribe()`. Use this — not userId — to identify a distinct
+     *  client, so multiple tabs of the same user are separate connections. */
+    id: string;
+    userId: string;
+    appId: string;
+    instanceId: string;
+    send(data: Send): void;
+    reject(code: number, reason: string): void;
+}
+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. */
+    deleteAll(): Promise<void>;
+}
+/**
+ * Base class for an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this actor *sends* to clients
+ *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
+ *
+ * With a generated `schema.jsonc`, wire both from the registry so they can't drift
+ * from the client's types:
+ * ```ts
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export declare abstract class Actor<Incoming = unknown, Outgoing = unknown> {
+    abstract handleConnect(conn: Conn<Outgoing>): void | Promise<void>;
+    abstract handleMessage(conn: Conn<Outgoing>, msg: Incoming): void | Promise<void>;
+    abstract handleClose(conn: Conn<Outgoing>): void | Promise<void>;
+    abstract handleTick(): void | Promise<void>;
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart(): void | Promise<void>;
+    /**
+     * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+     * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+     * and stops (letting the Durable Object hibernate — no compute cost) when it
+     * returns false. The platform owns scheduling, rescheduling, self-heal, and
+     * error-safety — you don't call {@link startLoop}/{@link stopLoop}.
+     *
+     * Re-evaluated after every connect/message/close and on every tick, so keep it
+     * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+     */
+    protected tickIntervalMs: number;
+    protected shouldTick?(): boolean;
+    protected broadcast(_data: Outgoing): void;
+    protected getConnections(): Conn<Outgoing>[];
+    protected startLoop(_ms: number): Promise<void>;
+    protected stopLoop(): Promise<void>;
+    protected get instanceId(): string;
+    protected get storage(): Storage;
+    /**
+     * Anonymous Base44 client scoped to this actor instance — no user or service
+     * auth, so entity access is RLS-gated (same as a logged-out visitor). Always
+     * operates on production data: an actor runs server-side with no per-connection
+     * identity, so a Test DB preview selected in the editor does not apply here.
+     * Example: `const rows = await this.client.entities.Score.list();`
+     */
+    protected get client(): Base44Client;
+}

package/dist/actor.js

@@ -0,0 +1,73 @@
+/**
+ * Type-only base class for Actors.
+ *
+ * Import and extend this in your actor files:
+ *   import { Actor } from "@base44/sdk";
+ *   export class MyActor extends Actor { ... }
+ *
+ * At deploy time the bundler replaces this import with the compiled
+ * Cloudflare Durable Object implementation — this file provides types only.
+ */
+/**
+ * Base class for an Actor.
+ *
+ * @typeParam Incoming - messages this actor *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this actor *sends* to clients
+ *   (`conn.send`/`broadcast`) — the schema's `toClient` section.
+ *
+ * With a generated `schema.jsonc`, wire both from the registry so they can't drift
+ * from the client's types:
+ * ```ts
+ * type Reg = ActorRegistry["MyActor"];
+ * class MyActor extends Actor<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export class Actor {
+    constructor() {
+        /**
+         * Managed ticker (opt-in). Override {@link shouldTick} and the platform runs
+         * {@link handleTick} on a timer of {@link tickIntervalMs} while it returns true,
+         * and stops (letting the Durable Object hibernate — no compute cost) when it
+         * returns false. The platform owns scheduling, rescheduling, self-heal, and
+         * error-safety — you don't call {@link startLoop}/{@link stopLoop}.
+         *
+         * Re-evaluated after every connect/message/close and on every tick, so keep it
+         * cheap and pure (no async, no side effects). Example: `return this.players >= 2`.
+         */
+        this.tickIntervalMs = 100;
+    }
+    /**
+     * Optional wake hook: runs once when the instance starts, before any
+     * connection is handled — safe to load persisted state here.
+     */
+    handleStart() { }
+    broadcast(_data) {
+        throw new Error("Actor.broadcast() is only available inside a deployed actor");
+    }
+    getConnections() {
+        throw new Error("Actor.getConnections() is only available inside a deployed actor");
+    }
+    startLoop(_ms) {
+        throw new Error("Actor.startLoop() is only available inside a deployed actor");
+    }
+    stopLoop() {
+        throw new Error("Actor.stopLoop() is only available inside a deployed actor");
+    }
+    get instanceId() {
+        throw new Error("Actor.instanceId is only available inside a deployed actor");
+    }
+    get storage() {
+        throw new Error("Actor.storage is only available inside a deployed actor");
+    }
+    /**
+     * Anonymous Base44 client scoped to this actor instance — no user or service
+     * auth, so entity access is RLS-gated (same as a logged-out visitor). Always
+     * operates on production data: an actor runs server-side with no per-connection
+     * identity, so a Test DB preview selected in the editor does not apply here.
+     * Example: `const rows = await this.client.entities.Score.list();`
+     */
+    get client() {
+        throw new Error("Actor.client is only available inside a deployed actor");
+    }
+}

package/dist/client.js

@@ -12,6 +12,7 @@ import { createAppLogsModule } from "./modules/app-logs.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
 import { createAnalyticsModule } from "./modules/analytics.js";
+import { createActorsModule, resolveActorsHost } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
  *
@@ -50,7 +51,7 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  * ```
  */
 export function createClient(config) {
-    var _a, _b;
+    var _a, _b, _c;
     const { serverUrl = "https://base44.app", appId, 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 : "";
@@ -123,6 +124,14 @@ export function createClient(config) {
             userAuthModule.setToken(accessToken);
         }
     }
+    const actorsModule = createActorsModule({
+        appId,
+        // serverUrl is often relative/empty (same-origin app); PartySocket needs an
+        // absolute host, so fall back to the page origin.
+        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined),
+        functionsVersion,
+        getAuthToken: () => token || getAccessToken(),
+    });
     const userModules = {
         entities: createEntitiesModule({
             axios: axiosClient,
@@ -142,7 +151,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_a = functionsAxiosClient.defaults) === null || _a === void 0 ? void 0 : _a.baseURL,
+            baseURL: (_b = functionsAxiosClient.defaults) === null || _b === void 0 ? void 0 : _b.baseURL,
         }),
         agents: createAgentsModule({
             axios: axiosClient,
@@ -160,8 +169,10 @@ export function createClient(config) {
             appId,
             userAuthModule,
         }),
+        actors: actorsModule.module,
         cleanup: () => {
             userModules.analytics.cleanup();
+            actorsModule.closeAll();
             if (socket) {
                 socket.disconnect();
             }
@@ -185,7 +196,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_b = serviceRoleFunctionsAxiosClient.defaults) === null || _b === void 0 ? void 0 : _b.baseURL,
+            baseURL: (_c = serviceRoleFunctionsAxiosClient.defaults) === null || _c === void 0 ? void 0 : _c.baseURL,
         }),
         agents: createAgentsModule({
             axios: serviceRoleAxiosClient,

package/dist/client.types.d.ts

@@ -8,6 +8,7 @@ import type { AgentsModule } from "./modules/agents.types.js";
 import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
+import type { ActorsModule } from "./modules/actors.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -88,6 +89,8 @@ export interface Base44Client {
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
+    /** {@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. */
     auth: AuthModule;
     /** {@link UserConnectorsModule | Connectors module} for app-user OAuth flows. */
@@ -139,9 +142,7 @@ export interface Base44Client {
         functions: FunctionsModule;
         /** {@link IntegrationsModule | Integrations module} with elevated permissions. */
         integrations: IntegrationsModule;
-        /** {@link SsoModule | SSO module} for generating SSO tokens.
-         * @internal
-         */
+        /** {@link SsoModule | SSO module} for generating SSO tokens. */
         sso: SsoModule;
         /** Cleanup function to disconnect WebSocket connections. */
         cleanup: () => void;

package/dist/index.d.ts

@@ -11,7 +11,9 @@ 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 { 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";
 export type { ConnectorsModule, UserConnectorsModule, } 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";

package/dist/index.js

@@ -3,3 +3,4 @@ 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 { Actor } from "./actor.js";

package/dist/modules/actors.d.ts

@@ -0,0 +1,25 @@
+import type { ActorRef } from "./actors.types.js";
+interface ActorsConfig {
+    appId: string;
+    /** Current user access token, if authenticated. Rides the WS query so the
+     * platform proxy can authenticate the connection; anonymous connects omit it. */
+    getAuthToken(): string | null | undefined;
+    /** Same semantics as function calls: editors with a non-prod version get the
+     * draft actor script; everyone else gets the published one. */
+    functionsVersion?: string;
+    /** Absolute host PartySocket dials (it strips the scheme and connects wss, ws
+     * for localhost). Resolved by {@link resolveActorsHost}. */
+    host: string;
+}
+/**
+ * Absolute host for the actor WebSocket. PartySocket needs an absolute host and
+ * can't resolve a relative/empty `serverUrl` (same-origin apps use a relative
+ * `/api`, so `serverUrl` is often `""`), so fall back to the page origin.
+ * PartySocket handles the scheme (https→wss, ws for localhost).
+ */
+export declare function resolveActorsHost(serverUrl: string, browserOrigin?: string): string;
+export declare function createActorsModule(config: ActorsConfig): {
+    module: Record<string, (instanceId: string) => ActorRef>;
+    closeAll: () => void;
+};
+export {};

package/dist/modules/actors.js

@@ -0,0 +1,135 @@
+import PartySocket from "partysocket";
+// Heartbeat / half-open detection: PartySocket only reconnects on a close/error
+// event, so ping periodically and force a reconnect if nothing returns in DEAD_MS.
+const PING_MS = 1000;
+const DEAD_MS = 3000;
+/**
+ * A live connection to an actor instance. Only obtainable from
+ * {@link ActorRef.connect}, so `subscribe`/`send` are always valid — the socket
+ * exists for this object's whole lifetime.
+ */
+class Connection {
+    constructor(actorName, instanceId, config, options, onClose) {
+        var _a;
+        this.onClose = onClose;
+        this.listeners = new Set();
+        this.heartbeat = null;
+        this.id = (_a = options === null || options === void 0 ? void 0 : options.id) !== null && _a !== void 0 ? _a : crypto.randomUUID();
+        const ws = new PartySocket({
+            host: config.host,
+            party: actorName,
+            room: instanceId,
+            id: this.id,
+            // Re-read on every (re)connect so a login/logout is picked up.
+            query: () => {
+                const token = config.getAuthToken();
+                return {
+                    app_id: config.appId,
+                    handler: actorName,
+                    ...(token ? { token } : {}),
+                    ...(config.functionsVersion ? { fv: config.functionsVersion } : {}),
+                };
+            },
+        });
+        this.ws = ws;
+        let lastMsg = Date.now();
+        const bumpAlive = () => { lastMsg = Date.now(); };
+        ws.addEventListener("open", bumpAlive);
+        ws.addEventListener("message", (ev) => {
+            bumpAlive();
+            let data;
+            try {
+                data = JSON.parse(ev.data);
+            }
+            catch (_a) {
+                return;
+            }
+            const msgType = data && typeof data === "object" ? data.type : undefined;
+            if (msgType === "__pong")
+                return;
+            for (const listener of this.listeners)
+                listener(data);
+        });
+        this.heartbeat = setInterval(() => {
+            if (Date.now() - lastMsg > DEAD_MS) {
+                bumpAlive(); // avoid a reconnect storm while the new socket comes up
+                ws.reconnect();
+                return;
+            }
+            try {
+                // The deployed shim echoes __ping → __pong (base44-userapp-bundler
+                // shim/actor.ts); without that, an idle room reconnects every DEAD_MS.
+                ws.send(JSON.stringify({ type: "__ping" }));
+            }
+            catch (_a) {
+                // not open; the watchdog above will reconnect
+            }
+        }, PING_MS);
+    }
+    subscribe(callback) {
+        this.listeners.add(callback);
+        return {
+            unsubscribe: () => { this.listeners.delete(callback); },
+        };
+    }
+    send(data) {
+        this.ws.send(JSON.stringify(data));
+    }
+    close() {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+        this.listeners.clear();
+        this.ws.close();
+        this.onClose();
+    }
+}
+/** Handle for one actor instance: `connect()` opens the socket (idempotent). */
+function makeActorRef(actorName, instanceId, config, connections) {
+    let conn = null;
+    return {
+        connect(options) {
+            if (conn)
+                return conn;
+            const c = new Connection(actorName, instanceId, config, options, () => {
+                connections.delete(c);
+                if (conn === c)
+                    conn = null; // allow a fresh connect() after close
+            });
+            conn = c;
+            connections.add(c);
+            return c;
+        },
+    };
+}
+/**
+ * Absolute host for the actor WebSocket. PartySocket needs an absolute host and
+ * can't resolve a relative/empty `serverUrl` (same-origin apps use a relative
+ * `/api`, so `serverUrl` is often `""`), so fall back to the page origin.
+ * PartySocket handles the scheme (https→wss, ws for localhost).
+ */
+export function resolveActorsHost(serverUrl, browserOrigin) {
+    return serverUrl && !serverUrl.startsWith("/") ? serverUrl : browserOrigin !== null && browserOrigin !== void 0 ? browserOrigin : serverUrl;
+}
+export function createActorsModule(config) {
+    // Live connections this client opened, so client.cleanup() can reclaim any the
+    // app forgot to close() (each connection removes itself here on close).
+    const connections = new Set();
+    const module = new Proxy({}, {
+        get(_, key) {
+            // Symbols and `then` resolve to undefined (so the module isn't mistaken
+            // for a thenable when awaited); any string key is an actor name.
+            if (typeof key !== "string" || key === "then")
+                return undefined;
+            return (instanceId) => makeActorRef(key, instanceId, config, connections);
+        },
+    });
+    return {
+        module,
+        closeAll: () => {
+            for (const c of [...connections])
+                c.close();
+        },
+    };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed Actors.
+ *
+ * This is separate from {@link ActorNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
+ *
+ * @example
+ * ```typescript
+ * declare module "@base44/sdk" {
+ *   interface ActorRegistry {
+ *     ChatRoom: {
+ *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
+ *       toServer: { type: "message"; text: string };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+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.
+ */
+export interface ActorNameRegistry {
+}
+type AllActorNames = keyof ActorRegistry | keyof ActorNameRegistry;
+type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toClient: infer I;
+} ? I : unknown : unknown;
+type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
+    toServer: infer O;
+} ? O : unknown : unknown;
+/** Options for {@link ActorRef.connect}. */
+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.
+     */
+    id?: string;
+}
+/** Handle for one listener registered via {@link Connection.subscribe}. */
+export interface ActorSubscription {
+    /** Remove this listener; other listeners and the socket stay live. */
+    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.
+ */
+export interface Connection<N extends string = string> {
+    /** The connection id (the value the actor sees as `conn.id`). */
+    readonly id: string;
+    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
+    /** Send a message. Buffered by the socket until it's open. */
+    send(data: ToServerFor<N>): void;
+    /** Tear down the socket, heartbeat, and all listeners. */
+    close(): void;
+}
+/**
+ * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
+ * {@link connect} to open the socket and get a {@link Connection}.
+ */
+export interface ActorRef<N extends string = string> {
+    /** Open the WebSocket and return the {@link Connection}. Idempotent. */
+    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}.
+ */
+export interface ActorClient<N extends string = string> {
+    (instanceId: string): ActorRef<N>;
+}
+/**
+ * The actors module provides access to Cloudflare Durable Object-backed
+ * Actors deployed by the Base44 platform.
+ *
+ * ```typescript
+ * const conn = base44.actors.MyActor("room-1").connect();
+ * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * conn.send({ type: "message", text: "hi" });
+ * sub.unsubscribe();
+ * conn.close();
+ * ```
+ */
+export type ActorsModule = {
+    [K in AllActorNames]: K extends keyof ActorRegistry ? ActorClient<string & K> : ActorClient;
+} & Record<string, ActorClient>;
+export {};

package/dist/modules/actors.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,13 +1,13 @@
 /**
- * A connection to the Base44 AI Gateway.
- *
- * Contains the base URL and bearer token to use with any OpenAI-compatible
- * client pointed at the Base44 AI Gateway.
+ * Connection details for the Base44 AI Gateway.
  */
 export interface AiGatewayConnection {
-    /** Base URL of the gateway's OpenAI-compatible endpoint. */
+    /** Base URL of the gateway's OpenAI-compatible Chat Completions endpoint. */
     baseURL: string;
-    /** Bearer token used to authenticate requests to the gateway. */
+    /**
+     * Bearer token that authenticates the request. Empty string when the caller is
+     * unauthenticated.
+     */
     token: string;
 }
 /**
@@ -25,13 +25,45 @@ export interface AiGatewayModuleConfig {
 /**
  * AI Gateway module for calling Base44's managed AI models from your own code.
  *
- * The gateway exposes an OpenAI-compatible Chat Completions endpoint, so any
- * OpenAI-compatible SDK works against it:
- * - Build custom AI agents or call models directly from your backend code
- * - Uses your app's models, billing, and credit quota, no API key to manage
+ * `connection()` hands you a `baseURL` and `token` 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 Chat Completions API and lets you point it at a custom `baseURL`
+ * instead of OpenAI's own servers. Pass `connection()`'s values to one of
+ * these clients and it works against Base44's gateway exactly as it would
+ * against the provider directly, no separate account, API key, or billing
+ * setup with the underlying model provider required.
+ *
+ * Call `connection()` from a backend function rather than the browser. This
+ * keeps your instructions, tools, and business logic server-side, and lets
+ * you enforce your own auth, rate, and spend limits around the call. The
+ * `token` it returns is the caller's regular session token, the same one
+ * used for every other SDK call.
+ *
+ * ## Models
+ *
+ * You can use any of the [models available through `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm).
+ * Pass `'automatic'` to let Base44 choose one, or pin a specific model such
+ * as `'claude_sonnet_4_6'`, `'gpt_5_5'`, or `'gemini_3_1_pro'`.
+ *
+ * ## Authentication Modes
+ *
+ * There's no permission difference between modes. Both just determine 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, for calling the gateway when there's no signed-in user, such as from a scheduled automation.
+ *
+ * ## Billing and limits
+ *
+ * Requests are billed to your app's credit quota, which is the same shared
+ * quota your app's built-in AI features use, and isn't split per user. If the
+ * app runs out of credits, the gateway stops working for every user of the
+ * app until the quota resets. A request is rejected before the model runs if
+ * the app is out of credits. If you need to cap usage per user, build that
+ * check yourself, for example by tracking calls per user in your own entity.
  *
- * Available in user authentication mode (`base44.aiGateway`) and with the
- * service-role token via `base44.asServiceRole.aiGateway`.
+ * Streaming responses aren't supported yet, so leave `stream` unset on your requests.
  */
 export interface AiGatewayModule {
     /**
@@ -39,19 +71,38 @@ export interface AiGatewayModule {
      *
      * Returns the `baseURL` and `token` to pass to any OpenAI-compatible client.
      *
-     * The `token` is the current caller's bearer token: the app user's token for
-     * `base44.aiGateway`, or the service-role token for `base44.asServiceRole.aiGateway`.
-     * When the caller is unauthenticated, `token` is an empty string.
-     *
      * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`).
      *
      * @example
      * ```typescript
+     * // Call a model directly
+     * import { createClientFromRequest } from "@base44/sdk";
+     * import OpenAI from "openai";
+     *
+     * // Runs inside a backend function
+     * const base44 = createClientFromRequest(request);
+     * const { baseURL, token } = base44.aiGateway.connection();
+     * const openai = new OpenAI({ baseURL, apiKey: token });
+     *
+     * const response = await openai.chat.completions.create({
+     *   model: "automatic",
+     *   messages: [{ role: "user", content: "Summarize this week's top support tickets." }],
+     * });
+     *
+     * console.log(response.choices[0].message.content);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use a tool-calling agent
+     * import { createClientFromRequest } from "@base44/sdk";
      * import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai";
      * import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
      * import { z } from "zod";
      *
-     * const request = await base44.entities.ReturnRequest.get(returnId);
+     * // Runs inside a backend function, reviewing a return request
+     * const base44 = createClientFromRequest(request);
+     * const returnRequest = await base44.entities.ReturnRequest.get(returnId);
      * const { baseURL, token } = base44.aiGateway.connection();
      * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token`.
      * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
@@ -66,7 +117,7 @@ export interface AiGatewayModule {
      *       description: "This customer's past orders, optionally filtered by status",
      *       inputSchema: z.object({ status: z.string().optional() }),
      *       execute: ({ status }) => {
-     *         const query = { customer_email: request.customer_email };
+     *         const query = { customer_email: returnRequest.customer_email };
      *         if (status) query.status = status;
      *         return base44.entities.Order.filter(query, "-created_date", 50);
      *       },
@@ -81,7 +132,7 @@ export interface AiGatewayModule {
      *   stopWhen: [stepCountIs(8), hasToolCall("submitVerdict")],
      * });
      *
-     * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(request)}` });
+     * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });
      * ```
      */
     connection(): AiGatewayConnection;

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

@@ -1,6 +1,5 @@
 /**
  * Response from SSO access token endpoint.
- * @internal
  */
 export interface SsoAccessTokenResponse {
     access_token: string;
@@ -13,46 +12,53 @@ export interface SsoAccessTokenResponse {
  * services.
  *
  * This module is only available to use with a client in service role authentication mode, which means it can only be used in backend environments.
- *
- * @internal
- *
- * @example
- * ```typescript
- * // Access SSO module with service role
- * const response = await base44.asServiceRole.sso.getAccessToken('user_123');
- * console.log(response.data.access_token);
- * ```
  */
 export interface SsoModule {
     /**
-     * Gets SSO access token for a specific user.
+     * Gets an SSO access token for the user who made the current request.
      *
-     * Retrieves a Single Sign-On access token that can be used to authenticate
-     * a user with external services or systems.
+     * Use this token to authenticate the user with external systems or services.
+     * This only works for that same user. Create the client with
+     * {@link createClientFromRequest} so it acts on behalf of the request's user,
+     * then pass that user's ID as `userid`. If `userid` is any other user, the
+     * call fails. An expired token is refreshed automatically when a refresh token
+     * is available.
      *
-     * @param userid - The user ID to get the access token for.
+     * @param userid - The ID of the user who made the current request, such as the
+     * `id` returned by {@link AuthModule | base44.auth.me()}.
      * @returns Promise resolving to the SSO access token response.
      *
      * @example
      * ```typescript
-     * // Get SSO access token for a user
-     * const response = await base44.asServiceRole.sso.getAccessToken('user_123');
-     * console.log(response.access_token);
+     * // Get the user's SSO access token to call an external system
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const user = await base44.auth.me();
+     *   const { access_token } = await base44.asServiceRole.sso.getAccessToken(user.id);
+     *
+     *   return Response.json({ access_token });
+     * });
      * ```
      */
     getAccessToken(userid: string): Promise<SsoAccessTokenResponse>;
     /**
-     * Gets the stored SSO OIDC ID token for the current app user.
+     * Gets the stored SSO OIDC ID token for the user who made the current request.
      *
-     * The service-role client must include an on-behalf-of token for the same
-     * user specified by `userid`. This method returns the stored token as-is and
-     * does not refresh it.
+     * This only works for that same user, not for arbitrary users. Create the
+     * client with {@link createClientFromRequest} so it acts on behalf of the
+     * request's user, then pass that user's ID as `userid`. If `userid` is any
+     * other user, the call fails. The stored token is returned as-is and is never
+     * refreshed, so the call fails if the token has already expired.
      *
-     * @param userid - The current app user's ID.
+     * @param userid - The ID of the user who made the current request, such as the
+     * `id` returned by {@link AuthModule | base44.auth.me()}.
      * @returns Promise resolving to the raw ID-token string.
      *
      * @example
      * ```typescript
+     * // Get the user's ID token to read identity claims such as email
      * import { createClientFromRequest } from 'npm:@base44/sdk';
      *
      * Deno.serve(async (req) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depup/base44__sdk",
-  "version": "0.8.40-depup.0",
+  "version": "0.8.41-depup.0",
   "description": "JavaScript SDK for Base44 API (with updated dependencies)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "axios": "^1.18.1",
+    "partysocket": "^1.3.0",
     "socket.io-client": "^4.8.3",
     "uuid": "^14.0.1"
   },
@@ -72,15 +73,19 @@
   "homepage": "https://github.com/base44/javascript-sdk#readme",
   "depup": {
     "changes": {
+      "partysocket": {
+        "from": "^0.0.23",
+        "to": "^1.3.0"
+      },
       "uuid": {
         "from": "^13.0.2",
         "to": "^14.0.1"
       }
     },
-    "depsUpdated": 1,
+    "depsUpdated": 2,
     "originalPackage": "@base44/sdk",
-    "originalVersion": "0.8.40",
-    "processedAt": "2026-07-21T16:02:47.902Z",
+    "originalVersion": "0.8.41",
+    "processedAt": "2026-07-29T16:34:30.935Z",
     "smokeTest": "passed"
   }
 }