@base44-preview/sdk 0.8.35-pr.212.b15255e → 0.8.35-pr.212.c335c63

package/dist/index.d.ts

@@ -10,8 +10,9 @@ export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations,
 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 { 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";
 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 { RealtimeHandler } from "./realtime-handler.js";

package/dist/modules/realtime.d.ts

@@ -4,10 +4,7 @@ export declare function createRealtimeModule(config: {
     dispatcherWsUrl: string;
 }): Record<string, RealtimeHandler>;
 interface RealtimeHandler {
-    subscribe(instanceId: string, callback: (data: unknown) => void): Promise<{
-        send(data: unknown): void;
-        close(): void;
-    }>;
+    subscribe(instanceId: string, callback: (data: unknown) => void): () => void;
     send(instanceId: string, data: unknown): void;
 }
 export {};

package/dist/modules/realtime.js

@@ -8,47 +8,62 @@ export function createRealtimeModule(config) {
     return new Proxy({}, {
         get(_, handlerName) {
             return {
-                async subscribe(instanceId, callback) {
+                subscribe(instanceId, callback) {
                     var _a;
                     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);
+                    // 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).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 = 5000;
+                    const DEAD_MS = 12000;
+                    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
                         }
-                    });
-                    return {
-                        send(data) {
-                            ws.send(JSON.stringify(data));
-                        },
-                        close() {
-                            activeSockets.delete(key);
-                            ws.close();
-                        },
+                    }, PING_MS);
+                    return () => {
+                        clearInterval(heartbeat);
+                        activeSockets.delete(key);
+                        ws.close();
                     };
                 },
                 send(instanceId, data) {

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

@@ -1,32 +1,46 @@
 /**
- * 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: {
+ *       inbound:  { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
+ *       outbound: { text: string };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+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 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 RealtimeHandlerNameRegistry {
 }
+type AllHandlerNames = keyof RealtimeHandlerRegistry | keyof RealtimeHandlerNameRegistry;
+type InboundFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
+    inbound: infer I;
+} ? I : unknown : unknown;
+type OutboundFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? RealtimeHandlerRegistry[N] extends {
+    outbound: 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>;
-    /**
-     * Send a message to an existing active subscription.
-     *
-     * @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.
-     */
-    send(instanceId: string, data: unknown): void;
+export interface RealtimeHandlerClient<N extends string = string> {
+    /** Open a WebSocket subscription. Returns a synchronous unsubscribe function. */
+    subscribe(instanceId: string, callback: (data: InboundFor<N>) => void): () => void;
+    /** Send a message over the open socket. Throws if not subscribed. */
+    send(instanceId: string, data: OutboundFor<N>): void;
 }
 /**
  * The realtime module provides access to Cloudflare Durable Object-backed
@@ -35,10 +49,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();
  * ```
  */
-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/realtime-handler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Type-only base class for Realtime Handlers.
+ *
+ * Import and extend this in your handler files:
+ *   import { RealtimeHandler } from "@base44/sdk";
+ *   export class MyHandler extends RealtimeHandler { ... }
+ *
+ * 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.types.js";
+export interface Conn {
+    userId: string;
+    appId: string;
+    instanceId: string;
+    send(data: unknown): 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>;
+}
+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>;
+    abstract handleTick(): void | Promise<void>;
+    onStart(): void | Promise<void>;
+    protected broadcast(_data: unknown): void;
+    protected getConnections(): Conn[];
+    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

@@ -0,0 +1,34 @@
+/**
+ * Type-only base class for Realtime Handlers.
+ *
+ * Import and extend this in your handler files:
+ *   import { RealtimeHandler } from "@base44/sdk";
+ *   export class MyHandler extends RealtimeHandler { ... }
+ *
+ * At deploy time the bundler replaces this import with the compiled
+ * Cloudflare Durable Object implementation — this file provides types only.
+ */
+export class RealtimeHandler {
+    onStart() { }
+    broadcast(_data) {
+        throw new Error("RealtimeHandler.broadcast() is only available inside a deployed handler");
+    }
+    getConnections() {
+        throw new Error("RealtimeHandler.getConnections() is only available inside a deployed handler");
+    }
+    startLoop(_ms) {
+        throw new Error("RealtimeHandler.startLoop() is only available inside a deployed handler");
+    }
+    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.b15255e",
+  "version": "0.8.35-pr.212.c335c63",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",