@base44-preview/sdk 0.8.35-pr.212.2fe0031 → 0.8.35-pr.212.36b2685

package/dist/client.js

@@ -7,6 +7,7 @@ import { createConnectorsModule, createUserConnectorsModule, } from "./modules/c
 import { getAccessToken } from "./utils/auth-utils.js";
 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 { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
@@ -161,6 +162,7 @@ export function createClient(config) {
             serverUrl,
             token,
         }),
+        aiGateway: createAiGatewayModule({ serverUrl, appBaseUrl: normalizedAppBaseUrl, token }),
         appLogs: createAppLogsModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
         analytics: createAnalyticsModule({
@@ -172,9 +174,15 @@ export function createClient(config) {
         realtime: createRealtimeModule({
             appId,
             dispatcherWsUrl: resolvedDispatcherWsUrl,
-            getToken: async (handlerName, instanceId) => {
-                // axiosClient interceptors unwrap response.data, so the result is the body directly
-                const data = await axiosClient.post(`/apps/${appId}/realtime-token`, { handler_name: handlerName, instance_id: instanceId });
+            getToken: async (handlerName, instanceId, connId) => {
+                // axiosClient interceptors unwrap response.data, so the result is the body directly.
+                // conn_id rides inside the signed token (not a WS query param) so it survives
+                // proxies that strip params; the dispatcher forwards it as the handler's conn.id.
+                // Base44-Functions-Version rides along (like function calls) so live apps get
+                // tokens for the *published* realtime script and previews get the draft.
+                const data = await axiosClient.post(`/apps/${appId}/realtime-token`, { handler_name: handlerName, instance_id: instanceId, conn_id: connId }, functionsVersion
+                    ? { headers: { "Base44-Functions-Version": functionsVersion } }
+                    : undefined);
                 return data.token;
             },
         }),
@@ -212,6 +220,7 @@ export function createClient(config) {
             serverUrl,
             token,
         }),
+        aiGateway: createAiGatewayModule({ serverUrl, appBaseUrl: normalizedAppBaseUrl, token: serviceToken }),
         appLogs: createAppLogsModule(serviceRoleAxiosClient, appId),
         cleanup: () => {
             if (socket) {
@@ -361,6 +370,7 @@ export function createClientFromRequest(request) {
     const serviceRoleAuthHeader = request.headers.get("Base44-Service-Authorization");
     const appId = request.headers.get("Base44-App-Id");
     const serverUrlHeader = request.headers.get("Base44-Api-Url");
+    const appBaseUrlHeader = request.headers.get("Base44-App-Base-Url");
     const functionsVersion = request.headers.get("Base44-Functions-Version");
     const stateHeader = request.headers.get("Base44-State");
     if (!appId) {
@@ -392,6 +402,7 @@ export function createClientFromRequest(request) {
     }
     return createClient({
         serverUrl: serverUrlHeader || "https://base44.app",
+        appBaseUrl: appBaseUrlHeader !== null && appBaseUrlHeader !== void 0 ? appBaseUrlHeader : undefined,
         appId,
         token: userToken,
         serviceToken: serviceRoleToken,

package/dist/client.types.d.ts

@@ -5,6 +5,7 @@ import type { SsoModule } from "./modules/sso.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 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 { AnalyticsModule } from "./modules/analytics.types.js";
 import type { RealtimeModule } from "./modules/realtime.types.js";
@@ -89,6 +90,8 @@ export interface CreateClientConfig {
 export interface Base44Client {
     /** {@link AgentsModule | Agents module} for managing AI agent conversations. */
     agents: AgentsModule;
+    /** {@link AiGatewayModule | AI Gateway module} for connecting to the Base44 AI Gateway with your own SDK. */
+    aiGateway: AiGatewayModule;
     /** {@link AnalyticsModule | Analytics module} for tracking custom events in your app. */
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
@@ -134,6 +137,8 @@ export interface Base44Client {
     readonly asServiceRole: {
         /** {@link AgentsModule | Agents module} with elevated permissions. */
         agents: AgentsModule;
+        /** {@link AiGatewayModule | AI Gateway module} with the service-role token. */
+        aiGateway: AiGatewayModule;
         /** {@link AppLogsModule | App logs module} with elevated permissions. */
         appLogs: AppLogsModule;
         /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */

package/dist/index.d.ts

@@ -9,8 +9,9 @@ export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, Change
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
 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 { RealtimeModule, RealtimeHandlerClient, RealtimeSubscription, } from "./modules/realtime.types.js";
+export type { RealtimeModule, RealtimeHandlerClient, RealtimeHandlerNameRegistry, RealtimeHandlerRegistry, } from "./modules/realtime.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export { RealtimeHandler, type Conn } from "./realtime-handler.js";
 export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";

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

@@ -0,0 +1,2 @@
+import { AiGatewayModule, AiGatewayModuleConfig } from "./ai-gateway.types.js";
+export declare function createAiGatewayModule({ serverUrl, appBaseUrl, token, }: AiGatewayModuleConfig): AiGatewayModule;

package/dist/modules/ai-gateway.js

@@ -0,0 +1,14 @@
+import { getAccessToken } from "../utils/auth-utils.js";
+export function createAiGatewayModule({ serverUrl, appBaseUrl, token, }) {
+    const gatewayOrigin = appBaseUrl || serverUrl;
+    const connection = () => {
+        var _a;
+        return ({
+            baseURL: `${gatewayOrigin}/api/ai/openai/v1`,
+            token: (_a = token !== null && token !== void 0 ? token : getAccessToken()) !== null && _a !== void 0 ? _a : "",
+        });
+    };
+    return {
+        connection,
+    };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * A connection to the Base44 AI Gateway.
+ *
+ * Contains the base URL and bearer token to use with any OpenAI-compatible client
+ * (OpenAI SDK, Mastra, Vercel AI SDK, and others) pointed at the Base44 AI
+ * Gateway.
+ */
+export interface AiGatewayConnection {
+    /** Base URL of the gateway's OpenAI-compatible endpoint. */
+    baseURL: string;
+    /** Bearer token used to authenticate requests to the gateway. */
+    token: string;
+}
+/**
+ * Configuration for the AI Gateway module.
+ * @internal
+ */
+export interface AiGatewayModuleConfig {
+    /** Server URL */
+    serverUrl?: string;
+    /** The app's own public base URL (e.g. https://my-app.base44.app). */
+    appBaseUrl?: string;
+    /** Authentication token */
+    token?: string;
+}
+/**
+ * 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 with agent SDKs such as Mastra or the Vercel AI SDK
+ * - Uses your app's models, billing, and credit quota, no API key to manage
+ *
+ * Available in user authentication mode (`base44.aiGateway`) and with the
+ * service-role token via `base44.asServiceRole.aiGateway`.
+ */
+export interface AiGatewayModule {
+    /**
+     * Gets the connection details for the Base44 AI Gateway.
+     *
+     * 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
+     * // Build an AI agent with Mastra on top of the gateway, inside a backend function
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     * import { Agent } from 'npm:@mastra/core/agent';
+     * import { createTool } from 'npm:@mastra/core/tools';
+     * import { createOpenAICompatible } from 'npm:@ai-sdk/openai-compatible';
+     * import { z } from 'npm:zod';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const { baseURL, token } = base44.aiGateway.connection();
+     *   const models = createOpenAICompatible({ name: 'base44', baseURL, apiKey: token });
+     *
+     *   const agent = new Agent({
+     *     id: 'order-helper',
+     *     name: 'order-helper',
+     *     instructions: 'Help the user with their orders.',
+     *     model: models('claude_sonnet_4_6'),
+     *     tools: {
+     *       lookupOrder: createTool({
+     *         id: 'lookup-order',
+     *         description: 'Fetch an order by id',
+     *         inputSchema: z.object({ orderId: z.string() }),
+     *         execute: async ({ orderId }) => base44.entities.Order.get(orderId),
+     *       }),
+     *     },
+     *   });
+     *
+     *   const { text } = await agent.generate('Where is order 123?');
+     *   return Response.json({ text });
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Call a model directly with the OpenAI SDK
+     * import { createClientFromRequest } from 'npm:@base44/sdk';
+     * import OpenAI from 'npm:openai';
+     *
+     * Deno.serve(async (req) => {
+     *   const base44 = createClientFromRequest(req);
+     *   const { baseURL, token } = base44.aiGateway.connection();
+     *
+     *   const openai = new OpenAI({ baseURL, apiKey: token });
+     *   const res = await openai.chat.completions.create({
+     *     model: 'claude_sonnet_4_6',
+     *     messages: [{ role: 'user', content: 'Hello!' }],
+     *   });
+     *   return Response.json({ text: res.choices[0].message.content });
+     * });
+     * ```
+     */
+    connection(): AiGatewayConnection;
+}

package/dist/modules/ai-gateway.types.js

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

package/dist/modules/realtime.d.ts

@@ -1,13 +1,19 @@
 export declare function createRealtimeModule(config: {
     appId: string;
-    getToken(handlerName: string, instanceId: string): Promise<string>;
+    getToken(handlerName: string, instanceId: string, connId: string): Promise<string>;
     dispatcherWsUrl: string;
 }): Record<string, RealtimeHandler>;
+/** Handle for an active realtime subscription. */
+interface RealtimeSubscription {
+    /** This connection's id — the same value the handler receives as `conn.id`. */
+    id: string;
+    /** Close the subscription and its underlying socket. */
+    unsubscribe(): void;
+}
 interface RealtimeHandler {
-    subscribe(instanceId: string, callback: (data: unknown) => void): Promise<{
-        send(data: unknown): void;
-        close(): void;
-    }>;
+    subscribe(instanceId: string, callback: (data: unknown) => void, options?: {
+        id?: string;
+    }): RealtimeSubscription;
     send(instanceId: string, data: unknown): void;
 }
 export {};

package/dist/modules/realtime.js

@@ -8,44 +8,69 @@ export function createRealtimeModule(config) {
     return new Proxy({}, {
         get(_, handlerName) {
             return {
-                async subscribe(instanceId, callback) {
-                    var _a;
+                subscribe(instanceId, callback, options) {
+                    var _a, _b;
                     const key = socketKey(handlerName, instanceId);
                     // close existing if any
                     (_a = activeSockets.get(key)) === null || _a === void 0 ? void 0 : _a.close();
-                    const token = await config.getToken(handlerName, instanceId);
+                    // Connection id: caller-supplied (stable — reuse across reconnects/tabs as
+                    // you see fit) or auto-generated per subscription. It travels INSIDE the
+                    // signed realtime token (never as a WS query param, which proxies strip);
+                    // the dispatcher forwards the verified claim as partyserver's _pk, so the
+                    // handler sees this exact value as conn.id. Reconnects re-mint the token
+                    // with the same id, so conn.id is stable across reconnects.
+                    const connId = (_b = options === null || options === void 0 ? void 0 : options.id) !== null && _b !== void 0 ? _b : crypto.randomUUID();
+                    // query as async fn: called on every (re)connect, fetches a fresh token each time
                     const ws = new PartySocket({
                         host: config.dispatcherWsUrl,
                         party: handlerName,
                         room: instanceId,
-                        query: { token },
+                        query: () => config.getToken(handlerName, instanceId, connId).then((token) => ({ token })),
                     });
                     activeSockets.set(key, ws);
+                    // Heartbeat / half-open detection. PartySocket only reconnects on a
+                    // browser close/error event, so a silently-dead connection (TCP alive,
+                    // no data — common behind proxies/LBs) hangs until the OS idle timeout
+                    // (~60s). We ping periodically and force a reconnect if nothing comes
+                    // back within DEAD_MS, cutting detection from ~60s to a few seconds.
+                    // Pairs with the handler's setWebSocketAutoResponse("__ping"→"__pong"),
+                    // so idle handlers (no app broadcasts) still keep the connection proven.
+                    const PING_MS = 1000;
+                    const DEAD_MS = 3000;
+                    let lastMsg = Date.now();
+                    const bumpAlive = () => { lastMsg = Date.now(); };
+                    ws.addEventListener("open", bumpAlive);
                     ws.addEventListener("message", (ev) => {
+                        bumpAlive();
+                        let data;
                         try {
-                            callback(JSON.parse(ev.data));
+                            data = JSON.parse(ev.data);
                         }
                         catch (_a) {
-                            // ignore malformed
+                            return; // ignore malformed
                         }
+                        // Swallow heartbeat acks — never surface them to the app.
+                        if (data && typeof data === "object" && data.type === "__pong")
+                            return;
+                        callback(data);
                     });
-                    // Re-fetch token on reconnect
-                    ws.addEventListener("close", async () => {
-                        if (activeSockets.get(key) !== ws)
-                            return; // replaced
+                    const heartbeat = setInterval(() => {
+                        if (Date.now() - lastMsg > DEAD_MS) {
+                            bumpAlive(); // avoid a reconnect storm while the new socket comes up
+                            ws.reconnect();
+                            return;
+                        }
                         try {
-                            const newToken = await config.getToken(handlerName, instanceId);
-                            ws.updateProperties({ query: { token: newToken } });
+                            ws.send(JSON.stringify({ type: "__ping" }));
                         }
                         catch (_a) {
-                            // ignore token refresh failure
+                            // socket not open; the watchdog above will force a reconnect
                         }
-                    });
+                    }, PING_MS);
                     return {
-                        send(data) {
-                            ws.send(JSON.stringify(data));
-                        },
-                        close() {
+                        id: connId, // the connection id (same value the handler sees as conn.id)
+                        unsubscribe() {
+                            clearInterval(heartbeat);
                             activeSockets.delete(key);
                             ws.close();
                         },

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

@@ -1,32 +1,62 @@
 /**
- * A subscription handle returned by {@link RealtimeHandlerClient.subscribe}.
+ * Extend this interface to add typed `subscribe` callbacks and `send` payloads
+ * for your deployed RealtimeHandlers.
+ *
+ * This is separate from {@link RealtimeHandlerNameRegistry} (which is auto-generated
+ * by `base44 types generate`), so there are no conflicts.
+ *
+ * @example
+ * ```typescript
+ * declare module "@base44/sdk" {
+ *   interface RealtimeHandlerRegistry {
+ *     ChatRoom: {
+ *       toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
+ *       toServer: { type: "message"; text: string };
+ *     };
+ *   }
+ * }
+ * ```
  */
-export interface RealtimeSubscription {
-    /** Send a message to all subscribers of this instance. */
-    send(data: unknown): void;
-    /** Close the WebSocket connection and remove the subscription. */
-    close(): void;
+export interface RealtimeHandlerRegistry {
 }
+/**
+ * Auto-populated by `base44 types generate` with the names of your deployed handlers.
+ * Do not edit this interface manually — use {@link RealtimeHandlerRegistry} for message types.
+ */
+export interface RealtimeHandlerNameRegistry {
+}
+type AllHandlerNames = keyof RealtimeHandlerRegistry | keyof RealtimeHandlerNameRegistry;
+type ToClientFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
+    toClient: infer I;
+} ? I : unknown : unknown;
+type ToServerFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
+    toServer: infer O;
+} ? O : unknown : unknown;
 /**
  * Client for a single named RealtimeHandler.
+ * Typed automatically when the handler is registered in {@link RealtimeHandlerRegistry}.
  */
-export interface RealtimeHandlerClient {
-    /**
-     * Subscribe to messages from a specific RealtimeHandler instance.
-     *
-     * @param instanceId - The instance ID of the Durable Object.
-     * @param callback - Called with each parsed message payload.
-     * @returns A subscription handle with `send` and `close` methods.
-     */
-    subscribe(instanceId: string, callback: (data: unknown) => void): Promise<RealtimeSubscription>;
+export interface RealtimeHandlerClient<N extends string = string> {
     /**
-     * Send a message to an existing active subscription.
+     * Open a WebSocket subscription. Returns a {@link RealtimeSubscription} with the
+     * connection `id` (same value the handler sees as `conn.id`) and an `unsubscribe()` method.
      *
-     * @param instanceId - The instance ID of the Durable Object.
-     * @param data - The data to send (will be JSON-serialized).
-     * @throws {Error} When no active subscription exists for this handler/instance pair.
+     * Pass `options.id` to control the connection id (e.g. a stable per-tab id so a
+     * reconnect reuses the same server-side connection); omit it for an auto-generated
+     * per-connection id.
      */
-    send(instanceId: string, data: unknown): void;
+    subscribe(instanceId: string, callback: (data: ToClientFor<N>) => void, options?: {
+        id?: string;
+    }): RealtimeSubscription;
+    /** Send a message over the open socket. Throws if not subscribed. */
+    send(instanceId: string, data: ToServerFor<N>): void;
+}
+/** Handle for an active realtime subscription. */
+export interface RealtimeSubscription {
+    /** This connection's id — the same value the handler receives as `conn.id`. */
+    id: string;
+    /** Close the subscription and its underlying socket. */
+    unsubscribe(): void;
 }
 /**
  * The realtime module provides access to Cloudflare Durable Object-backed
@@ -35,10 +65,13 @@ export interface RealtimeHandlerClient {
  * Handler names are accessed as dynamic properties on this module:
  * ```typescript
  * const sub = await base44.realtime.MyHandler.subscribe("room-1", (msg) => {
- *   console.log(msg);
+ *   console.log(msg); // typed if MyHandler is in RealtimeHandlerRegistry
  * });
- * sub.send({ text: "hello" });
- * sub.close();
+ * const { id, unsubscribe } = sub;
+ * unsubscribe();
  * ```
  */
-export type RealtimeModule = Record<string, RealtimeHandlerClient>;
+export type RealtimeModule = {
+    [K in AllHandlerNames]: K extends keyof RealtimeHandlerRegistry ? RealtimeHandlerClient<string & K> : RealtimeHandlerClient;
+} & Record<string, RealtimeHandlerClient>;
+export {};

package/dist/modules/types.d.ts

@@ -1,4 +1,5 @@
 export * from "./app.types.js";
 export * from "./agents.types.js";
+export * from "./ai-gateway.types.js";
 export * from "./connectors.types.js";
 export * from "./analytics.types.js";

package/dist/modules/types.js

@@ -1,4 +1,5 @@
 export * from "./app.types.js";
 export * from "./agents.types.js";
+export * from "./ai-gateway.types.js";
 export * from "./connectors.types.js";
 export * from "./analytics.types.js";

package/dist/realtime-handler.d.ts

@@ -8,20 +8,65 @@
  * At deploy time the bundler replaces this import with the compiled
  * Cloudflare Durable Object implementation — this file provides types only.
  */
-export interface Conn {
+import type { Base44Client } from "./client.types.js";
+/**
+ * A single client connection. `Send` is the message type this connection accepts
+ * via {@link send} — the handler'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: unknown): void;
+    send(data: Send): void;
     reject(code: number, reason: string): void;
 }
-export declare abstract class RealtimeHandler<_State = unknown, Message = unknown> {
-    abstract handleConnect(conn: Conn): void | Promise<void>;
-    abstract handleMessage(conn: Conn, msg: Message): void | Promise<void>;
-    abstract handleClose(conn: Conn): void | Promise<void>;
+export interface Storage {
+    get<T>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+/**
+ * Base class for a Realtime Handler.
+ *
+ * @typeParam Incoming - messages this handler *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this handler *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 = RealtimeHandlerRegistry["MyHandler"];
+ * class MyHandler extends RealtimeHandler<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
+export declare abstract class RealtimeHandler<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>;
-    protected broadcast(_data: unknown): void;
-    protected getConnections(): Conn[];
+    onStart(): 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;
+    protected createServiceClient(): Base44Client;
 }

package/dist/realtime-handler.js

@@ -8,7 +8,36 @@
  * At deploy time the bundler replaces this import with the compiled
  * Cloudflare Durable Object implementation — this file provides types only.
  */
+/**
+ * Base class for a Realtime Handler.
+ *
+ * @typeParam Incoming - messages this handler *receives* from clients
+ *   (`handleMessage`'s `msg`) — the schema's `toServer` section.
+ * @typeParam Outgoing - messages this handler *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 = RealtimeHandlerRegistry["MyHandler"];
+ * class MyHandler extends RealtimeHandler<Reg["toServer"], Reg["toClient"]> { ... }
+ * ```
+ */
 export class RealtimeHandler {
+    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;
+    }
+    onStart() { }
     broadcast(_data) {
         throw new Error("RealtimeHandler.broadcast() is only available inside a deployed handler");
     }
@@ -21,4 +50,13 @@ export class RealtimeHandler {
     stopLoop() {
         throw new Error("RealtimeHandler.stopLoop() is only available inside a deployed handler");
     }
+    get instanceId() {
+        throw new Error("RealtimeHandler.instanceId is only available inside a deployed handler");
+    }
+    get storage() {
+        throw new Error("RealtimeHandler.storage is only available inside a deployed handler");
+    }
+    createServiceClient() {
+        throw new Error("RealtimeHandler.createServiceClient() is only available inside a deployed handler");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.35-pr.212.2fe0031",
+  "version": "0.8.35-pr.212.36b2685",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",