@hyperbrowser/sdk 0.93.0 → 1.0.0

package/README.md

@@ -241,6 +241,70 @@ await sandbox.stop();
 
 `connect()` refreshes runtime auth and throws if the sandbox is no longer running.
 
+Run commands and stream complete output. `exec()` and `processes.start()` open a
+single streamed request and collect stdout/stderr from process start, so output is
+complete even beyond the receiver's replay window. `wait()` timeouts are local and
+keep collecting; `disconnect()` stops collecting without killing the process.
+
+```typescript
+const result = await sandbox.exec("npm test", {
+  cwd: "/workspace",
+  maxOutputBytes: 128 * 1024 * 1024, // default 64 MiB; exceeding it fails, never truncates
+});
+console.log(result.exitCode, result.stdout);
+
+const proc = await sandbox.processes.start("tail -f /var/log/app.log");
+try {
+  await proc.wait({ timeoutSec: 5 });
+} catch (error) {
+  // Local wait timeout: the process is still running and output is still collected.
+}
+for await (const event of proc.stream()) {
+  if (event.type === "stdout") process.stdout.write(event.data);
+  if (event.type === "exit") console.log(event.result.exitCode);
+}
+proc.disconnect();
+```
+
+Build a custom sandbox image from a Dockerfile or a local Docker image. `getOrBuildImage()`
+derives a content-based image name, reuses a ready image with the same identity, joins a
+matching in-progress build, or creates a new one. Dockerfile builds package the effective
+build context (Dockerfile sources, `.dockerignore`) and build remotely; no local Docker is
+required. `dockerImage` imports a local `linux/amd64` image via the Docker CLI.
+
+```typescript
+const resolved = await client.sandboxes.getOrBuildImage({
+  contextPath: "./services/api",
+  dockerfile: "Dockerfile", // relative to contextPath
+  imageInit: { env: { NODE_ENV: "production" }, workingDir: "/app" },
+  builderCpus: 4,
+  builderMemoryMiB: 8192,
+  builderScratchMiB: 20480,
+});
+console.log(resolved.outcome, resolved.imageName, resolved.imageId); // "reused" | "joined" | "created"
+
+const sandbox = await client.sandboxes.create({ imageName: resolved.imageName });
+
+// Import a local Docker image instead (requires docker CLI, linux/amd64 image):
+const imported = await client.sandboxes.getOrBuildImage({ dockerImage: "myorg/app:1.2.3" });
+
+// Detached build: return immediately and poll later.
+const pending = await client.sandboxes.getOrBuildImage({ contextPath: ".", wait: false });
+if (pending.build) {
+  const build = await client.sandboxes.waitForImageBuild(pending.build.id, {
+    pollInterval: 3,
+    timeout: 35 * 60,
+  });
+  console.log(build.status, build.imageId);
+}
+```
+
+Lower-level helpers are also available: `buildImageFromDockerfile()`,
+`buildImageFromDockerImage()`, `findReadyImage()`, `reuseDockerImage()`, plus the raw
+`createImageBuild()` / `completeImageBuild()` / `getImageBuild()` / `listImageBuilds()` /
+`cancelImageBuild()` APIs. Control-plane `GET` requests retry transient failures
+(429/502/503/504 and network errors) up to three times with jittered backoff.
+
 Create a sandbox with pre-exposed ports:
 
 ```typescript
@@ -339,3 +403,129 @@ const terminal = await sandbox.terminal.create({
 
 const connection = await terminal.attach(10);
 ```
+
+### Streaming file transfers and watches
+
+`read({ format: "stream" })` retains its buffered behavior. Use `uploadStream()`
+and `downloadStream()` for large transfers with backpressure and bounded memory:
+
+```typescript
+import { createReadStream, createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+
+await sandbox.files.withRunAs("root").uploadStream(
+  "/tmp/archive.tar", createReadStream("./archive.tar"),
+);
+await pipeline(sandbox.files.downloadStream("/tmp/archive.tar"), createWriteStream("./copy.tar"));
+```
+
+Uploads accept a Node readable or iterable of string/byte chunks and optional
+`{ contentLength, signal }`. Downloads return an async generator of buffers and
+accept `{ signal }`. Breaking download iteration closes the request. After an
+authentication failure, a consumed upload is rejected with `stream_not_replayable`;
+open a fresh source to retry it. `files.stat`, `mkdir`, `move`, and `delete` are
+aliases; `rename(oldPath, newPath, { overwrite: false })` forwards overwrite policy.
+
+```typescript
+const watch = await sandbox.files.watch("/workspace", { recursive: true });
+try {
+  for await (const message of watch.events({ cursor: 0, route: "ws" })) {
+    if (message.type === "done") break;
+    console.log(message.event.seq, message.event.path, message.event.op);
+    break; // Close this connection; the remote watch remains active.
+  }
+  // Persist watch.id and the last sequence to resume an active watch:
+  const resumed = await sandbox.files.getWatch(watch.id, true);
+  await resumed.refresh(true);
+  console.log(resumed.current, resumed.toJSON());
+} finally {
+  await watch.stop();
+}
+```
+
+Both watch routes (`ws` and `stream`) use WebSocket transport. Watch events include
+an explicit `done` envelope. `watchDir()` remains the callback convenience API.
+Stopping a watcher stops the remote watch; breaking event iteration only closes
+that connection. Watch timestamps remain milliseconds; existing file metadata
+continues to expose `modifiedTime` as a `Date`.
+
+### Image identities, snapshots, and runtime sessions
+
+Offline identity helpers are available from the package root and
+`@hyperbrowser/sdk/image-builds`:
+
+```typescript
+import {
+  dockerBuildContextFingerprint, imageBuildName, DockerBuildContextChangedError,
+} from "@hyperbrowser/sdk/image-builds";
+
+const fingerprint = await dockerBuildContextFingerprint("./app");
+const imageName = imageBuildName({ source: "dockerfile", fingerprint });
+try {
+  await client.sandboxes.buildImageFromDockerfile({
+    contextPath: "./app", imageName, expectedContextFingerprint: fingerprint,
+    builderCpus: 4, builderMemoryMiB: 8192, builderScratchMiB: 20480,
+  });
+} catch (error) {
+  if (error instanceof DockerBuildContextChangedError) {
+    // Recompute identity after a local edit, then retry explicitly.
+  } else throw error;
+}
+
+const restored = await client.sandboxes.startFromSnapshot({ snapshotName: "saved" });
+const session = await restored.createRuntimeSession({ forceRefresh: true });
+// Also available without keeping a handle:
+await client.sandboxes.getRuntimeSession(restored.id);
+```
+
+Remote Dockerfile builds need no local Docker. Local builds/imports require Docker;
+platform-specific digest lookup requires Docker API 1.49+ (Docker 28.1+). Imports
+preserve image `PATH`, entrypoint/CMD, working directory, and supported environment
+variables; explicit image initialization overrides take precedence. Names include
+context/digest, platform, and initialization overrides. Mutable base tags and
+network downloads are not resolved by fingerprinting; use `forceBuild` when needed.
+
+Only `linux/amd64` image builds are supported. Sandbox creation preserves
+`runtimeClass: "firecracker" | "gvisor-cpu"`; use response capabilities when choosing
+snapshot, volume, or exposure operations. Snapshot launches cannot override image
+resources. Invalid or conflicting launch sources fail before a network request.
+
+### Timeouts, cancellation, and compatibility
+
+- Client `timeout` is milliseconds. Normal runtime requests have separate header
+  and body budgets. Streaming transfers reset inactivity budgets as data moves.
+- Process `timeoutMs` / `timeoutSec` limit remote execution. `wait({ timeoutMs })`
+  only limits local waiting and leaves collection running.
+- `exec()` / `processes.start()` accept an `AbortSignal`. Aborting stops local
+  collection and closes its connection; the detached remote process continues.
+  Use `signal()` or `kill()` when you intend to stop the command.
+- Process stream inactivity is limited to 60 seconds; receiver keepalives reset it.
+  Incomplete output, exceeded output limits, and unsupported receivers produce
+  structured errors. A failed streaming start is never automatically re-executed.
+- Image polling `pollInterval`, `waitTimeout`, and `uploadTimeout` are seconds.
+  `getOrBuildImage()` defaults uploads to 600 seconds of inactivity and polling to
+  35 minutes. Explicit `null` disables the corresponding timeout. Polling deadlines
+  include control GET retries. A polling `signal` or timeout leaves accepted builds
+  running for other callers. Lower-level build helpers leave upload timeouts unset
+  unless explicitly supplied.
+- `HYPERBROWSER_BASE_URL` supplies the API base URL when `baseUrl` is not provided.
+
+Public handle classes are available from `@hyperbrowser/sdk/sandbox`; request and
+response types remain under `@hyperbrowser/sdk/types`.
+
+### Development checks
+
+The supported Node baseline is 20.20.2. Run `yarn build`, `yarn typecheck`,
+`yarn lint`, and `yarn test` for local verification. Tests share `vitest.config.ts`:
+
+- `tests/unit`: isolated logic and mocked contracts (`yarn test:unit`).
+- `tests/integration`: local HTTP, WebSocket, filesystem, and subprocess tests
+  (`yarn test:integration`).
+- `tests/e2e`: live Hyperbrowser API tests (`yarn test:e2e`).
+
+`yarn test` and `yarn test:watch` select unit and integration tests by default;
+neither requires API credentials or a Docker daemon.
+
+Live tests are opt-in: set `HYPERBROWSER_API_KEY` and `HYPERBROWSER_BASE_URL`, then
+run `yarn test:e2e`. They create remote resources and require a receiver supporting
+streamed process starts.

package/dist/client.d.ts

@@ -18,26 +18,8 @@ import { JevComputerUseService } from "./services/agents/jev-computer-use";
 import { WebService } from "./services/web";
 import { SandboxesService } from "./services/sandboxes";
 import { VolumesService } from "./services/volumes";
-export type HyperbrowserService = "control" | "runtime";
-export interface HyperbrowserErrorOptions {
-    statusCode?: number;
-    code?: string;
-    requestId?: string;
-    retryable?: boolean;
-    service?: HyperbrowserService;
-    details?: unknown;
-    cause?: unknown;
-}
-export declare class HyperbrowserError extends Error {
-    readonly statusCode?: number;
-    readonly code?: string;
-    readonly requestId?: string;
-    readonly retryable: boolean;
-    readonly service?: HyperbrowserService;
-    readonly details?: unknown;
-    readonly cause?: unknown;
-    constructor(message: string, options?: number | HyperbrowserErrorOptions);
-}
+export { HyperbrowserError } from "./error";
+export type { HyperbrowserErrorOptions, HyperbrowserService } from "./error";
 export declare class HyperbrowserClient {
     readonly sessions: SessionsService;
     readonly scrape: ScrapeService;

package/dist/client.js

@@ -20,29 +20,17 @@ const jev_computer_use_1 = require("./services/agents/jev-computer-use");
 const web_1 = require("./services/web");
 const sandboxes_1 = require("./services/sandboxes");
 const volumes_1 = require("./services/volumes");
-class HyperbrowserError extends Error {
-    constructor(message, options = {}) {
-        super(`[Hyperbrowser]: ${message}`);
-        this.name = "HyperbrowserError";
-        const normalized = typeof options === "number" ? { statusCode: options } : options;
-        this.statusCode = normalized.statusCode;
-        this.code = normalized.code;
-        this.requestId = normalized.requestId;
-        this.retryable = normalized.retryable ?? false;
-        this.service = normalized.service;
-        this.details = normalized.details;
-        this.cause = normalized.cause;
-    }
-}
-exports.HyperbrowserError = HyperbrowserError;
+const error_1 = require("./error");
+var error_2 = require("./error");
+Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return error_2.HyperbrowserError; } });
 class HyperbrowserClient {
     constructor(config = {}) {
         const apiKey = config.apiKey || process.env["HYPERBROWSER_API_KEY"];
-        const baseUrl = config.baseUrl || "https://api.hyperbrowser.ai";
+        const baseUrl = config.baseUrl || process.env["HYPERBROWSER_BASE_URL"] || "https://api.hyperbrowser.ai";
         const timeout = config.timeout || 30000;
         const runtimeProxyOverride = config.runtimeProxyOverride?.trim() || undefined;
         if (!apiKey) {
-            throw new HyperbrowserError("API key is required - either pass it in config or set HYPERBROWSER_API_KEY environment variable");
+            throw new error_1.HyperbrowserError("API key is required - either pass it in config or set HYPERBROWSER_API_KEY environment variable");
         }
         this.sessions = new sessions_1.SessionsService(apiKey, baseUrl, timeout);
         this.scrape = new scrape_1.ScrapeService(apiKey, baseUrl, timeout);

package/dist/error.d.ts

@@ -0,0 +1,27 @@
+export type HyperbrowserService = "control" | "runtime";
+/** Keep diagnostics useful without retaining query credentials or URL hosts. */
+export declare const errorRequestPath: (target: string) => string;
+export declare const networkErrorMessage: (error: unknown, fallback: string) => string;
+export interface HyperbrowserErrorOptions {
+    statusCode?: number;
+    code?: string;
+    requestId?: string;
+    retryable?: boolean;
+    service?: HyperbrowserService;
+    details?: unknown;
+    cause?: unknown;
+    method?: string;
+    path?: string;
+}
+export declare class HyperbrowserError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    readonly service?: HyperbrowserService;
+    readonly details?: unknown;
+    readonly cause?: unknown;
+    readonly method?: string;
+    readonly path?: string;
+    constructor(message: string, options?: number | HyperbrowserErrorOptions);
+}

package/dist/error.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperbrowserError = exports.networkErrorMessage = exports.errorRequestPath = void 0;
+/** Keep diagnostics useful without retaining query credentials or URL hosts. */
+const errorRequestPath = (target) => {
+    try {
+        return new URL(target, "http://sdk.invalid").pathname;
+    }
+    catch {
+        return target.split("?", 1)[0];
+    }
+};
+exports.errorRequestPath = errorRequestPath;
+const networkErrorMessage = (error, fallback) => error instanceof Error ? error.message || `${fallback} (${error.name || "Error"})` : fallback;
+exports.networkErrorMessage = networkErrorMessage;
+class HyperbrowserError extends Error {
+    constructor(message, options = {}) {
+        super(`[Hyperbrowser]: ${message}`);
+        this.name = "HyperbrowserError";
+        const normalized = typeof options === "number" ? { statusCode: options } : options;
+        this.statusCode = normalized.statusCode;
+        this.code = normalized.code;
+        this.requestId = normalized.requestId;
+        this.retryable = normalized.retryable ?? false;
+        this.service = normalized.service;
+        this.details = normalized.details;
+        this.cause = normalized.cause;
+        this.method = normalized.method;
+        this.path = normalized.path;
+    }
+}
+exports.HyperbrowserError = HyperbrowserError;

package/dist/image-builds.d.ts

@@ -0,0 +1,6 @@
+/** Public, offline image identity helpers. */
+export { dockerBuildContextFingerprint, DockerBuildContextChangedError, } from "./sandbox/image-build/context";
+export type { DockerBuildContextOptions } from "./sandbox/image-build/context";
+export { imageBuildName } from "./sandbox/image-build/resolution";
+export type { ImageBuildNameOptions, ImageBuildSource } from "./sandbox/image-build/resolution";
+export { dockerImageDigest, DockerCommandError } from "./sandbox/image-build/docker-image";

package/dist/image-builds.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerCommandError = exports.dockerImageDigest = exports.imageBuildName = exports.DockerBuildContextChangedError = exports.dockerBuildContextFingerprint = void 0;
+/** Public, offline image identity helpers. */
+var context_1 = require("./sandbox/image-build/context");
+Object.defineProperty(exports, "dockerBuildContextFingerprint", { enumerable: true, get: function () { return context_1.dockerBuildContextFingerprint; } });
+Object.defineProperty(exports, "DockerBuildContextChangedError", { enumerable: true, get: function () { return context_1.DockerBuildContextChangedError; } });
+var resolution_1 = require("./sandbox/image-build/resolution");
+Object.defineProperty(exports, "imageBuildName", { enumerable: true, get: function () { return resolution_1.imageBuildName; } });
+var docker_image_1 = require("./sandbox/image-build/docker-image");
+Object.defineProperty(exports, "dockerImageDigest", { enumerable: true, get: function () { return docker_image_1.dockerImageDigest; } });
+Object.defineProperty(exports, "DockerCommandError", { enumerable: true, get: function () { return docker_image_1.DockerCommandError; } });

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { dockerBuildContextFingerprint, DockerBuildContextChangedError, imageBuildName, dockerImageDigest, DockerCommandError } from "./image-builds";
+export { dockerBuildContextFingerprint, DockerBuildContextChangedError, imageBuildName, dockerImageDigest, DockerCommandError, };
+export type { DockerBuildContextOptions, ImageBuildNameOptions, ImageBuildSource, } from "./image-builds";
 import { HyperbrowserClient, HyperbrowserError } from "./client";
 export declare const Hyperbrowser: typeof HyperbrowserClient;
 export type Hyperbrowser = HyperbrowserClient;

package/dist/index.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HyperbrowserError = exports.HyperbrowserClient = exports.Hyperbrowser = void 0;
+exports.HyperbrowserError = exports.HyperbrowserClient = exports.Hyperbrowser = exports.DockerCommandError = exports.dockerImageDigest = exports.imageBuildName = exports.DockerBuildContextChangedError = exports.dockerBuildContextFingerprint = void 0;
+const image_builds_1 = require("./image-builds");
+Object.defineProperty(exports, "dockerBuildContextFingerprint", { enumerable: true, get: function () { return image_builds_1.dockerBuildContextFingerprint; } });
+Object.defineProperty(exports, "DockerBuildContextChangedError", { enumerable: true, get: function () { return image_builds_1.DockerBuildContextChangedError; } });
+Object.defineProperty(exports, "imageBuildName", { enumerable: true, get: function () { return image_builds_1.imageBuildName; } });
+Object.defineProperty(exports, "dockerImageDigest", { enumerable: true, get: function () { return image_builds_1.dockerImageDigest; } });
+Object.defineProperty(exports, "DockerCommandError", { enumerable: true, get: function () { return image_builds_1.DockerCommandError; } });
 const client_1 = require("./client");
 Object.defineProperty(exports, "HyperbrowserClient", { enumerable: true, get: function () { return client_1.HyperbrowserClient; } });
 Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return client_1.HyperbrowserError; } });
@@ -13,5 +19,10 @@ if (typeof module !== "undefined" && module.exports) {
     module.exports.Hyperbrowser = client_1.HyperbrowserClient;
     module.exports.HyperbrowserClient = client_1.HyperbrowserClient;
     module.exports.HyperbrowserError = client_1.HyperbrowserError;
+    module.exports.dockerBuildContextFingerprint = image_builds_1.dockerBuildContextFingerprint;
+    module.exports.DockerBuildContextChangedError = image_builds_1.DockerBuildContextChangedError;
+    module.exports.imageBuildName = image_builds_1.imageBuildName;
+    module.exports.dockerImageDigest = image_builds_1.dockerImageDigest;
+    module.exports.DockerCommandError = image_builds_1.DockerCommandError;
     module.exports.default = client_1.HyperbrowserClient;
 }

package/dist/retry.d.ts

@@ -0,0 +1,14 @@
+import { HyperbrowserError } from "./error";
+export declare const RETRYABLE_STATUS_CODES: Set<number>;
+export declare const GET_RETRY_MAX_ATTEMPTS = 3;
+export declare const GET_RETRY_INITIAL_DELAY_MS = 250;
+export declare const GET_RETRY_MAX_DELAY_MS = 1000;
+export declare const isRetryableNetworkError: (error: unknown) => boolean;
+export declare const shouldRetryGet: (method: string, error: HyperbrowserError, failedAttempt: number) => boolean;
+/** Exponential backoff with jitter, capped at one second. */
+export declare const getRetryDelayMs: (failedAttempt: number) => number;
+export declare const retryDelay: (ms: number, signal?: {
+    readonly aborted: boolean;
+    addEventListener: AbortSignal["addEventListener"];
+    removeEventListener: AbortSignal["removeEventListener"];
+}) => Promise<void>;

package/dist/retry.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryDelay = exports.getRetryDelayMs = exports.shouldRetryGet = exports.isRetryableNetworkError = exports.GET_RETRY_MAX_DELAY_MS = exports.GET_RETRY_INITIAL_DELAY_MS = exports.GET_RETRY_MAX_ATTEMPTS = exports.RETRYABLE_STATUS_CODES = void 0;
+const error_1 = require("./error");
+exports.RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+exports.GET_RETRY_MAX_ATTEMPTS = 3;
+exports.GET_RETRY_INITIAL_DELAY_MS = 250;
+exports.GET_RETRY_MAX_DELAY_MS = 1000;
+const RETRYABLE_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+]);
+const isRetryableNetworkError = (error) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const networkError = error;
+    return (networkError.name === "AbortError" ||
+        networkError.type === "request-timeout" ||
+        (networkError.code ? RETRYABLE_NETWORK_CODES.has(networkError.code) : false));
+};
+exports.isRetryableNetworkError = isRetryableNetworkError;
+const shouldRetryGet = (method, error, failedAttempt) => method.toUpperCase() === "GET" && error.retryable && failedAttempt < exports.GET_RETRY_MAX_ATTEMPTS;
+exports.shouldRetryGet = shouldRetryGet;
+/** Exponential backoff with jitter, capped at one second. */
+const getRetryDelayMs = (failedAttempt) => {
+    const maximumDelay = Math.min(exports.GET_RETRY_INITIAL_DELAY_MS * 2 ** (failedAttempt - 1), exports.GET_RETRY_MAX_DELAY_MS);
+    return maximumDelay / 2 + Math.random() * (maximumDelay / 2);
+};
+exports.getRetryDelayMs = getRetryDelayMs;
+const retryDelay = (ms, signal) => new Promise((resolve, reject) => {
+    const aborted = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", aborted);
+        reject(new error_1.HyperbrowserError("Request canceled", { code: "request_aborted", service: "control" }));
+    };
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", aborted);
+        resolve();
+    }, ms);
+    if (signal?.aborted)
+        aborted();
+    else
+        signal?.addEventListener("abort", aborted, { once: true });
+});
+exports.retryDelay = retryDelay;

package/dist/sandbox/base.d.ts

@@ -11,14 +11,41 @@ export interface RuntimeSSEEvent {
     id?: string;
 }
 type RuntimeParams = Record<string, string | number | boolean | undefined>;
+export declare const PROCESS_STREAM_IDLE_TIMEOUT_MS = 60000;
+export interface RuntimeSSEInit {
+    method?: "GET" | "POST";
+    body?: string;
+    headers?: Record<string, string>;
+    /** Milliseconds without any bytes before the stream fails. Defaults to 60s. */
+    idleTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface RuntimeSSEStream {
+    events: AsyncGenerator<RuntimeSSEEvent>;
+    /** Close the underlying connection; the remote process keeps running. */
+    close(): void;
+}
 export declare class RuntimeTransport {
     private readonly resolveConnection;
     private readonly timeout;
     private readonly runtimeProxyOverride?;
+    private readonly responseCleanup;
+    private closeResponse;
+    private failure;
     constructor(resolveConnection: (forceRefresh?: boolean) => Promise<RuntimeConnection>, timeout?: number, runtimeProxyOverride?: string | undefined);
     requestJSON<T>(path: string, init?: RequestInit, params?: RuntimeParams): Promise<T>;
     requestBuffer(path: string, init?: RequestInit, params?: RuntimeParams): Promise<Buffer>;
+    /** Pull-based binary transfer. Breaking iteration closes the HTTP connection. */
+    streamBytes(path: string, init?: RequestInit, params?: RuntimeParams): AsyncGenerator<Buffer>;
+    private readChunk;
     streamSSE(path: string, params?: RuntimeParams): AsyncGenerator<RuntimeSSEEvent>;
+    /**
+     * Open a server-sent event stream. POST streams carry a JSON body and
+     * require an event-stream response, since the request may have side effects
+     * that must not be retried blindly.
+     */
+    openSSE(path: string, params?: RuntimeParams, init?: RuntimeSSEInit): Promise<RuntimeSSEStream>;
+    private parseSSE;
     private fetchWithAuth;
     private fetchForConnection;
     private assertResponse;