@base44-preview/sdk 0.8.35-pr.212.1d74ede → 0.8.35-pr.212.5aafd7f

package/dist/modules/realtime.d.ts

@@ -3,8 +3,17 @@ export declare function createRealtimeModule(config: {
     getToken(handlerName: string, instanceId: 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): () => 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,68 @@ export function createRealtimeModule(config) {
     return new Proxy({}, {
         get(_, handlerName) {
             return {
-                subscribe(instanceId, callback) {
+                subscribe(instanceId, callback, options) {
                     var _a;
                     const key = socketKey(handlerName, instanceId);
                     // close existing if any
                     (_a = activeSockets.get(key)) === null || _a === void 0 ? void 0 : _a.close();
+                    // 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,
+                        // Connection id: caller-supplied (stable — reuse across reconnects/tabs as
+                        // you see fit) or auto-generated per connection. Server sees it as conn.id.
+                        id: options === null || options === void 0 ? void 0 : options.id,
+                        query: () => config.getToken(handlerName, instanceId).then((token) => ({ token })),
                     });
                     activeSockets.set(key, ws);
-                    // Fetch token and attach on connect
-                    config.getToken(handlerName, instanceId).then((token) => {
-                        ws.updateProperties({ party: handlerName, room: instanceId, query: { token } });
-                    });
+                    // 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({ party: handlerName, room: instanceId, 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 () => {
-                        activeSockets.delete(key);
-                        ws.close();
+                    }, PING_MS);
+                    return {
+                        id: ws.id, // the connection id (same value the handler sees as conn.id)
+                        unsubscribe() {
+                            clearInterval(heartbeat);
+                            activeSockets.delete(key);
+                            ws.close();
+                        },
                     };
                 },
                 send(instanceId, data) {

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

@@ -37,11 +37,27 @@ type OutboundFor<N extends string> = N extends keyof RealtimeHandlerRegistry ? R
  * Typed automatically when the handler is registered in {@link RealtimeHandlerRegistry}.
  */
 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;
+    /**
+     * Open a WebSocket subscription. Returns a {@link RealtimeSubscription} with the
+     * connection `id` (same value the handler sees as `conn.id`) and an `unsubscribe()` method.
+     *
+     * 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.
+     */
+    subscribe(instanceId: string, callback: (data: InboundFor<N>) => void, options?: {
+        id?: string;
+    }): RealtimeSubscription;
     /** Send a message over the open socket. Throws if not subscribed. */
     send(instanceId: string, data: OutboundFor<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
  * RealtimeHandlers deployed by the Base44 platform.
@@ -51,8 +67,8 @@ export interface RealtimeHandlerClient<N extends string = string> {
  * const sub = await base44.realtime.MyHandler.subscribe("room-1", (msg) => {
  *   console.log(msg); // typed if MyHandler is in RealtimeHandlerRegistry
  * });
- * sub.send({ text: "hello" });
- * sub.close();
+ * const { id, unsubscribe } = sub;
+ * unsubscribe();
  * ```
  */
 export type RealtimeModule = {

package/dist/realtime-handler.d.ts

@@ -8,6 +8,7 @@
  * 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;
@@ -15,13 +16,34 @@ export interface Conn {
     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>;
+    /**
+     * 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: 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

@@ -9,6 +9,20 @@
  * Cloudflare Durable Object implementation — this file provides types only.
  */
 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 +35,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.1d74ede",
+  "version": "0.8.35-pr.212.5aafd7f",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",