@phpsandbox/sdk 0.0.64 → 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');
@@ -246,6 +251,7 @@ if (preview.status === 'ready') {
 ```
 
 Use `notebookId` when diffing or merging from another PHPSandbox notebook. Use `url` for external Git remotes. `notebookId`, `url`, and `target` are mutually exclusive.
+Set `patch: false` when only the structured file list, stat, and divergence counts are needed. Patch generation defaults to enabled for backward compatibility.
 
 Fork diff requires the base and fork to share Git history. If they do not, `diff()` returns `status: 'unrelated'`.
 

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,