@phpsandbox/sdk 0.0.65 → 0.0.66

package/README.md

@@ -18,7 +18,7 @@ import { PHPSandbox } from '@phpsandbox/sdk';
 const token = process.env.PHPSANDBOX_TOKEN;
 if (!token) throw new Error('Missing PHPSANDBOX_TOKEN');
 
-const client = new PHPSandbox(token);
+const client = PHPSandbox.realtime(token);
 
 // create() initializes the notebook by default
 const notebook = await client.notebook.create('php');
@@ -53,22 +53,27 @@ Use an API token:
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
 
-const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN!);
+const client = PHPSandbox.realtime(process.env.PHPSANDBOX_TOKEN!);
 ```
 
-Optional constructor args:
+Explicit realtime and REST clients:
 
 ```ts
-new PHPSandbox('token', 'https://api.phpsandbox.io/v1', {
+PHPSandbox.realtime('token', 'https://api.phpsandbox.io/v1', {
   debug: false,
   startClosed: true,
 });
+
+// Use explicit request/response runtime actions without a websocket.
+PHPSandbox.rest('token', 'https://api.phpsandbox.io/v1', {
+  okraUrlProvider: async (notebookId) => getFreshOkraUrl(notebookId),
+});
 ```
 
 ## Notebook Lifecycle
 
 ```ts
-const client = new PHPSandbox(process.env.PHPSANDBOX_TOKEN!);
+const client = PHPSandbox.realtime(process.env.PHPSANDBOX_TOKEN!);
 
 const created = await client.notebook.create('laravel');
 const opened = await client.notebook.open('notebook-id');

package/dist/auth.d.ts

@@ -1,13 +1,12 @@
 import { Action, NotebookInstance } from './index.js';
 export interface AuthActions {
     'auth.login': Action<{
-        newConnectionData: string;
+        runtimeTicket: string;
     }, boolean>;
-    'auth.logout': Action<null>;
 }
 export default class Auth {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
-    logout(): Promise<void>;
-    login(newConnectionData: string): Promise<boolean>;
+    logout(): void;
+    login(okraUrl: string): Promise<boolean>;
 }

package/dist/auth.js

@@ -3,9 +3,13 @@ export default class Auth {
         this.okra = okra;
     }
     logout() {
-        return this.okra.invoke('auth.logout');
+        this.okra.dispose();
     }
-    login(newConnectionData) {
-        return this.okra.invoke('auth.login', { newConnectionData });
+    login(okraUrl) {
+        const runtimeTicket = new URL(okraUrl).searchParams.get('ticket');
+        if (runtimeTicket === null || runtimeTicket === '') {
+            throw new TypeError('The notebook connection does not contain a runtime ticket.');
+        }
+        return this.okra.invoke('auth.login', { runtimeTicket });
     }
 }

package/dist/browser/phpsandbox-sdk.esm.js

@@ -93,13 +93,16 @@ var FilesystemSubscription = class {
   }
 };
 var Filesystem = class {
-  constructor(okra) {
+  constructor(okra, registerReconnect = (handler) => okra.onDidConnect(handler)) {
     this.okra = okra;
     this.watches = /* @__PURE__ */ new Map();
-    this.watchOkraConnection();
+    this.registerReconnectHandler(registerReconnect);
   }
-  watchOkraConnection() {
-    this.okra.onDidConnect(() => {
+  registerReconnectHandler(registerReconnect) {
+    if (registerReconnect === null) {
+      return;
+    }
+    registerReconnect(() => {
       for (const { path, options } of this.watches.values()) {
         void this.okra.invoke("fs.watch", { path, options }).catch(() => {
         });
@@ -306,6 +309,12 @@ var NotebookUnavailableError = class extends Error {
     this.name = "NotebookUnavailableError";
   }
 };
+var UnsupportedRuntimeTransportError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedRuntimeTransportError";
+  }
+};
 
 // src/utils/promise.ts
 var timeout = (prom, time3) => {
@@ -573,10 +582,14 @@ var Auth = class {
     this.okra = okra;
   }
   logout() {
-    return this.okra.invoke("auth.logout");
+    this.okra.dispose();
   }
-  login(newConnectionData) {
-    return this.okra.invoke("auth.login", { newConnectionData });
+  login(okraUrl) {
+    const runtimeTicket = new URL(okraUrl).searchParams.get("ticket");
+    if (runtimeTicket === null || runtimeTicket === "") {
+      throw new TypeError("The notebook connection does not contain a runtime ticket.");
+    }
+    return this.okra.invoke("auth.login", { runtimeTicket });
   }
 };
 
@@ -3136,11 +3149,12 @@ var Transport = class {
     this.pingIntervalStarted = false;
     this.incomingMessageChain = Promise.resolve();
     this.validateConfiguration(options);
-    this.url = new URL(url2);
+    this.url = typeof url2 === "string" ? new URL(url2) : null;
+    const urlProvider = typeof url2 === "string" ? this.url.toString() : async () => new URL(await url2()).toString();
     this.PING_INTERVAL = options.pingInterval ?? 3e4;
     this.CONNECT_WAIT_TIMEOUT = options.connectWaitTimeout ?? 3e4;
     const startClosed = options.startClosed !== false;
-    this.rws = new ReconnectingWebSocket2(this.url.toString(), [], {
+    this.rws = new ReconnectingWebSocket2(urlProvider, [], {
       WebSocket: options.webSocket ?? globalThis.WebSocket ?? browser_default,
       connectionTimeout: options.connectionTimeout,
       maxReconnectionDelay: 2e3,
@@ -3150,7 +3164,7 @@ var Transport = class {
       startClosed
     });
     this.log("debug", "Transport initialized", {
-      url: this.url.toString(),
+      url: this.url === null ? "dynamic" : transportLogUrl(this.url),
       options
     });
     this.registerWatchers();
@@ -3736,6 +3750,12 @@ startPeriodicPing_fn = function() {
     };
   });
 };
+function transportLogUrl(url2) {
+  const safeUrl = new URL(url2);
+  safeUrl.search = "";
+  safeUrl.hash = "";
+  return safeUrl.toString();
+}
 
 // node_modules/mitt/dist/mitt.mjs
 var mitt_exports = {};
@@ -19785,6 +19805,231 @@ var ServerInstance = class {
   }
 };
 
+// src/runtime/rest.ts
+var restActionRoutes = {
+  "runtime.ready": { method: "GET", path: "/runtime" },
+  ping: { method: "GET", path: "/runtime/ping" },
+  "config.get": { method: "GET", path: "/runtime/config" },
+  "config.update": { method: "PATCH", path: "/runtime/config" },
+  "config.set-ports": { method: "PUT", path: "/runtime/config/ports" },
+  "container.state": { method: "GET", path: "/runtime/container" },
+  "container.start": { method: "POST", path: "/runtime/container/start" },
+  "container.restart": { method: "POST", path: "/runtime/container/restart" },
+  "container.stop": { method: "POST", path: "/runtime/container/stop" },
+  "container.set-php": { method: "PUT", path: "/runtime/container/php" },
+  "container.opened-ports": { method: "GET", path: "/runtime/container/ports" },
+  "terminal.list": { method: "GET", path: "/runtime/terminals" },
+  "shell.exec": { method: "POST", path: "/runtime/executions" },
+  "fs.info": { method: "POST", path: "/runtime/files/info" },
+  "fs.readFile": { method: "GET", path: "/runtime/files/content" },
+  "fs.writeFile": { method: "PUT", path: "/runtime/files/content" },
+  "fs.write": { method: "PUT", path: "/runtime/files/text" },
+  "fs.mkdir": { method: "POST", path: "/runtime/directories" },
+  "fs.createDirectory": { method: "PUT", path: "/runtime/directories" },
+  "fs.readDirectory": { method: "POST", path: "/runtime/directories/read" },
+  "fs.stat": { method: "POST", path: "/runtime/files/stat" },
+  "fs.move": { method: "POST", path: "/runtime/files/move" },
+  "fs.rename": { method: "POST", path: "/runtime/files/rename" },
+  "fs.copy": { method: "POST", path: "/runtime/files/copy" },
+  "fs.remove": { method: "POST", path: "/runtime/files/remove" },
+  "fs.delete": { method: "DELETE", path: "/runtime/files" },
+  "fs.tail": { method: "POST", path: "/runtime/files/tail" },
+  "fs.find": { method: "POST", path: "/runtime/files/find" },
+  "fs.textSearch": { method: "POST", path: "/runtime/files/search" },
+  "fs.tree": { method: "POST", path: "/runtime/files/tree" },
+  "service.list": { method: "GET", path: "/runtime/services" },
+  "service.run": { method: "POST", path: "/runtime/services/run" },
+  "service.stop": { method: "POST", path: "/runtime/services/stop" },
+  "service.logs": { method: "POST", path: "/runtime/services/logs" },
+  "composer.invoke": { method: "POST", path: "/runtime/composer/executions" },
+  "composer.packages": { method: "GET", path: "/runtime/composer/packages" },
+  "composer.dump-autoload": {
+    method: "POST",
+    path: "/runtime/composer/autoload"
+  },
+  "git.checkpoint": { method: "POST", path: "/runtime/git/checkpoints" },
+  "git.checkout": { method: "POST", path: "/runtime/git/checkouts" },
+  "git.log": { method: "POST", path: "/runtime/git/log" },
+  "git.sync": { method: "POST", path: "/runtime/git/sync" },
+  "git.diff": { method: "POST", path: "/runtime/git/diff" },
+  "git.merge": { method: "POST", path: "/runtime/git/merge" },
+  "git.conflicts": { method: "GET", path: "/runtime/git/conflicts" },
+  "git.resolve": { method: "POST", path: "/runtime/git/conflicts/resolve" },
+  "git.restore": { method: "POST", path: "/runtime/git/restore" },
+  "git.status": { method: "GET", path: "/runtime/git/status" },
+  "git.review": { method: "GET", path: "/runtime/git/review" },
+  "git.stage": { method: "POST", path: "/runtime/git/stage" },
+  "git.unstage": { method: "POST", path: "/runtime/git/unstage" },
+  "git.revert": { method: "POST", path: "/runtime/git/revert" }
+};
+var RestRuntimeInvoker = class {
+  constructor(data, fetch, refresh) {
+    this.fetch = fetch;
+    this.refresh = refresh;
+    this.refreshPromise = null;
+    this.notebookId = data.id;
+    this.configure(data.okraUrl);
+  }
+  configure(connectionUrl) {
+    const okraUrl = new URL(connectionUrl);
+    const ticket = okraUrl.searchParams.get("ticket") ?? "";
+    if (ticket === "") {
+      throw new UnsupportedRuntimeTransportError("The notebook connection does not contain a runtime ticket.");
+    }
+    this.ticket = ticket;
+    okraUrl.protocol = okraUrl.protocol === "wss:" ? "https:" : "http:";
+    okraUrl.pathname = `/api/v1/notebooks/${encodeURIComponent(this.notebookId)}`;
+    okraUrl.searchParams.delete("ticket");
+    okraUrl.hash = "";
+    this.actionUrl = okraUrl;
+  }
+  ready() {
+    return this.invokeRaw("runtime.ready", {}, {});
+  }
+  supports(action) {
+    return action in restActionRoutes;
+  }
+  invoke(action, data = {}, options = {}) {
+    return this.invokeRaw(action, data ?? {}, options);
+  }
+  send() {
+    throw new UnsupportedRuntimeTransportError("Fire-and-forget actions require the realtime transport.");
+  }
+  async invokeRaw(action, data, options) {
+    const abort = runtimeAbort(options);
+    try {
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const response = await this.fetch(this.request(action, data, abort.signal));
+        if (response.status === 401 && attempt === 0 && this.refresh !== void 0) {
+          await this.refreshAuthorization();
+          continue;
+        }
+        const payload = await runtimeActionResponse(response);
+        if (!response.ok || payload.error !== void 0) {
+          const error51 = payload.error ?? payload;
+          const message = typeof error51.message === "string" ? error51.message : `Runtime action ${action} failed.`;
+          const code = typeof error51.code === "number" ? error51.code : response.status;
+          throw new ErrorEvent(code, message, error51);
+        }
+        return payload.data;
+      }
+      throw new ErrorEvent(401, `Runtime action ${action} could not be authorized.`, {});
+    } finally {
+      abort.dispose();
+    }
+  }
+  request(action, data, signal) {
+    const route = restActionRoutes[action];
+    if (route === void 0) {
+      throw new UnsupportedRuntimeTransportError(`Runtime action ${action} requires the realtime transport.`);
+    }
+    const url2 = new URL(this.actionUrl);
+    url2.pathname += route.path;
+    const headers = {
+      Accept: "application/json, application/octet-stream",
+      Authorization: `Bearer ${this.ticket}`
+    };
+    const body = runtimeActionRequestBody(action, data, url2, headers);
+    return new Request(url2, {
+      method: route.method,
+      headers,
+      body: route.method === "GET" ? void 0 : body,
+      signal
+    });
+  }
+  async refreshAuthorization() {
+    if (this.refreshPromise === null) {
+      this.refreshPromise = this.refresh().then((okraUrl) => this.configure(okraUrl));
+    }
+    try {
+      await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+};
+async function runtimeActionResponse(response) {
+  if (response.ok && response.headers.get("content-type")?.toLowerCase().startsWith("application/octet-stream")) {
+    return { data: new Uint8Array(await response.arrayBuffer()) };
+  }
+  const body = await response.text();
+  if (body === "") {
+    return {};
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return { error: { code: response.status, message: body } };
+  }
+}
+function runtimeActionRequestBody(action, data, url2, headers) {
+  const payload = runtimeActionRecord(data);
+  if (action === "fs.readFile") {
+    setRequiredRuntimeQuery(url2, "path", payload.path);
+    const lineRange = runtimeActionRecord(payload.lineRange);
+    if (lineRange.lineStart !== void 0 || lineRange.lineEnd !== void 0) {
+      setRequiredRuntimeQuery(url2, "lineStart", lineRange.lineStart);
+      setRequiredRuntimeQuery(url2, "lineEnd", lineRange.lineEnd);
+    }
+    return void 0;
+  }
+  if (action === "fs.writeFile") {
+    setRequiredRuntimeQuery(url2, "path", payload.path);
+    const options = runtimeActionRecord(payload.options);
+    setBooleanRuntimeQuery(url2, "overwrite", options.overwrite);
+    setBooleanRuntimeQuery(url2, "create", options.create);
+    setBooleanRuntimeQuery(url2, "unlock", options.unlock);
+    const atomic = runtimeActionRecord(options.atomic);
+    if (typeof atomic.postfix === "string" && atomic.postfix !== "") {
+      url2.searchParams.set("atomicPostfix", atomic.postfix);
+    }
+    if (!ArrayBuffer.isView(payload.contents)) {
+      throw new TypeError("Runtime file contents must be binary data.");
+    }
+    headers["Content-Type"] = "application/octet-stream";
+    return Uint8Array.from(
+      new Uint8Array(payload.contents.buffer, payload.contents.byteOffset, payload.contents.byteLength)
+    ).buffer;
+  }
+  headers["Content-Type"] = "application/json";
+  return JSON.stringify(data);
+}
+function runtimeActionRecord(value) {
+  return value !== null && typeof value === "object" ? value : {};
+}
+function setRequiredRuntimeQuery(url2, name, value) {
+  if (typeof value !== "string" && typeof value !== "number" || String(value) === "") {
+    throw new TypeError(`Runtime file ${name} is required.`);
+  }
+  url2.searchParams.set(name, String(value));
+}
+function setBooleanRuntimeQuery(url2, name, value) {
+  url2.searchParams.set(name, value === true ? "true" : "false");
+}
+function runtimeAbort(options) {
+  if (options.timeout === void 0 && options.abortSignal === void 0) {
+    return { signal: new AbortController().signal, dispose: () => void 0 };
+  }
+  const controller = new AbortController();
+  const abortFromCaller = () => controller.abort(options.abortSignal?.reason);
+  options.abortSignal?.addEventListener("abort", abortFromCaller, {
+    once: true
+  });
+  if (options.abortSignal?.aborted) {
+    abortFromCaller();
+  }
+  const timeout2 = options.timeout === void 0 ? void 0 : setTimeout(() => controller.abort(), options.timeout);
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      options.abortSignal?.removeEventListener("abort", abortFromCaller);
+      if (timeout2 !== void 0) {
+        clearTimeout(timeout2);
+      }
+    }
+  };
+}
+
 // src/index.ts
 function normalizeNotebookSecretInputs(input) {
   if (Array.isArray(input)) {
@@ -19892,6 +20137,7 @@ function normalizeApiBaseUrl(url2) {
 }
 var Client2 = class {
   constructor(token, url2 = "https://api.phpsandbox.io/v1", options = {}) {
+    this.runtimeTransportValue = "realtime";
     this.fetch = globalThis.fetch;
     this.deployments = new DeploymentApi(this);
     this.notebook = new NotebookApi(this);
@@ -19907,6 +20153,9 @@ var Client2 = class {
       "Content-Type": "application/json"
     };
   }
+  get runtimeTransport() {
+    return this.runtimeTransportValue;
+  }
   get(path) {
     return this.makeRequest("GET", path);
   }
@@ -19970,7 +20219,15 @@ var Client2 = class {
     return { data: body === "" ? void 0 : JSON.parse(body) };
   }
 };
-var PHPSandbox = class extends Client2 {
+var PHPSandbox = class _PHPSandbox extends Client2 {
+  static realtime(token, url2 = "https://api.phpsandbox.io/v1", options = {}) {
+    return new _PHPSandbox(token, url2, options);
+  }
+  static rest(token, url2 = "https://api.phpsandbox.io/v1", options = {}) {
+    const client = new _PHPSandbox(token, url2, options);
+    client.runtimeTransportValue = "rest";
+    return client;
+  }
 };
 var NotebookSecretApi = class {
   constructor(client) {
@@ -20076,17 +20333,38 @@ var NotebookInstance2 = class {
     this.client = client;
     __privateAdd(this, _NotebookInstance_instances);
     this.initialized = false;
-    __privateAdd(this, _initPromise);
+    __privateAdd(this, _initPromise, null);
     this.disposables = [];
     this.emitter = EventManager.createInstance();
-    this.socket = new Transport(data.okraUrl, this.emitter, {
-      debug: client.options.debug,
-      startClosed: client.options.startClosed,
-      webSocket: client.options.webSocket
-    });
-    this.watchConnection();
-    __privateSet(this, _initPromise, __privateMethod(this, _NotebookInstance_instances, init_fn).call(this));
-    this.file = new Filesystem(this);
+    if (client.runtimeTransport === "rest") {
+      this.socket = null;
+      this.restInvoker = new RestRuntimeInvoker(
+        data,
+        client.options.fetch ?? globalThis.fetch,
+        client.options.okraUrlProvider === void 0 ? void 0 : () => client.options.okraUrlProvider(data.id)
+      );
+    } else {
+      this.restInvoker = null;
+      let initialConnection = true;
+      const connectionUrl = client.options.okraUrlProvider === void 0 ? data.okraUrl : async () => {
+        if (initialConnection) {
+          initialConnection = false;
+          return data.okraUrl;
+        }
+        return client.options.okraUrlProvider(data.id);
+      };
+      this.socket = new Transport(connectionUrl, this.emitter, {
+        debug: client.options.debug,
+        startClosed: client.options.startClosed,
+        webSocket: client.options.webSocket
+      });
+      this.watchConnection();
+      __privateSet(this, _initPromise, __privateMethod(this, _NotebookInstance_instances, init_fn).call(this));
+    }
+    this.file = new Filesystem(
+      this,
+      this.socket === null ? null : (handler) => this.onDidConnect(handler)
+    );
     this.terminal = new Terminal(this);
     this.auth = new Auth(this);
     this.lsp = new Lsp(this);
@@ -20103,14 +20381,21 @@ var NotebookInstance2 = class {
     this.preview = new NotebookPreview(client, this.data.id);
     this.mail = new NotebookMail(client, this.data.id);
   }
+  get runtimeTransport() {
+    return this.client.runtimeTransport;
+  }
   async ready() {
-    const terminalError = this.socket.getTerminalError();
+    if (this.restInvoker !== null) {
+      return this.restInitialization();
+    }
+    const socket = this.realtimeSocket();
+    const terminalError = socket.getTerminalError();
     if (terminalError) {
       throw terminalError;
     }
     const ready = async () => {
-      if (this.client.options.startClosed && !this.socket.isConnected) {
-        await this.socket.connect();
+      if (this.client.options.startClosed && !socket.isConnected) {
+        await socket.connect();
       }
       return __privateGet(this, _initPromise);
     };
@@ -20130,7 +20415,7 @@ var NotebookInstance2 = class {
   }
   delete() {
     return this.client.notebook.delete(this.data.id).then(() => {
-      this.socket.terminate(new NotebookUnavailableError("Notebook has been deleted.", { id: this.data.id }));
+      this.socket?.terminate(new NotebookUnavailableError("Notebook has been deleted.", { id: this.data.id }));
     });
   }
   stop() {
@@ -20140,10 +20425,19 @@ var NotebookInstance2 = class {
     return this.container.restart();
   }
   invoke(action, data = {}, options = {}) {
-    return this.socket.invoke(action, data || {}, options);
+    if (this.restInvoker !== null) {
+      if (this.restInvoker.supports(String(action))) {
+        void this.restInitialization();
+      }
+      return this.restInvoker.invoke(action, data || {}, options);
+    }
+    return this.realtimeSocket().invoke(action, data || {}, options);
   }
   send(action, data = {}) {
-    return this.socket.send(action, data || {});
+    if (this.restInvoker !== null) {
+      return this.restInvoker.send();
+    }
+    return this.realtimeSocket().send(action, data || {});
   }
   ping() {
     return this.invoke("ping");
@@ -20155,7 +20449,9 @@ var NotebookInstance2 = class {
   }
   dispose() {
     this.disposables.forEach((d) => d.dispose());
-    !this.socket.isClosed && this.socket.disconnect();
+    if (this.socket !== null && !this.socket.isClosed) {
+      this.socket.disconnect();
+    }
   }
   connected() {
     return this.waitForSocketConnection({ rejectOnClose: true });
@@ -20164,11 +20460,12 @@ var NotebookInstance2 = class {
     return this.waitForSocketConnection({ rejectOnClose: false });
   }
   waitForSocketConnection(options) {
-    const terminalError = this.socket.getTerminalError();
+    const socket = this.realtimeSocket();
+    const terminalError = socket.getTerminalError();
     if (terminalError) {
       return Promise.reject(terminalError);
     }
-    if (this.socket.isConnected) {
+    if (socket.isConnected) {
       return Promise.resolve(this);
     }
     return new Promise((resolve, reject) => {
@@ -20189,49 +20486,66 @@ var NotebookInstance2 = class {
         callback();
       };
       try {
-        disposables.push(this.socket.onDidConnect(() => settle(() => resolve(this))));
+        disposables.push(socket.onDidConnect(() => settle(() => resolve(this))));
         if (options.rejectOnClose) {
-          disposables.push(this.socket.onDidClose(() => settle(() => reject(new Error("Connection closed")))));
+          disposables.push(socket.onDidClose(() => settle(() => reject(new Error("Connection closed")))));
         }
-        disposables.push(this.socket.onDidBootError((error51) => settle(() => reject(error51))));
+        disposables.push(socket.onDidBootError((error51) => settle(() => reject(error51))));
       } catch (e) {
         settle(() => reject(e));
       }
     });
   }
   watchConnection() {
-    this.socket.onDidConnect(() => {
-      this.socket.emit("okra.connected");
+    const socket = this.realtimeSocket();
+    socket.onDidConnect(() => {
+      socket.emit("okra.connected");
       if (this.client.options.telemetry) {
         this.container.enableTelemetry(this.client.options.telemetry);
       }
     });
-    this.socket.onDidClose(() => {
-      this.socket.emit("okra.disconnected");
+    socket.onDidClose(() => {
+      socket.emit("okra.disconnected");
       this.initialized = false;
     });
-    this.socket.onDidBootError((error51) => {
-      this.socket.emit("okra.boot_error", error51);
-      this.socket.emit("okra.disconnected");
+    socket.onDidBootError((error51) => {
+      socket.emit("okra.boot_error", error51);
+      socket.emit("okra.disconnected");
       this.initialized = false;
     });
   }
   onDidConnect(handler) {
-    this.socket.removeListener("okra.connected", handler);
-    const disposable = this.socket.listen("okra.connected", handler);
+    const socket = this.realtimeSocket();
+    socket.removeListener("okra.connected", handler);
+    const disposable = socket.listen("okra.connected", handler);
     this.disposables.push(disposable);
     return disposable;
   }
   onDidDisconnect(handler) {
-    const disposable = this.socket.listen("okra.disconnected", handler);
+    const disposable = this.realtimeSocket().listen("okra.disconnected", handler);
     this.disposables.push(disposable);
     return disposable;
   }
   onDidBootError(handler) {
-    const disposable = this.socket.listen("okra.boot_error", handler);
+    const disposable = this.realtimeSocket().listen("okra.boot_error", handler);
     this.disposables.push(disposable);
     return disposable;
   }
+  restInitialization() {
+    if (this.restInvoker === null) {
+      throw new UnsupportedRuntimeTransportError("This operation requires the REST transport.");
+    }
+    if (__privateGet(this, _initPromise) === null) {
+      __privateSet(this, _initPromise, this.restInvoker.ready().then((result) => {
+        this.initialized = result;
+        this.emitter.emit("notebook.initialized", result);
+        return result;
+      }));
+      void __privateGet(this, _initPromise).catch(() => {
+      });
+    }
+    return __privateGet(this, _initPromise);
+  }
   update(input) {
     return this.client.notebook.update(this.data.id, input);
   }
@@ -20239,8 +20553,9 @@ var NotebookInstance2 = class {
     return this.listen("notebook.initialized", handler);
   }
   async reconnect() {
+    const socket = this.realtimeSocket();
     const whenConnected = this.whenConnected();
-    this.socket.reconnect();
+    socket.reconnect();
     this.initialized = false;
     await whenConnected;
     __privateMethod(this, _NotebookInstance_instances, init_fn).call(this);
@@ -20251,6 +20566,12 @@ var NotebookInstance2 = class {
     iframe.src = result.data.previewUrl;
     return createBeacon(iframe, options);
   }
+  realtimeSocket() {
+    if (this.socket === null) {
+      throw new UnsupportedRuntimeTransportError("This operation requires the realtime transport.");
+    }
+    return this.socket;
+  }
 };
 _initPromise = new WeakMap();
 _NotebookInstance_instances = new WeakSet();
@@ -20431,6 +20752,7 @@ export {
   ServerApi,
   ServerInstance,
   Transport,
+  UnsupportedRuntimeTransportError,
   createBeacon,
   isBeaconSupported,
   notebookBuiltinServices,