@miosa/sdk 0.3.0 → 1.0.0

package/dist/index.d.ts

@@ -4150,6 +4150,32 @@ declare class Sandbox {
     deploy(params?: SandboxDeployParams): Promise<Record<string, unknown>>;
     /** Check readiness of the sandbox (GET /sandboxes/:id/readiness). */
     readiness(): Promise<Record<string, unknown>>;
+    /**
+     * Block until the sandbox reports ready, or *timeout* seconds elapse.
+     *
+     * When `stream` is `true` (the default) this opens an SSE connection
+     * to `GET /sandboxes/:id/readiness/stream` and waits for an
+     * `event: ready` frame. The server emits `ready` immediately if the
+     * sandbox is already ready, otherwise as soon as the readiness PubSub
+     * message fires.
+     *
+     * Returns `true` once the sandbox is ready, `false` on `event: timeout`
+     * or when the local timeout elapses before ready.
+     *
+     * If the SSE endpoint returns 404 (server pre-dates the streaming
+     * endpoint) this transparently falls back to polling
+     * {@link readiness} every 10 ms until ready or timeout.
+     */
+    waitUntilReady(options?: {
+        timeout?: number;
+        stream?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Returns `true` / `false` for terminal SSE events, or `null` if the
+     * stream endpoint is unavailable (404 or transport error) so callers
+     * can fall back to polling.
+     */
+    private tryReadinessStream;
     destroy(): Promise<void>;
     delete(): Promise<void>;
     private assertRunning;

package/dist/index.js

@@ -5224,6 +5224,96 @@ var Sandbox = class _Sandbox {
       )
     );
   }
+  /**
+   * Block until the sandbox reports ready, or *timeout* seconds elapse.
+   *
+   * When `stream` is `true` (the default) this opens an SSE connection
+   * to `GET /sandboxes/:id/readiness/stream` and waits for an
+   * `event: ready` frame. The server emits `ready` immediately if the
+   * sandbox is already ready, otherwise as soon as the readiness PubSub
+   * message fires.
+   *
+   * Returns `true` once the sandbox is ready, `false` on `event: timeout`
+   * or when the local timeout elapses before ready.
+   *
+   * If the SSE endpoint returns 404 (server pre-dates the streaming
+   * endpoint) this transparently falls back to polling
+   * {@link readiness} every 10 ms until ready or timeout.
+   */
+  async waitUntilReady(options = {}) {
+    const timeout = options.timeout ?? 30;
+    const stream = options.stream ?? true;
+    if (stream) {
+      const sseResult = await this.tryReadinessStream(timeout);
+      if (sseResult !== null) return sseResult;
+    }
+    const deadlineMs = Date.now() + timeout * 1e3;
+    while (Date.now() < deadlineMs) {
+      try {
+        const data = await this.readiness();
+        if (data.ready === true || data.status === "ready") return true;
+      } catch {
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    return false;
+  }
+  /**
+   * Returns `true` / `false` for terminal SSE events, or `null` if the
+   * stream endpoint is unavailable (404 or transport error) so callers
+   * can fall back to polling.
+   */
+  async tryReadinessStream(timeoutSec) {
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), (timeoutSec + 5) * 1e3);
+    try {
+      const headers = {
+        Authorization: `Bearer ${this.http.apiKey}`,
+        Accept: "text/event-stream",
+        "User-Agent": "@miosa/sdk/1.0.0"
+      };
+      const response = await fetch(
+        `${this.http.baseUrl}/sandboxes/${this.id}/readiness/stream`,
+        { method: "GET", headers, signal: abort.signal }
+      );
+      if (response.status === 404) return null;
+      if (!response.ok || !response.body) return null;
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let newlineIdx;
+          while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newlineIdx).replace(/\r$/, "");
+            buffer = buffer.slice(newlineIdx + 1);
+            if (line.startsWith("event:")) {
+              const evt = line.slice(6).trim();
+              if (evt === "ready") return true;
+              if (evt === "timeout") return false;
+            }
+          }
+        }
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {
+        }
+      }
+      return null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+      try {
+        abort.abort();
+      } catch {
+      }
+    }
+  }
   async destroy() {
     if (this.data.state === "destroyed") return;
     await this.http.delete(`/sandboxes/${this.id}`);