@phpsandbox/sdk 0.0.32 → 0.0.34

package/README.md

@@ -79,12 +79,20 @@ await fetched.ready();
 
 const forked = await created.fork();
 await forked.delete();
+
+const persistent = await client.notebook.create('laravel', {
+  title: 'Persistent Laravel',
+  persistent: true,
+});
+
+console.log(persistent.data.policy);
 ```
 
 Notes:
 
 - `create()` and `fork()` initialize automatically.
 - `open()` and `get()` return a notebook instance; call `await notebook.ready()` before using tools.
+- API notebook creates are ephemeral by default. `persistent: true` requires an entitled account.
 
 ## Services At A Glance
 
@@ -103,6 +111,12 @@ Each `NotebookInstance` exposes service clients:
 - `notebook.log` (`Log`)
 - `notebook.services` (`Services`)
 
+Notes:
+
+- `terminal.spawn()` and `shell.exec()` are part of the current okra websocket action set. `terminal.start` currently is not.
+- `notebook.repl.eval()` is part of the current okra websocket action set. `repl.start` is currently not.
+- `notebook.laravel` is exposed by the SDK, but the current okra websocket action set does not expose Laravel maintenance actions.
+
 ## Common Operations
 
 ### Files

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

@@ -639,19 +639,30 @@ var Terminal = class {
       },
       close: dispose
     });
+    let controller = null;
     const output = new ReadableStream({
-      start: (controller) => {
+      start: (_controller) => {
+        controller = _controller;
         disposables.add(
           this.listen(`terminal.output.${id}`, (data) => {
-            controller.enqueue(data.output);
+            controller?.enqueue(data.output);
           })
         );
       },
-      cancel: dispose
+      cancel: () => {
+        controller = null;
+        dispose();
+      }
     });
     const exit = new Promise((resolve) => {
       disposables.add(
         this.listen(`terminal.close.${id}`, (data) => {
+          if (controller) {
+            try {
+              controller.close();
+            } catch {
+            }
+          }
           dispose();
           resolve(data.exitCode);
         })
@@ -3091,6 +3102,89 @@ var ReconnectingWebSocket = (
 );
 var reconnecting_websocket_mjs_default = ReconnectingWebSocket;
 
+// src/utils/websocket.ts
+var getReadyStateLabel = (state) => {
+  if (typeof state !== "number") {
+    return void 0;
+  }
+  return {
+    0: "CONNECTING",
+    1: "OPEN",
+    2: "CLOSING",
+    3: "CLOSED"
+  }[state] ?? `STATE_${state}`;
+};
+var sanitizeWebSocketUrl = (value) => {
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return value;
+  }
+};
+var extractNestedErrorMessage = (value) => {
+  if (value instanceof Error) {
+    return value.message ? `${value.name}: ${value.message}` : value.name;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const record = value;
+  const message = typeof record.message === "string" && record.message ? record.message : typeof record.reason === "string" && record.reason ? record.reason : void 0;
+  if (!message) {
+    return void 0;
+  }
+  const name = typeof record.name === "string" && record.name ? record.name : void 0;
+  return name ? `${name}: ${message}` : message;
+};
+var describeWebSocketEvent = (event) => {
+  if (event instanceof Error) {
+    return event.message ? `${event.name}: ${event.message}` : event.name;
+  }
+  if (typeof event === "string") {
+    return event;
+  }
+  if (!event || typeof event !== "object") {
+    return String(event);
+  }
+  const record = event;
+  const parts = [];
+  const topLevelMessage = extractNestedErrorMessage(record);
+  if (topLevelMessage) {
+    parts.push(topLevelMessage);
+  }
+  const nestedErrorMessage = extractNestedErrorMessage(record.error);
+  if (nestedErrorMessage && nestedErrorMessage !== topLevelMessage) {
+    parts.push(`error=${nestedErrorMessage}`);
+  }
+  if (typeof record.type === "string" && record.type) {
+    parts.push(`type=${record.type}`);
+  }
+  if (typeof record.code === "number") {
+    parts.push(`code=${record.code}`);
+  }
+  if (typeof record.reason === "string" && record.reason && record.reason !== topLevelMessage) {
+    parts.push(`reason=${record.reason}`);
+  }
+  if (typeof record.wasClean === "boolean") {
+    parts.push(`wasClean=${record.wasClean}`);
+  }
+  const target = record.target ?? record.currentTarget;
+  if (target && typeof target === "object") {
+    if (typeof target.url === "string" && target.url) {
+      parts.push(`url=${sanitizeWebSocketUrl(target.url)}`);
+    }
+    const readyState = getReadyStateLabel(target.readyState);
+    if (readyState) {
+      parts.push(`readyState=${readyState}`);
+    }
+  }
+  return parts.length > 0 ? parts.join(" | ") : "Unknown websocket event";
+};
+
 // node_modules/isomorphic-ws/browser.js
 var ws = null;
 if (typeof WebSocket !== "undefined") {
@@ -3128,6 +3222,13 @@ var NamedDisposable = class {
 };
 
 // src/socket/index.ts
+var ConnectionFailedError = class extends Error {
+  constructor(message, originalError) {
+    super(message);
+    this.originalError = originalError;
+    this.name = "ConnectionFailedError";
+  }
+};
 var InvalidMessageError = class extends Error {
   constructor(message, data) {
     super(message);
@@ -3182,7 +3283,7 @@ var Transport = class {
     this.connectionStats.connectionStartTime = Date.now();
     const startClosed = options.startClosed !== false;
     this.rws = new reconnecting_websocket_mjs_default(this.url.toString(), [], {
-      WebSocket: globalThis.WebSocket ?? browser_default,
+      WebSocket: options.webSocket ?? globalThis.WebSocket ?? browser_default,
       connectionTimeout: options.connectionTimeout,
       maxReconnectionDelay: 2e3,
       minReconnectionDelay: 200,
@@ -3237,7 +3338,19 @@ var Transport = class {
   async registerWatchers() {
     const onMessage = (ev) => {
       if (!(ev.data instanceof Blob)) {
-        throw new Error("Unexpected message type: " + typeof ev.data);
+        const error = new Error("Unexpected message type: " + typeof ev.data);
+        this.connectionStats.totalErrors++;
+        this.log("error", "Unexpected WebSocket message type", {
+          error: error.message,
+          messageType: typeof ev.data
+        });
+        this.eventEmitter.emit("transport.error", {
+          type: "message_type_error",
+          error,
+          rawMessage: ev.data,
+          timestamp: Date.now()
+        });
+        return;
       }
       ev.data.arrayBuffer().then((buffer) => {
         if (buffer.byteLength === 0) {
@@ -3245,7 +3358,19 @@ var Transport = class {
           return;
         }
         try {
-          this.handleRawMessage(decode(buffer));
+          void this.handleRawMessage(decode(buffer)).catch((error) => {
+            this.connectionStats.totalErrors++;
+            this.log("error", "Failed to process WebSocket frame", {
+              error: error instanceof Error ? error.message : String(error),
+              byteLength: buffer.byteLength
+            });
+            this.eventEmitter.emit("transport.error", {
+              type: "message_handle_error",
+              error,
+              rawMessage: buffer,
+              timestamp: Date.now()
+            });
+          });
         } catch (error) {
           this.connectionStats.totalErrors++;
           this.log("error", "Failed to decode WebSocket frame", {
@@ -3269,6 +3394,10 @@ var Transport = class {
     });
   }
   async handleRawMessage(ev) {
+    if (this.closed) {
+      this.log("debug", "Ignoring message received after transport was closed");
+      return;
+    }
     if (typeof ev !== "object" || ev === null) {
       this.log("debug", "Received invalid message format", { ev });
       return;
@@ -3466,7 +3595,8 @@ var Transport = class {
           reject(new RateLimitError(_ev.reason || "Rate limit exceeded", _ev));
           return;
         }
-        reject(this.terminalError || new Error(`Connection lost to the notebook during request: ${_ev.reason || "Unknown reason"}`));
+        const detail = describeWebSocketEvent(_ev);
+        reject(this.terminalError || new ConnectionFailedError(`Connection lost to the notebook during request: ${detail}`, _ev));
       };
       this.rws.addEventListener("close", closeHandler);
       this.rws.addEventListener("error", closeHandler);
@@ -3654,8 +3784,10 @@ var Transport = class {
     });
     this.rws.addEventListener("error", (event) => {
       this.connectionStats.totalErrors++;
+      const detail = describeWebSocketEvent(event);
       this.log("error", "Connection error", {
-        error: event,
+        error: detail,
+        rawError: event,
         totalErrors: this.connectionStats.totalErrors
       });
     });
@@ -3928,7 +4060,8 @@ connect_fn = function() {
       this.rws.removeEventListener("error", errorHandler);
       clearTimeout(timeoutId);
       this.connectPromise = null;
-      reject(new Error(`WebSocket connection failed: ${error}`));
+      const detail = describeWebSocketEvent(error);
+      reject(new ConnectionFailedError(`WebSocket connection failed: ${detail}`, error));
     };
     timeoutId = setTimeout(() => {
       this.rws.removeEventListener("open", openHandler);
@@ -4930,7 +5063,8 @@ var NotebookInstance = class {
     this.emitter = EventManager.createInstance();
     this.socket = new Transport(data.okraUrl, this.emitter, {
       debug: client.options.debug,
-      startClosed: client.options.startClosed
+      startClosed: client.options.startClosed,
+      webSocket: client.options.webSocket
     });
     this.watchConnection();
     __privateSet(this, _initPromise, __privateMethod(this, _NotebookInstance_instances, init_fn).call(this));
@@ -5098,6 +5232,8 @@ init_fn = function() {
       reject(error);
     });
   }));
+  void __privateGet(this, _initPromise).catch(() => {
+  });
   return __privateGet(this, _initPromise);
 };
 var NotebookSecrets = class {