@base44-preview/sdk 0.8.40-pr.212.5212229 → 0.8.40-pr.212.8d7ec0a

package/dist/client.js

@@ -52,19 +52,19 @@ import { createActorsModule } from "./modules/actors.js";
  */
 export function createClient(config) {
     var _a, _b;
-    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, dispatcherWsUrl, webSocketImpl, } = config;
+    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, actorsWsUrl, } = config;
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
-    // Derive the dispatcher WebSocket URL if not explicitly provided. Default to
+    // Derive the Actor WebSocket URL if not explicitly provided. Default to
     // the app's OWN origin (the app URL proxies /parties to the backend) so the
     // socket is same-origin with the running app, not the API host: prefer an
     // explicit appBaseUrl, then the browser origin, then fall back to serverUrl
     // (Node/SSR, where there's no window). Convert https:// → wss:// (http → ws)
     // and strip the trailing slash.
-    const resolvedDispatcherWsUrl = (() => {
+    const resolvedActorsWsUrl = (() => {
         var _a, _b;
-        if (dispatcherWsUrl)
-            return dispatcherWsUrl.replace(/\/$/, "");
+        if (actorsWsUrl)
+            return actorsWsUrl.replace(/\/$/, "");
         const appOrigin = normalizedAppBaseUrl ||
             // React Native has a bare `window` with no `location`, so guard both.
             (typeof window !== "undefined" ? (_b = (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin) !== null && _b !== void 0 ? _b : "" : "");
@@ -181,11 +181,8 @@ export function createClient(config) {
         }),
         actors: createActorsModule({
             appId,
-            dispatcherWsUrl: resolvedDispatcherWsUrl,
-            webSocketImpl,
+            actorsWsUrl: resolvedActorsWsUrl,
             functionsVersion,
-            // Same credential as function calls; the platform proxy authenticates the
-            // WS connection with it (anonymous when absent) — no pre-connect token mint.
             getAuthToken: () => token || getAccessToken(),
         }),
         cleanup: () => {

package/dist/client.types.d.ts

@@ -75,27 +75,15 @@ export interface CreateClientConfig {
      */
     options?: CreateClientOptions;
     /**
-     * Base WebSocket URL for the Cloudflare Durable Object dispatcher.
+     * Base WebSocket URL for Actor connections.
      *
      * Defaults to the app's own origin (`appBaseUrl`, else the browser's
      * `window.location.origin`, else `serverUrl`) with `https://` replaced by
-     * `wss://` (or `http://` by `ws://`) — so the realtime socket is same-origin
-     * with the running app, which proxies `/parties` to the backend.
-     * Override when the dispatcher lives at a different host than the app.
+     * `wss://` (or `http://` by `ws://`) — so the Actor socket is same-origin
+     * with the running app, which proxies `/parties` to the backend dispatcher.
+     * Override only when the Actor host differs from the app origin.
      */
-    dispatcherWsUrl?: string;
-    /**
-     * WebSocket implementation for realtime subscriptions in environments
-     * without a global `WebSocket` (Node.js < 22). Browsers and Node ≥ 22
-     * don't need this.
-     *
-     * @example
-     * ```typescript
-     * import WS from "ws";
-     * const base44 = createClient({ appId, webSocketImpl: WS });
-     * ```
-     */
-    webSocketImpl?: unknown;
+    actorsWsUrl?: string;
 }
 /**
  * The Base44 client instance.
@@ -164,9 +152,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/modules/actors.d.ts

@@ -7,9 +7,7 @@ interface ActorsConfig {
     /** Same semantics as function calls: editors with a non-prod version get the
      * draft actor script; everyone else gets the published one. */
     functionsVersion?: string;
-    dispatcherWsUrl: string;
-    /** WebSocket implementation for runtimes without a global one (Node < 22). */
-    webSocketImpl?: unknown;
+    actorsWsUrl: string;
 }
 export declare function createActorsModule(config: ActorsConfig): Record<string, (instanceId: string) => ActorRoom>;
 export {};

package/dist/modules/actors.js

@@ -27,11 +27,10 @@ class Room {
         const connId = (_a = options === null || options === void 0 ? void 0 : options.id) !== null && _a !== void 0 ? _a : crypto.randomUUID();
         this.connId = connId;
         const ws = new PartySocket({
-            host: this.config.dispatcherWsUrl,
+            host: this.config.actorsWsUrl,
             party: this.actorName,
             room: this.instanceId,
             id: connId,
-            ...(this.config.webSocketImpl ? { WebSocket: this.config.webSocketImpl } : {}),
             // Re-read on every (re)connect so a login/logout is picked up.
             query: () => {
                 const token = this.config.getAuthToken();
@@ -54,11 +53,11 @@ class Room {
                 data = JSON.parse(ev.data);
             }
             catch (_a) {
-                return; // ignore malformed
+                return;
             }
             const msgType = data && typeof data === "object" ? data.type : undefined;
             if (msgType === "__pong")
-                return; // platform message — never surface it
+                return;
             for (const listener of this.listeners)
                 listener(data);
         });
@@ -69,10 +68,12 @@ class Room {
                 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) {
-                // socket not open; the watchdog above will force a reconnect
+                // not open; the watchdog above will reconnect
             }
         }, PING_MS);
         return this;

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": "@base44-preview/sdk",
-  "version": "0.8.40-pr.212.5212229",
+  "version": "0.8.40-pr.212.8d7ec0a",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",